@chipzen-ai/bot 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,746 @@
+/**
+ * Core data models — Action, GameState, Card.
+ *
+ * Field naming uses idiomatic camelCase for the SDK's user-facing
+ * surface. The on-the-wire JSON the protocol uses is snake_case
+ * (Layer 1 / Layer 2 spec); the parsers in this module translate.
+ */
+/**
+ * A standard playing card. `rank` is one of `2`-`9`, `T`, `J`, `Q`,
+ * `K`, `A`. `suit` is one of `h` (hearts), `d` (diamonds), `c`
+ * (clubs), `s` (spades).
+ */
+interface Card {
+    readonly rank: string;
+    readonly suit: string;
+}
+/**
+ * Parse a card from its 2-character wire representation, e.g. `"Ah"`.
+ *
+ * Throws `Error` on malformed input; the wire format is
+ * always exactly 2 characters with a valid rank + suit.
+ */
+declare function cardFromString(s: string): Card;
+/** Render a card back to its 2-character wire form. */
+declare function cardToString(c: Card): string;
+type ActionKind = "fold" | "check" | "call" | "raise" | "all_in";
+/**
+ * The action a bot returns from `decide()`.
+ *
+ * Construct via the static factories (`Action.fold()` etc.) — they
+ * validate the action vs. amount invariants for you.
+ */
+declare class Action {
+    readonly action: ActionKind;
+    readonly amount?: number | undefined;
+    private constructor();
+    static fold(): Action;
+    static check(): Action;
+    static call(): Action;
+    static raiseTo(amount: number): Action;
+    static allIn(): Action;
+    /**
+     * Serialize to the two-layer `turn_action` payload shape the server expects.
+     *
+     * Returns `{action, params}` where `params` carries the raise amount
+     * for `raise` and is empty for everything else.
+     */
+    toWire(): {
+        action: ActionKind;
+        params: Record<string, unknown>;
+    };
+}
+/**
+ * A single entry from `state.actionHistory`. Synthetic blind/ante
+ * entries (`post_small_blind`, `post_big_blind`, `post_ante`) appear
+ * here too — the server generates them; bots do not submit them.
+ */
+interface ActionHistoryEntry {
+    readonly seat: number;
+    readonly action: string;
+    readonly amount?: number;
+    readonly isTimeout?: boolean;
+}
+/**
+ * Built from the server's `turn_request` message. The parser in
+ * `parseGameState` converts the wire-format snake_case to the
+ * camelCase fields below.
+ */
+interface GameState {
+    readonly handNumber: number;
+    readonly phase: "preflop" | "flop" | "turn" | "river";
+    readonly holeCards: readonly Card[];
+    readonly board: readonly Card[];
+    readonly pot: number;
+    readonly yourStack: number;
+    readonly opponentStacks: readonly number[];
+    readonly yourSeat: number;
+    readonly dealerSeat: number;
+    readonly toCall: number;
+    readonly minRaise: number;
+    readonly maxRaise: number;
+    readonly validActions: readonly string[];
+    readonly actionHistory: readonly ActionHistoryEntry[];
+    readonly roundId: string;
+    readonly requestId: string;
+}
+interface RawTurnRequest {
+    request_id?: string;
+    round_id?: string;
+    valid_actions?: string[];
+    state?: Record<string, unknown> | null;
+}
+/**
+ * Parse a `turn_request` envelope into a `GameState`.
+ *
+ * The wire shape is documented in
+ * `docs/protocol/POKER-GAME-STATE-PROTOCOL.md`. All fields default
+ * to safe values when absent — but a real server always sends them.
+ */
+declare function parseGameState(message: RawTurnRequest): GameState;
+
+/**
+ * `Bot` abstract base class.
+ *
+ * Subclass and override `decide()`. Lifecycle hooks
+ * (`onMatchStart` / `onRoundStart` / `onPhaseChange` / `onTurnResult` /
+ * `onRoundResult` / `onMatchEnd`) are optional — defaults are no-ops.
+ * Override the ones you need; the SDK's session loop will call them
+ * at the right point.
+ */
+
+declare abstract class Bot {
+    /**
+     * The only required override. Called every time the server sends a
+     * `turn_request` for your seat. Return one of:
+     * `Action.fold()`, `Action.check()`, `Action.call()`,
+     * `Action.raiseTo(amount)`, `Action.allIn()`.
+     *
+     * The returned action's wire-form `action` string MUST be in
+     * `state.validActions`; raise amounts MUST satisfy
+     * `state.minRaise <= amount <= state.maxRaise`. If the bot returns
+     * an illegal action, the SDK's safe-fallback substitutes `check`
+     * (or `fold` if check is illegal) and the platform sends a
+     * `bot_error` event to the human's UI.
+     */
+    abstract decide(state: GameState): Action;
+    /** Called once when the `match_start` message arrives. */
+    onMatchStart(_matchInfo: Record<string, unknown>): void;
+    /**
+     * Called at the start of every hand with the raw `round_start` message.
+     *
+     * Override if you need the Layer 1 envelope (`round_id`,
+     * `round_number`) or the full Layer 2 `state` payload. For most bots,
+     * `onHandStart` is the simpler hook.
+     */
+    onRoundStart(_message: Record<string, unknown>): void;
+    /**
+     * Called when the flop, turn, or river is dealt. Useful for triggering
+     * postflop planning *between* your turns rather than inside `decide`.
+     */
+    onPhaseChange(_message: Record<string, unknown>): void;
+    /**
+     * Called after every participant's action is broadcast — yours and
+     * every opponent's. Use for opponent modeling, timing analysis, or
+     * stack tracking.
+     *
+     * This hook runs *before* the next `turn_request` is dispatched, and
+     * runs serially. Slow work here eats into your decide budget — see
+     * the DEV-MANUAL §6 for the "queue drain" failure mode.
+     */
+    onTurnResult(_message: Record<string, unknown>): void;
+    /** Called when a hand ends (`round_result` message). */
+    onRoundResult(_message: Record<string, unknown>): void;
+    /** Called once when the match ends. */
+    onMatchEnd(_results: Record<string, unknown>): void;
+    /**
+     * Called after each `turn_action` is sent, with the wall-clock time
+     * `decide()` took in milliseconds.
+     *
+     * Default is a no-op. Override to track decision latency — useful for
+     * spotting when your bot is drifting toward the platform's turn-timeout
+     * budget. See chipzen-ai/chipzen-sdk#46.
+     */
+    onDecisionLatency(_latencyMs: number): void;
+}
+
+/**
+ * Retry / backoff policy for the WebSocket client.
+ *
+ * When the connection to the Chipzen server drops (TCP reset, heartbeat
+ * miss, transient network failure, etc.) the SDK reconnects within the
+ * server's reconnect grace window. The pacing of those reconnect attempts
+ * is configurable via {@link RetryPolicy}, accepted by both `runBot` and
+ * `runExternalBot`.
+ *
+ * The default policy mirrors the Python SDK's spec (External-API Issue 26):
+ * 5 attempts, 500ms initial backoff, doubling each attempt, capped at
+ * 30 seconds. The defaults are sensible for the typical home-network
+ * deployment; devs on noisy connections may want a longer backoff or
+ * more attempts.
+ *
+ * Note: this policy controls **only** how reconnect attempts are paced.
+ * The 30-second server-side grace window itself is unchanged; if the
+ * reconnects burn through the window the session is considered lost and
+ * the server terminates the match-side state.
+ */
+/** Backoff knobs accepted by {@link RetryPolicy}. All fields are optional. */
+interface RetryPolicyOptions {
+    /**
+     * Maximum number of reconnection attempts after a connection drop or
+     * heartbeat miss. Must be `>= 0`. `0` disables reconnection entirely
+     * (the first connect failure raises). Default `5`.
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Delay before the **first** reconnect attempt, in milliseconds. Must
+     * be `>= 0`. Default `500`.
+     */
+    initialBackoffMs?: number;
+    /**
+     * Upper bound for any single backoff delay, in milliseconds. Must be
+     * `>= initialBackoffMs`. Default `30000` (matches the server-side grace
+     * window so a single backoff never exceeds the window itself).
+     */
+    maxBackoffMs?: number;
+    /**
+     * Exponential factor applied between attempts. `2.0` doubles the delay
+     * each attempt. Must be `>= 1.0`; `1.0` produces constant backoff.
+     * Default `2.0`.
+     */
+    backoffMultiplier?: number;
+}
+/**
+ * Backoff knobs applied to reconnect attempts.
+ *
+ * Backoff progression for attempt `n` (1-indexed) is:
+ *
+ *     min(initialBackoffMs * backoffMultiplier ** (n - 1), maxBackoffMs)
+ *
+ * Examples (defaults):
+ *
+ *     attempt 1:   500 ms
+ *     attempt 2:  1000 ms
+ *     attempt 3:  2000 ms
+ *     attempt 4:  4000 ms
+ *     attempt 5:  8000 ms
+ *     attempt 6: 16000 ms  (would be next, but capped by attempts=5)
+ */
+declare class RetryPolicy {
+    readonly maxReconnectAttempts: number;
+    readonly initialBackoffMs: number;
+    readonly maxBackoffMs: number;
+    readonly backoffMultiplier: number;
+    constructor(options?: RetryPolicyOptions);
+    /**
+     * Return the delay (in ms) to wait **before** the given attempt.
+     *
+     * @param attempt 1-indexed attempt number. `attempt=1` is the first
+     *   reconnect after a drop, `attempt=2` the second, etc.
+     * @returns The delay in milliseconds, capped at `maxBackoffMs`.
+     * @throws Error if `attempt < 1`.
+     */
+    backoffMs(attempt: number): number;
+}
+/**
+ * The default {@link RetryPolicy} used when `runBot` / `runExternalBot`
+ * is called without an explicit `retryPolicy` argument.
+ */
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+
+/**
+ * WebSocket client for the Chipzen two-layer protocol.
+ *
+ * The user-facing surface is `runBot(url, bot, options)`. Internals
+ * (session loop, mock-friendly helpers) are exported with `_` prefix
+ * for the conformance harness and tests; they are not part of the
+ * supported API.
+ */
+
+/**
+ * Raised when `bot.decide()` errors and `safeMode` is `false`.
+ *
+ * Distinguished from transport/connection errors so the caller treats it
+ * as terminal (a deterministic bot bug, not a transient disconnect) and
+ * does NOT reconnect-retry it. See chipzen-ai/chipzen-sdk#52.
+ */
+declare class BotDecisionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Optional knobs for `runBot`. All fields default to sensible values
+ * matching the platform's expectations.
+ */
+interface RunBotOptions {
+    /** Bot API token. Required for the `/bot` endpoint; empty is fine for local dev. */
+    token?: string | null;
+    /** Single-use ticket alternative to `token` (competitive endpoints). */
+    ticket?: string | null;
+    /** Match UUID. Auto-extracted from the URL if not supplied. */
+    matchId?: string;
+    /** Client software name sent in the `hello` handshake. */
+    clientName?: string;
+    /** Client software version sent in the `hello` handshake. Defaults to the SDK version. */
+    clientVersion?: string;
+    /**
+     * Reconnect attempt **cap**. When given, overrides the attempt count
+     * from `retryPolicy` (the policy's backoff knobs still apply). When
+     * omitted, the policy's `maxReconnectAttempts` is used.
+     */
+    maxRetries?: number;
+    /**
+     * {@link RetryPolicy} controlling reconnect attempts + exponential
+     * backoff. Defaults to {@link DEFAULT_RETRY_POLICY}.
+     */
+    retryPolicy?: RetryPolicy;
+    /**
+     * When `true` (default), an exception thrown by `bot.decide()` is
+     * folded (a safe fallback action is sent). Set `false` for dev/eval so
+     * the first exception propagates as a {@link BotDecisionError} and the
+     * process exits non-zero (chipzen-ai/chipzen-sdk#52).
+     */
+    safeMode?: boolean;
+    /**
+     * Override the WS `User-Agent` header. Defaults to
+     * `chipzen-sdk-js/<version>` (a non-default UA also clears the
+     * platform's Cloudflare bot-fight rule; chipzen-ai/chipzen-sdk#46).
+     */
+    userAgent?: string;
+}
+/** Protocol versions this client claims to support in the handshake. */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["1.0"];
+/**
+ * Connect a bot to the Chipzen server and play until the match ends.
+ *
+ * Resolves on `match_end` (with the `match_end` payload, ignored by most
+ * callers). Rejects if the connection cannot be established (after the
+ * reconnect budget is exhausted) or if `safeMode` is `false` and
+ * `bot.decide()` throws (a terminal {@link BotDecisionError}).
+ */
+declare function runBot(url: string, bot: Bot, options?: RunBotOptions): Promise<Record<string, unknown> | null>;
+interface AsyncMessageReader {
+    next(): Promise<string | null>;
+}
+
+/**
+ * `chipzen.toml` discovery and parsing for the SDK.
+ *
+ * Devs running an external-API bot should be able to drop their long-lived
+ * API token into a config file once and forget about it, instead of
+ * hard-coding `token="cz_extbot_..."` into source. This module implements
+ * the discovery + parsing half of that convention; `runExternalBot` (and
+ * the `chipzen-sdk run-external` CLI) consume the result and prefer
+ * explicit kwargs over config-file values.
+ *
+ * Mirrors the Python SDK's `chipzen.config` (External-API Issue 23,
+ * chipzen-ai/chipzen-sdk#42).
+ *
+ * Discovery
+ * ---------
+ *
+ * Search order, first match wins:
+ *
+ * 1. `./chipzen.toml` (current working directory)
+ * 2. `~/.chipzen/chipzen.toml` (user-home config)
+ * 3. `/etc/chipzen/chipzen.toml` (system config, POSIX only — silently
+ *    skipped on Windows where `/etc` does not exist)
+ *
+ * If no file is found, `loadChipzenConfig` returns `null` and the caller
+ * falls back to whatever explicit arguments were passed. A clear error is
+ * only raised when a file IS found but is malformed or missing the
+ * expected section.
+ *
+ * File format
+ * -----------
+ *
+ *     [external_api]
+ *     token  = "cz_extbot_<32-char-base62-random>"
+ *     url    = "wss://chipzen.ai/ws/external/bot/<bot_id>"  # optional
+ *     bot_id = "<bot-uuid>"                                 # optional
+ *
+ * All three fields are optional and must be quoted strings. We parse the
+ * single `[external_api]` table with a minimal inline reader rather than
+ * pulling in a TOML dependency — keeping the package's single runtime dep
+ * (`ws`).
+ */
+declare const CONFIG_FILENAME = "chipzen.toml";
+declare const SECTION_NAME = "external_api";
+/**
+ * Parsed contents of a `chipzen.toml` file. All `[external_api]` fields
+ * are optional; absence yields `null`.
+ */
+interface ChipzenConfig {
+    /** Filesystem path the config was loaded from (for error messages). */
+    readonly path: string;
+    /** Value of `[external_api] token` if present, else `null`. */
+    readonly token: string | null;
+    /** Value of `[external_api] url` if present, else `null`. */
+    readonly url: string | null;
+    /** Value of `[external_api] bot_id` if present, else `null`. */
+    readonly botId: string | null;
+}
+/**
+ * Raised when a `chipzen.toml` is found but cannot be used (malformed,
+ * missing the `[external_api]` section, or a field is the wrong type).
+ *
+ * A "found but unusable" file is always a hard error — silent fallback
+ * would mask typos that would otherwise be obvious.
+ */
+declare class ChipzenConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Discover and parse a `chipzen.toml` from the search path.
+ *
+ * @param paths Override the default search order. When omitted, uses
+ *   cwd → `~/.chipzen/` → `/etc/chipzen/` (POSIX only).
+ * @returns A {@link ChipzenConfig} if a file was found and parsed; `null`
+ *   if no file exists on the search path. The "no file" case is NOT an
+ *   error — the SDK falls back to explicit kwargs in that case.
+ * @throws ChipzenConfigError if a file is found but is malformed, lacks
+ *   the `[external_api]` section, or has a wrong-typed token / url / bot_id.
+ */
+declare function loadChipzenConfig(paths?: string[]): ChipzenConfig | null;
+/**
+ * Return the token to use, honoring the precedence rules.
+ *
+ * 1. If `explicitToken` is non-`undefined`/non-`null`, return it. Even an
+ *    empty string wins — the dev was explicit.
+ * 2. If `explicitTicket` is set, return `null` (ticket-auth; no token).
+ * 3. Otherwise, if `config` carries a token, return it.
+ * 4. Otherwise, return `null`.
+ */
+declare function resolveToken(opts: {
+    explicitToken?: string | null;
+    explicitTicket?: string | null;
+    config?: ChipzenConfig | null;
+}): string | null;
+/**
+ * Return the URL override to use, honoring the precedence rules.
+ *
+ * 1. If `explicitUrl` is set, return it.
+ * 2. Otherwise, if `config` carries a `url`, return it.
+ * 3. Otherwise, return `null`.
+ */
+declare function resolveUrl(opts: {
+    explicitUrl?: string | null;
+    config?: ChipzenConfig | null;
+}): string | null;
+
+/**
+ * Environment-aware connection helper for the external-API lobby.
+ *
+ * Devs running an external-API bot against Chipzen shouldn't need to
+ * remember the exact lobby WebSocket URL per environment. This module
+ * exposes {@link connectToChipzen} — a small one-liner that returns a
+ * fully-populated {@link ConnectionConfig} containing the resolved `url`,
+ * `token`, and `retryPolicy`, ready to hand off to `runExternalBot`.
+ *
+ * Mirrors the Python SDK's `chipzen.connect` (External-API Issue 24,
+ * chipzen-ai/chipzen-sdk#43).
+ *
+ * Environment → URL mapping:
+ *
+ *     prod    -> wss://chipzen.ai/ws/external/bot/{botId}
+ *     staging -> wss://staging.chipzen.ai/ws/external/bot/{botId}
+ *     local   -> ws://localhost:8001/ws/external/bot/{botId}
+ *
+ * Precedence (highest first) for the final WebSocket URL:
+ *
+ * 1. `[external_api].url` from a discovered `chipzen.toml` — a config-file
+ *    URL ALWAYS wins (most explicit, user-managed override).
+ * 2. An **explicitly passed** `env` argument.
+ * 3. The `CHIPZEN_ENV` environment variable, if set to a recognized value.
+ * 4. The default of `"prod"`.
+ */
+
+/** Recognized target environments. */
+type EnvName = "prod" | "staging" | "local";
+/** The canonical env names, in order, for error messages + validation. */
+declare const ENV_NAMES: readonly EnvName[];
+/**
+ * Name of the environment variable consulted when `env` is not explicitly
+ * passed.
+ */
+declare const ENV_VAR_NAME = "CHIPZEN_ENV";
+/**
+ * Fully-resolved connection parameters ready for `runExternalBot`.
+ * Returned by {@link connectToChipzen}.
+ */
+interface ConnectionConfig {
+    /** WebSocket URL the bot should connect to. */
+    readonly url: string;
+    /** Long-lived API token from a discovered `chipzen.toml`, or `null`. */
+    readonly token: string | null;
+    /** {@link RetryPolicy} controlling reconnect pacing. */
+    readonly retryPolicy: RetryPolicy;
+    /**
+     * The resolved environment name, or `null` if the URL was supplied
+     * verbatim via a config file (no env mapping applied). Mostly for logs.
+     */
+    readonly env: EnvName | null;
+    /**
+     * The {@link ChipzenConfig} discovered during resolution (if any), or
+     * `null`. Exposed so callers can pass it through to `runExternalBot`
+     * and avoid a second filesystem stat.
+     */
+    readonly config: ChipzenConfig | null;
+}
+/** Options for {@link connectToChipzen}. */
+interface ConnectToChipzenOptions {
+    /** Override the reconnect-pacing policy. Defaults to {@link DEFAULT_RETRY_POLICY}. */
+    retryPolicy?: RetryPolicy;
+    /** Pre-loaded config to avoid a second filesystem stat. `undefined` triggers discovery. */
+    config?: ChipzenConfig | null;
+}
+/**
+ * Resolve a {@link ConnectionConfig} for the external-API lobby.
+ *
+ * Maps `env` to a canonical lobby URL and combines it with whatever
+ * config-file token / URL / retry policy the dev has set up.
+ *
+ * @param botId External-API bot UUID. Required, non-empty.
+ * @param env Target environment. `undefined`/`null` means "look at
+ *   `$CHIPZEN_ENV` first, then fall back to `prod`".
+ * @param options Optional retry policy + pre-loaded config.
+ * @throws Error if `botId` is empty, `env` is unrecognized, or
+ *   `$CHIPZEN_ENV` is set to an unrecognized value.
+ * @throws ChipzenConfigError if a discovered `chipzen.toml` is malformed.
+ */
+declare function connectToChipzen(botId: string, env?: EnvName | null, options?: ConnectToChipzenOptions): ConnectionConfig;
+
+/**
+ * External-API remote-play entry point: {@link runExternalBot}.
+ *
+ * Where `runBot` connects a bot to a *known* match URL (the
+ * containerized/upload path — the platform's executor hands the container
+ * its `/ws/match/{matchId}/{participantId}` URL), this module implements
+ * the **external-API remote-play** path: a developer runs their bot on
+ * their own machine, authenticates with a long-lived `cz_extbot_` token,
+ * and the platform matches and dispatches them like any other competitor.
+ *
+ * The flow:
+ *
+ *     lobby WS  /ws/external/bot/{botId}      (token in authenticate frame)
+ *         -> "matched" notify (carries matchId + gatewayWsUrl)
+ *         -> per-match gateway WS /ws/external/match/{mid}/{pid}
+ *                                  (token in Sec-WebSocket-Protocol header)
+ *         -> two-layer bot handshake + game loop to match_end
+ *
+ * The **match data plane is identical** to the containerized path, so the
+ * game loop here reuses `_runSession` from `client.ts` verbatim — the only
+ * external-API-specific code is the lobby connection and the per-match
+ * gateway handshake. A developer writes ONE `Bot` subclass and it works on
+ * both paths.
+ *
+ * The lobby is held open for the bot's whole session and each `matched`
+ * plays in its own task (Promise), so the 15-second lobby heartbeat is
+ * answered even while a multi-minute match is in flight. This is what lets
+ * a single connection serve a whole tournament (the bot is "checked in"
+ * via lobby presence and matched once per round).
+ *
+ * Mirrors the Python SDK's `chipzen.external`, including the reconnect
+ * fix: a dropped gateway socket RECONNECTS and resumes; match-task
+ * ownership is hoisted to the top level so a lobby reconnect doesn't kill
+ * in-flight matches; teardown drains-then-cancels, never orphaning a task.
+ */
+
+/**
+ * Sentinel subprotocol that marks the `cz_extbot_` token in the
+ * `Sec-WebSocket-Protocol` header (CZ issue 2932 moved the token off the
+ * query string, where it leaked into proxy access logs). Must match the
+ * value the platform's api gateway expects.
+ */
+declare const BOT_TOKEN_SUBPROTOCOL = "chipzen-bot-token";
+/**
+ * Build the `Sec-WebSocket-Protocol` offer that carries the bot token.
+ *
+ * Returns `[sentinel, token]` — the sentinel marks "the next value is my
+ * bot token". The api gateway extracts the token from this header (so it
+ * never appears in any access log / URL) and echoes the sentinel back on
+ * accept.
+ */
+declare function botTokenSubprotocols(token: string): [string, string];
+/**
+ * Resolve the `matched.gateway_ws_url` path against the lobby origin.
+ *
+ * The `matched` notification carries `gateway_ws_url` as a *path*
+ * (`/ws/external/match/{mid}/{pid}`). The `cz_extbot_` token is NOT on the
+ * query string — it travels in the `Sec-WebSocket-Protocol` header. A
+ * future server that returns a full URL is passed through unchanged.
+ */
+declare function resolveGatewayUrl(lobbyUrl: string, gatewayWsPath: string): string;
+/** A factory that produces a fresh {@link Bot} per match (or returns the same one). */
+type BotFactory = () => Bot;
+/** A connected WS-shaped object the lobby loop / `_runSession` drive. */
+interface ExternalConnection {
+    /** Send a string frame. */
+    send(data: string): void | Promise<void>;
+    /** Pull-based message reader; resolves `null` when the socket closes. */
+    reader: AsyncMessageReader;
+    /** Close the underlying socket. */
+    close(): void;
+}
+/** Options handed to a {@link Transport} on connect. */
+interface TransportConnectOptions {
+    /** WS `User-Agent` header value. */
+    userAgent: string;
+    /**
+     * Sec-WebSocket-Protocol offer (gateway leg carries `[sentinel, token]`).
+     * Omitted for the lobby leg.
+     */
+    subprotocols?: string[];
+}
+/** Opens WS connections for the external path. Injectable for tests. */
+type Transport = (url: string, options: TransportConnectOptions) => Promise<ExternalConnection>;
+/** Per-match result recorded by the session. */
+interface MatchResult {
+    matchId: string | null;
+    end: Record<string, unknown> | null;
+}
+/** Options for {@link runExternalBot}. */
+interface RunExternalBotOptions {
+    /** External-API bot UUID. Used to build the lobby URL when `url` is absent. */
+    botId?: string;
+    /** Target environment (`prod` / `staging` / `local`). `undefined` consults `$CHIPZEN_ENV`. */
+    env?: EnvName | null;
+    /** Explicit full lobby URL. Overrides `botId` / `env` derivation. */
+    url?: string;
+    /** Long-lived `cz_extbot_` API token. Falls back to `[external_api].token`. Required. */
+    token?: string | null;
+    /** Pre-loaded config, to avoid a second filesystem stat. `undefined` triggers discovery. */
+    config?: ChipzenConfig | null;
+    /** Reconnect-pacing policy. Defaults to {@link DEFAULT_RETRY_POLICY}. */
+    retryPolicy?: RetryPolicy;
+    /** Client software name sent in the per-match `hello`. */
+    clientName?: string;
+    /** Client software version. Defaults to the SDK version. */
+    clientVersion?: string;
+    /** When `true` (default), a `decide()` throw is folded; `false` propagates a {@link BotDecisionError}. */
+    safeMode?: boolean;
+    /** Stop after this many matches complete. `undefined` runs until the lobby closes / evict. */
+    maxMatches?: number | null;
+    /** Override the WS `User-Agent`. Defaults to `chipzen-sdk-js/<version>`. */
+    userAgent?: string;
+    /** Injectable transport (tests). Defaults to a real `ws.WebSocket`. */
+    transport?: Transport;
+}
+/**
+ * Run a bot on the Chipzen external-API remote-play path.
+ *
+ * Connects to the lobby, then plays every match the platform dispatches to
+ * this bot (a single challenge, or every round of a tournament) until the
+ * lobby closes, the bot is evicted, or `maxMatches` matches complete.
+ *
+ * @returns A list of per-match result objects (`{matchId, end}`), one per
+ *   match played this session.
+ * @throws Error if no token can be resolved, or neither `url` nor a
+ *   `botId` is available to build the lobby URL.
+ * @throws BotDecisionError if `safeMode` is `false` and `bot.decide()` throws.
+ */
+declare function runExternalBot(bot: Bot | BotFactory, options?: RunExternalBotOptions): Promise<MatchResult[]>;
+
+/**
+ * Single source of truth for the SDK version string.
+ *
+ * Reads `version` from the package's own `package.json` so the value the
+ * handshake reports always tracks the published package (chipzen-ai/chipzen-sdk#41)
+ * — no hardcoded literal to drift out of sync on a release bump.
+ *
+ * The import is resolved against `../package.json` (one level up from
+ * `src/`). `tsup` inlines the JSON at build time, so the bundled output
+ * carries the literal value with no runtime filesystem read.
+ */
+/** The installed SDK version, e.g. `"0.3.0"`. */
+declare const VERSION: string;
+
+/**
+ * `chipzen-sdk init <name>` — scaffold a new Chipzen bot project.
+ *
+ * Mirrors the Python `chipzen.scaffold` shape so cross-language
+ * developers see the same outputs. The scaffolded project is plain
+ * ESM JavaScript (no TypeScript dep required to run); convert to TS
+ * if you want by renaming bot.js -> bot.ts and adding a tsconfig.
+ */
+interface ScaffoldOptions {
+    /** Where to create the new project. Defaults to cwd. */
+    parentDir?: string;
+}
+declare function scaffoldBot(name: string, options?: ScaffoldOptions): Promise<string>;
+
+/**
+ * `chipzen-sdk validate <path>` — pre-upload conformance checks.
+ *
+ * Mirrors the Python validator's check shape and severity model so a
+ * `(severity, name, message)` tuple from either language renders the
+ * same way in client tooling.
+ */
+type Severity$1 = "pass" | "warn" | "fail";
+interface ValidationResult {
+    severity: Severity$1;
+    name: string;
+    message: string;
+}
+interface ValidateOptions {
+    /** Override entry point filename (default: auto-detect bot.js / bot.mjs / bot.cjs). */
+    entryPoint?: string;
+    /** Hard-fail upload size threshold, in bytes. Defaults to 500 MB (platform cap). */
+    maxUploadBytes?: number;
+    /** Warn if `decide()` takes longer than this (ms). */
+    timeoutWarnMs?: number;
+    /**
+     * If true, run the protocol-conformance harness after the smoke test
+     * passes — drives the bot through one full canned match (handshake +
+     * 1 hand + match_end) against an in-process mock WebSocket.
+     */
+    checkConnectivity?: boolean;
+    /** Per-conformance-scenario timeout (ms). Default 10s. */
+    conformanceTimeoutMs?: number;
+}
+declare const DEFAULT_MAX_UPLOAD_BYTES: number;
+declare const DEFAULT_TIMEOUT_WARN_MS = 100;
+declare const PLATFORM_TIMEOUT_MS = 500;
+declare function validateBot(botPath: string, options?: ValidateOptions): Promise<ValidationResult[]>;
+
+/**
+ * Protocol-conformance harness used by `chipzen-sdk validate --check-connectivity`.
+ *
+ * Mirrors the Python harness in `packages/python/src/chipzen/conformance.py`
+ * — same scenario shape, same severity model, same canned protocol
+ * exchange (handshake + one full hand + match_end). A clean run means
+ * the upload pipeline will accept the bot on protocol grounds. It does
+ * NOT mean the bot is good.
+ *
+ * Implementation: drives `_runSession` from `client.ts` against an
+ * in-process mock WebSocket rather than spinning up a real server. The
+ * `ws` transport is well-tested upstream; what we verify here is the
+ * bot's own protocol handling, which is the only part the user's code
+ * influences.
+ */
+
+type Severity = "pass" | "warn" | "fail";
+/** Single conformance scenario result. Same shape as `ValidationResult`. */
+interface ConformanceCheck {
+    severity: Severity;
+    name: string;
+    message: string;
+}
+interface RunConformanceOptions {
+    /** Per-scenario timeout in milliseconds. Default 10s. */
+    timeoutMs?: number;
+}
+/**
+ * Run every conformance scenario against `bot` and return per-check
+ * results. The same bot instance is reused across scenarios — matches
+ * the user's production usage shape.
+ *
+ * Note: the JavaScript harness does not currently include a hard
+ * wall-clock watchdog. A bot whose `decide()` blocks the event loop
+ * (busy-loop, sync `Atomics.wait`) will hang the harness because
+ * `setTimeout` cannot fire while the loop is starved. The Python SDK
+ * uses a daemon thread for this; the JS equivalent is a Worker and is
+ * deferred to a follow-up.
+ */
+declare function runConformanceChecks(bot: Bot, options?: RunConformanceOptions): Promise<ConformanceCheck[]>;
+
+export { Action, type ActionHistoryEntry, type ActionKind, BOT_TOKEN_SUBPROTOCOL, Bot, BotDecisionError, type BotFactory, CONFIG_FILENAME, type Card, type ChipzenConfig, ChipzenConfigError, type ConformanceCheck, type ConnectToChipzenOptions, type ConnectionConfig, DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_WARN_MS, ENV_NAMES, ENV_VAR_NAME, type EnvName, type GameState, type MatchResult, PLATFORM_TIMEOUT_MS, RetryPolicy, type RetryPolicyOptions, type RunBotOptions, type RunConformanceOptions, type RunExternalBotOptions, SECTION_NAME, SUPPORTED_PROTOCOL_VERSIONS, type ScaffoldOptions, type Severity$1 as Severity, VERSION, type ValidateOptions, type ValidationResult, botTokenSubprotocols, cardFromString, cardToString, connectToChipzen, loadChipzenConfig, parseGameState, resolveGatewayUrl, resolveToken, resolveUrl, runBot, runConformanceChecks, runExternalBot, scaffoldBot, validateBot };