@dereekb/calcom 13.4.0

package/nestjs/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@dereekb/calcom/nestjs",
+  "version": "13.4.0",
+  "peerDependencies": {
+    "@dereekb/nestjs": "13.4.0",
+    "@dereekb/util": "13.4.0",
+    "@dereekb/calcom": "13.4.0",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/config": "^4.0.3",
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/testing": "^11.1.14",
+    "date-fns": "^4.0.0"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/nestjs/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

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

@@ -0,0 +1,160 @@
+import { CalcomServiceConfig } from './calcom.config';
+import { type Calcom, type CalcomContext, type CalcomServerContext, type CalcomUserContext, type CalcomUserContextFactoryInput } from '@dereekb/calcom';
+import { CalcomOAuthApi } from '../oauth';
+/**
+ * Injectable NestJS service that provides access to the Cal.com API.
+ *
+ * Use {@link serverContextInstance} to access API functions via the server context,
+ * or {@link makeUserContextInstance} to create per-mentor API instances.
+ *
+ * @example
+ * ```ts
+ * // Server context (API key or server OAuth)
+ * const instance = calcomApi.serverContextInstance;
+ * const me = await instance.getMe();
+ *
+ * // Per-mentor context
+ * const mentorInstance = calcomApi.makeUserContextInstance({ refreshToken: mentor.calcomRefreshToken });
+ * const eventTypes = await mentorInstance.getEventTypes();
+ *
+ * // Public slot query (no auth)
+ * const slots = await calcomApi.getAvailableSlots({ start: '...', end: '...', eventTypeId: 123 });
+ * ```
+ */
+export declare class CalcomApi {
+    readonly config: CalcomServiceConfig;
+    readonly calcomOAuthApi: CalcomOAuthApi;
+    readonly calcom: Calcom;
+    private readonly _serverInstance;
+    private readonly _publicContext;
+    get calcomServerContext(): CalcomServerContext;
+    constructor(config: CalcomServiceConfig, calcomOAuthApi: CalcomOAuthApi);
+    /**
+     * Returns the cached {@link CalcomApiContextInstance} for the server context.
+     * All API functions are available through this instance.
+     */
+    get serverContextInstance(): CalcomApiContextInstance;
+    /** Configured pass-through for {@link getAvailableSlots} using the public (unauthenticated) context. */
+    get getAvailableSlots(): (input: import("@dereekb/calcom").CalcomGetAvailableSlotsInput) => Promise<import("@dereekb/calcom").CalcomGetAvailableSlotsResponse>;
+    /**
+     * Creates a {@link CalcomApiContextInstance} for a specific user using their OAuth refresh token.
+     * The returned instance has all API functions scoped to that user's account.
+     *
+     * When no explicit `accessTokenCache` is provided, a per-user cache is automatically
+     * resolved from the cache service using an md5 hash of the refresh token as the key.
+     * This ensures tokens persist across requests and server restarts without collisions.
+     *
+     * @example
+     * ```ts
+     * // Automatic per-user caching (recommended):
+     * const userInstance = calcomApi.makeUserContextInstance({
+     *   refreshToken: user.calcomRefreshToken
+     * });
+     *
+     * // With explicit cache override:
+     * const userInstance = calcomApi.makeUserContextInstance({
+     *   refreshToken: user.calcomRefreshToken,
+     *   accessTokenCache: customCache
+     * });
+     * ```
+     */
+    makeUserContextInstance(input: CalcomUserContextFactoryInput): CalcomApiContextInstance;
+    /**
+     * Creates a {@link CalcomApiContextInstance} from any {@link CalcomContext}.
+     */
+    makeContextInstance(context: CalcomContext): CalcomApiContextInstance;
+    /**
+     * Creates a raw {@link CalcomUserContext} from a refresh token, without wrapping in a {@link CalcomApiContextInstance}.
+     * Prefer {@link makeUserContextInstance} unless you need direct context access.
+     */
+    makeUserContext(input: CalcomUserContextFactoryInput): CalcomUserContext;
+}
+/**
+ * Wraps a {@link CalcomContext} (server or user) and exposes all authenticated Cal.com API
+ * functions bound to that context. Each getter delegates to the corresponding function
+ * from `@dereekb/calcom`.
+ *
+ * Access the parent {@link CalcomApi} via {@link calcomApi} for public endpoints
+ * (e.g., `calcomApi.getAvailableSlots`) or to create additional context instances.
+ *
+ * @example
+ * ```ts
+ * const instance = calcomApi.serverContextInstance;
+ *
+ * // Authenticated API calls
+ * const me = await instance.getMe();
+ * const schedules = await instance.getSchedules();
+ *
+ * // Access public endpoints via parent
+ * const slots = await instance.calcomApi.getAvailableSlots({ start: '...', end: '...', eventTypeId: 123 });
+ * ```
+ */
+export declare class CalcomApiContextInstance {
+    readonly calcomApi: CalcomApi;
+    readonly context: CalcomContext;
+    constructor(calcomApi: CalcomApi, context: CalcomContext);
+    /**
+     * Configured pass-through for {@link getMe}.
+     */
+    get getMe(): () => Promise<import("@dereekb/calcom").CalcomGetMeResponse>;
+    /**
+     * Configured pass-through for {@link getSchedules}.
+     */
+    get getSchedules(): () => Promise<import("@dereekb/calcom").CalcomGetSchedulesResponse>;
+    /**
+     * Configured pass-through for {@link createBooking}.
+     */
+    get createBooking(): (input: import("@dereekb/calcom").CalcomCreateBookingInput) => Promise<import("@dereekb/calcom").CalcomCreateBookingResponse>;
+    /**
+     * Configured pass-through for {@link getBooking}.
+     */
+    get getBooking(): (uid: import("@dereekb/calcom").CalcomBookingUid) => Promise<import("@dereekb/calcom").CalcomGetBookingResponse>;
+    /**
+     * Configured pass-through for {@link cancelBooking}.
+     */
+    get cancelBooking(): (input: import("@dereekb/calcom").CalcomCancelBookingInput) => Promise<import("@dereekb/calcom").CalcomCancelBookingResponse>;
+    /**
+     * Configured pass-through for {@link getEventTypes}.
+     */
+    get getEventTypes(): () => Promise<import("@dereekb/calcom").CalcomGetEventTypesResponse>;
+    /**
+     * Configured pass-through for {@link createEventType}.
+     */
+    get createEventType(): (input: import("@dereekb/calcom").CalcomCreateEventTypeInput) => Promise<import("@dereekb/calcom").CalcomEventTypeResponse>;
+    /**
+     * Configured pass-through for {@link updateEventType}.
+     */
+    get updateEventType(): (eventTypeId: import("@dereekb/calcom").CalcomEventTypeId, input: import("@dereekb/calcom").CalcomUpdateEventTypeInput) => Promise<import("@dereekb/calcom").CalcomEventTypeResponse>;
+    /**
+     * Configured pass-through for {@link deleteEventType}.
+     */
+    get deleteEventType(): (eventTypeId: import("@dereekb/calcom").CalcomEventTypeId) => Promise<import("@dereekb/calcom").CalcomEventTypeResponse>;
+    /**
+     * Configured pass-through for {@link getCalendars}.
+     */
+    get getCalendars(): () => Promise<import("@dereekb/calcom").CalcomGetCalendarsResponse>;
+    /**
+     * Configured pass-through for {@link getBusyTimes}.
+     */
+    get getBusyTimes(): (input: import("@dereekb/calcom").CalcomGetBusyTimesInput) => Promise<import("@dereekb/calcom").CalcomGetBusyTimesResponse>;
+    /**
+     * Configured pass-through for {@link createWebhook}.
+     */
+    get createWebhook(): (input: import("@dereekb/calcom").CalcomCreateWebhookInput) => Promise<import("@dereekb/calcom").CalcomWebhookResponse>;
+    /**
+     * Configured pass-through for {@link getWebhooks}.
+     */
+    get getWebhooks(): () => Promise<import("@dereekb/calcom").CalcomGetWebhooksResponse>;
+    /**
+     * Configured pass-through for {@link getWebhook}.
+     */
+    get getWebhook(): (webhookId: import("@dereekb/calcom").CalcomWebhookId) => Promise<import("@dereekb/calcom").CalcomWebhookResponse>;
+    /**
+     * Configured pass-through for {@link updateWebhook}.
+     */
+    get updateWebhook(): (webhookId: import("@dereekb/calcom").CalcomWebhookId, input: import("@dereekb/calcom").CalcomUpdateWebhookInput) => Promise<import("@dereekb/calcom").CalcomWebhookResponse>;
+    /**
+     * Configured pass-through for {@link deleteWebhook}.
+     */
+    get deleteWebhook(): (webhookId: import("@dereekb/calcom").CalcomWebhookId) => Promise<import("@dereekb/calcom").CalcomWebhookResponse>;
+}

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

@@ -0,0 +1,10 @@
+import { type CalcomConfig, type CalcomFactoryConfig } from '@dereekb/calcom';
+export type CalcomServiceApiConfig = CalcomConfig & {};
+/**
+ * Configuration for CalcomService
+ */
+export declare abstract class CalcomServiceConfig {
+    readonly calcom: CalcomServiceApiConfig;
+    readonly factoryConfig?: CalcomFactoryConfig;
+    static assertValidConfig(_config: CalcomServiceConfig): void;
+}

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

@@ -0,0 +1,18 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { CalcomServiceConfig } from './calcom.config';
+import { type Maybe } from '@dereekb/util';
+export declare function calcomServiceConfigFactory(_configService: ConfigService): CalcomServiceConfig;
+export interface ProvideAppCalcomMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * The CalcomModule requires the following dependencies in order to initialize properly:
+     * - CalcomOAuthApi
+     *
+     * This module declaration makes it easier to import a module that exports those dependencies.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's CalcomModule.
+ */
+export declare function appCalcomModuleMetadata(config: ProvideAppCalcomMetadataConfig): ModuleMetadata;

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

@@ -0,0 +1,3 @@
+export * from './calcom.api';
+export * from './calcom.config';
+export * from './calcom.module';

package/nestjs/src/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './oauth';
+export * from './calcom';
+export * from './webhook';

package/nestjs/src/lib/oauth/index.d.ts

@@ -0,0 +1,4 @@
+export * from './oauth.api';
+export * from './oauth.config';
+export * from './oauth.module';
+export * from './oauth.service';

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

@@ -0,0 +1,25 @@
+import { type CalcomAccessTokenCache, type CalcomOAuth, type CalcomOAuthContext, type CalcomRefreshToken } from '@dereekb/calcom';
+import { type Maybe } from '@dereekb/util';
+import { CalcomOAuthServiceConfig } from './oauth.config';
+import { CalcomOAuthAccessTokenCacheService } from './oauth.service';
+export declare class CalcomOAuthApi {
+    readonly config: CalcomOAuthServiceConfig;
+    readonly cacheService: CalcomOAuthAccessTokenCacheService;
+    readonly calcomOAuth: CalcomOAuth;
+    get oauthContext(): CalcomOAuthContext;
+    constructor(config: CalcomOAuthServiceConfig, cacheService: CalcomOAuthAccessTokenCacheService);
+    /** Configured pass-through for {@link exchangeAuthorizationCode}. */
+    get exchangeAuthorizationCode(): (input: import("@dereekb/calcom").CalcomOAuthExchangeAuthorizationCodeInput) => Promise<import("@dereekb/calcom").CalcomOAuthTokenResponse>;
+    /**
+     * Retrieves an access token for a specific user using their refresh token.
+     */
+    userAccessToken(input: {
+        refreshToken: string;
+        userAccessTokenCache?: Maybe<CalcomAccessTokenCache>;
+    }): Promise<import("@dereekb/calcom").CalcomAccessToken>;
+    /**
+     * Returns a per-user CalcomAccessTokenCache derived from the refresh token (md5 hashed as the file key).
+     * Returns undefined if the cache service does not support per-user caching.
+     */
+    cacheForRefreshToken(refreshToken: CalcomRefreshToken): Maybe<CalcomAccessTokenCache>;
+}

package/nestjs/src/lib/oauth/oauth.config.d.ts

@@ -0,0 +1,22 @@
+import { type CalcomOAuthFactoryConfig } from '@dereekb/calcom';
+import { type ConfigService } from '@nestjs/config';
+export declare const CALCOM_SERVICE_NAME = "calcom";
+export declare const CALCOM_CLIENT_ID_CONFIG_KEY = "CALCOM_CLIENT_ID";
+export declare const CALCOM_CLIENT_SECRET_CONFIG_KEY = "CALCOM_CLIENT_SECRET";
+export declare const CALCOM_REFRESH_TOKEN_CONFIG_KEY = "CALCOM_REFRESH_TOKEN";
+export declare const CALCOM_API_KEY_CONFIG_KEY = "CALCOM_API_KEY";
+export interface CalcomOAuthServiceApiConfig {
+    readonly clientId?: string;
+    readonly clientSecret?: string;
+    readonly refreshToken?: string;
+    readonly apiKey?: string;
+}
+/**
+ * Configuration for CalcomOAuthService
+ */
+export declare abstract class CalcomOAuthServiceConfig {
+    readonly calcomOAuth: CalcomOAuthServiceApiConfig;
+    readonly factoryConfig?: CalcomOAuthFactoryConfig;
+    static assertValidConfig(config: CalcomOAuthServiceConfig): void;
+}
+export declare function calcomOAuthServiceConfigFactory(configService: ConfigService): CalcomOAuthServiceConfig;

package/nestjs/src/lib/oauth/oauth.module.d.ts

@@ -0,0 +1,24 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { CalcomOAuthServiceConfig } from './oauth.config';
+import { type Maybe } from '@dereekb/util';
+export type CalcomOAuthServiceConfigFactory = (configService: ConfigService) => CalcomOAuthServiceConfig;
+export interface ProvideAppCalcomOAuthMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * The CalcomOAuthModule requires the following dependencies in order to initialize properly:
+     * - CalcomOAuthAccessTokenCacheService
+     *
+     * This module declaration makes it easier to import a module that exports those dependencies.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+    /**
+     * Optional override for the CalcomOAuthServiceConfigFactory.
+     *
+     * @default calcomOAuthServiceConfigFactory
+     */
+    readonly calcomOAuthServiceConfigFactory?: CalcomOAuthServiceConfigFactory;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's CalcomOAuthModule.
+ */
+export declare function appCalcomOAuthModuleMetadata(config: ProvideAppCalcomOAuthMetadataConfig): ModuleMetadata;

package/nestjs/src/lib/oauth/oauth.service.d.ts

@@ -0,0 +1,66 @@
+import { type CalcomAccessToken, type CalcomAccessTokenCache, type CalcomRefreshToken } from '@dereekb/calcom';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Service used for retrieving CalcomAccessTokenCache for Cal.com services.
+ *
+ * Implementations store and retrieve OAuth access tokens (and the rotated refresh tokens
+ * embedded in them). The service supports both a server-level cache and per-user caches
+ * keyed by the user's initial refresh token.
+ */
+export declare abstract class CalcomOAuthAccessTokenCacheService {
+    /**
+     * Loads the server-level CalcomAccessTokenCache.
+     */
+    abstract loadCalcomAccessTokenCache(): CalcomAccessTokenCache;
+    /**
+     * Creates or retrieves a cache for a specific user context, keyed by the refresh token.
+     *
+     * The refresh token is hashed to derive a stable cache key. Even though Cal.com
+     * rotates refresh tokens, the cache instance persists the updated token in-place,
+     * so subsequent reads return the latest token regardless of rotation.
+     */
+    abstract cacheForRefreshToken?(refreshToken: CalcomRefreshToken): CalcomAccessTokenCache;
+}
+export type CalcomOAuthAccessTokenCacheServiceWithRefreshToken = Required<CalcomOAuthAccessTokenCacheService>;
+/**
+ * Derives a short, filesystem-safe cache key from a refresh token using md5.
+ */
+export declare function calcomRefreshTokenCacheKey(refreshToken: string): string;
+export type LogMergeCalcomOAuthAccessTokenCacheServiceErrorFunction = (failedUpdates: (readonly [CalcomAccessTokenCache, unknown])[]) => void;
+export declare function logMergeCalcomOAuthAccessTokenCacheServiceErrorFunction(failedUpdates: (readonly [CalcomAccessTokenCache, unknown])[]): void;
+/**
+ * Merges the input services in order to use some as a backup source.
+ *
+ * If one source fails retrieval, the next will be tried.
+ * When updating a cached token, it will update the token across all services.
+ *
+ * @param inputServicesToMerge Must include at least one service. Empty arrays will throw an error.
+ */
+export declare function mergeCalcomOAuthAccessTokenCacheServices(inputServicesToMerge: CalcomOAuthAccessTokenCacheService[], logError?: Maybe<boolean | LogMergeCalcomOAuthAccessTokenCacheServiceErrorFunction>): CalcomOAuthAccessTokenCacheService;
+/**
+ * Creates a CalcomOAuthAccessTokenCacheService that uses in-memory storage.
+ * Per-user caches are stored in a Map keyed by the md5 hash of the refresh token.
+ */
+export declare function memoryCalcomOAuthAccessTokenCacheService(existingToken?: Maybe<CalcomAccessToken>, logAccessToConsole?: boolean): CalcomOAuthAccessTokenCacheService;
+export declare const DEFAULT_FILE_CALCOM_ACCESS_TOKEN_CACHE_DIR = ".tmp/calcom-tokens";
+export declare const CALCOM_SERVER_TOKEN_FILE_KEY = "server";
+export type CalcomOAuthAccessTokenCacheFileContent = {
+    readonly token?: Maybe<CalcomAccessToken>;
+};
+export interface FileSystemCalcomOAuthAccessTokenCacheService extends CalcomOAuthAccessTokenCacheService {
+    readonly cacheDir: string;
+}
+/**
+ * Creates a CalcomOAuthAccessTokenCacheService that reads and writes access tokens
+ * to the file system. Each user gets their own file, keyed by an md5 hash of their refresh token.
+ *
+ * File structure:
+ * ```
+ * <cacheDir>/
+ *   server.json              — server-level token
+ *   user-<md5hash>.json      — per-user tokens (hash of initial refresh token)
+ * ```
+ *
+ * @param cacheDir Directory to store token files. Defaults to `.tmp/calcom-tokens`.
+ */
+export declare function fileCalcomOAuthAccessTokenCacheService(cacheDir?: string): FileSystemCalcomOAuthAccessTokenCacheService;

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

@@ -0,0 +1,7 @@
+export * from './webhook.calcom';
+export * from './webhook.calcom.config';
+export * from './webhook.calcom.controller';
+export * from './webhook.calcom.module';
+export * from './webhook.calcom.service';
+export * from './webhook.calcom.type';
+export * from './webhook.calcom.verify';

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

@@ -0,0 +1,11 @@
+export declare const CALCOM_WEBHOOK_SECRET_CONFIG_KEY = "CALCOM_WEBHOOK_SECRET";
+export interface CalcomWebhookConfig {
+    readonly webhookSecret: string;
+}
+/**
+ * Configuration for CalcomWebhookService
+ */
+export declare abstract class CalcomWebhookServiceConfig {
+    readonly webhookConfig: CalcomWebhookConfig;
+    static assertValidConfig(config: CalcomWebhookServiceConfig): void;
+}

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

@@ -0,0 +1,8 @@
+import { type RawBodyBuffer } from '@dereekb/nestjs';
+import { type Request, type Response } from 'express';
+import { CalcomWebhookService } from './webhook.calcom.service';
+export declare class CalcomWebhookController {
+    readonly calcomWebhookService: CalcomWebhookService;
+    constructor(calcomWebhookService: CalcomWebhookService);
+    handleCalcomWebhook(res: Response, req: Request, rawBody: RawBodyBuffer): Promise<void>;
+}

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

@@ -0,0 +1,16 @@
+import { type HandlerBindAccessor, type HandlerMappedSetFunction, type Handler } from '@dereekb/util';
+import { type CalcomWebhookEventType, type UntypedCalcomWebhookEvent, type CalcomWebhookEvent, type CalcomWebhookBookingPayload } from './webhook.calcom.type';
+/**
+ * Creates a CalcomWebhookEvent and treats the data as the input type.
+ */
+export declare function calcomWebhookEvent<T>(event: UntypedCalcomWebhookEvent): CalcomWebhookEvent<T>;
+export type CalcomEventHandler = Handler<UntypedCalcomWebhookEvent, CalcomWebhookEventType>;
+export declare const calcomEventHandlerFactory: import("@dereekb/util").HandlerFactory<UntypedCalcomWebhookEvent, string, boolean>;
+export type CalcomHandlerMappedSetFunction<T> = HandlerMappedSetFunction<CalcomWebhookEvent<T>>;
+export interface CalcomEventHandlerConfigurer extends HandlerBindAccessor<UntypedCalcomWebhookEvent, CalcomWebhookEventType> {
+    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.module.d.ts

@@ -0,0 +1,20 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { CalcomWebhookServiceConfig } from './webhook.calcom.config';
+import { type Maybe } from '@dereekb/util';
+export declare function calcomWebhookServiceConfigFactory(configService: ConfigService): CalcomWebhookServiceConfig;
+/**
+ * Configures webhooks for the service.
+ */
+export declare class CalcomWebhookModule {
+}
+export interface ProvideAppCalcomWebhookMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Optional dependency module that provides required services.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's CalcomWebhookModule.
+ */
+export declare function appCalcomWebhookModuleMetadata(config: ProvideAppCalcomWebhookMetadataConfig): ModuleMetadata;

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

@@ -0,0 +1,21 @@
+import { type Request } from 'express';
+import { type Handler } from '@dereekb/util';
+import { CalcomWebhookServiceConfig } from './webhook.calcom.config';
+import { type UntypedCalcomWebhookEvent } from './webhook.calcom.type';
+export interface CalcomUpdateForWebhookResponse {
+    readonly valid: boolean;
+    readonly handled: boolean;
+    readonly event: UntypedCalcomWebhookEvent;
+}
+/**
+ * Service that makes system changes based on Cal.com webhook events.
+ */
+export declare class CalcomWebhookService {
+    private readonly logger;
+    private readonly _verifier;
+    readonly handler: Handler<UntypedCalcomWebhookEvent>;
+    readonly configure: import("@dereekb/util").HandlerConfigurer<import("./webhook.calcom").CalcomEventHandlerConfigurer, UntypedCalcomWebhookEvent, string, boolean>;
+    constructor(config: CalcomWebhookServiceConfig);
+    updateForWebhook(req: Request, rawBody: Buffer): Promise<CalcomUpdateForWebhookResponse>;
+    updateForCalcomEvent(event: UntypedCalcomWebhookEvent): Promise<boolean>;
+}

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

@@ -0,0 +1,33 @@
+import { type EmailAddress, type ISO8601DateString, type TimezoneString } from '@dereekb/util';
+import { type CalcomBookingId, type CalcomBookingUid, type CalcomBookingStatus } 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> {
+    readonly triggerEvent: ET;
+    readonly createdAt: ISO8601DateString;
+    readonly payload: T;
+}
+export type UntypedCalcomWebhookEvent = CalcomWebhookEvent<any>;
+export interface CalcomWebhookBookingAttendee {
+    readonly email: EmailAddress;
+    readonly name: string;
+    readonly timeZone: TimezoneString;
+}
+export interface CalcomWebhookBookingOrganizer {
+    readonly email: EmailAddress;
+    readonly name: string;
+    readonly timeZone: TimezoneString;
+}
+export interface CalcomWebhookBookingPayload {
+    readonly id: CalcomBookingId;
+    readonly uid: CalcomBookingUid;
+    readonly title: string;
+    readonly startTime: ISO8601DateString;
+    readonly endTime: ISO8601DateString;
+    readonly status: CalcomBookingStatus;
+    readonly attendees: readonly CalcomWebhookBookingAttendee[];
+    readonly organizer: CalcomWebhookBookingOrganizer;
+}

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

@@ -0,0 +1,16 @@
+import { type UntypedCalcomWebhookEvent } from './webhook.calcom.type';
+export interface CalcomWebhookEventVerificationResult {
+    readonly valid: boolean;
+    readonly event: UntypedCalcomWebhookEvent;
+}
+/**
+ * Function that verifies a Cal.com webhook event.
+ */
+export type CalcomWebhookEventVerifier = (rawBody: Buffer, headers: Record<string, string>) => CalcomWebhookEventVerificationResult;
+/**
+ * Verifies a Cal.com webhook event using HMAC-SHA256 signature.
+ *
+ * @param secret The webhook signing secret.
+ * @returns A function that verifies a Cal.com webhook event.
+ */
+export declare function calcomWebhookEventVerifier(secret: string): CalcomWebhookEventVerifier;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@dereekb/calcom",
+  "version": "13.4.0",
+  "exports": {
+    "./nestjs": {
+      "module": "./nestjs/index.esm.js",
+      "types": "./nestjs/index.d.ts",
+      "import": "./nestjs/index.cjs.mjs",
+      "default": "./nestjs/index.cjs.js"
+    },
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "peerDependencies": {
+    "@dereekb/nestjs": "13.4.0",
+    "@dereekb/util": "13.4.0",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/config": "^4.0.3",
+    "express": "^5.0.0",
+    "make-error": "^1.3.0"
+  },
+  "devDependencies": {
+    "@nestjs/testing": "^11.1.14",
+    "date-fns": "^4.0.0"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

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

@@ -0,0 +1,86 @@
+import { type EmailAddress, type ISO8601DateString, type Maybe, type Minutes, type TimezoneString } from '@dereekb/util';
+import { type CalcomContext } from './calcom.config';
+import { type CalcomBookingId, type CalcomBookingUid, type CalcomBookingStatus, type CalcomEventTypeId, type CalcomResponseStatus } from '../calcom.type';
+export interface CalcomBookingAttendee {
+    readonly name: string;
+    readonly email: EmailAddress;
+    readonly timeZone: TimezoneString;
+}
+export interface CalcomCreateBookingInput {
+    readonly start: ISO8601DateString;
+    readonly eventTypeId: CalcomEventTypeId;
+    readonly attendee: {
+        readonly name: string;
+        readonly email: EmailAddress;
+        readonly timeZone: TimezoneString;
+    };
+    readonly metadata?: Maybe<Record<string, unknown>>;
+    readonly lengthInMinutes?: Maybe<Minutes>;
+    readonly guests?: Maybe<string[]>;
+}
+export interface CalcomBooking {
+    readonly id: CalcomBookingId;
+    readonly uid: CalcomBookingUid;
+    readonly title: string;
+    readonly status: CalcomBookingStatus;
+    readonly startTime: ISO8601DateString;
+    readonly endTime: ISO8601DateString;
+    readonly attendees: CalcomBookingAttendee[];
+    readonly metadata: Record<string, unknown>;
+}
+export interface CalcomCreateBookingResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomBooking;
+}
+export interface CalcomGetBookingResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomBooking;
+}
+export interface CalcomCancelBookingInput {
+    readonly uid: CalcomBookingUid;
+    readonly cancellationReason?: Maybe<string>;
+}
+export interface CalcomCancelBookingResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomBooking;
+}
+/**
+ * Creates a new booking for the specified event type. The `attendee` represents the person
+ * booking (the client), not the host. This endpoint can be called without authentication.
+ *
+ * @see https://cal.com/docs/api-reference/v2/bookings/create-a-booking
+ *
+ * @example
+ * ```ts
+ * const response = await createBooking(context)({
+ *   start: '2026-03-20T14:00:00.000Z',
+ *   eventTypeId: 12345,
+ *   attendee: { name: 'Jane Doe', email: 'jane@example.com', timeZone: 'America/New_York' }
+ * });
+ * console.log(response.data.uid);
+ * ```
+ */
+export declare function createBooking(context: CalcomContext): (input: CalcomCreateBookingInput) => Promise<CalcomCreateBookingResponse>;
+/**
+ * Retrieves a booking by its unique UID.
+ *
+ * @see https://cal.com/docs/api-reference/v2/bookings/get-a-booking
+ *
+ * @example
+ * ```ts
+ * const response = await getBooking(context)('abc-123-uid');
+ * console.log(response.data.title, response.data.status);
+ * ```
+ */
+export declare function getBooking(context: CalcomContext): (uid: CalcomBookingUid) => Promise<CalcomGetBookingResponse>;
+/**
+ * Cancels a booking by its unique UID, with an optional cancellation reason.
+ *
+ * @see https://cal.com/docs/api-reference/v2/bookings/cancel-a-booking
+ *
+ * @example
+ * ```ts
+ * await cancelBooking(context)({ uid: 'abc-123-uid', cancellationReason: 'Schedule conflict' });
+ * ```
+ */
+export declare function cancelBooking(context: CalcomContext): (input: CalcomCancelBookingInput) => Promise<CalcomCancelBookingResponse>;