@dereekb/calcom 13.4.0

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

@@ -0,0 +1,82 @@
+import { type EmailAddress, type ISO8601DateString, type Maybe } 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 {
+    readonly externalId: string;
+    readonly integration: CalcomCalendarIntegration;
+    readonly name: string;
+    readonly readOnly: boolean;
+    readonly email: EmailAddress;
+    readonly isSelected: boolean;
+    readonly credentialId: CalcomCredentialId;
+}
+export interface CalcomConnectedCalendar {
+    readonly integration: CalcomCalendarIntegration;
+    readonly credentialId: CalcomCredentialId;
+    readonly primary: {
+        readonly calendars: CalcomCalendar[];
+    };
+}
+export interface CalcomDestinationCalendar {
+    readonly id: CalcomId;
+    readonly integration: CalcomCalendarIntegration;
+    readonly externalId: string;
+    readonly primaryEmail: EmailAddress;
+    readonly name: string;
+    readonly readOnly: boolean;
+    readonly email: EmailAddress;
+    readonly isSelected: boolean;
+    readonly credentialId: CalcomCredentialId;
+    readonly userId: CalcomUserId;
+    readonly eventTypeId: Maybe<CalcomEventTypeId>;
+    readonly integrationTitle: string;
+}
+export interface CalcomGetCalendarsResponseData {
+    readonly connectedCalendars: CalcomConnectedCalendar[];
+    readonly destinationCalendar: Maybe<CalcomDestinationCalendar>;
+}
+export interface CalcomGetCalendarsResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomGetCalendarsResponseData;
+}
+export interface CalcomGetBusyTimesInput {
+    readonly dateFrom: ISO8601DateString;
+    readonly dateTo: ISO8601DateString;
+    readonly calendarsToLoad?: Maybe<string[]>;
+}
+export interface CalcomBusyTime {
+    readonly start: ISO8601DateString;
+    readonly end: ISO8601DateString;
+    readonly source?: Maybe<string>;
+}
+export interface CalcomGetBusyTimesResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomBusyTime[];
+}
+/**
+ * Retrieves all connected calendars and the destination calendar for the authenticated user.
+ *
+ * @see https://cal.com/docs/api-reference/v2/calendars/get-all-calendars
+ *
+ * @example
+ * ```ts
+ * const response = await getCalendars(context)();
+ * response.data.connectedCalendars.forEach(cc => console.log(cc.integration));
+ * ```
+ */
+export declare function getCalendars(context: CalcomContext): () => Promise<CalcomGetCalendarsResponse>;
+/**
+ * Retrieves busy time ranges across the user's connected calendars for a given date range.
+ *
+ * @see https://cal.com/docs/api-reference/v2/calendars/get-busy-times
+ *
+ * @example
+ * ```ts
+ * const response = await getBusyTimes(context)({
+ *   dateFrom: '2026-03-17',
+ *   dateTo: '2026-03-24'
+ * });
+ * response.data.forEach(bt => console.log(bt.start, bt.end));
+ * ```
+ */
+export declare function getBusyTimes(context: CalcomContext): (input: CalcomGetBusyTimesInput) => Promise<CalcomGetBusyTimesResponse>;

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

