phonic 0.30.10 → 0.30.12

package/dist/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
-exports.SDK_VERSION = "0.30.10";
+exports.SDK_VERSION = "0.30.12";

package/dist/esm/Client.d.mts

@@ -16,7 +16,7 @@ export declare namespace PhonicClient {
         baseUrl?: core.Supplier<string>;
         apiKey?: core.Supplier<core.BearerToken | undefined>;
         /** Additional headers to include in requests. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
         fetcher?: core.FetchFunction;
     }
     interface RequestOptions {
@@ -29,7 +29,7 @@ export declare namespace PhonicClient {
         /** Additional query string parameters to include in the request. */
         queryParams?: Record<string, unknown>;
         /** Additional headers to include in the request. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
     }
 }
 export declare class PhonicClient {

package/dist/esm/Client.mjs

@@ -14,8 +14,8 @@ export class PhonicClient {
         this._options = Object.assign(Object.assign({}, _options), { headers: mergeHeaders({
                 "X-Fern-Language": "JavaScript",
                 "X-Fern-SDK-Name": "phonic",
-                "X-Fern-SDK-Version": "0.30.10",
-                "User-Agent": "phonic/0.30.10",
+                "X-Fern-SDK-Version": "0.30.12",
+                "User-Agent": "phonic/0.30.12",
                 "X-Fern-Runtime": core.RUNTIME.type,
                 "X-Fern-Runtime-Version": core.RUNTIME.version,
             }, _options === null || _options === void 0 ? void 0 : _options.headers) });

package/dist/esm/api/resources/agents/client/Client.d.mts

@@ -11,7 +11,7 @@ export declare namespace Agents {
         baseUrl?: core.Supplier<string>;
         apiKey?: core.Supplier<core.BearerToken | undefined>;
         /** Additional headers to include in requests. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
         fetcher?: core.FetchFunction;
     }
     interface RequestOptions {
@@ -24,7 +24,7 @@ export declare namespace Agents {
         /** Additional query string parameters to include in the request. */
         queryParams?: Record<string, unknown>;
         /** Additional headers to include in the request. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
     }
 }
 export declare class Agents {

package/dist/esm/api/resources/agents/client/requests/AgentsCreateRequest.d.mts

@@ -52,6 +52,8 @@ export interface AgentsCreateRequest {
     audio_speed?: number;
     /** The background noise level of the agent. */
     background_noise_level?: number;
+    /** The background noise type. Can be "office", "call-center", "coffee-shop", or null. */
+    background_noise?: Phonic.CreateAgentRequest.BackgroundNoise | null;
     /** Message to play when the conversation starts. Can contain template variables like `{{customer_name}}`. */
     welcome_message?: string;
     /** Instructions for the conversation. Can contain template variables like `{{subject}}`. */

package/dist/esm/api/resources/agents/client/requests/UpdateAgentRequest.d.mts

@@ -52,6 +52,8 @@ export interface UpdateAgentRequest {
     audio_speed?: number;
     /** The background noise level of the agent. */
     background_noise_level?: number;
+    /** The background noise type. Can be "office", "call-center", "coffee-shop", or null. */
+    background_noise?: UpdateAgentRequest.BackgroundNoise | null;
     /** Message to play when the conversation starts. Can contain template variables like `{{customer_name}}`. */
     welcome_message?: string;
     /** Instructions for the conversation. Can contain template variables like `{{subject}}`. */
@@ -86,6 +88,15 @@ export declare namespace UpdateAgentRequest {
         readonly Pcm8000: "pcm_8000";
         readonly Mulaw8000: "mulaw_8000";
     };
+    /**
+     * The background noise type. Can be "office", "call-center", "coffee-shop", or null.
+     */
+    type BackgroundNoise = "office" | "call-center" | "coffee-shop";
+    const BackgroundNoise: {
+        readonly Office: "office";
+        readonly CallCenter: "call-center";
+        readonly CoffeeShop: "coffee-shop";
+    };
     namespace TemplateVariables {
         interface Value {
             default_value: string | null;

package/dist/esm/api/resources/agents/client/requests/UpdateAgentRequest.mjs

@@ -9,4 +9,9 @@ export var UpdateAgentRequest;
         Pcm8000: "pcm_8000",
         Mulaw8000: "mulaw_8000",
     };
+    UpdateAgentRequest.BackgroundNoise = {
+        Office: "office",
+        CallCenter: "call-center",
+        CoffeeShop: "coffee-shop",
+    };
 })(UpdateAgentRequest || (UpdateAgentRequest = {}));

package/dist/esm/api/resources/conversations/client/Client.d.mts

@@ -12,7 +12,7 @@ export declare namespace Conversations {
         baseUrl?: core.Supplier<string>;
         apiKey?: core.Supplier<core.BearerToken | undefined>;
         /** Additional headers to include in requests. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
         fetcher?: core.FetchFunction;
     }
     interface RequestOptions {
@@ -25,7 +25,7 @@ export declare namespace Conversations {
         /** Additional query string parameters to include in the request. */
         queryParams?: Record<string, unknown>;
         /** Additional headers to include in the request. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
     }
     interface ConnectArgs {
         downstream_websocket_url?: string | undefined;

package/dist/esm/api/resources/extractionSchemas/client/Client.d.mts

@@ -11,7 +11,7 @@ export declare namespace ExtractionSchemas {
         baseUrl?: core.Supplier<string>;
         apiKey?: core.Supplier<core.BearerToken | undefined>;
         /** Additional headers to include in requests. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
         fetcher?: core.FetchFunction;
     }
     interface RequestOptions {
@@ -24,7 +24,7 @@ export declare namespace ExtractionSchemas {
         /** Additional query string parameters to include in the request. */
         queryParams?: Record<string, unknown>;
         /** Additional headers to include in the request. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
     }
 }
 export declare class ExtractionSchemas {

package/dist/esm/api/resources/projects/client/Client.d.mts

@@ -11,7 +11,7 @@ export declare namespace Projects {
         baseUrl?: core.Supplier<string>;
         apiKey?: core.Supplier<core.BearerToken | undefined>;
         /** Additional headers to include in requests. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
         fetcher?: core.FetchFunction;
     }
     interface RequestOptions {
@@ -24,7 +24,7 @@ export declare namespace Projects {
         /** Additional query string parameters to include in the request. */
         queryParams?: Record<string, unknown>;
         /** Additional headers to include in the request. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
     }
 }
 export declare class Projects {

package/dist/esm/api/resources/tools/client/Client.d.mts

@@ -11,7 +11,7 @@ export declare namespace Tools {
         baseUrl?: core.Supplier<string>;
         apiKey?: core.Supplier<core.BearerToken | undefined>;
         /** Additional headers to include in requests. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
         fetcher?: core.FetchFunction;
     }
     interface RequestOptions {
@@ -24,7 +24,7 @@ export declare namespace Tools {
         /** Additional query string parameters to include in the request. */
         queryParams?: Record<string, unknown>;
         /** Additional headers to include in the request. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
     }
 }
 export declare class Tools {
@@ -66,12 +66,14 @@ export declare class Tools {
      *                 type: "string",
      *                 name: "date",
      *                 description: "The date for the appointment in YYYY-MM-DD format",
-     *                 is_required: true
+     *                 is_required: true,
+     *                 location: "request_body"
      *             }, {
      *                 type: "string",
      *                 name: "time",
      *                 description: "The time for the appointment in HH:MM format",
-     *                 is_required: true
+     *                 is_required: true,
+     *                 location: "request_body"
      *             }],
      *         endpoint_method: "POST",
      *         endpoint_url: "https://api.example.com/book-appointment",

package/dist/esm/api/resources/tools/client/Client.mjs

@@ -118,12 +118,14 @@ export class Tools {
      *                 type: "string",
      *                 name: "date",
      *                 description: "The date for the appointment in YYYY-MM-DD format",
-     *                 is_required: true
+     *                 is_required: true,
+     *                 location: "request_body"
      *             }, {
      *                 type: "string",
      *                 name: "time",
      *                 description: "The time for the appointment in HH:MM format",
-     *                 is_required: true
+     *                 is_required: true,
+     *                 location: "request_body"
      *             }],
      *         endpoint_method: "POST",
      *         endpoint_url: "https://api.example.com/book-appointment",

package/dist/esm/api/resources/tools/client/requests/CreateToolRequest.d.mts

@@ -14,12 +14,14 @@ import * as Phonic from "../../../../index.mjs";
  *                 type: "string",
  *                 name: "date",
  *                 description: "The date for the appointment in YYYY-MM-DD format",
- *                 is_required: true
+ *                 is_required: true,
+ *                 location: "request_body"
  *             }, {
  *                 type: "string",
  *                 name: "time",
  *                 description: "The time for the appointment in HH:MM format",
- *                 is_required: true
+ *                 is_required: true,
+ *                 location: "request_body"
  *             }],
  *         endpoint_method: "POST",
  *         endpoint_url: "https://api.example.com/book-appointment",
@@ -67,10 +69,15 @@ export interface CreateToolRequest {
     type: CreateToolRequest.Type;
     /** Mode of operation. */
     execution_mode: CreateToolRequest.ExecutionMode;
-    /** Array of parameter definitions. */
+    /**
+     * Array of parameter definitions.
+     * For `custom_webhook` tools with POST method, each parameter must include a `location` field.
+     * For `custom_webhook` tools with GET method, `location` defaults to `"query_string"` if not specified.
+     * For `custom_websocket` and `built_in_transfer_to_phone_number` tools, `location` must not be specified.
+     */
     parameters?: Phonic.ToolParameter[];
-    /** Required for webhook tools. */
-    endpoint_method?: "POST";
+    /** Required for webhook tools. HTTP method for the webhook endpoint. */
+    endpoint_method?: CreateToolRequest.EndpointMethod;
     /** Required for webhook tools. */
     endpoint_url?: string;
     /** Optional headers for webhook tools. */
@@ -100,4 +107,12 @@ export declare namespace CreateToolRequest {
         readonly Sync: "sync";
         readonly Async: "async";
     };
+    /**
+     * Required for webhook tools. HTTP method for the webhook endpoint.
+     */
+    type EndpointMethod = "GET" | "POST";
+    const EndpointMethod: {
+        readonly Get: "GET";
+        readonly Post: "POST";
+    };
 }

package/dist/esm/api/resources/tools/client/requests/CreateToolRequest.mjs

@@ -12,4 +12,8 @@ export var CreateToolRequest;
         Sync: "sync",
         Async: "async",
     };
