@playmos/sdk 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, A as AgentWallet, c as AgentFundResult, T as TransferResult, E as EscrowHoldInput, d as EscrowHoldResult, e as EscrowResolveResult, M as MarketplaceListInput, L as Listing, f as MarketplaceSaleResult, g as MarketplaceGetResult, h as PayInput, i as Payment, j as EnterRoundInput, k as TransferInput, V as VerifyResult } from './errors-CjL85YKR.cjs';
-export { l as AgentEconomyConfig, m as ApiError, n as AuthError, C as ConfigError, o as ContractConfig, p as Eip1193Provider, G as GasConfig, q as GasMode, I as InsufficientGasError, r as InvalidAmountError, s as ListingStatus, t as MarketplaceItem, u as MarketplaceSale, v as MissingFieldError, w as PaymentFailedError, x as PaymentStatus, y as PayoutRule, z as PlaymosError, B as PlaymosErrorCode, D as RoundStatus, F as WalletConfig, H as WalletConnectionError, J as WalletConnector, K as WebhookEventType } from './errors-CjL85YKR.cjs';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, A as AgentWallet, c as AgentFundResult, T as TransferResult, E as EscrowHoldInput, d as EscrowHoldResult, e as EscrowResolveResult, M as MarketplaceListInput, L as Listing, f as MarketplaceSaleResult, g as MarketplaceGetResult, h as PayInput, i as Payment, j as EnterRoundInput, k as TransferReconcile, l as WaitOptions, m as TransferInput, n as TransferConfirmOptions, V as VerifyResult } from './errors-BVESr920.cjs';
+export { o as AgentEconomyConfig, p as ApiError, q as AuthError, C as ConfigError, r as ContractConfig, s as Eip1193Provider, G as GasConfig, t as GasMode, I as InsufficientGasError, u as InvalidAmountError, v as ListingStatus, w as MarketplaceItem, x as MarketplaceSale, y as MissingFieldError, z as PaymentFailedError, B as PaymentStatus, D as PayoutRule, F as PlaymosError, H as PlaymosErrorCode, J as RetryOptions, K as RoundStatus, O as WalletConfig, Q as WalletConnectionError, U as WalletConnector, X as WebhookEventType } from './errors-BVESr920.cjs';
 
 /**
  * Environment resolution + the canonical address book.
@@ -99,6 +99,7 @@ declare class Playmos {
         fund: (input: {
             agentId: string;
             amount: string;
+            idempotencyKey?: string;
         }) => Promise<AgentFundResult>;
         /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
         pay: (input: {
@@ -194,18 +195,24 @@ declare class Playmos {
     /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
     enterRound(input: EnterRoundInput): Promise<Payment>;
     /**
-     * `transfers` — read-back / confirmation for a prior `transfer()` (issue #27).
-     * Poll when POST returned `status: "settling"`; reconciles against chain (incl. gasless agent path).
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
+     * `get` reconciles once against chain truth; `wait` polls it to a terminal state
+     * for you (no hand-rolled loop). Both cover the gasless agent path.
      */
     readonly transfers: {
-        get: (transferId: string) => Promise<{
-            id: string;
-            status: string;
-            txHash: string | null;
-            to: string;
-            amount: string;
-            verifiedVia: "chain" | "cache" | "degraded";
-        }>;
+        /** One-shot reconcile of a transfer against chain truth. */
+        get: (transferId: string) => Promise<TransferReconcile>;
+        /**
+         * Block until a transfer reaches a terminal state — `settled` or `failed` —
+         * instead of hand-rolling a poll loop (#47). Polls `transfers.get(id)` every
+         * `intervalMs` (default 1000) until terminal, then RESOLVES with the final
+         * reconcile. Throws a typed `ApiError` (`detail.timeout`) if neither
+         * `timeoutMs` (default 30000) nor `maxAttempts` (default 40) is reached first.
+         *
+         * A `failed` transfer is a legitimate outcome, so it RESOLVES (status
+         * "failed") — inspect `result.status`; it does not throw.
+         */
+        wait: (transferId: string, opts?: WaitOptions) => Promise<TransferReconcile>;
     };
     /**
      * `transfer` — the value-movement base primitive (Phase 1a): move USDC from one wallet to another,
@@ -218,12 +225,13 @@ declare class Playmos {
      * Retries are safe: pass the same `idempotencyKey` and a re-call NEVER broadcasts a second tx —
      * it returns the cached result (`idempotentReplay: true`).
      *
-     * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, call
-     * `playmos.transfers.get(id)` until settled/failed. BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
+     * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, either call
+     * `playmos.transfers.wait(id)`, or pass `{ confirm: true }` here to block until terminal in one
+     * call (#47). BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
      *
      * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
      */