@@ -0,0 +1,85 @@
+import { type Minutes } from '@dereekb/util';
+import { type CalcomContext } from './calcom.config';
+import { type CalcomEventTypeId, type CalcomEventTypeSlug, type CalcomResponseStatus } from '../calcom.type';
+export interface CalcomEventType {
+    readonly id: CalcomEventTypeId;
+    readonly title: string;
+    readonly slug: CalcomEventTypeSlug;
+    readonly description: string | null;
+    readonly lengthInMinutes: Minutes;
+    readonly locations: unknown[];
+}
+export interface CalcomGetEventTypesResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomEventType[];
+}
+export interface CalcomEventTypeResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomEventType;
+}
+export interface CalcomCreateEventTypeInput {
+    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[];
+}
+/**
+ * Retrieves all event types for the authenticated user.
+ *
+ * @see https://cal.com/docs/api-reference/v2/event-types/get-all-event-types
+ *
+ * @example
+ * ```ts
+ * const response = await getEventTypes(context)();
+ * response.data.forEach(et => console.log(et.title, et.slug, et.lengthInMinutes));
+ * ```
+ */
+export declare function getEventTypes(context: CalcomContext): () => Promise<CalcomGetEventTypesResponse>;
+/**
+ * Creates a new event type for the authenticated user.
+ *
+ * @see https://cal.com/docs/api-reference/v2/event-types/create-an-event-type
+ *
+ * @example
+ * ```ts
+ * const response = await createEventType(context)({
+ *   title: 'Mentoring Session',
+ *   slug: 'mentoring-session',
+ *   lengthInMinutes: 30
+ * });
+ * console.log(response.data.id);
+ * ```
+ */
+export declare function createEventType(context: CalcomContext): (input: CalcomCreateEventTypeInput) => Promise<CalcomEventTypeResponse>;
+/**
+ * Updates an existing event type by ID.
+ *
+ * @see https://cal.com/docs/api-reference/v2/event-types/update-an-event-type
+ *
+ * @example
+ * ```ts
+ * await updateEventType(context)(12345, { title: 'Updated Session Title' });
+ * ```
+ */
+export declare function updateEventType(context: CalcomContext): (eventTypeId: CalcomEventTypeId, input: CalcomUpdateEventTypeInput) => Promise<CalcomEventTypeResponse>;
+/**
+ * Deletes an event type by ID.
+ *
+ * @see https://cal.com/docs/api-reference/v2/event-types/delete-an-event-type
+ *
+ * @example
+ * ```ts
+ * await deleteEventType(context)(12345);
+ * ```
+ */
+export declare function deleteEventType(context: CalcomContext): (eventTypeId: CalcomEventTypeId) => Promise<CalcomEventTypeResponse>;

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

@@ -0,0 +1,32 @@
+import { type TimezoneString } from '@dereekb/util';
+import { type CalcomContext } from './calcom.config';
+import { type CalcomScheduleId, type CalcomResponseStatus } from '../calcom.type';
+export interface CalcomAvailabilityRule {
+    readonly days: string[];
+    readonly startTime: string;
+    readonly endTime: string;
+}
+export interface CalcomSchedule {
+    readonly id: CalcomScheduleId;
+    readonly name: string;
+    readonly timeZone: TimezoneString;
+    readonly availability: CalcomAvailabilityRule[];
+    readonly isDefault: boolean;
+    readonly overrides: Record<string, CalcomAvailabilityRule[]>;
+}
+export interface CalcomGetSchedulesResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomSchedule[];
+}
+/**
+ * Retrieves all schedules for the authenticated user, including availability rules and overrides.
+ *
+ * @see https://cal.com/docs/api-reference/v2/schedules/get-all-schedules
+ *
+ * @example
+ * ```ts
+ * const response = await getSchedules(context)();
+ * response.data.forEach(schedule => console.log(schedule.name, schedule.timeZone));
+ * ```
+ */
+export declare function getSchedules(context: CalcomContext): () => Promise<CalcomGetSchedulesResponse>;

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

@@ -0,0 +1,46 @@
+import { type ISO8601DateString, 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 {
+    readonly start: ISO8601DateString;
+    readonly end: ISO8601DateString;
+    readonly eventTypeId?: Maybe<CalcomEventTypeId>;
+    readonly eventTypeSlug?: Maybe<CalcomEventTypeSlug>;
+    readonly username?: Maybe<CalcomUsername>;
+    readonly teamSlug?: Maybe<CalcomTeamSlug>;
+    readonly organizationSlug?: Maybe<CalcomOrganizationSlug>;
+    readonly timeZone?: Maybe<TimezoneString>;
+    readonly duration?: Maybe<Minutes>;
+    readonly format?: Maybe<'range' | 'time'>;
+}
+export interface CalcomSlot {
+    readonly time: ISO8601DateString;
+}
+export interface CalcomGetAvailableSlotsResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: {
+        readonly slots: Record<string, CalcomSlot[]>;
+    };
+}
+/**
+ * Queries available booking slots for a given event type within a date range.
+ * This endpoint is public and does not require authentication.
+ *
+ * Identify the event type by `eventTypeId`, or by `eventTypeSlug` + `username`/`teamSlug`.
+ *
+ * @see https://cal.com/docs/api-reference/v2/slots/get-available-time-slots-for-an-event-type
+ *
+ * @example
+ * ```ts
+ * const response = await getAvailableSlots(context)({
+ *   start: '2026-03-17T00:00:00.000Z',
+ *   end: '2026-03-24T00:00:00.000Z',
+ *   eventTypeId: 12345
+ * });
+ *
+ * for (const [date, slots] of Object.entries(response.data.slots)) {
+ *   console.log(date, slots.map(s => s.time));
+ * }
+ * ```
+ */
+export declare function getAvailableSlots(context: CalcomContext | CalcomPublicContext): (input: CalcomGetAvailableSlotsInput) => Promise<CalcomGetAvailableSlotsResponse>;

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

