@playmos/sdk 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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.cjs';
-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.cjs';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as PrizeBalance, d as WithdrawResult, A as AgentWallet, e as AgentFundResult, T as TransferResult, E as EscrowHoldInput, f as EscrowHoldResult, g as EscrowResolveResult, M as MarketplaceListInput, L as Listing, h as MarketplaceSaleResult, i as MarketplaceGetResult, j as PayInput, k as Payment, l as EnterRoundInput, m as TransferReconcile, n as WaitOptions, o as TransferInput, p as TransferConfirmOptions, V as VerifyResult } from './errors-DMtMpbR6.cjs';
+export { q as AgentEconomyConfig, r as ApiError, s as AuthError, C as ConfigError, t as ContractConfig, u as Eip1193Provider, G as GasConfig, v as GasMode, I as InsufficientGasError, w as InvalidAmountError, x as ListingStatus, y as MarketplaceItem, z as MarketplaceSale, B as MissingFieldError, D as NothingToWithdrawError, F as PaymentFailedError, H as PaymentStatus, J as PayoutRule, K as PlaymosError, O as PlaymosErrorCode, Q as RetryOptions, U as RoundStatus, X as WalletConfig, Y as WalletConnectionError, Z as WalletConnector, _ as WebhookEventType } from './errors-DMtMpbR6.cjs';
 
 /**
  * Environment resolution + the canonical address book.
@@ -80,6 +80,30 @@ declare class Playmos {
         get: (input: {
             roundId: string;
         }) => Promise<RoundState>;
+        /**
+         * Read a wallet's **claimable** prize balance for a round (issue #41).
+         * Prefers the service chain read (`GET /v1/rounds/:id/prize?wallet=`); falls
+         * back to a direct eth_call when `prizePoolAddress` is supplied and no wallet
+         * connector is needed for the read path… actually uses service first, then
+         * on-chain via the player's provider if the service is unavailable.
+         */
+        prize: (input: {
+            roundId: string;
+            wallet: `0x${string}`;
+            /** Optional override if you already hold the pool address from enterRound. */
+            prizePoolAddress?: `0x${string}`;
+        }) => Promise<PrizeBalance>;
+        /**
+         * Winner **claim** — call PrizePool.withdraw() from the player's wallet (issue #41).
+         * Pull-payment: credits from settle live in `withdrawable[msg.sender]`. No approve needed.
+         * Pass either `prizePoolAddress` (from enterRound / rounds.get) or `roundId` (service resolves).
+         */
+        withdraw: (input: {
+            prizePoolAddress?: `0x${string}`;
+            roundId?: string;
+            /** Pre-check claimable; default true. Set false only if you already called `prize()`. */
+            checkBalance?: boolean;
+        }) => Promise<WithdrawResult>;
     };
     /**
      * `agents` — assign wallets to the NPCs YOUR game already owns, so they can transact USDC in your economy.
@@ -99,6 +123,7 @@ declare class Playmos {
         fund: (input: {
             agentId: string;
             amount: string;
+            idempotencyKey?: string;
         }) => Promise<AgentFundResult>;
         /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
         pay: (input: {
@@ -194,18 +219,24 @@ declare class Playmos {
     /** 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).
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
+     * `get` reconciles once against chain truth; `wait` polls it to a terminal state
+     * for you (no hand-rolled loop). Both cover the gasless agent path.
      */
     readonly transfers: {
-        get: (transferId: string) => Promise<{
-            id: string;
-            status: string;
-            txHash: string | null;
-            to: string;
-            amount: string;
-            verifiedVia: "chain" | "cache" | "degraded";
-        }>;
+        /** One-shot reconcile of a transfer against chain truth. */
+        get: (transferId: string) => Promise<TransferReconcile>;
+        /**
+         * Block until a transfer reaches a terminal state — `settled` or `failed` —
+         * instead of hand-rolling a poll loop (#47). Polls `transfers.get(id)` every
+         * `intervalMs` (default 1000) until terminal, then RESOLVES with the final
+         * reconcile. Throws a typed `ApiError` (`detail.timeout`) if neither
+         * `timeoutMs` (default 30000) nor `maxAttempts` (default 40) is reached first.
+         *
+         * A `failed` transfer is a legitimate outcome, so it RESOLVES (status
+         * "failed") — inspect `result.status`; it does not throw.
+         */
+        wait: (transferId: string, opts?: WaitOptions) => Promise<TransferReconcile>;
     };
     /**
      * `transfer` — the value-movement base primitive (Phase 1a): move USDC from one wallet to another,
@@ -218,12 +249,13 @@ declare class Playmos {
      * 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>`.
+     * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, either call
+     * `playmos.transfers.wait(id)`, or pass `{ confirm: true }` here to block until terminal in one
+     * call (#47). BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
      *
      * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
      */
-    transfer(input: TransferInput): Promise<TransferResult>;
+    transfer(input: TransferInput, opts?: TransferConfirmOptions): Promise<TransferResult>;
     /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
     verify(paymentId: string): Promise<VerifyResult>;
     /**
@@ -237,6 +269,11 @@ declare class Playmos {
     /** Prefer the service's authoritative micro-USDC amount; fall back to the
      *  locally-parsed value if the service didn't echo one. */
     private resolveUnits;
