@playmos/sdk 0.1.4 → 0.1.6

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/dist/chunk-B7SHFZYY.js

@@ -0,0 +1,62 @@
+// src/errors.ts
+var PlaymosError = class extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.detail = detail;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidAmountError = class extends PlaymosError {
+  constructor(amount) {
+    super(
+      "invalid_amount",
+      `Invalid amount: ${JSON.stringify(amount)}. Provide a positive USD decimal string with at most 2 decimals, e.g. "4.99".`,
+      { amount }
+    );
+  }
+};
+var MissingFieldError = class extends PlaymosError {
+  constructor(field) {
+    super("missing_field", `Missing required field: "${field}".`, { field });
+  }
+};
+var InsufficientGasError = class extends PlaymosError {
+  constructor(detail) {
+    super(
+      "insufficient_gas",
+      `The player's wallet has too little ETH to pay gas. Ask them to add a little ETH, or switch to gas.mode: "sponsored".`,
+      detail
+    );
+  }
+};
+var WalletConnectionError = class extends PlaymosError {
+  constructor(message = "Could not connect the player's wallet.", detail) {
+    super("wallet_connection", message, detail);
+  }
+};
+var PaymentFailedError = class extends PlaymosError {
+  constructor(message = "The on-chain payment did not complete.", detail) {
+    super("payment_failed", message, detail);
+  }
+};
+var AuthError = class extends PlaymosError {
+  constructor(message = "Invalid or missing API key.", detail) {
+    super("auth", message, detail);
+  }
+};
+var ApiError = class extends PlaymosError {
+  constructor(message, detail) {
+    super("api_error", message, detail);
+  }
+};
+var ConfigError = class extends PlaymosError {
+  constructor(message, detail) {
+    super("config", message, detail);
+  }
+};
+
+export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, PaymentFailedError, PlaymosError, WalletConnectionError };
+//# sourceMappingURL=chunk-B7SHFZYY.js.map
+//# sourceMappingURL=chunk-B7SHFZYY.js.map

