@dereekb/calcom 13.4.0 → 13.4.2

package/index.esm.js

@@ -265,7 +265,7 @@ function _ts_generator$5(thisArg, body) {
  * 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
  */ function logCalcomServerErrorFunction(calcomApiNamePrefix) {
     return function(error) {
         if (_instanceof(error, CalcomServerFetchResponseError)) {
@@ -286,6 +286,10 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * 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
  */ function handleCalcomErrorFetchFactory(parseCalcomError, defaultLogError) {
     return function(fetch) {
         var logError = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : defaultLogError;
@@ -348,7 +352,12 @@ var CALCOM_RATE_LIMIT_REMAINING_HEADER = 'X-RateLimit-Remaining';
 var CALCOM_RATE_LIMIT_RESET_HEADER = 'X-RateLimit-Reset';
 var DEFAULT_CALCOM_API_RATE_LIMIT = 100;
 var DEFAULT_CALCOM_API_RATE_LIMIT_RESET_PERIOD = 60 * MS_IN_SECOND;
-function calcomRateLimitHeaderDetails(headers) {
+/**
+ * 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
+ */ function calcomRateLimitHeaderDetails(headers) {
     var limitHeader = headers.get(CALCOM_RATE_LIMIT_LIMIT_HEADER);
     var remainingHeader = headers.get(CALCOM_RATE_LIMIT_REMAINING_HEADER);
     var resetHeader = headers.get(CALCOM_RATE_LIMIT_RESET_HEADER);
@@ -383,6 +392,10 @@ var CalcomTooManyRequestsError = /*#__PURE__*/ function(CalcomServerFetchRespons
 }(CalcomServerFetchResponseError);
 /**
  * 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
  */ function parseCalcomServerErrorData(calcomServerError, responseError) {
     var result;
     if (responseError.response.status === CALCOM_TOO_MANY_REQUESTS_HTTP_STATUS_CODE) {
@@ -532,7 +545,13 @@ function _ts_generator$4(thisArg, body) {
 }
 // MARK: Parser
 var logCalcomErrorToConsole = logCalcomServerErrorFunction('Calcom');
-function parseCalcomApiError(responseError) {
+/**
+ * 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
+ */ function parseCalcomApiError(responseError) {
     return _async_to_generator$4(function() {
         var data, result;
         return _ts_generator$4(this, function(_state) {
@@ -557,7 +576,14 @@ function parseCalcomApiError(responseError) {
         });
     })();
 }
-function parseCalcomApiServerErrorResponseData(calcomServerError, responseError) {
+/**
+ * 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
+ */ function parseCalcomApiServerErrorResponseData(calcomServerError, responseError) {
     var result;
     if (calcomServerError) {
         switch(calcomServerError.code){
@@ -805,7 +831,13 @@ function _ts_generator$3(thisArg, body) {
     return CalcomOAuthAuthFailureError;
 }(FetchRequestFactoryError);
 var logCalcomOAuthErrorToConsole = logCalcomServerErrorFunction('CalcomOAuth');
-function parseCalcomOAuthError(responseError) {
+/**
+ * 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
+ */ function parseCalcomOAuthError(responseError) {
     return _async_to_generator$3(function() {
         var data, result;
         return _ts_generator$3(this, function(_state) {
@@ -830,7 +862,15 @@ function parseCalcomOAuthError(responseError) {
         });
     })();
 }
-function parseCalcomOAuthServerErrorResponseData(calcomServerError, responseError) {
+/**
+ * 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
+ */ function parseCalcomOAuthServerErrorResponseData(calcomServerError, responseError) {
     var result;
     if (calcomServerError) {
         var potentialErrorStringCode = calcomServerError.error;
@@ -978,6 +1018,11 @@ function _ts_generator$2(thisArg, body) {
 }
 /**
  * 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
  */ function calcomAccessTokenStringFactory(calcomAccessTokenFactory) {
     return function() {
         return _async_to_generator$2(function() {
@@ -1007,7 +1052,13 @@ function _ts_generator$2(thisArg, body) {
 var DEFAULT_CALCOM_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION = function DEFAULT_CALCOM_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION(headers) {
     console.warn("calcomRateLimitedFetchHandler(): Too many requests made. The limit is ".concat(headers.limit, " requests per reset period. ResetAt is set for ").concat(headers.resetAt, "."));
 };
-function calcomRateLimitedFetchHandler(config) {
+/**
+ * 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
+ */ function calcomRateLimitedFetchHandler(config) {
     var _ref, _ref1, _ref2;
     var onTooManyRequests = (config === null || config === void 0 ? void 0 : config.onTooManyRequests) !== false ? (_ref = config === null || config === void 0 ? void 0 : config.onTooManyRequests) !== null && _ref !== void 0 ? _ref : DEFAULT_CALCOM_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION : undefined;
     var defaultLimit = (_ref1 = config === null || config === void 0 ? void 0 : config.maxRateLimit) !== null && _ref1 !== void 0 ? _ref1 : DEFAULT_CALCOM_API_RATE_LIMIT;
@@ -1037,8 +1088,8 @@ function calcomRateLimitedFetchHandler(config) {
                     if (response.status === CALCOM_TOO_MANY_REQUESTS_HTTP_STATUS_CODE) {
                         shouldRetry = true;
                         try {
-                            onTooManyRequests === null || onTooManyRequests === void 0 ? void 0 : onTooManyRequests(headerDetails, response, fetchResponseError);
-                        } catch (_) {
+                            void (onTooManyRequests === null || onTooManyRequests === void 0 ? void 0 : onTooManyRequests(headerDetails, response, fetchResponseError));
+                        } catch (unused) {
                         // ignore logging errors
                         }
                     }
@@ -1055,8 +1106,8 @@ function calcomRateLimitedFetchHandler(config) {
                 shouldRetry = true;
                 try {
                     var headerDetails1 = {};
-                    onTooManyRequests === null || onTooManyRequests === void 0 ? void 0 : onTooManyRequests(headerDetails1, response, fetchResponseError);
-                } catch (_) {
+                    void (onTooManyRequests === null || onTooManyRequests === void 0 ? void 0 : onTooManyRequests(headerDetails1, response, fetchResponseError));
+                } catch (unused) {
                 // ignore logging errors
                 }
             }
@@ -1197,7 +1248,14 @@ function _ts_generator$1(thisArg, body) {
         };
     }
 }
-function calcomFactory(factoryConfig) {
+/**
+ * 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
+ */ function calcomFactory(factoryConfig) {
     var oauthContext = factoryConfig.oauthContext;
     var serverAccessTokenStringFactory = calcomAccessTokenStringFactory(oauthContext.loadAccessToken);
     var fetchHandler = calcomRateLimitedFetchHandler(factoryConfig.rateLimiterConfig);
@@ -1336,6 +1394,9 @@ var CALCOM_API_VERSION_ME = '2024-08-13';
 var 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
  */ function calcomApiVersionHeaders(version) {
     return _define_property({}, CALCOM_API_VERSION_HEADER, version);
 }
@@ -1345,6 +1406,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)();
@@ -1364,6 +1428,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)();
@@ -1386,6 +1453,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)({
@@ -1414,6 +1484,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)({
@@ -1437,6 +1510,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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');
@@ -1455,6 +1531,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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' });
@@ -1478,6 +1557,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)();
@@ -1496,6 +1578,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)({
@@ -1519,6 +1604,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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' });
@@ -1537,6 +1625,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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);
@@ -1555,6 +1646,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)();
@@ -1573,6 +1667,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)({
@@ -1602,6 +1699,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)({
@@ -1624,6 +1724,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)();
@@ -1641,6 +1744,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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);
@@ -1658,6 +1764,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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 });
@@ -1675,6 +1784,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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);
@@ -1695,6 +1807,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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' });
@@ -1724,6 +1839,9 @@ var CALCOM_API_VERSION_HEADER = 'cal-api-version';
  *
  * @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)({
@@ -1883,7 +2001,14 @@ function _ts_generator(thisArg, body) {
         };
     }
 }
-function calcomOAuthFactory(factoryConfig) {
+/**
+ * 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
+ */ function calcomOAuthFactory(factoryConfig) {
     var fetchHandler = calcomRateLimitedFetchHandler();
     var logCalcomServerErrorFunction = factoryConfig.logCalcomServerErrorFunction, _factoryConfig_fetchFactory = factoryConfig.fetchFactory, fetchFactory = _factoryConfig_fetchFactory === void 0 ? function(_) {
         return fetchApiFetchService.makeFetch({
@@ -2038,6 +2163,11 @@ function calcomOAuthFactory(factoryConfig) {
 }
 /**
  * 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
  */ function calcomOAuthAccessTokenFactory(config) {
     var tokenRefresher = config.tokenRefresher, accessTokenCache = config.accessTokenCache, inputTokenExpirationBuffer = config.tokenExpirationBuffer;
     var tokenExpirationBuffer = inputTokenExpirationBuffer !== null && inputTokenExpirationBuffer !== void 0 ? inputTokenExpirationBuffer : MS_IN_MINUTE;