@aura-payments/sdk 2.1.0 → 2.2.0

package/dist/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var crypto$1 = require('crypto');
+var crypto = require('crypto');
 
 // src/errors.ts
 var AuraError = class _AuraError extends Error {
@@ -238,12 +238,17 @@ async function retryWithBackoff(fn, maxRetries = 3, shouldRetry = isRetryableErr
   throw lastError;
 }
 async function withTimeout(promise, timeoutMs, timeoutMessage) {
+  let timer;
   const timeoutPromise = new Promise((_, reject) => {
-    setTimeout(() => {
+    timer = setTimeout(() => {
       reject(new AuraTimeoutError(timeoutMessage || `Request timeout after ${timeoutMs}ms`));
     }, timeoutMs);
   });
-  return Promise.race([promise, timeoutPromise]);
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
 }
 
 // src/resources/escrows.ts
@@ -474,6 +479,74 @@ var Escrows = class {
     );
   }
 };
+
+// src/resources/insights.ts
+var Insights = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Revenue, transactions, active escrows and commissions for a period, each
+   * with its change against the prior period.
+   *
+   * The route defaults to `7d`. `start` and `end` are ISO 8601 datetimes and are
+   * both required when `period` is `'custom'`.
+   */
+  async overview(period, start, end) {
+    const query = new URLSearchParams();
+    if (period !== void 0) query.set("period", period);
+    if (start !== void 0) query.set("start", start);
+    if (end !== void 0) query.set("end", end);
+    const qs = query.toString();
+    return this.client["request"](
+      "GET",
+      qs ? `/v1/insights/overview?${qs}` : "/v1/insights/overview"
+    );
+  }
+  /**
+   * Forecast a metric over a horizon. Gated to Growth+ plans; lower tiers
+   * surface a 403 `AuraAPIError`.
+   */
+  async forecast(params) {
+    const query = new URLSearchParams();
+    query.set("metric", params.metric);
+    if (params.algorithm !== void 0) query.set("algorithm", params.algorithm);
+    if (params.period !== void 0) query.set("period", params.period);
+    if (params.horizon !== void 0) query.set("horizon", params.horizon.toString());
+    if (params.includeHistory !== void 0) {
+      query.set("includeHistory", String(params.includeHistory));
+    }
+    if (params.historyPeriods !== void 0) {
+      query.set("historyPeriods", params.historyPeriods.toString());
+    }
+    return this.client["request"](
+      "GET",
+      `/v1/insights/forecast?${query.toString()}`
+    );
+  }
+  /**
+   * Query the account audit log by action, actor, resource and date range.
+   *
+   * The route defaults to `range: '30d'`, `page: 1`, `limit: 50`.
+   */
+  async audit(params) {
+    const query = new URLSearchParams();
+    if (params?.action !== void 0) query.set("action", params.action);
+    if (params?.actor !== void 0) query.set("actor", params.actor);
+    if (params?.resourceType !== void 0) query.set("resourceType", params.resourceType);
+    if (params?.resourceId !== void 0) query.set("resourceId", params.resourceId);
+    if (params?.range !== void 0) query.set("range", params.range);
+    if (params?.start !== void 0) query.set("start", params.start);
+    if (params?.end !== void 0) query.set("end", params.end);
+    if (params?.page !== void 0) query.set("page", params.page.toString());
+    if (params?.limit !== void 0) query.set("limit", params.limit.toString());
+    const qs = query.toString();
+    return this.client["request"](
+      "GET",
+      qs ? `/v1/insights/audit?${qs}` : "/v1/insights/audit"
+    );
+  }
+};
 var Mandates = class {
   constructor(client) {
     this.client = client;
@@ -543,7 +616,7 @@ var Mandates = class {
 var MandateSignature = {
   compute(input) {
     const payload = `${input.mandateId}:${input.decision}:${input.decidedAt}`;
-    return crypto$1.createHmac("sha256", input.secret).update(payload).digest("hex");
+    return crypto.createHmac("sha256", input.secret).update(payload).digest("hex");
   },
   verify(input) {
     const expected = MandateSignature.compute({
@@ -599,6 +672,24 @@ var Policies = class {
   }
 };
 
+// src/resources/treasury.ts
+var Treasury = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Analyze treasury balances, escrow exposure and pending payouts, and return
+   * an AI recommendation. Moves no funds.
+   *
+   * A POST with no body — the platform derives everything from the authenticated
+   * account. Gated to Growth+ plans; lower tiers surface a 403 `AuraAPIError`
+   * with code `feature_not_available`.
+   */
+  async optimize() {
+    return this.client["request"]("POST", "/v1/treasury/optimize");
+  }
+};
+
 // src/resources/wallets.ts
 var Wallets = class {
   constructor(client) {
@@ -782,23 +873,89 @@ var Webhooks = class {
    * Compute HMAC-SHA256 signature
    */
   static computeHmacSignature(payload, secret) {
-    if (typeof crypto !== "undefined" && crypto.subtle) {
-      throw new Error("Web Crypto implementation needed for browser");
-    }
-    return crypto$1.createHmac("sha256", secret).update(payload).digest("hex");
+    return crypto.createHmac("sha256", secret).update(payload).digest("hex");
   }
   /**
-   * Constant-time string comparison
+   * Constant-time comparison of two hex signatures.
+   *
+   * Length is compared first because `timingSafeEqual` throws on mismatched
+   * buffers; that only reveals the length of an attacker-supplied signature,
+   * never the contents of the expected one.
    */
   static secureCompare(a, b) {
-    if (a.length !== b.length) {
+    const left = Buffer.from(a, "utf8");
+    const right = Buffer.from(b, "utf8");
+    if (left.length !== right.length) {
       return false;
     }
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-      result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
+    return crypto.timingSafeEqual(left, right);
+  }
+};
+
+// src/resources/withdrawals.ts
+var Withdrawals = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get a single withdrawal, including status, fees, destination and tx hash.
+   */
+  async get(withdrawalId) {
+    return this.client["request"](
+      "GET",
+      `/v1/withdrawals/${encodeURIComponent(withdrawalId)}`
+    );
+  }
+  /**
+   * List withdrawals for the account, most recent first.
+   *
+   * Returns the whole `{withdrawals, pagination}` envelope — this route does not
+   * use the `{success,data}` wrapper, so pagination metadata is preserved.
+   */
+  async list(params) {
+    const query = new URLSearchParams();
+    if (params?.limit !== void 0) query.set("limit", params.limit.toString());
+    if (params?.offset !== void 0) query.set("offset", params.offset.toString());
+    if (params?.status !== void 0) query.set("status", params.status);
+    if (params?.chain !== void 0) query.set("chain", params.chain);
+    if (params?.fromDate !== void 0) query.set("fromDate", params.fromDate);
+    if (params?.toDate !== void 0) query.set("toDate", params.toDate);
+    const qs = query.toString();
+    return this.client["request"](
+      "GET",
+      qs ? `/v1/withdrawals?${qs}` : "/v1/withdrawals"
+    );
+  }
+  /**
+   * Preview fees and net amount for a withdrawal WITHOUT creating it.
+   *
+   * `params.exchange` is required by the route when `destinationType` is
+   * `'exchange'`; cross-chain estimates (source ≠ destination) add a CCTP
+   * bridge fee and only the supported routes are accepted.
+   */
+  async estimate(params) {
+    return this.client["request"](
+      "POST",
+      "/v1/withdrawals/estimate",
+      params
+    );
+  }
+  /**
+   * Get the account's KYC-tier withdrawal limits and remaining allowance.
+   */
+  async limits() {
+    return this.client["request"]("GET", "/v1/withdrawals/limits");
+  }
+  /**
+   * Validate a destination address for a chain. Moves no funds; when `amount` is
+   * supplied the response also carries a fee preview.
+   */
+  async validate(params) {
+    return this.client["request"](
+      "POST",
+      "/v1/withdrawals/validate",
+      params
+    );
   }
 };
 
@@ -819,6 +976,9 @@ var AuraClient = class _AuraClient {
     this.agents = new Agents(this);
     this.policies = new Policies(this);
     this.mandates = new Mandates(this);
+    this.withdrawals = new Withdrawals(this);
+    this.treasury = new Treasury(this);
+    this.insights = new Insights(this);
   }
   /**
    * Normalize the base URL so resource paths like `/v1/escrow` reach the
@@ -862,7 +1022,8 @@ var AuraClient = class _AuraClient {
    * Make an authenticated request to the API with automatic retry logic
    */
   async request(method, path, body, options) {
-    const requestFn = () => this.executeRequest(method, path, body, options);
+    const idempotencyKey = options?.idempotencyKey ?? (this.autoIdempotency && (method === "POST" || method === "PUT") ? generateIdempotencyKey() : void 0);
+    const requestFn = () => this.executeRequest(method, path, body, { ...options, idempotencyKey });
     if (options?.skipRetry || method === "GET") {
       return requestFn();
     }
@@ -876,12 +1037,10 @@ var AuraClient = class _AuraClient {
     const headers = {
       "Content-Type": "application/json",
       "Authorization": `Bearer ${this.apiKey}`,
-      "User-Agent": "@aura-payments/sdk/2.1.0"
+      "User-Agent": "@aura-payments/sdk/2.1.1"
     };
     if (options?.idempotencyKey) {
       headers["Idempotency-Key"] = options.idempotencyKey;
-    } else if (this.autoIdempotency && (method === "POST" || method === "PUT")) {
-      headers["Idempotency-Key"] = generateIdempotencyKey();
     }
     try {
       const response = await withTimeout(
@@ -994,11 +1153,14 @@ exports.AuraRateLimitError = AuraRateLimitError;
 exports.AuraTimeoutError = AuraTimeoutError;
 exports.AuraValidationError = AuraValidationError;
 exports.Escrows = Escrows;
+exports.Insights = Insights;
 exports.MandateSignature = MandateSignature;
 exports.Mandates = Mandates;
 exports.Policies = Policies;
+exports.Treasury = Treasury;
 exports.Wallets = Wallets;
 exports.Webhooks = Webhooks;
+exports.Withdrawals = Withdrawals;
 exports.calculateBackoff = calculateBackoff;
 exports.generateIdempotencyKey = generateIdempotencyKey;
 exports.isAuraAPIError = isAuraAPIError;
@@ -1009,5 +1171,3 @@ exports.isAuraTimeoutError = isAuraTimeoutError;
 exports.isRetryableError = isRetryableError;
 exports.retryWithBackoff = retryWithBackoff;
 exports.withTimeout = withTimeout;
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { createHmac } from 'crypto';
+import { createHmac, timingSafeEqual } from 'crypto';
 
 // src/errors.ts
 var AuraError = class _AuraError extends Error {
@@ -236,12 +236,17 @@ async function retryWithBackoff(fn, maxRetries = 3, shouldRetry = isRetryableErr
   throw lastError;
 }
 async function withTimeout(promise, timeoutMs, timeoutMessage) {
+  let timer;
   const timeoutPromise = new Promise((_, reject) => {
-    setTimeout(() => {
+    timer = setTimeout(() => {
       reject(new AuraTimeoutError(timeoutMessage || `Request timeout after ${timeoutMs}ms`));
     }, timeoutMs);
   });
-  return Promise.race([promise, timeoutPromise]);
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
 }
 
 // src/resources/escrows.ts
@@ -472,6 +477,74 @@ var Escrows = class {
     );
   }
 };
+
+// src/resources/insights.ts
+var Insights = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Revenue, transactions, active escrows and commissions for a period, each
+   * with its change against the prior period.
+   *
+   * The route defaults to `7d`. `start` and `end` are ISO 8601 datetimes and are
+   * both required when `period` is `'custom'`.
+   */
+  async overview(period, start, end) {
+    const query = new URLSearchParams();
+    if (period !== void 0) query.set("period", period);
+    if (start !== void 0) query.set("start", start);
+    if (end !== void 0) query.set("end", end);
+    const qs = query.toString();
+    return this.client["request"](
+      "GET",
+      qs ? `/v1/insights/overview?${qs}` : "/v1/insights/overview"
+    );
+  }
+  /**
+   * Forecast a metric over a horizon. Gated to Growth+ plans; lower tiers
+   * surface a 403 `AuraAPIError`.
+   */
+  async forecast(params) {
+    const query = new URLSearchParams();
+    query.set("metric", params.metric);
+    if (params.algorithm !== void 0) query.set("algorithm", params.algorithm);
+    if (params.period !== void 0) query.set("period", params.period);
+    if (params.horizon !== void 0) query.set("horizon", params.horizon.toString());
+    if (params.includeHistory !== void 0) {
+      query.set("includeHistory", String(params.includeHistory));
+    }
+    if (params.historyPeriods !== void 0) {
+      query.set("historyPeriods", params.historyPeriods.toString());
+    }
+    return this.client["request"](
+      "GET",
+      `/v1/insights/forecast?${query.toString()}`
+    );
+  }
+  /**
+   * Query the account audit log by action, actor, resource and date range.
+   *
+   * The route defaults to `range: '30d'`, `page: 1`, `limit: 50`.
+   */
+  async audit(params) {
+    const query = new URLSearchParams();
+    if (params?.action !== void 0) query.set("action", params.action);
+    if (params?.actor !== void 0) query.set("actor", params.actor);
+    if (params?.resourceType !== void 0) query.set("resourceType", params.resourceType);
+    if (params?.resourceId !== void 0) query.set("resourceId", params.resourceId);
+    if (params?.range !== void 0) query.set("range", params.range);
+    if (params?.start !== void 0) query.set("start", params.start);
+    if (params?.end !== void 0) query.set("end", params.end);
+    if (params?.page !== void 0) query.set("page", params.page.toString());
+    if (params?.limit !== void 0) query.set("limit", params.limit.toString());
+    const qs = query.toString();
+    return this.client["request"](
+      "GET",
+      qs ? `/v1/insights/audit?${qs}` : "/v1/insights/audit"
+    );
+  }
+};
 var Mandates = class {
   constructor(client) {
     this.client = client;
@@ -597,6 +670,24 @@ var Policies = class {
   }
 };
 
+// src/resources/treasury.ts
+var Treasury = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Analyze treasury balances, escrow exposure and pending payouts, and return
+   * an AI recommendation. Moves no funds.
+   *
+   * A POST with no body — the platform derives everything from the authenticated
+   * account. Gated to Growth+ plans; lower tiers surface a 403 `AuraAPIError`
+   * with code `feature_not_available`.
+   */
+  async optimize() {
+    return this.client["request"]("POST", "/v1/treasury/optimize");
+  }
+};
+
 // src/resources/wallets.ts
 var Wallets = class {
   constructor(client) {
@@ -780,23 +871,89 @@ var Webhooks = class {
    * Compute HMAC-SHA256 signature
    */
   static computeHmacSignature(payload, secret) {
-    if (typeof crypto !== "undefined" && crypto.subtle) {
-      throw new Error("Web Crypto implementation needed for browser");
-    }
     return createHmac("sha256", secret).update(payload).digest("hex");
   }
   /**
-   * Constant-time string comparison
+   * Constant-time comparison of two hex signatures.
+   *
+   * Length is compared first because `timingSafeEqual` throws on mismatched
+   * buffers; that only reveals the length of an attacker-supplied signature,
+   * never the contents of the expected one.
    */
   static secureCompare(a, b) {
-    if (a.length !== b.length) {
+    const left = Buffer.from(a, "utf8");
+    const right = Buffer.from(b, "utf8");
+    if (left.length !== right.length) {
       return false;
     }
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-      result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
+    return timingSafeEqual(left, right);
+  }
+};
+
+// src/resources/withdrawals.ts
+var Withdrawals = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get a single withdrawal, including status, fees, destination and tx hash.
+   */
+  async get(withdrawalId) {
+    return this.client["request"](
+      "GET",
+      `/v1/withdrawals/${encodeURIComponent(withdrawalId)}`
+    );
+  }
+  /**
+   * List withdrawals for the account, most recent first.
+   *
+   * Returns the whole `{withdrawals, pagination}` envelope — this route does not
+   * use the `{success,data}` wrapper, so pagination metadata is preserved.
+   */
+  async list(params) {
+    const query = new URLSearchParams();
+    if (params?.limit !== void 0) query.set("limit", params.limit.toString());
+    if (params?.offset !== void 0) query.set("offset", params.offset.toString());
+    if (params?.status !== void 0) query.set("status", params.status);
+    if (params?.chain !== void 0) query.set("chain", params.chain);
+    if (params?.fromDate !== void 0) query.set("fromDate", params.fromDate);
+    if (params?.toDate !== void 0) query.set("toDate", params.toDate);
+    const qs = query.toString();
+    return this.client["request"](
+      "GET",
+      qs ? `/v1/withdrawals?${qs}` : "/v1/withdrawals"
+    );
+  }
+  /**
+   * Preview fees and net amount for a withdrawal WITHOUT creating it.
+   *
+   * `params.exchange` is required by the route when `destinationType` is
+   * `'exchange'`; cross-chain estimates (source ≠ destination) add a CCTP
+   * bridge fee and only the supported routes are accepted.
+   */
+  async estimate(params) {
+    return this.client["request"](
+      "POST",
+      "/v1/withdrawals/estimate",
+      params
+    );
+  }
+  /**
+   * Get the account's KYC-tier withdrawal limits and remaining allowance.
+   */
+  async limits() {
+    return this.client["request"]("GET", "/v1/withdrawals/limits");
+  }
+  /**
+   * Validate a destination address for a chain. Moves no funds; when `amount` is
+   * supplied the response also carries a fee preview.
+   */
+  async validate(params) {
+    return this.client["request"](
+      "POST",
+      "/v1/withdrawals/validate",
+      params
+    );
   }
 };
 
@@ -817,6 +974,9 @@ var AuraClient = class _AuraClient {
     this.agents = new Agents(this);
     this.policies = new Policies(this);
     this.mandates = new Mandates(this);
+    this.withdrawals = new Withdrawals(this);
+    this.treasury = new Treasury(this);
+    this.insights = new Insights(this);
   }
   /**
    * Normalize the base URL so resource paths like `/v1/escrow` reach the
@@ -860,7 +1020,8 @@ var AuraClient = class _AuraClient {
    * Make an authenticated request to the API with automatic retry logic
    */
   async request(method, path, body, options) {
-    const requestFn = () => this.executeRequest(method, path, body, options);
+    const idempotencyKey = options?.idempotencyKey ?? (this.autoIdempotency && (method === "POST" || method === "PUT") ? generateIdempotencyKey() : void 0);
+    const requestFn = () => this.executeRequest(method, path, body, { ...options, idempotencyKey });
     if (options?.skipRetry || method === "GET") {
       return requestFn();
     }
@@ -874,12 +1035,10 @@ var AuraClient = class _AuraClient {
     const headers = {
       "Content-Type": "application/json",
       "Authorization": `Bearer ${this.apiKey}`,
-      "User-Agent": "@aura-payments/sdk/2.1.0"
+      "User-Agent": "@aura-payments/sdk/2.1.1"
     };
     if (options?.idempotencyKey) {
       headers["Idempotency-Key"] = options.idempotencyKey;
-    } else if (this.autoIdempotency && (method === "POST" || method === "PUT")) {
-      headers["Idempotency-Key"] = generateIdempotencyKey();
     }
     try {
       const response = await withTimeout(
@@ -980,6 +1139,4 @@ var AuraClient = class _AuraClient {
   }
 };
 
-export { Agents, AuraAPIError, AuraAuthenticationError, AuraClient, AuraError, AuraFaucetUnavailableError, AuraNetworkError, AuraNotFoundError, AuraRateLimitError, AuraTimeoutError, AuraValidationError, Escrows, MandateSignature, Mandates, Policies, Wallets, Webhooks, calculateBackoff, generateIdempotencyKey, isAuraAPIError, isAuraError, isAuraFaucetUnavailableError, isAuraNetworkError, isAuraTimeoutError, isRetryableError, retryWithBackoff, withTimeout };
-//# sourceMappingURL=index.mjs.map
-//# sourceMappingURL=index.mjs.map
+export { Agents, AuraAPIError, AuraAuthenticationError, AuraClient, AuraError, AuraFaucetUnavailableError, AuraNetworkError, AuraNotFoundError, AuraRateLimitError, AuraTimeoutError, AuraValidationError, Escrows, Insights, MandateSignature, Mandates, Policies, Treasury, Wallets, Webhooks, Withdrawals, calculateBackoff, generateIdempotencyKey, isAuraAPIError, isAuraError, isAuraFaucetUnavailableError, isAuraNetworkError, isAuraTimeoutError, isRetryableError, retryWithBackoff, withTimeout };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aura-payments/sdk",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "TypeScript SDK for Aura Payments Platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -27,9 +27,21 @@
   ],
   "author": "Aura Payments",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/humancodex/ap.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://getaura.sh",
+  "bugs": {
+    "url": "https://github.com/humancodex/ap/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "dependencies": {
     "zod": "^3.25.76",
-    "@aura-payments/shared": "2.0.0"
+    "@aura-payments/shared": "2.0.1"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",