@dereekb/calcom 13.4.0 → 13.4.2

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

@@ -2,6 +2,12 @@ import { type ModuleMetadata } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { CalcomWebhookServiceConfig } from './webhook.calcom.config';
 import { type Maybe } from '@dereekb/util';
+/**
+ * Factory function that creates a {@link CalcomWebhookServiceConfig} from NestJS ConfigService environment variables.
+ *
+ * @param configService - the NestJS ConfigService instance
+ * @returns a validated CalcomWebhookServiceConfig
+ */
 export declare function calcomWebhookServiceConfigFactory(configService: ConfigService): CalcomWebhookServiceConfig;
 /**
  * Configures webhooks for the service.
@@ -16,5 +22,8 @@ export interface ProvideAppCalcomWebhookMetadataConfig extends Pick<ModuleMetada
 }
 /**
  * Convenience function used to generate ModuleMetadata for an app's CalcomWebhookModule.
+ *
+ * @param config - the module metadata configuration including optional dependency module
+ * @returns NestJS ModuleMetadata for registering the CalcomWebhookModule
  */
 export declare function appCalcomWebhookModuleMetadata(config: ProvideAppCalcomWebhookMetadataConfig): ModuleMetadata;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/calcom",
-  "version": "13.4.0",
+  "version": "13.4.2",
   "exports": {
     "./nestjs": {
       "module": "./nestjs/index.esm.js",
@@ -17,8 +17,8 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/nestjs": "13.4.0",
-    "@dereekb/util": "13.4.0",
+    "@dereekb/nestjs": "13.4.2",
+    "@dereekb/util": "13.4.2",
     "@nestjs/common": "^11.1.16",
     "@nestjs/config": "^4.0.3",
     "express": "^5.0.0",

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

@@ -50,6 +50,9 @@ export interface CalcomCancelBookingResponse {
  *
  * @see https://cal.com/docs/api-reference/v2/bookings/create-a-booking
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that creates a booking from the given input
+ *
  * @example
  * ```ts
  * const response = await createBooking(context)({
@@ -66,6 +69,9 @@ export declare function createBooking(context: CalcomContext): (input: CalcomCre
  *
  * @see https://cal.com/docs/api-reference/v2/bookings/get-a-booking
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that retrieves a booking by its UID
+ *
  * @example
  * ```ts
  * const response = await getBooking(context)('abc-123-uid');
@@ -78,6 +84,9 @@ export declare function getBooking(context: CalcomContext): (uid: CalcomBookingU
  *
  * @see https://cal.com/docs/api-reference/v2/bookings/cancel-a-booking
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that cancels a booking by UID
+ *
  * @example
  * ```ts
  * await cancelBooking(context)({ uid: 'abc-123-uid', cancellationReason: 'Schedule conflict' });

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

@@ -58,6 +58,9 @@ export interface CalcomGetBusyTimesResponse {
  *
  * @see https://cal.com/docs/api-reference/v2/calendars/get-all-calendars
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that retrieves all connected calendars
+ *
  * @example
  * ```ts
  * const response = await getCalendars(context)();
@@ -70,6 +73,9 @@ export declare function getCalendars(context: CalcomContext): () => Promise<Calc
  *
  * @see https://cal.com/docs/api-reference/v2/calendars/get-busy-times
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that retrieves busy time ranges for a date range
+ *
  * @example
  * ```ts
  * const response = await getBusyTimes(context)({

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

@@ -38,6 +38,9 @@ export interface CalcomUpdateEventTypeInput {
  *
  * @see https://cal.com/docs/api-reference/v2/event-types/get-all-event-types
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that retrieves all event types
+ *
  * @example
  * ```ts
  * const response = await getEventTypes(context)();
@@ -50,6 +53,9 @@ export declare function getEventTypes(context: CalcomContext): () => Promise<Cal
  *
  * @see https://cal.com/docs/api-reference/v2/event-types/create-an-event-type
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that creates a new event type from the given input
+ *
  * @example
  * ```ts
  * const response = await createEventType(context)({
@@ -66,6 +72,9 @@ export declare function createEventType(context: CalcomContext): (input: CalcomC
  *
  * @see https://cal.com/docs/api-reference/v2/event-types/update-an-event-type
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that updates an event type by ID
+ *
  * @example
  * ```ts
  * await updateEventType(context)(12345, { title: 'Updated Session Title' });
@@ -77,6 +86,9 @@ export declare function updateEventType(context: CalcomContext): (eventTypeId: C
  *
  * @see https://cal.com/docs/api-reference/v2/event-types/delete-an-event-type
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that deletes an event type by ID
+ *
  * @example
  * ```ts
  * await deleteEventType(context)(12345);

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

@@ -23,6 +23,9 @@ export interface CalcomGetSchedulesResponse {
  *
  * @see https://cal.com/docs/api-reference/v2/schedules/get-all-schedules
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that retrieves all schedules
+ *
  * @example
  * ```ts
  * const response = await getSchedules(context)();

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

@@ -30,6 +30,9 @@ export interface CalcomGetAvailableSlotsResponse {
  *
  * @see https://cal.com/docs/api-reference/v2/slots/get-available-time-slots-for-an-event-type
  *
+ * @param context - the Cal.com API context (authenticated or public)
+ * @returns a function that queries available slots for the given input
+ *
  * @example
  * ```ts
  * const response = await getAvailableSlots(context)({

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

@@ -20,6 +20,9 @@ export interface CalcomGetMeResponse {
  *
  * @see https://cal.com/docs/api-reference/v2/me
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that retrieves the authenticated user's profile
+ *
  * @example
  * ```ts
  * const response = await getMe(context)();

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

@@ -38,6 +38,9 @@ export interface CalcomGetWebhooksResponse {
  *
  * @see https://cal.com/docs/api-reference/v2/webhooks/create-a-webhook
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that creates a webhook subscription from the given input
+ *
  * @example
  * ```ts
  * const response = await createWebhook(context)({
@@ -54,6 +57,9 @@ export declare function createWebhook(context: CalcomContext): (input: CalcomCre
  *
  * @see https://cal.com/docs/api-reference/v2/webhooks/get-all-webhooks
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that retrieves all webhooks
+ *
  * @example
  * ```ts
  * const response = await getWebhooks(context)();
@@ -66,6 +72,9 @@ export declare function getWebhooks(context: CalcomContext): () => Promise<Calco
  *
  * @see https://cal.com/docs/api-reference/v2/webhooks/get-a-webhook
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that retrieves a specific webhook by ID
+ *
  * @example
  * ```ts
  * const response = await getWebhook(context)(42);
@@ -78,6 +87,9 @@ export declare function getWebhook(context: CalcomContext): (webhookId: CalcomWe
  *
  * @see https://cal.com/docs/api-reference/v2/webhooks/update-a-webhook
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that updates an existing webhook by ID
+ *
  * @example
  * ```ts
  * await updateWebhook(context)(42, { active: false });
@@ -89,6 +101,9 @@ export declare function updateWebhook(context: CalcomContext): (webhookId: Calco
  *
  * @see https://cal.com/docs/api-reference/v2/webhooks/delete-a-webhook
  *
+ * @param context - the Cal.com API context providing authentication and fetch capabilities
+ * @returns a function that deletes a webhook by ID
+ *
  * @example
  * ```ts
  * await deleteWebhook(context)(42);

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

@@ -1,6 +1,21 @@
 import { type FetchResponseError } from '@dereekb/util/fetch';
 import { type CalcomServerErrorData, type ParsedCalcomServerError } from '../calcom.error.api';
 export declare const logCalcomErrorToConsole: import("..").LogCalcomServerErrorFunction;
+/**
+ * Parses a FetchResponseError from a Cal.com API call into a typed CalcomServerError.
+ * Attempts to extract JSON error data from the response body.
+ *
+ * @param responseError - the fetch response error to parse
+ * @returns a parsed CalcomServerError, or undefined if the response body cannot be parsed
+ */
 export declare function parseCalcomApiError(responseError: FetchResponseError): Promise<ParsedCalcomServerError>;
+/**
+ * Parses Cal.com API server error response data into a specific error type.
+ * Delegates to {@link parseCalcomServerErrorData} for general error classification.
+ *
+ * @param calcomServerError - the parsed error data from the Cal.com response body
+ * @param responseError - the original FetchResponseError containing the HTTP response
+ * @returns a parsed CalcomServerError, or undefined if the error data is falsy
+ */
 export declare function parseCalcomApiServerErrorResponseData(calcomServerError: CalcomServerErrorData, responseError: FetchResponseError): ParsedCalcomServerError;
 export declare const handleCalcomErrorFetch: import("..").HandleCalcomErrorFetchFactory;

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

@@ -20,4 +20,12 @@ export interface CalcomFactoryConfig extends CalcomOAuthContextRef {
     readonly logCalcomServerErrorFunction?: LogCalcomServerErrorFunction;
 }
 export type CalcomFactory = (config: CalcomConfig) => Calcom;
+/**
+ * Creates a {@link CalcomFactory} that produces fully configured Cal.com API instances.
+ * Sets up rate limiting, error handling, OAuth token management, and both server
+ * and per-user fetch contexts.
+ *
+ * @param factoryConfig - configuration including OAuth context, rate limiter, and optional fetch/logging overrides
+ * @returns a factory function that accepts a CalcomConfig and produces a Calcom instance
+ */
 export declare function calcomFactory(factoryConfig: CalcomFactoryConfig): CalcomFactory;

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

@@ -40,7 +40,7 @@ export type LogCalcomServerErrorFunction = (error: FetchRequestFactoryError | Ca
  * Creates a logCalcomServerErrorFunction that logs the error to console.
  *
  * @param calcomApiNamePrefix Prefix to use when logging. I.E. CalcomError, etc.
- * @returns
+ * @returns a LogCalcomServerErrorFunction that logs errors with the given prefix
  */
 export declare function logCalcomServerErrorFunction(calcomApiNamePrefix: string): LogCalcomServerErrorFunction;
 /**
@@ -51,6 +51,10 @@ export type ParsedCalcomServerError = FetchRequestFactoryError | CalcomServerErr
 export type ParseCalcomFetchResponseErrorFunction = (responseError: FetchResponseError) => Promise<ParsedCalcomServerError>;
 /**
  * Wraps a ConfiguredFetch to support handling errors returned by fetch.
+ *
+ * @param parseCalcomError - function to parse a FetchResponseError into a CalcomServerError
+ * @param defaultLogError - default error logging function used when no override is provided
+ * @returns a factory that wraps any ConfiguredFetch with Cal.com error handling
  */
 export declare function handleCalcomErrorFetchFactory(parseCalcomError: ParseCalcomFetchResponseErrorFunction, defaultLogError: LogCalcomServerErrorFunction): HandleCalcomErrorFetchFactory;
 /**
@@ -76,11 +80,21 @@ export interface CalcomRateLimitHeaderDetails {
      */
     readonly resetAt?: Date;
 }
+/**
+ * Extracts Cal.com rate limit information from HTTP response headers.
+ *
+ * @param headers - the HTTP response headers to parse
+ * @returns parsed rate limit details, or null if no rate limit headers are present
+ */
 export declare function calcomRateLimitHeaderDetails(headers: Headers): Maybe<CalcomRateLimitHeaderDetails>;
 export declare class CalcomTooManyRequestsError extends CalcomServerFetchResponseError {
     get headerDetails(): Maybe<CalcomRateLimitHeaderDetails>;
 }
 /**
  * Function that parses/transforms a CalcomServerErrorData into a general CalcomServerError or other known error type.
+ *
+ * @param calcomServerError - the parsed error data from the Cal.com response body
+ * @param responseError - the original FetchResponseError containing the HTTP response
+ * @returns a CalcomServerFetchResponseError (or subclass like CalcomTooManyRequestsError), or undefined if unrecognized
  */
 export declare function parseCalcomServerErrorData(calcomServerError: CalcomServerErrorData, responseError: FetchResponseError): CalcomServerFetchResponseError | undefined;

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

@@ -32,4 +32,11 @@ export interface CalcomRateLimitedFetchHandlerConfig {
     readonly onTooManyRequests?: CalcomRateLimitedTooManyRequestsLogFunction | false;
 }
 export type CalcomRateLimitedFetchHandler = RateLimitedFetchHandler<ResetPeriodPromiseRateLimiter>;
+/**
+ * Creates a rate-limited fetch handler configured for Cal.com API rate limits.
+ * Automatically adjusts based on rate limit response headers and retries on 429 responses.
+ *
+ * @param config - optional rate limiter configuration overrides
+ * @returns a CalcomRateLimitedFetchHandler that enforces rate limiting
+ */
 export declare function calcomRateLimitedFetchHandler(config?: Maybe<CalcomRateLimitedFetchHandlerConfig>): CalcomRateLimitedFetchHandler;

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

@@ -27,6 +27,9 @@ export interface CalcomOAuthAccessTokenErrorResponse {
  *
  * @see https://cal.com/docs/api-reference/v2/oauth/refresh-an-existing-access-token
  *
+ * @param context - the Cal.com OAuth context providing client credentials and fetch capabilities
+ * @returns a function that refreshes an access token using an optional refresh token override
+ *
  * @example
  * ```ts
  * const response = await refreshAccessToken(context)({ refreshToken: 'existing-refresh-token' });
@@ -42,6 +45,9 @@ export declare function refreshAccessToken(context: CalcomOAuthContext): (input?
  *
  * @see https://cal.com/docs/api-reference/v2/oauth/exchange-an-authorization-code-for-access-tokens
  *
+ * @param context - the Cal.com OAuth context providing client credentials and fetch capabilities
+ * @returns a function that exchanges an authorization code for access and refresh tokens
+ *
  * @example
  * ```ts
  * const response = await exchangeAuthorizationCode(context)({

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

@@ -60,5 +60,10 @@ export type CalcomAccessTokenRefresher = CalcomAccessTokenFactory;
 export type CalcomAccessTokenStringFactory = () => Promise<CalcomAccessTokenString>;
 /**
  * Generates a new CalcomAccessTokenStringFactory.
+ * Wraps a CalcomAccessTokenFactory to extract just the access token string,
+ * throwing a CalcomOAuthAuthFailureError if the token is missing.
+ *
+ * @param calcomAccessTokenFactory - the factory that produces CalcomAccessToken objects
+ * @returns a factory function that returns the access token string
  */
 export declare function calcomAccessTokenStringFactory(calcomAccessTokenFactory: CalcomAccessTokenFactory): CalcomAccessTokenStringFactory;

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

@@ -21,6 +21,22 @@ export declare class CalcomOAuthAuthFailureError extends FetchRequestFactoryErro
     constructor(reason?: string | undefined);
 }
 export declare const logCalcomOAuthErrorToConsole: import("..").LogCalcomServerErrorFunction;
+/**
+ * Parses a FetchResponseError from a Cal.com OAuth call into a typed error.
+ * Attempts to extract JSON error data from the response body.
+ *
+ * @param responseError - the fetch response error to parse
+ * @returns a parsed CalcomServerError or CalcomOAuthAccessTokenError, or undefined if unparseable
+ */
 export declare function parseCalcomOAuthError(responseError: FetchResponseError): Promise<ParsedCalcomServerError>;
+/**
+ * Parses Cal.com OAuth server error response data into a specific error type.
+ * Handles known error codes like `invalid_grant` and delegates unknown errors
+ * to {@link parseCalcomServerErrorData}.
+ *
+ * @param calcomServerError - the parsed error data from the Cal.com OAuth response body
+ * @param responseError - the original FetchResponseError containing the HTTP response
+ * @returns a parsed error instance, or undefined if the error data is falsy
+ */
 export declare function parseCalcomOAuthServerErrorResponseData(calcomServerError: CalcomServerErrorData, responseError: FetchResponseError): ParsedCalcomServerError;
 export declare const handleCalcomOAuthErrorFetch: import("..").HandleCalcomErrorFetchFactory;

package/src/lib/oauth/oauth.factory.d.ts

@@ -14,6 +14,14 @@ export interface CalcomOAuthFactoryConfig {
     logCalcomServerErrorFunction?: LogCalcomServerErrorFunction;
 }
 export type CalcomOAuthFactory = (config: CalcomOAuthConfig) => CalcomOAuth;
+/**
+ * Creates a {@link CalcomOAuthFactory} that produces configured Cal.com OAuth instances.
+ * Supports both API key authentication (static token, no refresh) and full OAuth
+ * refresh token flow with automatic token rotation.
+ *
+ * @param factoryConfig - configuration including optional fetch factory and error logging
+ * @returns a factory function that accepts a CalcomOAuthConfig and produces a CalcomOAuth instance
+ */
 export declare function calcomOAuthFactory(factoryConfig: CalcomOAuthFactoryConfig): CalcomOAuthFactory;
 export interface CalcomOAuthAccessTokenFactoryConfig {
     /**
@@ -27,5 +35,10 @@ export interface CalcomOAuthAccessTokenFactoryConfig {
 }
 /**
  * Creates a CalcomAccessTokenFactory with multi-tier caching.
+ * Checks the in-memory cache first, then the external cache, and finally refreshes
+ * from the token refresher if no valid token is available.
+ *
+ * @param config - configuration including the token refresher, optional cache, and expiration buffer
+ * @returns a CalcomAccessTokenFactory that returns a valid access token on each call
  */
 export declare function calcomOAuthAccessTokenFactory(config: CalcomOAuthAccessTokenFactoryConfig): CalcomAccessTokenFactory;

package/src/lib/shared/calcom.api-version.d.ts

@@ -13,5 +13,8 @@ export type CalcomApiVersionString = string;
 export declare const CALCOM_API_VERSION_HEADER = "cal-api-version";
 /**
  * Returns a headers object with the cal-api-version header set.
+ *
+ * @param version - the Cal.com API version string to include in the header
+ * @returns a headers record containing the cal-api-version header
  */
 export declare function calcomApiVersionHeaders(version: CalcomApiVersionString): Record<string, string>;