+    /**
+     * Read PrizePool.withdrawable[wallet] via eth_call (issue #41).
+     * Uses the wallet provider when present; otherwise a public Base Sepolia RPC in test.
+     */
+    private readWithdrawable;
     private sponsorUrl;
     /**
      * After the batch lands, resolve the authoritative status via the service's
@@ -506,4 +543,4 @@ declare function isWalletSignatureAuthorization(auth: Authorization): auth is Wa
 /** 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 };
+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, PrizeBalance, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, WithdrawResult, type X402PayloadAuthorization, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as PrizeBalance, d as WithdrawResult, A as AgentWallet, e as AgentFundResult, T as TransferResult, E as EscrowHoldInput, f as EscrowHoldResult, g as EscrowResolveResult, M as MarketplaceListInput, L as Listing, h as MarketplaceSaleResult, i as MarketplaceGetResult, j as PayInput, k as Payment, l as EnterRoundInput, m as TransferReconcile, n as WaitOptions, o as TransferInput, p as TransferConfirmOptions, V as VerifyResult } from './errors-DMtMpbR6.js';
+export { q as AgentEconomyConfig, r as ApiError, s as AuthError, C as ConfigError, t as ContractConfig, u as Eip1193Provider, G as GasConfig, v as GasMode, I as InsufficientGasError, w as InvalidAmountError, x as ListingStatus, y as MarketplaceItem, z as MarketplaceSale, B as MissingFieldError, D as NothingToWithdrawError, F as PaymentFailedError, H as PaymentStatus, J as PayoutRule, K as PlaymosError, O as PlaymosErrorCode, Q as RetryOptions, U as RoundStatus, X as WalletConfig, Y as WalletConnectionError, Z as WalletConnector, _ as WebhookEventType } from './errors-DMtMpbR6.js';
 
 /**
  * Environment resolution + the canonical address book.
@@ -80,6 +80,30 @@ declare class Playmos {
         get: (input: {
             roundId: string;
         }) => Promise<RoundState>;
+        /**
+         * Read a wallet's **claimable** prize balance for a round (issue #41).
+         * Prefers the service chain read (`GET /v1/rounds/:id/prize?wallet=`); falls
+         * back to a direct eth_call when `prizePoolAddress` is supplied and no wallet
+         * connector is needed for the read path… actually uses service first, then
+         * on-chain via the player's provider if the service is unavailable.
+         */
+        prize: (input: {
+            roundId: string;
+            wallet: `0x${string}`;
+            /** Optional override if you already hold the pool address from enterRound. */
+            prizePoolAddress?: `0x${string}`;
+        }) => Promise<PrizeBalance>;
+        /**
+         * Winner **claim** — call PrizePool.withdraw() from the player's wallet (issue #41).
+         * Pull-payment: credits from settle live in `withdrawable[msg.sender]`. No approve needed.
+         * Pass either `prizePoolAddress` (from enterRound / rounds.get) or `roundId` (service resolves).
+         */
+        withdraw: (input: {
+            prizePoolAddress?: `0x${string}`;
+            roundId?: string;
+            /** Pre-check claimable; default true. Set false only if you already called `prize()`. */
+            checkBalance?: boolean;
+        }) => Promise<WithdrawResult>;
     };
     /**
      * `agents` — assign wallets to the NPCs YOUR game already owns, so they can transact USDC in your economy.
@@ -99,6 +123,7 @@ declare class Playmos {
         fund: (input: {
             agentId: string;
             amount: string;
+            idempotencyKey?: string;
         }) => Promise<AgentFundResult>;
         /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
         pay: (input: {
@@ -194,18 +219,24 @@ declare class Playmos {
     /** 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).
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
+     * `get` reconciles once against chain truth; `wait` polls it to a terminal state
+     * for you (no hand-rolled loop). Both cover the gasless agent path.
      */
     readonly transfers: {
-        get: (transferId: string) => Promise<{
-            id: string;
-            status: string;
-            txHash: string | null;
-            to: string;
-            amount: string;
-            verifiedVia: "chain" | "cache" | "degraded";
-        }>;
+        /** One-shot reconcile of a transfer against chain truth. */
+        get: (transferId: string) => Promise<TransferReconcile>;
+        /**
+         * Block until a transfer reaches a terminal state — `settled` or `failed` —
+         * instead of hand-rolling a poll loop (#47). Polls `transfers.get(id)` every
+         * `intervalMs` (default 1000) until terminal, then RESOLVES with the final
+         * reconcile. Throws a typed `ApiError` (`detail.timeout`) if neither
+         * `timeoutMs` (default 30000) nor `maxAttempts` (default 40) is reached first.
+         *
+         * A `failed` transfer is a legitimate outcome, so it RESOLVES (status
+         * "failed") — inspect `result.status`; it does not throw.
+         */
+        wait: (transferId: string, opts?: WaitOptions) => Promise<TransferReconcile>;
     };
     /**
      * `transfer` — the value-movement base primitive (Phase 1a): move USDC from one wallet to another,
@@ -218,12 +249,13 @@ declare class Playmos {
      * 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>`.
+     * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, either call
+     * `playmos.transfers.wait(id)`, or pass `{ confirm: true }` here to block until terminal in one
+     * call (#47). BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
      *
      * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
      */
-    transfer(input: TransferInput): Promise<TransferResult>;
+    transfer(input: TransferInput, opts?: TransferConfirmOptions): Promise<TransferResult>;
     /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
     verify(paymentId: string): Promise<VerifyResult>;
     /**
@@ -237,6 +269,11 @@ declare class Playmos {
     /** Prefer the service's authoritative micro-USDC amount; fall back to the
      *  locally-parsed value if the service didn't echo one. */
     private resolveUnits;
+    /**
+     * Read PrizePool.withdrawable[wallet] via eth_call (issue #41).
+     * Uses the wallet provider when present; otherwise a public Base Sepolia RPC in test.
+     */
+    private readWithdrawable;
     private sponsorUrl;
     /**
      * After the batch lands, resolve the authoritative status via the service's
@@ -506,4 +543,4 @@ declare function isWalletSignatureAuthorization(auth: Authorization): auth is Wa
 /** 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 };
+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, PrizeBalance, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, WithdrawResult, type X402PayloadAuthorization, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };