# @kody/calendly ## Intent Reusable Calendly helpers so Kody agents can inspect **the caller's** event types, scheduled events, and invitees — not a shared platform calendar, and not Cal.com. Auth is a saved personal access token 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 `calendlyPat` (or connect OAuth) and call the helpers in your account. No personal Calendly scheduling URLs, user slugs, or organization URIs are hard-coded. Use `@kody/cal-com` for Cal.com booking pages, slots, and webhooks. Use a Google Calendar helpers package for direct Google Calendar event CRUD. Share this package as https://kody.codes/@kody/calendly (never a `/community/{listing_id}` URL). ## What it does - Read event types, scheduled events, invitees, and available times - Cancel scheduled events, create invitees, or mark no-shows when you explicitly request it (`dryRun` / `confirm`) - Resolve multi-account PAT / OAuth credentials via `./accounts` - Escape-hatch `./request` for uncommon Calendly API paths ## Prerequisites / setup Calendly has **no built-in Kody OAuth app**. Choose one lane: | Lane | Credential | When to use | | --- | --- | --- | | A. Personal access token (fastest) | User secret `calendlyPat` | Internal / single-account automation. Calendly recommends PATs for private apps. | | B. Bring-your-own OAuth | Saved integration named `calendly` (or another name you pass as `integrationName`) | Multi-account or public apps. There is no built-in Calendly platform app. | Both lanes send `Authorization: Bearer …` to `https://api.calendly.com`. Do not paste tokens or client secrets into chat. ### Lane A: Personal access token 1. Create a token at [Integrations → API & Webhooks](https://calendly.com/integrations/api_webhooks). Grant `users:read`, `event_types:read`, `scheduled_events:read`, and `scheduled_events:write` for the helpers in this package. 2. Save it in Kody (do not paste the value in chat): ``` https://kody.codes/account/secrets/new?name=calendlyPat&description=Calendly%20personal%20access%20token%20(Bearer%20token%20for%20api.calendly.com)&allowedHosts=api.calendly.com&scope=user ``` 3. In the account secrets UI, approve host `api.calendly.com`. 4. Agents: smoke-test via [`AGENTS.md`](./AGENTS.md). Pass `account: "work"` to use secret `calendlyPat-work`, or pass `secretName: "calendlyPat-work"`. There are no hard-coded account aliases. ### Lane B: OAuth Create an OAuth app at [developer.calendly.com](https://developer.calendly.com/). Register the redirect URI exactly: ``` https://kody.codes/connect/oauth ``` Use Production for live account data. Calendly shows the client secret only once. Then open this prefilled connect URL while signed in to Kody and paste the client ID and client secret into the setup form (`flow=confidential` plus S256 PKCE): ``` https://kody.codes/connect/oauth?provider=calendly&authorizeUrl=https%3A%2F%2Fauth.calendly.com%2Foauth%2Fauthorize&tokenUrl=https%3A%2F%2Fauth.calendly.com%2Foauth%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.calendly.com&scopes=users%3Aread%20event_types%3Aread%20scheduled_events%3Aread%20scheduled_events%3Awrite&flow=confidential&pkce=true&allowedHosts=api.calendly.com%2Cauth.calendly.com&dashboardUrl=https%3A%2F%2Fdeveloper.calendly.com%2F&providerSetupInstructions=Create%20an%20OAuth%20app%20at%20https%3A%2F%2Fdeveloper.calendly.com%2F.%20Register%20redirect%20URI%20exactly%20https%3A%2F%2Fkody.codes%2Fconnect%2Foauth.%20Use%20Production%20for%20live%20account%20data.%20Calendly%20shows%20the%20client%20secret%20only%20once.%20Paste%20the%20client%20id%20and%20client%20secret%20into%20this%20Kody%20form.%20Request%20scopes%20users%3Aread%20event_types%3Aread%20scheduled_events%3Aread%20scheduled_events%3Awrite.%20Do%20not%20paste%20secrets%20into%20chat. ``` Decoded: authorize `https://auth.calendly.com/oauth/authorize`, token `https://auth.calendly.com/oauth/token`, scopes `users:read event_types:read scheduled_events:read scheduled_events:write`, hosts `api.calendly.com,auth.calendly.com`. Call helpers with `integrationName: "calendly"` (or your chosen provider name). `secretName` selects the PAT lane and ignores `integrationName` unless you also pass `auth: "oauth"`. When both a `calendly` integration and `calendlyPat` exist, helpers prefer OAuth unless you pass `auth: "pat"`. Reconnect later at `https://kody.codes/connect/oauth?provider=calendly`. To connect a second account, change `provider` (for example `provider=calendly-work`) and pass `account: "work"` or `integrationName: "calendly-work"` / `secretName: "calendlyPat-work"` on every call. ### Hosts - `api.calendly.com` — all REST calls (required) - `auth.calendly.com` — OAuth authorize + token (OAuth lane) ### Scopes | Scope | Needed for | | --- | --- | | `users:read` | `./get-user`, `./smoke-test` | | `event_types:read` | `./list-event-types`, `./get-event-type`, `./get-available-times` | | `scheduled_events:read` | `./list-scheduled-events`, `./get-scheduled-event`, `./list-invitees`, `./get-invitee` | | `scheduled_events:write` | `./cancel-scheduled-event`, `./create-invitee`, `./mark-no-show` | If Calendly returns 401/403 or an insufficient-scope error, helpers throw a message that names the missing scope and the next setup URL. Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and mutation snippets. ## Done when - `calendlyPat` is saved (or `calendly` OAuth is connected); `api.calendly.com` (and `auth.calendly.com` for OAuth) are approved - Smoke test returns `{ ok: true, live: true, … }` with a trimmed user (no email), or `{ ok: true, live: false }` plus setup URLs when credentials are missing - Mutations preview with `dryRun: true` and only run live with `confirm: true` after you approve the target event/invitee ## Branding `community-icon.svg` is Calendly's official brand mark (the C-in-circle logomark from Calendly's public media kit, color `#006BFF`). Paths are unmodified except for a square tile so the mark stays legible at 56 pixels. Calendly® is a trademark of Calendly. This package is not affiliated with or endorsed by Calendly. ## Docs - [Calendly API getting started](https://developer.calendly.com/getting-started) - [Authentication](https://developer.calendly.com/authentication) - [Creating an OAuth app](https://developer.calendly.com/creating-an-oauth-app) - [Scopes](https://developer.calendly.com/scopes) - [API reference](https://developer.calendly.com/api-docs)