@playmos/sdk 0.1.5 → 0.1.6

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 };

package/dist/index.cjs

@@ -1,7 +1,6 @@
 'use strict';
 
 var viem = require('viem');
-var crypto = require('crypto');
 
 // src/errors.ts
 var PlaymosError = class extends Error {
@@ -513,46 +512,6 @@ function mockEntryPayment(args) {
     mock: true
   };
 }
-var WebhookSignatureError = class extends PlaymosError {
-  constructor(message) {
-    super("api_error", `Webhook signature verification failed: ${message}`);
-  }
-};
-function parseHeader(header) {
-  const parts = Object.fromEntries(
-    header.split(",").map((kv) => {
-      const [k, v] = kv.split("=");
-      return [k?.trim(), v?.trim()];
-    })
-  );
-  const t = Number(parts["t"]);
-  const v1 = parts["v1"];
-  if (!Number.isFinite(t) || !v1) throw new WebhookSignatureError("malformed signature header");
-  return { t, v1 };
-}
-function computeSignature(secret, t, rawBody) {
-  return crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
-}
-function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
-  if (!signatureHeader || Array.isArray(signatureHeader)) {
-    throw new WebhookSignatureError("missing signature header");
-  }
-  if (!secret) throw new WebhookSignatureError("missing signing secret");
-  const body = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
-  const { t, v1 } = parseHeader(signatureHeader);
-  const tolerance = opts.toleranceSeconds ?? 300;
-  const nowSec = Math.floor(Date.now() / 1e3);
-  if (Math.abs(nowSec - t) > tolerance) {
-    throw new WebhookSignatureError(`timestamp outside tolerance (${tolerance}s)`);
-  }
-  const expected = computeSignature(secret, t, body);
-  const a = Buffer.from(expected, "hex");
-  const b = Buffer.from(v1, "hex");
-  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
-    throw new WebhookSignatureError("signature mismatch");
-  }
-  return JSON.parse(body);
-}
 
 // src/client.ts
 var IAP_FEE_BPS = 100;
@@ -562,8 +521,17 @@ var RAKE_BPS = 1e3;
 var Playmos = class {
   constructor(config) {
     this.webhooks = {
-      /** Verify a webhook signature and return the parsed event (server-side). */
-      verify: (rawBody, signatureHeader, secret) => verifyWebhook(rawBody, signatureHeader, secret)
+      /**
+       * Webhook verification is server-only (it uses node:crypto) and no longer
+       * ships in the browser entry (issue #9). On a backend, import it directly:
+       *   import { verifyWebhook } from "@playmos/sdk/server";
+       */
+      verify: (_rawBody, _signatureHeader, _secret) => {
+        throw new ConfigError(
+          'playmos.webhooks.verify is server-only and no longer ships in the browser entry (issue #9). Use: import { verifyWebhook } from "@playmos/sdk/server"',
+          { entry: "@playmos/sdk/server" }
+        );
+      }
     };
     this.payouts = {
       /** Choose how the studio is paid: "usdc" (default) or "fiat" (Bridge). */
@@ -840,7 +808,6 @@ exports.PlaymosError = PlaymosError;
 exports.USDC_ADDRESS = USDC_ADDRESS;
 exports.USDC_DECIMALS = USDC_DECIMALS;
 exports.WalletConnectionError = WalletConnectionError;
-exports.WebhookSignatureError = WebhookSignatureError;
 exports.computeIapSplit = computeIapSplit;
 exports.computePoolSplit = computePoolSplit;
 exports.formatMicroToUsd = formatMicroToUsd;
@@ -849,6 +816,5 @@ exports.prefixedId = prefixedId;
 exports.previewIapSplit = previewIapSplit;
 exports.previewPoolSplit = previewPoolSplit;
 exports.ulid = ulid;
-exports.verifyWebhook = verifyWebhook;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map