@playmos/sdk 0.2.0 → 0.3.1

package/dist/index.cjs

@@ -2,6 +2,8 @@
 
 var viem = require('viem');
 
+// src/client.ts
+
 // src/errors.ts
 var PlaymosError = class extends Error {
   constructor(code, message, detail) {
@@ -60,6 +62,15 @@ var ConfigError = class extends PlaymosError {
     super("config", message, detail);
   }
 };
+var NothingToWithdrawError = class extends PlaymosError {
+  constructor(detail) {
+    super(
+      "nothing_to_withdraw",
+      "Nothing to withdraw \u2014 this wallet has no credited prize balance on this PrizePool (round not settled for them, or already claimed).",
+      detail
+    );
+  }
+};
 
 // src/config.ts
 var CHAIN_ID = {
@@ -222,8 +233,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);
@@ -235,6 +275,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 {
@@ -267,11 +315,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}` }
       });
@@ -425,6 +473,13 @@ var prizePoolAbi = [
     ],
     outputs: [{ type: "bool" }]
   },
+  {
+    type: "function",
+    name: "withdrawable",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ type: "uint256" }]
+  },
   {
     type: "function",
     name: "withdraw",
@@ -512,6 +567,14 @@ function buildEntryCalls(args) {
     { to: args.prizePool, data: enterData }
   ];
 }
+function buildWithdrawCall(prizePool) {
+  const data = viem.encodeFunctionData({
+    abi: prizePoolAbi,
+    functionName: "withdraw",
+    args: []
+  });
+  return { to: prizePool, data };
+}
 
 // src/mock.ts
 var MOCK_TX = "0x000000000000000000000000000000000000000000000000000000000000mock";
@@ -556,6 +619,9 @@ function mockEntryPayment(args) {
     },
     gameId: args.gameId,
     roundId: args.roundId,
+    roundKey: args.roundId,
+    // Deterministic mock pool address so claim-flow unit tests can assert shape (#41).
+    prizePoolAddress: "0x0000000000000000000000000000000000000001",
     playerId: args.playerId,
     txHash: MOCK_TX,
     chain: args.chain,
@@ -668,6 +734,112 @@ var Playmos = class {
           `/rounds/${encodeURIComponent(input.roundId)}`
         );
         return round;
+      },
+      /**
+       * Read a wallet's **claimable** prize balance for a round (issue #41).
+       * Prefers the service chain read (`GET /v1/rounds/:id/prize?wallet=`); falls
+       * back to a direct eth_call when `prizePoolAddress` is supplied and no wallet
+       * connector is needed for the read path… actually uses service first, then
+       * on-chain via the player's provider if the service is unavailable.
+       */
+      prize: async (input) => {
+        requireField(input?.roundId, "roundId");
+        const wallet = requireAddressField(input?.wallet, "wallet");
+        try {
+          const res = await this.http.get(
+            `/rounds/${encodeURIComponent(input.roundId)}/prize?wallet=${encodeURIComponent(wallet)}`
+          );
+          return res.prize;
+        } catch (e) {
+          if (!input.prizePoolAddress && !(e instanceof ApiError)) throw e;
+          if (!input.prizePoolAddress) throw e;
+        }
+        const prizePoolAddress = requireAddressField(input.prizePoolAddress, "prizePoolAddress");
+        const claimableMicro = await this.readWithdrawable(prizePoolAddress, wallet);
+        return {
+          roundId: input.roundId,
+          prizePoolAddress,
+          wallet,
+          claimable: formatMicroToUsd(claimableMicro),
+          claimableMicro: claimableMicro.toString()
+        };
+      },
+      /**
+       * Winner **claim** — call PrizePool.withdraw() from the player's wallet (issue #41).
+       * Pull-payment: credits from settle live in `withdrawable[msg.sender]`. No approve needed.
+       * Pass either `prizePoolAddress` (from enterRound / rounds.get) or `roundId` (service resolves).
+       */
+      withdraw: async (input) => {
+        if (this.config.mock) {
+          return {
+            prizePoolAddress: input.prizePoolAddress ?? "0x0000000000000000000000000000000000000001",
+            amount: "0.00",
+            amountMicro: "0",
+            txHash: "0x000000000000000000000000000000000000000000000000000000000000mock",
+            status: "confirmed"
+          };
+        }
+        let prizePool = input.prizePoolAddress ? requireAddressField(input.prizePoolAddress, "prizePoolAddress") : void 0;
+        if (!prizePool) {
+          requireField(input?.roundId, "roundId");
+          const round = await this.rounds.get({ roundId: input.roundId });
+          if (!round.prizePoolAddress) {
+            throw new ConfigError(
+              "rounds.get did not return prizePoolAddress \u2014 pass prizePoolAddress from enterRound or configure contracts.prizePool"
+            );
+          }
+          prizePool = round.prizePoolAddress;
+        }
+        const provider = resolveProvider(this.config.wallet);
+        if (this.config.gas?.mode === "player") {
+          const from0 = await getAccount(provider);
+          await assertEnoughGas(provider, from0);
+        }
+        const from = await getAccount(provider);
+        let amountMicro = 0n;
+        if (input.checkBalance !== false) {
+          amountMicro = await this.readWithdrawable(prizePool, from);
+          if (amountMicro === 0n) {
+            throw new NothingToWithdrawError({ prizePoolAddress: prizePool, wallet: from });
+          }
+        }
+        const call = buildWithdrawCall(prizePool);
+        const paymasterUrl = this.config.gas?.mode === "sponsored" ? this.config.gas.paymasterUrl : void 0;
+        let txHash;
+        let status = "pending";
+        try {
+          const { id: callsId } = await sendCalls(
+            provider,
+            from,
+            this.env.chainId,
+            [call],
+            paymasterUrl
+          );
+          const waited = await waitForCalls(provider, callsId);
+          txHash = waited.txHash;
+          status = waited.status === "CONFIRMED" ? "confirmed" : waited.status === "FAILED" ? "failed" : "pending";
+        } catch (e) {
+          const msg = e?.message ?? String(e);
+          if (/NothingToWithdraw|nothing to withdraw/i.test(msg)) {
+            throw new NothingToWithdrawError({ prizePoolAddress: prizePool, wallet: from, cause: msg });
+          }
+          if (e instanceof NothingToWithdrawError || e instanceof PaymentFailedError) throw e;
+          throw new PaymentFailedError("PrizePool.withdraw() failed.", { cause: msg });
+        }
+        if (status === "failed") {
+          throw new PaymentFailedError("PrizePool.withdraw() did not confirm on-chain.", {
+            prizePoolAddress: prizePool,
+            txHash
+          });
+        }
+        if (amountMicro === 0n && input.checkBalance === false) ;
+        return {
+          prizePoolAddress: prizePool,
+          amount: formatMicroToUsd(amountMicro),
+          amountMicro: amountMicro.toString(),
+          txHash,
+          status
+        };
       }
     };
     /**
@@ -697,7 +869,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) => {
@@ -726,7 +903,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;
@@ -838,19 +1015,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() {
@@ -960,6 +1169,9 @@ var Playmos = class {
       );
       const payment2 = this.mapServerPayment(res.payment, "entry", amountMicro);
       if (input.identity) payment2.identity = input.identity;
+      const pool = res.clientParams?.contractAddress ?? this.config.contracts?.prizePool;
+      if (pool) payment2.prizePoolAddress = pool.toLowerCase();
+      payment2.roundKey = res.clientParams?.roundKey ?? res.clientParams?.roundId ?? payment2.roundId ?? input.roundId;
       return payment2;
     }
     const intent = await this.http.post(
@@ -987,6 +1199,8 @@ var Playmos = class {
     const { txHash } = await waitForCalls(provider, callsId);
     const payment = await this.settle(intent.payment.id, txHash);
     payment.identity = identity;
+    payment.prizePoolAddress = prizePool.toLowerCase();
+    payment.roundKey = roundKey;
     return payment;
   }
   /**
@@ -1000,12 +1214,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");
@@ -1016,12 +1231,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",
@@ -1030,7 +1240,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,
@@ -1046,6 +1256,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) {
@@ -1094,6 +1310,58 @@ var Playmos = class {
     const fromServer = intent.clientParams?.amountUnits ?? intent.clientParams?.amountMicro;
     return fromServer ? BigInt(fromServer) : local;
   }
+  /**
+   * Read PrizePool.withdrawable[wallet] via eth_call (issue #41).
+   * Uses the wallet provider when present; otherwise a public Base Sepolia RPC in test.
+   */
+  async readWithdrawable(prizePool, wallet) {
+    const data = viem.encodeFunctionData({
+      abi: prizePoolAbi,
+      functionName: "withdrawable",
+      args: [wallet]
+    });
+    let raw;
+    try {
+      if (await walletAvailable(this.config.wallet)) {
+        const provider = resolveProvider(this.config.wallet);
+        raw = await provider.request({
+          method: "eth_call",
+          params: [{ to: prizePool, data }, "latest"]
+        });
+      } else {
+        const rpc = this.env.network === "base" ? "https://mainnet.base.org" : "https://sepolia.base.org";
+        const res = await fetch(rpc, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "eth_call",
+            params: [{ to: prizePool, data }, "latest"]
+          })
+        });
+        const json = await res.json();
+        if (!json.result) {
+          throw new ApiError(
+            `eth_call withdrawable failed: ${json.error?.message ?? "no result"}`,
+            { prizePool, wallet }
+          );
+        }
+        raw = json.result;
+      }
+    } catch (e) {
+      if (e instanceof ApiError) throw e;
+      throw new ApiError(`Could not read withdrawable balance: ${e.message}`, {
+        prizePool,
+        wallet
+      });
+    }
+    return viem.decodeFunctionResult({
+      abi: prizePoolAbi,
+      functionName: "withdrawable",
+      data: raw
+    });
+  }
   sponsorUrl(intent) {
     if (this.config.gas?.mode === "player") return void 0;
     return this.config.gas?.paymasterUrl ?? intent.clientParams?.paymasterUrl;
@@ -1381,6 +1649,7 @@ exports.InsufficientGasError = InsufficientGasError;
 exports.InvalidAmountError = InvalidAmountError;
 exports.MICRO_PER_USDC = MICRO_PER_USDC;
 exports.MissingFieldError = MissingFieldError;
+exports.NothingToWithdrawError = NothingToWithdrawError;
 exports.PaymentFailedError = PaymentFailedError;
 exports.PayoutError = PayoutError;
 exports.Playmos = Playmos;