@aura-payments/sdk 2.2.0 → 2.3.0

package/README.md

@@ -14,6 +14,8 @@ pnpm add @aura-payments/sdk
 
 ## Quick Start
 
+Receive USDC and split it across recipients in one call (testnet):
+
 ```typescript
 import { AuraClient } from '@aura-payments/sdk'
 
@@ -21,25 +23,36 @@ const client = new AuraClient({
   apiKey: process.env.AURA_API_KEY!,
 })
 
-// Create a multi-party escrow
-const escrow = await client.escrows.create({
+// receiveAndSplit pays from the wallet owned by this id with type 'buyer' —
+// create the wallet with the SAME id and type (the default type is 'BUSINESS').
+const PAYER_ID = 'my-agent'
+
+// 1. Provision (create-or-get) the payer wallet — moves no money.
+const wallet = await client.wallets.create({ entityId: PAYER_ID, chain: 'ARC', type: 'buyer' })
+
+// 2. (testnet) drip USDC into the payer wallet.
+await client.wallets.requestTestnetFunds(wallet.walletId)
+
+// 3. Escrow create → fund → release, in one call.
+const result = await client.escrows.receiveAndSplit({
   orderId: 'order-123',
-  amountUsdc: '100.00',
-  splits: {
-    vendorEntityId: 'vendor-1',
-    sellerEntityId: 'seller-1',
-    platformEntityId: 'platform-1',
-    vendorPercentage: 70,
-    sellerPercentage: 20,
-    platformPercentage: 10,
-  },
-  adminSafeAddress: '0x...',
+  payerOwnerId: PAYER_ID,
+  amount: '10',
+  chain: 'ARC',
+  splits: [
+    { ownerType: 'vendor', ownerId: 'vendor-1', role: 'vendor', percentage: 80 },
+    { ownerType: 'platform', ownerId: 'platform-1', role: 'platform', percentage: 20 },
+  ],
 })
 
-console.log(`Escrow created: ${escrow.escrowId}`)
-console.log(`Vault address: ${escrow.vaultAddress}`)
+console.log(result.stage) // 'released' on the happy path
+console.log(result.escrow.escrowId)
 ```
 
+Scaffold this flow into any project with the CLI: `npx @aura-payments/cli init`
+(writes `.mcp.json`, `.env.example`, an `AGENTS.md` section, and
+`examples/aura/receive.ts`).
+
 ## Features
 
 - **Type-Safe** - Full TypeScript support with comprehensive type definitions