@@ -0,0 +1,29 @@
+import { type EmailAddress, type ISO8601DateString, type TimezoneString } from '@dereekb/util';
+import { type CalcomContext } from './calcom.config';
+import { type CalcomUserId, type CalcomUsername, type CalcomScheduleId, type CalcomResponseStatus } from '../calcom.type';
+export interface CalcomUser {
+    readonly id: CalcomUserId;
+    readonly email: EmailAddress;
+    readonly username: CalcomUsername | null;
+    readonly timeZone: TimezoneString;
+    readonly weekStart: string;
+    readonly createdDate: ISO8601DateString;
+    readonly timeFormat: number;
+    readonly defaultScheduleId: CalcomScheduleId | null;
+}
+export interface CalcomGetMeResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomUser;
+}
+/**
+ * Retrieves the profile of the currently authenticated Cal.com user.
+ *
+ * @see https://cal.com/docs/api-reference/v2/me
+ *
+ * @example
+ * ```ts
+ * const response = await getMe(context)();
+ * console.log(response.data.email);
+ * ```
+ */
+export declare function getMe(context: CalcomContext): () => Promise<CalcomGetMeResponse>;

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

@@ -0,0 +1,97 @@
+import { type WebsiteUrl } 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';
+export interface CalcomWebhook {
+    readonly id: CalcomWebhookId;
+    readonly subscriberUrl: WebsiteUrl;
+    readonly triggers: CalcomWebhookTrigger[];
+    readonly active: boolean;
+    readonly payloadTemplate?: string | null;
+    readonly secret?: string | null;
+}
+export interface CalcomCreateWebhookInput {
+    readonly subscriberUrl: WebsiteUrl;
+    readonly triggers: CalcomWebhookTrigger[];
+    readonly active?: boolean;
+    readonly payloadTemplate?: string;
+    readonly secret?: string;
+}
+export interface CalcomUpdateWebhookInput {
+    readonly subscriberUrl?: WebsiteUrl;
+    readonly triggers?: CalcomWebhookTrigger[];
+    readonly active?: boolean;
+    readonly payloadTemplate?: string;
+    readonly secret?: string;
+}
+export interface CalcomWebhookResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomWebhook;
+}
+export interface CalcomGetWebhooksResponse {
+    readonly status: CalcomResponseStatus;
+    readonly data: CalcomWebhook[];
+}
+/**
+ * Creates a webhook subscription for the authenticated user. Webhooks notify your app
+ * when specified events occur (e.g., bookings created, cancelled, rescheduled).
+ *
+ * @see https://cal.com/docs/api-reference/v2/webhooks/create-a-webhook
+ *
+ * @example
+ * ```ts
+ * const response = await createWebhook(context)({
+ *   subscriberUrl: 'https://example.com/webhook/calcom',
+ *   triggers: ['BOOKING_CREATED', 'BOOKING_CANCELLED'],
+ *   active: true
+ * });
+ * console.log(response.data.id);
+ * ```
+ */
+export declare function createWebhook(context: CalcomContext): (input: CalcomCreateWebhookInput) => Promise<CalcomWebhookResponse>;
+/**
+ * Retrieves all webhooks for the authenticated user.
+ *
+ * @see https://cal.com/docs/api-reference/v2/webhooks/get-all-webhooks
+ *
+ * @example
+ * ```ts
+ * const response = await getWebhooks(context)();
+ * response.data.forEach(wh => console.log(wh.subscriberUrl, wh.triggers));
+ * ```
+ */
+export declare function getWebhooks(context: CalcomContext): () => Promise<CalcomGetWebhooksResponse>;
+/**
+ * Retrieves a specific webhook by ID.
+ *
+ * @see https://cal.com/docs/api-reference/v2/webhooks/get-a-webhook
+ *
+ * @example
+ * ```ts
+ * const response = await getWebhook(context)(42);
+ * console.log(response.data.subscriberUrl);
+ * ```
+ */
+export declare function getWebhook(context: CalcomContext): (webhookId: CalcomWebhookId) => Promise<CalcomWebhookResponse>;
+/**
+ * Updates an existing webhook by ID.
+ *
+ * @see https://cal.com/docs/api-reference/v2/webhooks/update-a-webhook
+ *
+ * @example
+ * ```ts
+ * await updateWebhook(context)(42, { active: false });
+ * ```
+ */
+export declare function updateWebhook(context: CalcomContext): (webhookId: CalcomWebhookId, input: CalcomUpdateWebhookInput) => Promise<CalcomWebhookResponse>;
+/**
+ * Deletes a webhook by ID.
+ *
+ * @see https://cal.com/docs/api-reference/v2/webhooks/delete-a-webhook
+ *
+ * @example
+ * ```ts
+ * await deleteWebhook(context)(42);
+ * ```
+ */
+export declare function deleteWebhook(context: CalcomContext): (webhookId: CalcomWebhookId) => Promise<CalcomWebhookResponse>;

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

