@playmos/sdk 0.1.6 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { N as Network, P as PlaymosConfig, W as WebhookEvent, a as PayInput, b as Payment, E as EnterRoundInput, V as VerifyResult } from './errors-B-85VYMv.js';
-export { A as AgentEconomyConfig, c as ApiError, d as AuthError, C as ConfigError, e as ContractConfig, f as Eip1193Provider, G as GasConfig, g as GasMode, I as InsufficientGasError, h as InvalidAmountError, M as MissingFieldError, i as PaymentFailedError, j as PaymentStatus, k as PlaymosError, l as PlaymosErrorCode, m as WalletConfig, n as WalletConnectionError, o as WalletConnector, p as WebhookEventType } from './errors-B-85VYMv.js';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, A as AgentWallet, c as AgentFundResult, T as TransferResult, E as EscrowHoldInput, d as EscrowHoldResult, e as EscrowResolveResult, M as MarketplaceListInput, L as Listing, f as MarketplaceSaleResult, g as MarketplaceGetResult, h as PayInput, i as Payment, j as EnterRoundInput, k as TransferInput, V as VerifyResult } from './errors-CjL85YKR.js';
+export { l as AgentEconomyConfig, m as ApiError, n as AuthError, C as ConfigError, o as ContractConfig, p as Eip1193Provider, G as GasConfig, q as GasMode, I as InsufficientGasError, r as InvalidAmountError, s as ListingStatus, t as MarketplaceItem, u as MarketplaceSale, v as MissingFieldError, w as PaymentFailedError, x as PaymentStatus, y as PayoutRule, z as PlaymosError, B as PlaymosErrorCode, D as RoundStatus, F as WalletConfig, H as WalletConnectionError, J as WalletConnector, K as WebhookEventType } from './errors-CjL85YKR.js';
 
 /**
  * Environment resolution + the canonical address book.
@@ -36,11 +36,18 @@ declare class Playmos {
     readonly config: PlaymosConfig;
     readonly env: ResolvedEnv;
     private readonly http;
+    /**
+     * Webhook helpers. Signature verification is **server-only** (Node `crypto`) and
+     * lives on `@playmos/sdk/server` so browser bundlers never see `node:crypto` (#9).
+     *
+     *   import { verifyWebhook } from "@playmos/sdk/server";
+     *   const event = verifyWebhook(rawBody, req.headers["x-playmos-signature"], secret);
+     */
     readonly webhooks: {
         /**
-         * 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";
+         * @deprecated Use `import { verifyWebhook } from "@playmos/sdk/server"` instead.
+         * Throws if called — kept as a discoverable pointer so call sites fail loudly
+         * with a fix instruction rather than a silent missing method.
          */
         verify: (_rawBody: string | Buffer, _signatureHeader: string | string[] | undefined, _secret: string) => WebhookEvent;
     };
@@ -54,25 +61,104 @@ declare class Playmos {
             url: string;
         }>;
     };
