@dereekb/calcom 13.4.0

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

@@ -0,0 +1,70 @@
+/**
+ * A numeric identifier in Cal.com.
+ */
+export type CalcomId = number;
+/**
+ * Cal.com user identifier.
+ */
+export type CalcomUserId = number;
+/**
+ * Cal.com event type identifier.
+ */
+export type CalcomEventTypeId = number;
+/**
+ * Cal.com booking identifier.
+ */
+export type CalcomBookingId = number;
+/**
+ * Cal.com schedule identifier.
+ */
+export type CalcomScheduleId = number;
+/**
+ * Cal.com webhook identifier.
+ */
+export type CalcomWebhookId = number;
+/**
+ * Cal.com credential identifier, used to reference connected calendar credentials.
+ */
+export type CalcomCredentialId = number;
+/**
+ * Cal.com booking UID string. A unique string identifier for a booking,
+ * distinct from the numeric booking ID.
+ */
+export type CalcomBookingUid = string;
+/**
+ * Cal.com username. Used to identify a user in public-facing URLs
+ * (e.g., cal.com/{username}/{event-slug}).
+ */
+export type CalcomUsername = string;
+/**
+ * Cal.com event type slug. A URL-safe string identifying an event type
+ * (e.g., "30-minute-meeting").
+ */
+export type CalcomEventTypeSlug = string;
+/**
+ * Cal.com team slug. A URL-safe string identifying a team
+ * (e.g., "engineering-team").
+ */
+export type CalcomTeamSlug = string;
+/**
+ * Cal.com organization slug. A URL-safe string identifying an organization.
+ */
+export type CalcomOrganizationSlug = string;
+/**
+ * Cal.com calendar integration identifier string
+ * (e.g., "google_calendar", "outlook_calendar", "apple_calendar").
+ */
+export type CalcomCalendarIntegration = string;
+/**
+ * Cal.com webhook event type string
+ * (e.g., "BOOKING_CREATED", "BOOKING_CANCELLED").
+ */
+export type CalcomWebhookEventTypeString = string;
+/**
+ * Cal.com API response status string (e.g., "success", "error").
+ */
+export type CalcomResponseStatus = 'success' | 'error';
+/**
+ * Cal.com booking status string.
+ */
+export type CalcomBookingStatus = 'accepted' | 'pending' | 'cancelled' | 'rejected';

package/src/lib/index.d.ts

@@ -0,0 +1,7 @@
+export * from './calcom';
+export * from './oauth';
+export * from './shared';
+export * from './calcom.error.api';
+export * from './calcom.config';
+export * from './calcom.limit';
+export * from './calcom.type';

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

@@ -0,0 +1,5 @@
+export * from './oauth';
+export * from './oauth.api';
+export * from './oauth.config';
+export * from './oauth.error.api';
+export * from './oauth.factory';

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

@@ -0,0 +1,54 @@
+import { type CalcomOAuthContext } from './oauth.config';
+import { type CalcomRefreshToken } from '../calcom.config';
+import { type CalcomAccessTokenScopesString, type CalcomAccessTokenString } from './oauth';
+import { type Maybe, type Seconds } from '@dereekb/util';
+export interface CalcomOAuthRefreshTokenInput {
+    readonly refreshToken?: Maybe<CalcomRefreshToken>;
+}
+export interface CalcomOAuthExchangeAuthorizationCodeInput {
+    readonly code: string;
+    readonly redirectUri: string;
+}
+export interface CalcomOAuthTokenResponse {
+    readonly access_token: CalcomAccessTokenString;
+    readonly refresh_token: CalcomRefreshToken;
+    readonly token_type: 'Bearer';
+    readonly expires_in: Seconds;
+    readonly scope?: CalcomAccessTokenScopesString;
+}
+export interface CalcomOAuthAccessTokenErrorResponse {
+    readonly error: string;
+}
+/**
+ * Refreshes an access token using a refresh token. Cal.com rotates refresh tokens
+ * on every use, so the new `refresh_token` from the response must be persisted.
+ *
+ * Cal.com uses JSON body (not Basic Auth) for token requests.
+ *
+ * @see https://cal.com/docs/api-reference/v2/oauth/refresh-an-existing-access-token
+ *
+ * @example
+ * ```ts
+ * const response = await refreshAccessToken(context)({ refreshToken: 'existing-refresh-token' });
+ * console.log(response.access_token, response.refresh_token);
+ * ```
+ */
+export declare function refreshAccessToken(context: CalcomOAuthContext): (input?: CalcomOAuthRefreshTokenInput) => Promise<CalcomOAuthTokenResponse>;
+/**
+ * Exchanges an OAuth authorization code for access and refresh tokens.
+ * Used during the initial OAuth flow when a user authorizes your app.
+ *
+ * Cal.com uses JSON body (not Basic Auth) for token requests.
+ *
+ * @see https://cal.com/docs/api-reference/v2/oauth/exchange-an-authorization-code-for-access-tokens
+ *
+ * @example
+ * ```ts
+ * const response = await exchangeAuthorizationCode(context)({
+ *   code: 'auth-code-from-redirect',
+ *   redirectUri: 'https://example.com/callback'
+ * });
+ * console.log(response.access_token, response.refresh_token);
+ * ```
+ */
+export declare function exchangeAuthorizationCode(context: CalcomOAuthContext): (input: CalcomOAuthExchangeAuthorizationCodeInput) => Promise<CalcomOAuthTokenResponse>;

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