-    transfer(input: TransferInput): Promise<TransferResult>;
+    transfer(input: TransferInput, opts?: TransferConfirmOptions): Promise<TransferResult>;
     /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
     verify(paymentId: string): Promise<VerifyResult>;
     /**
@@ -506,4 +514,4 @@ declare function isWalletSignatureAuthorization(auth: Authorization): auth is Wa
 /** Narrow to the declared-but-unimplemented x402 variant. */
 declare function isX402PayloadAuthorization(auth: Authorization): auth is X402PayloadAuthorization;
 
-export { AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, type PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferInput, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, type WalletSignatureAuthorization, WebhookEvent, type X402PayloadAuthorization, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };
+export { AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, type PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, type X402PayloadAuthorization, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, A as AgentWallet, c as AgentFundResult, T as TransferResult, E as EscrowHoldInput, d as EscrowHoldResult, e as EscrowResolveResult, M as MarketplaceListInput, L as Listing, f as MarketplaceSaleResult, g as MarketplaceGetResult, h as PayInput, i as Payment, j as EnterRoundInput, k as TransferInput, V as VerifyResult } from './errors-CjL85YKR.js';
-export { l as AgentEconomyConfig, m as ApiError, n as AuthError, C as ConfigError, o as ContractConfig, p as Eip1193Provider, G as GasConfig, q as GasMode, I as InsufficientGasError, r as InvalidAmountError, s as ListingStatus, t as MarketplaceItem, u as MarketplaceSale, v as MissingFieldError, w as PaymentFailedError, x as PaymentStatus, y as PayoutRule, z as PlaymosError, B as PlaymosErrorCode, D as RoundStatus, F as WalletConfig, H as WalletConnectionError, J as WalletConnector, K as WebhookEventType } from './errors-CjL85YKR.js';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, A as AgentWallet, c as AgentFundResult, T as TransferResult, E as EscrowHoldInput, d as EscrowHoldResult, e as EscrowResolveResult, M as MarketplaceListInput, L as Listing, f as MarketplaceSaleResult, g as MarketplaceGetResult, h as PayInput, i as Payment, j as EnterRoundInput, k as TransferReconcile, l as WaitOptions, m as TransferInput, n as TransferConfirmOptions, V as VerifyResult } from './errors-BVESr920.js';
+export { o as AgentEconomyConfig, p as ApiError, q as AuthError, C as ConfigError, r as ContractConfig, s as Eip1193Provider, G as GasConfig, t as GasMode, I as InsufficientGasError, u as InvalidAmountError, v as ListingStatus, w as MarketplaceItem, x as MarketplaceSale, y as MissingFieldError, z as PaymentFailedError, B as PaymentStatus, D as PayoutRule, F as PlaymosError, H as PlaymosErrorCode, J as RetryOptions, K as RoundStatus, O as WalletConfig, Q as WalletConnectionError, U as WalletConnector, X as WebhookEventType } from './errors-BVESr920.js';
 
 /**
  * Environment resolution + the canonical address book.
@@ -99,6 +99,7 @@ declare class Playmos {
         fund: (input: {
             agentId: string;
             amount: string;
+            idempotencyKey?: string;
         }) => Promise<AgentFundResult>;
         /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
         pay: (input: {
@@ -194,18 +195,24 @@ declare class Playmos {
     /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
     enterRound(input: EnterRoundInput): Promise<Payment>;
     /**
-     * `transfers` — read-back / confirmation for a prior `transfer()` (issue #27).
-     * Poll when POST returned `status: "settling"`; reconciles against chain (incl. gasless agent path).
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
+     * `get` reconciles once against chain truth; `wait` polls it to a terminal state
+     * for you (no hand-rolled loop). Both cover the gasless agent path.
      */
     readonly transfers: {
-        get: (transferId: string) => Promise<{
-            id: string;
-            status: string;
-            txHash: string | null;
-            to: string;
-            amount: string;
-            verifiedVia: "chain" | "cache" | "degraded";
-        }>;
+        /** One-shot reconcile of a transfer against chain truth. */
+        get: (transferId: string) => Promise<TransferReconcile>;
+        /**
+         * Block until a transfer reaches a terminal state — `settled` or `failed` —
+         * instead of hand-rolling a poll loop (#47). Polls `transfers.get(id)` every
+         * `intervalMs` (default 1000) until terminal, then RESOLVES with the final
+         * reconcile. Throws a typed `ApiError` (`detail.timeout`) if neither
+         * `timeoutMs` (default 30000) nor `maxAttempts` (default 40) is reached first.
+         *
+         * A `failed` transfer is a legitimate outcome, so it RESOLVES (status
+         * "failed") — inspect `result.status`; it does not throw.
+         */
+        wait: (transferId: string, opts?: WaitOptions) => Promise<TransferReconcile>;
     };
     /**
      * `transfer` — the value-movement base primitive (Phase 1a): move USDC from one wallet to another,
@@ -218,12 +225,13 @@ declare class Playmos {
      * Retries are safe: pass the same `idempotencyKey` and a re-call NEVER broadcasts a second tx —
      * it returns the cached result (`idempotentReplay: true`).
      *
-     * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, call
-     * `playmos.transfers.get(id)` until settled/failed. BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
+     * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, either call
+     * `playmos.transfers.wait(id)`, or pass `{ confirm: true }` here to block until terminal in one
+     * call (#47). BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
      *
      * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
      */
