@dereekb/calcom 13.32.0 → 13.34.0

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

@@ -1,11 +1,12 @@
-import { type CalcomAccessToken, type CalcomAccessTokenCache, type CalcomRefreshToken } from '@dereekb/calcom';
+import { type CalcomAccessToken, type CalcomAccessTokenCache, type CalcomAccessTokenCacheKey, 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.
+ * keyed either by a caller-owned key ({@link cacheForKey}) or by the user's refresh token
+ * ({@link cacheForRefreshToken}).
  */
 export declare abstract class CalcomOAuthAccessTokenCacheService {
     /**
@@ -13,15 +14,27 @@ export declare abstract class CalcomOAuthAccessTokenCacheService {
      */
     abstract loadCalcomAccessTokenCache(): CalcomAccessTokenCache;
     /**
-     * Creates or retrieves a cache for a specific user context, keyed by the refresh token.
+     * Creates or retrieves a cache for a specific user context, keyed by a stable caller-owned key.
      *
-     * 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.
+     * Prefer this over {@link cacheForRefreshToken}: a key the caller already owns (a user or
+     * profile id) survives refresh-token rotation, so the same entry is found on every boot.
+     */
+    abstract cacheForKey?(key: CalcomAccessTokenCacheKey): CalcomAccessTokenCache;
+    /**
+     * Creates or retrieves a cache for a specific user context, keyed by a hash of the refresh token.
+     *
+     * The cache instance persists the rotated token in-place, so reads return the latest token for
+     * as long as the *original* refresh token keeps being used as the lookup key. Because Cal.com
+     * rotates the refresh token on every use, that only holds within a single process lifetime:
+     * once a rotated token is persisted and then used as the key, the key changes and the previous
+     * entry is orphaned.
+     *
+     * Prefer {@link cacheForKey} with a stable id for anything that outlives one process.
      */
     abstract cacheForRefreshToken?(refreshToken: CalcomRefreshToken): CalcomAccessTokenCache;
 }
-export type CalcomOAuthAccessTokenCacheServiceWithRefreshToken = Required<CalcomOAuthAccessTokenCacheService>;
+export type CalcomOAuthAccessTokenCacheServiceWithRefreshToken = Required<Pick<CalcomOAuthAccessTokenCacheService, 'cacheForRefreshToken'>> & CalcomOAuthAccessTokenCacheService;
+export type CalcomOAuthAccessTokenCacheServiceWithKey = Required<Pick<CalcomOAuthAccessTokenCacheService, 'cacheForKey'>> & CalcomOAuthAccessTokenCacheService;
 /**
  * Derives a short, filesystem-safe cache key from a refresh token.
  *
@@ -31,6 +44,17 @@ export type CalcomOAuthAccessTokenCacheServiceWithRefreshToken = Required<Calcom
  * @returns A 16-character hex string suitable for use as a cache key.
  */
 export declare function calcomRefreshTokenCacheKey(refreshToken: string): string;
+/**
+ * Converts a cache key into a filesystem-safe path segment.
+ *
+ * A key that is already safe (such as the hex output of {@link calcomRefreshTokenCacheKey}) is
+ * returned unchanged. Otherwise the unsafe characters are replaced and a hash of the original key
+ * is appended, so two different keys can never collapse onto the same file.
+ *
+ * @param key - The cache key to convert.
+ * @returns A filesystem-safe path segment for the key.
+ */
+export declare function calcomAccessTokenCacheFileKey(key: CalcomAccessTokenCacheKey): string;
 export type LogMergeCalcomOAuthAccessTokenCacheServiceErrorFunction = (failedUpdates: (readonly [CalcomAccessTokenCache, unknown])[]) => void;
 /**
  * Default error logging function for {@link mergeCalcomOAuthAccessTokenCacheServices}.

package/package.json

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

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

@@ -1,7 +1,8 @@
-import { type FactoryWithRequiredInput, type Maybe } from '@dereekb/util';
+import { type FactoryWithRequiredInput } 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 CalcomConfig } from '../calcom.config';
+import { type CalcomAccessTokenStringFactory } from '../oauth/oauth';
+import { type CalcomRefreshTokenCredential } from '../oauth/oauth.config';
 import { type CalcomRateLimiterRef } from '../calcom.limit';
 export interface CalcomFetchFactoryInput {
     readonly calcomAccessTokenStringFactory: CalcomAccessTokenStringFactory;
@@ -30,22 +31,14 @@ export interface CalcomUserContext extends CalcomContext {
     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.
+ * Creates a CalcomUserContext from a user's credential.
+ *
+ * Deliberately the refresh-token arm of {@link CalcomAuthCredential} rather than the full union: a
+ * user context acts as a connected user, while an api key acts as whoever created it — which is the
+ * server context's job.
  */
-export type CalcomUserContextFactory = FactoryWithRequiredInput<CalcomUserContext, CalcomUserContextFactoryInput>;
+export type CalcomUserContextFactory = FactoryWithRequiredInput<CalcomUserContext, CalcomRefreshTokenCredential>;
 /**
  * Context for making public (unauthenticated) requests to the Cal.com API.
  */

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

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

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

@@ -1,9 +1,16 @@
 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';
+import { type Seconds } from '@dereekb/util';
 export interface CalcomOAuthRefreshTokenInput {
-    readonly refreshToken?: Maybe<CalcomRefreshToken>;
+    /**
+     * The refresh token to exchange.
+     *
+     * Required, and deliberately not defaulted from the context's configuration: Cal.com rotates
+     * refresh tokens on every use, so the configured value is spent the first time the context
+     * refreshes. Every caller therefore has to name the token it actually holds.
+     */
+    readonly refreshToken: CalcomRefreshToken;
 }
 export interface CalcomOAuthExchangeAuthorizationCodeInput {
     readonly code: string;
@@ -26,7 +33,7 @@ export interface CalcomOAuthAccessTokenErrorResponse {
  * Cal.com uses JSON body (not Basic Auth) for token requests.
  *
  * @param context - The Cal.com OAuth context providing client credentials and fetch capabilities.
- * @returns Refreshes an access token using an optional refresh token override.
+ * @returns Refreshes an access token using the given refresh token.
  *
  * @see https://cal.com/docs/api-reference/v2/oauth/refresh-an-existing-access-token
  *
@@ -36,7 +43,7 @@ export interface CalcomOAuthAccessTokenErrorResponse {
  * console.log(response.access_token, response.refresh_token);
  * ```
  */
-export declare function refreshAccessToken(context: CalcomOAuthContext): (input?: CalcomOAuthRefreshTokenInput) => Promise<CalcomOAuthTokenResponse>;
+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.

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

@@ -0,0 +1,91 @@
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { type CalcomOAuthClientId } from '../calcom.config';
+/**
+ * Every granular Cal.com OAuth scope.
+ *
+ * A runtime list rather than a bare type union, so a configured scope can be validated instead of
+ * being passed through to the consent screen and refused there.
+ *
+ * @see https://cal.com/docs/api-reference/v2/oauth
+ */
+export declare const ALL_CALCOM_OAUTH_SCOPES: readonly ["PROFILE_READ", "PROFILE_WRITE", "BOOKING_READ", "BOOKING_WRITE", "SCHEDULE_READ", "SCHEDULE_WRITE", "EVENT_TYPE_READ", "EVENT_TYPE_WRITE", "APPS_READ", "APPS_WRITE", "WEBHOOK_READ", "WEBHOOK_WRITE"];
+/**
+ * A granular Cal.com OAuth scope.
+ */
+export type CalcomOAuthScope = (typeof ALL_CALCOM_OAUTH_SCOPES)[number];
+/**
+ * Returns whether the input is a known {@link CalcomOAuthScope}.
+ *
+ * @param value - The value to check.
+ * @returns True when the value is a known Cal.com OAuth scope.
+ */
+export declare function isCalcomOAuthScope(value: string): value is CalcomOAuthScope;
+/**
+ * The delimiter used to join scopes in the `scope` query parameter.
+ *
+ * OAuth2 specifies a space-delimited list. Cal.com's granular scopes are documented without an
+ * explicit delimiter, so this is isolated here: if the consent screen rejects the `scope`
+ * parameter, this is the only value that needs to change.
+ */
+export declare const CALCOM_OAUTH_SCOPE_DELIMITER = " ";
+/**
+ * The `response_type` used by the authorization-code flow.
+ */
+export declare const CALCOM_OAUTH_AUTHORIZE_RESPONSE_TYPE = "code";
+export interface CalcomOAuthAuthorizeUrlFactoryConfig {
+    /**
+     * The OAuth client id to authorize as.
+     */
+    readonly clientId: CalcomOAuthClientId;
+    /**
+     * The redirect URI to return to after the user consents.
+     *
+     * Must match the URI registered on the Cal.com OAuth client byte-for-byte, including the port,
+     * and must be identical to the `redirectUri` later passed to the token exchange.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The scopes to request.
+     */
+    readonly scopes: readonly CalcomOAuthScope[];
+    /**
+     * Optional override of the authorize URL. Defaults to {@link CALCOM_OAUTH_AUTHORIZE_URL}.
+     */
+    readonly authorizeUrl?: Maybe<WebsiteUrl>;
+}
+export interface CalcomOAuthAuthorizeUrlParams {
+    /**
+     * Opaque state echoed back to the redirect URI.
+     *
+     * Carries the acting user and is the CSRF defense for the handoff, so it should be signed and
+     * short-lived.
+     */
+    readonly state?: Maybe<string>;
+}
+export type CalcomOAuthAuthorizeUrlFactory = (params?: Maybe<CalcomOAuthAuthorizeUrlParams>) => WebsiteUrl;
+/**
+ * Creates a {@link CalcomOAuthAuthorizeUrlFactory} that composes the Cal.com authorize URL that a
+ * user's browser is redirected to in order to begin the authorization-code flow.
+ *
+ * The client id, redirect URI, and scopes are fixed by the config, since a consumer holds those
+ * constant and varies only the per-request `state`.
+ *
+ * @param config - The client id, redirect URI, and scopes to request.
+ * @returns A factory that builds an authorize URL for the given params.
+ *
+ * @see https://cal.com/docs/api-reference/v2/oauth
+ *
+ * @example
+ * ```ts
+ * const authorizeUrlFactory = calcomOAuthAuthorizeUrlFactory({
+ *   clientId: 'client-id',
+ *   redirectUri: 'http://localhost:9901/oauth/calcom/callback',
+ *   scopes: ['PROFILE_READ', 'BOOKING_READ']
+ * });
+ *
+ * const url = authorizeUrlFactory({ state: 'signed-state' });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calcomOAuthAuthorizeUrlFactory(config: CalcomOAuthAuthorizeUrlFactoryConfig): CalcomOAuthAuthorizeUrlFactory;

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

@@ -3,51 +3,146 @@ import { type ConfiguredFetch, type FetchJsonFunction } from '@dereekb/util/fetc
 import { type CalcomApiKey, type CalcomAuthClientIdAndSecretPair, type CalcomRefreshToken } from '../calcom.config';
 import { type CalcomAccessTokenCache, type CalcomAccessTokenFactory } from './oauth';
 /**
- * The Cal.com OAuth token endpoint URL.
+ * The Cal.com OAuth API base URL.
+ *
+ * Endpoint paths are appended to this base, so it intentionally carries no endpoint segment of
+ * its own. This is the single place the OAuth host and prefix are encoded.
  */
-export declare const CALCOM_OAUTH_TOKEN_URL = "https://api.cal.com/v2/oauth/token";
+export declare const CALCOM_OAUTH_API_URL = "https://api.cal.com/v2/auth/oauth2";
+export type CalcomOAuthApiUrl = typeof CALCOM_OAUTH_API_URL;
+/**
+ * The Cal.com OAuth token endpoint path, relative to {@link CALCOM_OAUTH_API_URL}.
+ */
+export declare const CALCOM_OAUTH_TOKEN_PATH = "/token";
 /**
  * The Cal.com OAuth authorize URL.
  */
 export declare const CALCOM_OAUTH_AUTHORIZE_URL = "https://app.cal.com/auth/oauth2/authorize";
 /**
- * Configuration for CalcomOAuth.
+ * Authenticates as the Cal.com user who created the API key.
+ *
+ * The key IS the bearer token and does not expire, so this credential never reaches the token
+ * endpoint and needs no {@link CalcomOAuthConfig.client}.
  */
-export interface CalcomOAuthConfig extends Partial<CalcomAuthClientIdAndSecretPair> {
+export interface CalcomApiKeyCredential {
+    readonly apiKey: CalcomApiKey;
+}
+/**
+ * Authenticates as the Cal.com user who granted the refresh token.
+ *
+ * Every exchange is authenticated with {@link CalcomOAuthConfig.client}'s id and secret, so this
+ * credential is unusable without one.
+ */
+export interface CalcomRefreshTokenCredential {
     /**
-     * Optional CalcomAccessTokenCache for caching access tokens.
+     * The grant's refresh token.
+     *
+     * Cal.com rotates it on every use. The factory built from this credential tracks the rotation in
+     * memory, so this value is read once rather than re-read per refresh.
      */
-    readonly accessTokenCache?: Maybe<CalcomAccessTokenCache>;
+    readonly refreshToken: CalcomRefreshToken;
     /**
-     * Server-level refresh token for initial authentication.
+     * Cache for THIS credential's access token.
+     *
+     * Must be scoped to exactly this grant. Two credentials sharing one cache overwrite each other,
+     * and the rotated refresh token rides along inside the cached value — so a shared cache does not
+     * merely lose a token, it spends one.
      */
+    readonly accessTokenCache?: Maybe<CalcomAccessTokenCache>;
+}
+/**
+ * A credential Cal.com calls can be made with.
+ *
+ * One union for the ambient credential and for any per-user one, because they are the same thing:
+ * a way to act as some Cal.com user. Discriminated by the presence of `apiKey`.
+ */
+export type CalcomAuthCredential = CalcomApiKeyCredential | CalcomRefreshTokenCredential;
+/**
+ * Returns whether the credential is a {@link CalcomApiKeyCredential}.
+ *
+ * @param credential - The credential to check.
+ * @returns True when the credential carries an api key.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isCalcomApiKeyCredential(credential: CalcomAuthCredential): credential is CalcomApiKeyCredential;
+export interface CalcomAuthCredentialValues {
+    readonly apiKey?: Maybe<CalcomApiKey>;
     readonly refreshToken?: Maybe<CalcomRefreshToken>;
+    readonly accessTokenCache?: Maybe<CalcomAccessTokenCache>;
+}
+/**
+ * Builds a {@link CalcomAuthCredential} from flat, optional values, as an environment-facing
+ * configuration provides them.
+ *
+ * An api key wins when both are present: it does not expire, so it skips the refresh loop entirely.
+ * The cache attaches only to the refresh-token arm, since an api key has no token to cache. Empty
+ * strings count as absent, so an unset environment variable read as `''` does not become a
+ * credential that sends `Bearer `.
+ *
+ * @param values - The flat credential values.
+ * @returns The equivalent credential, or undefined when neither value is present.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calcomAuthCredentialFromValues(values: CalcomAuthCredentialValues): Maybe<CalcomAuthCredential>;
+/**
+ * Configuration for CalcomOAuth.
+ *
+ * `client` is the app's OAuth *registration*. It is sent on EVERY token exchange — the ambient one
+ * as much as any per-user one — so it is not "the user half" of anything.
+ *
+ * `defaultAuth` is the credential used when no specific one is named, and is the only thing
+ * `loadAccessToken()` reads. It is not an "app identity" either: an api key acts as the user who
+ * created it, and a refresh token here is some user's grant being reused ambiently.
+ *
+ * An app that only acts for named users needs just `client`. An app that makes ambient calls needs
+ * a `defaultAuth`, plus `client` whenever that credential is a refresh token.
+ */
+export interface CalcomOAuthConfig {
     /**
-     * Optional API key for simple bearer token auth.
+     * The OAuth client registration, required for ANY refresh-token exchange.
      *
-     * 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.
+     * Both halves of the pair are required together, so a client cannot be half-configured into a state
+     * that composes an authorize URL carrying `client_id=undefined`.
      */
-    readonly apiKey?: Maybe<CalcomApiKey>;
+    readonly client?: Maybe<CalcomAuthClientIdAndSecretPair>;
+    /**
+     * The credential used when no specific one is named.
+     */
+    readonly defaultAuth?: Maybe<CalcomAuthCredential>;
 }
 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>;
+export type CalcomOAuthMakeAccessTokenFactory = FactoryWithRequiredInput<CalcomAccessTokenFactory, CalcomAuthCredential>;
 /**
  * Context used for performing fetch() and fetchJson() calls with a configured fetch instance.
  */
 export interface CalcomOAuthContext {
     readonly fetch: ConfiguredFetch;
     readonly fetchJson: FetchJsonFunction;
+    /**
+     * Resolves the access token for {@link CalcomOAuthConfig.defaultAuth}.
+     *
+     * `makeAccessTokenFactory(config.defaultAuth)`, built once at construction so its in-memory token
+     * tier and its refresh-token rotation are shared across the whole context.
+     */
     readonly loadAccessToken: CalcomAccessTokenFactory;
-    readonly makeUserAccessTokenFactory: CalcomOAuthMakeUserAccessTokenFactory;
+    /**
+     * Builds an access token factory for one credential.
+     *
+     * Each returned factory owns its own rotation and cache tier, so refreshing one credential never
+     * spends another's token.
+     */
+    readonly makeAccessTokenFactory: CalcomOAuthMakeAccessTokenFactory;
     readonly config: CalcomOAuthConfig;
 }
 export interface CalcomOAuthContextRef {
     readonly oauthContext: CalcomOAuthContext;
 }
+/**
+ * @deprecated use {@link CALCOM_OAUTH_API_URL} instead. This was previously used as the fetch base
+ * URL while the endpoint path `/oauth/token` was also appended, resolving to a doubly-pathed URL.
+ */
+export declare const CALCOM_OAUTH_TOKEN_URL = "https://api.cal.com/v2/auth/oauth2/token";

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

@@ -27,6 +27,13 @@ export interface CalcomAccessToken {
      */
     readonly expiresAt: Date;
 }
+/**
+ * A stable key identifying a cached CalcomAccessToken.
+ *
+ * Should be owned by the caller (a user/profile id) rather than derived from the refresh token,
+ * since Cal.com rotates refresh tokens on every use and a token-derived key changes with them.
+ */
+export type CalcomAccessTokenCacheKey = string;
 /**
  * Used for retrieving and storing CalcomAccessToken values.
  */

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

@@ -1,13 +1,53 @@
+import { type FetchHandler } from '@dereekb/util/fetch';
 import { type CalcomOAuthConfig, type CalcomOAuthContextRef, type CalcomOAuthFetchFactory } from './oauth.config';
+import { type CalcomApiKey } from '../calcom.config';
 import { type LogCalcomServerErrorFunction } from '../calcom.error.api';
-import { type CalcomAccessTokenCache, type CalcomAccessTokenFactory, type CalcomAccessTokenRefresher } from './oauth';
+import { type CalcomAccessToken, type CalcomAccessTokenCache, type CalcomAccessTokenFactory, type CalcomAccessTokenRefresher } from './oauth';
 import { type Maybe, type Milliseconds } from '@dereekb/util';
+import { type CalcomOAuthTokenResponse } from './oauth.api';
 export type CalcomOAuth = CalcomOAuthContextRef;
+/**
+ * Maps a {@link CalcomOAuthTokenResponse} to a {@link CalcomAccessToken}.
+ *
+ * Pure: the caller owns the rotated refresh token that comes back on the result, so each token
+ * scope (server-level vs per-user) tracks its own rotation instead of sharing one variable.
+ *
+ * @param response - The token response returned by the Cal.com token endpoint.
+ * @returns The equivalent CalcomAccessToken, with `expiresAt` resolved against the current time.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calcomAccessTokenFromTokenResponse(response: CalcomOAuthTokenResponse): CalcomAccessToken;
+/**
+ * The lifetime given to the synthetic access token an api key is wrapped in.
+ *
+ * Cal.com api keys do not expire; the value only has to outlive any process holding one, so the
+ * token satisfies the same expiration check every other token goes through.
+ */
+export declare const CALCOM_API_KEY_ACCESS_TOKEN_EXPIRATION: Milliseconds;
+/**
+ * Wraps a {@link CalcomApiKey} as a static {@link CalcomAccessToken}.
+ *
+ * An api key is already a bearer token acting as the user who created it, so there is nothing to
+ * exchange and nothing to refresh.
+ *
+ * @param apiKey - The Cal.com api key.
+ * @returns The equivalent static CalcomAccessToken.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calcomAccessTokenFromApiKey(apiKey: CalcomApiKey): CalcomAccessToken;
 export interface CalcomOAuthFactoryConfig {
     /**
      * Creates a new fetch instance to use when making calls.
      */
     readonly fetchFactory?: CalcomOAuthFetchFactory;
+    /**
+     * Custom FetchHandler to use with the default fetchFactory.
+     *
+     * Defaults to a {@link calcomRateLimitedFetchHandler}. Ignored when a `fetchFactory` is provided.
+     */
+    readonly fetchHandler?: Maybe<FetchHandler>;
     /**
      * Custom log error function.
      */