package/dist/chunk-B7SHFZYY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";AAkBO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAKtC,WAAA,CAAY,IAAA,EAAwB,OAAA,EAAiB,MAAA,EAAkC;AACrF,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,OAAO,GAAA,CAAA,MAAA,CAAW,IAAA;AACvB,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAEd,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EAClD;AACF;AAGO,IAAM,kBAAA,GAAN,cAAiC,YAAA,CAAa;AAAA,EACnD,YAAY,MAAA,EAAiB;AAC3B,IAAA,KAAA;AAAA,MACE,gBAAA;AAAA,MACA,CAAA,gBAAA,EAAmB,IAAA,CAAK,SAAA,CAAU,MAAM,CAAC,CAAA,6EAAA,CAAA;AAAA,MACzC,EAAE,MAAA;AAAO,KACX;AAAA,EACF;AACF;AAGO,IAAM,iBAAA,GAAN,cAAgC,YAAA,CAAa;AAAA,EAClD,YAAY,KAAA,EAAe;AACzB,IAAA,KAAA,CAAM,iBAAiB,CAAA,yBAAA,EAA4B,KAAK,CAAA,EAAA,CAAA,EAAM,EAAE,OAAO,CAAA;AAAA,EACzE;AACF;AAGO,IAAM,oBAAA,GAAN,cAAmC,YAAA,CAAa;AAAA,EACrD,YAAY,MAAA,EAAkC;AAC5C,IAAA,KAAA;AAAA,MACE,kBAAA;AAAA,MACA,CAAA,oHAAA,CAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AACF;AAGO,IAAM,qBAAA,GAAN,cAAoC,YAAA,CAAa;AAAA,EACtD,WAAA,CAAY,OAAA,GAAU,wCAAA,EAA0C,MAAA,EAAkC;AAChG,IAAA,KAAA,CAAM,mBAAA,EAAqB,SAAS,MAAM,CAAA;AAAA,EAC5C;AACF;AAGO,IAAM,kBAAA,GAAN,cAAiC,YAAA,CAAa;AAAA,EACnD,WAAA,CAAY,OAAA,GAAU,wCAAA,EAA0C,MAAA,EAAkC;AAChG,IAAA,KAAA,CAAM,gBAAA,EAAkB,SAAS,MAAM,CAAA;AAAA,EACzC;AACF;AAGO,IAAM,SAAA,GAAN,cAAwB,YAAA,CAAa;AAAA,EAC1C,WAAA,CAAY,OAAA,GAAU,6BAAA,EAA+B,MAAA,EAAkC;AACrF,IAAA,KAAA,CAAM,MAAA,EAAQ,SAAS,MAAM,CAAA;AAAA,EAC/B;AACF;AAGO,IAAM,QAAA,GAAN,cAAuB,YAAA,CAAa;AAAA,EACzC,WAAA,CAAY,SAAiB,MAAA,EAAkC;AAC7D,IAAA,KAAA,CAAM,WAAA,EAAa,SAAS,MAAM,CAAA;AAAA,EACpC;AACF;AAGO,IAAM,WAAA,GAAN,cAA0B,YAAA,CAAa;AAAA,EAC5C,WAAA,CAAY,SAAiB,MAAA,EAAkC;AAC7D,IAAA,KAAA,CAAM,QAAA,EAAU,SAAS,MAAM,CAAA;AAAA,EACjC;AACF","file":"chunk-B7SHFZYY.js","sourcesContent":["/**\n * Typed, actionable errors — the Stripe bar (spec §11).\n *\n * Every error carries a stable machine-readable `code` and is thrown at the\n * EARLIEST possible layer: input errors fire client-side before any network or\n * chain call, so a studio never pays gas to discover a typo.\n */\n\nexport type PlaymosErrorCode =\n  | \"invalid_amount\"\n  | \"missing_field\"\n  | \"insufficient_gas\"\n  | \"wallet_connection\"\n  | \"payment_failed\"\n  | \"auth\"\n  | \"api_error\"\n  | \"config\";\n\nexport class PlaymosError extends Error {\n  readonly code: PlaymosErrorCode;\n  /** Optional machine context (e.g. the offending field, the http status). */\n  readonly detail?: Record<string, unknown>;\n\n  constructor(code: PlaymosErrorCode, message: string, detail?: Record<string, unknown>) {\n    super(message);\n    this.name = new.target.name;\n    this.code = code;\n    this.detail = detail;\n    // Restore prototype chain for `instanceof` across transpile targets.\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** amount ≤ 0, non-numeric, empty, or more than 2 decimal places. */\nexport class InvalidAmountError extends PlaymosError {\n  constructor(amount: unknown) {\n    super(\n      \"invalid_amount\",\n      `Invalid amount: ${JSON.stringify(amount)}. Provide a positive USD decimal string with at most 2 decimals, e.g. \"4.99\".`,\n      { amount },\n    );\n  }\n}\n\n/** A required field (sku, playerId, gameId, roundId, agentId…) was empty. */\nexport class MissingFieldError extends PlaymosError {\n  constructor(field: string) {\n    super(\"missing_field\", `Missing required field: \"${field}\".`, { field });\n  }\n}\n\n/** gas mode \"player\" and the player's ETH is too low to cover gas (pre-check, §7). */\nexport class InsufficientGasError extends PlaymosError {\n  constructor(detail?: Record<string, unknown>) {\n    super(\n      \"insufficient_gas\",\n      \"The player's wallet has too little ETH to pay gas. Ask them to add a little ETH, or switch to gas.mode: \\\"sponsored\\\".\",\n      detail,\n    );\n  }\n}\n\n/** The player closed or failed the wallet sheet, or no provider is available. */\nexport class WalletConnectionError extends PlaymosError {\n  constructor(message = \"Could not connect the player's wallet.\", detail?: Record<string, unknown>) {\n    super(\"wallet_connection\", message, detail);\n  }\n}\n\n/** The on-chain settlement reverted, was cancelled, or timed out. */\nexport class PaymentFailedError extends PlaymosError {\n  constructor(message = \"The on-chain payment did not complete.\", detail?: Record<string, unknown>) {\n    super(\"payment_failed\", message, detail);\n  }\n}\n\n/** Bad, missing, or wrong-environment API key (e.g. a pk_test_ key on a live route). */\nexport class AuthError extends PlaymosError {\n  constructor(message = \"Invalid or missing API key.\", detail?: Record<string, unknown>) {\n    super(\"auth\", message, detail);\n  }\n}\n\n/** The Playmos service returned a non-2xx we don't have a more specific error for. */\nexport class ApiError extends PlaymosError {\n  constructor(message: string, detail?: Record<string, unknown>) {\n    super(\"api_error\", message, detail);\n  }\n}\n\n/** SDK misconfiguration (e.g. a missing contract address for on-chain mode). */\nexport class ConfigError extends PlaymosError {\n  constructor(message: string, detail?: Record<string, unknown>) {\n    super(\"config\", message, detail);\n  }\n}\n"]}

