# @kody/cal-com — agent notes Human setup and intent live in [`README.md`](./README.md). This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by **name** only — never paste key values. Do not disable live webhooks or jobs. ## Auth | Lane | Credential | Notes | | --- | --- | --- | | A (default) | User secret `calComApiKey` | Bearer to `api.cal.com`. `account: "work"` → `calComApiKey-work`; or pass `secretName`. | | B | Integration `cal-com` (or `integrationName`) | BYO OAuth. `secretName` wins over `integrationName`. | Placeholder: `{{secret:calComApiKey}}`. Hosts: `api.cal.com` (required), `app.cal.com` (OAuth). ## Import paths | Export | Import | | --- | --- | | root dispatcher (default `smoke-test`) | `kody:@kody/cal-com` | | request (escape hatch) | `kody:@kody/cal-com/request` | | get-profile | `kody:@kody/cal-com/get-profile` | | list-bookings | `kody:@kody/cal-com/list-bookings` | | get-booking | `kody:@kody/cal-com/get-booking` | | create-booking | `kody:@kody/cal-com/create-booking` | | cancel-booking | `kody:@kody/cal-com/cancel-booking` | | reschedule-booking | `kody:@kody/cal-com/reschedule-booking` | | list-event-types | `kody:@kody/cal-com/list-event-types` | | get-event-type | `kody:@kody/cal-com/get-event-type` | | get-available-slots | `kody:@kody/cal-com/get-available-slots` | | list-webhooks | `kody:@kody/cal-com/list-webhooks` | | create-webhook | `kody:@kody/cal-com/create-webhook` | | summarize-booking-pages | `kody:@kody/cal-com/summarize-booking-pages` | | smoke-test | `kody:@kody/cal-com/smoke-test` | Prefer static `kody:@kody/cal-com/...` imports from `execute`. Do not lead with `packages.invoke`. ## Smoke test (read-only) ```js import smokeTest from 'kody:@kody/cal-com/smoke-test' export default async function main() { return await smokeTest() // with creds => { ok: true, live: true, profile: { id, username, email, ... }, setup } // without => { ok: true, live: false, setup: { ...URLs } } } ``` Dry-run preview (no network): ```js import smokeTest from 'kody:@kody/cal-com/smoke-test' export default async function main() { return await smokeTest({ dryRun: true }) } ``` Read-only samples: ```js import listEventTypes from 'kody:@kody/cal-com/list-event-types' import getAvailableSlots from 'kody:@kody/cal-com/get-available-slots' import summarizeBookingPages from 'kody:@kody/cal-com/summarize-booking-pages' import listWebhooks from 'kody:@kody/cal-com/list-webhooks' export default async function main() { const types = await listEventTypes() const slots = await getAvailableSlots({ eventTypeId: types[0]?.id, start: '2026-06-01', end: '2026-06-08', timeZone: 'America/Denver', }) const pages = await summarizeBookingPages() const webhooks = await listWebhooks() return { types, slots, pages, webhooks } } ``` ## dryRun / confirm (writes) `create-booking`, `cancel-booking`, `reschedule-booking`, `create-webhook`, and mutating `./request` calls: `dryRun: true` returns `{ dryRun: true, method, path, body }` without contacting Cal.com. Live writes also throw unless `confirm: true`. ```js import createBooking from 'kody:@kody/cal-com/create-booking' export default async function main() { const preview = await createBooking({ eventTypeId: 123, start: '2026-06-01T16:00:00Z', attendee: { name: 'Ada', email: 'ada@example.com' }, dryRun: true, }) // Only after explicit user confirmation: const booking = await createBooking({ eventTypeId: 123, start: '2026-06-01T16:00:00Z', attendee: { name: 'Ada', email: 'ada@example.com' }, confirm: true, }) return { preview, booking } } ``` ## Edge cases / fork notes - Prefer this package for Cal.com booking flows; use Google Calendar helpers for direct Google event CRUD. - Fork/adapt: keep secret name `calComApiKey` (or document a rename); do not hard-code personal booking paths. - Low-level `./request` path is relative to `https://api.cal.com` (include `/v2/...`). - Never paste Cal.com API keys or OAuth client secrets into chat or logs.