Cal.diy Connector

The Cal.diy connector projects the pinned self-hosted scheduling API into 81 typed AIP capabilities. It is built into aipd and is the reference product connector for governed mutations, tenant credential routing, signed webhook ingress, idempotency fencing, and recovery.

What It Supports

Capability family	Count	Examples
Profile	2	Read and update the authenticated profile
Event types	15	CRUD, private links, and webhooks
Slots	5	Availability and reservation lifecycle
Bookings	22	Create, reschedule, cancel, attendees, recordings, and transcripts
Calendars	21	Connections, busy time, event CRUD, free/busy, and selection
Conferencing	5	List, default, connect, and disconnect
Schedules	6	List, read, create, update, and delete
User webhooks	5	Signed webhook CRUD

Interactive OAuth callbacks, raw credential capture, deprecated routes, and unbounded outbound URL operations are deliberately excluded.

Configure aipd

Provide exactly one Cal.diy authentication mode through secret files:

cargo run -p aipd -- \
  --bind 0.0.0.0:18080 \
  --service-id agent:aipd:calendar \
  --native-bearer-token-file /run/secrets/aip-native-token \
  --native-principal service:calendar-edge \
  --native-principal-scope action:read \
  --native-principal-scope action:write \
  --trusted-identity-file /run/aip/trusted-identities.json \
  --approval-authority-file /run/aip/approval-authorities.json \
  --postgres-url "$AIP_POSTGRES_URL" \
  --cal-diy-base-url https://calendar.example.com/api \
  --cal-diy-account-id primary \
  --cal-diy-bearer-token-file /run/secrets/cal-diy-token

OAuth client authentication uses --cal-diy-oauth-client-id and --cal-diy-oauth-client-secret-file instead of the bearer-token file.

For multiple tenants, bind each trusted tenant to an external account and opaque credential handle. The trusted identity directory is authoritative; action input cannot select another tenant’s credential.

The command is a composition example, not a complete public-edge deployment. Terminate TLS, restrict health and metrics routes, and grant only the scopes required by the chosen capabilities.

See aipd Configuration for all connector options and Environment Variables for orchestrator equivalents.

Mutation Safety

Every mutation requires an external-account-scoped idempotency key and AIP approval. High-risk booking create, reschedule, and cancel operations require a validated plan before commit.

Cal.diy does not provide universal provider idempotency. The connector therefore claims a durable dispatch fence before sending a mutation and never blindly retries an uncertain provider outcome. When provider response and settlement evidence are both unavailable, the operation remains fenced for operator reconciliation.

Use PostgreSQL for multi-process deployment. The file-backed runtime is a single-host durability option, not a shared cluster coordinator.

Signed Webhooks

Configure one secret selector per owned webhook subscription:

--cal-diy-webhook-secret-file bookings=/run/secrets/cal-diy-bookings-hmac
--cal-diy-webhook-subscriber-prefix https://aip.example.com/connectors/cal-diy/webhooks/

The provider sends to:

POST /connectors/cal-diy/webhooks/bookings

The connector verifies the exact raw body, required version, HMAC signature, timestamp window, replay identity, and payload bound before appending a native event. Provider retries resolve to the same deterministic event id.

Qualification Boundary

The connector has complete frozen-SDK conformance and a retained exact-upstream isolated-live report for its named source and image artifacts. That historical report does not automatically qualify a rebuild or a new Cal.diy revision. Run the campaign again for the exact production artifact.

For the full provider baseline and safety boundaries, read Pinned Upstream Baselines. Evidence is described in Cal.diy Isolated-Live Evidence.