+    CreateToolRequest.EndpointMethod = {
+        Get: "GET",
+        Post: "POST",
+    };
 })(CreateToolRequest || (CreateToolRequest = {}));

package/dist/esm/api/resources/tools/client/requests/UpdateToolRequest.d.mts

@@ -24,9 +24,15 @@ export interface UpdateToolRequest {
     type?: UpdateToolRequest.Type;
     /** Mode of operation. */
     execution_mode?: UpdateToolRequest.ExecutionMode;
-    /** Array of parameter definitions. */
+    /**
+     * Array of parameter definitions.
+     * When updating `type` or `endpoint_method`, all parameters must include explicit `location` values.
+     * For `custom_webhook` tools: `location` is required for POST, defaults to `"query_string"` for GET.
+     * For `custom_websocket` and `built_in_transfer_to_phone_number` tools: `location` must not be specified.
+     */
     parameters?: Phonic.ToolParameter[];
-    endpoint_method?: "POST";
+    /** HTTP method for webhook tools. When changing this value, all parameters must include explicit `location` values. */
+    endpoint_method?: UpdateToolRequest.EndpointMethod;
     endpoint_url?: string;
     endpoint_headers?: Record<string, string>;
     endpoint_timeout_ms?: number;
@@ -52,4 +58,12 @@ export declare namespace UpdateToolRequest {
         readonly Sync: "sync";
         readonly Async: "async";
     };
+    /**
+     * HTTP method for webhook tools. When changing this value, all parameters must include explicit `location` values.
+     */
+    type EndpointMethod = "GET" | "POST";
+    const EndpointMethod: {
+        readonly Get: "GET";
+        readonly Post: "POST";
+    };
 }