@@ -0,0 +1,53 @@
+import { type FactoryWithInput, type FactoryWithRequiredInput, type Maybe } from '@dereekb/util';
+import { type ConfiguredFetch, type FetchJsonFunction } from '@dereekb/util/fetch';
+import { type CalcomApiKey, type CalcomAuthClientIdAndSecretPair, type CalcomRefreshToken } from '../calcom.config';
+import { type CalcomAccessTokenCache, type CalcomAccessTokenFactory } from './oauth';
+/**
+ * The Cal.com OAuth token endpoint URL.
+ */
+export declare const CALCOM_OAUTH_TOKEN_URL = "https://api.cal.com/v2/oauth/token";
+/**
+ * The Cal.com OAuth authorize URL.
+ */
+export declare const CALCOM_OAUTH_AUTHORIZE_URL = "https://app.cal.com/auth/oauth2/authorize";
+/**
+ * Configuration for CalcomOAuth.
+ */
+export interface CalcomOAuthConfig extends Partial<CalcomAuthClientIdAndSecretPair> {
+    /**
+     * Optional CalcomAccessTokenCache for caching access tokens.
+     */
+    readonly accessTokenCache?: Maybe<CalcomAccessTokenCache>;
+    /**
+     * Server-level refresh token for initial authentication.
+     */
+    readonly refreshToken?: Maybe<CalcomRefreshToken>;
+    /**
+     * Optional API key for simple bearer token auth.
+     *
+     * When provided, OAuth token refresh is skipped and the API key is used directly as the bearer token.
+     * Does not expire and requires no refresh.
+     */
+    readonly apiKey?: Maybe<CalcomApiKey>;
+}
+export interface CalcomOAuthFetchFactoryInput {
+}
+export type CalcomOAuthFetchFactory = FactoryWithInput<ConfiguredFetch, CalcomOAuthFetchFactoryInput>;
+export type CalcomOAuthMakeUserAccessTokenFactoryInput = {
+    readonly refreshToken: CalcomRefreshToken;
+    readonly userAccessTokenCache?: Maybe<CalcomAccessTokenCache>;
+};
+export type CalcomOAuthMakeUserAccessTokenFactory = FactoryWithRequiredInput<CalcomAccessTokenFactory, CalcomOAuthMakeUserAccessTokenFactoryInput>;
+/**
+ * Context used for performing fetch() and fetchJson() calls with a configured fetch instance.
+ */
+export interface CalcomOAuthContext {
+    readonly fetch: ConfiguredFetch;
+    readonly fetchJson: FetchJsonFunction;
+    readonly loadAccessToken: CalcomAccessTokenFactory;
+    readonly makeUserAccessTokenFactory: CalcomOAuthMakeUserAccessTokenFactory;
+    readonly config: CalcomOAuthConfig;
+}
+export interface CalcomOAuthContextRef {
+    readonly oauthContext: CalcomOAuthContext;
+}

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

@@ -0,0 +1,64 @@
+import { type Maybe, type Seconds } from '@dereekb/util';
+import { type CalcomRefreshToken } from '../calcom.config';
+/**
+ * Access token authorization string generated from a refresh token.
+ */
+export type CalcomAccessTokenString = string;
+/**
+ * Scopes string for a CalcomAccessToken that is space-separated.
+ */
+export type CalcomAccessTokenScopesString = string;
+/**
+ * Cal.com account access token.
+ */
+export interface CalcomAccessToken {
+    readonly accessToken: CalcomAccessTokenString;
+    readonly scope: CalcomAccessTokenScopesString;
+    /**
+     * The latest refresh token. Cal.com rotates refresh tokens on every use.
+     */
+    readonly refreshToken: CalcomRefreshToken;
+    /**
+     * Length of time the token is valid for.
+     */
+    readonly expiresIn: Seconds;
+    /**
+     * Date the token expires at.
+     */
+    readonly expiresAt: Date;
+}
+/**
+ * Used for retrieving and storing CalcomAccessToken values.
+ */
+export interface CalcomAccessTokenCache {
+    /**
+     * Loads the token from the cache, if available.
+     *
+     * The token may be expired.
+     */
+    loadCachedToken(): Promise<Maybe<CalcomAccessToken>>;
+    /**
+     * Updates the cache with the given access token.
+     */
+    updateCachedToken(accessToken: CalcomAccessToken): Promise<void>;
+}
+/**
+ * Source for retrieving a CalcomAccessToken.
+ *
+ * Throws a CalcomOAuthAuthFailureError error if the token could not be retrieved.
+ */
+export type CalcomAccessTokenFactory = () => Promise<CalcomAccessToken>;
+/**
+ * A CalcomAccessTokenFactory that always generates a new CalcomAccessToken.
+ */
+export type CalcomAccessTokenRefresher = CalcomAccessTokenFactory;
+/**
+ * Source for retrieving a CalcomAccessToken string.
+ *
+ * Throws a CalcomOAuthAuthFailureError error if the token could not be retrieved.
+ */
+export type CalcomAccessTokenStringFactory = () => Promise<CalcomAccessTokenString>;
+/**
+ * Generates a new CalcomAccessTokenStringFactory.
+ */
+export declare function calcomAccessTokenStringFactory(calcomAccessTokenFactory: CalcomAccessTokenFactory): CalcomAccessTokenStringFactory;

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