-    transfer(input: TransferInput): Promise<TransferResult>;
+    transfer(input: TransferInput, opts?: TransferConfirmOptions): Promise<TransferResult>;
     /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
     verify(paymentId: string): Promise<VerifyResult>;
     /**
@@ -506,4 +514,4 @@ declare function isWalletSignatureAuthorization(auth: Authorization): auth is Wa
 /** Narrow to the declared-but-unimplemented x402 variant. */
 declare function isX402PayloadAuthorization(auth: Authorization): auth is X402PayloadAuthorization;
 
-export { AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, type PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferInput, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, type WalletSignatureAuthorization, WebhookEvent, type X402PayloadAuthorization, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };
+export { AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, type PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, type X402PayloadAuthorization, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { InvalidAmountError, ConfigError, MissingFieldError, AuthError, WalletConnectionError, InsufficientGasError, PaymentFailedError, ApiError } from './chunk-B7SHFZYY.js';
+import { InvalidAmountError, ConfigError, ApiError, MissingFieldError, AuthError, WalletConnectionError, InsufficientGasError, PaymentFailedError } from './chunk-B7SHFZYY.js';
 export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, PaymentFailedError, PlaymosError, WalletConnectionError } from './chunk-B7SHFZYY.js';
 import { encodeFunctionData, numberToHex, keccak256, toBytes } from 'viem';
 
@@ -163,8 +163,37 @@ function validateMetadata(metadata) {
 }
 
 // src/http.ts
