@dereekb/calcom 13.34.0 → 13.36.0

package/src/lib/calcom/calcom.api.eventtype.d.ts

@@ -1,13 +1,80 @@
-import { type Minutes, type Maybe } from '@dereekb/util';
+import { type Minutes, type Maybe, type WebsiteUrl } from '@dereekb/util';
 import { type CalcomContext } from './calcom.config';
-import { type CalcomEventTypeId, type CalcomEventTypeSlug, type CalcomResponseStatus } from '../calcom.type';
+import { type CalcomEventTypeId, type CalcomEventTypeSlug, type CalcomResponseStatus, type CalcomScheduleId, type CalcomUserId } from '../calcom.type';
+/**
+ * A toggleable event-type policy, returned either disabled or with its configuration.
+ *
+ * Cal.com models several independent settings this way (`confirmationPolicy`, `bookingWindow`,
+ * `seats`, `bookerActiveBookingsLimit`), each as `{ disabled: true }` or a settings object.
+ */
+export type CalcomEventTypePolicy = {
+    readonly disabled: true;
+} | Record<string, unknown>;
+/**
+ * A boolean event-type setting Cal.com wraps in an object rather than sending bare.
+ *
+ * `disableCancelling`/`disableRescheduling` are `{ disabled: false }` on the wire in BOTH
+ * directions — the response never carries a bare boolean (so `if (eventType.disableCancelling)`
+ * on one would always be truthy), and passing one to create/update is rejected with "nested
+ * property disableCancelling must be either object or array".
+ */
+export interface CalcomEventTypeDisabledPolicy {
+    readonly disabled: boolean;
+}
 export interface CalcomEventType {
     readonly id: CalcomEventTypeId;
+    readonly ownerId: CalcomUserId;
     readonly title: string;
     readonly slug: CalcomEventTypeSlug;
     readonly description: Maybe<string>;
     readonly lengthInMinutes: Minutes;
+    /**
+     * The selectable lengths of a multi-length event type. Absent on a fixed-length event type —
+     * which is exactly when `lengthInMinutes` may NOT be passed to create-booking.
+     */
+    readonly lengthInMinutesOptions?: Maybe<Minutes[]>;
     readonly locations: unknown[];
+    readonly bookingFields: unknown[];
+    readonly hidden: boolean;
+    readonly scheduleId: Maybe<CalcomScheduleId>;
+    readonly slotInterval: Maybe<Minutes>;
+    readonly minimumBookingNotice: Minutes;
+    readonly beforeEventBuffer: Minutes;
+    readonly afterEventBuffer: Minutes;
+    readonly offsetStart: Minutes;
+    readonly disableGuests: boolean;
+    readonly hideCalendarNotes: boolean;
+    readonly hideCalendarEventDetails: boolean;
+    readonly hideOrganizerEmail: boolean;
+    readonly requiresBookerEmailVerification: boolean;
+    readonly skipAttendeeEmailDeliverabilityCheck: boolean;
+    readonly lockTimeZoneToggleOnBookingPage: boolean;
+    readonly onlyShowFirstAvailableSlot: boolean;
+    readonly showOptimizedSlots: boolean;
+    readonly isInstantEvent: boolean;
+    readonly useDestinationCalendarEmail: boolean;
+    readonly bookingRequiresAuthentication: boolean;
+    readonly disableCancelling: CalcomEventTypeDisabledPolicy;
+    readonly disableRescheduling: CalcomEventTypeDisabledPolicy;
+    readonly allowReschedulingPastBookings: boolean;
+    readonly allowReschedulingCancelledBookings: boolean;
+    readonly forwardParamsSuccessRedirect: boolean;
+    readonly successRedirectUrl: Maybe<WebsiteUrl>;
+    readonly bookingUrl: Maybe<WebsiteUrl>;
+    readonly interfaceLanguage: Maybe<string>;
+    readonly price: number;
+    readonly currency: string;
+    readonly recurrence: Maybe<unknown>;
+    readonly metadata: Record<string, unknown>;
+    readonly users: unknown[];
+    readonly calVideoSettings: Maybe<Record<string, unknown>>;
+    readonly confirmationPolicy: CalcomEventTypePolicy;
+    readonly bookingWindow: CalcomEventTypePolicy;
+    readonly seats: CalcomEventTypePolicy;
+    readonly bookerActiveBookingsLimit: CalcomEventTypePolicy;
+    readonly privateNoteEnabled: boolean;
+    readonly privateNoteMode: Maybe<string>;
+    readonly privateNoteTemplate: Maybe<string>;
 }
 export interface CalcomGetEventTypesResponse {
     readonly status: CalcomResponseStatus;
@@ -17,21 +84,64 @@ export interface CalcomEventTypeResponse {
     readonly status: CalcomResponseStatus;
     readonly data: CalcomEventType;
 }
-export interface CalcomCreateEventTypeInput {
+/**
+ * The event-type settings accepted on both create and update.
+ */
+export interface CalcomEventTypeInputSettings {
+    readonly description?: Maybe<string>;
+    readonly locations?: Maybe<unknown[]>;
+    readonly bookingFields?: Maybe<unknown[]>;
+    /**
+     * The selectable lengths of a multi-length event type. Required before a booking may pass
+     * `lengthInMinutes`.
+     */
+    readonly lengthInMinutesOptions?: Maybe<Minutes[]>;
+    readonly hidden?: Maybe<boolean>;
+    readonly scheduleId?: Maybe<CalcomScheduleId>;
+    readonly slotInterval?: Maybe<Minutes>;
+    readonly minimumBookingNotice?: Maybe<Minutes>;
+    readonly beforeEventBuffer?: Maybe<Minutes>;
+    readonly afterEventBuffer?: Maybe<Minutes>;
+    readonly offsetStart?: Maybe<Minutes>;
+    readonly disableGuests?: Maybe<boolean>;
+    readonly hideCalendarNotes?: Maybe<boolean>;
+    readonly hideCalendarEventDetails?: Maybe<boolean>;
+    readonly hideOrganizerEmail?: Maybe<boolean>;
+    readonly requiresBookerEmailVerification?: Maybe<boolean>;
+    /**
+     * Skips Cal.com's deliverability check on the attendee email, which otherwise rejects
+     * addresses it cannot verify.
+     */
+    readonly skipAttendeeEmailDeliverabilityCheck?: Maybe<boolean>;
+    readonly lockTimeZoneToggleOnBookingPage?: Maybe<boolean>;
+    readonly onlyShowFirstAvailableSlot?: Maybe<boolean>;
+    readonly useDestinationCalendarEmail?: Maybe<boolean>;
+    readonly bookingRequiresAuthentication?: Maybe<boolean>;
+    readonly disableCancelling?: Maybe<CalcomEventTypeDisabledPolicy>;
+    readonly disableRescheduling?: Maybe<CalcomEventTypeDisabledPolicy>;
+    readonly allowReschedulingPastBookings?: Maybe<boolean>;
+    readonly allowReschedulingCancelledBookings?: Maybe<boolean>;
+    readonly forwardParamsSuccessRedirect?: Maybe<boolean>;
+    readonly successRedirectUrl?: Maybe<WebsiteUrl>;
+    readonly interfaceLanguage?: Maybe<string>;
+    readonly price?: Maybe<number>;
+    readonly currency?: Maybe<string>;
+    readonly recurrence?: Maybe<unknown>;
+    readonly metadata?: Maybe<Record<string, unknown>>;
+    readonly confirmationPolicy?: Maybe<CalcomEventTypePolicy>;
+    readonly bookingWindow?: Maybe<CalcomEventTypePolicy>;
+    readonly seats?: Maybe<CalcomEventTypePolicy>;
+    readonly bookerActiveBookingsLimit?: Maybe<CalcomEventTypePolicy>;
+}
+export interface CalcomCreateEventTypeInput extends CalcomEventTypeInputSettings {
     readonly title: string;
     readonly slug: CalcomEventTypeSlug;
     readonly lengthInMinutes: Minutes;
-    readonly description?: string;
-    readonly locations?: unknown[];
-    readonly bookingFields?: unknown[];
 }
-export interface CalcomUpdateEventTypeInput {
-    readonly title?: string;
-    readonly slug?: CalcomEventTypeSlug;
-    readonly lengthInMinutes?: Minutes;
-    readonly description?: string;
-    readonly locations?: unknown[];
-    readonly bookingFields?: unknown[];
+export interface CalcomUpdateEventTypeInput extends CalcomEventTypeInputSettings {
+    readonly title?: Maybe<string>;
+    readonly slug?: Maybe<CalcomEventTypeSlug>;
+    readonly lengthInMinutes?: Maybe<Minutes>;
 }
 /**
  * Retrieves all event types for the authenticated user.

package/src/lib/calcom/calcom.api.schedule.d.ts

@@ -1,18 +1,34 @@
-import { type TimezoneString } from '@dereekb/util';
+import { type ISO8601DayString, type TimezoneString } from '@dereekb/util';
 import { type CalcomContext } from './calcom.config';
-import { type CalcomScheduleId, type CalcomResponseStatus } from '../calcom.type';
+import { type CalcomScheduleId, type CalcomResponseStatus, type CalcomUserId } from '../calcom.type';
 export interface CalcomAvailabilityRule {
     readonly days: string[];
     readonly startTime: string;
     readonly endTime: string;
 }
+/**
+ * A date-specific exception to a schedule's weekly availability.
+ *
+ * NOTE: the array itself is confirmed against the live API, but this entry shape is taken from
+ * the Cal.com docs — the account used to verify this package has no overrides configured, so no
+ * real entry was observed. Treat the field names as unverified.
+ */
+export interface CalcomScheduleOverride {
+    readonly date: ISO8601DayString;
+    readonly startTime: string;
+    readonly endTime: string;
+}
 export interface CalcomSchedule {
     readonly id: CalcomScheduleId;
+    readonly ownerId: CalcomUserId;
     readonly name: string;
     readonly timeZone: TimezoneString;
     readonly availability: CalcomAvailabilityRule[];
     readonly isDefault: boolean;
-    readonly overrides: Record<string, CalcomAvailabilityRule[]>;
+    /**
+     * Date-specific overrides, returned as an ARRAY (not a date-keyed record).
+     */
+    readonly overrides: CalcomScheduleOverride[];
 }
 export interface CalcomGetSchedulesResponse {
     readonly status: CalcomResponseStatus;

package/src/lib/calcom/calcom.api.slot.d.ts

@@ -1,4 +1,4 @@
-import { type ISO8601DateString, type Maybe, type Minutes, type TimezoneString } from '@dereekb/util';
+import { type ISO8601DateString, type ISO8601DayString, type Maybe, type Minutes, type TimezoneString } from '@dereekb/util';
 import { type CalcomContext, type CalcomPublicContext } from './calcom.config';
 import { type CalcomEventTypeId, type CalcomEventTypeSlug, type CalcomUsername, type CalcomTeamSlug, type CalcomOrganizationSlug, type CalcomResponseStatus } from '../calcom.type';
 export interface CalcomGetAvailableSlotsInput {
@@ -14,13 +14,22 @@ export interface CalcomGetAvailableSlotsInput {
     readonly format?: Maybe<'range' | 'time'>;
 }
 export interface CalcomSlot {
-    readonly time: ISO8601DateString;
+    readonly start: ISO8601DateString;
+    /**
+     * The end of the slot. Only returned when `format: 'range'` was requested.
+     */
+    readonly end?: Maybe<ISO8601DateString>;
 }
+/**
+ * Available slots keyed by day (`"2026-08-12"`), each holding that day's slots.
+ */
+export type CalcomSlotsByDay = Record<ISO8601DayString, CalcomSlot[]>;
 export interface CalcomGetAvailableSlotsResponse {
     readonly status: CalcomResponseStatus;
-    readonly data: {
-        readonly slots: Record<string, CalcomSlot[]>;
-    };
+    /**
+     * The day-keyed slot map itself — at `cal-api-version: 2024-09-04` there is no `slots` wrapper.
+     */
+    readonly data: CalcomSlotsByDay;
 }
 /**
  * Queries available booking slots for a given event type within a date range.
@@ -31,6 +40,8 @@ export interface CalcomGetAvailableSlotsResponse {
  * @param context - The Cal.com API context (authenticated or public)
  * @returns Queries available slots for the given input.
  *
+ * The `cal-api-version` header is REQUIRED here — without it the endpoint 404s.
+ *
  * @see https://cal.com/docs/api-reference/v2/slots/get-available-time-slots-for-an-event-type
  *
  * @example
@@ -41,8 +52,8 @@ export interface CalcomGetAvailableSlotsResponse {
  *   eventTypeId: 12345
  * });
  *
- * for (const [date, slots] of Object.entries(response.data.slots)) {
- *   console.log(date, slots.map(s => s.time));
+ * for (const [date, slots] of Object.entries(response.data)) {
+ *   console.log(date, slots.map(s => s.start));
  * }
  * ```
  */

package/src/lib/calcom/calcom.api.user.d.ts

@@ -1,15 +1,27 @@
-import { type EmailAddress, type ISO8601DateString, type TimezoneString, type Maybe } from '@dereekb/util';
+import { type EmailAddress, type TimezoneString, type Maybe, type WebsiteUrl } from '@dereekb/util';
 import { type CalcomContext } from './calcom.config';
-import { type CalcomUserId, type CalcomUsername, type CalcomScheduleId, type CalcomResponseStatus } from '../calcom.type';
+import { type CalcomId, type CalcomUserId, type CalcomUsername, type CalcomScheduleId, type CalcomResponseStatus } from '../calcom.type';
+/**
+ * The organization a user belongs to, as embedded on the user.
+ */
+export interface CalcomUserOrganization {
+    readonly id: CalcomId;
+    readonly isPlatform: boolean;
+}
 export interface CalcomUser {
     readonly id: CalcomUserId;
     readonly email: EmailAddress;
+    readonly name: Maybe<string>;
     readonly username: Maybe<CalcomUsername>;
     readonly timeZone: TimezoneString;
     readonly weekStart: string;
-    readonly createdDate: ISO8601DateString;
     readonly timeFormat: number;
     readonly defaultScheduleId: Maybe<CalcomScheduleId>;
+    readonly avatarUrl: Maybe<WebsiteUrl>;
+    readonly bio: Maybe<string>;
+    readonly locale: Maybe<string>;
+    readonly organizationId: Maybe<CalcomId>;
+    readonly organization: Maybe<CalcomUserOrganization>;
 }
 export interface CalcomGetMeResponse {
     readonly status: CalcomResponseStatus;

package/src/lib/calcom/calcom.api.webhook.d.ts

@@ -1,29 +1,123 @@
-import { type WebsiteUrl, type Maybe } from '@dereekb/util';
+import { type WebsiteUrl, type Maybe, type ISO8601DateString, type TimeDuration, type TimeUnit } from '@dereekb/util';
 import { type CalcomContext } from './calcom.config';
-import { type CalcomWebhookId, type CalcomResponseStatus } from '../calcom.type';
-export type CalcomWebhookTrigger = 'BOOKING_CREATED' | 'BOOKING_CANCELLED' | 'BOOKING_RESCHEDULED' | 'BOOKING_REQUESTED' | 'BOOKING_REJECTED' | 'BOOKING_NO_SHOW_UPDATED' | 'BOOKING_PAYMENT_INITIATED' | 'BOOKING_PAID' | 'MEETING_STARTED' | 'MEETING_ENDED' | 'RECORDING_READY' | 'RECORDING_TRANSCRIPTION_GENERATED';
+import { type CalcomWebhookId, type CalcomResponseStatus, type CalcomUserId, type CalcomId, type CalcomEventTypeId } from '../calcom.type';
+/**
+ * The triggers that fire a set amount of time after the booking, rather than on an event.
+ *
+ * These are the only triggers a {@link CalcomWebhookTimeOffset} applies to.
+ */
+export type CalcomWebhookTimeRelativeTrigger = 'AFTER_HOSTS_CAL_VIDEO_NO_SHOW' | 'AFTER_GUESTS_CAL_VIDEO_NO_SHOW';
+/**
+ * All {@link CalcomWebhookTimeRelativeTrigger} values.
+ */
+export declare const ALL_CALCOM_WEBHOOK_TIME_RELATIVE_TRIGGERS: readonly CalcomWebhookTimeRelativeTrigger[];
+/**
+ * The events a webhook may subscribe to.
+ *
+ * Enumerated by the API itself: posting an unknown trigger returns the full accepted set.
+ */
+export type CalcomWebhookTrigger = CalcomWebhookTimeRelativeTrigger | 'BOOKING_CREATED' | 'BOOKING_PAYMENT_INITIATED' | 'BOOKING_PAID' | 'BOOKING_RESCHEDULED' | 'BOOKING_REQUESTED' | 'BOOKING_CANCELLED' | 'BOOKING_REJECTED' | 'BOOKING_NO_SHOW_UPDATED' | 'BOOKING_LOCATION_UPDATED' | 'FORM_SUBMITTED' | 'FORM_SUBMITTED_NO_EVENT' | 'MEETING_STARTED' | 'MEETING_ENDED' | 'RECORDING_READY' | 'RECORDING_TRANSCRIPTION_GENERATED' | 'INSTANT_MEETING' | 'INSTANT_MEETING_ACCEPTED' | 'OOO_CREATED' | 'ROUTING_FORM_FALLBACK_HIT' | 'WRONG_ASSIGNMENT_REPORT' | 'CALENDAR_ENTRY_REJECTED' | 'DELEGATION_CREDENTIAL_ERROR' | 'DELEGATION_CREDENTIAL_ROTATION_REQUIRED' | 'DELEGATION_CREDENTIAL_SECRET_ROTATED' | 'DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED';
+/**
+ * The payload format Cal.com sends to the subscriber.
+ *
+ * Enumerated by the API: posting an unknown value returns "version must be one of the following
+ * values: 2021-10-20, 2026-07-27". Distinct from the `cal-api-version` header, which the webhook
+ * endpoints do not use at all.
+ */
+export type CalcomWebhookVersion = '2021-10-20' | '2026-07-27';
+/**
+ * All {@link CalcomWebhookVersion} values, oldest first.
+ */
+export declare const ALL_CALCOM_WEBHOOK_VERSIONS: readonly CalcomWebhookVersion[];
+/**
+ * The unit a {@link CalcomWebhookTimeOffset} is counted in.
+ *
+ * Enumerated by the API: posting an unknown value returns "timeUnit must be one of the following
+ * values: DAY, HOUR, MINUTE". These are UPPERCASE and unrelated to the lowercase `@dereekb/util`
+ * {@link TimeUnit} strings — map between them with {@link CALCOM_WEBHOOK_TIME_UNIT_TIME_UNIT_MAP}.
+ */
+export type CalcomWebhookTimeUnit = 'MINUTE' | 'HOUR' | 'DAY';
+/**
+ * All {@link CalcomWebhookTimeUnit} values, smallest first.
+ */
+export declare const ALL_CALCOM_WEBHOOK_TIME_UNITS: readonly CalcomWebhookTimeUnit[];
+/**
+ * Maps each {@link CalcomWebhookTimeUnit} to the equivalent `@dereekb/util` {@link TimeUnit}.
+ */
+export declare const CALCOM_WEBHOOK_TIME_UNIT_TIME_UNIT_MAP: Readonly<Record<CalcomWebhookTimeUnit, TimeUnit>>;
+/**
+ * How many {@link CalcomWebhookTimeUnit} units after the booking start the trigger is evaluated.
+ *
+ * A whole number of at least 1 — the API rejects 0 with "time must not be less than 1".
+ */
+export type CalcomWebhookTimeAmount = number;
+/**
+ * How long after the booking start a {@link CalcomWebhookTimeRelativeTrigger} is evaluated.
+ *
+ * Carried on the wire as the sibling `time` + `timeUnit` fields; convert to a `@dereekb/util`
+ * {@link TimeDuration} with {@link calcomWebhookTimeOffsetToTimeDuration} to do arithmetic on it.
+ */
+export interface CalcomWebhookTimeOffset {
+    readonly time: CalcomWebhookTimeAmount;
+    readonly timeUnit: CalcomWebhookTimeUnit;
+}
+/**
+ * Either both halves of a {@link CalcomWebhookTimeOffset}, or neither.
+ *
+ * The API does not enforce the pairing itself — it accepts a `time` with no `timeUnit` and then
+ * has no unit to apply it in — so this input type is what keeps a caller from sending half of one.
+ */
+export type CalcomWebhookTimeOffsetInput = CalcomWebhookTimeOffset | {
+    readonly time?: never;
+    readonly timeUnit?: never;
+};
 export interface CalcomWebhook {
     readonly id: CalcomWebhookId;
     readonly subscriberUrl: WebsiteUrl;
     readonly triggers: CalcomWebhookTrigger[];
     readonly active: boolean;
-    readonly payloadTemplate?: Maybe<string>;
-    readonly secret?: Maybe<string>;
+    readonly payloadTemplate: Maybe<string>;
+    readonly secret: Maybe<string>;
+    readonly userId: Maybe<CalcomUserId>;
+    readonly version: Maybe<CalcomWebhookVersion>;
+    /**
+     * The magnitude of the webhook's {@link CalcomWebhookTimeOffset}, null unless it subscribes to a
+     * {@link CalcomWebhookTimeRelativeTrigger}. Read both halves together with
+     * {@link calcomWebhookTimeOffsetFromWebhook}.
+     */
+    readonly time: Maybe<CalcomWebhookTimeAmount>;
+    readonly timeUnit: Maybe<CalcomWebhookTimeUnit>;
+    /**
+     * Returned when reading a webhook, but not on the create response.
+     */
+    readonly createdAt?: Maybe<ISO8601DateString>;
+    readonly teamId?: Maybe<CalcomId>;
+    readonly eventTypeId?: Maybe<CalcomEventTypeId>;
+    readonly appId?: Maybe<string>;
+    readonly platform?: Maybe<boolean>;
+    readonly oAuthClientId?: Maybe<string>;
 }
-export interface CalcomCreateWebhookInput {
+export interface CalcomCreateWebhookInputBase {
     readonly subscriberUrl: WebsiteUrl;
     readonly triggers: CalcomWebhookTrigger[];
-    readonly active?: boolean;
+    /**
+     * Required: a create with no `active` is rejected with "active must be a boolean value".
+     */
+    readonly active: boolean;
     readonly payloadTemplate?: string;
     readonly secret?: string;
+    readonly version?: CalcomWebhookVersion;
 }
-export interface CalcomUpdateWebhookInput {
+export type CalcomCreateWebhookInput = CalcomCreateWebhookInputBase & CalcomWebhookTimeOffsetInput;
+export interface CalcomUpdateWebhookInputBase {
     readonly subscriberUrl?: WebsiteUrl;
     readonly triggers?: CalcomWebhookTrigger[];
     readonly active?: boolean;
     readonly payloadTemplate?: string;
     readonly secret?: string;
+    readonly version?: CalcomWebhookVersion;
 }
+export type CalcomUpdateWebhookInput = CalcomUpdateWebhookInputBase & CalcomWebhookTimeOffsetInput;
 export interface CalcomWebhookResponse {
     readonly status: CalcomResponseStatus;
     readonly data: CalcomWebhook;
@@ -32,6 +126,33 @@ export interface CalcomGetWebhooksResponse {
     readonly status: CalcomResponseStatus;
     readonly data: CalcomWebhook[];
 }
+/**
+ * Converts a Cal.com webhook time offset to a `@dereekb/util` {@link TimeDuration}, so the
+ * duration utilities (`timeDurationToMilliseconds()`, `convertTimeDuration()`, ...) apply to it.
+ *
+ * @param offset - The webhook time offset to convert.
+ * @returns The equivalent TimeDuration.
+ *
+ * @example
+ * ```ts
+ * timeDurationToMilliseconds(calcomWebhookTimeOffsetToTimeDuration({ time: 5, timeUnit: 'MINUTE' })); // 300000
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calcomWebhookTimeOffsetToTimeDuration(offset: CalcomWebhookTimeOffset): TimeDuration;
+/**
+ * Reads a webhook's {@link CalcomWebhookTimeOffset} out of the sibling `time`/`timeUnit` fields.
+ *
+ * Returns undefined unless both halves are present, as the API returns them null on a webhook
+ * with no {@link CalcomWebhookTimeRelativeTrigger} and a magnitude with no unit means nothing.
+ *
+ * @param webhook - The webhook to read the offset from.
+ * @returns The webhook's time offset, or undefined when it has none.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calcomWebhookTimeOffsetFromWebhook(webhook: Pick<CalcomWebhook, 'time' | 'timeUnit'>): Maybe<CalcomWebhookTimeOffset>;
 /**
  * Creates a webhook subscription for the authenticated user. Webhooks notify your app
  * when specified events occur (e.g., bookings created, cancelled, rescheduled).

package/src/lib/calcom/calcom.error.api.d.ts

@@ -1,6 +1,32 @@
+import { type Maybe } from '@dereekb/util';
 import { type FetchResponseError } from '@dereekb/util/fetch';
-import { type CalcomServerErrorData, type ParsedCalcomServerError } from '../calcom.error.api';
+import { type CalcomServerErrorCode, type CalcomServerErrorData, type ParsedCalcomServerError } from '../calcom.error.api';
 export declare const logCalcomErrorToConsole: import("..").LogCalcomServerErrorFunction;
+/**
+ * The error envelope returned by the Cal.com v2 API.
+ *
+ * The code and message are nested under `error` — they are NOT top-level fields on the body.
+ */
+export interface CalcomApiErrorResponseBody {
+    readonly status?: Maybe<string>;
+    readonly timestamp?: Maybe<string>;
+    readonly path?: Maybe<string>;
+    readonly error?: Maybe<{
+        readonly code?: Maybe<CalcomServerErrorCode>;
+        readonly message?: Maybe<string>;
+        readonly details?: Maybe<unknown>;
+    }>;
+}
+/**
+ * Flattens a Cal.com API error response body into {@link CalcomServerErrorData}.
+ *
+ * Reads the nested `error` envelope when present, and otherwise treats the body as already
+ * flat — so an endpoint that returns a bare error object still yields its code and message.
+ *
+ * @param body - The parsed error response body.
+ * @returns The flattened error data.
+ */
+export declare function calcomServerErrorDataFromApiErrorResponseBody(body: CalcomApiErrorResponseBody): CalcomServerErrorData;
 /**
  * Parses a FetchResponseError from a Cal.com API call into a typed CalcomServerError.
  * Attempts to extract JSON error data from the response body.

package/src/lib/calcom.type.d.ts

@@ -1,3 +1,4 @@
+import { type Count, type PageNumber } from '@dereekb/util';
 /**
  * A numeric identifier in Cal.com.
  */
@@ -20,8 +21,11 @@ export type CalcomBookingId = number;
 export type CalcomScheduleId = number;
 /**
  * Cal.com webhook identifier.
+ *
+ * A UUID string (e.g. `"7c3b0811-8a5a-4754-8b31-9f594559f98e"`), unlike the numeric ids used
+ * elsewhere in the API.
  */
-export type CalcomWebhookId = number;
+export type CalcomWebhookId = string;
 /**
  * Cal.com credential identifier, used to reference connected calendar credentials.
  */
@@ -55,11 +59,6 @@ export type CalcomOrganizationSlug = string;
  * (e.g., "google_calendar", "outlook_calendar", "apple_calendar").
  */
 export type CalcomCalendarIntegration = string;
-/**
- * Cal.com webhook event type string
- * (e.g., "BOOKING_CREATED", "BOOKING_CANCELLED").
- */
-export type CalcomWebhookEventTypeString = string;
 /**
  * Cal.com API response status string (e.g., "success", "error").
  */
@@ -68,3 +67,19 @@ export type CalcomResponseStatus = 'success' | 'error';
  * Cal.com booking status string.
  */
 export type CalcomBookingStatus = 'accepted' | 'pending' | 'cancelled' | 'rejected';
+/**
+ * The pagination envelope a paginated Cal.com list response carries beside its `data`.
+ *
+ * `currentPage`/`totalPages` are 1-based, and are derived from the `take`/`skip` of the request
+ * rather than being a cursor.
+ */
+export interface CalcomPagination {
+    readonly returnedItems: Count;
+    readonly totalItems: Count;
+    readonly itemsPerPage: Count;
+    readonly remainingItems: Count;
+    readonly currentPage: PageNumber;
+    readonly totalPages: Count;
+    readonly hasNextPage: boolean;
+    readonly hasPreviousPage: boolean;
+}