@playmos/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,383 @@
+/**
+ * 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>;
+}
+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>;
+    /** 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>;
+    };
+}
+
+/**
+ * Environment resolution + the canonical address book.
+ *
+ * The API key prefix selects the environment (Stripe's ergonomic): pk_test_* →
+ * Base Sepolia + the sandbox service; pk_live_* → Base mainnet + production. An
+ * explicit `network` override always wins.
+ */
+
+declare const CHAIN_ID: Record<Network, number>;
+/**
+ * Circle USDC. Sepolia value fixes #336 (the vendored SDK shipped 0x0 here).
+ * Verified against the game-hub deploy scripts + kit config.
+ */
+declare const USDC_ADDRESS: Record<Network, `0x${string}`>;
+declare const DEFAULT_API_BASE_URL: Record<Network, string>;
+interface ResolvedEnv {
+    network: Network;
+    chainId: number;
+    apiBaseUrl: string;
+    isTest: boolean;
+}
+
+/**
+ * The Playmos client — `new Playmos({ apiKey })` → `pay()`, `enterRound()`,
+ * `verify()`, `webhooks`, `payouts`, `agents`.
+ *
+ * Real behavior, no `"mocked"` status anywhere. The chain calls use the proven
+ * EIP-5792 approve+call batch; `verify()` resolves by the service's on-chain
+ * read; ids are ULIDs; inputs are validated client-side; idempotency is honored.
+ */
+
+declare class Playmos {
+    readonly config: PlaymosConfig;
+    readonly env: ResolvedEnv;
+    private readonly http;
+    readonly webhooks: {
+        /** Verify a webhook signature and return the parsed event (server-side). */
+        verify: (rawBody: string | Buffer, signatureHeader: string | string[] | undefined, secret: string) => WebhookEvent;
+    };
+    readonly payouts: {
+        /** Choose how the studio is paid: "usdc" (default) or "fiat" (Bridge). */
+        setMode: (mode: "usdc" | "fiat") => Promise<{
+            mode: "usdc" | "fiat";
+        }>;
+        /** Create a Bridge KYC onboarding link (fiat payout). */
+        createOnboardingLink: () => Promise<{
+            url: string;
+        }>;
+    };
+    readonly agents: {
+        /** Assign a wallet to any identity (incl. an AI NPC). Idempotent by agentId. */
+        createWallet: (input: {
+            agentId: string;
+        }) => Promise<{
+            agentId: string;
+            address: `0x${string}`;
+            chain: string;
+        }>;
+        /** Agent↔agent USDC transfer; the configured taxBps is skimmed to Playmos. */
+        pay: (input: {
+            from: string;
+            to: string;
+            amount: string;
+        }) => Promise<{
+            id: string;
+            taxUSD: string;
+            status: string;
+        }>;
+    };
+    constructor(config: PlaymosConfig);
+    /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
+    pay(input: PayInput): Promise<Payment>;
+    /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
+    enterRound(input: EnterRoundInput): Promise<Payment>;
+    /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
+    verify(paymentId: string): Promise<VerifyResult>;
+    /** Prefer the service's authoritative micro-USDC amount; fall back to the
+     *  locally-parsed value if the service didn't echo one. */
+    private resolveUnits;
+    private sponsorUrl;
+    /**
+     * After the batch lands, resolve the authoritative status via the service's
+     * on-chain read. Polls briefly; returns the merged Payment with the real txHash.
+     */
+    private settle;
+}
+/** Local preview of a split without any network — handy for UIs. */
+declare function previewIapSplit(amount: string): {
+    amount: string;
+    fee: string;
+    net: string;
+};
+/** Local preview of the 60/30/10 entry split without any network. */
+declare function previewPoolSplit(amount: string): {
+    amount: string;
+    pool: string;
+    seed: string;
+    rake: 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>);
+}
+
+/**
+ * Webhook signature verification (spec §6.2) — server-side only.
+ *
+ * Signature scheme (mirrors the Playmos service byte-for-byte):
+ *   header `X-Playmos-Signature: t=<unixSeconds>,v1=<hex>`
+ *   where <hex> = HMAC_SHA256(secret, `${t}.${rawBody}`)
+ *
+ * Verify BEFORE trusting an event. Uses node:crypto (constant-time compare) and
+ * rejects stale timestamps to blunt replay. Throws on any mismatch.
+ */
+
+declare class WebhookSignatureError extends PlaymosError {
+    constructor(message: string);
+}
+/**
+ * Verify a webhook and return the parsed event. `rawBody` MUST be the exact raw
+ * request bytes (use express.raw / fastify rawBody) — a re-serialized JSON body
+ * will not match the signature.
+ */
+declare function verifyWebhook(rawBody: string | Buffer, signatureHeader: string | string[] | undefined, secret: string, opts?: {
+    toleranceSeconds?: number;
+}): WebhookEvent;
+
+/**
+ * Money math — exact, integer-only, in USDC micro-units (6 decimals).
+ *
+ * USD amounts are decimal strings ("4.99") to avoid float corruption. Internally
+ * every value is a BigInt count of micro-USDC (1 USDC = 1_000_000 micro), so the
+ * split is bit-exact and always sums back to the input — no wei is ever lost.
+ *
+ * The split arithmetic MIRRORS the contracts (floor division, exactly like
+ * Solidity `amount * bps / 10000`), so the SDK receipt matches what settles
+ * on-chain. The contract remains the source of truth; these numbers are the
+ * faithful preview.
+ */
+declare const USDC_DECIMALS = 6;
+declare const MICRO_PER_USDC = 1000000n;
+/**
+ * Parse a USD decimal string (≤ 2 dp, > 0) into micro-USDC.
+ * Throws {@link InvalidAmountError} on anything that isn't a clean positive price.
+ */
+declare function parseUsdToMicro(amount: string): bigint;
+/**
+ * Format micro-USDC back to a USD decimal string. Keeps full precision (up to 6
+ * dp) but trims trailing zeros to a minimum of 2 dp — so "$4.99" stays "4.99"
+ * while a 1% fee of $4.99 renders its exact "0.0499", not a lossy "0.05".
+ */
+declare function formatMicroToUsd(micro: bigint): string;
+/** External-studio IAP split (99/1 by default). Floor-matches `PlaymosPay.pay`. */
+declare function computeIapSplit(amountMicro: bigint, feeBps: number): {
+    feeMicro: bigint;
+    netMicro: bigint;
+};
+/**
+ * Skill-game prize-pool split (60/30/10 by default). Floor-matches the on-chain
+ * `EconomyConfig`. Any 1–2 micro rounding remainder is assigned to the pool so
+ * the three parts sum EXACTLY to the entry (invariant asserted below).
+ */
+declare function computePoolSplit(amountMicro: bigint, poolBps: number, seedBps: number, rakeBps: number): {
+    poolMicro: bigint;
+    seedMicro: bigint;
+    rakeMicro: bigint;
+};
+
+/**
+ * ULID generation (fixes #341/C — the `pay_mock_${Date.now()}` collision bug).
+ *
+ * A ULID is a 26-char Crockford-base32 string: 48 bits of millisecond timestamp
+ * (lexicographically sortable) + 80 bits of cryptographic randomness. Within the
+ * same millisecond we increment the random component monotonically, so even 50+
+ * ids minted in a tight loop are unique and ordered. Uses Web Crypto
+ * (`crypto.getRandomValues`), available in browsers and Node ≥ 18.
+ */
+/** Generate a monotonic ULID (26 chars, uppercase Crockford base32). */
+declare function ulid(seedTime?: number): string;
+/** `${prefix}_${ulid()}` — e.g. `pay_01J…`, `entry_01J…`, `idem_01J…`. */
+declare function prefixedId(prefix: string): string;
+
+export { type AgentEconomyConfig, ApiError, AuthError, CHAIN_ID, ConfigError, type ContractConfig, DEFAULT_API_BASE_URL, type Eip1193Provider, type EnterRoundInput, type GasConfig, type GasMode, InsufficientGasError, InvalidAmountError, MICRO_PER_USDC, MissingFieldError, type Network, type PayInput, type Payment, PaymentFailedError, type PaymentStatus, Playmos, type PlaymosConfig, PlaymosError, type PlaymosErrorCode, USDC_ADDRESS, USDC_DECIMALS, type VerifyResult, type WalletConfig, WalletConnectionError, type WalletConnector, type WebhookEvent, type WebhookEventType, WebhookSignatureError, computeIapSplit, computePoolSplit, formatMicroToUsd, parseUsdToMicro, prefixedId, previewIapSplit, previewPoolSplit, ulid, verifyWebhook };