@kody/cal-com
Read booking pages, event types, slots, and webhooks on the caller's Cal.com account, with dry-run mutations.
Files
@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.
- Create a key at
Settings → Developer → API Keys.
Keys look like
cal_…orcal_live_…. - 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- In the account secrets UI, approve host
api.cal.com. - Omit
secretNameandintegrationNameon helpers (default secretcalComApiKey). Passaccount: "work"forcalComApiKey-work, orsecretName: "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/oauthThen 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
calComApiKeyis saved (orcal-comOAuth is connected);api.cal.com(andapp.cal.comfor 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: trueand only run live withconfirm: trueafter 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.