package/dist/errors-B-85VYMv.d.cts

@@ -0,0 +1,224 @@
+/**
+ * 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}`;
+}
+interface AgentEconomyConfig {
+    enabled?: boolean;
+    /** Tax skimmed to Playmos on each agent↔agent transfer. 100 = 1% (default). */
+    taxBps?: number;
+}
+interface PlaymosConfig {
+    /** pk_test_* (sandbox / Base Sepolia) or pk_live_* (production / Base mainnet).
+     *  The key prefix selects the environment. */
+    apiKey: string;
+    /** Override the network derived from the key. Explicit value wins. */
+    network?: Network;
+    wallet?: WalletConfig;
+    gas?: GasConfig;
+    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;
+}
+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>;
+    };
+}
+
+/**
+ * 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 AgentEconomyConfig as A, ConfigError as C, type EnterRoundInput as E, type GasConfig as G, InsufficientGasError as I, MissingFieldError as M, type Network as N, type PlaymosConfig as P, type VerifyResult as V, type WebhookEvent as W, type PayInput as a, type Payment as b, ApiError as c, AuthError as d, type ContractConfig as e, type Eip1193Provider as f, type GasMode as g, InvalidAmountError as h, PaymentFailedError as i, type PaymentStatus as j, PlaymosError as k, type PlaymosErrorCode as l, type WalletConfig as m, WalletConnectionError as n, type WalletConnector as o, type WebhookEventType as p };

package/dist/errors-B-85VYMv.d.ts

@@ -0,0 +1,224 @@
+/**
+ * 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}`;
+}
+interface AgentEconomyConfig {
+    enabled?: boolean;
+    /** Tax skimmed to Playmos on each agent↔agent transfer. 100 = 1% (default). */
+    taxBps?: number;
+}
+interface PlaymosConfig {
+    /** pk_test_* (sandbox / Base Sepolia) or pk_live_* (production / Base mainnet).
+     *  The key prefix selects the environment. */
+    apiKey: string;
+    /** Override the network derived from the key. Explicit value wins. */
+    network?: Network;
+    wallet?: WalletConfig;
+    gas?: GasConfig;
+    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;
+}
+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>;
+    };
+}
+
+/**
+ * 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 AgentEconomyConfig as A, ConfigError as C, type EnterRoundInput as E, type GasConfig as G, InsufficientGasError as I, MissingFieldError as M, type Network as N, type PlaymosConfig as P, type VerifyResult as V, type WebhookEvent as W, type PayInput as a, type Payment as b, ApiError as c, AuthError as d, type ContractConfig as e, type Eip1193Provider as f, type GasMode as g, InvalidAmountError as h, PaymentFailedError as i, type PaymentStatus as j, PlaymosError as k, type PlaymosErrorCode as l, type WalletConfig as m, WalletConnectionError as n, type WalletConnector as o, type WebhookEventType as p };