@playmos/sdk 0.1.4 → 0.1.5

package/README.md

@@ -0,0 +1,86 @@
+# @playmos/sdk
+
+Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-game prize-pool entries (10%, 60/30/10), and agent economies. USD in, USDC on-chain — no crypto UX for your players.
+
+## Install
+
+```bash
+npm i @playmos/sdk
+```
+
+## Quickstart — the no-wallet sandbox
+
+The public sandbox key `pk_test_playmos_sandbox` runs against a real Playmos test service on Base Sepolia. **You don't need a wallet:** on a `pk_test` key with no `wallet` configured, the SDK routes to a server-settle path where Playmos signs and submits the on-chain transaction for you. You still get a real, confirmed `txHash` — just signed by the service. No wallet, no gas, no crypto.
+
+The key comes wired to two demo games: `game_sandbox_iap` (IAP) and `game_sandbox_skill` (prize pool).
+
+### In-app purchase — `pay()`
+
+```ts
+import { Playmos } from "@playmos/sdk";
+
+// No wallet in the sandbox — Playmos signs the test payment for you.
+const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox" });
+
+const payment = await playmos.pay({
+  gameId: "game_sandbox_iap", // the public sandbox IAP game
+  amount: "4.99",             // USD, as a string
+  sku: "gems_500",            // your product id
+  playerId: "player_abc",     // your user id
+});
+
+payment.status; // "confirmed" — real, on Base Sepolia
+payment.txHash; // 0x… open on sepolia.basescan.org
+```
+
+### Skill-game entry — `enterRound()`
+
+```ts
+const entry = await playmos.enterRound({
+  gameId: "game_sandbox_skill",
+  roundId: "5m-5944009",
+  amount: "1.00",         // grows this round's pool
+  playerId: "player_abc",
+});
+// entry.status === "confirmed"; entry.split is the on-chain 60/30/10 breakdown
+```
+
+### Verify before you grant
+
+Grant items on a verified confirmation — never on the client `pay()` return alone.
+
+```ts
+const result = await playmos.verify(payment.id); // on-chain read
+if (result.status === "confirmed") grantItem(result.playerId, result.sku);
+```
+
+## 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.
+
+```ts
+const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox", mock: true });
+const payment = await playmos.pay({
+  gameId: "game_sandbox_iap", sku: "gems_100", amount: "4.99", playerId: "player_abc",
+});
+// instant — payment.status === "confirmed", payment.mock === true
+```
+
+Mock mode is not test mode: mock is fabricated and offline; the sandbox is real and settles on Base Sepolia.
+
+## Production — real player wallets
+
+Outside the sandbox (a `pk_live` key), or whenever you want the player to sign their own on-chain transaction, configure a wallet connector. With a wallet present the SDK uses the client-signed path instead of server-settle.
+
+```ts
+const playmos = new Playmos({
+  apiKey: "pk_live_…",
+  wallet: { connector: "base-account" }, // or "injected" in a wallet browser
+});
+```
+
+Promote by swapping the key — the same code that passed in the sandbox works live.
+
+## Docs
+
+Full documentation — skill games, webhooks, gas, payouts, agent economies, and the REST API — at [playmos.io](https://playmos.io).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playmos/sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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,