@playmos/sdk 0.1.6 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # @playmos/sdk
 
+**🧪 Beta — Playmos SDK.** Runs on Base Sepolia **testnet**. The value-movement primitives (escrow / marketplace / transfer) are proven on-chain but **not yet production-hardened**, and nothing is on mainnet. Build and integrate freely against the sandbox; don't route real user funds yet.
+
 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
@@ -8,6 +10,15 @@ Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-
 npm i @playmos/sdk
 ```
 
+Requires **Node 18 / 20 / 22 LTS** for the monorepo toolchains (Hardhat/service). See repo `docs/TOOLCHAIN.md` (issue #5).
+
+## Browser vs server entry
+
+- **Games (browser / Vite / Phaser):** `import { Playmos } from "@playmos/sdk"` — this entry is browser-safe and does **not** import Node `crypto` (issue #9).
+- **Your backend (webhook receivers):** `import { verifyWebhook } from "@playmos/sdk/server"` — HMAC verification uses Node crypto and must stay off the client bundle.
+
+The sandbox API also sends CORS headers so browser `pay()` / `enterRound()` work without a same-origin proxy (issue #10).
+
 ## 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.
@@ -45,6 +56,59 @@ const entry = await playmos.enterRound({
 // entry.status === "confirmed"; entry.split is the on-chain 60/30/10 breakdown
 ```
 
