Skip to content
← Public packages

@kody/calendly

Read Calendly event types, scheduled events, and invitees on the caller's account, with dry-run mutations.

FollowFork

Files

README.md

135 lines · 6.5 KB · Markdown

@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:

LaneCredentialWhen to use
A. Personal access token (fastest)User secret calendlyPatInternal / single-account automation. Calendly recommends PATs for private apps.
B. Bring-your-own OAuthSaved 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. 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
  1. In the account secrets UI, approve host api.calendly.com.
  2. Agents: smoke-test via 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. 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
ScopeNeeded 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 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