package/dist/esm/api/resources/tools/client/requests/UpdateToolRequest.mjs

@@ -12,4 +12,8 @@ export var UpdateToolRequest;
         Sync: "sync",
         Async: "async",
     };
+    UpdateToolRequest.EndpointMethod = {
+        Get: "GET",
+        Post: "POST",
+    };
 })(UpdateToolRequest || (UpdateToolRequest = {}));

package/dist/esm/api/resources/voices/client/Client.d.mts

@@ -11,7 +11,7 @@ export declare namespace Voices {
         baseUrl?: core.Supplier<string>;
         apiKey?: core.Supplier<core.BearerToken | undefined>;
         /** Additional headers to include in requests. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
         fetcher?: core.FetchFunction;
     }
     interface RequestOptions {
@@ -24,7 +24,7 @@ export declare namespace Voices {
         /** Additional query string parameters to include in the request. */
         queryParams?: Record<string, unknown>;
         /** Additional headers to include in the request. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
     }
 }
 export declare class Voices {

package/dist/esm/api/types/Agent.d.mts

@@ -21,6 +21,8 @@ export interface Agent {
     audio_speed: number;
     /** The background noise level of the agent. Must be between 0 and 1. */
     background_noise_level: number;
+    /** The background noise type. Can be "office", "call-center", "coffee-shop", or null. */
+    background_noise: Agent.BackgroundNoise | null;
     /** Message to play when the conversation starts. */
     welcome_message: string | null;
     /** Instructions for the conversation. */
@@ -62,6 +64,15 @@ export declare namespace Agent {
         readonly Pcm8000: "pcm_8000";
         readonly Mulaw8000: "mulaw_8000";
     };
+    /**
+     * The background noise type. Can be "office", "call-center", "coffee-shop", or null.
+     */
+    type BackgroundNoise = "office" | "call-center" | "coffee-shop";
+    const BackgroundNoise: {
+        readonly Office: "office";
+        readonly CallCenter: "call-center";
+        readonly CoffeeShop: "coffee-shop";
+    };
     namespace TemplateVariables {
         interface Value {
             default_value: string | null;

package/dist/esm/api/types/Agent.mjs

@@ -9,4 +9,9 @@ export var Agent;
         Pcm8000: "pcm_8000",
         Mulaw8000: "mulaw_8000",
     };
+    Agent.BackgroundNoise = {
+        Office: "office",
+        CallCenter: "call-center",
+        CoffeeShop: "coffee-shop",
+    };
 })(Agent || (Agent = {}));

