Skip to content
← Public packages

@kody/cal-com

Read booking pages, event types, slots, and webhooks on the caller's Cal.com account, with dry-run mutations.

FollowFork

Files

AGENTS.md

121 lines · 4.0 KB · Markdown

@kody/cal-com — 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)User secret calComApiKeyBearer to api.cal.com. account: "work" → calComApiKey-work; or pass secretName.
BIntegration cal-com (or integrationName)BYO OAuth. secretName wins over integrationName.

Placeholder: {{secret:calComApiKey}}. Hosts: api.cal.com (required), app.cal.com (OAuth).

Import paths

ExportImport
root dispatcher (default smoke-test)kody:@kody/cal-com
request (escape hatch)kody:@kody/cal-com/request
get-profilekody:@kody/cal-com/get-profile
list-bookingskody:@kody/cal-com/list-bookings
get-bookingkody:@kody/cal-com/get-booking
create-bookingkody:@kody/cal-com/create-booking
cancel-bookingkody:@kody/cal-com/cancel-booking
reschedule-bookingkody:@kody/cal-com/reschedule-booking
list-event-typeskody:@kody/cal-com/list-event-types
get-event-typekody:@kody/cal-com/get-event-type
get-available-slotskody:@kody/cal-com/get-available-slots
list-webhookskody:@kody/cal-com/list-webhooks
create-webhookkody:@kody/cal-com/create-webhook
summarize-booking-pageskody:@kody/cal-com/summarize-booking-pages
smoke-testkody:@kody/cal-com/smoke-test

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

Smoke test (read-only)

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

import smokeTest from 'kody:@kody/cal-com/smoke-test'

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

Read-only samples:

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.

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.