@kentcdodds/cal-com

@kentcdodds/cal-com — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke checks, snippets, and edge cases. Secrets by name only — never paste key values. Do not disable live webhooks or jobs.

Secret

• Name: cal-com-api-key (user scope)
• Host: api.cal.com
• Placeholder: {{secret:cal-com-api-key}} (bearer)

Import paths

Prefer named subpath imports. Root dispatches { action } and defaults to smoke-test.

Smoke test (read-only)

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

export default async function main() {
	return await smokeTest()
	// => { ok: true, profile, eventTypeCount, eventTypeId, checks }
}

Or via root:

import calCom from 'kody:@kentcdodds/cal-com'

export default async function main() {
	return await calCom({ action: 'smoke-test' })
}

Safe catalog probes (never use placeholder ids like 123):

import getEventType from 'kody:@kentcdodds/cal-com/get-event-type'
import getAvailableSlots from 'kody:@kentcdodds/cal-com/get-available-slots'

export default async function main() {
	const type = await getEventType({ smoke: true })
	const slots = await getAvailableSlots({ smoke: true })
	return { type, slots }
}

Read-only samples:

import listBookings from 'kody:@kentcdodds/cal-com/list-bookings'
import summarizeBookingPages from 'kody:@kentcdodds/cal-com/summarize-booking-pages'

export default async function main() {
	const bookings = await listBookings({ status: 'upcoming', limit: 10 })
	const pages = await summarizeBookingPages()
	return { bookings, pages }
}

Mutations (live Cal.com state)

There is no package-level dryRun on booking/webhook helpers. Confirm event type, attendee, and start time with the user before create-booking / cancel-booking / reschedule-booking / create-webhook.

import listEventTypes from 'kody:@kentcdodds/cal-com/list-event-types'
import createBooking from 'kody:@kentcdodds/cal-com/create-booking'

export default async function main() {
	const types = await listEventTypes()
	// Only after explicit user confirmation:
	return await createBooking({
		eventTypeId: types[0].id,
		start: '2026-06-01T16:00:00Z',
		attendee: {
			name: 'Ada',
			email: 'ada@example.com',
			timeZone: 'America/Denver',
		},
	})
}

Edge cases

• get-event-type / get-available-slots accept id, slug, or title. With no selector they list event types (same as list-event-types). Unknown slugs/titles throw with a catalog; unknown numeric ids 404 with a catalog.
• { smoke: true } ignores caller selectors and uses a real catalog event type (or returns the list when none exist). Never probe with fake placeholder ids.
• create-booking needs a real id (or slug + username/teamSlug).
• create-webhook accepts official triggers (BOOKING_CREATED, …). Kebab / lowercase aliases normalize; unofficial names (e.g. BOOKING_CONFIRMED) are rejected locally with the allowed list.
• Prefer this package for Cal.com booking flows; use Google Calendar helpers for direct Google event CRUD.
• Low-level ./request path is relative to https://api.cal.com (include /v2/...; legacy /me-style paths are rewritten).