@@ -0,0 +1,66 @@
+import { type FactoryWithRequiredInput, type Maybe } from '@dereekb/util';
+import { type ConfiguredFetch, type FetchJsonFunction } from '@dereekb/util/fetch';
+import { type CalcomConfig, type CalcomRefreshToken } from '../calcom.config';
+import { type CalcomAccessTokenCache, type CalcomAccessTokenStringFactory } from '../oauth/oauth';
+import { type CalcomRateLimiterRef } from '../calcom.limit';
+export interface CalcomFetchFactoryInput {
+    readonly calcomAccessTokenStringFactory: CalcomAccessTokenStringFactory;
+}
+export type CalcomFetchFactory = (input: CalcomFetchFactoryInput) => ConfiguredFetch;
+/**
+ * A calcom context that can send requests to the Cal.com API.
+ */
+export interface CalcomContext extends CalcomRateLimiterRef {
+    /**
+     * Type of context this is.
+     */
+    readonly type: 'server' | 'user';
+    /**
+     * Performs a fetch.
+     */
+    readonly fetch: ConfiguredFetch;
+    /**
+     * Performs a json fetch.
+     */
+    readonly fetchJson: FetchJsonFunction;
+}
+export interface CalcomUserContext extends CalcomContext {
+    readonly type: 'user';
+    readonly calcomServerContext: CalcomServerContext;
+    readonly userFetch: ConfiguredFetch;
+    readonly userFetchJson: FetchJsonFunction;
+}
+export interface CalcomUserContextFactoryInput {
+    /**
+     * The user's refresh token.
+     */
+    readonly refreshToken: CalcomRefreshToken;
+    /**
+     * Optional cache to use for the user's access token.
+     *
+     * The cache should only be configured for the user that owns the refresh token.
+     */
+    readonly accessTokenCache?: Maybe<CalcomAccessTokenCache>;
+}
+/**
+ * Creates a CalcomUserContext from the input.
+ */
+export type CalcomUserContextFactory = FactoryWithRequiredInput<CalcomUserContext, CalcomUserContextFactoryInput>;
+/**
+ * Context for making public (unauthenticated) requests to the Cal.com API.
+ */
+export interface CalcomPublicContext {
+    readonly fetch: ConfiguredFetch;
+    readonly fetchJson: FetchJsonFunction;
+}
+export interface CalcomServerContext extends CalcomContext {
+    readonly type: 'server';
+    readonly serverFetch: ConfiguredFetch;
+    readonly serverFetchJson: FetchJsonFunction;
+    readonly makeUserContext: CalcomUserContextFactory;
+    readonly makePublicContext: () => CalcomPublicContext;
+    readonly config: CalcomConfig;
+}
+export interface CalcomServerContextRef {
+    readonly calcomServerContext: CalcomServerContext;
+}

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

@@ -0,0 +1,6 @@
+import { type FetchResponseError } from '@dereekb/util/fetch';
+import { type CalcomServerErrorData, type ParsedCalcomServerError } from '../calcom.error.api';
+export declare const logCalcomErrorToConsole: import("..").LogCalcomServerErrorFunction;
+export declare function parseCalcomApiError(responseError: FetchResponseError): Promise<ParsedCalcomServerError>;
+export declare function parseCalcomApiServerErrorResponseData(calcomServerError: CalcomServerErrorData, responseError: FetchResponseError): ParsedCalcomServerError;
+export declare const handleCalcomErrorFetch: import("..").HandleCalcomErrorFetchFactory;

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

