@playmos/sdk 0.3.5 → 0.3.7

package/README.md

@@ -5,20 +5,6 @@
 Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-game prize-pool entries (10%, 60/30/10), and **in-game economies** (player · NPC · agent commerce via `transfer()`). USD in, USDC on-chain — no crypto UX for your players.
 
 
-## Local `file:` / monorepo install
-
-`@playmos/sdk` ships **built `dist/`**. `prepare` / `prepack` / `prepublishOnly` run
-`scripts/ensure-build.cjs`, which rebuilds `dist/` via local `tsup` or (on a cold
-`file:` install with no `sdk/node_modules`) `npx --yes tsup@8.3.0`:
-
-- `npm install` inside `sdk/`
-- `npm install` of a **`file:`** / git dependency (dogfood monorepos)
-- `npm publish` / pack
-
-So wiping `dist/` then `npm i file:…/sdk` still yields a current build (#211).
-CI also fails if committed `dist/` drifts from source.
-
-
 ## Install
 
 ```bash
@@ -205,6 +191,26 @@ The full 5-NPC walkthrough — create → fund → P2P / shop / bounty, each con
 PLAYMOS_SK_TEST=sk_test_… PLAYMOS_FEE_SINK=0x… node docs/examples/playmos-town-sdk.mjs
 ```
 
+## Local `file:` / monorepo install
+
+`@playmos/sdk` ships **built `dist/`**. Lifecycle hooks `prepare` / `prepack` / `prepublishOnly`
+run `scripts/ensure-build.cjs` (rebuild via local `tsup` or, on a cold `file:` install with no
+`sdk/node_modules`, `npx --yes tsup@8.3.0`) — **when lifecycle scripts are enabled**.
+
+**Repo hardening (sdk#431 / #434):** root + `sdk/` + `service/` + `contracts/` set
+`ignore-scripts=true` in `.npmrc`. That blocks dependency install scripts (supply-chain defense)
+and also suppresses those prepare/prepack/prepublishOnly hooks.
+
+| Action | What to do |
+|--------|------------|
+| Day-to-day install in this monorepo | `npm ci` / `npm i` as usual — scripts ignored by design |
+| Rebuild dist after source edits | **`npm run build`** in `sdk/` (user scripts still run) |
+| **Manual** `npm publish` from a laptop | **`cd sdk && npm run build && npm publish`** — do not rely on prepublishOnly |
+| CI publish | Already runs `npm run build` explicitly before pack/publish |
+
+So wiping `dist/` then `npm i file:…/sdk` may **not** auto-rebuild under `ignore-scripts`;
+run `npm run build` in `sdk/` first, or use CI. CI also fails if committed `dist/` drifts from source.
+
 ## Mock mode — offline, deterministic
 
 For CI and wiring checks, `mock: true` returns instant, deterministic results with **no network and no chain**. Results carry `mock: true` and use the real status union, so your handling code sees the exact production shape.
@@ -215,9 +221,23 @@ const payment = await playmos.pay({
   gameId: "game_sandbox_iap", sku: "gems_100", amount: "0.99", playerId: "player_abc",
 });
 // instant — payment.status === "confirmed", payment.mock === true
+
+// Operator lifecycle offline too — no sk_ required when mock:true (#435)
+await playmos.rounds.open({
+  gameId: "game_sandbox_skill",
+  roundId: "r1",
+  entryAmount: "0.25",
+  payout: { kind: "winner-take-all" },
+});
+await playmos.rounds.lock({ roundId: "r1" });
+await playmos.rounds.settle({
+  roundId: "r1",
+  results: { ranking: ["0x0000000000000000000000000000000000000001"] },
+});
 ```
 
 Mock mode is not test mode: mock is fabricated and offline; the sandbox is real and settles on Base Sepolia.
+**Live** `rounds.open` / `lock` / `settle` still need a provisioned secret key on the server.
 
 ## Production — real player wallets
 
@@ -257,4 +277,8 @@ The escrow/marketplace resolve endpoints (release/refund/confirm) return a deter
 
 ## Docs
 
-Full documentation — skill games, webhooks, gas, payouts, in-game economies, and the REST API — at [playmos.io](https://playmos.io).
+Full developer docs (install, IAP `pay()`, skill `enterRound()`, agents, webhooks, REST) — **public, no login**:
+
+**https://playmos-docs-public.vercel.app/docs**
+
+That is the third-party / stranger surface while we stress-test. Production **`playmos.io/docs`** comes after Founder promote (gate still holds for production only).

package/dist/index.cjs

@@ -315,12 +315,66 @@ function createHttpClient(baseUrl, apiKey, retry) {
     }
     return false;
   }
+  async function probeSignerBelowFloor() {
+    try {
+      const res = await send(`${base}/health`, { method: "GET" });
+      if (!res.ok) return { below: false };
+      const body = await res.json();
+      const bal = body?.capabilities?.payments?.signerBalance;
+      if (!bal || bal.ok !== false) return { below: false };
+      const reason = bal.reason ?? "";
+      const fundedFloorMiss = reason === "low_usdc" || reason === "low_eth" || reason === "low_usdc_and_eth";
+      if (!fundedFloorMiss) return { below: false, reason: reason || void 0 };
+      return { below: true, reason };
+    } catch {
+      return { below: false };
+    }
+  }
   async function sendWithRetry(url, init) {
     let res = await send(url, init);
+    let signerBelowFloor = false;
+    let signerBelowReason;
+    let probed = false;
+    const maybeProbe = async () => {
+      if (probed || signerBelowFloor) return;
+      if (res.status !== 502 && res.status !== 503 && res.status !== 504) return;
+      const ct = (res.headers.get("content-type") || "").toLowerCase();
+      if (ct.includes("application/json")) return;
+      probed = true;
+      const probe = await probeSignerBelowFloor();
+      signerBelowFloor = probe.below;
+      signerBelowReason = probe.reason;
+    };
+    const maybePeekJsonSignerLow = async () => {
+      if (signerBelowFloor) return;
+      if (res.status !== 502 && res.status !== 503 && res.status !== 504) return;
+      const ct = (res.headers.get("content-type") || "").toLowerCase();
+      if (!ct.includes("application/json")) return;
+      try {
+        const peek = JSON.parse(await res.clone().text());
+        const code = peek?.error?.code;
+        const reason = peek?.error?.reason;
+        if (code === "signer_low_balance" || reason === "low_usdc" || reason === "low_eth" || reason === "low_usdc_and_eth") {
+          signerBelowFloor = true;
+          signerBelowReason = reason ?? code;
+        }
+      } catch {
+      }
+    };
+    const classifySignerBelow = async () => {
+      await maybeProbe();
+      await maybePeekJsonSignerLow();
+    };
+    await classifySignerBelow();
     for (let attempt = 0; attempt < cfg.maxRetries && isRetryable(res, init); attempt++) {
+      if (signerBelowFloor) break;
       await sleep(backoffMs(res, attempt, cfg));
       res = await send(url, init);
+      await classifySignerBelow();
     }
+    const flagged = res;
+    flagged.__playmosSignerBelowFloor = signerBelowFloor;
+    if (signerBelowReason) flagged.__playmosSignerBelowReason = signerBelowReason;
     return res;
   }
   async function handle(res, acceptStatuses) {
@@ -339,8 +393,22 @@ function createHttpClient(baseUrl, apiKey, retry) {
       json = text ? JSON.parse(text) : {};
     } catch {
       const gateway = res.status === 502 || res.status === 503 || res.status === 504;
-      const msg = gateway ? `Sandbox gateway timeout (${res.status}) from ${res.url} \u2014 the request likely exceeded the platform limit while settling on-chain. Retry with the same idempotency key (safe); prefer a dedicated Base Sepolia RPC on the service (BB-GATEB-002).` : `Non-JSON response (${res.status}) from ${res.url}`;
-      throw new ApiError(msg, { status: res.status, body: text.slice(0, 500), gateway });
+      const below = res.__playmosSignerBelowFloor === true;
+      let msg;
+      if (gateway && below) {
+        const why = res.__playmosSignerBelowReason ?? "low_balance";
+        msg = `Sandbox signer below funding floor (${why}) (${res.status} from ${res.url}) \u2014 top up Sepolia USDC (see GET /health capabilities.payments.signerBalance). Do not retry; retry cannot succeed until funded. Cross-ref: issue #205 recurrence \xB7 hub funding #15.`;
+      } else if (gateway) {
+        msg = `Sandbox gateway timeout (${res.status}) from ${res.url} \u2014 the request likely exceeded the platform limit while settling on-chain. Retry with the same idempotency key (safe); prefer a dedicated Base Sepolia RPC on the service (BB-GATEB-002).`;
+      } else {
+        msg = `Non-JSON response (${res.status}) from ${res.url}`;
+      }
+      throw new ApiError(msg, {
+        status: res.status,
+        body: text.slice(0, 500),
+        gateway,
+        signerBelowFloor: below || void 0
+      });
     }
     if (res.ok || acceptStatuses !== void 0 && acceptStatuses.includes(res.status)) {
       return json;
@@ -981,7 +1049,7 @@ var Playmos = class {
     this.mockWithdrawable = /* @__PURE__ */ new Map();
     this.rounds = {
       open: async (input) => {
-        this.assertSecretKey("playmos.rounds.open");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.open");
         requireField(input?.gameId, "gameId");
         requireField(input?.roundId, "roundId");
         requireField(input?.entryAmount, "entryAmount");
@@ -1035,7 +1103,7 @@ var Playmos = class {
         return body.round;
       },
       lock: async (input) => {
-        this.assertSecretKey("playmos.rounds.lock");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.lock");
         requireField(input?.roundId, "roundId");
         if (this.config.mock) {
           const existing = this.mockRounds.get(input.roundId);
@@ -1067,7 +1135,7 @@ var Playmos = class {
         return round;
       },
       settle: async (input) => {
-        this.assertSecretKey("playmos.rounds.settle");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.settle");
         requireField(input?.roundId, "roundId");
         if (!input?.results) throw new ConfigError("results are required (ranking or winners)");
         if (this.config.mock) {
@@ -1141,7 +1209,7 @@ var Playmos = class {
        * chain Cancelled(4) reconciles — poll `rounds.get` or re-call cancel (#346).
        */
       cancel: async (input) => {
-        this.assertSecretKey("playmos.rounds.cancel");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.cancel");
         requireField(input?.roundId, "roundId");
         if (this.config.mock) {
           const existing = this.mockRounds.get(input.roundId);

package/dist/index.js

@@ -245,12 +245,66 @@ function createHttpClient(baseUrl, apiKey, retry) {
     }
     return false;
   }
+  async function probeSignerBelowFloor() {
+    try {
+      const res = await send(`${base}/health`, { method: "GET" });
+      if (!res.ok) return { below: false };
+      const body = await res.json();
+      const bal = body?.capabilities?.payments?.signerBalance;
+      if (!bal || bal.ok !== false) return { below: false };
+      const reason = bal.reason ?? "";
+      const fundedFloorMiss = reason === "low_usdc" || reason === "low_eth" || reason === "low_usdc_and_eth";
+      if (!fundedFloorMiss) return { below: false, reason: reason || void 0 };
+      return { below: true, reason };
+    } catch {
+      return { below: false };
+    }
+  }
   async function sendWithRetry(url, init) {
     let res = await send(url, init);
+    let signerBelowFloor = false;
+    let signerBelowReason;
+    let probed = false;
+    const maybeProbe = async () => {
+      if (probed || signerBelowFloor) return;
+      if (res.status !== 502 && res.status !== 503 && res.status !== 504) return;
+      const ct = (res.headers.get("content-type") || "").toLowerCase();
+      if (ct.includes("application/json")) return;
+      probed = true;
+      const probe = await probeSignerBelowFloor();
+      signerBelowFloor = probe.below;
+      signerBelowReason = probe.reason;
+    };
+    const maybePeekJsonSignerLow = async () => {
+      if (signerBelowFloor) return;
+      if (res.status !== 502 && res.status !== 503 && res.status !== 504) return;
+      const ct = (res.headers.get("content-type") || "").toLowerCase();
+      if (!ct.includes("application/json")) return;
+      try {
+        const peek = JSON.parse(await res.clone().text());
+        const code = peek?.error?.code;
+        const reason = peek?.error?.reason;
+        if (code === "signer_low_balance" || reason === "low_usdc" || reason === "low_eth" || reason === "low_usdc_and_eth") {
+          signerBelowFloor = true;
+          signerBelowReason = reason ?? code;
+        }
+      } catch {
+      }
+    };
+    const classifySignerBelow = async () => {
+      await maybeProbe();
+      await maybePeekJsonSignerLow();
+    };
+    await classifySignerBelow();
     for (let attempt = 0; attempt < cfg.maxRetries && isRetryable(res, init); attempt++) {
+      if (signerBelowFloor) break;
       await sleep(backoffMs(res, attempt, cfg));
       res = await send(url, init);
+      await classifySignerBelow();
     }
+    const flagged = res;
+    flagged.__playmosSignerBelowFloor = signerBelowFloor;
+    if (signerBelowReason) flagged.__playmosSignerBelowReason = signerBelowReason;
     return res;
   }
   async function handle(res, acceptStatuses) {
@@ -269,8 +323,22 @@ function createHttpClient(baseUrl, apiKey, retry) {
       json = text ? JSON.parse(text) : {};
     } catch {
       const gateway = res.status === 502 || res.status === 503 || res.status === 504;
-      const msg = gateway ? `Sandbox gateway timeout (${res.status}) from ${res.url} \u2014 the request likely exceeded the platform limit while settling on-chain. Retry with the same idempotency key (safe); prefer a dedicated Base Sepolia RPC on the service (BB-GATEB-002).` : `Non-JSON response (${res.status}) from ${res.url}`;
-      throw new ApiError(msg, { status: res.status, body: text.slice(0, 500), gateway });
+      const below = res.__playmosSignerBelowFloor === true;
+      let msg;
+      if (gateway && below) {
+        const why = res.__playmosSignerBelowReason ?? "low_balance";
+        msg = `Sandbox signer below funding floor (${why}) (${res.status} from ${res.url}) \u2014 top up Sepolia USDC (see GET /health capabilities.payments.signerBalance). Do not retry; retry cannot succeed until funded. Cross-ref: issue #205 recurrence \xB7 hub funding #15.`;
+      } else if (gateway) {
+        msg = `Sandbox gateway timeout (${res.status}) from ${res.url} \u2014 the request likely exceeded the platform limit while settling on-chain. Retry with the same idempotency key (safe); prefer a dedicated Base Sepolia RPC on the service (BB-GATEB-002).`;
+      } else {
+        msg = `Non-JSON response (${res.status}) from ${res.url}`;
+      }
+      throw new ApiError(msg, {
+        status: res.status,
+        body: text.slice(0, 500),
+        gateway,
+        signerBelowFloor: below || void 0
+      });
     }
     if (res.ok || acceptStatuses !== void 0 && acceptStatuses.includes(res.status)) {
       return json;
@@ -911,7 +979,7 @@ var Playmos = class {
     this.mockWithdrawable = /* @__PURE__ */ new Map();
     this.rounds = {
       open: async (input) => {
-        this.assertSecretKey("playmos.rounds.open");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.open");
         requireField(input?.gameId, "gameId");
         requireField(input?.roundId, "roundId");
         requireField(input?.entryAmount, "entryAmount");
@@ -965,7 +1033,7 @@ var Playmos = class {
         return body.round;
       },
       lock: async (input) => {
-        this.assertSecretKey("playmos.rounds.lock");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.lock");
         requireField(input?.roundId, "roundId");
         if (this.config.mock) {
           const existing = this.mockRounds.get(input.roundId);
@@ -997,7 +1065,7 @@ var Playmos = class {
         return round;
       },
       settle: async (input) => {
-        this.assertSecretKey("playmos.rounds.settle");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.settle");
         requireField(input?.roundId, "roundId");
         if (!input?.results) throw new ConfigError("results are required (ranking or winners)");
         if (this.config.mock) {
@@ -1071,7 +1139,7 @@ var Playmos = class {
        * chain Cancelled(4) reconciles — poll `rounds.get` or re-call cancel (#346).
        */
       cancel: async (input) => {
-        this.assertSecretKey("playmos.rounds.cancel");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.cancel");
         requireField(input?.roundId, "roundId");
         if (this.config.mock) {
           const existing = this.mockRounds.get(input.roundId);

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@playmos/sdk",
-  "version": "0.3.5",
-  "description": "Playmos SDK \u2014 stablecoin payments for games on Base. One SDK for IAP (1%), skill-game prize-pool entries (10%, 60/30/10), and agent economies. USD in, USDC on-chain, no crypto UX for players.",
+  "version": "0.3.7",
+  "description": "Playmos SDK — stablecoin payments for games on Base. One SDK for IAP (1%), skill-game prize-pool entries (10%, 60/30/10), and agent economies. USD in, USDC on-chain, no crypto UX for players.",
   "license": "UNLICENSED",
   "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/playmos-labs/playmos-sdk.git",
+    "directory": "sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.cjs",