# @kody/cal-com ## Intent Reusable Cal.com helpers so Kody agents can inspect booking pages, event types, availability slots, bookings, and webhooks on the **caller's** Cal.com account — not a shared platform calendar. Auth is a saved API key by default, or a bring-your-own OAuth client. Reads are free-form. Mutations support `dryRun: true`, and live writes also require `confirm: true`. This listing is meant to be forked. After you fork, save your own `calComApiKey` (or connect OAuth) and call the helpers in your account. Booking URLs are built from the connected profile username plus each event-type slug (or the event type's own `link`). No personal Cal.com booking paths are hard-coded. The earlier `@kentcdodds/cal-com` listing stored `cal-com-api-key`; this official package uses `calComApiKey`. Use a Google Calendar helpers package for direct Google Calendar event CRUD instead of Cal.com booking flows. ## What it does - Read profile, bookings, event types, available slots, and webhooks - Summarize booking pages (username + event-type booking URLs) - Create, cancel, or reschedule bookings when you explicitly request it - Register Cal.com webhooks for automation - Escape-hatch request helper for uncommon Cal.com API v2 paths ## Prerequisites / setup ### Lane A: API key (default) Cal.com recommends API keys for agents. 1. Create a key at [Settings → Developer → API Keys](https://app.cal.com/settings/developer/api-keys). Keys look like `cal_…` or `cal_live_…`. 2. Save it in Kody (do not paste the value in chat): ``` https://kody.codes/account/secrets/new?name=calComApiKey&description=Cal.com%20API%20key%20(Bearer%20token%20for%20api.cal.com)&allowedHosts=api.cal.com&scope=user ``` 3. In the account secrets UI, approve host `api.cal.com`. 4. Omit `secretName` and `integrationName` on helpers (default secret `calComApiKey`). Pass `account: "work"` for `calComApiKey-work`, or `secretName: "calComApiKey-live"`. There are no hard-coded account aliases. ### Lane B: OAuth Saved integration named `cal-com` (or another name you pass as `integrationName`). There is no built-in Cal.com platform app. Cal.com OAuth clients are created at [Settings → Developer → OAuth](https://app.cal.com/settings/developer/oauth) and stay pending until a Cal.com admin approves them. Register the redirect URI exactly: ``` https://kody.codes/connect/oauth ``` Then open this prefilled connect URL while signed in to Kody. Paste the client ID and client secret into the setup form (`flow=confidential`): ``` https://kody.codes/connect/oauth?provider=cal-com&authorizeUrl=https%3A%2F%2Fapp.cal.com%2Fauth%2Foauth2%2Fauthorize&tokenUrl=https%3A%2F%2Fapi.cal.com%2Fv2%2Fauth%2Foauth2%2Ftoken&flow=confidential&scopes=PROFILE_READ%20EVENT_TYPE_READ%20BOOKING_READ%20SCHEDULE_READ%20WEBHOOK_READ%20WEBHOOK_WRITE%20BOOKING_WRITE&allowedHosts=api.cal.com%2Capp.cal.com&apiBaseUrl=https%3A%2F%2Fapi.cal.com&dashboardUrl=https%3A%2F%2Fapp.cal.com%2Fsettings%2Fdeveloper%2Foauth&providerSetupInstructions=Create%20an%20OAuth%20client%20at%20https%3A%2F%2Fapp.cal.com%2Fsettings%2Fdeveloper%2Foauth.%20Register%20redirect%20URI%20exactly%20https%3A%2F%2Fkody.codes%2Fconnect%2Foauth.%20Cal.com%20must%20approve%20the%20client%20before%20authorize%20works.%20Paste%20the%20client%20id%20and%20client%20secret%20into%20this%20form. ``` Decoded: authorize `https://app.cal.com/auth/oauth2/authorize`, token `https://api.cal.com/v2/auth/oauth2/token`, scopes `PROFILE_READ EVENT_TYPE_READ BOOKING_READ SCHEDULE_READ WEBHOOK_READ WEBHOOK_WRITE BOOKING_WRITE`, hosts `api.cal.com,app.cal.com`. Call helpers with `integrationName: "cal-com"` (or your chosen provider name). `secretName` selects the API-key lane and ignores `integrationName`. Reconnect later at `https://kody.codes/connect/oauth?provider=cal-com`. This is not Cal.com Platform / managed-user auth (`x-cal-client-id` / `x-cal-secret-key`). Those credentials are a different product. ### Hosts - `api.cal.com` — all REST calls (required) - `app.cal.com` — OAuth authorize + developer settings (OAuth lane) Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and mutation snippets. ## Done when - `calComApiKey` is saved (or `cal-com` OAuth is connected); `api.cal.com` (and `app.cal.com` for OAuth) are approved - Smoke test returns `{ ok: true, live: true, … }` with a trimmed profile, or `{ ok: true, live: false }` plus setup URLs when credentials are missing - Booking / webhook mutations preview with `dryRun: true` and only run live with `confirm: true` after you approve the target ## Branding `community-icon.svg` is Cal.com's official wordmark (white "Cal" on `#292929`). Cal.com is a trademark of Cal.com, Inc. This package is not affiliated with or endorsed by Cal.com. ## Docs - [Cal.com API v2](https://cal.com/docs/api-reference/v2/introduction) - [OAuth](https://cal.com/docs/api-reference/v2/oauth) - [Agents (API key)](https://cal.com/docs/agents)