@naturalpay/sdk 0.1.2 → 0.1.4

package/dist/index.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'async_hooks';
+import { createHash, randomUUID, createHmac, timingSafeEqual } from 'crypto';
 
 // src/errors.ts
 var NaturalError = class extends Error {
@@ -58,9 +59,15 @@ var ServerError = class extends NaturalError {
     this.name = "ServerError";
   }
 };
+var WebhookVerificationError = class extends NaturalError {
+  constructor(message) {
+    super(message, { code: "webhook_verification_failed" });
+    this.name = "WebhookVerificationError";
+  }
+};
 
 // src/version.ts
-var VERSION = "0.1.1";
+var VERSION = "0.1.4";
 
 // src/logging.ts
 var LOG_LEVEL_VALUES = {
@@ -251,7 +258,7 @@ function getLogger(name) {
   }
   return new Logger(name);
 }
-function logError(logger2, message, options) {
+function logError(logger3, message, options) {
   const extra = { ...options };
   if (options?.error) {
     extra["errorType"] = options.error.name;
@@ -261,9 +268,9 @@ function logError(logger2, message, options) {
     }
     delete extra["error"];
   }
-  logger2.error(message, extra);
+  logger3.error(message, extra);
 }
-function logApiCall(logger2, method, path, options) {
+function logApiCall(logger3, method, path, options) {
   const extra = {
     method,
     path,
@@ -276,14 +283,14 @@ function logApiCall(logger2, method, path, options) {
     extra["durationMs"] = Math.round(options.durationMs * 100) / 100;
   }
   if (options?.error) {
-    logError(logger2, `API call failed: ${method} ${path}`, extra);
+    logError(logger3, `API call failed: ${method} ${path}`, extra);
   } else if (options?.statusCode && options.statusCode >= 400) {
-    logger2.warning(`API call error: ${method} ${path} -> ${options.statusCode}`, extra);
+    logger3.warning(`API call error: ${method} ${path} -> ${options.statusCode}`, extra);
   } else {
-    logger2.info(`API call: ${method} ${path} -> ${options?.statusCode}`, extra);
+    logger3.info(`API call: ${method} ${path} -> ${options?.statusCode}`, extra);
   }
 }
-function logToolCall(logger2, toolName, options) {
+function logToolCall(logger3, toolName, options) {
   const extra = {
     toolName,
     ...options
@@ -292,24 +299,114 @@ function logToolCall(logger2, toolName, options) {
     extra["durationMs"] = Math.round(options.durationMs * 100) / 100;
   }
   if (options?.error) {
-    logError(logger2, `Tool call failed: ${toolName}`, extra);
+    logError(logger3, `Tool call failed: ${toolName}`, extra);
   } else if (options?.success === false) {
-    logger2.warning(`Tool call returned error: ${toolName}`, extra);
+    logger3.warning(`Tool call returned error: ${toolName}`, extra);
   } else {
-    logger2.info(`Tool call: ${toolName}`, extra);
+    logger3.info(`Tool call: ${toolName}`, extra);
   }
 }
+function configHash(cfg) {
+  const content = JSON.stringify({
+    system_prompt: cfg.systemPrompt,
+    tools_available: [...cfg.toolsAvailable].sort()
+  });
+  return createHash("sha256").update(content).digest("hex");
+}
+function agentConfigToDict(cfg) {
+  return {
+    system_prompt: cfg.systemPrompt,
+    tools_available: [...cfg.toolsAvailable].sort()
+  };
+}
+function modelUsageToDict(usage) {
+  const dict = {};
+  if (usage.model) {
+    dict.model = usage.model;
+  }
+  if (usage.provider) {
+    dict.provider = usage.provider;
+  }
+  if (usage.inputTokens != null) {
+    dict.input_tokens = usage.inputTokens;
+  }
+  if (usage.outputTokens != null) {
+    dict.output_tokens = usage.outputTokens;
+  }
+  if (usage.toolsCalled != null && usage.toolsCalled.length > 0) {
+    dict.tools_called = usage.toolsCalled;
+  }
+  return dict;
+}
+var logger = getLogger("tool-call-context");
 var toolCallStorage = new AsyncLocalStorage();
+function generateToolCallId() {
+  return `tc_${randomUUID()}`;
+}
 function getToolCallHeader() {
   const data = toolCallStorage.getStore();
   if (!data) return void 0;
-  return btoa(JSON.stringify(data));
+  const full = Buffer.from(JSON.stringify(data)).toString("base64");
+  if (full.length <= 16 * 1024) return full;
+  logger.warning("Tool call header exceeds 16KB, omitting arguments", {
+    toolCallId: data.tool_call_id,
+    toolName: data.tool_name,
+    fullSizeBytes: full.length
+  });
+  const slim = {
+    tool_call_id: data.tool_call_id,
+    tool_name: data.tool_name
+  };
+  return Buffer.from(JSON.stringify(slim)).toString("base64");
+}
+function runWithToolCall(toolCallId, name, args, fn) {
+  return toolCallStorage.run(
+    {
+      tool_call_id: toolCallId,
+      tool_name: name,
+      tool_call_arguments: JSON.stringify(args)
+    },
+    fn
+  );
 }
 
 // src/http.ts
-var logger = getLogger("http");
+var logger2 = getLogger("http");
 var DEFAULT_BASE_URL = "https://api.natural.co";
 var DEFAULT_TIMEOUT = 3e4;
+var API_KEY_PREFIX_REGEX = /^sk_ntl_(dev|sandbox|prod)_/;
+function parseApiKeyEnv(key) {
+  const match = API_KEY_PREFIX_REGEX.exec(key);
+  if (match) {
+    return match[1];
+  }
+  const preview = key.length > 16 ? `${key.slice(0, 16)}...` : key;
+  throw new InvalidRequestError(
+    `Invalid API key prefix. Expected a key starting with 'sk_ntl_dev_', 'sk_ntl_sandbox_', or 'sk_ntl_prod_'. Got: '${preview}'`
+  );
+}
+function validateBaseUrl(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new InvalidRequestError(`Invalid baseUrl: '${baseUrl}'. Must be a valid absolute URL.`);
+  }
+  if (url.protocol === "https:") {
+    return;
+  }
+  const host = url.hostname;
+  if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]") {
+    return;
+  }
+  const allowHttp = process.env["NATURAL_ALLOW_HTTP"];
+  if (allowHttp && allowHttp !== "0" && allowHttp.toLowerCase() !== "false") {
+    return;
+  }
+  throw new InvalidRequestError(
+    `baseUrl must use HTTPS (got '${baseUrl}'). To allow plaintext HTTP for development, set NATURAL_ALLOW_HTTP=1 or use a localhost host.`
+  );
+}
 function hashString(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -319,82 +416,167 @@ function hashString(str) {
   }
   return Math.abs(hash).toString(16).slice(0, 16);
 }
-var HTTPClient = class {
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+function hasIdempotencyKey(headers) {
+  return Object.entries(headers).some(
+    ([k, v]) => k.toLowerCase() === "idempotency-key" && v !== ""
+  );
+}
+function shouldRetry(method, headers, error, attempt, maxRetries) {
+  if (attempt >= maxRetries) return false;
+  if (error instanceof AuthenticationError) return false;
+  if (error instanceof InvalidRequestError) return false;
+  if (!(error instanceof RateLimitError) && error instanceof NaturalError && error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
+    return false;
+  }
+  const isRetryable = error instanceof ServerError || error instanceof RateLimitError || error instanceof NaturalError && !(error instanceof AuthenticationError);
+  if (!isRetryable) return false;
+  if (SAFE_METHODS.has(method.toUpperCase())) return true;
+  return hasIdempotencyKey(headers);
+}
+var MAX_RETRY_AFTER_MS = 6e4;
+function calculateRetryDelay(attempt, retryAfterSeconds) {
+  if (retryAfterSeconds != null && Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0) {
+    return Math.min(retryAfterSeconds * 1e3, MAX_RETRY_AFTER_MS);
+  }
+  const jitter = 1 + Math.random() * 0.25;
+  return Math.min(500 * Math.pow(2, attempt) * jitter, 5e3);
+}
+var HTTPClient = class _HTTPClient {
   apiKey;
   baseUrl;
   timeout;
+  maxRetries;
   jwtCache = /* @__PURE__ */ new Map();
+  agentConfig;
+  _defaultModelUsage;
+  _configResolved = false;
+  _configAttempted = false;
+  _registerConfigPromise = null;
+  _nextRetryAt = 0;
+  _retryBackoffMs = 1e3;
+  static MAX_RETRY_BACKOFF_MS = 5 * 60 * 1e3;
   constructor(options = {}) {
     this.apiKey = options.apiKey ?? process.env["NATURAL_API_KEY"] ?? "";
     this.baseUrl = (options.baseUrl ?? process.env["NATURAL_SERVER_URL"] ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    validateBaseUrl(this.baseUrl);
+    if (this.apiKey) {
+      parseApiKeyEnv(this.apiKey);
+    }
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.agentConfig = options.agentConfig ? {
+      systemPrompt: options.agentConfig.systemPrompt,
+      toolsAvailable: [...options.agentConfig.toolsAvailable]
+    } : void 0;
+    if (options.defaultModelUsage) {
+      this._defaultModelUsage = {
+        model: options.defaultModelUsage.model,
+        provider: options.defaultModelUsage.provider
+      };
+    }
+    const maxRetries = options.maxRetries ?? 2;
+    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+      throw new InvalidRequestError("maxRetries must be a non-negative integer");
+    }
+    this.maxRetries = maxRetries;
   }
   /**
    * Get a cached JWT or exchange API key for a new one.
+   * Retries on transient failures (5xx, network) but not on 401.
    */
   async getJwt() {
     if (!this.apiKey) {
       throw new AuthenticationError();
     }
-    if (!this.apiKey.startsWith("sk_ntl_")) {
-      return this.apiKey;
-    }
     const cacheKey = hashString(this.apiKey);
     const cached = this.jwtCache.get(cacheKey);
     if (cached && Date.now() < cached.expiresAt) {
       return cached.token;
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    logger.debug("Exchanging API key for JWT", { path: "/auth/api/token" });
-    try {
-      const response = await fetch(`${this.baseUrl}/auth/api/token`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const authError = new AuthenticationError(
-          `Authentication failed (status=${response.status})`
-        );
-        logError(logger, "JWT exchange failed", {
-          error: authError,
-          statusCode: response.status,
-          path: "/auth/api/token"
+    logger2.debug("Exchanging API key for JWT", { path: "/auth/api/token" });
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(`${this.baseUrl}/auth/api/token`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json"
+          },
+          signal: controller.signal
         });
-        throw authError;
-      }
-      const data = await response.json();
-      const expiresIn = data.expiresIn ?? 900;
-      const expiresAt = Date.now() + (expiresIn - 30) * 1e3;
-      this.jwtCache.set(cacheKey, { token: data.accessToken, expiresAt });
-      return data.accessToken;
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof AuthenticationError) {
-        throw error;
-      }
-      if (error instanceof Error && error.name === "AbortError") {
-        const networkError2 = new NaturalError("Request timed out during authentication");
-        logError(logger, "JWT exchange network error", {
-          error: networkError2,
+        clearTimeout(timeoutId);
+        if (response.status === 429) {
+          const retryAfter = response.headers.get("Retry-After");
+          const rateError = new RateLimitError(
+            "JWT exchange rate limited",
+            retryAfter ? parseInt(retryAfter, 10) : void 0
+          );
+          throw rateError;
+        }
+        if (response.status >= 400 && response.status < 500) {
+          const authError = new AuthenticationError(
+            `Authentication failed (status=${response.status})`
+          );
+          logError(logger2, "JWT exchange failed", {
+            error: authError,
+            statusCode: response.status,
+            path: "/auth/api/token"
+          });
+          throw authError;
+        }
+        if (response.status >= 500) {
+          const serverError = new ServerError(`JWT exchange failed (status=${response.status})`);
+          logError(logger2, "JWT exchange server error", {
+            error: serverError,
+            statusCode: response.status,
+            path: "/auth/api/token"
+          });
+          throw serverError;
+        }
+        const data = await response.json();
+        const expiresIn = data.expiresIn ?? 900;
+        const expiresAt = Date.now() + (expiresIn - 30) * 1e3;
+        this.jwtCache.set(cacheKey, { token: data.accessToken, expiresAt });
+        return data.accessToken;
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof AuthenticationError) {
+          throw error;
+        }
+        let sdkError;
+        if (error instanceof NaturalError) {
+          sdkError = error;
+        } else if (error instanceof Error && error.name === "AbortError") {
+          sdkError = new NaturalError("Request timed out during authentication");
+        } else {
+          sdkError = new NaturalError(
+            `Network error during authentication: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+        }
+        if (attempt < this.maxRetries) {
+          const retryAfter = sdkError instanceof RateLimitError ? sdkError.retryAfter : void 0;
+          const delay = calculateRetryDelay(attempt, retryAfter);
+          const reason = sdkError instanceof RateLimitError ? "429 rate limited" : sdkError instanceof ServerError ? `status ${sdkError.statusCode}` : "network error";
+          logger2.warning(`Retrying JWT exchange (attempt ${attempt + 1}/${this.maxRetries})`, {
+            path: "/auth/api/token",
+            attempt: attempt + 1,
+            maxRetries: this.maxRetries,
+            delayMs: Math.round(delay),
+            reason
+          });
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+        logError(logger2, "JWT exchange failed after retries", {
+          error: sdkError,
           path: "/auth/api/token"
         });
-        throw networkError2;
+        throw sdkError;
       }
-      const networkError = new NaturalError(
-        `Network error during authentication: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-      logError(logger, "JWT exchange network error", {
-        error: networkError,
-        path: "/auth/api/token"
-      });
-      throw networkError;
     }
+    throw new NaturalError("Unexpected retry exhaustion during JWT exchange");
   }
   /**
    * Build URL with query parameters.
@@ -416,7 +598,7 @@ var HTTPClient = class {
   async handleResponse(response, method, path, durationMs) {
     if (response.status === 401) {
       const authError = new AuthenticationError();
-      logApiCall(logger, method, path, {
+      logApiCall(logger2, method, path, {
         statusCode: response.status,
         durationMs,
         error: authError
@@ -429,7 +611,7 @@ var HTTPClient = class {
         "Rate limit exceeded",
         retryAfter ? parseInt(retryAfter, 10) : void 0
       );
-      logger.warning(`Rate limited: ${method} ${path}`, {
+      logger2.warning(`Rate limited: ${method} ${path}`, {
         method,
         path,
         statusCode: response.status,
@@ -440,7 +622,7 @@ var HTTPClient = class {
     }
     if (response.status >= 500) {
       const serverError = new ServerError(`Server error: ${response.status}`);
-      logApiCall(logger, method, path, {
+      logApiCall(logger2, method, path, {
         statusCode: response.status,
         durationMs,
         error: serverError
@@ -453,17 +635,18 @@ var HTTPClient = class {
       data = text ? JSON.parse(text) : {};
     } catch {
       if (response.status >= 400) {
-        const parseError = new NaturalError(`Request failed: ${response.status}`, {
-          statusCode: response.status
-        });
-        logApiCall(logger, method, path, {
+        const parseError = new NaturalError(
+          `Request failed: ${response.status} (non-JSON response)`,
+          { statusCode: response.status, code: "parse_error" }
+        );
+        logApiCall(logger2, method, path, {
           statusCode: response.status,
           durationMs,
           error: parseError
         });
         throw parseError;
       }
-      logApiCall(logger, method, path, { statusCode: response.status, durationMs });
+      logApiCall(logger2, method, path, { statusCode: response.status, durationMs });
       return {};
     }
     if (response.status >= 400) {
@@ -476,69 +659,185 @@ var HTTPClient = class {
         `${errorMessage} (status=${response.status})`,
         errorCode
       );
-      logApiCall(logger, method, path, {
+      logApiCall(logger2, method, path, {
         statusCode: response.status,
         durationMs,
         error: requestError
       });
       throw requestError;
     }
-    logApiCall(logger, method, path, { statusCode: response.status, durationMs });
+    logApiCall(logger2, method, path, { statusCode: response.status, durationMs });
     return data;
   }
   /**
-   * Make an authenticated request.
+   * Register agent config with the observability service.
+   *
+   * Called lazily before the first request. Errors are caught and logged,
+   * never thrown.
    */
-  async request(method, path, options) {
-    const jwt = await this.getJwt();
-    const url = this.buildUrl(path, options?.params);
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    logger.debug(`API request: ${method} ${path}`, {
-      method,
-      path,
-      hasBody: !!options?.body
-    });
-    const startTime = Date.now();
+  async registerConfig() {
+    if (!this.agentConfig) return;
     try {
-      const headers = {
-        Authorization: `Bearer ${jwt}`,
-        "Content-Type": "application/json",
-        "User-Agent": `naturalpay-ts/${VERSION}`
+      const jwt = await this.getJwt();
+      const hash = configHash(this.agentConfig);
+      const body = {
+        config_hash: hash,
+        ...agentConfigToDict(this.agentConfig)
       };
-      const toolCallHeader = getToolCallHeader();
-      if (toolCallHeader) {
-        headers["X-Tool-Call"] = toolCallHeader;
-      }
-      if (options?.headers) {
-        Object.assign(headers, options.headers);
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(`${this.baseUrl}/agents/config`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${jwt}`,
+            "Content-Type": "application/json",
+            "User-Agent": `naturalpay-ts/${VERSION}`
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+        if (response.ok) {
+          this._configResolved = true;
+        } else if (response.status === 429 || response.status === 408 || response.status >= 500) {
+          this._nextRetryAt = Date.now() + this._retryBackoffMs;
+          this._retryBackoffMs = Math.min(
+            this._retryBackoffMs * 2,
+            _HTTPClient.MAX_RETRY_BACKOFF_MS
+          );
+          logger2.warning("Agent config registration failed (transient)", {
+            statusCode: response.status
+          });
+        } else {
+          this._configResolved = true;
+          logger2.warning("Agent config registration failed (permanent)", {
+            statusCode: response.status
+          });
+        }
+      } finally {
+        clearTimeout(timeoutId);
       }
-      const response = await fetch(url, {
-        method,
-        headers,
-        body: options?.body ? JSON.stringify(options.body) : void 0,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      const durationMs = Date.now() - startTime;
-      return this.handleResponse(response, method, path, durationMs);
     } catch (error) {
-      clearTimeout(timeoutId);
-      const durationMs = Date.now() - startTime;
-      if (error instanceof NaturalError || error instanceof AuthenticationError || error instanceof InvalidRequestError || error instanceof RateLimitError || error instanceof ServerError) {
-        throw error;
+      this._nextRetryAt = Date.now() + this._retryBackoffMs;
+      this._retryBackoffMs = Math.min(this._retryBackoffMs * 2, _HTTPClient.MAX_RETRY_BACKOFF_MS);
+      logger2.warning("Failed to register agent config", {
+        error: error instanceof Error ? error.message : "Unknown error"
+      });
+    } finally {
+      this._configAttempted = true;
+    }
+  }
+  /**
+   * Add agent config hash and model usage headers if configured.
+   */
+  injectModelContextHeaders(headers, modelUsage) {
+    if (this.agentConfig) {
+      headers["X-Model-Config-Hash"] = configHash(this.agentConfig);
+    }
+    const effectiveUsage = (() => {
+      if (!modelUsage && !this._defaultModelUsage) return void 0;
+      return {
+        model: modelUsage?.model ?? this._defaultModelUsage?.model,
+        provider: modelUsage?.provider ?? this._defaultModelUsage?.provider,
+        inputTokens: modelUsage?.inputTokens,
+        outputTokens: modelUsage?.outputTokens,
+        toolsCalled: modelUsage?.toolsCalled
+      };
+    })();
+    if (effectiveUsage) {
+      const usageDict = modelUsageToDict(effectiveUsage);
+      if (Object.keys(usageDict).length > 0) {
+        headers["X-Model-Usage"] = Buffer.from(JSON.stringify(usageDict)).toString("base64");
+      }
+    }
+  }
+  /**
+   * Make an authenticated request with automatic retries.
+   */
+  async request(method, path, options) {
+    if (this.agentConfig && !this._configResolved) {
+      if (!this._registerConfigPromise) {
+        if (!this._configAttempted || Date.now() >= this._nextRetryAt) {
+          this._registerConfigPromise = this.registerConfig().catch(() => {
+          }).finally(() => {
+            this._registerConfigPromise = null;
+          });
+        }
       }
-      if (error instanceof Error && error.name === "AbortError") {
-        const networkError2 = new NaturalError("Request timed out");
-        logApiCall(logger, method, path, { durationMs, error: networkError2 });
-        throw networkError2;
+      if (!this._configAttempted) {
+        await this._registerConfigPromise;
+      }
+    }
+    const jwt = await this.getJwt();
+    const url = this.buildUrl(path, options?.params);
+    const mergedHeaders = {
+      Authorization: `Bearer ${jwt}`,
+      "Content-Type": "application/json",
+      "User-Agent": `naturalpay-ts/${VERSION}`
+    };
+    const toolCallHeader = getToolCallHeader();
+    if (toolCallHeader) {
+      mergedHeaders["X-Tool-Call"] = toolCallHeader;
+    }
+    this.injectModelContextHeaders(mergedHeaders, options?.modelUsage);
+    if (options?.headers) {
+      Object.assign(mergedHeaders, options.headers);
+    }
+    const bodyStr = options?.body ? JSON.stringify(options.body) : void 0;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      const startTime = Date.now();
+      if (attempt === 0) {
+        logger2.debug(`API request: ${method} ${path}`, {
+          method,
+          path,
+          hasBody: !!options?.body
+        });
+      }
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: mergedHeaders,
+          body: bodyStr,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        const durationMs = Date.now() - startTime;
+        return await this.handleResponse(response, method, path, durationMs);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        const durationMs = Date.now() - startTime;
+        let sdkError;
+        if (error instanceof NaturalError) {
+          sdkError = error;
+        } else if (error instanceof Error && error.name === "AbortError") {
+          sdkError = new NaturalError("Request timed out");
+          logApiCall(logger2, method, path, { durationMs, error: sdkError });
+        } else {
+          sdkError = new NaturalError(
+            `Network error: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+          logApiCall(logger2, method, path, { durationMs, error: sdkError });
+        }
+        if (shouldRetry(method, mergedHeaders, sdkError, attempt, this.maxRetries)) {
+          const retryAfter = sdkError instanceof RateLimitError ? sdkError.retryAfter : void 0;
+          const delay = calculateRetryDelay(attempt, retryAfter);
+          logger2.warning(`Retrying ${method} ${path} (attempt ${attempt + 1}/${this.maxRetries})`, {
+            method,
+            path,
+            attempt: attempt + 1,
+            maxRetries: this.maxRetries,
+            delayMs: Math.round(delay),
+            reason: sdkError instanceof ServerError ? `status ${sdkError.statusCode}` : sdkError instanceof RateLimitError ? "429 rate limited" : "network error"
+          });
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+        throw sdkError;
       }
-      const networkError = new NaturalError(
-        `Network error: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-      logApiCall(logger, method, path, { durationMs, error: networkError });
-      throw networkError;
     }
+    throw new NaturalError("Unexpected retry exhaustion");
   }
   async get(path, options) {
     return this.request("GET", path, options);
@@ -561,6 +860,9 @@ var BaseResource = class {
     this.http = http;
   }
 };
+function sanitizeHeaderValue(value) {
+  return value.replace(/[\x00-\x1f\x7f]/g, "");
+}
 
 // src/resources/transactions.ts
 function unwrapTransactionResource(resource) {
@@ -605,9 +907,15 @@ var TransactionsResource = class extends BaseResource {
    */
   async get(transactionId, params) {
     const headers = {};
+    if (params?.agentId) {
+      headers["X-Agent-ID"] = params.agentId;
+    }
     if (params?.instanceId) {
       headers["X-Instance-ID"] = params.instanceId;
     }
+    if (params?.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const queryParams = {};
     if (params?.customerPartyId) {
       queryParams["partyId"] = params.customerPartyId;
@@ -638,6 +946,9 @@ var TransactionsResource = class extends BaseResource {
     if (params?.instanceId) {
       headers["X-Instance-ID"] = params.instanceId;
     }
+    if (params?.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const queryParams = {
       limit: params?.limit ?? 50,
       cursor: params?.cursor,
@@ -730,6 +1041,9 @@ var PaymentsResource = class extends BaseResource {
     if (params.instanceId) {
       headers["X-Instance-ID"] = params.instanceId;
     }
+    if (params.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const response = await this.http.post("/payments", {
       body,
       headers
@@ -812,9 +1126,15 @@ var WalletResource = class extends BaseResource {
    */
   async balance(options) {
     const headers = {};
+    if (options?.agentId) {
+      headers["X-Agent-ID"] = options.agentId;
+    }
     if (options?.instanceId) {
       headers["X-Instance-ID"] = options.instanceId;
     }
+    if (options?.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(options.traceId);
+    }
     const params = {};
     if (options?.customerPartyId) {
       params["partyId"] = options.customerPartyId;
@@ -842,9 +1162,21 @@ var WalletResource = class extends BaseResource {
     };
     if (params.description) attributes["description"] = params.description;
     const body = { data: { attributes } };
+    const headers = {
+      "Idempotency-Key": params.idempotencyKey
+    };
+    if (params.agentId) {
+      headers["X-Agent-ID"] = params.agentId;
+    }
+    if (params.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    if (params.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const response = await this.http.post("/wallet/withdraw", {
       body,
-      headers: { "Idempotency-Key": params.idempotencyKey }
+      headers
     });
     return unwrapWithdrawal(response);
   }
@@ -899,9 +1231,15 @@ var AgentsResource = class extends BaseResource {
    */
   async list(params) {
     const headers = {};
+    if (params?.agentId) {
+      headers["X-Agent-ID"] = params.agentId;
+    }
     if (params?.instanceId) {
       headers["X-Instance-ID"] = params.instanceId;
     }
+    if (params?.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const queryParams = {
       status: params?.status,
       limit: params?.limit ?? 50,
@@ -921,9 +1259,15 @@ var AgentsResource = class extends BaseResource {
    */
   async get(agentId, options) {
     const headers = {};
+    if (options?.agentId) {
+      headers["X-Agent-ID"] = options.agentId;
+    }
     if (options?.instanceId) {
       headers["X-Instance-ID"] = options.instanceId;
     }
+    if (options?.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(options.traceId);
+    }
     const response = await this.http.get(`/agents/${agentId}`, {
       headers: Object.keys(headers).length > 0 ? headers : void 0
     });
@@ -950,9 +1294,15 @@ var AgentsResource = class extends BaseResource {
     if (params.idempotencyKey) {
       headers["Idempotency-Key"] = params.idempotencyKey;
     }
+    if (params.agentId) {
+      headers["X-Agent-ID"] = params.agentId;
+    }
     if (params.instanceId) {
       headers["X-Instance-ID"] = params.instanceId;
     }
+    if (params.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const response = await this.http.post("/agents", {
       body,
       headers: Object.keys(headers).length > 0 ? headers : void 0
@@ -976,9 +1326,15 @@ var AgentsResource = class extends BaseResource {
     if (params.idempotencyKey) {
       headers["Idempotency-Key"] = params.idempotencyKey;
     }
+    if (params.agentId) {
+      headers["X-Agent-ID"] = params.agentId;
+    }
     if (params.instanceId) {
       headers["X-Instance-ID"] = params.instanceId;
     }
+    if (params.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const response = await this.http.put(`/agents/${agentId}`, {
       body,
       headers: Object.keys(headers).length > 0 ? headers : void 0
@@ -993,9 +1349,15 @@ var AgentsResource = class extends BaseResource {
    */
   async delete(agentId, options) {
     const headers = {};
+    if (options?.agentId) {
+      headers["X-Agent-ID"] = options.agentId;
+    }
     if (options?.instanceId) {
       headers["X-Instance-ID"] = options.instanceId;
     }
+    if (options?.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(options.traceId);
+    }
     await this.http.delete(`/agents/${agentId}`, {
       headers: Object.keys(headers).length > 0 ? headers : void 0
     });
@@ -1061,6 +1423,9 @@ var DelegationsResource = class extends BaseResource {
     if (params?.instanceId) {
       headers["X-Instance-ID"] = params.instanceId;
     }
+    if (params?.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const queryParams = {
       delegationId: params?.delegationId,
       agentId: params?.agentId,
@@ -1146,9 +1511,15 @@ var CustomersResource = class extends BaseResource {
    */
   async list(params) {
     const headers = {};
+    if (params?.agentId) {
+      headers["X-Agent-ID"] = params.agentId;
+    }
     if (params?.instanceId) {
       headers["X-Instance-ID"] = params.instanceId;
     }
+    if (params?.traceId) {
+      headers["X-Trace-ID"] = sanitizeHeaderValue(params.traceId);
+    }
     const queryParams = {
       limit: params?.limit,
       cursor: params?.cursor
@@ -1194,6 +1565,84 @@ var NaturalClient = class {
     this.customers = new CustomersResource(this.http);
   }
 };
+var WHSEC_PREFIX = "whsec_";
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function getHeader(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const lower = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === lower) {
+      return headers[key];
+    }
+  }
+  return void 0;
+}
+function verifyWebhookSignature(body, headers, secret, options) {
+  const tolerance = options?.toleranceInSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (!Number.isInteger(tolerance) || tolerance <= 0) {
+    throw new WebhookVerificationError("toleranceInSeconds must be a positive integer");
+  }
+  const webhookId = getHeader(headers, "webhook-id");
+  if (!webhookId) {
+    throw new WebhookVerificationError("webhook-id header is missing");
+  }
+  const timestampStr = getHeader(headers, "webhook-timestamp");
+  if (!timestampStr) {
+    throw new WebhookVerificationError("webhook-timestamp header is missing");
+  }
+  const signatureHeader = getHeader(headers, "webhook-signature");
+  if (!signatureHeader) {
+    throw new WebhookVerificationError("webhook-signature header is missing");
+  }
+  if (!/^\d+$/.test(timestampStr)) {
+    throw new WebhookVerificationError(
+      `Invalid webhook-timestamp: '${timestampStr}' is not a valid integer`
+    );
+  }
+  const timestamp = parseInt(timestampStr, 10);
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - timestamp) > tolerance) {
+    throw new WebhookVerificationError(
+      timestamp > now ? "Webhook timestamp is too far in the future" : "Webhook timestamp is too old"
+    );
+  }
+  let keyBytes;
+  const base64Part = secret.startsWith(WHSEC_PREFIX) ? secret.slice(WHSEC_PREFIX.length) : secret;
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(base64Part) || base64Part.length === 0) {
+    throw new WebhookVerificationError("Invalid signing secret: could not base64-decode");
+  }
+  try {
+    keyBytes = Buffer.from(base64Part, "base64");
+    if (keyBytes.length === 0) {
+      throw new Error("empty key");
+    }
+  } catch {
+    throw new WebhookVerificationError("Invalid signing secret: could not base64-decode");
+  }
+  const bodyStr = typeof body === "string" ? body : Buffer.from(body).toString("utf-8");
+  const signedContent = `${webhookId}.${timestampStr}.${bodyStr}`;
+  const expectedSig = createHmac("sha256", keyBytes).update(signedContent).digest("base64");
+  const candidates = signatureHeader.split(" ");
+  for (const candidate of candidates) {
+    if (!candidate.startsWith("v1,")) continue;
+    const candidateSig = candidate.slice(3);
+    const expectedBuf = Buffer.from(expectedSig, "utf-8");
+    const candidateBuf = Buffer.from(candidateSig, "utf-8");
+    if (expectedBuf.length !== candidateBuf.length) continue;
+    if (timingSafeEqual(expectedBuf, candidateBuf)) {
+      try {
+        return JSON.parse(bodyStr);
+      } catch {
+        throw new WebhookVerificationError("Webhook signature is valid but body is not valid JSON");
+      }
+    }
+  }
+  throw new WebhookVerificationError(
+    "Webhook signature does not match \u2014 ensure you are using the raw request body"
+  );
+}
 
 // src/types/transactions.ts
 var TransactionTypeFilter = /* @__PURE__ */ ((TransactionTypeFilter2) => {
@@ -1203,6 +1652,6 @@ var TransactionTypeFilter = /* @__PURE__ */ ((TransactionTypeFilter2) => {
   return TransactionTypeFilter2;
 })(TransactionTypeFilter || {});
 
-export { AuthenticationError, InsufficientFundsError, InvalidRequestError, NaturalClient, NaturalError, PaymentError, RateLimitError, RecipientNotFoundError, ServerError, TransactionTypeFilter, VERSION, bindContext, clearContext, configureLogging, getContext, getLogger, logApiCall, logError, logToolCall, runWithContext };
+export { AuthenticationError, InsufficientFundsError, InvalidRequestError, NaturalClient, NaturalError, PaymentError, RateLimitError, RecipientNotFoundError, ServerError, TransactionTypeFilter, VERSION, WebhookVerificationError, agentConfigToDict, bindContext, clearContext, configHash, configureLogging, generateToolCallId, getContext, getLogger, getToolCallHeader, logApiCall, logError, logToolCall, modelUsageToDict, parseApiKeyEnv, runWithContext, runWithToolCall, validateBaseUrl, verifyWebhookSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map