@playmos/sdk 0.3.10 → 0.3.11

package/dist/index.cjs

@@ -267,10 +267,10 @@ function validateMetadata(metadata) {
 
 // src/payout.ts
 var PayoutError = class extends Error {
-  constructor(message) {
+  constructor(message, code = "payout_invalid") {
     super(message);
-    this.code = "payout_invalid";
     this.name = "PayoutError";
+    this.code = code;
   }
 };
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
@@ -315,7 +315,8 @@ function computePayout(pool, ranking, rule) {
     }
     if (splits.length > wallets.length) {
       throw new PayoutError(
-        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
+        `ranking_too_short: a top-n rule cannot be settled from a ranking shorter than splitsBps.length (need ${splits.length}, got ${wallets.length}) \u2014 open with winner-take-all, or settle with explicit winners[{wallet,amount}]`,
+        "ranking_too_short"
       );
     }
     let sumBps = 0;
@@ -628,7 +629,7 @@ function resolveRawProvider(wallet) {
   }
   if (injected) return injected;
   throw new WalletConnectionError(
-    "base-account connector needs a provider. In the Base App it is injected automatically; elsewhere, create one with @base-org/account and pass it as wallet.provider."
+    'base-account connector needs a provider \u2014 this is not a built-in Base Account/passkey flow in @playmos/sdk. In the Base App a provider is often injected; elsewhere install @base-org/account, construct a provider, and pass it as wallet.provider (or use connector: "injected" in a wallet browser).'
   );
 }
 function resolveProvider(wallet, opts) {
@@ -2037,8 +2038,16 @@ var Playmos = class {
     /**
      * Offline mock payments for this client instance — so `verify(id)` after
      * `mock: true` pay/enterRound does not hit the live API (#204).
+     * Keyed by payment id for verify.
      */
     this.mockPayments = /* @__PURE__ */ new Map();
+    /**
+     * sdk#513 / residual B1–B2 — held idempotencyKey offline (live contract rehearsal).
+     * Keyed like service: `${gameId}:${key}` (IAP without gameId uses empty gameId).
+     * Stores terms so same key + different money throws (live IdempotencyConflict), not silent replay.
+     * Auto-minted keys still unique per call (not stored for cross-call replay).
+     */
+    this.mockByIdempotencyKey = /* @__PURE__ */ new Map();
     /**
      * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
      * `get` reconciles once against chain truth; `wait` polls it to a terminal state
@@ -2223,18 +2232,62 @@ var Playmos = class {
       }
     };
   }
-  rememberMock(payment) {
-    if (payment.mock) this.mockPayments.set(payment.id, payment);
+  mockIdemScopeKey(gameId, heldKey) {
+    return `${gameId ?? ""}:${heldKey}`;
+  }
+  rememberMock(payment, held) {
+    if (payment.mock) {
+      this.mockPayments.set(payment.id, payment);
+      if (held) {
+        this.mockByIdempotencyKey.set(this.mockIdemScopeKey(held.terms.gameId, held.key), {
+          payment,
+          terms: held.terms
+        });
+      }
+    }
     return payment;
   }
+  /** Live-shaped conflict when held mock key is reused with different money terms (sdk#513 residual B1). */
+  mockIdemReplayOrThrow(heldKey, terms) {
+    const prior = this.mockByIdempotencyKey.get(this.mockIdemScopeKey(terms.gameId, heldKey));
+    if (!prior) return null;
+    const t = prior.terms;
+    const same = t.kind === terms.kind && t.amount === terms.amount && t.gameId === terms.gameId && t.playerId === terms.playerId && t.roundId === terms.roundId && t.identity === terms.identity && t.sku === terms.sku;
+    if (!same) {
+      throw new ApiError(
+        `idempotencyKey was already used for a payment with DIFFERENT terms (kind/amount/gameId/playerId/roundId/identity/sku); use a fresh key (mock:true mirrors live conflict \u2014 sdk#513).`,
+        {
+          code: "idempotency_conflict",
+          idempotencyKey: heldKey,
+          priorKind: t.kind,
+          priorAmount: t.amount
+        }
+      );
+    }
+    return prior.payment;
+  }
   /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
   async pay(input) {
     const amountMicro = validateAmount(input.amount);
     requireField(input.sku, "sku");
     requireField(input.playerId, "playerId");
     const metadata = validateMetadata(input.metadata);
-    const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+    const heldIdem = typeof input.idempotencyKey === "string" && input.idempotencyKey.trim() ? input.idempotencyKey.trim() : void 0;
+    const idempotencyKey = heldIdem ?? prefixedId("idem");
     if (this.config.mock) {
+      const terms = {
+        kind: "iap",
+        amount: formatMicroToUsd(amountMicro),
+        gameId: input.gameId ?? "",
+        playerId: input.playerId,
+        roundId: "",
+        identity: "",
+        sku: input.sku.trim()
+      };
+      if (heldIdem) {
+        const replay = this.mockIdemReplayOrThrow(heldIdem, terms);
+        if (replay) return replay;
+      }
       return this.rememberMock(
         mockIapPayment({
           amountMicro,
@@ -2243,7 +2296,8 @@ var Playmos = class {
           playerId: input.playerId,
           chain: this.env.network,
           metadata
-        })
+        }),
+        heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
     if (this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
@@ -2265,7 +2319,13 @@ var Playmos = class {
       );
       let payment = this.mapServerPayment(res.payment, "iap", amountMicro);
       if (payment.status === "pending" || payment.status === "created") {
-        payment = await this.waitForServerSettle(payment.id, "iap", amountMicro);
+        payment = await this.waitForServerSettle(
+          payment.id,
+          "iap",
+          amountMicro,
+          input.settleTimeoutMs ?? 6e4,
+          input.signal
+        );
       }
       return payment;
     }
@@ -2310,8 +2370,22 @@ var Playmos = class {
     requireField(input.roundId, "roundId");
     requireField(input.playerId, "playerId");
     const metadata = validateMetadata(input.metadata);
-    const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+    const heldIdem = typeof input.idempotencyKey === "string" && input.idempotencyKey.trim() ? input.idempotencyKey.trim() : void 0;
+    const idempotencyKey = heldIdem ?? prefixedId("idem");
     if (this.config.mock) {
+      const terms = {
+        kind: "entry",
+        amount: formatMicroToUsd(amountMicro),
+        gameId: input.gameId,
+        playerId: input.playerId,
+        roundId: input.roundId,
+        identity: typeof input.identity === "string" ? input.identity.trim() : "",
+        sku: ""
+      };
+      if (heldIdem) {
+        const replay = this.mockIdemReplayOrThrow(heldIdem, terms);
+        if (replay) return replay;
+      }
       this.mockAccumulateEntry(input.roundId, amountMicro);
       return this.rememberMock(
         mockEntryPayment({
@@ -2327,7 +2401,8 @@ var Playmos = class {
           // B2 pins — must survive mock path for hub hasEntered parity (#204).
           roundKey: input.roundKey,
           identity: input.identity
-        })
+        }),
+        heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
     const serverSettleNoWallet = this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
@@ -2360,7 +2435,13 @@ var Playmos = class {
       );
       let payment2 = this.mapServerPayment(res.payment, "entry", amountMicro);
       if (payment2.status === "pending" || payment2.status === "created") {
-        payment2 = await this.waitForServerSettle(payment2.id, "entry", amountMicro);
+        payment2 = await this.waitForServerSettle(
+          payment2.id,
+          "entry",
+          amountMicro,
+          input.settleTimeoutMs ?? 6e4,
+          input.signal
+        );
       }
       if (input.identity) payment2.identity = input.identity;
       const pool = res.clientParams?.contractAddress ?? this.config.contracts?.prizePool;
@@ -2543,10 +2624,16 @@ var Playmos = class {
    *   until chain verify catches PaymentSettled (RPC lag) — poll so pay() matches
    *   the documented "confirmed" sandbox promise (TTFSC-T0 / cold-run).
    */
-  async waitForServerSettle(paymentId, kind, amountMicro, timeoutMs = 6e4) {
+  async waitForServerSettle(paymentId, kind, amountMicro, timeoutMs = 6e4, signal) {
     const start = Date.now();
     let delayMs = 400;
     while (Date.now() - start < timeoutMs) {
+      if (signal?.aborted) {
+        throw new ApiError(
+          `Aborted waiting for server-settle of ${paymentId}. Re-check with playmos.verify("${paymentId}").`,
+          { paymentId, aborted: true, asyncSettle: true }
+        );
+      }
       const raw = await this.http.get(
         `/payments/${encodeURIComponent(paymentId)}`
       );
@@ -2561,12 +2648,46 @@ var Playmos = class {
       { paymentId, timeout: true, asyncSettle: true }
     );
   }
+  /**
+   * sdk#509 — recover a payment after a lost response by the idempotency key you held.
+   * Requires secret sk_test_ (same as list). Returns null if not found.
+   */
+  async findPaymentByIdempotencyKey(idempotencyKey, opts) {
+    requireField(idempotencyKey, "idempotencyKey");
+    if (this.config.mock) {
+      return null;
+    }
+    const q = new URLSearchParams({ idempotencyKey });
+    if (opts?.gameId) q.set("gameId", opts.gameId);
+    try {
+      const res = await this.http.get(
+        `/payments?${q.toString()}`
+      );
+      const row = res.data?.[0];
+      if (!row || typeof row.id !== "string") return null;
+      const kind = row.kind === "entry" ? "entry" : "iap";
+      const amountMicro = validateAmount(String(row.amount ?? "0.01"));
+      return this.mapServerPayment(
+        row,
+        kind,
+        amountMicro
+      );
+    } catch (e) {
+      if (e instanceof ApiError && (e.detail?.status === 404 || e.detail?.code === "not_found" || /not found/i.test(e.message))) {
+        return null;
+      }
+      throw e;
+    }
+  }
   /**
    * Map a server-settled payment (from the `settle: "server"` response) into the
    * SDK's `Payment` shape. The service already signed + confirmed on-chain, so we
-   * pass its authoritative `status`/`txHash`/amounts straight through and, for an
-   * entry, derive the 60/30/10 USD `split` locally (exactly as the mock + the
-   * contract compute it) from the parsed amount.
+   * pass its authoritative `status`/`txHash`/amounts straight through.
+   *
+   * For entry, `Payment.split` is a **first-party 60/30/10 projection** from the
+   * request amount using SDK BPS constants (same integer math as mock) — not a
+   * chain read of pool constructor bps or post-lock payable pot (sdk#514 residual N1).
+   * Prefer `chainAmount` / on-chain `getRound` for money truth.
    */
   mapServerPayment(p, kind, amountMicro) {
     const payment = {

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, c as RoundCancelInput, C as CancelRoundResult, d as RoundGetResult, A as ActiveSeriesRound, e as PrizeBalance, f as WithdrawResult, g as AgentWallet, h as AgentFundResult, T as TransferResult, E as EscrowHoldInput, i as EscrowHoldResult, j as EscrowResolveResult, M as MarketplaceListInput, L as Listing, k as MarketplaceSaleResult, l as MarketplaceGetResult, m as PayInput, n as Payment, o as EnterRoundInput, p as TransferReconcile, q as WaitOptions, r as TransferInput, s as TransferConfirmOptions, V as VerifyResult, t as PayoutRule } from './errors-Chizbb96.cjs';
-export { u as ActiveForSeriesResult, v as AgentEconomyConfig, w as AlreadyEnteredError, x as ApiError, y as AuthError, z as ConfigError, B as ContractConfig, D as Eip1193Provider, G as GasConfig, F as GasMode, I as InsufficientGasError, H as InvalidAmountError, J as ListingStatus, K as MarketplaceItem, O as MarketplaceSale, Q as MissingFieldError, U as NothingToWithdrawError, X as PaymentFailedError, Y as PaymentStatus, Z as PlaymosError, _ as PlaymosErrorCode, $ as RetryOptions, a0 as RoundGetVia, a1 as RoundStatus, a2 as WalletConfig, a3 as WalletConnectionError, a4 as WalletConnector, a5 as WalletTimeoutError, a6 as WebhookEventType } from './errors-Chizbb96.cjs';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, C as CancelRoundResult, d as RoundGetResult, A as ActiveSeriesRound, e as PrizeBalance, f as WithdrawResult, g as AgentWallet, h as AgentFundResult, T as TransferResult, E as EscrowHoldInput, i as EscrowHoldResult, j as EscrowResolveResult, M as MarketplaceListInput, L as Listing, k as MarketplaceSaleResult, l as MarketplaceGetResult, m as PayInput, n as Payment, o as EnterRoundInput, p as TransferReconcile, q as WaitOptions, r as TransferInput, s as TransferConfirmOptions, V as VerifyResult, t as PayoutRule } from './errors-Dpeesyop.cjs';
+export { u as ActiveForSeriesResult, v as AgentEconomyConfig, w as AlreadyEnteredError, x as ApiError, y as AuthError, z as ConfigError, B as ContractConfig, D as Eip1193Provider, G as GasConfig, F as GasMode, I as InsufficientGasError, H as InvalidAmountError, J as ListingStatus, K as MarketplaceItem, O as MarketplaceSale, Q as MissingFieldError, U as NothingToWithdrawError, X as PaymentFailedError, Y as PaymentStatus, Z as PlaymosError, _ as PlaymosErrorCode, $ as RetryOptions, a0 as RoundGetVia, a1 as RoundStatus, a2 as WalletConfig, a3 as WalletConnectionError, a4 as WalletConnector, a5 as WalletTimeoutError, a6 as WebhookEventType } from './errors-Dpeesyop.cjs';
 
 /**
  * Environment resolution + the canonical address book.
@@ -655,8 +655,16 @@ declare class Playmos {
     /**
      * Offline mock payments for this client instance — so `verify(id)` after
      * `mock: true` pay/enterRound does not hit the live API (#204).
+     * Keyed by payment id for verify.
      */
     private readonly mockPayments;
+    /**
+     * sdk#513 / residual B1–B2 — held idempotencyKey offline (live contract rehearsal).
+     * Keyed like service: `${gameId}:${key}` (IAP without gameId uses empty gameId).
+     * Stores terms so same key + different money throws (live IdempotencyConflict), not silent replay.
+     * Auto-minted keys still unique per call (not stored for cross-call replay).
+     */
+    private readonly mockByIdempotencyKey;
     constructor(config: PlaymosConfig);
     /**
      * Wallet timeout policy (#462 / PR #463 residual).
@@ -695,7 +703,10 @@ declare class Playmos {
             identity?: string;
         }>;
     };
+    private mockIdemScopeKey;
     private rememberMock;
+    /** Live-shaped conflict when held mock key is reused with different money terms (sdk#513 residual B1). */
+    private mockIdemReplayOrThrow;
     /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
     pay(input: PayInput): Promise<Payment>;
     /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
@@ -759,12 +770,22 @@ declare class Playmos {
      *   the documented "confirmed" sandbox promise (TTFSC-T0 / cold-run).
      */
     private waitForServerSettle;
+    /**
+     * sdk#509 — recover a payment after a lost response by the idempotency key you held.
+     * Requires secret sk_test_ (same as list). Returns null if not found.
+     */
+    findPaymentByIdempotencyKey(idempotencyKey: string, opts?: {
+        gameId?: string;
+    }): Promise<Payment | null>;
     /**
      * Map a server-settled payment (from the `settle: "server"` response) into the
      * SDK's `Payment` shape. The service already signed + confirmed on-chain, so we
-     * pass its authoritative `status`/`txHash`/amounts straight through and, for an
-     * entry, derive the 60/30/10 USD `split` locally (exactly as the mock + the
-     * contract compute it) from the parsed amount.
+     * pass its authoritative `status`/`txHash`/amounts straight through.
+     *
+     * For entry, `Payment.split` is a **first-party 60/30/10 projection** from the
+     * request amount using SDK BPS constants (same integer math as mock) — not a
+     * chain read of pool constructor bps or post-lock payable pot (sdk#514 residual N1).
+     * Prefer `chainAmount` / on-chain `getRound` for money truth.
      */
     private mapServerPayment;
     /** Prefer the service's authoritative micro-USDC amount; fall back to the
@@ -838,8 +859,8 @@ declare function previewPoolSplit(amount: string): {
  */
 
 declare class PayoutError extends Error {
-    code: "payout_invalid";
-    constructor(message: string);
+    code: string;
+    constructor(message: string, code?: string);
 }
 /**
  * Apply the studio's payout rule to a payable pool and ranking (best-first).

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, c as RoundCancelInput, C as CancelRoundResult, d as RoundGetResult, A as ActiveSeriesRound, e as PrizeBalance, f as WithdrawResult, g as AgentWallet, h as AgentFundResult, T as TransferResult, E as EscrowHoldInput, i as EscrowHoldResult, j as EscrowResolveResult, M as MarketplaceListInput, L as Listing, k as MarketplaceSaleResult, l as MarketplaceGetResult, m as PayInput, n as Payment, o as EnterRoundInput, p as TransferReconcile, q as WaitOptions, r as TransferInput, s as TransferConfirmOptions, V as VerifyResult, t as PayoutRule } from './errors-Chizbb96.js';
-export { u as ActiveForSeriesResult, v as AgentEconomyConfig, w as AlreadyEnteredError, x as ApiError, y as AuthError, z as ConfigError, B as ContractConfig, D as Eip1193Provider, G as GasConfig, F as GasMode, I as InsufficientGasError, H as InvalidAmountError, J as ListingStatus, K as MarketplaceItem, O as MarketplaceSale, Q as MissingFieldError, U as NothingToWithdrawError, X as PaymentFailedError, Y as PaymentStatus, Z as PlaymosError, _ as PlaymosErrorCode, $ as RetryOptions, a0 as RoundGetVia, a1 as RoundStatus, a2 as WalletConfig, a3 as WalletConnectionError, a4 as WalletConnector, a5 as WalletTimeoutError, a6 as WebhookEventType } from './errors-Chizbb96.js';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, C as CancelRoundResult, d as RoundGetResult, A as ActiveSeriesRound, e as PrizeBalance, f as WithdrawResult, g as AgentWallet, h as AgentFundResult, T as TransferResult, E as EscrowHoldInput, i as EscrowHoldResult, j as EscrowResolveResult, M as MarketplaceListInput, L as Listing, k as MarketplaceSaleResult, l as MarketplaceGetResult, m as PayInput, n as Payment, o as EnterRoundInput, p as TransferReconcile, q as WaitOptions, r as TransferInput, s as TransferConfirmOptions, V as VerifyResult, t as PayoutRule } from './errors-Dpeesyop.js';
+export { u as ActiveForSeriesResult, v as AgentEconomyConfig, w as AlreadyEnteredError, x as ApiError, y as AuthError, z as ConfigError, B as ContractConfig, D as Eip1193Provider, G as GasConfig, F as GasMode, I as InsufficientGasError, H as InvalidAmountError, J as ListingStatus, K as MarketplaceItem, O as MarketplaceSale, Q as MissingFieldError, U as NothingToWithdrawError, X as PaymentFailedError, Y as PaymentStatus, Z as PlaymosError, _ as PlaymosErrorCode, $ as RetryOptions, a0 as RoundGetVia, a1 as RoundStatus, a2 as WalletConfig, a3 as WalletConnectionError, a4 as WalletConnector, a5 as WalletTimeoutError, a6 as WebhookEventType } from './errors-Dpeesyop.js';
 
 /**
  * Environment resolution + the canonical address book.
@@ -655,8 +655,16 @@ declare class Playmos {
     /**
      * Offline mock payments for this client instance — so `verify(id)` after
      * `mock: true` pay/enterRound does not hit the live API (#204).
+     * Keyed by payment id for verify.
      */
     private readonly mockPayments;
+    /**
+     * sdk#513 / residual B1–B2 — held idempotencyKey offline (live contract rehearsal).
+     * Keyed like service: `${gameId}:${key}` (IAP without gameId uses empty gameId).
+     * Stores terms so same key + different money throws (live IdempotencyConflict), not silent replay.
+     * Auto-minted keys still unique per call (not stored for cross-call replay).
+     */
+    private readonly mockByIdempotencyKey;
     constructor(config: PlaymosConfig);
     /**
      * Wallet timeout policy (#462 / PR #463 residual).
@@ -695,7 +703,10 @@ declare class Playmos {
             identity?: string;
         }>;
     };
+    private mockIdemScopeKey;
     private rememberMock;
+    /** Live-shaped conflict when held mock key is reused with different money terms (sdk#513 residual B1). */
+    private mockIdemReplayOrThrow;
     /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
     pay(input: PayInput): Promise<Payment>;
     /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
@@ -759,12 +770,22 @@ declare class Playmos {
      *   the documented "confirmed" sandbox promise (TTFSC-T0 / cold-run).
      */
     private waitForServerSettle;
+    /**
+     * sdk#509 — recover a payment after a lost response by the idempotency key you held.
+     * Requires secret sk_test_ (same as list). Returns null if not found.
+     */
+    findPaymentByIdempotencyKey(idempotencyKey: string, opts?: {
+        gameId?: string;
+    }): Promise<Payment | null>;
     /**
      * Map a server-settled payment (from the `settle: "server"` response) into the
      * SDK's `Payment` shape. The service already signed + confirmed on-chain, so we
-     * pass its authoritative `status`/`txHash`/amounts straight through and, for an
-     * entry, derive the 60/30/10 USD `split` locally (exactly as the mock + the
-     * contract compute it) from the parsed amount.
+     * pass its authoritative `status`/`txHash`/amounts straight through.
+     *
+     * For entry, `Payment.split` is a **first-party 60/30/10 projection** from the
+     * request amount using SDK BPS constants (same integer math as mock) — not a
+     * chain read of pool constructor bps or post-lock payable pot (sdk#514 residual N1).
+     * Prefer `chainAmount` / on-chain `getRound` for money truth.
      */
     private mapServerPayment;
     /** Prefer the service's authoritative micro-USDC amount; fall back to the
@@ -838,8 +859,8 @@ declare function previewPoolSplit(amount: string): {
  */
 
 declare class PayoutError extends Error {
-    code: "payout_invalid";
-    constructor(message: string);
+    code: string;
+    constructor(message: string, code?: string);
 }
 /**
  * Apply the studio's payout rule to a payable pool and ranking (best-first).