@playmos/sdk 0.1.6 → 0.2.0

package/dist/errors-CjL85YKR.d.ts

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