@aura-payments/sdk 2.1.0

package/dist/index.d.ts

@@ -0,0 +1,1292 @@
+import { PaginatedResponse } from '@aura-payments/shared';
+export { PaginatedResponse, PaginationParams } from '@aura-payments/shared';
+
+/**
+ * Escrow types for Aura Payments SDK
+ * Public API types for external developers
+ */
+/**
+ * Escrow states (matches API schema)
+ */
+type EscrowState = "initiated" | "deployed" | "funded" | "locked" | "released" | "refunded" | "disputed";
+type UnlockType = "oracle" | "timeout" | "hybrid" | "manual";
+type DisputeStatus = "open" | "investigating" | "resolved" | "closed";
+/**
+ * Supported blockchain chains
+ */
+type Chain = "ARC" | "ARB" | "BASE" | "ETH" | "MATIC";
+/**
+ * Owner types for escrow splits
+ */
+type OwnerType = "buyer" | "seller" | "platform" | "vendor" | "creator" | "affiliate" | "logistics" | "tax";
+/**
+ * Split roles (excludes buyer)
+ */
+type SplitRole = "seller" | "platform" | "vendor" | "creator" | "affiliate" | "logistics" | "tax";
+/**
+ * Split configuration for creating escrow (input)
+ */
+interface EscrowSplitInput {
+    ownerType: OwnerType;
+    ownerId: string;
+    role: SplitRole;
+    percentage: number;
+}
+/**
+ * Split in API response
+ */
+interface EscrowSplitResponse {
+    splitId: string;
+    role: string;
+    basisPoints: number;
+    recipientWallet: {
+        walletId: string;
+        address: string;
+    };
+}
+/**
+ * Main escrow object (from GET /v1/escrow/:id)
+ */
+interface Escrow {
+    escrowId: string;
+    orderId: string;
+    state: EscrowState;
+    buyerWalletId: string;
+    escrowWallet: {
+        walletId: string;
+        address: string;
+        circleWalletId: string;
+    };
+    buyerWallet: {
+        walletId: string;
+        address: string;
+    };
+    amount: string;
+    splits: EscrowSplitResponse[];
+    blockchain?: {
+        contractAddress: string | null;
+        chain: string;
+        factoryAddress: string | null;
+        deployed: boolean;
+        mode: string;
+    };
+    createdAt: string;
+}
+/**
+ * Parameters for creating an escrow
+ *
+ * Minimums:
+ * - `amount` must be large enough that, after platform fees (~1% + ~$0.009
+ *   gas), each split receives at least $1 USDC. As a safe floor, use $10+
+ *   for production flows; very small escrows ($1–$3) will be rejected with
+ *   `VALIDATION_ERROR` when net-after-fees per split falls below $1.
+ */
+interface CreateEscrowParams {
+    orderId: string;
+    buyerOwnerId: string;
+    amount: string;
+    chain?: Chain;
+    splits: EscrowSplitInput[];
+}
+/**
+ * Response from creating an escrow
+ *
+ * When created with async mode (default), includes:
+ * - async: true - indicates blockchain deployment is in progress
+ * - webhookPending: true - webhook will be sent when deployment completes
+ * - state: 'pending' - will transition to 'deployed' after contract deployment
+ */
+interface CreateEscrowResponse {
+    escrowId: string;
+    orderId: string;
+    state: EscrowState;
+    buyerWalletId: string;
+    escrowWallet: {
+        walletId: string;
+        address: string;
+        circleWalletId: string;
+    };
+    buyerWallet: {
+        walletId: string;
+        address: string;
+    };
+    amount: string;
+    splits: EscrowSplitResponse[];
+    blockchain?: {
+        contractAddress: string | null;
+        chain: string;
+        factoryAddress: string | null;
+        deployed: boolean;
+        mode: string;
+    };
+    unlock?: {
+        type: 'manual' | 'timeout' | 'oracle' | 'hybrid';
+        unlockAt: string | null;
+        delaySeconds: number | null;
+    };
+    createdAt: string;
+    /** Present when using async mode (default) - indicates deployment in progress */
+    async?: boolean;
+    /** Present when using async mode - webhook will be sent on completion */
+    webhookPending?: boolean;
+}
+/**
+ * Parameters for funding an escrow
+ */
+interface FundEscrowParams {
+    escrowId: string;
+    buyerWalletId: string;
+    amount: string;
+    correlationId?: string;
+}
+/**
+ * Parameters for releasing an escrow
+ */
+interface ReleaseEscrowParams {
+    escrowId: string;
+    actorId: string;
+    reason?: string;
+    correlationId?: string;
+}
+/**
+ * Parameters for refunding an escrow
+ */
+interface RefundEscrowParams {
+    escrowId: string;
+    reason: string;
+    actorId: string;
+}
+/**
+ * How far the `receiveAndSplit` loop progressed.
+ * - `created`   — escrow created, on-chain deployment not yet confirmed
+ * - `deployed`  — deployed, but funds not moved (payer balance short → see fundingRequired)
+ * - `funded`    — escrow funded; not released (autoRelease:false)
+ * - `released`  — funds split to recipients (terminal happy path)
+ */
+type ReceiveAndSplitStage = 'created' | 'deployed' | 'funded' | 'released';
+/**
+ * Parameters for the one-call receive→split primitive (board D4).
+ * Composes the existing create → fund → release escrow path.
+ */
+interface ReceiveAndSplitParams {
+    /** Caller-provided order id, unique per account. */
+    orderId: string;
+    /** Entity that funds the escrow. May be the agent itself or a counterparty. */
+    payerOwnerId: string;
+    /** Whole-number USDC amount as a string (e.g. "50"). */
+    amount: string;
+    /** Payment splits; percentages must sum to 100. */
+    splits: EscrowSplitInput[];
+    /** Target chain. Defaults to 'ARC' (→ ARC-TESTNET). */
+    chain?: Chain;
+    /** Actor recorded on release. Defaults to `payerOwnerId`. */
+    actorId?: string;
+    /** Auto-release immediately after funding. Default true. */
+    autoRelease?: boolean;
+    /** Max time to wait for on-chain deployment before returning stage:'created'. Default 60000. */
+    waitForDeploymentMs?: number;
+    /** Max time to wait for funds to settle (funded/locked) before releasing. Default 60000. */
+    waitForFundingMs?: number;
+    /** Poll interval while waiting for deployment/funding (floored at 250ms). Default 2000. */
+    pollIntervalMs?: number;
+    /** Idempotency key for the create call (fund/release derive suffixed keys). */
+    idempotencyKey?: string;
+}
+/**
+ * Present when `receiveAndSplit` stops at `deployed` because the payer wallet
+ * lacks the funds to fund the escrow. Resume by funding this wallet (e.g.
+ * `wallets.requestTestnetFunds`) then re-running fund + release.
+ */
+interface ReceiveAndSplitFundingRequired {
+    payerWalletId: string;
+    payerAddress: string;
+    /** Amount the escrow needs. */
+    amount: string;
+    /** Payer wallet's current USDC balance. */
+    available: string;
+}
+/**
+ * Result of `receiveAndSplit`. The `stage` field makes partial runs explicit
+ * and resumable instead of throwing opaquely.
+ */
+interface ReceiveAndSplitResult {
+    stage: ReceiveAndSplitStage;
+    escrow: Escrow;
+    splits: EscrowSplitResponse[];
+    /** Set iff stage === 'deployed' due to insufficient payer balance. */
+    fundingRequired?: ReceiveAndSplitFundingRequired;
+    /** Set iff stage === 'created' because deployment didn't confirm in time. */
+    deploymentPending?: boolean;
+    /** Set iff stage === 'funded' because funds didn't settle within waitForFundingMs (do not release yet). */
+    fundingPending?: boolean;
+}
+/**
+ * Dispute object
+ */
+interface Dispute {
+    id: string;
+    escrowId: string;
+    status: DisputeStatus;
+    reason: string;
+    evidence?: string[];
+    actorId: string;
+    resolution?: string;
+    resolvedBy?: string;
+    openedAt: string;
+    closedAt?: string;
+}
+/**
+ * Parameters for creating a dispute
+ */
+interface CreateDisputeParams {
+    escrowId: string;
+    reason: string;
+    actorId: string;
+    evidence?: string[];
+}
+/**
+ * Sort options for escrow list
+ */
+type EscrowSortBy = 'created_desc' | 'created_asc' | 'amount_desc' | 'amount_asc';
+/**
+ * List escrows query parameters (matches API route)
+ */
+interface ListEscrowsParams {
+    /** Search by escrow ID, order ID, or buyer wallet ID */
+    search?: string;
+    /** Filter by escrow state (or 'all' for all states) */
+    state?: EscrowState | 'all';
+    /** Sort order (default: created_desc) */
+    sortBy?: EscrowSortBy;
+    /** Number of results (default: 50) */
+    limit?: number;
+    /** Pagination offset (default: 0) */
+    offset?: number;
+}
+/**
+ * Escrow list item (from GET /v1/escrow response)
+ */
+interface EscrowListItem {
+    id: string;
+    orderId: string;
+    state: string;
+    amountUsdc: string;
+    createdAt: string;
+    buyerWalletId: string;
+    splitCount: number;
+}
+/**
+ * Paginated escrow list response
+ */
+interface ListEscrowsResponse {
+    escrows: EscrowListItem[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+/**
+ * Agent types for Aura Payments SDK.
+ *
+ * Public API types covering the agent lifecycle: create, list, get, update,
+ * freeze/unfreeze, balance, and policy evaluation. Wire shapes match the
+ * platform's `/v1/agents` route handlers exactly — types are kept in sync
+ * with `lib/agents/agent-service.ts` and the Zod schemas in those routes.
+ */
+
+type AgentType = 'treasury' | 'payment' | 'trading' | 'custom';
+type AgentStatus = 'active' | 'paused' | 'archived';
+type AgentRiskTier = 'low' | 'medium' | 'high' | 'critical';
+type SpendingLimitType = 'per_transaction' | 'daily' | 'weekly' | 'monthly' | 'lifetime';
+type MerchantRuleType = 'allowlist' | 'blocklist';
+type MerchantDestinationType = 'address' | 'domain' | 'category' | 'entity_id';
+interface SpendingLimitInput {
+    limitType: SpendingLimitType;
+    /** Whole-number USDC amount as string (e.g. `"100"`). */
+    maxAmount: string;
+    /** Defaults to `"USDC"` server-side. */
+    currency?: string;
+}
+interface MerchantRuleInput {
+    ruleType: MerchantRuleType;
+    destinationType: MerchantDestinationType;
+    /** For `address`, must be `0x` + 40 hex chars (validated server-side). */
+    destinationValue: string;
+}
+interface InitialPolicyInput {
+    name?: string;
+    description?: string;
+    spendingLimits?: SpendingLimitInput[];
+    merchantRules?: MerchantRuleInput[];
+    /** Amount above which a mandate (human approval) is required. */
+    requiresApprovalAbove?: string;
+    /** Amount below which the agent auto-approves without a mandate. */
+    autoApproveBelow?: string;
+}
+interface Agent {
+    id: string;
+    accountId: string;
+    name: string;
+    description?: string | null;
+    type: AgentType;
+    status: AgentStatus;
+    riskTier?: AgentRiskTier | null;
+    chain: Chain;
+    walletId?: string | null;
+    walletAddress?: string | null;
+    metadata?: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateAgentParams {
+    name: string;
+    description?: string;
+    type: AgentType;
+    chain?: Chain;
+    metadata?: Record<string, unknown>;
+    initialPolicy?: InitialPolicyInput;
+}
+interface CreateAgentResponse {
+    agent: Agent;
+    policyId: string;
+    walletId: string;
+    walletAddress: string;
+}
+interface UpdateAgentParams {
+    name?: string;
+    description?: string | null;
+    status?: AgentStatus;
+    metadata?: Record<string, unknown> | null;
+}
+interface ListAgentsParams {
+    status?: AgentStatus;
+    type?: AgentType;
+    limit?: number;
+    offset?: number;
+    orderBy?: 'createdAt' | 'name';
+    orderDirection?: 'asc' | 'desc';
+}
+interface ListAgentsResponse {
+    agents: Agent[];
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+interface FreezeAgentParams {
+    agentId: string;
+    /** Surfaced in the activity event metadata for the audit trail. */
+    reason?: string;
+}
+interface UnfreezeAgentParams {
+    agentId: string;
+}
+/**
+ * Returned by both freeze and unfreeze. `isActive` is a derived view of
+ * `status === 'active'` (no extra column on the agents table).
+ */
+interface AgentStatusResponse {
+    id: string;
+    name: string;
+    status: AgentStatus;
+    isActive: boolean;
+    updatedAt: string;
+}
+interface AgentBalance {
+    agentId: string;
+    walletId: string;
+    walletAddress: string;
+    chain: Chain;
+    /** USDC balance as a decimal string. */
+    amount: string;
+    currency: 'USDC';
+    /** ISO-8601 timestamp of when the balance was fetched on-chain. */
+    fetchedAt: string;
+}
+type PolicyDecision = 'auto_approve' | 'auto_deny' | 'requires_human_approval';
+interface EvaluatePolicyParams {
+    agentId: string;
+    /** USDC amount as decimal string. */
+    amount: string;
+    /** Counterparty wallet address (`0x...`) or merchant identifier. */
+    destination: string;
+    destinationType?: MerchantDestinationType;
+    /** Optional reasoning the agent will log alongside the decision. */
+    reasoning?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EvaluatePolicyResponse {
+    decision: PolicyDecision;
+    /** Human-readable reason for the decision. */
+    reason: string;
+    /** When `requires_human_approval`, the mandate that was created (if any). */
+    mandateId?: string;
+    /** The matched rule(s) that drove the decision. */
+    matchedRules?: Array<{
+        kind: string;
+        ruleId?: string;
+        detail?: string;
+    }>;
+}
+
+/**
+ * Agents resource for the Aura Payments SDK.
+ *
+ * Wraps `/v1/agents/*` routes: create, list, get, update, freeze, unfreeze,
+ * balance, evaluate. All methods are account-scoped via the API key — the
+ * platform extracts `accountId` server-side; the SDK never sends it.
+ */
+
+declare class Agents {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * 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.
+     */
+    create(params: CreateAgentParams, idempotencyKey?: string): Promise<CreateAgentResponse>;
+    /**
+     * List agents for the authenticated account, paginated.
+     */
+    list(params?: ListAgentsParams): Promise<ListAgentsResponse>;
+    /**
+     * Get a single agent by id.
+     */
+    get(agentId: string): Promise<Agent>;
+    /**
+     * 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.
+     */
+    update(agentId: string, params: UpdateAgentParams, idempotencyKey?: string): Promise<Agent>;
+    /**
+     * Freeze (kill switch) — sets status to `paused` and cascade-rejects every
+     * pending mandate the agent has in flight. Idempotent.
+     */
+    freeze(params: FreezeAgentParams, idempotencyKey?: string): Promise<AgentStatusResponse>;
+    /**
+     * Unfreeze — sets status back to `active`. Previously cascade-rejected
+     * mandates are NOT restored; the agent re-creates them on its next loop.
+     */
+    unfreeze(params: UnfreezeAgentParams, idempotencyKey?: string): Promise<AgentStatusResponse>;
+    /**
+     * Get the agent's wallet balance (USDC, on-chain at request time).
+     */
+    getBalance(agentId: string): Promise<AgentBalance>;
+    /**
+     * 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.
+     */
+    evaluate(params: EvaluatePolicyParams, idempotencyKey?: string): Promise<EvaluatePolicyResponse>;
+}
+
+/**
+ * Escrows resource for Aura Payments SDK
+ */
+
+declare class Escrows {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * Create a new escrow
+     */
+    create(params: CreateEscrowParams, idempotencyKey?: string): Promise<CreateEscrowResponse>;
+    /**
+     * Get escrow by ID
+     */
+    get(escrowId: string): Promise<Escrow>;
+    /**
+     * List escrows with optional filters
+     */
+    list(params?: ListEscrowsParams): Promise<ListEscrowsResponse>;
+    /**
+     * Fund an escrow
+     */
+    fund(params: FundEscrowParams, idempotencyKey?: string): Promise<Escrow>;
+    /**
+     * Release an escrow
+     */
+    release(params: ReleaseEscrowParams, idempotencyKey?: string): Promise<Escrow>;
+    /**
+     * Refund an escrow
+     */
+    refund(params: RefundEscrowParams, idempotencyKey?: string): Promise<Escrow>;
+    /**
+     * 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).
+     */
+    receiveAndSplit(params: ReceiveAndSplitParams): Promise<ReceiveAndSplitResult>;
+    /**
+     * 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.
+     */
+    private pollEscrowUntil;
+    /**
+     * Create a dispute for an escrow
+     */
+    createDispute(params: CreateDisputeParams, idempotencyKey?: string): Promise<Dispute>;
+    /**
+     * Get dispute details
+     */
+    getDispute(escrowId: string, disputeId: string): Promise<Dispute>;
+}
+
+/**
+ * Mandate types for Aura Payments SDK.
+ *
+ * A mandate is a single human-approval request raised when the agent's
+ * policy engine returns `requires_human_approval`. Operators decide
+ * (approve/reject) on mobile (biometric/passcode) or via the CLI (manual).
+ *
+ * Wire shape mirrors `agent_mandates` table + `lib/agents/mandate-service.ts`.
+ * Decision signature is HMAC over `${id}:${decision}:${decidedAt}`; the
+ * platform verifies before applying state changes.
+ */
+type MandateStatus = 'pending' | 'approved' | 'rejected' | 'cancelled';
+type MandateDecisionMethod = 'biometric' | 'passcode' | 'manual' | 'ttl_expired';
+/**
+ * Discriminated union for the kinds of intents a mandate can carry.
+ * Each kind has its own `intent.payload` shape that the operator UI
+ * renders differently.
+ */
+type MandateIntentKind = 'x402.payment' | 'escrow.fund' | 'escrow.release' | 'agent.policy.proposed' | 'agent.transfer';
+interface MandateIntent {
+    kind: MandateIntentKind;
+    /** Human-readable summary the operator sees. */
+    summary: string;
+    /** Optional decimal-string amount in USDC (most kinds carry this). */
+    amount?: string;
+    currency?: 'USDC';
+    counterparty?: string;
+    /** Kind-specific payload. Type narrows on `kind`. */
+    payload: Record<string, unknown>;
+}
+interface Mandate {
+    id: string;
+    accountId: string;
+    agentId: string;
+    /** Denormalized agent name so inbox rows render without a join. */
+    agentName: string;
+    status: MandateStatus;
+    intent: MandateIntent;
+    /** ISO-8601. After this, the TTL sweeper auto-rejects. */
+    expiresAt: string;
+    createdAt: string;
+    decidedAt?: string;
+    /** User id of the operator who decided, or `kill-switch:<agentId>` for cascade. */
+    decidedBy?: string;
+    decisionMethod?: MandateDecisionMethod;
+    decisionSignature?: string;
+}
+interface ListMandatesParams {
+    status?: MandateStatus;
+    agentId?: string;
+    /** Page size, 1-200, defaults to 50. */
+    limit?: number;
+    /** Last mandate id from the previous page. */
+    cursor?: string;
+}
+interface ListMandatesResponse {
+    mandates: Mandate[];
+    /** Pass back as `cursor` to fetch the next page. `null` at end. */
+    nextCursor: string | null;
+}
+interface ApproveMandateParams {
+    mandateId: string;
+    /**
+     * `biometric`/`passcode` come from the mobile flow, `manual` from CLI/web.
+     * `ttl_expired` is reserved for the server-side sweeper.
+     */
+    decisionMethod: Exclude<MandateDecisionMethod, 'ttl_expired'>;
+    /**
+     * HMAC-SHA256 over `${mandateId}:approve:${decidedAt}`. Computed by the
+     * caller; the platform re-derives and verifies before applying.
+     */
+    decisionSignature: string;
+    /** ISO-8601. The signature commits to this; defaults to "now" server-side. */
+    decidedAt?: string;
+}
+interface RejectMandateParams {
+    mandateId: string;
+    decisionMethod: Exclude<MandateDecisionMethod, 'ttl_expired'>;
+    decisionSignature: string;
+    decidedAt?: string;
+    /** Optional human-readable reason logged to the activity feed. */
+    reason?: string;
+}
+
+/**
+ * Mandates resource for the Aura Payments SDK.
+ *
+ * Wraps `/v1/agent/mandates/*` routes (operator-facing inbox). Approve/reject
+ * require an HMAC decision signature — see `MandateSignature` helper below
+ * for computing it client-side.
+ */
+
+declare class Mandates {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * List mandates for the authenticated account. Defaults to `status=pending`
+     * so this acts as the operator's inbox out of the box.
+     */
+    list(params?: ListMandatesParams): Promise<ListMandatesResponse>;
+    /**
+     * Convenience wrapper for the most common case: pending mandates in
+     * urgency order (most-expiring first).
+     */
+    listPending(extras?: Omit<ListMandatesParams, 'status'>): Promise<ListMandatesResponse>;
+    /**
+     * Get a single mandate by id.
+     */
+    get(mandateId: string): Promise<Mandate>;
+    /**
+     * 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.
+     */
+    approve(params: ApproveMandateParams, idempotencyKey?: string): Promise<Mandate>;
+    /**
+     * Reject a pending mandate. Same signature scheme as `approve`.
+     */
+    reject(params: RejectMandateParams, idempotencyKey?: string): Promise<Mandate>;
+}
+/**
+ * Computes / verifies the HMAC-SHA256 signature the platform requires when
+ * deciding a mandate. The signature commits to the mandate id, the decision
+ * verb, and the timestamp so a stolen "approve" payload can't be replayed
+ * against a different mandate.
+ *
+ * Usage:
+ * ```ts
+ * const decidedAt = new Date().toISOString()
+ * const sig = MandateSignature.compute({
+ *   mandateId,
+ *   decision: 'approve',
+ *   decidedAt,
+ *   secret: process.env.MANDATE_HMAC_SECRET!,
+ * })
+ * await client.mandates.approve({
+ *   mandateId,
+ *   decisionMethod: 'manual',
+ *   decisionSignature: sig,
+ *   decidedAt,
+ * })
+ * ```
+ *
+ * The platform's verify lives at `lib/agents/mandate-signature.ts` and uses
+ * the same `${id}:${decision}:${decidedAt}` payload format. Keep them
+ * synchronized.
+ */
+declare const MandateSignature: {
+    compute(input: {
+        mandateId: string;
+        decision: 'approve' | 'reject';
+        decidedAt: string;
+        secret: string;
+    }): string;
+    verify(input: {
+        mandateId: string;
+        decision: 'approve' | 'reject';
+        decidedAt: string;
+        secret: string;
+        signature: string;
+    }): boolean;
+};
+
+/**
+ * Policy types for Aura Payments SDK.
+ *
+ * Policies are the persistent rules that drive the agent's policy engine.
+ * Each agent has 1+ policies; each policy has spending limits + merchant
+ * rules + approval thresholds. Approving an `agent.policy.proposed` mandate
+ * creates a new policy via the same shape.
+ */
+
+interface SpendingLimit {
+    id: string;
+    agentId: string;
+    policyId: string;
+    limitType: SpendingLimitInput['limitType'];
+    maxAmount: string;
+    currency: string;
+    createdAt: string;
+}
+interface MerchantRule {
+    id: string;
+    agentId: string;
+    policyId: string;
+    ruleType: MerchantRuleInput['ruleType'];
+    destinationType: MerchantRuleInput['destinationType'];
+    destinationValue: string;
+    createdAt: string;
+}
+interface AgentPolicy {
+    id: string;
+    accountId: string;
+    agentId: string;
+    name?: string | null;
+    description?: string | null;
+    /** Amount above which a mandate is required. Decimal string in USDC. */
+    requiresApprovalAbove?: string | null;
+    /** Amount below which the agent auto-approves silently. */
+    autoApproveBelow?: string | null;
+    spendingLimits: SpendingLimit[];
+    merchantRules: MerchantRule[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreatePolicyParams {
+    agentId: string;
+    name?: string;
+    description?: string;
+    spendingLimits?: SpendingLimitInput[];
+    merchantRules?: MerchantRuleInput[];
+    requiresApprovalAbove?: string;
+    autoApproveBelow?: string;
+}
+interface ListPoliciesResponse {
+    policies: AgentPolicy[];
+    total: number;
+}
+
+/**
+ * Policies resource for the Aura Payments SDK.
+ *
+ * Wraps `/v1/agents/{agentId}/policies/*` routes for managing the persistent
+ * rules that drive the policy engine. Note: approving an `agent.policy.proposed`
+ * mandate also creates a new policy server-side — this resource is for direct
+ * policy CRUD outside the mandate flow.
+ */
+
+declare class Policies {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * List all policies attached to an agent.
+     */
+    list(agentId: string): Promise<ListPoliciesResponse>;
+    /**
+     * Get a single policy by id (scoped to the parent agent).
+     */
+    get(agentId: string, policyId: string): Promise<AgentPolicy>;
+    /**
+     * Create a new policy for an agent. The agent's policy engine will start
+     * matching against this policy on the next evaluation.
+     */
+    create(params: CreatePolicyParams, idempotencyKey?: string): Promise<AgentPolicy>;
+}
+
+/**
+ * Wallet types for Aura Payments SDK
+ * Public API types for external developers
+ */
+
+/**
+ * Wallet owner types - matches escrow split roles
+ */
+type WalletOwnerType = 'BUSINESS' | 'buyer' | 'seller' | 'platform' | 'vendor' | 'creator' | 'affiliate' | 'logistics' | 'tax' | 'escrow';
+/**
+ * Wallet object (from API response)
+ */
+interface Wallet {
+    id: string;
+    accountId: string;
+    circleWalletId: string;
+    address: string;
+    chain: string;
+    custodyType: string;
+    ownerType: string;
+    ownerId: string;
+    userId: string | null;
+    circleUserId: string | null;
+    createdAt: string;
+}
+/**
+ * Resolved wallet returned by POST /v1/wallets (create-or-get).
+ * Note: the platform API returns `walletId` (not `id`) here for historical reasons.
+ */
+interface ResolvedWallet {
+    walletId: string;
+    circleWalletId: string;
+    address: string;
+    ownerType: string;
+    ownerId: string;
+    chain: string;
+    createdAt: string;
+    accountId: string;
+    isNew: boolean;
+}
+/**
+ * Individual token balance
+ */
+interface TokenBalance {
+    token: string;
+    symbol: string;
+    amount: string;
+    decimals: number;
+}
+/**
+ * Wallet balance response (GET /v1/wallets/:walletId/balance)
+ */
+interface WalletBalance {
+    walletId: string;
+    address: string;
+    chain: Chain;
+    balance: {
+        usdc: string;
+        tokenBalances: TokenBalance[];
+    };
+    tokens?: TokenBalance[];
+}
+/**
+ * Parameters for creating a wallet (matches createWalletRequestSchema)
+ */
+interface CreateWalletParams {
+    /** Your unique entity identifier */
+    entityId: string;
+    /** Blockchain chain (default: 'ARC') */
+    chain?: Chain;
+    /** Wallet owner type (default: 'BUSINESS') */
+    type?: WalletOwnerType;
+}
+/**
+ * Parameters for wallet transfer
+ */
+interface TransferParams {
+    fromWalletId: string;
+    toAddress: string;
+    amount: string;
+    token?: string;
+    idempotencyKey?: string;
+}
+/**
+ * Transfer response
+ */
+interface Transfer {
+    id: string;
+    txHash: string;
+    status: 'pending' | 'confirmed' | 'failed';
+    amount: string;
+    token: string;
+    fromAddress: string;
+    toAddress: string;
+    chain: Chain;
+    createdAt: string;
+    confirmedAt?: string;
+}
+/**
+ * Parameters for requesting testnet funds from the faucet.
+ *
+ * Testnet only. Backed by `POST /v1/wallets/:id/faucet` (provided by AURA-010);
+ * see {@link AuraFaucetUnavailableError} for the not-yet-deployed case.
+ */
+interface RequestTestnetFundsParams {
+    /** Token to drip. Default: 'USDC'. */
+    token?: string;
+    /** Override the wallet's chain (testnet codes only). */
+    chain?: Chain;
+}
+/**
+ * Faucet response. Drips are asynchronous on-chain — the wallet balance may
+ * take a few seconds to reflect the funds.
+ */
+interface RequestTestnetFundsResponse {
+    requested: boolean;
+    walletId: string;
+    address: string;
+    chain: string;
+    token: string;
+    /** Optional human-readable note (e.g. "drip queued; allow ~30s"). */
+    note?: string;
+}
+/**
+ * List wallets query parameters
+ */
+interface ListWalletsParams {
+    entityId?: string;
+    chain?: Chain;
+    type?: WalletOwnerType;
+    page?: number;
+    limit?: number;
+}
+/**
+ * Paginated wallet list response
+ */
+type ListWalletsResponse = PaginatedResponse<Wallet>;
+
+/**
+ * Wallets resource for Aura Payments SDK
+ */
+
+declare class Wallets {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * Create a new wallet
+     */
+    create(params: CreateWalletParams, idempotencyKey?: string): Promise<ResolvedWallet>;
+    /**
+     * Get wallet by ID
+     */
+    get(walletId: string): Promise<Wallet>;
+    /**
+     * List wallets with optional filters
+     */
+    list(params?: ListWalletsParams): Promise<ListWalletsResponse>;
+    /**
+     * Get wallet balance
+     */
+    getBalance(walletId: string): Promise<WalletBalance>;
+    /**
+     * Transfer funds from wallet
+     */
+    transfer(params: TransferParams): Promise<Transfer>;
+    /**
+     * 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.
+     */
+    requestTestnetFunds(walletId: string, params?: RequestTestnetFundsParams): Promise<RequestTestnetFundsResponse>;
+    /**
+     * Get transfer by ID
+     */
+    getTransfer(walletId: string, transferId: string): Promise<Transfer>;
+    /**
+     * Generate a unique idempotency key
+     */
+    private generateIdempotencyKey;
+}
+
+/**
+ * Webhook types for Aura Payments SDK
+ * Public API types for external developers
+ */
+/**
+ * Webhook event types (matches Platform `lib/webhooks/types.ts`)
+ *
+ * Note: `'*'` is a special subscription value meaning "all events".
+ */
+type WebhookEventType = '*' | 'escrow.created' | 'escrow.funded' | 'escrow.locked' | 'escrow.released' | 'escrow.refunded' | 'escrow.disputed' | 'transfer.completed' | 'transfer.failed' | 'withdrawal.created' | 'withdrawal.processing' | 'withdrawal.completed' | 'withdrawal.failed' | 'account.kyc_approved' | 'account.kyc_rejected' | 'account.tier_upgraded' | 'security.api_key_created' | 'security.api_key_revoked';
+/**
+ * Webhook event payload
+ */
+interface WebhookEvent<T = Record<string, unknown>> {
+    id: string;
+    type: WebhookEventType;
+    data: T;
+    accountId: string;
+    timestamp: string;
+    livemode: boolean;
+}
+/**
+ * Webhook configuration
+ */
+interface WebhookConfig {
+    url: string;
+    events: WebhookEventType[];
+    status: 'active';
+    createdAt: string;
+}
+interface WebhookConfigWithSecret extends WebhookConfig {
+    /** Only returned once on initial configuration */
+    secret: string;
+}
+/**
+ * Parameters for configuring webhook
+ */
+interface ConfigureWebhookParams {
+    url: string;
+    /** Optional list of event types. If omitted, the platform subscribes to all events. */
+    events?: WebhookEventType[];
+    /** Optional description (currently ignored by the platform API). */
+    description?: string;
+}
+/**
+ * Webhook validation result
+ */
+interface WebhookValidationResult {
+    valid: boolean;
+    event?: WebhookEvent;
+    error?: string;
+}
+/**
+ * Webhook signature validation options
+ */
+interface ValidateWebhookSignatureOptions {
+    payload: string | object;
+    signature: string;
+    secret: string;
+    /**
+     * Max allowed signature age in milliseconds (default: 300_000ms).
+     * The platform signs payloads as: `${timestampMs}.${rawBody}` with signature header `t=...,v1=...`.
+     */
+    toleranceMs?: number;
+}
+
+/**
+ * Webhooks resource and utilities for Aura Payments SDK
+ */
+
+declare class Webhooks {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * Configure webhook endpoint and events
+     */
+    configure(params: ConfigureWebhookParams): Promise<WebhookConfigWithSecret>;
+    /**
+     * Get current webhook configuration
+     */
+    getConfig(): Promise<WebhookConfig>;
+    /**
+     * Delete webhook configuration
+     */
+    delete(): Promise<{
+        deleted: true;
+        message: string;
+    }>;
+    /**
+     * Validate webhook signature
+     * Use this in your webhook handler to verify authenticity
+     */
+    static validateSignature(options: ValidateWebhookSignatureOptions): WebhookValidationResult;
+    /**
+     * Parse signature header: "t=timestamp,v1=signature"
+     */
+    private static parseSignatureHeader;
+    /**
+     * Compute HMAC-SHA256 signature
+     */
+    private static computeHmacSignature;
+    /**
+     * Constant-time string comparison
+     */
+    private static secureCompare;
+}
+
+/**
+ * Aura Payments SDK Client
+ * Main entry point for interacting with the Aura Payments Platform API
+ */
+
+interface AuraClientConfig {
+    /**
+     * API key for authentication
+     */
+    apiKey: string;
+    /**
+     * Base URL of the Aura Platform API.
+     *
+     * Accepts either a bare hostname (`https://getaura.sh`) or a hostname
+     * including the `/api` path (`https://getaura.sh/api`). The SDK appends
+     * `/api` automatically if it's missing, so resource paths like `/v1/escrow`
+     * always resolve to `https://your-host/api/v1/escrow`.
+     *
+     * @default 'https://getaura.sh/api'
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Maximum number of retry attempts for failed requests
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Enable automatic idempotency key generation
+     * @default true
+     */
+    autoIdempotency?: boolean;
+}
+interface RequestOptions {
+    idempotencyKey?: string;
+    skipRetry?: boolean;
+}
+declare class AuraClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly autoIdempotency;
+    readonly escrows: Escrows;
+    readonly wallets: Wallets;
+    readonly webhooks: Webhooks;
+    readonly agents: Agents;
+    readonly policies: Policies;
+    readonly mandates: Mandates;
+    constructor(config: AuraClientConfig);
+    /**
+     * 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.
+     */
+    private static normalizeBaseUrl;
+    /**
+     * Get the API key
+     */
+    getApiKey(): string;
+    /**
+     * Get the base URL
+     */
+    getBaseUrl(): string;
+    /**
+     * Get the timeout value
+     */
+    getTimeout(): number;
+    /**
+     * Get the max retries value
+     */
+    getMaxRetries(): number;
+    /**
+     * Make an authenticated request to the API with automatic retry logic
+     */
+    protected request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Execute a single HTTP request (internal)
+     */
+    private executeRequest;
+    /**
+     * 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.
+     */
+    private normalizeResponse;
+    /**
+     * Handle HTTP error responses and throw appropriate errors
+     */
+    private handleErrorResponse;
+    /**
+     * Get the auto-idempotency setting
+     */
+    getAutoIdempotency(): boolean;
+}
+
+/**
+ * Custom error classes for Aura Payments SDK
+ */
+declare class AuraError extends Error {
+    readonly code?: string | undefined;
+    readonly statusCode?: number | undefined;
+    readonly details?: unknown;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined, details?: unknown);
+}
+declare class AuraAPIError extends AuraError {
+    constructor(message: string, statusCode: number, code?: string, details?: unknown);
+}
+declare class AuraNetworkError extends AuraError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+declare class AuraTimeoutError extends AuraError {
+    constructor(message?: string);
+}
+declare class AuraValidationError extends AuraError {
+    constructor(message: string, details?: unknown);
+}
+declare class AuraAuthenticationError extends AuraError {
+    constructor(message?: string);
+}
+declare class AuraNotFoundError extends AuraError {
+    constructor(resource: string);
+}
+declare class AuraRateLimitError extends AuraError {
+    readonly retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+/**
+ * Thrown when the testnet faucet endpoint is not available on the target
+ * deployment. The faucet (`POST /v1/wallets/:id/faucet`) is provided by the
+ * platform (AURA-010); until it ships, `wallets.requestTestnetFunds()`
+ * capability-probes and raises this typed error instead of a generic 404/501,
+ * so callers can degrade gracefully (e.g. prompt for manual funding).
+ */
+declare class AuraFaucetUnavailableError extends AuraError {
+    constructor(message?: string);
+}
+/**
+ * Type guards for error handling
+ */
+declare function isAuraError(error: unknown): error is AuraError;
+declare function isAuraFaucetUnavailableError(error: unknown): error is AuraFaucetUnavailableError;
+declare function isAuraAPIError(error: unknown): error is AuraAPIError;
+declare function isAuraNetworkError(error: unknown): error is AuraNetworkError;
+declare function isAuraTimeoutError(error: unknown): error is AuraTimeoutError;
+declare function isRetryableError(error: unknown): boolean;
+
+/**
+ * Utility functions for Aura Payments SDK
+ */
+/**
+ * Generate a unique idempotency key
+ * Format: timestamp-random
+ */
+declare function generateIdempotencyKey(): string;
+/**
+ * Calculate exponential backoff delay
+ * @param attempt - The retry attempt number (0-based)
+ * @param baseDelay - Base delay in milliseconds (default: 1000ms)
+ * @param maxDelay - Maximum delay in milliseconds (default: 30000ms)
+ * @returns Delay in milliseconds
+ */
+declare function calculateBackoff(attempt: number, baseDelay?: number, maxDelay?: number): number;
+/**
+ * Retry a function with exponential backoff
+ * @param fn - The async function to retry
+ * @param maxRetries - Maximum number of retry attempts
+ * @param shouldRetry - Optional function to determine if error is retryable
+ * @returns Promise with the function result
+ */
+declare function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries?: number, shouldRetry?: (error: unknown) => boolean): Promise<T>;
+/**
+ * Execute with timeout
+ * @param promise - The promise to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param timeoutMessage - Optional timeout error message
+ */
+declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutMessage?: string): Promise<T>;
+
+export { type Agent, type AgentBalance, type AgentPolicy, type AgentRiskTier, type AgentStatus, type AgentStatusResponse, type AgentType, Agents, type ApproveMandateParams, AuraAPIError, AuraAuthenticationError, AuraClient, type AuraClientConfig, AuraError, AuraFaucetUnavailableError, AuraNetworkError, AuraNotFoundError, AuraRateLimitError, AuraTimeoutError, AuraValidationError, type Chain, type ConfigureWebhookParams, type CreateAgentParams, type CreateAgentResponse, type CreateDisputeParams, type CreateEscrowParams, type CreateEscrowResponse, type CreatePolicyParams, type CreateWalletParams, type Dispute, type DisputeStatus, type Escrow, type EscrowListItem, type EscrowSortBy, type EscrowSplitInput, type EscrowSplitResponse, type EscrowState, Escrows, type EvaluatePolicyParams, type EvaluatePolicyResponse, type FreezeAgentParams, type FundEscrowParams, type InitialPolicyInput, type ListAgentsParams, type ListAgentsResponse, type ListEscrowsParams, type ListEscrowsResponse, type ListMandatesParams, type ListMandatesResponse, type ListPoliciesResponse, type ListWalletsParams, type ListWalletsResponse, type Mandate, type MandateDecisionMethod, type MandateIntent, type MandateIntentKind, MandateSignature, type MandateStatus, Mandates, type MerchantDestinationType, type MerchantRule, type MerchantRuleInput, type MerchantRuleType, type OwnerType, Policies, type PolicyDecision, type ReceiveAndSplitFundingRequired, type ReceiveAndSplitParams, type ReceiveAndSplitResult, type ReceiveAndSplitStage, type RefundEscrowParams, type RejectMandateParams, type ReleaseEscrowParams, type RequestTestnetFundsParams, type RequestTestnetFundsResponse, type SpendingLimit, type SpendingLimitInput, type SpendingLimitType, type SplitRole, type TokenBalance, type Transfer, type TransferParams, type UnfreezeAgentParams, type UnlockType, type UpdateAgentParams, type ValidateWebhookSignatureOptions, type Wallet, type WalletBalance, type WalletOwnerType, Wallets, type WebhookConfig, type WebhookEvent, type WebhookEventType, type WebhookValidationResult, Webhooks, calculateBackoff, generateIdempotencyKey, isAuraAPIError, isAuraError, isAuraFaucetUnavailableError, isAuraNetworkError, isAuraTimeoutError, isRetryableError, retryWithBackoff, withTimeout };