@keystrokehq/cal-com

Official Keystroke integration for Cal.com.

Overview

This package provides a single-mode Cal.com authoring surface for the current Cal.com v2 API: bookings, event types, schedules, teams, memberships, organizations, calendars, webhook management, and direct-binding webhook triggers.

The package root is intentionally non-canonical. Import from explicit subpaths instead:

• Support surfaces: connection, client, schemas, events, triggers, verification
• Domain surfaces: bookings, event-types, availability, schedules, slots, teams, memberships, users, me, organizations, attributes, selected-calendars, destination-calendars, calendars, conferencing, webhooks, stripe, phone-calls, timezones

Install

pnpm add @keystrokehq/cal-com

Connect

Cal.com recommends OAuth and this package treats OAuth as the canonical public connection shape. The runtime also normalizes bearer API keys into the same resolved credential contract.

import { calCom, type CalComCredentials } from '@keystrokehq/cal-com/connection';

// `calCom` is the public CredentialSet for workflow definitions.
// Runtime credentials always resolve to a shape with:
// - CAL_COM_ACCESS_TOKEN
// - CAL_COM_AUTH_KIND (`oauth` | `api-key`)
// - optional self-hosted base URL / client metadata

Quickstart

One operation

import { getMe } from '@keystrokehq/cal-com/me';
import { listBookings } from '@keystrokehq/cal-com/bookings';
import { listSchedules } from '@keystrokehq/cal-com/schedules';

// Operations are workflow steps; call them with `.run(...)` from workflow code.

One trigger

import { webhooks } from '@keystrokehq/cal-com/triggers';

const bookingCreated = webhooks.bookingCreated({
  name: 'Cal.com Booking Created',
  transform: (event) => ({
    bookingUid:
      typeof event.payload === 'object' &&
      event.payload !== null &&
      'uid' in event.payload &&
      typeof event.payload.uid === 'string'
        ? event.payload.uid
        : undefined,
  }),
});

Modules

Authoring surface:

| Subpath | Purpose | | --- | --- | | @keystrokehq/cal-com/connection | calCom credential set, CAL_COM_OAUTH_SCOPES, CalComCredentials | | @keystrokehq/cal-com/bookings | booking CRUD and lifecycle mutations | | @keystrokehq/cal-com/event-types | event-type lookup plus team/org event-type helpers | | @keystrokehq/cal-com/availability | availability queries | | @keystrokehq/cal-com/schedules | schedules and org/team user schedule helpers | | @keystrokehq/cal-com/slots | available slots, slot reservations, busy times | | @keystrokehq/cal-com/teams | teams and organization team helpers | | @keystrokehq/cal-com/memberships | org/team membership CRUD | | @keystrokehq/cal-com/users | organization user helpers | | @keystrokehq/cal-com/me | current-user profile | | @keystrokehq/cal-com/organizations | organization lookup helpers | | @keystrokehq/cal-com/attributes | organization attributes and attribute options | | @keystrokehq/cal-com/calendars | calendar/provider connection and credential helpers | | @keystrokehq/cal-com/selected-calendars | selected calendar add/remove | | @keystrokehq/cal-com/destination-calendars | destination calendar updates | | @keystrokehq/cal-com/conferencing | conferencing app connect/oauth/default helpers | | @keystrokehq/cal-com/webhooks | general, event-type, and organization webhook CRUD | | @keystrokehq/cal-com/stripe | Stripe integration status and connect info | | @keystrokehq/cal-com/phone-calls | phone call event creation | | @keystrokehq/cal-com/timezones | supported timezone list | | @keystrokehq/cal-com/triggers | 21 direct-binding webhook trigger helpers |

Support surfaces:

| Subpath | Purpose | | --- | --- | | @keystrokehq/cal-com/client | createCalComClient(credentials) escape hatch | | @keystrokehq/cal-com/schemas | shared Zod schemas and inferred types | | @keystrokehq/cal-com/events | webhook event names and schemas | | @keystrokehq/cal-com/verification | low-level webhook signature verification |

Hidden internal imports: @keystrokehq/cal-com/_official and @keystrokehq/cal-com/_runtime.

Webhooks

Cal.com signs webhook deliveries with the x-cal-signature-256 header. This package verifies the raw request body against CAL_COM_WEBHOOK_SIGNING_SECRET before the bound trigger reaches user-authored filters or transforms.

import { verifyCalComWebhookRequest } from '@keystrokehq/cal-com/verification';

const verified = verifyCalComWebhookRequest({
  headers: { 'x-cal-signature-256': 'signature' },
  rawBody: '{}',
  signingSecret: 'whsec_demo',
});

Trigger Catalog

The trigger surface follows the current 21-event Cal.com webhook catalog:

BOOKING_CREATED, BOOKING_PAYMENT_INITIATED, BOOKING_PAID, BOOKING_RESCHEDULED, BOOKING_REQUESTED, BOOKING_CANCELLED, BOOKING_REJECTED, BOOKING_NO_SHOW_UPDATED, FORM_SUBMITTED, MEETING_ENDED, MEETING_STARTED, RECORDING_READY, INSTANT_MEETING, RECORDING_TRANSCRIPTION_GENERATED, OOO_CREATED, AFTER_HOSTS_CAL_VIDEO_NO_SHOW, AFTER_GUESTS_CAL_VIDEO_NO_SHOW, FORM_SUBMITTED_NO_EVENT, ROUTING_FORM_FALLBACK_HIT, DELEGATION_CREDENTIAL_ERROR, WRONG_ASSIGNMENT_REPORT.

Notes

• The package targets the current Cal.com v2 docs only.
• Deprecated platform-era domains are intentionally excluded.
• OAuth is the canonical public connection, but bearer API keys normalize into the same runtime auth shape.
• Self-hosted Cal.com deployments can set CAL_COM_SELF_HOSTED_BASE_URL.

License

MIT