+### Move USDC between wallets — `transfer()`
+
+The base value-movement primitive: move USDC from one wallet to another with a configurable per-call fee. The **game logic is the authority** — you already decided the move is valid — so this is a direct, unconditional push (reach for `escrow`/`marketplace` when a trust boundary needs fair exchange). Settled through the on-chain `PlaymosTransfer` contract; the split is verifiable on BaseScan.
+
+```ts
+// NPC→NPC with a 5% fee (Playmos Town P2P). Requires sk_test_ + agents.createWallet first.
+// Full walkthrough: docs/examples/playmos-town-sdk.mjs
+// Confirm: status === "settled" && txHash, or poll playmos.transfers.get(id) if settling.
+const t = await playmos.transfer({
+  // `from` is OPTIONAL in the sandbox — omit it and the service uses its server-held signer wallet
+  // (Phase 1a's only payer), so you don't need to know that address to run this example.
+  to:     "0x…blacksmith",
+  amount: "0.80",         // USD; USDC settles on-chain. Stay UNDER the $1.00 sandbox cap (see below).
+  feeBps: 500,            // 5% — 0–10000
+  feeSink: "0x…treasury", // required when feeBps > 0
+  memo:   "ore",          // optional, echoed on the receipt
+});
+t.status;          // "settled" — real, on Base Sepolia
+t.txHash;          // 0x… open on sepolia.basescan.org
+t.net;             // "0.76"  (payee)
+t.fee;             // "0.04"  (feeSink)
+t.idempotentReplay; // false on the first settle
+```
+
+**`feeBps: 0` is an untaxed reward/faucet transfer** (no fee taken; `feeSink` not needed) — e.g. a monster-bounty payout from a world wallet to a fighter. Set `feeBps: 10000` for a 100% first-party sale (all of it to `feeSink`).
+
+| Field | Required | Notes |
+|---|---|---|
+| `from` | no | Payer wallet — a `0x` address. **Omit in the sandbox** and the service defaults it to its server-held signer wallet (Phase 1a's only payer). If supplied, it must be that wallet. |
+| `to` | yes | Payee wallet — a `0x` address. |
+| `amount` | yes | USD decimal string ("0.80"); > 0, ≤ 2 dp. **Sandbox cap: ≤ $1.00 per transfer** (see limits below). |
+| `feeBps` | no (default `0`) | Per-call fee in bps, **0–10000**. `0` = untaxed reward/faucet. |
+| `feeSink` | when `feeBps > 0` | Fee destination `0x` address. |
+| `memo` | no | Optional note, echoed on the receipt. |
+| `idempotencyKey` | no | Pass the same key on a retry to guarantee **at most one** on-chain transfer (see below). |
+
+**Sandbox limits (enforced before any signing).** The public sandbox signs from a shared funded testnet wallet, so the transfer path is guarded: **$1.00 max per transfer** (a larger `amount` is a `400`), **5 requests/minute** per IP and per key (`429`), and a **$20/day budget** across all sandbox transfers (`429`). These are testnet abuse controls — not product limits.
+
+**Retries are safe (idempotent, no double-spend).** Every transfer is anchored on a requirement id derived from `idempotencyKey`. The service durably reserves the transfer *before* broadcasting, so a retry with the same key — or two concurrent calls with the same key — **broadcast at most one transaction**; the loser returns the original result with `idempotentReplay: true`. Preview the split with no network via `previewTransferSplit(amount, feeBps)`. Reusing an id with **different** terms (payTo/amount/fee/sink/from) is rejected, not silently replayed.
+
+**REST (no SDK).** The SDK's `transfer()` is a thin wrapper over `POST /v1/transfers`:
+
+```bash
+curl -X POST https://<sandbox-host>/v1/transfers \
+  -H "Authorization: Bearer pk_test_playmos_sandbox" \
+  -H "Content-Type: application/json" \
+  -d '{ "to": "0x…blacksmith", "amount": "0.80", "feeBps": 500, "feeSink": "0x…treasury", "memo": "ore", "idempotencyKey": "ore-trade-1" }'
+```
+
+Fields match the table above (`from` optional → defaults to the signer; `feeBps`/`feeSink` as documented). Poll `GET /v1/transfers/:id` to reconcile a transfer's status against the chain (it recovers a transfer left mid-flight by a crash).
+
+> Sandbox only (Phase 1a): `transfer` settles server-held NPC/agent wallets on Base Sepolia. The player-signed (EIP-3009) non-custodial path is Phase 1b.
+
 ### Verify before you grant
 
 Grant items on a verified confirmation — never on the client `pay()` return alone.
@@ -81,6 +145,29 @@ const playmos = new Playmos({
 
 Promote by swapping the key — the same code that passed in the sandbox works live.
 
+## Value movement — escrow, marketplace, transfer (0.2.0, testnet)
+
+`0.2.0` adds non-custodial USDC value-movement primitives on top of the settlement core:
+
+- **`playmos.transfer(...)`** — a direct USDC transfer.
+- **`playmos.escrow.hold / release / refund / get`** — hold funds against a deal, then pay the payee (fee skimmed at release) or refund the payer (100%). Every term is frozen on-chain at hold.
+- **`playmos.marketplace.list / buy / confirm / refund / cancel / get`** — a listing packaged as an escrow deal (`buy` = hold, `confirm` = release, timeout/dispute = refund), including `buy({ deliver: true })` to hold+release in one call.
+
+**Status quo (2026-07): testnet-sandbox only.** These paths are proven on Base Sepolia (independently reconciled on-chain) but are **not** marketed as production-hardened, and are not on mainnet. For money preflights, **point the service at a dedicated RPC** (Alchemy/QuickNode) — do not rely on a load-balanced public endpoint for read-your-write consistency.
+
+### Resolve status-code contract
+
+The escrow/marketplace resolve endpoints (release/refund/confirm) return a deterministic contract — handle it explicitly:
+
+| Code | Meaning | Client action |
+|------|---------|---------------|
+| **404** | Unknown escrow / listing | Terminal — the id does not exist |
+| **409** | Not resolvable (already released/refunded, or genuinely never held) | Terminal — do not retry |
+| **503** | Transient (RPC read-lag, or a crash-orphaned hold being reconciled) | **Retry** with backoff |
+| **400** | Malformed input | Terminal — fix the request |
+
+**On a `503`, retry the release/confirm** — it means the on-chain state just hasn't propagated yet, not that anything failed.
+
 ## Docs
 
 Full documentation — skill games, webhooks, gas, payouts, agent economies, and the REST API — at [playmos.io](https://playmos.io).

package/dist/errors-CjL85YKR.d.cts

@@ -0,0 +1,502 @@
+/**
+ * Public types — pruned to WIRED capability only (fixes #344/I and #335/E).
+ *
+ * The old vendored surface advertised four wallet connectors that silently
+ * returned {connected:false} and config fields the code never read. Here the
+ * types expose exactly what V1 does: two connectors, the fields `pay()` /
+ * `enterRound()` actually use, and no more.
+ */
+type Network = "base" | "base-sepolia";
+/** Only the connectors that are actually implemented. */
+type WalletConnector = "base-account" | "injected";
+type GasMode = "sponsored" | "player";
+type PaymentStatus = "created" | "pending" | "confirmed" | "failed";
+/** Minimal EIP-1193 provider shape (what the wallet must expose). */
+interface Eip1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+}
+interface GasConfig {
+    mode?: GasMode;
+    /** CDP paymaster URL — required only for `mode: "sponsored"`. */
+    paymasterUrl?: string;
+}
+interface WalletConfig {
+    connector?: WalletConnector;
+    /**
+     * Pre-built EIP-1193 provider. If omitted, `injected` uses globalThis.ethereum
+     * and `base-account` expects a provider supplied by the Base Account SDK host.
+     */
+    provider?: Eip1193Provider;
+}
+/** Per-game contract addresses. On testnet these come from the service intent,
+ *  but a studio may pin them explicitly (matches the dogfood adapter). */
+interface ContractConfig {
+    usdc?: `0x${string}`;
+    playmosPay?: `0x${string}`;
+    prizePool?: `0x${string}`;
+}
+/**
+ * @deprecated Unused — agent routes are enabled server-side (SERVICE_MASTER_SECRET +
+ * transfer contracts). Prefer `sk_test_` + `agents.createWallet`; do not set this.
+ * Kept optional so old clients don't type-error (issue #23).
+ */
+interface AgentEconomyConfig {
+    enabled?: boolean;
+}
+interface PlaymosConfig {
+    /** pk_test_* / sk_test_* (sandbox / Base Sepolia) or pk_live_* / sk_live_* (mainnet).
+     *  Agents require **sk_test_** (secret studio key), not the public pk_test_ sandbox key. */
+    apiKey: string;
+    /** Override the network derived from the key. Explicit value wins. */
+    network?: Network;
+    wallet?: WalletConfig;
+    gas?: GasConfig;
+    /** @deprecated No-op. Server enables agents; use sk_test_ + agents.* (issue #23). */
+    agentEconomy?: AgentEconomyConfig;
+    contracts?: ContractConfig;
+    /** Escape hatch; defaults to the right env's base URL. */
+    apiBaseUrl?: string;
+    /**
+     * Explicit, clearly-labeled offline unit-test helper — instant, deterministic,
+     * NO network, NO chain. Never the default, never conflated with sandbox. Note:
+     * even mock results use the REAL status union (never a synthetic "mocked").
+     */
+    mock?: boolean;
+}
+interface PayInput {
+    /** USD decimal string ("4.99"). Rejected: ≤ 0, non-numeric, > 2 dp. */
+    amount: string;
+    /** Your product id, echoed on the receipt + webhook. */
+    sku: string;
+    /** Your opaque user id. */
+    playerId: string;
+    /**
+     * The game this IAP belongs to. Optional: when your API key maps to exactly
+     * one game the service resolves it for you (the quickstart). Supply it
+     * explicitly when your key spans multiple games.
+     */
+    gameId?: string;
+    /** The studio wallet that receives the 99%. Falls back to the service default. */
+    studio?: `0x${string}`;
+    /** Supply your own to make retries safe; omit and the SDK generates a ULID. */
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+}
+interface EnterRoundInput {
+    /** The game — selects its prize-pool contract. */
+    gameId: string;
+    /** The round being entered. */
+    roundId: string;
+    /** USD entry — grows this round's pool. */
+    amount: string;
+    playerId: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+    /**
+     * Advanced (games that manage their own on-chain rounds, e.g. the Playmos
+     * game-hub kit): the EXACT on-chain round key to enter — overrides the default
+     * `${gameId}:${roundId}` derivation. Set it to the value your game's server
+     * verifies `hasEntered` against (e.g. "bjtest:T1").
+     */
+    roundKey?: string;
+    /**
+     * Advanced: the EXACT on-chain identity for this paid attempt (e.g.
+     * "0xWallet#nonce"). Overrides the server-generated identity so the on-chain
+     * entry and your server's `hasEntered` check line up. One entry per identity.
+     */
+    identity?: string;
+}
+/**
+ * Input to `playmos.transfer(...)` — the value-movement `transfer` primitive (Phase 1a): move USDC
+ * from one wallet to another, with a configurable per-call fee. The game logic is the authority; the
+ * SDK just moves the money and proves it on-chain.
+ */
+interface TransferInput {
+    /**
+     * The payer — either a **game NPC id** you assigned a wallet to (`playmos.agents.createWallet`, e.g.
+     * `"npc_miner"`) OR a raw `0x` wallet address. OMIT it in the sandbox and the service defaults `from` to
+     * its server-held treasury signer (the untaxed-faucet path). Transferring FROM an NPC requires a secret
+     * test key (`sk_test_`) and settles gaslessly (the NPC signs; Playmos relays + pays gas).
+     */
+    from?: string;
+    /** The payee — a game NPC id you assigned a wallet to, OR a raw `0x` address (player or NPC). */
+    to: string;
+    /** USD decimal string ("5.00"). Rejected: ≤ 0, non-numeric, > 2 dp. */
+    amount: string;
+    /** Optional note, echoed on the receipt (carried as the requirement's `terms`). */
+    memo?: string;
+    /**
+     * Per-call Playmos fee in bps of `amount`, 0–10000. Defaults to 0.
+     *   0     → an UNTAXED reward/faucet transfer (no fee taken; `feeSink` not needed).
+     *   500   → 5% (e.g. Playmos-Town P2P: 95% to payee, 5% to `feeSink`).
+     *   10000 → 100% (e.g. a first-party shop sale: all of it to `feeSink`).
+     */
+    feeBps?: number;
+    /** Fee destination. REQUIRED when `feeBps > 0`; ignored when `feeBps === 0`. */
+    feeSink?: `0x${string}`;
+    /** Supply your own to make retries safe (anchors idempotency on the same requirement); omit and the SDK generates one. */
+    idempotencyKey?: string;
+}
+/** A wallet the SDK assigned to one of your game's NPCs (by your own id). Keys are never returned. */
+interface AgentWallet {
+    agentId: string;
+    address: `0x${string}`;
+    chain: string;
+}
+/** What `agents.fund(...)` resolves to (sandbox faucet: treasury → NPC). */
+interface AgentFundResult {
+    agent: AgentWallet;
+    funding: {
+        amount: string;
+        status: string;
+        txHash: string | null;
+        idempotentReplay: boolean;
+    };
+}
+/** What `playmos.transfer(...)` resolves to — the settled result from the settlement core. */
+interface TransferResult {
+    /** The requirement id this transfer settled (the idempotency anchor). */
+    id: string;
+    /** "settled" (on-chain confirmed) · "failed" (mined revert) · "settling" (reserved, confirmation pending). */
+    status: "settled" | "failed" | "settling";
+    /** The on-chain settlement tx (openable on BaseScan). */
+    txHash?: `0x${string}`;
+    /** Resolved payer address — omitted when it's the redacted server treasury signer. */
+    from?: `0x${string}`;
+    to: `0x${string}`;
+    /** Gross amount moved (USD). */
+    amount: string;
+    /** Fee skimmed to `feeSink` (USD). */
+    fee: string;
+    /** Amount the payee received (USD) = amount − fee. */
+    net: string;
+    feeBps: number;
+    feeSink?: `0x${string}` | null;
+    memo?: string | null;
+    /** True when a prior settle for this id was replayed instead of broadcasting again (double-spend safety). */
+    idempotentReplay: boolean;
+}
+/** Input to `playmos.escrow.hold(...)` — open a fair-exchange deal by locking the payer's USDC on-chain. */
+interface EscrowHoldInput {
+    /**
+     * Payer wallet whose USDC is locked. OPTIONAL in the sandbox: omit it and the service defaults `payer`
+     * to its server-held signer wallet (Phase 2a's only payer), like `transfer.from`.
+     */
+    payer?: `0x${string}`;
+    /** Payee wallet — where a `release` sends the funds (any identity: player or NPC). */
+    payee: `0x${string}`;
+    /** USD decimal string ("12.50"). Rejected: ≤ 0, non-numeric, > 2 dp. */
+    amount: string;
+    /**
+     * Per-call Playmos fee in bps, 0–10000, taken ONLY at `release` (a `refund` is always 100%, untaxed).
+     * Defaults to 0. Frozen at hold — the fee a deal will pay can't change once funds are locked.
+     */
+    feeBps?: number;
+    /** Fee destination. REQUIRED when `feeBps > 0`; ignored when `feeBps === 0`. */
+    feeSink?: `0x${string}`;
+    /**
+     * The authority allowed to `release`/`refund` this deal. Defaults to the payer. This is YOUR game
+     * server's address in the common case — it verifies the deal condition off-chain, then calls release.
+     */
+    resolver?: `0x${string}`;
+    /**
+     * On-chain auto-refund deadline as a relative duration — "30s" | "15m" | "1h" | "7d" (max 30 days).
+     * At/after it, ANYONE can trigger the refund (funds never get stuck). Defaults to "1h". This is the
+     * DEAL's life; it is distinct from the short off-chain window the hold authorization itself is valid for.
+     */
+    expiresIn?: string;
+    /** Absolute on-chain deadline as a unix-seconds timestamp. Overrides `expiresIn` when set. */
+    deadline?: number;
+    /** Optional note, echoed on the receipt. */
+    memo?: string;
+    /** Supply your own to make retries safe (anchors idempotency on the same deal); omit and the SDK generates one. */
+    idempotencyKey?: string;
+}
+/** What `playmos.escrow.hold(...)` resolves to. `id` is the holdId — pass it to `release`/`refund`/`get`. */
+interface EscrowHoldResult {
+    /** The deal id (holdId) — the reserve-before-broadcast anchor and the handle for release/refund/get. */
+    id: string;
+    /** "settled" (funds locked on-chain) · "failed" (mined revert) · "settling" (reserved, confirmation pending). */
+    status: "settled" | "failed" | "settling";
+    txHash?: `0x${string}`;
+    payee: `0x${string}`;
+    /** Gross amount locked (USD). */
+    amount: string;
+    feeBps: number;
+    feeSink?: `0x${string}` | null;
+    /** The resolver recorded for the deal; null means it defaulted to the payer. */
+    resolver?: `0x${string}` | null;
+    /** On-chain auto-refund deadline (unix seconds). */
+    deadline: number;
+    /** Fee that WOULD be skimmed on release (USD) — preview; a refund takes none. */
+    feeAtRelease: string;
+    /** Amount the payee WOULD receive on release (USD) = amount − feeAtRelease. */
+    netAtRelease: string;
+    memo?: string | null;
+    idempotentReplay: boolean;
+}
+/** What `release`/`refund`/`get` resolve to. */
+interface EscrowResolveResult {
+    /** The deal id (holdId). */
+    id: string;
+    /** Which resolution this was (absent on `get`). */
+    leg?: "release" | "refund";
+    /** For release/refund: the leg's settlement status. For `get`: the HOLD's on-chain-verified state. */
+    status: string;
+    txHash?: `0x${string}` | null;
+    idempotentReplay?: boolean;
+    /** How the status was derived — chain truth, honest cache, or not-yet-configured. */
+    verifiedVia?: "chain" | "cache" | "degraded";
+}
+/** An item for sale. Off-chain (game DB inventory) is Phase 3a; on-chain (token) is Phase 3b. */
+type MarketplaceItem = {
+    kind: "offchain";
+    sku: string;
+    metadata?: Record<string, unknown>;
+} | {
+    kind: "onchain";
+    token: `0x${string}`;
+    tokenId: string;
+};
+interface MarketplaceListInput {
+    /** Seller wallet (the payee, paid on sale). REQUIRED — it's never defaulted to the server signer.
+     *  (The buyer/payer is what defaults to the signer in the sandbox; the seller is a real counterparty.) */
+    seller: `0x${string}`;
+    /** The item being sold. Phase 3a settles `{ kind: "offchain", sku }`; on-chain items are Phase 3b. */
+    item: MarketplaceItem;
+    /** USD decimal string ("12.50"). */
+    price: string;
+    /** Per-sale Playmos take in bps, 0–10000, taken at settle (on the sale). Defaults to the service's config. */
+    feeBps?: number;
+    /** Fee destination; required when `feeBps > 0` and no service default is set. */
+    feeSink?: `0x${string}`;
+    /** On-sale delivery/escrow deadline as a duration — "30s"|"15m"|"1h"|"7d" (max 30d). Default "1h". */
+    deliveryWindow?: string;
+    /** Optional listing shelf-life — after this, the listing can't be bought (lazy `expired`). */
+    expiresIn?: string;
+    gameId?: string;
+    /** Supply your own for a deterministic listing id (retried list() never double-lists). */
+    idempotencyKey?: string;
+}
+type ListingStatus = "active" | "sold_pending_delivery" | "sold" | "refunded" | "cancelled" | "expired";
+/** A marketplace listing (as the service returns it). */
+interface Listing {
+    id: string;
+    status: ListingStatus;
+    seller: `0x${string}`;
+    buyer?: `0x${string}` | null;
+    item: MarketplaceItem;
+    price: string;
+    feeBps: number;
+    feeSink?: `0x${string}` | null;
+    /** Fee that WOULD be skimmed on a completed sale (USD). */
+    feeAtSale: string;
+    /** Amount the seller WOULD receive on a completed sale (USD) = price − feeAtSale. */
+    netAtSale: string;
+    deliveryWindowSec: number;
+    expiresAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** The escrow-backed sale attached to a listing after buy/confirm/refund/get. */
+interface MarketplaceSale {
+    /** The sale's settlement id (`<listingId>:sale`). */
+    id: string;
+    leg?: "confirm" | "refund";
+    /** "settled" (funds moved) · "settling" · "failed" — or the hold's verified state on `get`. */
+    status: string;
+    txHash?: `0x${string}` | null;
+    idempotentReplay?: boolean;
+    verifiedVia?: "chain" | "cache" | "degraded";
+}
+interface MarketplaceSaleResult {
+    listing: Listing;
+    sale: MarketplaceSale;
+}
+interface MarketplaceGetResult {
+    listing: Listing;
+    sale: MarketplaceSale | null;
+}
+interface Payment {
+    /** `pay_…` (IAP) or `entry_…` (prize-pool) — ULID, server-issued, unique. */
+    id: string;
+    status: PaymentStatus;
+    /** "iap" (1% external) or "entry" (60/30/10 prize-pool). */
+    kind: "iap" | "entry";
+    amount: string;
+    fee: string;
+    net: string;
+    /** Present for prize-pool entries: the 60/30/10 breakdown in USD. */
+    split?: {
+        pool: string;
+        seed: string;
+        rake: string;
+    };
+    sku?: string;
+    roundId?: string;
+    gameId?: string;
+    playerId: string;
+    txHash?: `0x${string}`;
+    chain: Network;
+    createdAt: string;
+    metadata?: Record<string, string>;
+    /**
+     * The on-chain identity used for a prize-pool entry (echo of
+     * `EnterRoundInput.identity` or the SDK-derived value) — reconcile against your
+     * server's `hasEntered`.
+     */
+    identity?: string;
+    /** True only when produced by the labeled `mock: true` helper. */
+    mock?: boolean;
+}
+/** What `verify()` resolves to (server reads the chain). */
+interface VerifyResult {
+    id: string;
+    status: PaymentStatus;
+    amount: string;
+    fee: string;
+    net: string;
+    txHash?: `0x${string}`;
+    playerId: string;
+    sku?: string;
+    roundId?: string;
+    chain: Network;
+    /** How the service derived this status: an on-chain read, the honest cache, or
+     *  degraded (chain reads not configured). Lets the SDK stop polling when the
+     *  service can never confirm on-chain. */
+    verifiedVia?: "chain" | "cache" | "degraded";
+    chainReads?: "enabled" | "degraded";
+}
+type WebhookEventType = "payment.confirmed" | "payment.failed" | "payout.settled" | "refund.processed";
+interface WebhookEvent {
+    id: string;
+    type: WebhookEventType;
+    createdAt: string;
+    data: {
+        id: string;
+        status: PaymentStatus;
+        amount: string;
+        fee: string;
+        net: string;
+        playerId: string;
+        sku?: string;
+        txHash?: `0x${string}`;
+        chain: Network;
+        metadata?: Record<string, string>;
+    };
+}
+/** How the payable pool is split among ranked wallets (best-first). Never a score. */
+type PayoutRule = {
+    kind: "winner-take-all";
+} | {
+    kind: "top-n";
+    splitsBps: number[];
+} | {
+    kind: "custom";
+    amounts: string[];
+};
+type RoundStatus = "open" | "locked" | "settled" | "cancelled" | "none";
+interface RoundOpenInput {
+    gameId: string;
+    /** Studio-facing round id (also used as the on-chain round key unless roundKey set). */
+    roundId: string;
+    /** USD entry amount ("0.25"). Fixed for the round once opened. */
+    entryAmount: string;
+    /** Studio payout rule stored for settle-from-ranking. */
+    payout: PayoutRule;
+    /** Optional ISO-8601 when the studio intends to close entries (off-chain advisory). */
+    closeAt?: string;
+    /** Optional series key for the 60/30/10 seed flywheel; defaults to gameId. */
+    seriesKey?: string;
+    /** Advanced: exact on-chain round key string (default = roundId). */
+    roundKey?: string;
+}
+interface RoundState {
+    roundId: string;
+    gameId: string;
+    roundKey: string;
+    status: RoundStatus;
+    entryAmount: string;
+    /** Payable pool in USD (from chain after lock); may be "0.00" while open. */
+    pool: string;
+    entrants: number;
+    payout: PayoutRule;
+    closeAt?: string;
+    openTxHash?: `0x${string}`;
+    lockTxHash?: `0x${string}`;
+    settleTxHash?: `0x${string}`;
+}
+interface RoundSettleInput {
+    roundId: string;
+    gameId?: string;
+    results: {
+        ranking: `0x${string}`[];
+    } | {
+        winners: {
+            wallet: `0x${string}`;
+            amount: string;
+        }[];
+    };
+}
+interface SettleRoundResult {
+    roundId: string;
+    txHash: `0x${string}`;
+    poolPaid: string;
+    winners: {
+        wallet: `0x${string}`;
+        amount: string;
+    }[];
+    status: "settled";
+}
+
+/**
+ * Typed, actionable errors — the Stripe bar (spec §11).
+ *
+ * Every error carries a stable machine-readable `code` and is thrown at the
+ * EARLIEST possible layer: input errors fire client-side before any network or
+ * chain call, so a studio never pays gas to discover a typo.
+ */
+type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "payment_failed" | "auth" | "api_error" | "config";
+declare class PlaymosError extends Error {
+    readonly code: PlaymosErrorCode;
+    /** Optional machine context (e.g. the offending field, the http status). */
+    readonly detail?: Record<string, unknown>;
+    constructor(code: PlaymosErrorCode, message: string, detail?: Record<string, unknown>);
+}
+/** amount ≤ 0, non-numeric, empty, or more than 2 decimal places. */
+declare class InvalidAmountError extends PlaymosError {
+    constructor(amount: unknown);
+}
+/** A required field (sku, playerId, gameId, roundId, agentId…) was empty. */
+declare class MissingFieldError extends PlaymosError {
+    constructor(field: string);
+}
+/** gas mode "player" and the player's ETH is too low to cover gas (pre-check, §7). */
+declare class InsufficientGasError extends PlaymosError {
+    constructor(detail?: Record<string, unknown>);
+}
+/** The player closed or failed the wallet sheet, or no provider is available. */
+declare class WalletConnectionError extends PlaymosError {
+    constructor(message?: string, detail?: Record<string, unknown>);
+}
+/** The on-chain settlement reverted, was cancelled, or timed out. */
+declare class PaymentFailedError extends PlaymosError {
+    constructor(message?: string, detail?: Record<string, unknown>);
+}
+/** Bad, missing, or wrong-environment API key (e.g. a pk_test_ key on a live route). */
+declare class AuthError extends PlaymosError {
+    constructor(message?: string, detail?: Record<string, unknown>);
+}
+/** The Playmos service returned a non-2xx we don't have a more specific error for. */
+declare class ApiError extends PlaymosError {
+    constructor(message: string, detail?: Record<string, unknown>);
+}
+/** SDK misconfiguration (e.g. a missing contract address for on-chain mode). */
+declare class ConfigError extends PlaymosError {
+    constructor(message: string, detail?: Record<string, unknown>);
+}
+
+export { type AgentWallet as A, type PlaymosErrorCode as B, ConfigError as C, type RoundStatus as D, type EscrowHoldInput as E, type WalletConfig as F, type GasConfig as G, WalletConnectionError as H, InsufficientGasError as I, type WalletConnector as J, type WebhookEventType as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type PlaymosConfig as P, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type VerifyResult as V, type WebhookEvent as W, type RoundState as a, type RoundSettleInput as b, type AgentFundResult as c, type EscrowHoldResult as d, type EscrowResolveResult as e, type MarketplaceSaleResult as f, type MarketplaceGetResult as g, type PayInput as h, type Payment as i, type EnterRoundInput as j, type TransferInput as k, type AgentEconomyConfig as l, ApiError as m, AuthError as n, type ContractConfig as o, type Eip1193Provider as p, type GasMode as q, InvalidAmountError as r, type ListingStatus as s, type MarketplaceItem as t, type MarketplaceSale as u, MissingFieldError as v, PaymentFailedError as w, type PaymentStatus as x, type PayoutRule as y, PlaymosError as z };