@@ -0,0 +1,23 @@
+import { type CalcomServerContextRef, type CalcomFetchFactory } from './calcom.config';
+import { type LogCalcomServerErrorFunction } from '../calcom.error.api';
+import { type CalcomOAuthContextRef } from '../oauth/oauth.config';
+import { type CalcomRateLimitedFetchHandlerConfig } from '../calcom.limit';
+import { type Maybe } from '@dereekb/util';
+import { type CalcomConfig } from '../calcom.config';
+export type Calcom = CalcomServerContextRef;
+export interface CalcomFactoryConfig extends CalcomOAuthContextRef {
+    /**
+     * Custom CalcomRateLimitedFetchHandlerConfig
+     */
+    readonly rateLimiterConfig?: Maybe<CalcomRateLimitedFetchHandlerConfig>;
+    /**
+     * Creates a new fetch instance to use when making calls.
+     */
+    readonly fetchFactory?: CalcomFetchFactory;
+    /**
+     * Custom log error function.
+     */
+    readonly logCalcomServerErrorFunction?: LogCalcomServerErrorFunction;
+}
+export type CalcomFactory = (config: CalcomConfig) => Calcom;
+export declare function calcomFactory(factoryConfig: CalcomFactoryConfig): CalcomFactory;

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

@@ -0,0 +1,10 @@
+export * from './calcom.config';
+export * from './calcom.factory';
+export * from './calcom.api.user';
+export * from './calcom.api.schedule';
+export * from './calcom.api.slot';
+export * from './calcom.api.booking';
+export * from './calcom.api.eventtype';
+export * from './calcom.api.calendar';
+export * from './calcom.api.webhook';
+export * from './calcom.error.api';

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

@@ -0,0 +1,35 @@
+/**
+ * The Cal.com API URL.
+ */
+export declare const CALCOM_API_URL = "https://api.cal.com/v2";
+/**
+ * OAuth Client Id
+ */
+export type CalcomOAuthClientId = string;
+/**
+ * OAuth Client Secret
+ */
+export type CalcomOAuthClientSecret = string;
+export interface CalcomAuthClientIdAndSecretPair {
+    readonly clientId: CalcomOAuthClientId;
+    readonly clientSecret: CalcomOAuthClientSecret;
+}
+/**
+ * Refresh token used to retrieve access tokens for performing API calls.
+ *
+ * Cal.com rotates refresh tokens on each use, so the latest value must always be persisted.
+ */
+export type CalcomRefreshToken = string;
+/**
+ * Cal.com API key, prefixed with `cal_` (test) or `cal_live_` (production).
+ *
+ * Created in Cal.com user settings > Security. Acts as the user who created it.
+ * Does not expire and requires no refresh.
+ */
+export type CalcomApiKey = string;
+export interface CalcomConfig {
+}
+/**
+ * Secret used for validating Cal.com webhooks.
+ */
+export type CalcomWebhookSecret = string;

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

