timezest 1.1.2 → 1.1.4

package/LICENSE

@@ -1,9 +1,9 @@
-MIT License
-
-Copyright (c) 2025 PNC IT
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
+MIT License
+
+Copyright (c) 2025 PNC IT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -133,29 +133,51 @@ async function fetchAllResources() {
 fetchAllResources();
 ```
 
-## Retry Logic
+## Rate Limiting and Retry Logic
 
-The `TimeZestAPI` class includes built-in retry logic for handling transient errors, such as network issues or rate-limiting responses from the TimeZest API. You can configure the retry behavior using the following options when initializing the class:
+The `TimeZestAPI` class includes intelligent retry logic optimized for TimeZest's API limits. TimeZest enforces a **maximum of 180 requests in any 60-second sliding window**.
 
-- **`maxRetryTimeMs`**: The maximum amount of time (in milliseconds) to spend retrying a request. Defaults to a reasonable value defined in the configuration.
-- **`maxRetryDelayMs`**: The maximum delay (in milliseconds) between retry attempts. This helps prevent excessive delays during retries.
+### Retry Strategy
+
+When a request fails due to rate limiting (429 Too Many Requests), the library automatically retries with an optimized strategy:
+
+- **Aggressive Exponential Backoff**: Starts at 1 second and doubles with each retry (1s, 2s, 4s, 8s, 16s, 32s, 64s...)
+- **Jitter**: Adds ±25% random variation to retry delays to prevent a thundering herd problem when multiple clients hit rate limits simultaneously
+- **Retry-After Header**: Always respects the `Retry-After` header from 429 responses when provided by the API
+- **Patient by Default**: Will retry for up to 5 minutes by default, allowing time for rate limit windows to clear
+- **Configurable**: Full control over retry behavior via configuration options
+
+### Configuration Options
+
+You can configure the retry behavior using the following options when initializing the class:
+
+- **`maxRetryTimeMs`**: The maximum amount of time (in milliseconds) to spend retrying a request. Defaults to 5 minutes (300,000ms).
+- **`maxRetryDelayMs`**: The maximum delay (in milliseconds) between individual retry attempts. Defaults to 60 seconds (60,000ms).
 
 ### Example Configuration
 
 ```typescript
 const options = {
-  maxRetryTimeMs: 30000, // Retry for up to 30 seconds
-  maxRetryDelayMs: 2000, // Wait up to 2 seconds between retries
+  maxRetryTimeMs: 10 * 60 * 1000, // Retry for up to 10 minutes
+  maxRetryDelayMs: 60 * 1000, // Max 60 seconds between retries
+  logLevel: "debug", // See detailed retry information in logs
 };
 
 const timeZest = new TimeZestAPI("your-api-key", options);
 ```
 
-### How It Works
+### Retry Behavior Example
 
-When a request fails due to a transient error (e.g., a 429 Too Many Requests response or a network timeout), the library will automatically retry the request until the `maxRetryTimeMs` limit is reached. The delay between retries is capped by `maxRetryDelayMs` and may increase with each attempt to avoid overwhelming the server.
+If you hit a rate limit without a `Retry-After` header, the retry delays will be:
+- 1st retry: ~1 second (0.75-1.25s with jitter)
+- 2nd retry: ~2 seconds (1.5-2.5s with jitter)  
+- 3rd retry: ~4 seconds (3-5s with jitter)
+- 4th retry: ~8 seconds (6-10s with jitter)
+- 5th retry: ~16 seconds (12-20s with jitter)
+- 6th retry: ~32 seconds (24-40s with jitter)
+- 7th+ retry: ~60 seconds (45-60s with jitter, capped at maxRetryDelayMs)
 
-This retry logic ensures that your application can gracefully handle temporary issues without requiring manual intervention.
+The jitter ensures that if multiple clients hit the rate limit at the same time, they won't all retry simultaneously.
 
 ## Logging
 

package/{config → dist/config}/config.d.ts

@@ -30,5 +30,8 @@ export interface TimeZestAPIConfig {
 }
 /**
  * Default configuration for the TimeZest API client.
+ *
+ * Rate limit: 180 requests per 60 seconds (sliding window)
+ * Retry strategy: Aggressive exponential backoff with jitter
  */
 export declare const CONFIG: TimeZestAPIConfig;

package/{config → dist/config}/config.js

@@ -4,13 +4,16 @@ exports.CONFIG = void 0;
 const logger_1 = require("../utils/logger");
 /**
  * Default configuration for the TimeZest API client.
+ *
+ * Rate limit: 180 requests per 60 seconds (sliding window)
+ * Retry strategy: Aggressive exponential backoff with jitter
  */
 exports.CONFIG = {
     logLevel: "error",
     logger: logger_1.defaultLogger,
     baseUrl: "https://api.timezest.com/v1",
-    maxRetryDelayMs: 1.5 * 60 * 1000, // 1.5 minutes
-    maxRetryTimeMs: 15 * 1000, // 15 seconds
+    maxRetryDelayMs: 60 * 1000, // 60 seconds (aligned with rate limit window)
+    maxRetryTimeMs: 5 * 60 * 1000, // 5 minutes (be patient with retries)
     outputValidation: true,
 };
 //# sourceMappingURL=config.js.map

package/dist/config/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":";;;AAAA,4CAAkE;AAqClE;;;;;GAKG;AACU,QAAA,MAAM,GAAsB;IACvC,QAAQ,EAAE,OAAO;IACjB,MAAM,EAAE,sBAAa;IACrB,OAAO,EAAE,6BAA6B;IACtC,eAAe,EAAE,EAAE,GAAG,IAAI,EAAE,8CAA8C;IAC1E,cAAc,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,sCAAsC;IACrE,gBAAgB,EAAE,IAAI;CACvB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { log, LogLevel, Logger } from "./utils/logger";
+import { TimeZestAPIConfig } from "./config/config";
+import { Agent, Resource, AppointmentType, SchedulingRequest, Team, SchedulingRequestPost } from "./entities/entities";
+import { TQLFilter } from "./utils/tqlFilter";
+export { Agent, Resource, AppointmentType, SchedulingRequest, SchedulingRequestPost, Team } from "./entities/entities";
+export { ResourceSchema, AgentSchema, AppointmentTypeSchema, SchedulingRequestSchema, TeamSchema } from "./entities/schemas";
+export { TQL, TQLFilter } from "./utils/tqlFilter";
+/**
+ * Options for configuring the TimeZest API.
+ */
+export interface TimeZestAPIOptions {
+    /** The log level for the API (e.g., 'info', 'debug'). */
+    logLevel?: LogLevel;
+    /** A custom logger implementation. */
+    logger?: Logger;
+    /** The base URL for the API. */
+    baseUrl?: string;
+    /** The maximum delay between retries, in milliseconds. */
+    maxRetryDelayMs?: number;
+    /** The maximum total retry time, in milliseconds. */
+    maxRetryTimeMs?: number;
+    /** Whether to use Zod validation for API responses. */
+    outputValidation?: boolean;
+}
+/**
+ * Represents the TimeZest API client.
+ * Provides methods to interact with the TimeZest API.
+ */
+export declare class TimeZestAPI {
+    private config;
+    private apiKey;
+    log: log;
+    /**
+     * Creates an instance of the TimeZestAPI client.
+     * @param apiKey - The API key for authenticating with the TimeZest API.
+     * @param options - Optional configuration options for the API client.
+     */
+    constructor(apiKey: string, options?: TimeZestAPIOptions);
+    /**
+     * Returns the API key used by this client instance.
+     * @returns {string} The API key for authenticating with the TimeZest API.
+     */
+    getApiKey(): string;
+    /**
+     * Returns the configuration object for this API client instance.
+     * @returns {TimeZestAPIConfig} The configuration for the API client.
+     */
+    getConfig(): TimeZestAPIConfig;
+    /**
+     * Fetches resources from the TimeZest API.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<Resource[]>} A promise that resolves to an array of resources.
+     */
+    getResources: (filter?: TQLFilter | string | null) => Promise<Resource[]>;
+    /**
+     * Fetches agents from the TimeZest API.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<Agent[]>} A promise that resolves to an array of agents.
+     */
+    getAgents(filter?: TQLFilter | string | null): Promise<Agent[]>;
+    /**
+     * Fetches teams from the TimeZest API.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<Team[]>} A promise that resolves to an array of teams.
+     */
+    getTeams(filter?: TQLFilter | string | null): Promise<Team[]>;
+    /**
+     * Fetches appointment types from the TimeZest API.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<AppointmentType[]>} A promise that resolves to an array of appointment types.
+     */
+    getAppointmentTypes(filter?: TQLFilter | string | null): Promise<AppointmentType[]>;
+    /**
+     * Fetches a scheduling request by its ID.
+     * @param {string} id - The ID of the scheduling request to fetch.
+     * @returns {Promise<SchedulingRequest>} A promise that resolves to the scheduling request.
+     */
+    getSchedulingRequest(id: string): Promise<SchedulingRequest>;
+    /**
+     * Fetches scheduling requests from the TimeZest API.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<SchedulingRequest[]>} A promise that resolves to an array of scheduling requests.
+     */
+    getSchedulingRequests(filter?: TQLFilter | string | null): Promise<SchedulingRequest[]>;
+    /**
+     * Creates a new scheduling request in the TimeZest API.
+     * @param {SchedulingRequestPost} data - The data for the new scheduling request.
+     * @returns {Promise<SchedulingRequest>} A promise that resolves to the created scheduling request.
+     */
+    createSchedulingRequest(data: SchedulingRequestPost): Promise<SchedulingRequest>;
+    /**
+     * Validates API responses using Zod schemas if outputValidation is enabled in the config.
+     * @param {T[]} response - The API response data to validate.
+     * @param {ZodSchema} schema - The Zod schema to validate against.
+     * @returns {T[]} The validated or raw response data.
+     */
+    private validateResponse;
+}
+export default TimeZestAPI;

package/{index.js → dist/index.js}

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimeZestAPI = exports.TeamSchema = exports.SchedulingRequestSchema = exports.AppointmentTypeSchema = exports.AgentSchema = exports.ResourceSchema = void 0;
+exports.TimeZestAPI = exports.TQLFilter = exports.TQL = exports.TeamSchema = exports.SchedulingRequestSchema = exports.AppointmentTypeSchema = exports.AgentSchema = exports.ResourceSchema = void 0;
 const schemas_1 = require("./entities/schemas");
 const config_1 = require("./config/config");
 const makeRequest_1 = require("./utils/makeRequest");
@@ -22,6 +22,9 @@ Object.defineProperty(exports, "AgentSchema", { enumerable: true, get: function
 Object.defineProperty(exports, "AppointmentTypeSchema", { enumerable: true, get: function () { return schemas_2.AppointmentTypeSchema; } });
 Object.defineProperty(exports, "SchedulingRequestSchema", { enumerable: true, get: function () { return schemas_2.SchedulingRequestSchema; } });
 Object.defineProperty(exports, "TeamSchema", { enumerable: true, get: function () { return schemas_2.TeamSchema; } });
+var tqlFilter_1 = require("./utils/tqlFilter");
+Object.defineProperty(exports, "TQL", { enumerable: true, get: function () { return tqlFilter_1.TQL; } });
+Object.defineProperty(exports, "TQLFilter", { enumerable: true, get: function () { return tqlFilter_1.TQLFilter; } });
 /**
  * Represents the TimeZest API client.
  * Provides methods to interact with the TimeZest API.
@@ -35,8 +38,8 @@ class TimeZestAPI {
     constructor(apiKey, options) {
         /**
          * Fetches resources from the TimeZest API.
-         * @param filter - Optional filter string to narrow down results.
-         * @returns A promise that resolves to an array of resources.
+         * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+         * @returns {Promise<Resource[]>} A promise that resolves to an array of resources.
          */
         this.getResources = (...args_1) => __awaiter(this, [...args_1], void 0, function* (filter = null) {
             const response = yield (0, makePaginatedRequest_1.makePaginatedRequest)(this, endpoints_1.API_ENDPOINTS.RESOURCES, "GET", null, filter);
@@ -65,23 +68,23 @@ class TimeZestAPI {
         this.createSchedulingRequest = (0, logger_1.withLogging)(this.createSchedulingRequest.bind(this), this, "createSchedulingRequest");
     }
     /**
-     * Retrieves the API key used by the client.
-     * @returns The API key.
+     * Returns the API key used by this client instance.
+     * @returns {string} The API key for authenticating with the TimeZest API.
      */
     getApiKey() {
         return this.apiKey;
     }
     /**
-     * Retrieves the configuration of the API client.
-     * @returns The API client configuration.
+     * Returns the configuration object for this API client instance.
+     * @returns {TimeZestAPIConfig} The configuration for the API client.
      */
     getConfig() {
         return this.config;
     }
     /**
      * Fetches agents from the TimeZest API.
-     * @param filter - Optional filter string to narrow down results.
-     * @returns A promise that resolves to an array of agents.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<Agent[]>} A promise that resolves to an array of agents.
      */
     getAgents() {
         return __awaiter(this, arguments, void 0, function* (filter = null) {
@@ -91,8 +94,8 @@ class TimeZestAPI {
     }
     /**
      * Fetches teams from the TimeZest API.
-     * @param filter - Optional filter string to narrow down results.
-     * @returns A promise that resolves to an array of teams.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<Team[]>} A promise that resolves to an array of teams.
      */
     getTeams() {
         return __awaiter(this, arguments, void 0, function* (filter = null) {
@@ -102,8 +105,8 @@ class TimeZestAPI {
     }
     /**
      * Fetches appointment types from the TimeZest API.
-     * @param filter - Optional filter string to narrow down results.
-     * @returns A promise that resolves to an array of appointment types.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<AppointmentType[]>} A promise that resolves to an array of appointment types.
      */
     getAppointmentTypes() {
         return __awaiter(this, arguments, void 0, function* (filter = null) {
@@ -113,8 +116,8 @@ class TimeZestAPI {
     }
     /**
      * Fetches a scheduling request by its ID.
-     * @param id - The ID of the scheduling request.
-     * @returns A promise that resolves to the scheduling request.
+     * @param {string} id - The ID of the scheduling request to fetch.
+     * @returns {Promise<SchedulingRequest>} A promise that resolves to the scheduling request.
      */
     getSchedulingRequest(id) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -124,8 +127,8 @@ class TimeZestAPI {
     }
     /**
      * Fetches scheduling requests from the TimeZest API.
-     * @param filter - Optional filter string to narrow down results.
-     * @returns A promise that resolves to an array of scheduling requests.
+     * @param {TQLFilter | string | null} [filter=null] - Optional filter (TQLFilter instance or string) to narrow down results.
+     * @returns {Promise<SchedulingRequest[]>} A promise that resolves to an array of scheduling requests.
      */
     getSchedulingRequests() {
         return __awaiter(this, arguments, void 0, function* (filter = null) {
@@ -134,9 +137,9 @@ class TimeZestAPI {
         });
     }
     /**
-     * Creates a new scheduling request.
-     * @param data - The data for the scheduling request.
-     * @returns A promise that resolves to the created scheduling request.
+     * Creates a new scheduling request in the TimeZest API.
+     * @param {SchedulingRequestPost} data - The data for the new scheduling request.
+     * @returns {Promise<SchedulingRequest>} A promise that resolves to the created scheduling request.
      */
     createSchedulingRequest(data) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -145,10 +148,10 @@ class TimeZestAPI {
         });
     }
     /**
-     * Validates API responses using Zod schemas if outputValidation is enabled.
-     * @param response - The API response data to validate.
-     * @param schema - The Zod schema to validate against.
-     * @returns The validated or raw response data.
+     * Validates API responses using Zod schemas if outputValidation is enabled in the config.
+     * @param {T[]} response - The API response data to validate.
+     * @param {ZodSchema} schema - The Zod schema to validate against.
+     * @returns {T[]} The validated or raw response data.
      */
     validateResponse(response, schema) {
         if (this.config.outputValidation) {

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/{utils → dist/utils}/makePaginatedRequest.d.ts

@@ -1,5 +1,6 @@
 import { apiEndpoint } from "../constants/endpoints";
 import { TimeZestAPI } from "../index";
+import { TQLFilter } from "./tqlFilter";
 /**
  * Makes a paginated API request.
  * @template T - The type of the response data.
@@ -7,7 +8,7 @@ import { TimeZestAPI } from "../index";
  * @param endpoint - The API endpoint to call.
  * @param method - The HTTP method (GET or POST).
  * @param data - The request payload.
- * @param filter - An optional filter string.
+ * @param filter - An optional filter string or TQLFilter instance.
  * @returns A promise that resolves to an array of response data.
  */
-export declare const makePaginatedRequest: <T>(apiInstance: TimeZestAPI, endpoint: apiEndpoint, method?: "GET" | "POST", data?: any, filter?: string | null) => Promise<T[]>;
+export declare const makePaginatedRequest: <T>(apiInstance: TimeZestAPI, endpoint: apiEndpoint, method?: "GET" | "POST", data?: any, filter?: TQLFilter | string | null) => Promise<T[]>;

package/{utils → dist/utils}/makePaginatedRequest.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.makePaginatedRequest = void 0;
 const makeRequest_1 = require("./makeRequest");
 const handleError_1 = require("./handleError");
+const tqlFilter_1 = require("./tqlFilter");
 /**
  * Makes a paginated API request.
  * @template T - The type of the response data.
@@ -19,7 +20,7 @@ const handleError_1 = require("./handleError");
  * @param endpoint - The API endpoint to call.
  * @param method - The HTTP method (GET or POST).
  * @param data - The request payload.
- * @param filter - An optional filter string.
+ * @param filter - An optional filter string or TQLFilter instance.
  * @returns A promise that resolves to an array of response data.
  */
 const makePaginatedRequest = (apiInstance_1, endpoint_1, ...args_1) => __awaiter(void 0, [apiInstance_1, endpoint_1, ...args_1], void 0, function* (apiInstance, endpoint, method = "GET", data = null, filter = null) {
@@ -31,7 +32,7 @@ const makePaginatedRequest = (apiInstance_1, endpoint_1, ...args_1) => __awaiter
     try {
         do {
             log("debug", `Fetching page ${nextPage} for ${endpoint}`);
-            const response = yield (0, makeRequest_1.makeRequest)(log, apiKey, baseUrl, endpoint, method, Object.assign(Object.assign({}, data), { filter, page: nextPage }), maxRetryTimeMs, maxRetryDelayMs);
+            const response = yield (0, makeRequest_1.makeRequest)(log, apiKey, baseUrl, endpoint, method, Object.assign(Object.assign({}, data), { filter: (0, tqlFilter_1.normalizeFilter)(filter), page: nextPage }), maxRetryTimeMs, maxRetryDelayMs);
             log("http", `Page ${nextPage} fetched successfully for ${endpoint}`);
             results = results.concat(response.data);
             nextPage = response.next_page;

package/dist/utils/makePaginatedRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"makePaginatedRequest.js","sourceRoot":"","sources":["../../src/utils/makePaginatedRequest.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,+CAA4C;AAC5C,+CAA4C;AAG5C,2CAAyD;AAEzD;;;;;;;;;GASG;AACI,MAAM,oBAAoB,GAAG,uCAMpB,EAAE,8EALhB,WAAwB,EACxB,QAAqB,EACrB,SAAyB,KAAK,EAC9B,OAAY,IAAI,EAChB,SAAoC,IAAI;IAExC,MAAM,EAAE,GAAG,EAAE,GAAG,WAAW,CAAC;IAC5B,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,EAAE,CAAC;IACvC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,WAAW,CAAC,SAAS,EAAE,CAAC;IAE7E,IAAI,OAAO,GAAU,EAAE,CAAC;IACxB,IAAI,QAAQ,GAAkB,CAAC,CAAC;IAEhC,IAAI,CAAC;QACH,GAAG,CAAC;YACF,GAAG,CAAC,OAAO,EAAE,iBAAiB,QAAQ,QAAQ,QAAQ,EAAE,CAAC,CAAC;YAC1D,MAAM,QAAQ,GACZ,MAAM,IAAA,yBAAW,EAIf,GAAG,EACH,MAAM,EACN,OAAO,EACP,QAAQ,EACR,MAAM,kCACD,IAAI,KAAE,MAAM,EAAE,IAAA,2BAAe,EAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,KAC1D,cAAc,EACd,eAAe,CAChB,CAAC;YAEJ,GAAG,CAAC,MAAM,EAAE,QAAQ,QAAQ,6BAA6B,QAAQ,EAAE,CAAC,CAAC;YACrE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxC,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC;QAChC,CAAC,QAAQ,QAAQ,EAAE;QAEnB,GAAG,CAAC,MAAM,EAAE,wBAAwB,QAAQ,yBAAyB,CAAC,CAAC;QACvE,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,GAAG,CACD,OAAO,EACP,wBAAwB,QAAQ,wBAAwB,KAAK,CAAC,OAAO,GAAG,CACzE,CAAC;QACF,IAAA,yBAAW,EAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC,CAAA,CAAC;AA/CW,QAAA,oBAAoB,wBA+C/B"}

package/{utils → dist/utils}/makeRequest.js

@@ -49,15 +49,38 @@ function makeRequest(log, apiKey, baseUrl, endpoint, method, data, maxRetryTimeM
             }
             catch (error) {
                 if (((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 429) {
-                    const retryAfterHeader = parseInt(error.response.headers["retry-after"], 10);
-                    const retryAfter = retryAfterHeader || Math.min(maxRetryDelayMs, Math.pow(2, retries));
-                    if (totalElapsedTime + retryAfter * 1000 >= maxRetryTimeMs) {
+                    // Parse Retry-After header (can be in seconds or HTTP date format)
+                    let retryAfterMs;
+                    const retryAfterHeader = error.response.headers["retry-after"];
+                    if (retryAfterHeader) {
+                        const retryAfterSeconds = parseInt(retryAfterHeader, 10);
+                        if (!isNaN(retryAfterSeconds)) {
+                            retryAfterMs = retryAfterSeconds * 1000;
+                        }
+                        else {
+                            // HTTP date format - calculate difference
+                            const retryDate = new Date(retryAfterHeader);
+                            retryAfterMs = Math.max(0, retryDate.getTime() - Date.now());
+                        }
+                    }
+                    else {
+                        // No Retry-After header - use aggressive exponential backoff
+                        // Start at 1 second, grow rapidly: 1s, 2s, 4s, 8s, 16s, 32s, 64s
+                        const baseDelayMs = Math.pow(2, retries) * 1000;
+                        // Add jitter (random ±25%) to prevent thundering herd
+                        // If multiple clients hit 429 at the same time, they'll retry at different times
+                        const jitterFactor = 0.75 + Math.random() * 0.5; // Random between 0.75 and 1.25
+                        retryAfterMs = baseDelayMs * jitterFactor;
+                    }
+                    // Cap at maxRetryDelayMs
+                    retryAfterMs = Math.min(maxRetryDelayMs, retryAfterMs);
+                    if (totalElapsedTime + retryAfterMs >= maxRetryTimeMs) {
                         log("error", `Max retry time exceeded for ${endpoint}`);
                         break;
                     }
-                    log("warn", `Rate limited on ${endpoint}. Retrying after ${retryAfter} seconds...`);
-                    yield new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
-                    totalElapsedTime += retryAfter * 1000;
+                    log("warn", `Rate limited (429) on ${endpoint}. Retrying after ${(retryAfterMs / 1000).toFixed(2)} seconds... (attempt ${retries + 1})`);
+                    yield new Promise((resolve) => setTimeout(resolve, retryAfterMs));
+                    totalElapsedTime += retryAfterMs;
                     retries++;
                 }
                 else {
@@ -66,7 +89,7 @@ function makeRequest(log, apiKey, baseUrl, endpoint, method, data, maxRetryTimeM
                 }
             }
         }
-        throw new Error(`Max retry time of ${maxRetryTimeMs} minutes exceeded for ${endpoint}`);
+        throw new Error(`Max retry time of ${maxRetryTimeMs / 1000} seconds exceeded for ${endpoint}`);
     });
 }
 //# sourceMappingURL=makeRequest.js.map

package/dist/utils/makeRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"makeRequest.js","sourceRoot":"","sources":["../../src/utils/makeRequest.ts"],"names":[],"mappings":"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"}