{
  "schemaVersion": "1.0",
  "title": "Cal.diy connector",
  "description": "Use the Cal.diy connector when an AIP application must read or change scheduling state through a typed, tenant-bound capability surface. The connector runs in its own aip-host-cal-diy process; product-neutral getaip-server routes admitted a",
  "canonical": "https://getaip.org/docs/connectors/cal-diy",
  "route": "/docs/connectors/cal-diy",
  "source": "docs/connectors/cal-diy/README.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/connectors/cal-diy.md",
    "txt": "/docs/download/connectors/cal-diy.txt",
    "json": "/docs/download/connectors/cal-diy.json",
    "pdf": "/docs/download/connectors/cal-diy.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Cal.diy connector\ndescription: Adopt the standalone Cal.diy connector for governed scheduling operations and signed events\nkind: connector-overview\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\nconnector: cal-diy\n---\n\n# Cal.diy connector\n\nUse the Cal.diy connector when an AIP application must read or change\nscheduling state through a typed, tenant-bound capability surface. The\nconnector runs in its own `aip-host-cal-diy` process; product-neutral `getaip-server`\nroutes admitted actions to that host and does not contain Cal.diy product code\nor credentials.\n\nThe reviewed connector exposes 81 operations from one pinned Cal.diy source\nrevision. It adds AIP approval, idempotency, routing, evidence, and webhook\nboundaries around those provider operations. It does not expose every Cal.diy\nadministrator, credential-provisioning, or compatibility route.\n\n## At a glance\n\n| Property | Reviewed value |\n|---|---|\n| Connector id | `cal-diy` |\n| Standalone process | `aip-host-cal-diy` |\n| AIP workspace version | `2.0.0` |\n| Reviewed AIP source | `d7cce13d1d555644d04a4d73c66c95b113737635` |\n| Pinned Cal.diy source | `f00434927386c9ecdcbd7e6c5f82d22044a245bc` |\n| Connector profile | `aip.connector.cal_diy.v1` |\n| Webhook profile | `aip.http.webhook.v1` |\n| Capability prefix | `cap:cal_diy:` |\n| Business operations | 81 |\n| Provider authentication | Bearer token or OAuth client credentials |\n| Execution | Synchronous; no connector streaming, async execution, or cancellation |\n| Mutation policy | Approval and external-account-scoped idempotency required |\n\nThe source revision identifies what was reviewed. It is not a claim that a\ndifferent branch, rebuilt image, Cal.diy deployment, or provider revision has\nthe same behavior.\n\n## Choose this connector when\n\nThe connector fits an integration that needs to:\n\n- discover availability and reserve a slot;\n- create and manage bookings with explicit approval;\n- read or change event types, schedules, calendars, conferencing, and\n  webhooks;\n- keep provider credentials in the connector deployment rather than in AIP\n  messages;\n- route each authenticated tenant to an owner-admitted, account-specific host\n  without placing provider credentials in AIP messages;\n- turn authenticated Cal.diy webhooks into durable AIP events;\n- prevent a retry from silently repeating an uncertain provider mutation.\n\nUse a provider-owned administrative integration instead when the task must\ncreate API keys, complete browser OAuth, administer OAuth clients, verify email\nor phone ownership, or invoke an upstream route outside the frozen catalogue.\n\nDo not adopt the reviewed connector unchanged for a different Cal.diy revision.\nCompare the provider routes and schemas first, then repeat connector\nconformance and deployment qualification for the exact artifact.\n\n## Deployment boundary\n\nThe reference topology separates protocol routing from product execution:\n\n1. An authenticated caller submits a native AIP action to `getaip-server`.\n2. `getaip-server` applies protocol validation, identity, authorization, approval, and\n   runtime policy.\n3. The connector registry selects an admitted `cal-diy` instance and healthy\n   replica for the tenant.\n4. The remote connector path sends the action to `aip-host-cal-diy`.\n5. The host uses its deployment-owned Cal.diy account and secret-file\n   configuration.\n6. The connector maps the capability to one fixed Cal.diy method, path, and\n   API-version header.\n7. The result returns through the host and central runtime with provider\n   credential material excluded.\n\nThe registry does not execute images or load product crates dynamically. An\noperator builds and deploys the Cal.diy host separately, then admits its exact\nidentity, contract, artifact, and evidence. Adding another admitted instance\ndoes not recompile `getaip-server`.\n\n## Supported capability families\n\nThe family counts below come from the 81-entry `ALL_OPERATIONS` catalogue at\nthe reviewed source revision.\n\n| Family | Count | Supported outcome |\n|---|---:|---|\n| Profile | 2 | Read or update the authenticated profile |\n| Event types and private links | 15 | Manage event types, private links, and event-type webhooks |\n| Slots and reservations | 5 | Query availability and manage a short-lived reservation |\n| Bookings | 22 | Read, create, reschedule, cancel, confirm, reassign, and inspect artifacts |\n| Calendars and free/busy | 21 | Manage connections, events, busy time, destination, and conflict selection |\n| Conferencing | 5 | Discover, select, connect, or disconnect conferencing applications |\n| Schedules | 6 | List, read, create, update, or delete schedules |\n| User webhooks | 5 | List, read, create, update, or delete user-level webhooks |\n| **Total** | **81** | Complete admitted business-operation catalogue |\n\nEach capability advertises both `aip.native.http.v1` and the connector profile.\nIts binding contains the exact provider method, path template, API version, and\noperation suffix. Input and output remain typed JSON; a provider response is\nbounded before it is parsed or returned.\n\n## Credential and tenant boundary\n\nThe standalone host accepts exactly one provider authentication mode:\n\n- an owner-controlled Bearer-token file; or\n- an OAuth client id with an owner-controlled client-secret file.\n\nThe connector does not perform an OAuth browser flow and does not refresh an\nOAuth credential through the agent surface.\n\nThe reviewed standalone host also requires one stable Cal.diy account id. It\ndoes not expose the connector library's optional tenant-to-account\ncredential-handle composition. In the standalone fleet, bind each tenant to an\nadmitted account-specific instance through owner-controlled registry topology;\naction input cannot choose another account or secret.\n\nThe connector library does implement a fail-closed credential-routing mode for\nspecialized compositions and frozen conformance tests. That mode requires a\ntrusted runtime tenant context, owner-defined bindings, and a credential\nprovider. Do not assume it is active in `aip-host-cal-diy`, and do not adopt the\nmigration-only bundled daemon as the target architecture merely to obtain its\nlegacy command-line wiring.\n\n## Mutation safety\n\nAll non-GET operations require AIP approval and an idempotency key scoped to the\nexternal account. Reading booking recordings or transcripts also requires\napproval because the result may contain restricted meeting data.\n\nBooking create, reschedule, and cancel require a validated plan before commit.\nOther mutations still support the connector transaction modes, but their dry\nrun checks policy and input without claiming a complete downstream simulation.\n\nCal.diy does not provide universal provider idempotency for this catalogue. The\nconnector therefore records a durable compare-and-set dispatch claim before a\nmutation can cross the provider boundary. Reusing the same key and input can\nreturn the stored result; reusing the key with different input is a collision.\n\nIf a crash or timeout leaves a dispatched mutation without trusted terminal\nevidence, the ledger marks the outcome uncertain. The connector does not\nblindly retry that mutation. Reconciliation must use the dispatch ledger, a\ntrusted transaction checkpoint, or operator evidence before another provider\neffect is allowed.\n\nReads are retryable. Mutations are not advertised as retry-safe. Some create\noperations name a best-effort compensating delete or cancel capability, but\ncompensation is a separately approved action, not an atomic rollback.\n\n## Signed event ingress\n\nWhen webhook secrets are configured, Cal.diy sends a delivery to the\nstandalone host route:\n\n```text\nPOST /webhooks/cal-diy/{subscription_id}\n```\n\nThe path selector chooses a deployment-owned secret reference. The host\nrequires `X-Cal-Signature-256` and `X-Cal-Webhook-Version`, preserves the exact\nraw body, enforces a 1 MiB body limit, and passes a trusted receipt time to the\nconnector.\n\nThe connector verifies the raw-body HMAC, the supported webhook version\n`2021-10-20`, the event-time window, and durable replay identity. Accepted\nevents are appended locally and queued for central delivery. A replay resolves\nto the same deterministic event identity; a replay-store or event-store\nfailure fails closed instead of acknowledging unretained state.\n\nCreating or updating a provider webhook also requires its subscriber URL to\nmatch an operator-configured HTTPS prefix. No destination is accepted by\ndefault.\n\n## Deliberate exclusions\n\nThe source names 38 operator-only upstream routes that are not capabilities.\nThey cover credential creation or refresh, browser OAuth and callbacks, OAuth\nclient administration, calendar or conferencing connection setup, Stripe\nconnection, and verified email or phone workflows.\n\nTwo deprecated singular calendar-event aliases are also excluded in favor of\nthe canonical plural event routes.\n\nThese are security and compatibility boundaries, not missing catalogue rows.\nThe connector also does not provide:\n\n- arbitrary provider URL or method forwarding;\n- raw credential input in an AIP action;\n- dynamic product code loading in `getaip-server`;\n- streaming results, connector-managed async execution, or cancellation;\n- an automatic retry for an uncertain mutation;\n- a production-readiness claim for an unqualified deployment.\n\n## Evidence status\n\nThe reviewed source contains connector contract tests and a frozen conformance\nsuite for the complete catalogue. A retained historical isolated-live report\nalso records an exact-upstream Cal.diy campaign, but that report does not prove\nthe current source revision, a rebuilt host, or a new Cal.diy deployment.\n\nTreat evidence labels narrowly:\n\n| Evidence | What it supports | What it does not support |\n|---|---|---|\n| Source and schemas | Implemented contract at the reviewed commit | Runtime behavior of an unbuilt artifact |\n| Deterministic tests | Reproducible connector behavior under test fixtures | Execution against a real Cal.diy service |\n| Historical isolated-live report | The named historical artifacts and upstream | Current deployment qualification |\n| Deployment campaign | Only the exact identities and scenarios retained by that run | Other images, revisions, tenants, or topology |\n\n## Choose the next document\n\nThe Cal.diy section is organized by task:\n\n- start with `getting-started/quickstart.md` for the first admitted host and\n  read-only invocation;\n- use `getting-started/authentication-and-tenant-routing.md` to choose a\n  credential and account-isolation model;\n- use `reference/configuration.md` for the complete host settings;\n- open `capabilities/README.md` to choose a capability family;\n- use the guides for booking and availability workflows;\n- use the operations pages for deployment, health, recovery, and rollout;\n- use `qualification/README.md` before making a readiness claim.\n\nUse the global references below for fleet-wide routing, conformance, migration,\nand evidence boundaries.\n\n## Related documentation\n\n- [Connector documentation](../README.md)\n- [Pinned upstream baselines](../upstream-baselines.md)\n- [Conformance](../../reference/conformance.md)\n- [Historical Cal.diy isolated-live evidence](../../testing/cal-diy-isolated-live.md)\n- [Migrate bundled connectors](../../guides/migrate-bundled-connectors.md)\n",
    "text": "Cal.diy connector\n\nUse the Cal.diy connector when an AIP application must read or change\nscheduling state through a typed, tenant-bound capability surface. The\nconnector runs in its own aip-host-cal-diy process; product-neutral getaip-server\nroutes admitted actions to that host and does not contain Cal.diy product code\nor credentials.\n\nThe reviewed connector exposes 81 operations from one pinned Cal.diy source\nrevision. It adds AIP approval, idempotency, routing, evidence, and webhook\nboundaries around those provider operations. It does not expose every Cal.diy\nadministrator, credential-provisioning, or compatibility route.\n\nAt a glance\n\n| Property | Reviewed value |\n\n| Connector id | cal-diy |\n| Standalone process | aip-host-cal-diy |\n| AIP workspace version | 2.0.0 |\n| Reviewed AIP source | d7cce13d1d555644d04a4d73c66c95b113737635 |\n| Pinned Cal.diy source | f00434927386c9ecdcbd7e6c5f82d22044a245bc |\n| Connector profile | aip.connector.caldiy.v1 |\n| Webhook profile | aip.http.webhook.v1 |\n| Capability prefix | cap:caldiy: |\n| Business operations | 81 |\n| Provider authentication | Bearer token or OAuth client credentials |\n| Execution | Synchronous; no connector streaming, async execution, or cancellation |\n| Mutation policy | Approval and external-account-scoped idempotency required |\n\nThe source revision identifies what was reviewed. It is not a claim that a\ndifferent branch, rebuilt image, Cal.diy deployment, or provider revision has\nthe same behavior.\n\nChoose this connector when\n\nThe connector fits an integration that needs to:\n• discover availability and reserve a slot;\n• create and manage bookings with explicit approval;\n• read or change event types, schedules, calendars, conferencing, and\n  webhooks;\n• keep provider credentials in the connector deployment rather than in AIP\n  messages;\n• route each authenticated tenant to an owner-admitted, account-specific host\n  without placing provider credentials in AIP messages;\n• turn authenticated Cal.diy webhooks into durable AIP events;\n• prevent a retry from silently repeating an uncertain provider mutation.\n\nUse a provider-owned administrative integration instead when the task must\ncreate API keys, complete browser OAuth, administer OAuth clients, verify email\nor phone ownership, or invoke an upstream route outside the frozen catalogue.\n\nDo not adopt the reviewed connector unchanged for a different Cal.diy revision.\nCompare the provider routes and schemas first, then repeat connector\nconformance and deployment qualification for the exact artifact.\n\nDeployment boundary\n\nThe reference topology separates protocol routing from product execution:\n1. An authenticated caller submits a native AIP action to getaip-server.\n2. getaip-server applies protocol validation, identity, authorization, approval, and\n   runtime policy.\n3. The connector registry selects an admitted cal-diy instance and healthy\n   replica for the tenant.\n4. The remote connector path sends the action to aip-host-cal-diy.\n5. The host uses its deployment-owned Cal.diy account and secret-file\n   configuration.\n6. The connector maps the capability to one fixed Cal.diy method, path, and\n   API-version header.\n7. The result returns through the host and central runtime with provider\n   credential material excluded.\n\nThe registry does not execute images or load product crates dynamically. An\noperator builds and deploys the Cal.diy host separately, then admits its exact\nidentity, contract, artifact, and evidence. Adding another admitted instance\ndoes not recompile getaip-server.\n\nSupported capability families\n\nThe family counts below come from the 81-entry ALLOPERATIONS catalogue at\nthe reviewed source revision.\n\n| Family | Count | Supported outcome |\n\n| Profile | 2 | Read or update the authenticated profile |\n| Event types and private links | 15 | Manage event types, private links, and event-type webhooks |\n| Slots and reservations | 5 | Query availability and manage a short-lived reservation |\n| Bookings | 22 | Read, create, reschedule, cancel, confirm, reassign, and inspect artifacts |\n| Calendars and free/busy | 21 | Manage connections, events, busy time, destination, and conflict selection |\n| Conferencing | 5 | Discover, select, connect, or disconnect conferencing applications |\n| Schedules | 6 | List, read, create, update, or delete schedules |\n| User webhooks | 5 | List, read, create, update, or delete user-level webhooks |\n| Total | 81 | Complete admitted business-operation catalogue |\n\nEach capability advertises both aip.native.http.v1 and the connector profile.\nIts binding contains the exact provider method, path template, API version, and\noperation suffix. Input and output remain typed JSON; a provider response is\nbounded before it is parsed or returned.\n\nCredential and tenant boundary\n\nThe standalone host accepts exactly one provider authentication mode:\n• an owner-controlled Bearer-token file; or\n• an OAuth client id with an owner-controlled client-secret file.\n\nThe connector does not perform an OAuth browser flow and does not refresh an\nOAuth credential through the agent surface.\n\nThe reviewed standalone host also requires one stable Cal.diy account id. It\ndoes not expose the connector library's optional tenant-to-account\ncredential-handle composition. In the standalone fleet, bind each tenant to an\nadmitted account-specific instance through owner-controlled registry topology;\naction input cannot choose another account or secret.\n\nThe connector library does implement a fail-closed credential-routing mode for\nspecialized compositions and frozen conformance tests. That mode requires a\ntrusted runtime tenant context, owner-defined bindings, and a credential\nprovider. Do not assume it is active in aip-host-cal-diy, and do not adopt the\nmigration-only bundled daemon as the target architecture merely to obtain its\nlegacy command-line wiring.\n\nMutation safety\n\nAll non-GET operations require AIP approval and an idempotency key scoped to the\nexternal account. Reading booking recordings or transcripts also requires\napproval because the result may contain restricted meeting data.\n\nBooking create, reschedule, and cancel require a validated plan before commit.\nOther mutations still support the connector transaction modes, but their dry\nrun checks policy and input without claiming a complete downstream simulation.\n\nCal.diy does not provide universal provider idempotency for this catalogue. The\nconnector therefore records a durable compare-and-set dispatch claim before a\nmutation can cross the provider boundary. Reusing the same key and input can\nreturn the stored result; reusing the key with different input is a collision.\n\nIf a crash or timeout leaves a dispatched mutation without trusted terminal\nevidence, the ledger marks the outcome uncertain. The connector does not\nblindly retry that mutation. Reconciliation must use the dispatch ledger, a\ntrusted transaction checkpoint, or operator evidence before another provider\neffect is allowed.\n\nReads are retryable. Mutations are not advertised as retry-safe. Some create\noperations name a best-effort compensating delete or cancel capability, but\ncompensation is a separately approved action, not an atomic rollback.\n\nSigned event ingress\n\nWhen webhook secrets are configured, Cal.diy sends a delivery to the\nstandalone host route:\n\nPOST /webhooks/cal-diy/{subscriptionid}\n\nThe path selector chooses a deployment-owned secret reference. The host\nrequires X-Cal-Signature-256 and X-Cal-Webhook-Version, preserves the exact\nraw body, enforces a 1 MiB body limit, and passes a trusted receipt time to the\nconnector.\n\nThe connector verifies the raw-body HMAC, the supported webhook version\n2021-10-20, the event-time window, and durable replay identity. Accepted\nevents are appended locally and queued for central delivery. A replay resolves\nto the same deterministic event identity; a replay-store or event-store\nfailure fails closed instead of acknowledging unretained state.\n\nCreating or updating a provider webhook also requires its subscriber URL to\nmatch an operator-configured HTTPS prefix. No destination is accepted by\ndefault.\n\nDeliberate exclusions\n\nThe source names 38 operator-only upstream routes that are not capabilities.\nThey cover credential creation or refresh, browser OAuth and callbacks, OAuth\nclient administration, calendar or conferencing connection setup, Stripe\nconnection, and verified email or phone workflows.\n\nTwo deprecated singular calendar-event aliases are also excluded in favor of\nthe canonical plural event routes.\n\nThese are security and compatibility boundaries, not missing catalogue rows.\nThe connector also does not provide:\n• arbitrary provider URL or method forwarding;\n• raw credential input in an AIP action;\n• dynamic product code loading in getaip-server;\n• streaming results, connector-managed async execution, or cancellation;\n• an automatic retry for an uncertain mutation;\n• a production-readiness claim for an unqualified deployment.\n\nEvidence status\n\nThe reviewed source contains connector contract tests and a frozen conformance\nsuite for the complete catalogue. A retained historical isolated-live report\nalso records an exact-upstream Cal.diy campaign, but that report does not prove\nthe current source revision, a rebuilt host, or a new Cal.diy deployment.\n\nTreat evidence labels narrowly:\n\n| Evidence | What it supports | What it does not support |\n\n| Source and schemas | Implemented contract at the reviewed commit | Runtime behavior of an unbuilt artifact |\n| Deterministic tests | Reproducible connector behavior under test fixtures | Execution against a real Cal.diy service |\n| Historical isolated-live report | The named historical artifacts and upstream | Current deployment qualification |\n| Deployment campaign | Only the exact identities and scenarios retained by that run | Other images, revisions, tenants, or topology |\n\nChoose the next document\n\nThe Cal.diy section is organized by task:\n• start with getting-started/quickstart.md for the first admitted host and\n  read-only invocation;\n• use getting-started/authentication-and-tenant-routing.md to choose a\n  credential and account-isolation model;\n• use reference/configuration.md for the complete host settings;\n• open capabilities/README.md to choose a capability family;\n• use the guides for booking and availability workflows;\n• use the operations pages for deployment, health, recovery, and rollout;\n• use qualification/README.md before making a readiness claim.\n\nUse the global references below for fleet-wide routing, conformance, migration,\nand evidence boundaries.\n\nRelated documentation\n• Connector documentation (../README.md)\n• Pinned upstream baselines (../upstream-baselines.md)\n• Conformance (../../reference/conformance.md)\n• Historical Cal.diy isolated-live evidence (../../testing/cal-diy-isolated-live.md)\n• Migrate bundled connectors (../../guides/migrate-bundled-connectors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "9785a2d4fd3c51c2d3105891d51ce69f42872bb30b609ab0312af3ad9f11a2e3"
  }
}