+    /**
+     * Skill/contest **round lifecycle** (issue #13) — closes the enterRound loop.
+     *
+     * Scores never leave the studio. Flow:
+     *   rounds.open → players enterRound → studio scores → rounds.lock →
+     *   rounds.settle({ ranking }) → contract pays winners.
+     *
+     * Operator txs are signed by the Playmos service (OPERATOR_ROLE key).
+     */
+    readonly rounds: {
+        open: (input: RoundOpenInput) => Promise<RoundState>;
+        lock: (input: {
+            roundId: string;
+            gameId?: string;
+        }) => Promise<RoundState>;
+        settle: (input: RoundSettleInput) => Promise<SettleRoundResult>;
+        get: (input: {
+            roundId: string;
+        }) => Promise<RoundState>;
+    };
+    /**
+     * `agents` — assign wallets to the NPCs YOUR game already owns, so they can transact USDC in your economy.
+     * The game creates the NPCs; the SDK only creates the WALLET for a game-supplied id. Engine-agnostic
+     * (Unity/Unreal/Godot/web all call the same REST). Requires a secret test key (`sk_test_`) on the sandbox.
+     */
     readonly agents: {
-        /** Assign a wallet to any identity (incl. an AI NPC). Idempotent by agentId. */
+        /** Assign (or return) the wallet for a game NPC id. Idempotent — safe to call wherever your NPCs spawn. */
         createWallet: (input: {
             agentId: string;
-        }) => Promise<{
+        }) => Promise<AgentWallet>;
+        /** Resolve one NPC's wallet by your id. */
+        wallet: (agentId: string) => Promise<AgentWallet>;
+        /** List the NPC wallets you've assigned in this studio. */
+        list: () => Promise<AgentWallet[]>;
+        /** Sandbox faucet: fund an NPC with USDC from your treasury (per-NPC lifetime cap). */
+        fund: (input: {
             agentId: string;
-            address: `0x${string}`;
-            chain: string;
-        }>;
-        /** Agent↔agent USDC transfer; the configured taxBps is skimmed to Playmos. */
+            amount: string;
+        }) => Promise<AgentFundResult>;
+        /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
         pay: (input: {
             from: string;
             to: string;
             amount: string;
-        }) => Promise<{
-            id: string;
-            taxUSD: string;
-            status: string;
-        }>;
+            feeBps?: number;
+            feeSink?: `0x${string}`;
+        }) => Promise<TransferResult>;
+    };
+    /**
+     * `escrow` — the fair-exchange primitive (Phase 2): lock the payer's USDC on-chain the instant a deal
+     * opens (`hold`), then move it exactly once — `release` (→ payee, fee skimmed) XOR `refund` (→ payer,
+     * 100%). The contract holds the funds trustlessly; YOUR game decides the rule (who resolves, and when).
+     * A `deadline` auto-refund guarantees funds never get stuck. Pass the `hold` result's `id` to the rest.
+     */
+    readonly escrow: {
+        /** Open a deal: lock `amount` of the payer's USDC into the on-chain escrow. Retries are idempotent.
+         *  `async` so client-side validation surfaces as a rejected promise, not a synchronous throw. */
+        hold: (input: EscrowHoldInput) => Promise<EscrowHoldResult>;
+        /** Release a held deal to the payee (fee skimmed). `escrowId` is the `hold` result's `id`. */
+        release: (input: {
+            escrowId: string;
+        }) => Promise<EscrowResolveResult>;
+        /** Refund a held deal to the payer (100%, untaxed). `escrowId` is the `hold` result's `id`. */
+        refund: (input: {
+            escrowId: string;
+        }) => Promise<EscrowResolveResult>;
+        /** Verify a deal's on-chain state (reconciles a `settling` hold wedged by a crash). */
+        get: (escrowId: string) => Promise<EscrowResolveResult>;
+    };
+    /**
+     * `marketplace` — list an item, and the seller is paid ONLY when it's bought (Phase 3a, off-chain items).
+     * Built on `escrow`: `buy` locks the buyer's USDC on-chain, `confirm` (after your game server delivers the
+     * item) pays the seller, and a no-delivery/timeout `refund`s the buyer. `deliver: true` on `buy` collapses
+     * lock+pay into one call when your server delivers synchronously. On-chain items are Phase 3b.
+     */
+    readonly marketplace: {
+        /** List an off-chain item for sale. No money moves. Idempotent on `idempotencyKey`. */
+        list: (input: MarketplaceListInput) => Promise<Listing>;
+        /** Buy a listing: lock the buyer's USDC in escrow. Pass `deliver: true` to also pay the seller in one call. */
+        buy: (input: {
+            listingId: string;
+            buyer?: `0x${string}`;
+            deliver?: boolean;
+        }) => Promise<MarketplaceSaleResult>;
+        /** Confirm delivery → the seller is paid (release), fee skimmed. */
+        confirm: (input: {
+            listingId: string;
+        }) => Promise<MarketplaceSaleResult>;
+        /** Refund the buyer 100% (seller couldn't deliver / dispute / timeout). */
+        refund: (input: {
+            listingId: string;
+        }) => Promise<MarketplaceSaleResult>;
+        /** Delist an unsold listing (pure DB, no tx). */
+        cancel: (input: {
+            listingId: string;
+        }) => Promise<Listing>;
+        /** Fetch a listing + its on-chain-verified sale status. */
+        get: (listingId: string) => Promise<MarketplaceGetResult>;
     };
     constructor(config: PlaymosConfig);
     /** Connect the player's wallet and return their address. */
