@swarm-tips/client 0.1.1 → 0.2.0

package/README.md

@@ -4,7 +4,12 @@ One typed package for Swarm Tips client-side integrations. The root export is
 deliberately lightweight; import only the capability you need:
 
 - `@swarm-tips/client/shillbot`
+- `@swarm-tips/client/shillbot/api`
 - `@swarm-tips/client/coordination-game`
+- `@swarm-tips/client/coordination-game/solana`
+- `@swarm-tips/client/coordination-game/evm`
+- `@swarm-tips/client/coordination-game/api`
+- `@swarm-tips/client/swarm`
 - `@swarm-tips/client/evm`
 - `@swarm-tips/client/evm/testing` (test-only helpers)
 - `@swarm-tips/client/inbox`

package/SBOM.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@swarm-tips/client-0.1.1",
-  "documentNamespace": "https://swarm.tips/sbom/client/0.1.1",
+  "name": "@swarm-tips/client-0.2.0",
+  "documentNamespace": "https://swarm.tips/sbom/client/0.2.0",
   "creationInfo": {
-    "created": "2026-09-08T02:44:57.447Z",
+    "created": "2026-09-08T06:28:09.085Z",
     "creators": [
       "Tool: sdk/client/scripts/generate-sbom.mjs",
       "Organization: Swarm Tips"
@@ -15,8 +15,8 @@
     {
       "name": "@swarm-tips/client",
       "SPDXID": "SPDXRef-Package",
-      "versionInfo": "0.1.1",
-      "downloadLocation": "https://www.npmjs.com/package/@swarm-tips/client/v/0.1.1",
+      "versionInfo": "0.2.0",
+      "downloadLocation": "https://www.npmjs.com/package/@swarm-tips/client/v/0.2.0",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
       "licenseDeclared": "MIT"

package/dist/coordination-game/api.d.ts

@@ -0,0 +1,276 @@
+import { HttpClient, type HttpClientOptions } from "../http.js";
+export interface ChallengeRequest {
+    wallet: string;
+}
+export interface ChallengeResponse {
+    nonce: string;
+}
+export interface VerifyRequest {
+    wallet: string;
+    nonce: string;
+    signature: string;
+}
+export interface VerifyResponse {
+    token: string;
+}
+export interface SessionAuthRequest {
+    wallet: string;
+    tx_signature: string;
+    nonce: string;
+}
+export interface SessionAuthResponse {
+    token: string;
+}
+export interface QueueRequest {
+    tournament_id: number;
+    is_ai?: boolean;
+}
+export type QueueJoinResponse = {
+    matched: true;
+    session_id: string;
+} | {
+    matched: false;
+};
+export interface OkResponse {
+    ok: boolean;
+}
+export interface XLegPayload {
+    chain: string;
+    contract: string;
+    player: string;
+    session_key: string;
+    stake_base_units: string;
+    tranche_base_units: string;
+}
+export interface XMatchPayload {
+    match_id: string;
+    tournament_id: number;
+    match_live_digest: string;
+    operator_signature: string;
+    create_match_operator_sig: string;
+    fund_deadline: number;
+    match_deadline: number;
+    claim_window_secs: number;
+    a_is_p1: number;
+    leg_a: XLegPayload;
+    leg_b: XLegPayload;
+}
+export interface XQueueResponse {
+    status: "waiting" | "matched";
+    match?: XMatchPayload;
+    poll_handle?: string;
+}
+export interface XGameplayView {
+    match_id: string;
+    step2_checkpoint?: unknown;
+    step2_checkpoint_digest?: string;
+    r_matchup?: string;
+    terminal_checkpoint?: unknown;
+    terminal_checkpoint_digest?: string;
+}
+export interface EvmCall {
+    player: string;
+    to: string;
+    data: string;
+    value_wei: string;
+}
+export interface EvmMatchPayload {
+    game_id: string;
+    matchup_commitment: string;
+    chain: string;
+    contract: string;
+    stake_base_units: string;
+    create_call: EvmCall;
+    join_call: EvmCall;
+}
+export interface EvmJoinResponse {
+    status: string;
+    match?: EvmMatchPayload;
+    session_id?: string;
+}
+export declare class CoordinationGameApiClient {
+    readonly http: HttpClient;
+    constructor(options: HttpClientOptions);
+    authChallenge(body: ChallengeRequest): Promise<ChallengeResponse>;
+    authSession(body: SessionAuthRequest): Promise<SessionAuthResponse>;
+    evmAuthChallenge(body: ChallengeRequest): Promise<ChallengeResponse>;
+    evmAuthVerify(body: VerifyRequest): Promise<VerifyResponse>;
+    joinQueue(body: QueueRequest, token: string): Promise<QueueJoinResponse>;
+    leaveQueue(body: QueueRequest, token: string): Promise<OkResponse>;
+    gameStarted(body: {
+        game_id: number;
+        session_id: string;
+    }, token: string): Promise<OkResponse>;
+    gameJoined(body: {
+        game_id: number;
+        session_id: string;
+    }, token: string): Promise<OkResponse>;
+    cosign(body: {
+        session_id: string;
+        message: string;
+    }, token: string): Promise<{
+        signature: string;
+    }>;
+    cosignJoin(body: {
+        session_id: string;
+        message: string;
+    }, token: string): Promise<{
+        signature: string;
+    }>;
+    committed(body: {
+        session_id: string;
+    }, token: string): Promise<{
+        ok: boolean;
+        both_committed: boolean;
+    }>;
+    bothCommitted(body: {
+        session_id: string;
+    }, token: string): Promise<{
+        r_matchup: string;
+    }>;
+    resolved(body: Record<string, number>, token: string): Promise<OkResponse>;
+    joinCrossChainQueue(body: {
+        wallet: string;
+        chain: string;
+        session_key: string;
+        tournament_id: number;
+    }): Promise<XQueueResponse>;
+    crossChainStatus(by: {
+        handle: string;
+    } | {
+        wallet: string;
+    }): Promise<XQueueResponse>;
+    crossChainCommit(body: {
+        wallet: string;
+        commit: string;
+        handle?: string;
+    }): Promise<{
+        status: string;
+        both_committed: boolean;
+    }>;
+    crossChainSign(body: {
+        wallet: string;
+        step: number;
+        signature: string;
+        handle?: string;
+    }): Promise<{
+        status: string;
+        relayed: boolean;
+        r_matchup: string | null;
+    }>;
+    crossChainReveal(body: {
+        wallet: string;
+        preimage: string;
+        handle?: string;
+    }): Promise<{
+        status: string;
+        both_revealed: boolean;
+    }>;
+    crossChainGameplay(by: {
+        handle: string;
+    } | {
+        wallet: string;
+    }): Promise<XGameplayView>;
+    joinEvmGame(body: {
+        wallet: string;
+        player_wallet?: string;
+        chain: string;
+        tournament_id: number;
+    }): Promise<EvmJoinResponse>;
+    evmGameStatus(wallet: string): Promise<EvmJoinResponse>;
+    evmGameCommitted(body: {
+        game_id: string;
+        wallet: string;
+    }): Promise<{
+        status: string;
+        both_committed: boolean;
+        r_matchup: string | null;
+    }>;
+    evmGameStaked(body: {
+        game_id: string;
+    }): Promise<{
+        status: string;
+    }>;
+}
+export type WebSocketLike = {
+    readyState: number;
+    onopen: (() => void) | null;
+    onclose: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    send(data: string): void;
+    close(): void;
+};
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export type ServerMessage = {
+    type: "chat";
+    text: string;
+    from: string;
+} | {
+    type: "match_found";
+    session_id: string;
+    role: number;
+    matchup_commitment?: string;
+} | {
+    type: "game_ready";
+    game_id: number;
+} | {
+    type: "both_staked";
+} | {
+    type: "reveal_data";
+    r_matchup: string;
+} | {
+    type: "opponent_committed";
+} | {
+    type: "game_resolved";
+    p1_guess: number;
+    p2_guess: number;
+    matchup_type: number;
+    first_committer: number;
+} | {
+    type: "opponent_disconnected" | "opponent_reconnected" | "pong";
+} | {
+    type: "error";
+    message: string;
+};
+export type ClientMessage = {
+    type: "chat";
+    text: string;
+} | {
+    type: "ping";
+};
+export interface CoordinationGameWebSocketOptions {
+    baseUrl: string;
+    token: string;
+    network?: string;
+    session?: string;
+    webSocket?: WebSocketFactory;
+    setTimeout?: typeof globalThis.setTimeout;
+    clearTimeout?: typeof globalThis.clearTimeout;
+    setInterval?: typeof globalThis.setInterval;
+    clearInterval?: typeof globalThis.clearInterval;
+    pingIntervalMs?: number;
+    maxRetries?: number;
+}
+export declare class CoordinationGameWebSocketClient {
+    private readonly options;
+    private socket;
+    private pingTimer;
+    private retryCount;
+    private closed;
+    private readonly outbox;
+    onMessage: ((message: ServerMessage) => void) | null;
+    onOpen: (() => void) | null;
+    onClose: (() => void) | null;
+    constructor(options: CoordinationGameWebSocketOptions);
+    connect(): void;
+    send(message: ClientMessage): void;
+    close(): void;
+    get connected(): boolean;
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    private flush;
+    private startPing;
+    private stopPing;
+}

package/dist/coordination-game/api.js

@@ -0,0 +1,146 @@
+import { HttpClient } from "../http.js";
+import { SwarmClientError } from "../errors.js";
+export class CoordinationGameApiClient {
+    http;
+    constructor(options) {
+        this.http = new HttpClient(options);
+    }
+    authChallenge(body) { return this.http.post("/auth/challenge", body); }
+    authSession(body) { return this.http.post("/auth/session", body); }
+    evmAuthChallenge(body) { return this.http.post("/auth/evm/challenge", body); }
+    evmAuthVerify(body) { return this.http.post("/auth/evm/verify", body); }
+    joinQueue(body, token) { return this.http.post("/queue/join", body, token); }
+    leaveQueue(body, token) { return this.http.post("/queue/leave", body, token); }
+    gameStarted(body, token) { return this.http.post("/games/started", body, token); }
+    gameJoined(body, token) { return this.http.post("/games/joined", body, token); }
+    cosign(body, token) { return this.http.post("/games/cosign", body, token); }
+    cosignJoin(body, token) { return this.http.post("/games/cosign-join", body, token); }
+    committed(body, token) { return this.http.post("/games/committed", body, token); }
+    bothCommitted(body, token) { return this.http.post("/games/both-committed", body, token); }
+    resolved(body, token) { return this.http.post("/games/resolved", body, token); }
+    joinCrossChainQueue(body) {
+        return this.http.post("/internal/xqueue/join", body);
+    }
+    crossChainStatus(by) {
+        const query = "handle" in by
+            ? `handle=${encodeURIComponent(by.handle)}`
+            : `wallet=${encodeURIComponent(by.wallet)}`;
+        return this.http.get(`/internal/xqueue/status?${query}`);
+    }
+    crossChainCommit(body) {
+        return this.http.post("/internal/xqueue/commit", body);
+    }
+    crossChainSign(body) {
+        return this.http.post("/internal/xqueue/sign", body);
+    }
+    crossChainReveal(body) {
+        return this.http.post("/internal/xqueue/reveal", body);
+    }
+    crossChainGameplay(by) {
+        const query = "handle" in by
+            ? `handle=${encodeURIComponent(by.handle)}`
+            : `wallet=${encodeURIComponent(by.wallet)}`;
+        return this.http.get(`/internal/xqueue/gameplay?${query}`);
+    }
+    joinEvmGame(body) {
+        return this.http.post("/internal/evmgame/join", body);
+    }
+    evmGameStatus(wallet) {
+        return this.http.get(`/internal/evmgame/status?wallet=${encodeURIComponent(wallet)}`);
+    }
+    evmGameCommitted(body) {
+        return this.http.post("/internal/evmgame/committed", body);
+    }
+    evmGameStaked(body) {
+        return this.http.post("/internal/evmgame/staked", body);
+    }
+}
+export class CoordinationGameWebSocketClient {
+    options;
+    socket = null;
+    pingTimer = null;
+    retryCount = 0;
+    closed = false;
+    outbox = [];
+    onMessage = null;
+    onOpen = null;
+    onClose = null;
+    constructor(options) {
+        this.options = options;
+    }
+    connect() {
+        if (this.closed)
+            return;
+        const factory = this.options.webSocket ?? ((url) => new globalThis.WebSocket(url));
+        if (!factory)
+            throw new SwarmClientError({ code: "INVALID_ARGUMENT", operation: "websocket.connect", message: "A WebSocket factory is required" });
+        const query = new URLSearchParams({ token: this.options.token });
+        if (this.options.network && this.options.network !== "mainnet")
+            query.set("network", this.options.network);
+        if (this.options.session)
+            query.set("session", this.options.session);
+        const url = `${this.options.baseUrl.replace(/^http/, "ws").replace(/\/$/, "")}/ws?${query.toString().replace(/%3A/g, ":")}`;
+        this.socket = factory(url);
+        this.socket.onopen = () => {
+            this.retryCount = 0;
+            this.startPing();
+            this.flush();
+            this.onOpen?.();
+        };
+        this.socket.onmessage = (event) => {
+            try {
+                this.onMessage?.(JSON.parse(String(event.data)));
+            }
+            catch { /* malformed peer data is ignored */ }
+        };
+        this.socket.onclose = () => {
+            this.stopPing();
+            this.onClose?.();
+            if (!this.closed && this.retryCount < (this.options.maxRetries ?? 10)) {
+                const delay = Math.min(2 ** this.retryCount * 1_000, 10_000);
+                this.retryCount += 1;
+                (this.options.setTimeout ?? globalThis.setTimeout)(() => this.connect(), delay);
+            }
+        };
+    }
+    send(message) {
+        if (this.socket?.readyState === 1)
+            this.socket.send(JSON.stringify(message));
+        else if (!this.closed && message.type !== "ping" && this.outbox.length < 100)
+            this.outbox.push(message);
+    }
+    close() {
+        this.closed = true;
+        this.outbox.length = 0;
+        this.stopPing();
+        this.socket?.close();
+        this.socket = null;
+    }
+    get connected() { return this.socket?.readyState === 1; }
+    waitForConnection(timeoutMs = 30_000) {
+        if (this.connected)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const timeout = (this.options.setTimeout ?? globalThis.setTimeout)(() => reject(new SwarmClientError({ code: "TIMEOUT", operation: "websocket.connect", message: "WebSocket connection timeout", retryable: true })), timeoutMs);
+            const previous = this.onOpen;
+            this.onOpen = () => {
+                (this.options.clearTimeout ?? globalThis.clearTimeout)(timeout);
+                this.onOpen = previous;
+                previous?.();
+                resolve();
+            };
+        });
+    }
+    flush() {
+        while (this.outbox.length && this.socket?.readyState === 1)
+            this.socket.send(JSON.stringify(this.outbox.shift()));
+    }
+    startPing() {
+        this.pingTimer = (this.options.setInterval ?? globalThis.setInterval)(() => this.send({ type: "ping" }), this.options.pingIntervalMs ?? 10_000);
+    }
+    stopPing() {
+        if (this.pingTimer !== null)
+            (this.options.clearInterval ?? globalThis.clearInterval)(this.pingTimer);
+        this.pingTimer = null;
+    }
+}