@@ -0,0 +1,26 @@
+import { FetchRequestFactoryError, type FetchResponseError } from '@dereekb/util/fetch';
+import { type CalcomServerErrorData, type ParsedCalcomServerError } from '../calcom.error.api';
+/**
+ * Error in the following cases:
+ * - the refresh token string is invalid
+ */
+export declare const CALCOM_OAUTH_INVALID_GRANT_ERROR_CODE = "invalid_grant";
+export type CalcomOAuthAccessTokenErrorCode = typeof CALCOM_OAUTH_INVALID_GRANT_ERROR_CODE;
+/**
+ * Thrown if the call to the Cal.com API creating an access token using a refresh token fails.
+ */
+export declare class CalcomOAuthAccessTokenError extends FetchRequestFactoryError {
+    readonly errorCode: CalcomOAuthAccessTokenErrorCode;
+    constructor(errorCode: CalcomOAuthAccessTokenErrorCode);
+}
+/**
+ * Thrown if a valid CalcomAccessToken cannot be retrieved successfully.
+ */
+export declare class CalcomOAuthAuthFailureError extends FetchRequestFactoryError {
+    readonly reason?: string | undefined;
+    constructor(reason?: string | undefined);
+}
+export declare const logCalcomOAuthErrorToConsole: import("..").LogCalcomServerErrorFunction;
+export declare function parseCalcomOAuthError(responseError: FetchResponseError): Promise<ParsedCalcomServerError>;
+export declare function parseCalcomOAuthServerErrorResponseData(calcomServerError: CalcomServerErrorData, responseError: FetchResponseError): ParsedCalcomServerError;
+export declare const handleCalcomOAuthErrorFetch: import("..").HandleCalcomErrorFetchFactory;

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

@@ -0,0 +1,31 @@
+import { type CalcomOAuthConfig, type CalcomOAuthContextRef, type CalcomOAuthFetchFactory } from './oauth.config';
+import { type LogCalcomServerErrorFunction } from '../calcom.error.api';
+import { type CalcomAccessTokenCache, type CalcomAccessTokenFactory, type CalcomAccessTokenRefresher } from './oauth';
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+export type CalcomOAuth = CalcomOAuthContextRef;
+export interface CalcomOAuthFactoryConfig {
+    /**
+     * Creates a new fetch instance to use when making calls.
+     */
+    fetchFactory?: CalcomOAuthFetchFactory;
+    /**
+     * Custom log error function.
+     */
+    logCalcomServerErrorFunction?: LogCalcomServerErrorFunction;
+}
+export type CalcomOAuthFactory = (config: CalcomOAuthConfig) => CalcomOAuth;
+export declare function calcomOAuthFactory(factoryConfig: CalcomOAuthFactoryConfig): CalcomOAuthFactory;
+export interface CalcomOAuthAccessTokenFactoryConfig {
+    /**
+     * Number of milliseconds before the expiration time a token should be discarded.
+     *
+     * Defaults to 1 minute.
+     */
+    readonly tokenExpirationBuffer?: Milliseconds;
+    readonly tokenRefresher: CalcomAccessTokenRefresher;
+    readonly accessTokenCache?: Maybe<CalcomAccessTokenCache>;
+}
+/**
+ * Creates a CalcomAccessTokenFactory with multi-tier caching.
+ */
+export declare function calcomOAuthAccessTokenFactory(config: CalcomOAuthAccessTokenFactoryConfig): CalcomAccessTokenFactory;

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

@@ -0,0 +1,17 @@
+/**
+ * Cal.com API version header constants.
+ *
+ * Each endpoint group requires a specific cal-api-version header value.
+ */
+export declare const CALCOM_API_VERSION_SCHEDULES = "2024-06-11";
+export declare const CALCOM_API_VERSION_SLOTS = "2024-09-04";
+export declare const CALCOM_API_VERSION_BOOKINGS = "2024-08-13";
+export declare const CALCOM_API_VERSION_EVENT_TYPES = "2024-06-14";
+export declare const CALCOM_API_VERSION_CALENDARS = "2024-06-11";
+export declare const CALCOM_API_VERSION_ME = "2024-08-13";
+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.
+ */
+export declare function calcomApiVersionHeaders(version: CalcomApiVersionString): Record<string, string>;

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

@@ -0,0 +1 @@
+export * from './calcom.api-version';