@aura-payments/sdk 2.1.1 → 2.3.0

package/dist/index.js

@@ -252,8 +252,8 @@ async function withTimeout(promise, timeoutMs, timeoutMessage) {
 }
 
 // src/resources/escrows.ts
-function isEscrowDeployed(e) {
-  if (e.blockchain?.deployed) return true;
+function isEscrowFundable(e) {
+  if (e.blockchain?.deployed || e.blockchain?.ready) return true;
   return ["deployed", "funded", "locked", "released"].includes(e.state ?? "");
 }
 function isEscrowFunded(e) {
@@ -338,11 +338,12 @@ var Escrows = class {
    * Receive USDC and split it across recipients in a single call (board D4).
    *
    * Composes the existing, crash-safe escrow path:
-   *   create → poll-until-deployed → pre-flight balance → fund → poll-until-funded → release.
+   *   create → poll-until-fundable (deployed or completed Circle-only fallback) → pre-flight balance → fund → poll-until-funded → release.
    *
    * Funds move from an Aura wallet owned by `payerOwnerId` (the agent itself or a
    * counterparty). The result's `stage` makes a partial run explicit:
-   *   - `created`  — deployment didn't confirm within `waitForDeploymentMs`
+   *   - `created`  — deploy outcome not definitive within `waitForDeploymentMs`
+   *                  (neither deployed nor the completed Circle-only fallback)
    *   - `deployed` — payer wallet lacks funds (see `fundingRequired`); no money moved
    *   - `funded`   — funded but not released (`autoRelease:false`, or funding didn't
    *                  settle within `waitForFundingMs` → `fundingPending: true`)
@@ -389,12 +390,12 @@ var Escrows = class {
     const escrowId = created.escrowId;
     const deployed = await this.pollEscrowUntil(
       escrowId,
-      isEscrowDeployed,
+      isEscrowFundable,
       waitForDeploymentMs,
       pollMs,
       created
     );
-    if (!isEscrowDeployed(deployed)) {
+    if (!isEscrowFundable(deployed)) {
       return {
         stage: "created",
         escrow: deployed,
@@ -402,7 +403,7 @@ var Escrows = class {
         deploymentPending: true
       };
     }
-    const payerWalletId = deployed.buyerWalletId;
+    const payerWalletId = deployed.buyerWalletId ?? deployed.buyerWallet?.walletId;
     const balance = await this.client.wallets.getBalance(payerWalletId);
     if (parseUsdc(balance.balance.usdc) < parseUsdc(amount)) {
       return {
@@ -479,6 +480,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;
@@ -604,6 +673,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) {
@@ -806,6 +893,73 @@ var Webhooks = class {
   }
 };
 
+// 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
+    );
+  }
+};
+
 // src/client.ts
 var AuraClient = class _AuraClient {
   constructor(config) {
@@ -823,6 +977,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
@@ -997,11 +1154,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;

package/dist/index.mjs

@@ -250,8 +250,8 @@ async function withTimeout(promise, timeoutMs, timeoutMessage) {
 }
 
 // src/resources/escrows.ts
-function isEscrowDeployed(e) {
-  if (e.blockchain?.deployed) return true;
+function isEscrowFundable(e) {
+  if (e.blockchain?.deployed || e.blockchain?.ready) return true;
   return ["deployed", "funded", "locked", "released"].includes(e.state ?? "");
 }
 function isEscrowFunded(e) {
@@ -336,11 +336,12 @@ var Escrows = class {
    * Receive USDC and split it across recipients in a single call (board D4).
    *
    * Composes the existing, crash-safe escrow path:
-   *   create → poll-until-deployed → pre-flight balance → fund → poll-until-funded → release.
+   *   create → poll-until-fundable (deployed or completed Circle-only fallback) → pre-flight balance → fund → poll-until-funded → release.
    *
    * Funds move from an Aura wallet owned by `payerOwnerId` (the agent itself or a
    * counterparty). The result's `stage` makes a partial run explicit:
-   *   - `created`  — deployment didn't confirm within `waitForDeploymentMs`
+   *   - `created`  — deploy outcome not definitive within `waitForDeploymentMs`
+   *                  (neither deployed nor the completed Circle-only fallback)
    *   - `deployed` — payer wallet lacks funds (see `fundingRequired`); no money moved
    *   - `funded`   — funded but not released (`autoRelease:false`, or funding didn't
    *                  settle within `waitForFundingMs` → `fundingPending: true`)
@@ -387,12 +388,12 @@ var Escrows = class {
     const escrowId = created.escrowId;
     const deployed = await this.pollEscrowUntil(
       escrowId,
-      isEscrowDeployed,
+      isEscrowFundable,
       waitForDeploymentMs,
       pollMs,
       created
     );
-    if (!isEscrowDeployed(deployed)) {
+    if (!isEscrowFundable(deployed)) {
       return {
         stage: "created",
         escrow: deployed,
@@ -400,7 +401,7 @@ var Escrows = class {
         deploymentPending: true
       };
     }
-    const payerWalletId = deployed.buyerWalletId;
+    const payerWalletId = deployed.buyerWalletId ?? deployed.buyerWallet?.walletId;
     const balance = await this.client.wallets.getBalance(payerWalletId);
     if (parseUsdc(balance.balance.usdc) < parseUsdc(amount)) {
       return {
@@ -477,6 +478,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;
@@ -602,6 +671,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) {
@@ -804,6 +891,73 @@ var Webhooks = class {
   }
 };
 
+// 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
+    );
+  }
+};
+
 // src/client.ts
 var AuraClient = class _AuraClient {
   constructor(config) {
@@ -821,6 +975,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
@@ -983,4 +1140,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 };
+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.1",
+  "version": "2.3.0",
   "description": "TypeScript SDK for Aura Payments Platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",