package/dist/esm/api/types/ConfigPayload.d.mts

@@ -15,6 +15,8 @@ export interface ConfigPayload {
     audio_speed?: number;
     /** Background noise level for the conversation */
     background_noise_level?: number;
+    /** Background noise type for the conversation */
+    background_noise?: ConfigPayload.BackgroundNoise | null;
     /** Message to play when conversation starts */
     welcome_message?: string | null;
     /** Voice ID to use for speech synthesis */
@@ -51,6 +53,15 @@ export interface ConfigPayload {
     template_variables?: Record<string, string>;
 }
 export declare namespace ConfigPayload {
+    /**
+     * Background noise type for the conversation
+     */
+    type BackgroundNoise = "office" | "call-center" | "coffee-shop";
+    const BackgroundNoise: {
+        readonly Office: "office";
+        readonly CallCenter: "call-center";
+        readonly CoffeeShop: "coffee-shop";
+    };
     /**
      * Audio input format
      */

package/dist/esm/api/types/ConfigPayload.mjs

@@ -3,6 +3,11 @@
  */
 export var ConfigPayload;
 (function (ConfigPayload) {
+    ConfigPayload.BackgroundNoise = {
+        Office: "office",
+        CallCenter: "call-center",
+        CoffeeShop: "coffee-shop",
+    };
     ConfigPayload.InputFormat = {
         Pcm44100: "pcm_44100",
         Pcm16000: "pcm_16000",

package/dist/esm/api/types/Conversation.d.mts

@@ -25,6 +25,8 @@ export interface Conversation {
     output_format: string;
     /** Background noise level used in the conversation. */
     background_noise_level: number;
+    /** The background noise type used in the conversation. */
+    background_noise: Conversation.BackgroundNoise | null;
     /** Live transcript of the conversation. */
     live_transcript: string;
     /** Post-call processed transcript. */
@@ -75,6 +77,15 @@ export declare namespace Conversation {
         /** The name of the project. */
         name: string;
     }
+    /**
+     * The background noise type used in the conversation.
+     */
+    type BackgroundNoise = "office" | "call-center" | "coffee-shop";
+    const BackgroundNoise: {
+        readonly Office: "office";
+        readonly CallCenter: "call-center";
+        readonly CoffeeShop: "coffee-shop";
+    };
     /**
      * Who or what ended the conversation.
      */

package/dist/esm/api/types/Conversation.mjs

@@ -3,6 +3,11 @@
  */
 export var Conversation;
 (function (Conversation) {
+    Conversation.BackgroundNoise = {
+        Office: "office",
+        CallCenter: "call-center",
+        CoffeeShop: "coffee-shop",
+    };
     Conversation.EndedBy = {
         User: "user",
         UserCanceled: "user_canceled",

package/dist/esm/api/types/CreateAgentRequest.d.mts

@@ -16,6 +16,8 @@ export interface CreateAgentRequest {
     audio_speed?: number;
     /** The background noise level of the agent. */
     background_noise_level?: number;
+    /** The background noise type. Can be "office", "call-center", "coffee-shop", or null. */
+    background_noise?: CreateAgentRequest.BackgroundNoise | null;
     /** Message to play when the conversation starts. Can contain template variables like `{{customer_name}}`. */
     welcome_message?: string;
     /** Instructions for the conversation. Can contain template variables like `{{subject}}`. */
@@ -50,6 +52,15 @@ export declare namespace CreateAgentRequest {
         readonly Pcm8000: "pcm_8000";
         readonly Mulaw8000: "mulaw_8000";
     };
+    /**
+     * The background noise type. Can be "office", "call-center", "coffee-shop", or null.
+     */
+    type BackgroundNoise = "office" | "call-center" | "coffee-shop";
+    const BackgroundNoise: {
+        readonly Office: "office";
+        readonly CallCenter: "call-center";
+        readonly CoffeeShop: "coffee-shop";
+    };
     namespace TemplateVariables {
         interface Value {
             default_value: string | null;

package/dist/esm/api/types/CreateAgentRequest.mjs

@@ -9,4 +9,9 @@ export var CreateAgentRequest;
         Pcm8000: "pcm_8000",
         Mulaw8000: "mulaw_8000",
     };
+    CreateAgentRequest.BackgroundNoise = {
+        Office: "office",
+        CallCenter: "call-center",
+        CoffeeShop: "coffee-shop",
+    };
 })(CreateAgentRequest || (CreateAgentRequest = {}));

package/dist/esm/api/types/Tool.d.mts

@@ -17,7 +17,7 @@ export interface Tool {
     /** Array of parameter definitions for the tool. */
     parameters: Phonic.ToolParameter[];
     /** HTTP method for webhook tools. */
-    endpoint_method?: "POST";
+    endpoint_method?: Tool.EndpointMethod;
     /** URL for webhook tools. */
     endpoint_url?: string;
     /** Headers for webhook tools. */
@@ -51,4 +51,12 @@ export declare namespace Tool {
         readonly Sync: "sync";
         readonly Async: "async";
     };
+    /**
+     * HTTP method for webhook tools.
+     */
+    type EndpointMethod = "GET" | "POST";
+    const EndpointMethod: {
+        readonly Get: "GET";
+        readonly Post: "POST";
+    };
 }

package/dist/esm/api/types/Tool.mjs

@@ -12,4 +12,8 @@ export var Tool;
         Sync: "sync",
         Async: "async",
     };
+    Tool.EndpointMethod = {
+        Get: "GET",
+        Post: "POST",
+    };
 })(Tool || (Tool = {}));

package/dist/esm/api/types/ToolParameter.d.mts

@@ -12,6 +12,14 @@ export interface ToolParameter {
     description: string;
     /** Whether the parameter is required. */
     is_required: boolean;
+    /**
+     * Only applicable for `custom_webhook` tools. Specifies where the parameter should be sent in the webhook request.
+     * - For GET webhooks: defaults to `"query_string"` and `"request_body"` is not allowed.
+     * - For POST webhooks: required, can be either `"request_body"` or `"query_string"`.
+     * - Not allowed for `custom_websocket` or `built_in_transfer_to_phone_number` tools.
+     * When updating a tool's type or endpoint_method, all parameters must include explicit `location` values.
+     */
+    location?: ToolParameter.Location;
 }
 export declare namespace ToolParameter {
     /**
@@ -35,4 +43,16 @@ export declare namespace ToolParameter {
         readonly Number: "number";
         readonly Boolean: "boolean";
     };
+    /**
+     * Only applicable for `custom_webhook` tools. Specifies where the parameter should be sent in the webhook request.
+     * - For GET webhooks: defaults to `"query_string"` and `"request_body"` is not allowed.
+     * - For POST webhooks: required, can be either `"request_body"` or `"query_string"`.
+     * - Not allowed for `custom_websocket` or `built_in_transfer_to_phone_number` tools.
+     * When updating a tool's type or endpoint_method, all parameters must include explicit `location` values.
+     */
+    type Location = "request_body" | "query_string";
+    const Location: {
+        readonly RequestBody: "request_body";
+        readonly QueryString: "query_string";
+    };
 }

package/dist/esm/api/types/ToolParameter.mjs

@@ -16,4 +16,8 @@ export var ToolParameter;
         Number: "number",
         Boolean: "boolean",
     };
+    ToolParameter.Location = {
+        RequestBody: "request_body",
+        QueryString: "query_string",
+    };
 })(ToolParameter || (ToolParameter = {}));

package/dist/esm/core/fetcher/Fetcher.d.mts

@@ -6,7 +6,7 @@ export declare namespace Fetcher {
         url: string;
         method: string;
         contentType?: string;
-        headers?: Record<string, string | Supplier<string | undefined> | undefined>;
+        headers?: Record<string, string | Supplier<string | null | undefined> | null | undefined>;
         queryParameters?: Record<string, unknown>;
         body?: unknown;
         timeoutMs?: number;

package/dist/esm/core/fetcher/requestWithRetries.mjs

@@ -11,21 +11,57 @@ const INITIAL_RETRY_DELAY = 1000; // in milliseconds
 const MAX_RETRY_DELAY = 60000; // in milliseconds
 const DEFAULT_MAX_RETRIES = 2;
 const JITTER_FACTOR = 0.2; // 20% random jitter
-function addJitter(delay) {
-    // Generate a random value between -JITTER_FACTOR and +JITTER_FACTOR
-    const jitterMultiplier = 1 + (Math.random() * 2 - 1) * JITTER_FACTOR;
+function addPositiveJitter(delay) {
+    // Generate a random value between 0 and +JITTER_FACTOR
+    const jitterMultiplier = 1 + Math.random() * JITTER_FACTOR;
     return delay * jitterMultiplier;
 }
+function addSymmetricJitter(delay) {
+    // Generate a random value in a JITTER_FACTOR-sized percentage range around delay
+    const jitterMultiplier = 1 + (Math.random() - 0.5) * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
+function getRetryDelayFromHeaders(response, retryAttempt) {
+    // Check for Retry-After header first (RFC 7231), with no jitter
+    const retryAfter = response.headers.get("Retry-After");
+    if (retryAfter) {
+        // Parse as number of seconds...
+        const retryAfterSeconds = parseInt(retryAfter, 10);
+        if (!isNaN(retryAfterSeconds) && retryAfterSeconds > 0) {
+            return Math.min(retryAfterSeconds * 1000, MAX_RETRY_DELAY);
+        }
+        // ...or as an HTTP date; both are valid
+        const retryAfterDate = new Date(retryAfter);
+        if (!isNaN(retryAfterDate.getTime())) {
+            const delay = retryAfterDate.getTime() - Date.now();
+            if (delay > 0) {
+                return Math.min(Math.max(delay, 0), MAX_RETRY_DELAY);
+            }
+        }
+    }
+    // Then check for industry-standard X-RateLimit-Reset header, with positive jitter
+    const rateLimitReset = response.headers.get("X-RateLimit-Reset");
+    if (rateLimitReset) {
+        const resetTime = parseInt(rateLimitReset, 10);
+        if (!isNaN(resetTime)) {
+            // Assume Unix timestamp in epoch seconds
+            const delay = resetTime * 1000 - Date.now();
+            if (delay > 0) {
+                return addPositiveJitter(Math.min(delay, MAX_RETRY_DELAY));
+            }
+        }
+    }
+    // Fall back to exponential backoff, with symmetric jitter
+    return addSymmetricJitter(Math.min(INITIAL_RETRY_DELAY * Math.pow(2, retryAttempt), MAX_RETRY_DELAY));
+}
 export function requestWithRetries(requestFn_1) {
     return __awaiter(this, arguments, void 0, function* (requestFn, maxRetries = DEFAULT_MAX_RETRIES) {
         let response = yield requestFn();
         for (let i = 0; i < maxRetries; ++i) {
             if ([408, 429].includes(response.status) || response.status >= 500) {
-                // Calculate base delay using exponential backoff (in milliseconds)
-                const baseDelay = Math.min(INITIAL_RETRY_DELAY * Math.pow(2, i), MAX_RETRY_DELAY);
-                // Add jitter to the delay
-                const delayWithJitter = addJitter(baseDelay);
-                yield new Promise((resolve) => setTimeout(resolve, delayWithJitter));
+                // Get delay with appropriate jitter applied
+                const delay = getRetryDelayFromHeaders(response, i);
+                yield new Promise((resolve) => setTimeout(resolve, delay));
                 response = yield requestFn();
             }
             else {

package/dist/esm/core/headers.d.mts

@@ -1,3 +1,3 @@
 import * as core from "./index.mjs";
-export declare function mergeHeaders(...headersArray: (Record<string, string | core.Supplier<string | undefined> | undefined> | undefined)[]): Record<string, string | core.Supplier<string | undefined>>;
-export declare function mergeOnlyDefinedHeaders(...headersArray: (Record<string, string | core.Supplier<string | undefined> | undefined> | undefined)[]): Record<string, string | core.Supplier<string | undefined>>;
+export declare function mergeHeaders(...headersArray: (Record<string, string | core.Supplier<string | null | undefined> | null | undefined> | null | undefined)[]): Record<string, string | core.Supplier<string | null | undefined>>;
+export declare function mergeOnlyDefinedHeaders(...headersArray: (Record<string, string | core.Supplier<string | null | undefined> | null | undefined> | null | undefined)[]): Record<string, string | core.Supplier<string | null | undefined>>;