@@ -107,6 +193,37 @@ declare class Playmos {
     pay(input: PayInput): Promise<Payment>;
     /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
     enterRound(input: EnterRoundInput): Promise<Payment>;
+    /**
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issue #27).
+     * Poll when POST returned `status: "settling"`; reconciles against chain (incl. gasless agent path).
+     */
+    readonly transfers: {
+        get: (transferId: string) => Promise<{
+            id: string;
+            status: string;
+            txHash: string | null;
+            to: string;
+            amount: string;
+            verifiedVia: "chain" | "cache" | "degraded";
+        }>;
+    };
+    /**
+     * `transfer` — the value-movement base primitive (Phase 1a): move USDC from one wallet to another,
+     * with a per-call fee. The GAME LOGIC is the authority — you already decided the move is valid — so
+     * this is a direct, unconditional push (use `escrow`/`marketplace` when a trust boundary needs fair
+     * exchange). The service settles it through the protocol-agnostic settlement core (idempotent,
+     * reserve-before-broadcast) and the on-chain PlaymosTransfer / PlaymosTransferAuth contracts.
+     *
+     * Fee is per-call: `feeBps` 0–10000 (+ `feeSink`). `feeBps: 0` is an untaxed reward/faucet transfer.
+     * Retries are safe: pass the same `idempotencyKey` and a re-call NEVER broadcasts a second tx —
+     * it returns the cached result (`idempotentReplay: true`).
+     *
+     * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, call
+     * `playmos.transfers.get(id)` until settled/failed. BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
+     *
+     * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
+     */
+    transfer(input: TransferInput): Promise<TransferResult>;
     /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
     verify(paymentId: string): Promise<VerifyResult>;
     /**
@@ -133,6 +250,37 @@ declare function previewIapSplit(amount: string): {
     fee: string;
     net: string;
 };
+/**
+ * Local preview of a `transfer` fee split without any network — handy for UIs and quotes. Mirrors the
+ * on-chain floor math: `fee = floor(amount * feeBps / 10000)`, `net = amount − fee` (dust → payee).
+ */
+declare function previewTransferSplit(amount: string, feeBps: number): {
+    amount: string;
+    fee: string;
+    net: string;
+    feeBps: number;
+};
+/**
+ * Local preview of what an escrow `release` would pay out, without any network. Mirrors the on-chain
+ * floor math: `fee = floor(amount * feeBps / 10000)`, `net = amount − fee` (dust → payee). A `refund`
+ * returns the full `amount` with no fee, so it needs no preview.
+ */
+declare function previewEscrowFee(amount: string, feeBps: number): {
+    amount: string;
+    fee: string;
+    net: string;
+    feeBps: number;
+};
+/**
+ * Local preview of a marketplace sale's payout, without any network. Mirrors the on-chain floor math
+ * (`fee = floor(price * feeBps / 10000)`, `net = price − fee`, dust → seller). A no-sale/refund pays 0.
+ */
+declare function previewMarketplaceSplit(price: string, feeBps: number): {
+    price: string;
+    fee: string;
+    net: string;
+    feeBps: number;
+};
 /** Local preview of the 60/30/10 entry split without any network. */
 declare function previewPoolSplit(amount: string): {
     amount: string;
@@ -141,6 +289,40 @@ declare function previewPoolSplit(amount: string): {
     rake: string;
 };
 
+/**
+ * payout.ts — pure payout math for skill/contest settlement (issue #13).
+ *
+ * Scores NEVER enter this module. The studio ranks wallets (best-first) from its
+ * own leaderboard; we only turn that ranking + a payout rule into integer USDC
+ * base-unit amounts that sum EXACTLY to the payable pool.
+ *
+ * No network, no chain — fully unit-testable.
+ */
+type PayoutRule = {
+    kind: "winner-take-all";
+} | {
+    kind: "top-n";
+    splitsBps: number[];
+} | {
+    kind: "custom";
+    amounts: string[];
+};
+declare class PayoutError extends Error {
+    code: "payout_invalid";
+    constructor(message: string);
+}
+/**
+ * Apply the studio's payout rule to a payable pool and ranking (best-first).
+ *
+ * - Integer math only (bigint micro-USDC).
+ * - Sum of amounts == pool exactly; any remainder from floor division goes to rank 1.
+ * - Rejects empty ranking, bad splits, more winners than ranking, zero pool.
+ */
+declare function computePayout(pool: bigint, ranking: `0x${string}`[], rule: PayoutRule): {
+    wallet: `0x${string}`;
+    amount: bigint;
+}[];
+
 /**
  * Money math — exact, integer-only, in USDC micro-units (6 decimals).
  *
@@ -196,4 +378,132 @@ declare function ulid(seedTime?: number): string;
 /** `${prefix}_${ulid()}` — e.g. `pay_01J…`, `entry_01J…`, `idem_01J…`. */
 declare function prefixedId(prefix: string): string;
 
-export { CHAIN_ID, DEFAULT_API_BASE_URL, EnterRoundInput, MICRO_PER_USDC, Network, PayInput, Payment, Playmos, PlaymosConfig, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WebhookEvent, computeIapSplit, computePoolSplit, formatMicroToUsd, parseUsdToMicro, prefixedId, previewIapSplit, previewPoolSplit, ulid };
+/**
+ * settlement.ts — the x402-ready settlement CORE contract (Phase 0).
+ *
+ * Two shared shapes every value-movement primitive (`transfer`, `escrow`,
+ * `marketplace`) AND the future x402 adapter build on. The whole point of
+ * naming them now is that x402 later becomes a thin HTTP-402 adapter with zero
+ * rework — see `docs/design/transfer-escrow-marketplace-spec.md` §"Architecture:
+ * x402-ready by design".
+ *
+ *   PaymentRequirement — WHAT must be paid. A plain, JSON-safe object. A direct
+ *     SDK call creates one and satisfies it immediately; an x402 "402 Payment
+ *     Required" challenge is literally this object serialized onto the wire. So
+ *     it is designed to round-trip to/from an HTTP 402 body with zero loss —
+ *     `parsePaymentRequirement(serializePaymentRequirement(req))` is `req`.
+ *
+ *   Authorization — HOW a settlement is authorized. A discriminated union so the
+ *     settlement core never bakes in "direct SDK signature": today a
+ *     `wallet-signature` (implemented), tomorrow an `x402-payload` (declared,
+ *     not settled yet). This union is the seam that keeps x402 out of the core.
+ *
+ * Nothing here touches the network or the chain — these are the shared data
+ * shapes the SDK produces and the service's protocol-agnostic settlement core
+ * consumes.
+ */
+
+/** The only settlement asset in V1. Named so an x402 challenge carries it verbatim. */
+type SettlementAsset = "USDC";
+/**
+ * The shared payment contract — WHAT must be paid, independent of HOW it was
+ * requested (direct SDK call today, x402 challenge tomorrow).
+ *
+ * Every field is a JSON primitive so the object is byte-stable across an HTTP
+ * 402 body: mint it once, and both the direct path and the x402 path settle the
+ * exact same requirement, idempotent on `id`.
+ */
+interface PaymentRequirement {
+    /** The anchor id (`preq_<ulid>`). Settlement idempotency key + x402 challenge id. */
+    id: string;
+    /** The recipient wallet (the payee). Checksummed or lowercase 0x-address. */
+    payTo: `0x${string}`;
+    /** USD decimal string ("5.00") — same money convention as `pay()`/`enterRound()`. */
+    amount: string;
+    /** Only USDC in V1. */
+    asset: SettlementAsset;
+    /** Which chain settles this requirement. */
+    network: Network;
+    /** Optional free-form terms/memo, echoed on the receipt and in the 402 body. */
+    terms?: string;
+    /** ISO-8601 expiry. A challenge/authorization presented after this is rejected. */
+    expiresAt: string;
+}
+interface CreatePaymentRequirementInput {
+    /** Recipient wallet. */
+    payTo: `0x${string}`;
+    /** USD decimal string ("5.00"). */
+    amount: string;
+    /** Settlement chain. */
+    network: Network;
+    /** Defaults to "USDC". */
+    asset?: SettlementAsset;
+    /** Optional terms/memo. */
+    terms?: string;
+    /** Absolute ISO expiry. Overrides `expiresInMs`. Defaults to now + 15 min. */
+    expiresAt?: string;
+    /** Relative TTL from now, in ms. Ignored if `expiresAt` is set. */
+    expiresInMs?: number;
+    /** Supply for a deterministic id (e.g. to reuse an upstream id); else a `preq_<ulid>` is minted. */
+    id?: string;
+    /** Injectable clock for deterministic tests. */
+    now?: () => Date;
+}
+/**
+ * Build a validated {@link PaymentRequirement}. This is the single producer the
+ * direct primitives (`transfer`/`escrow`/`marketplace`) and — later — the x402
+ * adapter both call, so every requirement on the wire is shaped identically.
+ * Pure: no network, no chain, no id collisions (monotonic ULID).
+ */
+declare function createPaymentRequirement(input: CreatePaymentRequirementInput): PaymentRequirement;
+/**
+ * Serialize a requirement to a plain, JSON-safe object — the exact body an x402
+ * "402 Payment Required" response carries. Undefined optionals are omitted so
+ * the shape is stable across `JSON.stringify` → `JSON.parse` → re-parse.
+ */
+declare function serializePaymentRequirement(req: PaymentRequirement): Record<string, unknown>;
+/**
+ * Parse + validate an untrusted object (an HTTP 402 body, a queue message, a
+ * direct call) back into a {@link PaymentRequirement}. This is the exact decoder
+ * the x402 adapter reuses — it must reject anything malformed with a typed error.
+ */
+declare function parsePaymentRequirement(input: unknown): PaymentRequirement;
+/**
+ * A settlement authorized by a wallet — the ONLY variant implemented in Phase 0.
+ * Covers both signer models the primitives support:
+ *   - server-held NPC/agent wallets (the service signs) and
+ *   - player Base Accounts (the client signs) —
+ * carrying either the settlement `txHash` the client already broadcast, or a
+ * `signature` + `payload` (e.g. EIP-3009 / EIP-5792 batch params) the service
+ * submits. Phase 0 only READS `txHash`; the signed-submit path lands in Phase 1.
+ */
+interface WalletSignatureAuthorization {
+    kind: "wallet-signature";
+    /** The wallet that authorized the move (payer / signer). */
+    from: `0x${string}`;
+    /** A settlement tx the client already broadcast (client-signed path). */
+    txHash?: `0x${string}`;
+    /** An off-chain signature the service submits on the payer's behalf. */
+    signature?: `0x${string}`;
+    /** Opaque protocol-specific authorization data (EIP-5792 calls, EIP-3009, …). */
+    payload?: Record<string, unknown>;
+}
+/**
+ * A settlement authorized by an x402 payment payload (the `X-PAYMENT` header).
+ * DECLARED for the Phase 4 HTTP-402 adapter so the core's type surface is final
+ * now — but NOT settled in Phase 0: `settle()` throws a clear "not implemented
+ * yet" for this variant. This is the seam that keeps x402 out of the core.
+ */
+interface X402PayloadAuthorization {
+    kind: "x402-payload";
+    /** The raw, opaque x402 payment payload decoded from the request. */
+    payload: Record<string, unknown>;
+}
+/** How a settlement is authorized — protocol-agnostic by construction. */
+type Authorization = WalletSignatureAuthorization | X402PayloadAuthorization;
+/** Narrow to the implemented wallet-signature variant. */
+declare function isWalletSignatureAuthorization(auth: Authorization): auth is WalletSignatureAuthorization;
+/** Narrow to the declared-but-unimplemented x402 variant. */
+declare function isX402PayloadAuthorization(auth: Authorization): auth is X402PayloadAuthorization;
+
+export { AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, type PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferInput, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, type WalletSignatureAuthorization, WebhookEvent, type X402PayloadAuthorization, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };