# @kody/calendly — 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 / fastest) | User secret `calendlyPat` | Bearer to `api.calendly.com`. `account: "work"` → `calendlyPat-work`; or pass `secretName`. | | B | Integration `calendly` (or `integrationName`) | BYO OAuth + PKCE. Hosts `api.calendly.com`, `auth.calendly.com`. | When both exist, helpers prefer OAuth unless `auth: "pat"`. `secretName` selects the PAT lane unless you also pass `auth: "oauth"`. Placeholder: `{{secret:calendlyPat|scope=user}}`. ## Import paths | Export | Import | | --- | --- | | root dispatcher (default `smoke-test`) | `kody:@kody/calendly` | | accounts | `kody:@kody/calendly/accounts` | | smoke-test | `kody:@kody/calendly/smoke-test` | | get-user | `kody:@kody/calendly/get-user` | | list-event-types | `kody:@kody/calendly/list-event-types` | | get-event-type | `kody:@kody/calendly/get-event-type` | | get-available-times | `kody:@kody/calendly/get-available-times` | | list-scheduled-events | `kody:@kody/calendly/list-scheduled-events` | | get-scheduled-event | `kody:@kody/calendly/get-scheduled-event` | | cancel-scheduled-event | `kody:@kody/calendly/cancel-scheduled-event` | | list-invitees | `kody:@kody/calendly/list-invitees` | | get-invitee | `kody:@kody/calendly/get-invitee` | | create-invitee | `kody:@kody/calendly/create-invitee` | | mark-no-show | `kody:@kody/calendly/mark-no-show` | | request (escape hatch) | `kody:@kody/calendly/request` | | types | `kody:@kody/calendly/types` | Prefer static `kody:@kody/calendly/...` imports from `execute`. Do not lead with `packages.invoke`. ## Smoke test (read-only) ```js import smokeTest from 'kody:@kody/calendly/smoke-test' export default async function main() { return await smokeTest() // without creds => { ok: true, live: false, setup: { ...URLs } } // with creds => { ok: true, live: true, ...trimmed user... } (no email) } ``` Dry-run preview (no network): ```js import calendly from 'kody:@kody/calendly' export default async function main() { return await calendly({ dryRun: true }) } ``` ## Common snippets ```js import listEventTypes from 'kody:@kody/calendly/list-event-types' export default async function main() { return await listEventTypes({ active: true, count: 20 }) } ``` ```js import listScheduledEvents from 'kody:@kody/calendly/list-scheduled-events' import listInvitees from 'kody:@kody/calendly/list-invitees' export default async function main() { const { items } = await listScheduledEvents({ status: 'active', count: 10 }) if (!items[0]) return { items, invitees: [] } return await listInvitees({ event: items[0].uuid }) } ``` ## dryRun / confirm (writes) `cancel-scheduled-event`, `create-invitee`, `mark-no-show`, and mutating `./request` calls: `dryRun: true` returns `{ dryRun: true, wouldCall }` without contacting Calendly. Live writes also throw unless `confirm: true`. ```js import cancelScheduledEvent from 'kody:@kody/calendly/cancel-scheduled-event' export default async function main() { const preview = await cancelScheduledEvent({ event: 'AAAAAAAAAAAAAAAA', reason: 'Need to reschedule', dryRun: true, }) // Only after explicit user confirmation: const canceled = await cancelScheduledEvent({ event: 'AAAAAAAAAAAAAAAA', reason: 'Need to reschedule', confirm: true, }) return { preview, canceled } } ``` ```js import createInvitee from 'kody:@kody/calendly/create-invitee' export default async function main() { return await createInvitee({ eventType: 'AAAAAAAAAAAAAAAA', startTime: '2026-06-01T16:00:00Z', invitee: { name: 'Ada', email: 'ada@example.com', timezone: 'America/Denver' }, dryRun: true, }) } ``` ## Edge cases / fork notes - REST base: `https://api.calendly.com` - List helpers return `{ items, pageInfo }`. Get helpers return a slim resource. - Uuids may be bare or full `https://api.calendly.com/...` URIs. - `POST /invitees` (create-invitee) can require a paid Calendly plan. - Prefer `@kody/cal-com` for Cal.com; this package is Calendly-only. - Fork/adapt: keep `calendlyPat` / `calendly` names documented; do not hard-code personal scheduling URLs, user slugs, or org URIs. - Never paste Calendly PATs or OAuth client secrets into chat or logs.