@@ -58,8 +71,8 @@ const client = new AuraClient({
   // Required: Your API key from the Aura dashboard
   apiKey: 'ak_live_...',
 
-  // Optional: API base URL (default: https://api.aura-payments.com)
-  baseUrl: 'https://api.aura-payments.com',
+  // Optional: API base URL (default: https://getaura.sh/api)
+  baseUrl: 'https://getaura.sh/api',
 
   // Optional: Request timeout in ms (default: 30000)
   timeout: 30000,
@@ -78,6 +91,39 @@ const client = new AuraClient({
 
 Escrows enable secure multi-party payments with configurable splits and release conditions.
 
+#### Receive and Split (one call)
+
+`receiveAndSplit` composes the full escrow loop — create → wait for deployment →
+pre-flight balance check → fund → wait for settlement → release:
+
+```typescript
+const result = await client.escrows.receiveAndSplit({
+  orderId: 'order-123',
+  payerOwnerId: 'my-agent', // wallet owned by this id with type 'buyer' pays
+  amount: '10',
+  chain: 'ARC',
+  splits: [
+    { ownerType: 'vendor', ownerId: 'vendor-1', role: 'vendor', percentage: 80 },
+    { ownerType: 'platform', ownerId: 'platform-1', role: 'platform', percentage: 20 },
+  ],
+  // Optional: autoRelease (default true), waitForDeploymentMs, waitForFundingMs,
+  // pollIntervalMs, idempotencyKey
+})
+```
+
+The result's `stage` makes partial runs explicit:
+
+| Stage | Meaning | Resume with |
+|-------|---------|-------------|
+| `created` | deployment didn't confirm in time (`deploymentPending: true`) | re-check `result.escrow.escrowId` |
+| `deployed` | payer wallet lacks funds — see `result.fundingRequired` | fund the payer wallet, then `escrows.fund` + `escrows.release` |
+| `funded` | funded but not released (`autoRelease: false` or settlement pending) | `escrows.release` |
+| `released` | funds split to recipients (happy path) | — |
+
+Resume a partial run by acting on the returned `escrow.escrowId` — do NOT
+re-call `receiveAndSplit` with the same `orderId` (it would re-create and hit a
+duplicate-orderId error).
+
 #### Create Escrow
 
 ```typescript
@@ -194,12 +240,29 @@ Manage Circle Developer-Controlled Wallets for your entities.
 
 ```typescript
 const wallet = await client.wallets.create({
-  entityId: 'entity-uuid',
+  entityId: 'entity-id', // your unique entity identifier
   chain: 'ARC', // 'ARC' | 'ARB' | 'BASE' | 'ETH' | 'MATIC' | 'SOL'
-  type: 'developer_controlled', // 'developer_controlled' | 'user_controlled'
+  type: 'buyer', // owner type: 'BUSINESS' (default) | 'buyer' | 'seller' | 'vendor' | 'platform' | ...
 })
+// Create-or-get: returns { walletId, address, ownerType, ownerId, isNew, ... }
+```
+
+Note: `receiveAndSplit` pays from the wallet owned by `payerOwnerId` with type
+`'buyer'` — create that wallet with the same `entityId` and `type: 'buyer'`.
+
+#### Request Testnet Funds
+
+Drip testnet USDC into a wallet from the platform faucet (testnet only):
+
+```typescript
+await client.wallets.requestTestnetFunds(wallet.walletId)
+// Optional params: { token: 'USDC', chain: 'ARC' }
 ```
 
+The drip lands asynchronously on-chain — poll `getBalance` until it reflects.
+Throws `AuraFaucetUnavailableError` if the deployment has no faucet enabled;
+fund the wallet address manually in that case.
+
 #### Get Wallet
 
 ```typescript

package/dist/index.d.mts

@@ -69,6 +69,13 @@ interface Escrow {
         factoryAddress: string | null;
         deployed: boolean;
         mode: string;
+        /**
+         * Definitive fund gate: true only once the deploy outcome is known —
+         * contract deployed (mode 'hybrid') or the platform completed the
+         * Circle-only fallback (mode 'circle-only'). False while a deployment
+         * is still running (mode 'pending').
+         */
+        ready?: boolean;
     };
     createdAt: string;
 }
@@ -118,6 +125,13 @@ interface CreateEscrowResponse {
         factoryAddress: string | null;
         deployed: boolean;
         mode: string;
+        /**
+         * Definitive fund gate: true only once the deploy outcome is known —
+         * contract deployed (mode 'hybrid') or the platform completed the
+         * Circle-only fallback (mode 'circle-only'). False while a deployment
+         * is still running (mode 'pending').
+         */
+        ready?: boolean;
     };
     unlock?: {
         type: 'manual' | 'timeout' | 'oracle' | 'hybrid';
@@ -519,11 +533,12 @@ declare class Escrows {
      * 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`)

package/dist/index.d.ts

@@ -69,6 +69,13 @@ interface Escrow {
         factoryAddress: string | null;
         deployed: boolean;
         mode: string;
+        /**
+         * Definitive fund gate: true only once the deploy outcome is known —
+         * contract deployed (mode 'hybrid') or the platform completed the
+         * Circle-only fallback (mode 'circle-only'). False while a deployment
+         * is still running (mode 'pending').
+         */
+        ready?: boolean;
     };
     createdAt: string;
 }
@@ -118,6 +125,13 @@ interface CreateEscrowResponse {
         factoryAddress: string | null;
         deployed: boolean;
         mode: string;
+        /**
+         * Definitive fund gate: true only once the deploy outcome is known —
+         * contract deployed (mode 'hybrid') or the platform completed the
+         * Circle-only fallback (mode 'circle-only'). False while a deployment
+         * is still running (mode 'pending').
+         */
+        ready?: boolean;
     };
     unlock?: {
         type: 'manual' | 'timeout' | 'oracle' | 'hybrid';
@@ -519,11 +533,12 @@ declare class Escrows {
      * 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`)

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 {

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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aura-payments/sdk",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "TypeScript SDK for Aura Payments Platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",