@kody/cal-com
Read booking pages, event types, slots, and webhooks on the caller's Cal.com account, with dry-run mutations.
Files
@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
| Lane | Credential | Notes |
|---|---|---|
| A (default) | User secret calComApiKey | Bearer to api.cal.com. account: "work" → calComApiKey-work; or pass secretName. |
| B | Integration cal-com (or integrationName) | BYO OAuth. secretName wins over integrationName. |
Placeholder: {{secret:calComApiKey}}. Hosts: api.cal.com (required),
app.cal.com (OAuth).
Import paths
| Export | Import |
|---|---|
root dispatcher (default smoke-test) | kody:@kody/cal-com |
| request (escape hatch) | kody:@kody/cal-com/request |
| get-profile | kody:@kody/cal-com/get-profile |
| list-bookings | kody:@kody/cal-com/list-bookings |
| get-booking | kody:@kody/cal-com/get-booking |
| create-booking | kody:@kody/cal-com/create-booking |
| cancel-booking | kody:@kody/cal-com/cancel-booking |
| reschedule-booking | kody:@kody/cal-com/reschedule-booking |
| list-event-types | kody:@kody/cal-com/list-event-types |
| get-event-type | kody:@kody/cal-com/get-event-type |
| get-available-slots | kody:@kody/cal-com/get-available-slots |
| list-webhooks | kody:@kody/cal-com/list-webhooks |
| create-webhook | kody:@kody/cal-com/create-webhook |
| summarize-booking-pages | kody:@kody/cal-com/summarize-booking-pages |
| smoke-test | kody:@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
./requestpath is relative tohttps://api.cal.com(include/v2/...). - Never paste Cal.com API keys or OAuth client secrets into chat or logs.