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

AGENTS.md

133 lines · 4.4 KB · Markdown

@kody/calendly — agent notes

Human setup and intent live in 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

LaneCredentialNotes
A (default / fastest)User secret calendlyPatBearer to api.calendly.com. account: "work" → calendlyPat-work; or pass secretName.
BIntegration 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

ExportImport
root dispatcher (default smoke-test)kody:@kody/calendly
accountskody:@kody/calendly/accounts
smoke-testkody:@kody/calendly/smoke-test
get-userkody:@kody/calendly/get-user
list-event-typeskody:@kody/calendly/list-event-types
get-event-typekody:@kody/calendly/get-event-type
get-available-timeskody:@kody/calendly/get-available-times
list-scheduled-eventskody:@kody/calendly/list-scheduled-events
get-scheduled-eventkody:@kody/calendly/get-scheduled-event
cancel-scheduled-eventkody:@kody/calendly/cancel-scheduled-event
list-inviteeskody:@kody/calendly/list-invitees
get-inviteekody:@kody/calendly/get-invitee
create-inviteekody:@kody/calendly/create-invitee
mark-no-showkody:@kody/calendly/mark-no-show
request (escape hatch)kody:@kody/calendly/request
typeskody:@kody/calendly/types

Prefer static kody:@kody/calendly/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only)

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

import calendly from 'kody:@kody/calendly'

export default async function main() {
	return await calendly({ dryRun: true })
}

Common snippets

import listEventTypes from 'kody:@kody/calendly/list-event-types'

export default async function main() {
	return await listEventTypes({ active: true, count: 20 })
}
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.

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 }
}
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.