@dereekb/calcom 13.35.0 → 13.37.0

package/nestjs/index.cjs.js

@@ -1454,6 +1454,16 @@ exports.CalcomApi = __decorate([
                 return calcom.getBooking(this.context);
             }
         },
+        {
+            key: "getBookings",
+            get: /**
+     * Configured pass-through for {@link getBookings}.
+     *
+     * @returns Function to retrieve a page of bookings.
+     */ function get() {
+                return calcom.getBookings(this.context);
+            }
+        },
         {
             key: "cancelBooking",
             get: /**
@@ -1526,6 +1536,16 @@ exports.CalcomApi = __decorate([
                 return calcom.getBusyTimes(this.context);
             }
         },
+        {
+            key: "getBusyTimesForConnectedCalendars",
+            get: /**
+     * Configured pass-through for {@link getBusyTimesForConnectedCalendars}.
+     *
+     * @returns Function to retrieve busy times without having to resolve `calendarsToLoad` first.
+     */ function get() {
+                return calcom.getBusyTimesForConnectedCalendars(this.context);
+            }
+        },
         {
             key: "createWebhook",
             get: // MARK: Webhooks
@@ -1654,7 +1674,6 @@ function _unsupported_iterable_to_array$1(o, minLen) {
 var CALCOM_WEBHOOK_BOOKING_CREATED = 'BOOKING_CREATED';
 var CALCOM_WEBHOOK_BOOKING_CANCELLED = 'BOOKING_CANCELLED';
 var CALCOM_WEBHOOK_BOOKING_RESCHEDULED = 'BOOKING_RESCHEDULED';
-var CALCOM_WEBHOOK_BOOKING_CONFIRMED = 'BOOKING_CONFIRMED';
 
 function _define_property$3(obj, key, value) {
     if (key in obj) {
@@ -1724,8 +1743,7 @@ var calcomEventHandlerConfigurerFactory = util.handlerConfigurerFactory({
         var configurer = _object_spread_props(_object_spread({}, accessor), {
             handleBookingCreated: fnWithKey(CALCOM_WEBHOOK_BOOKING_CREATED),
             handleBookingCancelled: fnWithKey(CALCOM_WEBHOOK_BOOKING_CANCELLED),
-            handleBookingRescheduled: fnWithKey(CALCOM_WEBHOOK_BOOKING_RESCHEDULED),
-            handleBookingConfirmed: fnWithKey(CALCOM_WEBHOOK_BOOKING_CONFIRMED)
+            handleBookingRescheduled: fnWithKey(CALCOM_WEBHOOK_BOOKING_RESCHEDULED)
         });
         return configurer;
     }
@@ -2378,7 +2396,6 @@ exports.CALCOM_REFRESH_TOKEN_CONFIG_KEY = CALCOM_REFRESH_TOKEN_CONFIG_KEY;
 exports.CALCOM_SERVER_TOKEN_FILE_KEY = CALCOM_SERVER_TOKEN_FILE_KEY;
 exports.CALCOM_SERVICE_NAME = CALCOM_SERVICE_NAME;
 exports.CALCOM_WEBHOOK_BOOKING_CANCELLED = CALCOM_WEBHOOK_BOOKING_CANCELLED;
-exports.CALCOM_WEBHOOK_BOOKING_CONFIRMED = CALCOM_WEBHOOK_BOOKING_CONFIRMED;
 exports.CALCOM_WEBHOOK_BOOKING_CREATED = CALCOM_WEBHOOK_BOOKING_CREATED;
 exports.CALCOM_WEBHOOK_BOOKING_RESCHEDULED = CALCOM_WEBHOOK_BOOKING_RESCHEDULED;
 exports.CALCOM_WEBHOOK_SECRET_CONFIG_KEY = CALCOM_WEBHOOK_SECRET_CONFIG_KEY;

package/nestjs/index.esm.js

@@ -1,5 +1,5 @@
 import { Logger, Injectable, Inject, Post, Res, Req, Controller, Module } from '@nestjs/common';
-import { calcomOAuthFactory, calcomAuthCredentialFromValues, exchangeAuthorizationCode, calcomAccessTokenFromTokenResponse, calcomFactory, getMe, getSchedules, createBooking, getBooking, cancelBooking, getEventTypes, createEventType, updateEventType, deleteEventType, getCalendars, getBusyTimes, createWebhook, getWebhooks, getWebhook, updateWebhook, deleteWebhook, getAvailableSlots } from '@dereekb/calcom';
+import { calcomOAuthFactory, calcomAuthCredentialFromValues, exchangeAuthorizationCode, calcomAccessTokenFromTokenResponse, calcomFactory, getMe, getSchedules, createBooking, getBooking, getBookings, cancelBooking, getEventTypes, createEventType, updateEventType, deleteEventType, getCalendars, getBusyTimes, getBusyTimesForConnectedCalendars, createWebhook, getWebhooks, getWebhook, updateWebhook, deleteWebhook, getAvailableSlots } from '@dereekb/calcom';
 import { inMemoryAsyncValueCache, inMemoryAsyncKeyedValueCache, mergeAsyncValueCaches, isExpired, filterMaybeArrayValues, cachedGetter, handlerFactory, handlerConfigurerFactory, handlerMappedSetFunctionFactory } from '@dereekb/util';
 import { createMemoizedJsonFileAsyncValueCache, RawBody } from '@dereekb/nestjs';
 import { createHash, createHmac } from 'node:crypto';
@@ -1452,6 +1452,16 @@ CalcomApi = __decorate([
                 return getBooking(this.context);
             }
         },
+        {
+            key: "getBookings",
+            get: /**
+     * Configured pass-through for {@link getBookings}.
+     *
+     * @returns Function to retrieve a page of bookings.
+     */ function get() {
+                return getBookings(this.context);
+            }
+        },
         {
             key: "cancelBooking",
             get: /**
@@ -1524,6 +1534,16 @@ CalcomApi = __decorate([
                 return getBusyTimes(this.context);
             }
         },
+        {
+            key: "getBusyTimesForConnectedCalendars",
+            get: /**
+     * Configured pass-through for {@link getBusyTimesForConnectedCalendars}.
+     *
+     * @returns Function to retrieve busy times without having to resolve `calendarsToLoad` first.
+     */ function get() {
+                return getBusyTimesForConnectedCalendars(this.context);
+            }
+        },
         {
             key: "createWebhook",
             get: // MARK: Webhooks
@@ -1652,7 +1672,6 @@ function _unsupported_iterable_to_array$1(o, minLen) {
 var CALCOM_WEBHOOK_BOOKING_CREATED = 'BOOKING_CREATED';
 var CALCOM_WEBHOOK_BOOKING_CANCELLED = 'BOOKING_CANCELLED';
 var CALCOM_WEBHOOK_BOOKING_RESCHEDULED = 'BOOKING_RESCHEDULED';
-var CALCOM_WEBHOOK_BOOKING_CONFIRMED = 'BOOKING_CONFIRMED';
 
 function _define_property$3(obj, key, value) {
     if (key in obj) {
@@ -1722,8 +1741,7 @@ var calcomEventHandlerConfigurerFactory = handlerConfigurerFactory({
         var configurer = _object_spread_props(_object_spread({}, accessor), {
             handleBookingCreated: fnWithKey(CALCOM_WEBHOOK_BOOKING_CREATED),
             handleBookingCancelled: fnWithKey(CALCOM_WEBHOOK_BOOKING_CANCELLED),
-            handleBookingRescheduled: fnWithKey(CALCOM_WEBHOOK_BOOKING_RESCHEDULED),
-            handleBookingConfirmed: fnWithKey(CALCOM_WEBHOOK_BOOKING_CONFIRMED)
+            handleBookingRescheduled: fnWithKey(CALCOM_WEBHOOK_BOOKING_RESCHEDULED)
         });
         return configurer;
     }
@@ -2369,4 +2387,4 @@ CalcomWebhookModule = __decorate([
     };
 }
 
-export { CALCOM_API_KEY_CONFIG_KEY, CALCOM_CLIENT_ID_CONFIG_KEY, CALCOM_CLIENT_SECRET_CONFIG_KEY, CALCOM_REFRESH_TOKEN_CONFIG_KEY, CALCOM_SERVER_TOKEN_FILE_KEY, CALCOM_SERVICE_NAME, CALCOM_WEBHOOK_BOOKING_CANCELLED, CALCOM_WEBHOOK_BOOKING_CONFIRMED, CALCOM_WEBHOOK_BOOKING_CREATED, CALCOM_WEBHOOK_BOOKING_RESCHEDULED, CALCOM_WEBHOOK_SECRET_CONFIG_KEY, CalcomApi, CalcomApiContextInstance, CalcomOAuthAccessTokenCacheService, CalcomOAuthApi, CalcomOAuthServiceConfig, CalcomServiceConfig, CalcomWebhookController, CalcomWebhookModule, CalcomWebhookService, CalcomWebhookServiceConfig, DEFAULT_FILE_CALCOM_ACCESS_TOKEN_CACHE_DIR, appCalcomModuleMetadata, appCalcomOAuthModuleMetadata, appCalcomWebhookModuleMetadata, calcomAccessTokenCacheFileKey, calcomEventHandlerConfigurerFactory, calcomEventHandlerFactory, calcomOAuthServiceConfigFactory, calcomRefreshTokenCacheKey, calcomServiceConfigFactory, calcomWebhookEvent, calcomWebhookEventVerifier, calcomWebhookServiceConfigFactory, fileCalcomOAuthAccessTokenCacheService, logMergeCalcomOAuthAccessTokenCacheServiceErrorFunction, memoryCalcomOAuthAccessTokenCacheService, mergeCalcomOAuthAccessTokenCacheServices };
+export { CALCOM_API_KEY_CONFIG_KEY, CALCOM_CLIENT_ID_CONFIG_KEY, CALCOM_CLIENT_SECRET_CONFIG_KEY, CALCOM_REFRESH_TOKEN_CONFIG_KEY, CALCOM_SERVER_TOKEN_FILE_KEY, CALCOM_SERVICE_NAME, CALCOM_WEBHOOK_BOOKING_CANCELLED, CALCOM_WEBHOOK_BOOKING_CREATED, CALCOM_WEBHOOK_BOOKING_RESCHEDULED, CALCOM_WEBHOOK_SECRET_CONFIG_KEY, CalcomApi, CalcomApiContextInstance, CalcomOAuthAccessTokenCacheService, CalcomOAuthApi, CalcomOAuthServiceConfig, CalcomServiceConfig, CalcomWebhookController, CalcomWebhookModule, CalcomWebhookService, CalcomWebhookServiceConfig, DEFAULT_FILE_CALCOM_ACCESS_TOKEN_CACHE_DIR, appCalcomModuleMetadata, appCalcomOAuthModuleMetadata, appCalcomWebhookModuleMetadata, calcomAccessTokenCacheFileKey, calcomEventHandlerConfigurerFactory, calcomEventHandlerFactory, calcomOAuthServiceConfigFactory, calcomRefreshTokenCacheKey, calcomServiceConfigFactory, calcomWebhookEvent, calcomWebhookEventVerifier, calcomWebhookServiceConfigFactory, fileCalcomOAuthAccessTokenCacheService, logMergeCalcomOAuthAccessTokenCacheServiceErrorFunction, memoryCalcomOAuthAccessTokenCacheService, mergeCalcomOAuthAccessTokenCacheServices };

package/nestjs/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/calcom/nestjs",
-  "version": "13.35.0",
+  "version": "13.37.0",
   "peerDependencies": {
-    "@dereekb/nestjs": "13.35.0",
-    "@dereekb/rxjs": "13.35.0",
-    "@dereekb/util": "13.35.0",
-    "@dereekb/calcom": "13.35.0",
+    "@dereekb/nestjs": "13.37.0",
+    "@dereekb/rxjs": "13.37.0",
+    "@dereekb/util": "13.37.0",
+    "@dereekb/calcom": "13.37.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1"

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

@@ -132,6 +132,12 @@ export declare class CalcomApiContextInstance {
      * @returns Function to retrieve a booking by UID.
      */
     get getBooking(): (uid: import("@dereekb/calcom").CalcomBookingUid) => Promise<import("@dereekb/calcom").CalcomGetBookingResponse>;
+    /**
+     * Configured pass-through for {@link getBookings}.
+     *
+     * @returns Function to retrieve a page of bookings.
+     */
+    get getBookings(): (input?: import("@dereekb/util").Maybe<import("@dereekb/calcom").CalcomGetBookingsInput>) => Promise<import("@dereekb/calcom").CalcomGetBookingsResponse>;
     /**
      * Configured pass-through for {@link cancelBooking}.
      *
@@ -174,6 +180,12 @@ export declare class CalcomApiContextInstance {
      * @returns Function to retrieve busy time ranges across connected calendars.
      */
     get getBusyTimes(): (input: import("@dereekb/calcom").CalcomGetBusyTimesInput) => Promise<import("@dereekb/calcom").CalcomGetBusyTimesResponse>;
+    /**
+     * Configured pass-through for {@link getBusyTimesForConnectedCalendars}.
+     *
+     * @returns Function to retrieve busy times without having to resolve `calendarsToLoad` first.
+     */
+    get getBusyTimesForConnectedCalendars(): (input: import("@dereekb/calcom").CalcomGetBusyTimesForConnectedCalendarsInput) => Promise<import("@dereekb/calcom").CalcomGetBusyTimesResponse>;
     /**
      * Configured pass-through for {@link createWebhook}.
      *

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

@@ -14,6 +14,5 @@ export interface CalcomEventHandlerConfigurer extends HandlerBindAccessor<Untype
     handleBookingCreated: CalcomHandlerMappedSetFunction<CalcomWebhookBookingPayload>;
     handleBookingCancelled: CalcomHandlerMappedSetFunction<CalcomWebhookBookingPayload>;
     handleBookingRescheduled: CalcomHandlerMappedSetFunction<CalcomWebhookBookingPayload>;
-    handleBookingConfirmed: CalcomHandlerMappedSetFunction<CalcomWebhookBookingPayload>;
 }
 export declare const calcomEventHandlerConfigurerFactory: import("@dereekb/util").HandlerConfigurerFactory<CalcomEventHandlerConfigurer, UntypedCalcomWebhookEvent, string, boolean>;

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

@@ -1,11 +1,21 @@
-import { type EmailAddress, type ISO8601DateString, type TimezoneString } from '@dereekb/util';
-import { type CalcomBookingId, type CalcomBookingUid, type CalcomBookingStatus } from '@dereekb/calcom';
+import { type EmailAddress, type ISO8601DateString, type SuggestedString, type TimezoneString } from '@dereekb/util';
+import { type CalcomBookingId, type CalcomBookingUid, type CalcomBookingStatus, type CalcomWebhookTrigger } from '@dereekb/calcom';
 export declare const CALCOM_WEBHOOK_BOOKING_CREATED = "BOOKING_CREATED";
 export declare const CALCOM_WEBHOOK_BOOKING_CANCELLED = "BOOKING_CANCELLED";
 export declare const CALCOM_WEBHOOK_BOOKING_RESCHEDULED = "BOOKING_RESCHEDULED";
-export declare const CALCOM_WEBHOOK_BOOKING_CONFIRMED = "BOOKING_CONFIRMED";
-export type CalcomWebhookEventType = typeof CALCOM_WEBHOOK_BOOKING_CREATED | typeof CALCOM_WEBHOOK_BOOKING_CANCELLED | typeof CALCOM_WEBHOOK_BOOKING_RESCHEDULED | typeof CALCOM_WEBHOOK_BOOKING_CONFIRMED | string;
-export interface CalcomWebhookEvent<T, ET extends string = string> {
+/**
+ * The `triggerEvent` of an inbound webhook payload.
+ *
+ * Deliberately open-ended: this is a value Cal.com sends US, so a trigger added upstream — or one
+ * enabled on a subscription that predates this package — has to keep parsing rather than fail to
+ * type. {@link CalcomWebhookTrigger} is the set the API actually accepts on a subscription, and is
+ * what autocompletes here.
+ *
+ * Note there is no `BOOKING_CONFIRMED` trigger, despite this package once declaring one: a booking
+ * awaiting confirmation arrives as `BOOKING_REQUESTED` and its acceptance as `BOOKING_CREATED`.
+ */
+export type CalcomWebhookEventType = SuggestedString<CalcomWebhookTrigger>;
+export interface CalcomWebhookEvent<T, ET extends CalcomWebhookEventType = CalcomWebhookEventType> {
     readonly triggerEvent: ET;
     readonly createdAt: ISO8601DateString;
     readonly payload: T;
@@ -21,6 +31,17 @@ export interface CalcomWebhookBookingOrganizer {
     readonly name: string;
     readonly timeZone: TimezoneString;
 }
+/**
+ * The booking as Cal.com POSTs it to a webhook subscriber.
+ *
+ * Deliberately NOT the same shape as the REST {@link CalcomBooking}: the webhook payload mirrors
+ * Cal.com's internal booking model and uses `startTime`/`endTime`, while `GET /v2/bookings/{uid}`
+ * returns `start`/`end`. Do not "align" these two out of a belief that they drifted — they are
+ * different surfaces.
+ *
+ * NOTE: unlike the REST types in this package, this shape has not been verified against a live
+ * payload (that requires a publicly reachable subscriber). Treat it as unconfirmed.
+ */
 export interface CalcomWebhookBookingPayload {
     readonly id: CalcomBookingId;
     readonly uid: CalcomBookingUid;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/calcom",
-  "version": "13.35.0",
+  "version": "13.37.0",
   "exports": {
     "./nestjs": {
       "module": "./nestjs/index.esm.js",
@@ -17,9 +17,9 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/nestjs": "13.35.0",
-    "@dereekb/rxjs": "13.35.0",
-    "@dereekb/util": "13.35.0",
+    "@dereekb/nestjs": "13.37.0",
+    "@dereekb/rxjs": "13.37.0",
+    "@dereekb/util": "13.37.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

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

@@ -1,10 +1,28 @@
-import { type EmailAddress, type ISO8601DateString, type Maybe, type Minutes, type TimezoneString } from '@dereekb/util';
+import { type Count, type EmailAddress, type ISO8601DateString, type Maybe, type Minutes, type SortingOrder, type TimezoneString, type WebsiteUrl } from '@dereekb/util';
 import { type CalcomContext } from './calcom.config';
-import { type CalcomBookingId, type CalcomBookingUid, type CalcomBookingStatus, type CalcomEventTypeId, type CalcomResponseStatus } from '../calcom.type';
+import { type CalcomBookingId, type CalcomBookingUid, type CalcomBookingStatus, type CalcomEventTypeId, type CalcomEventTypeSlug, type CalcomPagination, type CalcomResponseStatus, type CalcomUserId, type CalcomUsername } from '../calcom.type';
 export interface CalcomBookingAttendee {
     readonly name: string;
     readonly email: EmailAddress;
+    readonly displayEmail: Maybe<EmailAddress>;
     readonly timeZone: TimezoneString;
+    readonly language: string;
+    readonly absent: boolean;
+}
+export interface CalcomBookingHost {
+    readonly id: CalcomUserId;
+    readonly name: string;
+    readonly email: EmailAddress;
+    readonly displayEmail: Maybe<EmailAddress>;
+    readonly username: CalcomUsername;
+    readonly timeZone: TimezoneString;
+}
+/**
+ * The event type a booking was made against, as embedded on the booking itself.
+ */
+export interface CalcomBookingEventType {
+    readonly id: CalcomEventTypeId;
+    readonly slug: CalcomEventTypeSlug;
 }
 export interface CalcomCreateBookingInput {
     readonly start: ISO8601DateString;
@@ -15,6 +33,13 @@ export interface CalcomCreateBookingInput {
         readonly timeZone: TimezoneString;
     };
     readonly metadata?: Maybe<Record<string, unknown>>;
+    /**
+     * Only valid when the target event type declares `lengthInMinutesOptions`.
+     *
+     * Sending it to an event type with a single fixed length is rejected with "Can't specify
+     * 'lengthInMinutes' because event type does not have multiple possible lengths", so leave it
+     * unset unless the event type is explicitly multi-length.
+     */
     readonly lengthInMinutes?: Maybe<Minutes>;
     readonly guests?: Maybe<string[]>;
 }
@@ -22,11 +47,34 @@ export interface CalcomBooking {
     readonly id: CalcomBookingId;
     readonly uid: CalcomBookingUid;
     readonly title: string;
+    readonly description: string;
     readonly status: CalcomBookingStatus;
-    readonly startTime: ISO8601DateString;
-    readonly endTime: ISO8601DateString;
+    /**
+     * The start of the booking. Note the API returns `start`/`end`, NOT `startTime`/`endTime`.
+     */
+    readonly start: ISO8601DateString;
+    readonly end: ISO8601DateString;
+    readonly duration: Minutes;
+    readonly eventTypeId: CalcomEventTypeId;
+    readonly eventType: CalcomBookingEventType;
+    readonly hosts: CalcomBookingHost[];
     readonly attendees: CalcomBookingAttendee[];
+    readonly guests: EmailAddress[];
+    /**
+     * The join url Cal.com supplies for the meeting, when the location is a conferencing app.
+     */
+    readonly meetingUrl: Maybe<WebsiteUrl>;
+    readonly location: Maybe<string>;
+    readonly absentHost: boolean;
+    readonly cancellationReason: Maybe<string>;
+    readonly cancelledByEmail: Maybe<EmailAddress>;
+    readonly rescheduledByEmail: Maybe<EmailAddress>;
+    readonly icsUid: string;
+    readonly rating: Maybe<number>;
     readonly metadata: Record<string, unknown>;
+    readonly bookingFieldsResponses: Record<string, unknown>;
+    readonly createdAt: ISO8601DateString;
+    readonly updatedAt: ISO8601DateString;
 }
 export interface CalcomCreateBookingResponse {
     readonly status: CalcomResponseStatus;
@@ -36,6 +84,40 @@ export interface CalcomGetBookingResponse {
     readonly status: CalcomResponseStatus;
     readonly data: CalcomBooking;
 }
+/**
+ * How {@link getBookings} filters by status.
+ *
+ * Note this is a filter over the booking's position in time as well as its state, and is NOT the
+ * {@link CalcomBookingStatus} carried on a booking: passing an unknown value is rejected with
+ * "Invalid status. Allowed are upcoming, recurring, past, cancelled, unconfirmed".
+ */
+export type CalcomBookingsFilterStatus = 'upcoming' | 'recurring' | 'past' | 'cancelled' | 'unconfirmed';
+export interface CalcomGetBookingsInput {
+    /**
+     * The number of bookings to return. The endpoint applies its own default (10) when unset.
+     */
+    readonly take?: Maybe<Count>;
+    readonly skip?: Maybe<Count>;
+    readonly status?: Maybe<CalcomBookingsFilterStatus>;
+    readonly eventTypeId?: Maybe<CalcomEventTypeId>;
+    readonly attendeeEmail?: Maybe<EmailAddress>;
+    /**
+     * Only bookings that start at or after this instant.
+     */
+    readonly afterStart?: Maybe<ISO8601DateString>;
+    /**
+     * Only bookings that end at or before this instant.
+     */
+    readonly beforeEnd?: Maybe<ISO8601DateString>;
+    readonly sortStart?: Maybe<SortingOrder>;
+    readonly sortEnd?: Maybe<SortingOrder>;
+    readonly sortCreated?: Maybe<SortingOrder>;
+}
+export interface CalcomGetBookingsResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomBooking[];
+    readonly pagination: CalcomPagination;
+}
 export interface CalcomCancelBookingInput {
     readonly uid: CalcomBookingUid;
     readonly cancellationReason?: Maybe<string>;
@@ -66,6 +148,24 @@ export interface CalcomCancelBookingResponse {
  * @__NO_SIDE_EFFECTS__
  */
 export declare function createBooking(context: CalcomContext): (input: CalcomCreateBookingInput) => Promise<CalcomCreateBookingResponse>;
+/**
+ * Retrieves the bookings visible to the authenticated user, newest page first.
+ *
+ * Paginated: read {@link CalcomGetBookingsResponse.pagination} rather than assuming `data` holds
+ * everything, as the endpoint caps a page even with no `take`.
+ *
+ * @param context - The Cal.com API context providing authentication and fetch capabilities.
+ * @returns Retrieves a page of bookings for the given input.
+ *
+ * @see https://cal.com/docs/api-reference/v2/bookings/get-all-bookings
+ *
+ * @example
+ * ```ts
+ * const response = await getBookings(context)({ take: 10, status: 'upcoming', sortStart: 'asc' });
+ * console.log(response.pagination.totalItems, response.data.map(b => b.uid));
+ * ```
+ */
+export declare function getBookings(context: CalcomContext): (input?: Maybe<CalcomGetBookingsInput>) => Promise<CalcomGetBookingsResponse>;
 /**
  * Retrieves a booking by its unique UID.
  *

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

@@ -1,4 +1,4 @@
-import { type EmailAddress, type ISO8601DateString, type Maybe } from '@dereekb/util';
+import { type EmailAddress, type ISO8601DateString, type ISO8601DayString, type Maybe, type TimezoneString, type WebsiteUrl } from '@dereekb/util';
 import { type CalcomContext } from './calcom.config';
 import { type CalcomId, type CalcomCredentialId, type CalcomCalendarIntegration, type CalcomUserId, type CalcomEventTypeId, type CalcomResponseStatus } from '../calcom.type';
 export interface CalcomCalendar {
@@ -7,15 +7,58 @@ export interface CalcomCalendar {
     readonly name: string;
     readonly readOnly: boolean;
     readonly email: EmailAddress;
+    /**
+     * Whether Cal.com checks this calendar for conflicts.
+     *
+     * This is the flag to filter on when loading busy times; it is independent of {@link primary},
+     * and an account commonly has a selected calendar that is not its primary one.
+     */
     readonly isSelected: boolean;
+    /**
+     * Whether this is the primary calendar of the connection. Null on non-primary calendars.
+     */
+    readonly primary: Maybe<boolean>;
     readonly credentialId: CalcomCredentialId;
+    readonly delegationCredentialId: Maybe<CalcomId>;
+}
+/**
+ * App metadata describing the integration behind a connected calendar.
+ *
+ * Note this is an OBJECT, distinct from the {@link CalcomCalendarIntegration} string
+ * (e.g. `"google_calendar"`) carried on each individual {@link CalcomCalendar}.
+ */
+export interface CalcomCalendarIntegrationApp {
+    readonly name: string;
+    readonly type: CalcomCalendarIntegration;
+    readonly title: string;
+    readonly slug: string;
+    readonly description: string;
+    readonly variant: string;
+    readonly category: string;
+    readonly categories: string[];
+    readonly logo: string;
+    readonly publisher: string;
+    readonly url: WebsiteUrl;
+    readonly email: EmailAddress;
+    readonly installed: boolean;
+    readonly isOAuth: boolean;
+    readonly dirName: Maybe<string>;
+    readonly locationOption: Maybe<unknown>;
+    readonly appData: Maybe<unknown>;
+    readonly delegationCredential: Maybe<unknown>;
 }
 export interface CalcomConnectedCalendar {
-    readonly integration: CalcomCalendarIntegration;
+    readonly integration: CalcomCalendarIntegrationApp;
     readonly credentialId: CalcomCredentialId;
-    readonly primary: {
-        readonly calendars: CalcomCalendar[];
-    };
+    readonly delegationCredentialId: Maybe<CalcomId>;
+    /**
+     * The primary calendar of this connection, as a single calendar.
+     */
+    readonly primary: Maybe<CalcomCalendar>;
+    /**
+     * Every calendar available on this connection, as a sibling of {@link primary}.
+     */
+    readonly calendars: CalcomCalendar[];
 }
 export interface CalcomDestinationCalendar {
     readonly id: CalcomId;
@@ -27,9 +70,12 @@ export interface CalcomDestinationCalendar {
     readonly email: EmailAddress;
     readonly isSelected: boolean;
     readonly credentialId: CalcomCredentialId;
+    readonly delegationCredentialId: Maybe<CalcomId>;
     readonly userId: CalcomUserId;
     readonly eventTypeId: Maybe<CalcomEventTypeId>;
     readonly integrationTitle: string;
+    readonly createdAt: ISO8601DateString;
+    readonly updatedAt: ISO8601DateString;
 }
 export interface CalcomGetCalendarsResponseData {
     readonly connectedCalendars: CalcomConnectedCalendar[];
@@ -39,11 +85,46 @@ export interface CalcomGetCalendarsResponse {
     readonly status: CalcomResponseStatus;
     readonly data: CalcomGetCalendarsResponseData;
 }
-export interface CalcomGetBusyTimesInput {
-    readonly dateFrom: ISO8601DateString;
-    readonly dateTo: ISO8601DateString;
-    readonly calendarsToLoad?: Maybe<string[]>;
+/**
+ * Addresses a single calendar to load busy times from.
+ *
+ * Both halves are required: the endpoint matches a calendar by its external id within a
+ * specific credential, and rejects the request when either is missing.
+ */
+export interface CalcomCalendarToLoad {
+    readonly credentialId: CalcomCredentialId;
+    readonly externalId: string;
+}
+export interface CalcomGetBusyTimesInputBase {
+    /**
+     * Accepts either a plain day (`2026-08-01`) or a full ISO instant.
+     */
+    readonly dateFrom: ISO8601DateString | ISO8601DayString;
+    readonly dateTo: ISO8601DateString | ISO8601DayString;
+    /**
+     * The calendars to load, obtained from {@link getCalendars}.
+     *
+     * Encoded as an indexed object array (`calendarsToLoad[0][credentialId]=…`); the endpoint
+     * rejects any scalar form with "calendarsToLoad must be an array".
+     */
+    readonly calendarsToLoad: CalcomCalendarToLoad[];
 }
+/**
+ * The endpoint rejects a request carrying neither timezone with
+ * "Either timeZone or loggedInUsersTz must be provided", so at least one is required.
+ */
+export type CalcomGetBusyTimesTimezoneInput = {
+    readonly timeZone: TimezoneString;
+    readonly loggedInUsersTz?: Maybe<TimezoneString>;
+} | {
+    readonly timeZone?: Maybe<TimezoneString>;
+    readonly loggedInUsersTz: TimezoneString;
+};
+export type CalcomGetBusyTimesInput = CalcomGetBusyTimesInputBase & CalcomGetBusyTimesTimezoneInput;
+/**
+ * Input for {@link getBusyTimesForConnectedCalendars}, which derives `calendarsToLoad` itself.
+ */
+export type CalcomGetBusyTimesForConnectedCalendarsInput = Omit<CalcomGetBusyTimesInputBase, 'calendarsToLoad'> & CalcomGetBusyTimesTimezoneInput;
 export interface CalcomBusyTime {
     readonly start: ISO8601DateString;
     readonly end: ISO8601DateString;
@@ -64,12 +145,25 @@ export interface CalcomGetBusyTimesResponse {
  * @example
  * ```ts
  * const response = await getCalendars(context)();
- * response.data.connectedCalendars.forEach(cc => console.log(cc.integration));
+ * response.data.connectedCalendars.forEach(cc => console.log(cc.integration.slug, cc.calendars.length));
  * ```
  */
 export declare function getCalendars(context: CalcomContext): () => Promise<CalcomGetCalendarsResponse>;
 /**
- * Retrieves busy time ranges across the user's connected calendars for a given date range.
+ * Selects the calendars to load busy times from, out of a set of connected calendars.
+ *
+ * Prefers the calendars Cal.com is configured to check for conflicts (`isSelected`), and falls
+ * back to a connection's primary calendar when that connection has nothing selected.
+ *
+ * @param connectedCalendars - The connected calendars to select from.
+ * @returns The calendars to load.
+ */
+export declare function calcomCalendarsToLoadFromConnectedCalendars(connectedCalendars: CalcomConnectedCalendar[]): CalcomCalendarToLoad[];
+/**
+ * Retrieves busy time ranges across the given calendars for a date range.
+ *
+ * A caller cannot address this endpoint without first knowing its calendars, so this is the
+ * single-request primitive — see {@link getBusyTimesForConnectedCalendars} to resolve them too.
  *
  * @param context - The Cal.com API context providing authentication and fetch capabilities.
  * @returns Retrieves busy time ranges for a date range.
@@ -80,9 +174,31 @@ export declare function getCalendars(context: CalcomContext): () => Promise<Calc
  * ```ts
  * const response = await getBusyTimes(context)({
  *   dateFrom: '2026-03-17',
- *   dateTo: '2026-03-24'
+ *   dateTo: '2026-03-24',
+ *   timeZone: 'America/Chicago',
+ *   calendarsToLoad: [{ credentialId: 1845764, externalId: 'someone@example.com' }]
  * });
  * response.data.forEach(bt => console.log(bt.start, bt.end));
  * ```
  */
 export declare function getBusyTimes(context: CalcomContext): (input: CalcomGetBusyTimesInput) => Promise<CalcomGetBusyTimesResponse>;
+/**
+ * Retrieves busy time ranges across the user's connected calendars for a date range.
+ *
+ * Convenience over {@link getBusyTimes}: loads the connected calendars first and derives
+ * `calendarsToLoad` via {@link calcomCalendarsToLoadFromConnectedCalendars}, so a caller does not
+ * have to know Cal.com's `isSelected`/primary selection rule. Issues two requests.
+ *
+ * @param context - The Cal.com API context providing authentication and fetch capabilities.
+ * @returns Retrieves busy time ranges across the user's connected calendars.
+ *
+ * @example
+ * ```ts
+ * const response = await getBusyTimesForConnectedCalendars(context)({
+ *   dateFrom: '2026-03-17',
+ *   dateTo: '2026-03-24',
+ *   loggedInUsersTz: 'UTC'
+ * });
+ * ```
+ */
+export declare function getBusyTimesForConnectedCalendars(context: CalcomContext): (input: CalcomGetBusyTimesForConnectedCalendarsInput) => Promise<CalcomGetBusyTimesResponse>;