Skip to content
← Public packages

@kody/cal-com

Read booking pages, event types, slots, and webhooks on the caller's Cal.com account, with dry-run mutations.

FollowFork

Files

README.md

110 lines · 4.9 KB · Markdown

@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. 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
  1. In the account secrets UI, approve host api.cal.com.
  2. 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 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 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