-function createHttpClient(baseUrl, apiKey) {
+function resolveRetry(retry) {
+  const off = { maxRetries: 0, baseDelayMs: 500, maxDelayMs: 2e4 };
+  if (retry === false) return off;
+  const r = retry === true || retry === void 0 ? {} : retry;
+  return {
+    maxRetries: r.maxRetries ?? 2,
+    baseDelayMs: r.baseDelayMs ?? 500,
+    maxDelayMs: r.maxDelayMs ?? 2e4
+  };
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function backoffMs(res, attempt, cfg) {
+  const header = res.headers.get("retry-after");
+  if (header) {
+    const secs = Number(header);
+    let ms;
+    if (Number.isFinite(secs)) {
+      ms = secs * 1e3;
+    } else {
+      const at = Date.parse(header);
+      ms = Number.isNaN(at) ? NaN : at - Date.now();
+    }
+    if (Number.isFinite(ms) && ms >= 0) return Math.min(ms, cfg.maxDelayMs);
+  }
+  const expo = cfg.baseDelayMs * 2 ** attempt;
+  const jitter = Math.random() * cfg.baseDelayMs;
+  return Math.min(expo + jitter, cfg.maxDelayMs);
+}
+function createHttpClient(baseUrl, apiKey, retry) {
   const base = baseUrl.replace(/\/+$/, "");
+  const cfg = resolveRetry(retry);
   async function send(url, init) {
     try {
       return await fetch(url, init);
@@ -176,6 +205,14 @@ function createHttpClient(baseUrl, apiKey) {
       );
     }
   }
+  async function sendWithRetry(url, init) {
+    let res = await send(url, init);
+    for (let attempt = 0; res.status === 429 && attempt < cfg.maxRetries; attempt++) {
+      await sleep(backoffMs(res, attempt, cfg));
+      res = await send(url, init);
+    }
+    return res;
+  }
   async function handle(res) {
     let text;
     try {
@@ -208,11 +245,11 @@ function createHttpClient(baseUrl, apiKey) {
         authorization: `Bearer ${apiKey}`
       };
       if (opts?.idempotencyKey) headers["idempotency-key"] = opts.idempotencyKey;
-      const res = await send(`${base}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
+      const res = await sendWithRetry(`${base}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
       return handle(res);
     },
     async get(path) {
-      const res = await send(`${base}${path}`, {
+      const res = await sendWithRetry(`${base}${path}`, {
         method: "GET",
         headers: { authorization: `Bearer ${apiKey}` }
       });
@@ -638,7 +675,12 @@ var Playmos = class {
       fund: (input) => {
         requireField(input?.agentId, "agentId");
         validateAmount(input.amount);
-        return this.http.post(`/agents/wallets/${encodeURIComponent(input.agentId)}/fund`, { amount: input.amount });
+        const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+        return this.http.post(
+          `/agents/wallets/${encodeURIComponent(input.agentId)}/fund`,
+          { amount: input.amount, idempotencyKey },
+          { idempotencyKey }
+        );
       },
       /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
       pay: (input) => {
@@ -667,7 +709,7 @@ var Playmos = class {
             { feeBps: input.feeBps }
           );
         }
-        const feeSink = feeBps > 0 ? requireAddressField(input.feeSink, "feeSink") : input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
+        const feeSink = input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
         const resolver = input.resolver === void 0 ? void 0 : requireAddressField(input.resolver, "resolver");
         const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
         const feeMicro = amountMicro * BigInt(feeBps) / 10000n;
@@ -779,19 +821,51 @@ var Playmos = class {
       }
     };
     /**
-     * `transfers` — read-back / confirmation for a prior `transfer()` (issue #27).
-     * Poll when POST returned `status: "settling"`; reconciles against chain (incl. gasless agent path).
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
+     * `get` reconciles once against chain truth; `wait` polls it to a terminal state
+     * for you (no hand-rolled loop). Both cover the gasless agent path.
      */
     this.transfers = {
+      /** One-shot reconcile of a transfer against chain truth. */
       get: async (transferId) => {
         requireField(transferId, "transferId");
-        const res = await this.http.get(`/transfers/${encodeURIComponent(transferId)}`);
+        const res = await this.http.get(
+          `/transfers/${encodeURIComponent(transferId)}`
+        );
         return res.transfer;
+      },
+      /**
+       * Block until a transfer reaches a terminal state — `settled` or `failed` —
+       * instead of hand-rolling a poll loop (#47). Polls `transfers.get(id)` every
+       * `intervalMs` (default 1000) until terminal, then RESOLVES with the final
+       * reconcile. Throws a typed `ApiError` (`detail.timeout`) if neither
+       * `timeoutMs` (default 30000) nor `maxAttempts` (default 40) is reached first.
+       *
+       * A `failed` transfer is a legitimate outcome, so it RESOLVES (status
+       * "failed") — inspect `result.status`; it does not throw.
+       */
+      wait: async (transferId, opts) => {
+        requireField(transferId, "transferId");
+        const intervalMs = opts?.intervalMs ?? 1e3;
+        const timeoutMs = opts?.timeoutMs ?? 3e4;
+        const maxAttempts = opts?.maxAttempts ?? 40;
+        const deadline = Date.now() + timeoutMs;
+        let last;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+          last = await this.transfers.get(transferId);
+          if (last.status === "settled" || last.status === "failed") return last;
+          if (Date.now() + intervalMs > deadline) break;
+          await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        throw new ApiError(
+          `Timed out waiting for transfer ${transferId} to settle (last status: ${last?.status ?? "unknown"}). It may still settle \u2014 re-check with playmos.transfers.get("${transferId}").`,
+          { transferId, timeout: true, lastStatus: last?.status ?? "unknown" }
+        );
       }
     };
     this.config = config;
     this.env = resolveEnv(config.apiKey, config.network, config.apiBaseUrl);
-    this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey);
+    this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
   }
   /** Connect the player's wallet and return their address. */
   async connect() {
@@ -941,12 +1015,13 @@ var Playmos = class {
    * Retries are safe: pass the same `idempotencyKey` and a re-call NEVER broadcasts a second tx —
    * it returns the cached result (`idempotentReplay: true`).
    *
-   * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, call
-   * `playmos.transfers.get(id)` until settled/failed. BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
+   * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, either call
+   * `playmos.transfers.wait(id)`, or pass `{ confirm: true }` here to block until terminal in one
+   * call (#47). BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
    *
    * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
    */
-  async transfer(input) {
+  async transfer(input, opts) {
     const amountMicro = validateAmount(input.amount);
     const from = input.from === void 0 ? void 0 : partyRef(input.from, "from");
     const to = partyRef(input.to, "to");
@@ -957,12 +1032,7 @@ var Playmos = class {
         { feeBps: input.feeBps }
       );
     }
-    let feeSink;
-    if (feeBps > 0) {
-      feeSink = requireAddressField(input.feeSink, "feeSink");
-    } else if (input.feeSink !== void 0) {
-      feeSink = requireAddressField(input.feeSink, "feeSink");
-    }
+    const feeSink = input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
     const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
     const res = await this.http.post(
       "/transfers",
@@ -971,7 +1041,7 @@ var Playmos = class {
     );
     const t = res.transfer;
     const feeMicro = amountMicro * BigInt(feeBps) / 10000n;
-    return {
+    const out = {
       id: t.id,
       status: t.status,
       txHash: t.txHash,
@@ -987,6 +1057,12 @@ var Playmos = class {
       memo: t.memo ?? input.memo ?? null,
       idempotentReplay: Boolean(t.idempotentReplay)
     };
+    if (opts?.confirm && out.status === "settling") {
+      const final = await this.transfers.wait(out.id, opts);
+      out.status = final.status;
+      out.txHash = final.txHash ?? out.txHash;
+    }
+    return out;
   }
   /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
   async verify(paymentId) {