@aura-payments/sdk 2.1.0

package/dist/index.mjs

@@ -0,0 +1,985 @@
+import { createHmac } from 'crypto';
+
+// src/errors.ts
+var AuraError = class _AuraError extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "AuraError";
+    Object.setPrototypeOf(this, _AuraError.prototype);
+  }
+};
+var AuraAPIError = class _AuraAPIError extends AuraError {
+  constructor(message, statusCode, code, details) {
+    super(message, code, statusCode, details);
+    this.name = "AuraAPIError";
+    Object.setPrototypeOf(this, _AuraAPIError.prototype);
+  }
+};
+var AuraNetworkError = class _AuraNetworkError extends AuraError {
+  constructor(message, cause) {
+    super(message, "NETWORK_ERROR");
+    this.cause = cause;
+    this.name = "AuraNetworkError";
+    Object.setPrototypeOf(this, _AuraNetworkError.prototype);
+  }
+};
+var AuraTimeoutError = class _AuraTimeoutError extends AuraError {
+  constructor(message = "Request timeout") {
+    super(message, "TIMEOUT");
+    this.name = "AuraTimeoutError";
+    Object.setPrototypeOf(this, _AuraTimeoutError.prototype);
+  }
+};
+var AuraValidationError = class _AuraValidationError extends AuraError {
+  constructor(message, details) {
+    super(message, "VALIDATION_ERROR", 400, details);
+    this.name = "AuraValidationError";
+    Object.setPrototypeOf(this, _AuraValidationError.prototype);
+  }
+};
+var AuraAuthenticationError = class _AuraAuthenticationError extends AuraError {
+  constructor(message = "Authentication failed") {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuraAuthenticationError";
+    Object.setPrototypeOf(this, _AuraAuthenticationError.prototype);
+  }
+};
+var AuraNotFoundError = class _AuraNotFoundError extends AuraError {
+  constructor(resource) {
+    super(`${resource} not found`, "NOT_FOUND", 404);
+    this.name = "AuraNotFoundError";
+    Object.setPrototypeOf(this, _AuraNotFoundError.prototype);
+  }
+};
+var AuraRateLimitError = class _AuraRateLimitError extends AuraError {
+  constructor(message = "Rate limit exceeded", retryAfter) {
+    super(message, "RATE_LIMIT_EXCEEDED", 429);
+    this.retryAfter = retryAfter;
+    this.name = "AuraRateLimitError";
+    Object.setPrototypeOf(this, _AuraRateLimitError.prototype);
+  }
+};
+var AuraFaucetUnavailableError = class _AuraFaucetUnavailableError extends AuraError {
+  constructor(message = "Testnet faucet is not available on this deployment") {
+    super(message, "FAUCET_UNAVAILABLE", 501);
+    this.name = "AuraFaucetUnavailableError";
+    Object.setPrototypeOf(this, _AuraFaucetUnavailableError.prototype);
+  }
+};
+function isAuraError(error) {
+  return error instanceof AuraError;
+}
+function isAuraFaucetUnavailableError(error) {
+  return error instanceof AuraFaucetUnavailableError;
+}
+function isAuraAPIError(error) {
+  return error instanceof AuraAPIError;
+}
+function isAuraNetworkError(error) {
+  return error instanceof AuraNetworkError;
+}
+function isAuraTimeoutError(error) {
+  return error instanceof AuraTimeoutError;
+}
+function isRetryableError(error) {
+  if (!(error instanceof AuraError)) return false;
+  if (error instanceof AuraNetworkError) return true;
+  if (error instanceof AuraTimeoutError) return true;
+  if (error instanceof AuraRateLimitError) return true;
+  if (error.statusCode && error.statusCode >= 500) {
+    return true;
+  }
+  return false;
+}
+
+// src/resources/agents.ts
+var Agents = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new AI agent with a dedicated wallet and (optional) initial
+   * policy. The platform provisions a Circle wallet on the requested chain
+   * during this call; expect a few seconds of latency for the on-chain part.
+   */
+  async create(params, idempotencyKey) {
+    return this.client["request"](
+      "POST",
+      "/v1/agents",
+      params,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * List agents for the authenticated account, paginated.
+   */
+  async list(params) {
+    const query = new URLSearchParams();
+    if (params?.status) query.set("status", params.status);
+    if (params?.type) query.set("type", params.type);
+    if (params?.limit !== void 0) query.set("limit", String(params.limit));
+    if (params?.offset !== void 0) query.set("offset", String(params.offset));
+    if (params?.orderBy) query.set("orderBy", params.orderBy);
+    if (params?.orderDirection) query.set("orderDirection", params.orderDirection);
+    const qs = query.toString();
+    return this.client["request"](
+      "GET",
+      qs ? `/v1/agents?${qs}` : "/v1/agents"
+    );
+  }
+  /**
+   * Get a single agent by id.
+   */
+  async get(agentId) {
+    return this.client["request"]("GET", `/v1/agents/${agentId}`);
+  }
+  /**
+   * Patch an agent's metadata fields. Cannot be used to flip status — use
+   * `freeze`/`unfreeze` for that so the mandate-cascade and activity events
+   * fire correctly.
+   */
+  async update(agentId, params, idempotencyKey) {
+    return this.client["request"](
+      "PATCH",
+      `/v1/agents/${agentId}`,
+      params,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Freeze (kill switch) — sets status to `paused` and cascade-rejects every
+   * pending mandate the agent has in flight. Idempotent.
+   */
+  async freeze(params, idempotencyKey) {
+    const { agentId, ...body } = params;
+    return this.client["request"](
+      "POST",
+      `/v1/agents/${agentId}/freeze`,
+      body,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Unfreeze — sets status back to `active`. Previously cascade-rejected
+   * mandates are NOT restored; the agent re-creates them on its next loop.
+   */
+  async unfreeze(params, idempotencyKey) {
+    const { agentId } = params;
+    return this.client["request"](
+      "POST",
+      `/v1/agents/${agentId}/unfreeze`,
+      void 0,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Get the agent's wallet balance (USDC, on-chain at request time).
+   */
+  async getBalance(agentId) {
+    return this.client["request"](
+      "GET",
+      `/v1/agents/${agentId}/balance`
+    );
+  }
+  /**
+   * Run a hypothetical transaction through the policy engine without
+   * executing it. Returns the engine's decision (`auto_approve`, `auto_deny`,
+   * or `requires_human_approval`) along with the matched rules. When the
+   * decision is `requires_human_approval`, the engine creates a mandate row
+   * and returns its id so the caller can watch for the operator's decision.
+   */
+  async evaluate(params, idempotencyKey) {
+    const { agentId, ...body } = params;
+    return this.client["request"](
+      "POST",
+      `/v1/agents/${agentId}/evaluate`,
+      body,
+      { idempotencyKey }
+    );
+  }
+};
+
+// src/utils.ts
+function generateIdempotencyKey() {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 15);
+  return `${timestamp}-${random}`;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function calculateBackoff(attempt, baseDelay = 1e3, maxDelay = 3e4) {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  const jitter = exponentialDelay * Math.random() * 0.25;
+  return Math.min(exponentialDelay + jitter, maxDelay);
+}
+async function retryWithBackoff(fn, maxRetries = 3, shouldRetry = isRetryableError) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt === maxRetries) {
+        throw error;
+      }
+      if (!shouldRetry(error)) {
+        throw error;
+      }
+      const delay = calculateBackoff(attempt);
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+async function withTimeout(promise, timeoutMs, timeoutMessage) {
+  const timeoutPromise = new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new AuraTimeoutError(timeoutMessage || `Request timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  return Promise.race([promise, timeoutPromise]);
+}
+
+// src/resources/escrows.ts
+function isEscrowDeployed(e) {
+  if (e.blockchain?.deployed) return true;
+  return ["deployed", "funded", "locked", "released"].includes(e.state ?? "");
+}
+function isEscrowFunded(e) {
+  return ["funded", "locked", "released"].includes(e.state ?? "");
+}
+function parseUsdc(value) {
+  const n = Number.parseFloat(value);
+  return Number.isFinite(n) ? n : 0;
+}
+var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var Escrows = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new escrow
+   */
+  async create(params, idempotencyKey) {
+    return this.client["request"](
+      "POST",
+      "/v1/escrow/create",
+      params,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Get escrow by ID
+   */
+  async get(escrowId) {
+    return this.client["request"]("GET", `/v1/escrow/${escrowId}`);
+  }
+  /**
+   * List escrows with optional filters
+   */
+  async list(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.search) queryParams.set("search", params.search);
+    if (params?.state) queryParams.set("state", params.state);
+    if (params?.sortBy) queryParams.set("sortBy", params.sortBy);
+    if (params?.limit) queryParams.set("limit", params.limit.toString());
+    if (params?.offset) queryParams.set("offset", params.offset.toString());
+    const query = queryParams.toString();
+    const path = query ? `/v1/escrow?${query}` : "/v1/escrow";
+    return this.client["request"]("GET", path);
+  }
+  /**
+   * Fund an escrow
+   */
+  async fund(params, idempotencyKey) {
+    const { escrowId, ...body } = params;
+    return this.client["request"](
+      "POST",
+      `/v1/escrow/${escrowId}/fund`,
+      body,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Release an escrow
+   */
+  async release(params, idempotencyKey) {
+    const { escrowId, ...body } = params;
+    return this.client["request"](
+      "POST",
+      `/v1/escrow/${escrowId}/release`,
+      body,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Refund an escrow
+   */
+  async refund(params, idempotencyKey) {
+    return this.client["request"](
+      "POST",
+      `/v1/escrow/refund`,
+      params,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * 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.
+   *
+   * 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`
+   *   - `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`)
+   *   - `released` — split to recipients (happy path)
+   *
+   * Resume note: a partial run is resumed by acting on the returned
+   * `escrow.escrowId` (call `fund`/`release` directly) — NOT by re-calling
+   * `receiveAndSplit`, which re-`create`s and would hit a duplicate-orderId error.
+   * Pass a stable `idempotencyKey` for retry-safe fund/release.
+   *
+   * Funding is asynchronous and the platform's fund/release endpoints return
+   * operation metadata (not a full escrow), so this method re-`get`s the escrow
+   * for authoritative state + splits rather than trusting those response bodies.
+   *
+   * @throws AuraValidationError if split percentages don't sum to 100 (pre-flight).
+   */
+  async receiveAndSplit(params) {
+    const {
+      orderId,
+      payerOwnerId,
+      amount,
+      splits,
+      chain,
+      actorId,
+      autoRelease = true,
+      waitForDeploymentMs = 6e4,
+      waitForFundingMs = 6e4,
+      pollIntervalMs = 2e3,
+      idempotencyKey
+    } = params;
+    const pctSum = splits.reduce((acc, s) => acc + s.percentage, 0);
+    if (Math.round(pctSum * 100) !== 1e4) {
+      throw new AuraValidationError(
+        `Split percentages must sum to 100 (got ${pctSum}).`,
+        { splits }
+      );
+    }
+    const runKey = idempotencyKey ?? generateIdempotencyKey();
+    const pollMs = Math.max(pollIntervalMs, 250);
+    const created = await this.create(
+      { orderId, buyerOwnerId: payerOwnerId, amount, chain, splits },
+      `${runKey}-create`
+    );
+    const escrowId = created.escrowId;
+    const deployed = await this.pollEscrowUntil(
+      escrowId,
+      isEscrowDeployed,
+      waitForDeploymentMs,
+      pollMs,
+      created
+    );
+    if (!isEscrowDeployed(deployed)) {
+      return {
+        stage: "created",
+        escrow: deployed,
+        splits: deployed.splits,
+        deploymentPending: true
+      };
+    }
+    const payerWalletId = deployed.buyerWalletId;
+    const balance = await this.client.wallets.getBalance(payerWalletId);
+    if (parseUsdc(balance.balance.usdc) < parseUsdc(amount)) {
+      return {
+        stage: "deployed",
+        escrow: deployed,
+        splits: deployed.splits,
+        fundingRequired: {
+          payerWalletId,
+          payerAddress: deployed.buyerWallet.address,
+          amount,
+          available: balance.balance.usdc
+        }
+      };
+    }
+    await this.fund(
+      { escrowId, buyerWalletId: payerWalletId, amount },
+      `${runKey}-fund`
+    );
+    const funded = await this.pollEscrowUntil(
+      escrowId,
+      isEscrowFunded,
+      waitForFundingMs,
+      pollMs,
+      deployed
+    );
+    if (!isEscrowFunded(funded)) {
+      return { stage: "funded", escrow: funded, splits: funded.splits, fundingPending: true };
+    }
+    if (!autoRelease) {
+      return { stage: "funded", escrow: funded, splits: funded.splits };
+    }
+    await this.release(
+      { escrowId, actorId: actorId ?? payerOwnerId, reason: "receiveAndSplit auto-release" },
+      `${runKey}-release`
+    );
+    const final = await this.get(escrowId);
+    return { stage: "released", escrow: final, splits: final.splits };
+  }
+  /**
+   * Poll `get(escrowId)` until `predicate` holds or `budgetMs` elapses. Returns
+   * the last-observed escrow; the caller re-checks the predicate to branch.
+   * `seed` is the escrow already in hand, checked before any poll so a
+   * synchronously-settled escrow returns without a network round-trip.
+   */
+  async pollEscrowUntil(escrowId, predicate, budgetMs, pollMs, seed) {
+    let escrow = seed;
+    if (predicate(escrow)) return escrow;
+    const deadline = Date.now() + budgetMs;
+    while (Date.now() < deadline) {
+      await sleep2(pollMs);
+      escrow = await this.get(escrowId);
+      if (predicate(escrow)) break;
+    }
+    return escrow;
+  }
+  /**
+   * Create a dispute for an escrow
+   */
+  async createDispute(params, idempotencyKey) {
+    return this.client["request"](
+      "POST",
+      `/v1/escrow/${params.escrowId}/dispute`,
+      params,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Get dispute details
+   */
+  async getDispute(escrowId, disputeId) {
+    return this.client["request"](
+      "GET",
+      `/v1/escrow/${escrowId}/dispute/${disputeId}`
+    );
+  }
+};
+var Mandates = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List mandates for the authenticated account. Defaults to `status=pending`
+   * so this acts as the operator's inbox out of the box.
+   */
+  async list(params) {
+    const query = new URLSearchParams();
+    if (params?.status) query.set("status", params.status);
+    if (params?.agentId) query.set("agentId", params.agentId);
+    if (params?.limit !== void 0) query.set("limit", String(params.limit));
+    if (params?.cursor) query.set("cursor", params.cursor);
+    const qs = query.toString();
+    return this.client["request"](
+      "GET",
+      qs ? `/v1/agent/mandates?${qs}` : "/v1/agent/mandates"
+    );
+  }
+  /**
+   * Convenience wrapper for the most common case: pending mandates in
+   * urgency order (most-expiring first).
+   */
+  async listPending(extras) {
+    return this.list({ ...extras, status: "pending" });
+  }
+  /**
+   * Get a single mandate by id.
+   */
+  async get(mandateId) {
+    return this.client["request"](
+      "GET",
+      `/v1/agent/mandates/${mandateId}`
+    );
+  }
+  /**
+   * Approve a pending mandate. Caller is responsible for computing
+   * `decisionSignature` — use `MandateSignature.compute()` below.
+   *
+   * Idempotent: re-approving an already-`approved` mandate returns 200 with
+   * the existing decision. Approving a `rejected`/`cancelled` mandate
+   * returns 409.
+   */
+  async approve(params, idempotencyKey) {
+    const { mandateId, ...body } = params;
+    return this.client["request"](
+      "POST",
+      `/v1/agent/mandates/${mandateId}/approve`,
+      body,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Reject a pending mandate. Same signature scheme as `approve`.
+   */
+  async reject(params, idempotencyKey) {
+    const { mandateId, ...body } = params;
+    return this.client["request"](
+      "POST",
+      `/v1/agent/mandates/${mandateId}/reject`,
+      body,
+      { idempotencyKey }
+    );
+  }
+};
+var MandateSignature = {
+  compute(input) {
+    const payload = `${input.mandateId}:${input.decision}:${input.decidedAt}`;
+    return createHmac("sha256", input.secret).update(payload).digest("hex");
+  },
+  verify(input) {
+    const expected = MandateSignature.compute({
+      mandateId: input.mandateId,
+      decision: input.decision,
+      decidedAt: input.decidedAt,
+      secret: input.secret
+    });
+    if (expected.length !== input.signature.length) return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++) {
+      diff |= expected.charCodeAt(i) ^ input.signature.charCodeAt(i);
+    }
+    return diff === 0;
+  }
+};
+
+// src/resources/policies.ts
+var Policies = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List all policies attached to an agent.
+   */
+  async list(agentId) {
+    return this.client["request"](
+      "GET",
+      `/v1/agents/${agentId}/policies`
+    );
+  }
+  /**
+   * Get a single policy by id (scoped to the parent agent).
+   */
+  async get(agentId, policyId) {
+    return this.client["request"](
+      "GET",
+      `/v1/agents/${agentId}/policies/${policyId}`
+    );
+  }
+  /**
+   * Create a new policy for an agent. The agent's policy engine will start
+   * matching against this policy on the next evaluation.
+   */
+  async create(params, idempotencyKey) {
+    const { agentId, ...body } = params;
+    return this.client["request"](
+      "POST",
+      `/v1/agents/${agentId}/policies`,
+      body,
+      { idempotencyKey }
+    );
+  }
+};
+
+// src/resources/wallets.ts
+var Wallets = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new wallet
+   */
+  async create(params, idempotencyKey) {
+    return this.client["request"](
+      "POST",
+      "/v1/wallets",
+      params,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Get wallet by ID
+   */
+  async get(walletId) {
+    return this.client["request"]("GET", `/v1/wallets/${walletId}`);
+  }
+  /**
+   * List wallets with optional filters
+   */
+  async list(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.entityId) queryParams.set("entityId", params.entityId);
+    if (params?.chain) queryParams.set("chain", params.chain);
+    if (params?.type) queryParams.set("type", params.type);
+    if (params?.page) queryParams.set("page", params.page.toString());
+    if (params?.limit) queryParams.set("limit", params.limit.toString());
+    const query = queryParams.toString();
+    const path = query ? `/v1/wallets?${query}` : "/v1/wallets";
+    return this.client["request"]("GET", path);
+  }
+  /**
+   * Get wallet balance
+   */
+  async getBalance(walletId) {
+    return this.client["request"](
+      "GET",
+      `/v1/wallets/${walletId}/balance`
+    );
+  }
+  /**
+   * Transfer funds from wallet
+   */
+  async transfer(params) {
+    const idempotencyKey = params.idempotencyKey || this.generateIdempotencyKey();
+    return this.client["request"](
+      "POST",
+      `/v1/wallets/${params.fromWalletId}/transfer`,
+      params,
+      { idempotencyKey }
+    );
+  }
+  /**
+   * Request testnet funds (USDC) for a wallet from the platform faucet.
+   *
+   * Testnet only. Backed by `POST /v1/wallets/:id/faucet`, provided by the
+   * platform (AURA-010). Until that endpoint ships, this capability-probes and
+   * raises {@link AuraFaucetUnavailableError} (rather than a generic 404/501)
+   * so callers can degrade gracefully to manual funding.
+   */
+  async requestTestnetFunds(walletId, params) {
+    try {
+      return await this.client["request"](
+        "POST",
+        `/v1/wallets/${walletId}/faucet`,
+        params ?? {}
+      );
+    } catch (err) {
+      if (err instanceof AuraAPIError && err.statusCode === 501) {
+        throw new AuraFaucetUnavailableError(
+          "Testnet faucet is not enabled on this deployment yet (POST /v1/wallets/:id/faucet returned 501). Fund the wallet manually, or ask the operator to enable the faucet endpoint."
+        );
+      }
+      throw err;
+    }
+  }
+  /**
+   * Get transfer by ID
+   */
+  async getTransfer(walletId, transferId) {
+    return this.client["request"](
+      "GET",
+      `/v1/wallets/${walletId}/transfers/${transferId}`
+    );
+  }
+  /**
+   * Generate a unique idempotency key
+   */
+  generateIdempotencyKey() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+  }
+};
+var Webhooks = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Configure webhook endpoint and events
+   */
+  async configure(params) {
+    return this.client["request"](
+      "POST",
+      "/v1/webhooks/config",
+      params
+    );
+  }
+  /**
+   * Get current webhook configuration
+   */
+  async getConfig() {
+    return this.client["request"]("GET", "/v1/webhooks/config");
+  }
+  /**
+   * Delete webhook configuration
+   */
+  async delete() {
+    return this.client["request"](
+      "DELETE",
+      "/v1/webhooks/config"
+    );
+  }
+  /**
+   * Validate webhook signature
+   * Use this in your webhook handler to verify authenticity
+   */
+  static validateSignature(options) {
+    try {
+      const { payload, signature, secret, toleranceMs = 3e5 } = options;
+      const payloadString = typeof payload === "string" ? payload : JSON.stringify(payload);
+      const { timestamp, v1 } = this.parseSignatureHeader(signature);
+      const ageMs = Math.abs(Date.now() - timestamp);
+      if (ageMs > toleranceMs) {
+        return { valid: false, error: "Signature timestamp expired" };
+      }
+      const expectedSignature = this.computeHmacSignature(`${timestamp}.${payloadString}`, secret);
+      const valid = this.secureCompare(v1, expectedSignature);
+      if (!valid) {
+        return {
+          valid: false,
+          error: "Invalid signature"
+        };
+      }
+      const event = typeof payload === "string" ? JSON.parse(payload) : payload;
+      return {
+        valid: true,
+        event
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  /**
+   * Parse signature header: "t=timestamp,v1=signature"
+   */
+  static parseSignatureHeader(signatureHeader) {
+    const parts = signatureHeader.split(",").map((p) => p.trim());
+    const tPart = parts.find((p) => p.startsWith("t="));
+    const v1Part = parts.find((p) => p.startsWith("v1="));
+    if (!tPart || !v1Part) {
+      throw new Error("Invalid signature header format (expected: t=...,v1=...)");
+    }
+    const timestamp = parseInt(tPart.slice(2), 10);
+    const v1 = v1Part.slice(3);
+    if (!Number.isFinite(timestamp) || timestamp <= 0) {
+      throw new Error("Invalid signature timestamp");
+    }
+    if (!v1) {
+      throw new Error("Invalid signature value");
+    }
+    return { timestamp, v1 };
+  }
+  /**
+   * 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
+   */
+  static secureCompare(a, b) {
+    if (a.length !== b.length) {
+      return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+      result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+  }
+};
+
+// src/client.ts
+var AuraClient = class _AuraClient {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = _AuraClient.normalizeBaseUrl(config.baseUrl);
+    this.timeout = config.timeout || 3e4;
+    this.maxRetries = config.maxRetries || 3;
+    this.autoIdempotency = config.autoIdempotency !== false;
+    if (!this.apiKey) {
+      throw new AuraError("API key is required", "MISSING_API_KEY");
+    }
+    this.escrows = new Escrows(this);
+    this.wallets = new Wallets(this);
+    this.webhooks = new Webhooks(this);
+    this.agents = new Agents(this);
+    this.policies = new Policies(this);
+    this.mandates = new Mandates(this);
+  }
+  /**
+   * Normalize the base URL so resource paths like `/v1/escrow` reach the
+   * platform's `/api/v1/escrow` route regardless of how the caller framed
+   * `baseUrl`. Trailing slashes are trimmed; missing `/api` is appended.
+   *
+   * @internal exported pattern for tests; do not call directly.
+   */
+  static normalizeBaseUrl(input) {
+    const raw = (input || "https://getaura.sh/api").replace(/\/+$/, "");
+    if (/\/api(\/v\d+)?$/.test(raw) || /\/api$/.test(raw)) {
+      return raw;
+    }
+    return `${raw}/api`;
+  }
+  /**
+   * Get the API key
+   */
+  getApiKey() {
+    return this.apiKey;
+  }
+  /**
+   * Get the base URL
+   */
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+  /**
+   * Get the timeout value
+   */
+  getTimeout() {
+    return this.timeout;
+  }
+  /**
+   * Get the max retries value
+   */
+  getMaxRetries() {
+    return this.maxRetries;
+  }
+  /**
+   * 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);
+    if (options?.skipRetry || method === "GET") {
+      return requestFn();
+    }
+    return retryWithBackoff(requestFn, this.maxRetries);
+  }
+  /**
+   * Execute a single HTTP request (internal)
+   */
+  async executeRequest(method, path, body, options) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${this.apiKey}`,
+      "User-Agent": "@aura-payments/sdk/2.1.0"
+    };
+    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(
+        fetch(url, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0
+        }),
+        this.timeout
+      );
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      if (response.status === 204) {
+        return void 0;
+      }
+      const data = await response.json();
+      return this.normalizeResponse(data);
+    } catch (error) {
+      if (error instanceof TypeError && error.message.includes("fetch")) {
+        throw new AuraNetworkError("Network request failed", error);
+      }
+      if (error instanceof AuraError) {
+        throw error;
+      }
+      throw new AuraError(
+        error instanceof Error ? error.message : "Unknown error occurred",
+        "UNKNOWN_ERROR"
+      );
+    }
+  }
+  /**
+   * Normalize API responses across different wrapper formats.
+   *
+   * The platform API currently uses two common success wrappers:
+   * - { success: true, data: T, ... }
+   * - { data: T, meta: {...} } (and sometimes { data: T[], meta, pagination })
+   *
+   * SDK methods generally return the inner `data` payload, except for paginated
+   * endpoints where pagination metadata is meaningful and preserved.
+   */
+  normalizeResponse(payload) {
+    if (!payload || typeof payload !== "object") return payload;
+    const obj = payload;
+    if ("success" in obj && "data" in obj) {
+      return obj.data;
+    }
+    if ("data" in obj && ("meta" in obj || "metadata" in obj)) {
+      if ("pagination" in obj) {
+        return obj;
+      }
+      return obj.data;
+    }
+    if ("data" in obj && Object.keys(obj).length <= 2) {
+      return obj.data;
+    }
+    return payload;
+  }
+  /**
+   * Handle HTTP error responses and throw appropriate errors
+   */
+  async handleErrorResponse(response) {
+    const statusCode = response.status;
+    let errorData = {};
+    try {
+      const data = await response.json();
+      if (typeof data === "object" && data !== null) {
+        errorData = data;
+      }
+    } catch {
+      errorData = { message: response.statusText };
+    }
+    const message = errorData.message || `HTTP ${statusCode} error`;
+    const code = errorData.code;
+    const details = errorData.details;
+    switch (statusCode) {
+      case 400:
+        throw new AuraValidationError(message, details);
+      case 401:
+        throw new AuraAuthenticationError(message);
+      case 404:
+        throw new AuraNotFoundError(message);
+      case 429: {
+        const retryAfter = response.headers.get("Retry-After");
+        throw new AuraRateLimitError(message, retryAfter ? parseInt(retryAfter) : void 0);
+      }
+      case 408:
+        throw new AuraTimeoutError(message);
+      default:
+        throw new AuraAPIError(message, statusCode, code, details);
+    }
+  }
+  /**
+   * Get the auto-idempotency setting
+   */
+  getAutoIdempotency() {
+    return this.autoIdempotency;
+  }
+};
+
+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