@playmos/sdk 0.3.3 → 0.3.5

package/README.md

@@ -4,6 +4,21 @@
 
 Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-game prize-pool entries (10%, 60/30/10), and **in-game economies** (player · NPC · agent commerce via `transfer()`). USD in, USDC on-chain — no crypto UX for your players.
 
+
+## Local `file:` / monorepo install
+
+`@playmos/sdk` ships **built `dist/`**. `prepare` / `prepack` / `prepublishOnly` run
+`scripts/ensure-build.cjs`, which rebuilds `dist/` via local `tsup` or (on a cold
+`file:` install with no `sdk/node_modules`) `npx --yes tsup@8.3.0`:
+
+- `npm install` inside `sdk/`
+- `npm install` of a **`file:`** / git dependency (dogfood monorepos)
+- `npm publish` / pack
+
+So wiping `dist/` then `npm i file:…/sdk` still yields a current build (#211).
+CI also fails if committed `dist/` drifts from source.
+
+
 ## Install
 
 ```bash

package/dist/{chunk-TMBBEGIF.js → chunk-VYR6BBHF.js}

@@ -67,5 +67,3 @@ var NothingToWithdrawError = class extends PlaymosError {
 };
 
 export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError };
-//# sourceMappingURL=chunk-TMBBEGIF.js.map
-//# sourceMappingURL=chunk-TMBBEGIF.js.map

package/dist/{errors-DMtMpbR6.d.cts → errors-CdVzHuhY.d.cts}

@@ -76,7 +76,7 @@ interface PlaymosConfig {
 }
 /** Tuning for the automatic 429 retry (all optional; sane defaults). */
 interface RetryOptions {
-    /** Max automatic retries on HTTP 429. `0` disables retrying entirely. Default 2. */
+    /** Max automatic retries on HTTP 429. `0` disables retrying entirely. Default 2 (→ up to 3 attempts). */
     maxRetries?: number;
     /** Base backoff in ms; the wait grows exponentially per attempt (2^n). Default 500. */
     baseDelayMs?: number;
@@ -144,10 +144,11 @@ interface EnterRoundInput {
     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").
+     * Exact on-chain round key for Path B / entryProvider (#201 / #204 / #210).
+     * First-class for **fixed pins** (`bmtest:T1`, `bjtest:T1`) and **rolling**
+     * windows (`2026-07-15T18:00:T1`). Must match what the hub verifies via
+     * `hasEntered`. When set, this is sent as the payment roundId on create-intent
+     * and server-settle so on-chain enter + receipt agree.
      */
     roundKey?: string;
     /**
@@ -457,7 +458,11 @@ type PayoutRule = {
     kind: "custom";
     amounts: string[];
 };
-type RoundStatus = "open" | "locked" | "settled" | "cancelled" | "none";
+/**
+ * `opening` = open tx broadcast (#344).
+ * `cancelling` = cancel tx broadcast (#346) — refunds entrants, frees series latch.
+ */
+type RoundStatus = "opening" | "open" | "locked" | "settled" | "cancelling" | "cancelled" | "none";
 interface RoundOpenInput {
     gameId: string;
     /** Studio-facing round id (also used as the on-chain round key unless roundKey set). */
@@ -470,13 +475,22 @@ interface RoundOpenInput {
     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). */
+    /**
+     * Exact on-chain round key string (default = roundId).
+     * First-class for fixed pins (`bmtest:T1`, `bjtest:T1`) and rolling windows
+     * (`2026-07-15T18:00:T1`) — Path B / entryProvider (#201 / #210).
+     */
     roundKey?: string;
 }
 interface RoundState {
     roundId: string;
     gameId: string;
     roundKey: string;
+    /**
+     * Series latch key for the 60/30/10 flywheel (#351). Required for
+     * `rounds.activeForSeries` under mock — open must persist it (not discard).
+     */
+    seriesKey?: string;
     status: RoundStatus;
     entryAmount: string;
     /** Payable pool in USD from chain after reconcile; **`null` until reconciled** (never a fabricated "0.00"). Issue #42. */
@@ -488,12 +502,44 @@ interface RoundState {
     openTxHash?: `0x${string}`;
     lockTxHash?: `0x${string}`;
     settleTxHash?: `0x${string}`;
+    /** PrizePool.cancel broadcast hash (#346). */
+    cancelTxHash?: `0x${string}`;
     /**
      * PrizePool contract for this round's game (issue #41). Needed to claim winnings.
      * `null` only if the game has no contract address configured.
      */
     prizePoolAddress?: `0x${string}` | null;
 }
+/**
+ * Active series latch from `GET /v1/series/:seriesKey/active` (#351).
+ * `null` from `activeForSeries` is a **proof of free**, not a failed probe.
+ */
+interface ActiveSeriesRound {
+    roundId: string | null;
+    roundKey: string | null;
+    roundIdHash: `0x${string}`;
+    status: RoundStatus | "opening" | "cancelling";
+    /** null if unreconciled — never fabricate 0 */
+    entrants: number | null;
+    /** null unless Locked/Settled */
+    pool: string | null;
+    openTxHash?: string | null;
+    cancelTxHash?: string | null;
+    prizePoolAddress: `0x${string}`;
+}
+interface ActiveForSeriesResult {
+    series: string;
+    via: "chain" | "cache";
+    active: ActiveSeriesRound | null;
+}
+/** Result of `playmos.rounds.cancel` — may be async 202 cancelling (#346). */
+interface CancelRoundResult {
+    roundId: string;
+    txHash: `0x${string}` | null;
+    /** `"cancelling"` = broadcast accepted; `"cancelled"` = chain Cancelled(4) finalized. */
+    status: "cancelling" | "cancelled";
+    round?: RoundState;
+}
 /** What `rounds.prize({ … })` returns — claimable pull-payment balance (issue #41). */
 interface PrizeBalance {
     roundId: string;
@@ -528,15 +574,26 @@ interface RoundSettleInput {
         }[];
     };
 }
+/**
+ * Result of `playmos.rounds.settle`.
+ *
+ * After #339 / async settle: the service may return **`status: "settling"`** with a
+ * broadcast `txHash` (HTTP 202) — the receipt is **not** awaited in the request.
+ * Treat settle as **submit-only** when `status === "settling"`; poll
+ * `playmos.rounds.get` / on-chain inspect until `status === "settled"` (or call
+ * settle again to reconcile). `status: "settled"` remains the terminal success shape.
+ */
 interface SettleRoundResult {
     roundId: string;
-    txHash: `0x${string}`;
-    poolPaid: string;
-    winners: {
+    txHash: `0x${string}` | null;
+    /** Present when settled (or echoed from the submit body); may be omitted while settling. */
+    poolPaid?: string | null;
+    winners?: {
         wallet: `0x${string}`;
         amount: string;
     }[];
-    status: "settled";
+    /** `"settling"` = broadcast accepted, confirmation pending; `"settled"` = finalized. */
+    status: "settled" | "settling";
 }
 
 /**
@@ -593,4 +650,4 @@ declare class NothingToWithdrawError extends PlaymosError {
     constructor(detail?: Record<string, unknown>);
 }
 
-export { type AgentWallet as A, MissingFieldError as B, ConfigError as C, NothingToWithdrawError as D, type EscrowHoldInput as E, PaymentFailedError as F, type GasConfig as G, type PaymentStatus as H, InsufficientGasError as I, type PayoutRule as J, PlaymosError as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type PlaymosErrorCode as O, type PlaymosConfig as P, type RetryOptions as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type RoundStatus as U, type VerifyResult as V, type WebhookEvent as W, type WalletConfig as X, WalletConnectionError as Y, type WalletConnector as Z, type WebhookEventType as _, type RoundState as a, type RoundSettleInput as b, type PrizeBalance as c, type WithdrawResult as d, type AgentFundResult as e, type EscrowHoldResult as f, type EscrowResolveResult as g, type MarketplaceSaleResult as h, type MarketplaceGetResult as i, type PayInput as j, type Payment as k, type EnterRoundInput as l, type TransferReconcile as m, type WaitOptions as n, type TransferInput as o, type TransferConfirmOptions as p, type AgentEconomyConfig as q, ApiError as r, AuthError as s, type ContractConfig as t, type Eip1193Provider as u, type GasMode as v, InvalidAmountError as w, type ListingStatus as x, type MarketplaceItem as y, type MarketplaceSale as z };
+export { WalletConnectionError as $, type ActiveSeriesRound as A, InvalidAmountError as B, type CancelRoundResult as C, type ListingStatus as D, type EscrowHoldInput as E, type MarketplaceItem as F, type GasConfig as G, type MarketplaceSale as H, InsufficientGasError as I, MissingFieldError as J, NothingToWithdrawError as K, type Listing as L, type MarketplaceListInput as M, type Network as N, PaymentFailedError as O, type PlaymosConfig as P, type PaymentStatus as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, PlaymosError as U, type VerifyResult as V, type WebhookEvent as W, type PlaymosErrorCode as X, type RetryOptions as Y, type RoundStatus as Z, type WalletConfig as _, type RoundState as a, type WalletConnector as a0, type WebhookEventType as a1, type RoundSettleInput as b, type PrizeBalance as c, type WithdrawResult as d, type AgentWallet as e, type AgentFundResult as f, type EscrowHoldResult as g, type EscrowResolveResult as h, type MarketplaceSaleResult as i, type MarketplaceGetResult as j, type PayInput as k, type Payment as l, type EnterRoundInput as m, type TransferReconcile as n, type WaitOptions as o, type TransferInput as p, type TransferConfirmOptions as q, type PayoutRule as r, type ActiveForSeriesResult as s, type AgentEconomyConfig as t, ApiError as u, AuthError as v, ConfigError as w, type ContractConfig as x, type Eip1193Provider as y, type GasMode as z };

package/dist/{errors-DMtMpbR6.d.ts → errors-CdVzHuhY.d.ts}

@@ -76,7 +76,7 @@ interface PlaymosConfig {
 }
 /** Tuning for the automatic 429 retry (all optional; sane defaults). */
 interface RetryOptions {
-    /** Max automatic retries on HTTP 429. `0` disables retrying entirely. Default 2. */
+    /** Max automatic retries on HTTP 429. `0` disables retrying entirely. Default 2 (→ up to 3 attempts). */
     maxRetries?: number;
     /** Base backoff in ms; the wait grows exponentially per attempt (2^n). Default 500. */
     baseDelayMs?: number;
@@ -144,10 +144,11 @@ interface EnterRoundInput {
     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").
+     * Exact on-chain round key for Path B / entryProvider (#201 / #204 / #210).
+     * First-class for **fixed pins** (`bmtest:T1`, `bjtest:T1`) and **rolling**
+     * windows (`2026-07-15T18:00:T1`). Must match what the hub verifies via
+     * `hasEntered`. When set, this is sent as the payment roundId on create-intent
+     * and server-settle so on-chain enter + receipt agree.
      */
     roundKey?: string;
     /**
@@ -457,7 +458,11 @@ type PayoutRule = {
     kind: "custom";
     amounts: string[];
 };
-type RoundStatus = "open" | "locked" | "settled" | "cancelled" | "none";
+/**
+ * `opening` = open tx broadcast (#344).
+ * `cancelling` = cancel tx broadcast (#346) — refunds entrants, frees series latch.
+ */
+type RoundStatus = "opening" | "open" | "locked" | "settled" | "cancelling" | "cancelled" | "none";
 interface RoundOpenInput {
     gameId: string;
     /** Studio-facing round id (also used as the on-chain round key unless roundKey set). */
@@ -470,13 +475,22 @@ interface RoundOpenInput {
     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). */
+    /**
+     * Exact on-chain round key string (default = roundId).
+     * First-class for fixed pins (`bmtest:T1`, `bjtest:T1`) and rolling windows
+     * (`2026-07-15T18:00:T1`) — Path B / entryProvider (#201 / #210).
+     */
     roundKey?: string;
 }
 interface RoundState {
     roundId: string;
     gameId: string;
     roundKey: string;
+    /**
+     * Series latch key for the 60/30/10 flywheel (#351). Required for
+     * `rounds.activeForSeries` under mock — open must persist it (not discard).
+     */
+    seriesKey?: string;
     status: RoundStatus;
     entryAmount: string;
     /** Payable pool in USD from chain after reconcile; **`null` until reconciled** (never a fabricated "0.00"). Issue #42. */
@@ -488,12 +502,44 @@ interface RoundState {
     openTxHash?: `0x${string}`;
     lockTxHash?: `0x${string}`;
     settleTxHash?: `0x${string}`;
+    /** PrizePool.cancel broadcast hash (#346). */
+    cancelTxHash?: `0x${string}`;
     /**
      * PrizePool contract for this round's game (issue #41). Needed to claim winnings.
      * `null` only if the game has no contract address configured.
      */
     prizePoolAddress?: `0x${string}` | null;
 }
+/**
+ * Active series latch from `GET /v1/series/:seriesKey/active` (#351).
+ * `null` from `activeForSeries` is a **proof of free**, not a failed probe.
+ */
+interface ActiveSeriesRound {
+    roundId: string | null;
+    roundKey: string | null;
+    roundIdHash: `0x${string}`;
+    status: RoundStatus | "opening" | "cancelling";
+    /** null if unreconciled — never fabricate 0 */
+    entrants: number | null;
+    /** null unless Locked/Settled */
+    pool: string | null;
+    openTxHash?: string | null;
+    cancelTxHash?: string | null;
+    prizePoolAddress: `0x${string}`;
+}
+interface ActiveForSeriesResult {
+    series: string;
+    via: "chain" | "cache";
+    active: ActiveSeriesRound | null;
+}
+/** Result of `playmos.rounds.cancel` — may be async 202 cancelling (#346). */
+interface CancelRoundResult {
+    roundId: string;
+    txHash: `0x${string}` | null;
+    /** `"cancelling"` = broadcast accepted; `"cancelled"` = chain Cancelled(4) finalized. */
+    status: "cancelling" | "cancelled";
+    round?: RoundState;
+}
 /** What `rounds.prize({ … })` returns — claimable pull-payment balance (issue #41). */
 interface PrizeBalance {
     roundId: string;
@@ -528,15 +574,26 @@ interface RoundSettleInput {
         }[];
     };
 }
+/**
+ * Result of `playmos.rounds.settle`.
+ *
+ * After #339 / async settle: the service may return **`status: "settling"`** with a
+ * broadcast `txHash` (HTTP 202) — the receipt is **not** awaited in the request.
+ * Treat settle as **submit-only** when `status === "settling"`; poll
+ * `playmos.rounds.get` / on-chain inspect until `status === "settled"` (or call
+ * settle again to reconcile). `status: "settled"` remains the terminal success shape.
+ */
 interface SettleRoundResult {
     roundId: string;
-    txHash: `0x${string}`;
-    poolPaid: string;
-    winners: {
+    txHash: `0x${string}` | null;
+    /** Present when settled (or echoed from the submit body); may be omitted while settling. */
+    poolPaid?: string | null;
+    winners?: {
         wallet: `0x${string}`;
         amount: string;
     }[];
-    status: "settled";
+    /** `"settling"` = broadcast accepted, confirmation pending; `"settled"` = finalized. */
+    status: "settled" | "settling";
 }
 
 /**
@@ -593,4 +650,4 @@ declare class NothingToWithdrawError extends PlaymosError {
     constructor(detail?: Record<string, unknown>);
 }
 
-export { type AgentWallet as A, MissingFieldError as B, ConfigError as C, NothingToWithdrawError as D, type EscrowHoldInput as E, PaymentFailedError as F, type GasConfig as G, type PaymentStatus as H, InsufficientGasError as I, type PayoutRule as J, PlaymosError as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type PlaymosErrorCode as O, type PlaymosConfig as P, type RetryOptions as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type RoundStatus as U, type VerifyResult as V, type WebhookEvent as W, type WalletConfig as X, WalletConnectionError as Y, type WalletConnector as Z, type WebhookEventType as _, type RoundState as a, type RoundSettleInput as b, type PrizeBalance as c, type WithdrawResult as d, type AgentFundResult as e, type EscrowHoldResult as f, type EscrowResolveResult as g, type MarketplaceSaleResult as h, type MarketplaceGetResult as i, type PayInput as j, type Payment as k, type EnterRoundInput as l, type TransferReconcile as m, type WaitOptions as n, type TransferInput as o, type TransferConfirmOptions as p, type AgentEconomyConfig as q, ApiError as r, AuthError as s, type ContractConfig as t, type Eip1193Provider as u, type GasMode as v, InvalidAmountError as w, type ListingStatus as x, type MarketplaceItem as y, type MarketplaceSale as z };
+export { WalletConnectionError as $, type ActiveSeriesRound as A, InvalidAmountError as B, type CancelRoundResult as C, type ListingStatus as D, type EscrowHoldInput as E, type MarketplaceItem as F, type GasConfig as G, type MarketplaceSale as H, InsufficientGasError as I, MissingFieldError as J, NothingToWithdrawError as K, type Listing as L, type MarketplaceListInput as M, type Network as N, PaymentFailedError as O, type PlaymosConfig as P, type PaymentStatus as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, PlaymosError as U, type VerifyResult as V, type WebhookEvent as W, type PlaymosErrorCode as X, type RetryOptions as Y, type RoundStatus as Z, type WalletConfig as _, type RoundState as a, type WalletConnector as a0, type WebhookEventType as a1, type RoundSettleInput as b, type PrizeBalance as c, type WithdrawResult as d, type AgentWallet as e, type AgentFundResult as f, type EscrowHoldResult as g, type EscrowResolveResult as h, type MarketplaceSaleResult as i, type MarketplaceGetResult as j, type PayInput as k, type Payment as l, type EnterRoundInput as m, type TransferReconcile as n, type WaitOptions as o, type TransferInput as p, type TransferConfirmOptions as q, type PayoutRule as r, type ActiveForSeriesResult as s, type AgentEconomyConfig as t, ApiError as u, AuthError as v, ConfigError as w, type ContractConfig as x, type Eip1193Provider as y, type GasMode as z };