@@ -0,0 +1,86 @@
+import { type Maybe } from '@dereekb/util';
+import { type ConfiguredFetch, type FetchRequestFactoryError, FetchResponseError } from '@dereekb/util/fetch';
+import { BaseError } from 'make-error';
+/**
+ * Cal.com server error codes are numbers or strings.
+ */
+export type CalcomServerErrorCode = string | number;
+/**
+ * Cal.com Server Error Data
+ *
+ * Always contains a code and message. Details and status are optional.
+ */
+export interface CalcomServerErrorData<T = unknown> {
+    readonly code: CalcomServerErrorCode;
+    readonly message: string;
+    readonly details?: T;
+    /**
+     * Is sometimes present on some error responses.
+     */
+    readonly status?: string;
+}
+/**
+ * Cal.com Server Error
+ */
+export declare class CalcomServerError<D extends CalcomServerErrorData = CalcomServerErrorData> extends BaseError {
+    readonly error: D;
+    get code(): CalcomServerErrorCode;
+    constructor(error: D);
+}
+/**
+ * Cal.com Server Error that includes the FetchResponseError
+ */
+export declare class CalcomServerFetchResponseError<D extends CalcomServerErrorData = CalcomServerErrorData> extends CalcomServerError<D> {
+    readonly data: D;
+    readonly responseError: FetchResponseError;
+    constructor(data: D, responseError: FetchResponseError);
+}
+export type LogCalcomServerErrorFunction = (error: FetchRequestFactoryError | CalcomServerError | CalcomServerFetchResponseError) => void;
+/**
+ * Creates a logCalcomServerErrorFunction that logs the error to console.
+ *
+ * @param calcomApiNamePrefix Prefix to use when logging. I.E. CalcomError, etc.
+ * @returns
+ */
+export declare function logCalcomServerErrorFunction(calcomApiNamePrefix: string): LogCalcomServerErrorFunction;
+/**
+ * Wraps a ConfiguredFetch to support handling errors returned by fetch.
+ */
+export type HandleCalcomErrorFetchFactory = (fetch: ConfiguredFetch, logError?: LogCalcomServerErrorFunction) => ConfiguredFetch;
+export type ParsedCalcomServerError = FetchRequestFactoryError | CalcomServerError | undefined;
+export type ParseCalcomFetchResponseErrorFunction = (responseError: FetchResponseError) => Promise<ParsedCalcomServerError>;
+/**
+ * Wraps a ConfiguredFetch to support handling errors returned by fetch.
+ */
+export declare function handleCalcomErrorFetchFactory(parseCalcomError: ParseCalcomFetchResponseErrorFunction, defaultLogError: LogCalcomServerErrorFunction): HandleCalcomErrorFetchFactory;
+/**
+ * The status code that indicates too many requests have been made.
+ */
+export declare const CALCOM_TOO_MANY_REQUESTS_HTTP_STATUS_CODE = 429;
+export declare const CALCOM_RATE_LIMIT_LIMIT_HEADER = "X-RateLimit-Limit";
+export declare const CALCOM_RATE_LIMIT_REMAINING_HEADER = "X-RateLimit-Remaining";
+export declare const CALCOM_RATE_LIMIT_RESET_HEADER = "X-RateLimit-Reset";
+export declare const DEFAULT_CALCOM_API_RATE_LIMIT = 100;
+export declare const DEFAULT_CALCOM_API_RATE_LIMIT_RESET_PERIOD: number;
+export interface CalcomRateLimitHeaderDetails {
+    /**
+     * Total limit in a given period.
+     */
+    readonly limit?: number;
+    /**
+     * Total number of remaining allowed requests.
+     */
+    readonly remaining?: number;
+    /**
+     * The time at which the rate limit will reset.
+     */
+    readonly resetAt?: Date;
+}
+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.
+ */
+export declare function parseCalcomServerErrorData(calcomServerError: CalcomServerErrorData, responseError: FetchResponseError): CalcomServerFetchResponseError | undefined;

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

@@ -0,0 +1,35 @@
+import { type Maybe, type Milliseconds, type PromiseOrValue, type ResetPeriodPromiseRateLimiter } from '@dereekb/util';
+import { type FetchResponseError, type RateLimitedFetchHandler } from '@dereekb/util/fetch';
+import { type CalcomRateLimitHeaderDetails } from './calcom.error.api';
+export interface CalcomRateLimiterRef {
+    readonly calcomRateLimiter: ResetPeriodPromiseRateLimiter;
+}
+/**
+ * Function to execute when too many requests is reached.
+ *
+ * Typically used for logging of some sort. Thrown errors are ignored.
+ */
+export type CalcomRateLimitedTooManyRequestsLogFunction = (headers: CalcomRateLimitHeaderDetails, response: Response, fetchResponseError?: FetchResponseError) => PromiseOrValue<void>;
+export declare const DEFAULT_CALCOM_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION: (headers: CalcomRateLimitHeaderDetails) => void;
+export interface CalcomRateLimitedFetchHandlerConfig {
+    /**
+     * Custom max rate limit.
+     *
+     * Cal.com allows 120 req/min. We default to 100 as a conservative limit.
+     */
+    readonly maxRateLimit?: number;
+    /**
+     * Custom reset period for the rate limiter.
+     *
+     * Defaults to 1 minute in milliseconds.
+     */
+    readonly resetPeriod?: Milliseconds;
+    /**
+     * Optional function to execute when too many requests is reached.
+     *
+     * Defaults to the default logging function, unless false is passed.
+     */
+    readonly onTooManyRequests?: CalcomRateLimitedTooManyRequestsLogFunction | false;
+}
+export type CalcomRateLimitedFetchHandler = RateLimitedFetchHandler<ResetPeriodPromiseRateLimiter>;
+export declare function calcomRateLimitedFetchHandler(config?: Maybe<CalcomRateLimitedFetchHandlerConfig>): CalcomRateLimitedFetchHandler;