@apa-network/agent-sdk 0.1.0 → 0.2.0-beta.10

package/dist/bot/createBot.js

@@ -1,107 +0,0 @@
-import { EventEmitter } from "node:events";
-import { APAWsClient } from "../ws/client.js";
-import { nextRequestId, validateBotAction } from "../utils/action.js";
-const DEFAULT_GUARD_MS = 300;
-function withTimeout(promise, timeoutMs) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error("strategy_timeout")), timeoutMs);
-        promise
-            .then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        })
-            .catch((err) => {
-            clearTimeout(timer);
-            reject(err);
-        });
-    });
-}
-function buildTurnKey(s) {
-    return `${s.hand_id}:${s.street}:${s.current_actor_seat}:${s.current_bet}:${s.call_amount}:${s.pot}`;
-}
-export function createBot(opts) {
-    const emitter = new EventEmitter();
-    const ws = new APAWsClient({
-        wsUrl: opts.wsUrl,
-        agentId: opts.agentId,
-        apiKey: opts.apiKey,
-        join: opts.join,
-        reconnect: opts.reconnect
-    });
-    let running = false;
-    let lastTurnKey = "";
-    ws.on("join_result", (evt) => {
-        if (!evt.ok) {
-            emitter.emit("error", new Error(`join failed: ${evt.error || "unknown"}`));
-            return;
-        }
-        emitter.emit("join", evt);
-    });
-    ws.on("event_log", (evt) => emitter.emit("eventLog", evt));
-    ws.on("hand_end", (evt) => {
-        lastTurnKey = "";
-        emitter.emit("handEnd", evt);
-    });
-    ws.on("error", (err) => emitter.emit("error", err));
-    async function play(strategy) {
-        running = true;
-        await ws.connect();
-        ws.on("state_update", async (state) => {
-            if (!running) {
-                return;
-            }
-            if (state.current_actor_seat !== state.my_seat) {
-                return;
-            }
-            const turnKey = buildTurnKey(state);
-            if (turnKey === lastTurnKey) {
-                return;
-            }
-            lastTurnKey = turnKey;
-            const ctx = {
-                gameId: state.game_id,
-                handId: state.hand_id,
-                mySeat: state.my_seat,
-                currentActorSeat: state.current_actor_seat,
-                minRaise: state.min_raise,
-                currentBet: state.current_bet,
-                callAmount: state.call_amount,
-                myBalance: state.my_balance,
-                communityCards: state.community_cards,
-                holeCards: state.hole_cards || [],
-                raw: state
-            };
-            const safetyMs = Math.max(100, state.action_timeout_ms - (opts.actionTimeoutGuardMs ?? DEFAULT_GUARD_MS));
-            try {
-                const action = await withTimeout(Promise.resolve(strategy(ctx)), safetyMs);
-                validateBotAction(action);
-                await ws.sendAction({
-                    type: "action",
-                    request_id: nextRequestId(),
-                    action: action.action,
-                    amount: "amount" in action ? action.amount : undefined
-                });
-            }
-            catch {
-                await ws.sendAction({
-                    type: "action",
-                    request_id: nextRequestId(),
-                    action: "fold"
-                });
-            }
-        });
-        ws.on("action_result", (res) => {
-            if (!res.ok) {
-                emitter.emit("error", new Error(`action failed: ${res.error || "unknown"} (${res.request_id})`));
-            }
-        });
-    }
-    async function stop() {
-        running = false;
-        await ws.stop();
-    }
-    function on(event, cb) {
-        emitter.on(event, cb);
-    }
-    return { play, stop, on };
-}

package/dist/types/bot.d.ts

@@ -1,42 +0,0 @@
-import type { JoinMode, StateUpdateEvent } from "./messages.js";
-export type BotAction = {
-    action: "fold";
-} | {
-    action: "check";
-} | {
-    action: "call";
-} | {
-    action: "raise";
-    amount: number;
-} | {
-    action: "bet";
-    amount: number;
-};
-export type PlayContext = {
-    gameId: string;
-    handId: string;
-    mySeat: number;
-    currentActorSeat: number;
-    minRaise: number;
-    currentBet: number;
-    callAmount: number;
-    myBalance: number;
-    communityCards: string[];
-    holeCards: string[];
-    raw: StateUpdateEvent;
-};
-export type StrategyFn = (ctx: PlayContext) => BotAction | Promise<BotAction>;
-export type ReconnectOptions = {
-    enabled?: boolean;
-    baseMs?: number;
-    maxMs?: number;
-    jitter?: boolean;
-};
-export type CreateBotOptions = {
-    wsUrl?: string;
-    agentId: string;
-    apiKey: string;
-    join: JoinMode;
-    reconnect?: ReconnectOptions;
-    actionTimeoutGuardMs?: number;
-};

package/dist/types/messages.d.ts

@@ -1,85 +0,0 @@
-export type JoinMode = {
-    mode: "random";
-} | {
-    mode: "select";
-    roomId: string;
-};
-export type JoinMessage = {
-    type: "join";
-    agent_id: string;
-    api_key: string;
-    join_mode: "random" | "select";
-    room_id?: string;
-};
-export type ActionMessage = {
-    type: "action";
-    request_id: string;
-    action: "fold" | "check" | "call" | "raise" | "bet";
-    amount?: number;
-    thought_log?: string;
-};
-export type JoinResultEvent = {
-    type: "join_result";
-    protocol_version: string;
-    ok: boolean;
-    error?: string;
-    room_id?: string;
-};
-export type StateUpdateEvent = {
-    type: "state_update";
-    protocol_version: string;
-    game_id: string;
-    hand_id: string;
-    my_seat: number;
-    current_actor_seat: number;
-    min_raise: number;
-    current_bet: number;
-    call_amount: number;
-    my_balance: number;
-    action_timeout_ms: number;
-    street: string;
-    hole_cards?: string[];
-    community_cards: string[];
-    pot: number;
-    opponents: Array<{
-        seat: number;
-        name: string;
-        stack: number;
-        action: string;
-    }>;
-};
-export type ActionResultEvent = {
-    type: "action_result";
-    protocol_version: string;
-    request_id: string;
-    ok: boolean;
-    error?: string;
-};
-export type EventLogEvent = {
-    type: "event_log";
-    protocol_version: string;
-    timestamp_ms: number;
-    player_seat: number;
-    action: string;
-    amount?: number;
-    thought_log?: string;
-    event: string;
-};
-export type HandEndEvent = {
-    type: "hand_end";
-    protocol_version: string;
-    winner: string;
-    pot: number;
-    balances: Array<{
-        agent_id: string;
-        balance: number;
-    }>;
-    showdown?: Array<{
-        agent_id: string;
-        hole_cards: string[];
-    }>;
-};
-export type ServerEvent = JoinResultEvent | StateUpdateEvent | ActionResultEvent | EventLogEvent | HandEndEvent | {
-    type: string;
-    [k: string]: unknown;
-};

package/dist/utils/action.d.ts

@@ -1,3 +0,0 @@
-import type { BotAction } from "../types/bot.js";
-export declare function validateBotAction(action: BotAction): void;
-export declare function nextRequestId(): string;

package/dist/utils/action.js

@@ -1,10 +0,0 @@
-export function validateBotAction(action) {
-    if (action.action === "raise" || action.action === "bet") {
-        if (!Number.isFinite(action.amount) || action.amount <= 0) {
-            throw new Error(`${action.action} requires positive amount`);
-        }
-    }
-}
-export function nextRequestId() {
-    return `req_${Date.now()}_${Math.floor(Math.random() * 1_000_000_000)}`;
-}

package/dist/utils/action.test.js

@@ -1,10 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { validateBotAction } from "./action.js";
-test("validateBotAction accepts non-amount actions", () => {
-    validateBotAction({ action: "check" });
-    validateBotAction({ action: "fold" });
-});
-test("validateBotAction rejects invalid raise amount", () => {
-    assert.throws(() => validateBotAction({ action: "raise", amount: 0 }), /positive amount/);
-});

package/dist/utils/backoff.d.ts

@@ -1,2 +0,0 @@
-export declare function computeBackoffMs(attempt: number, baseMs: number, maxMs: number, jitter: boolean): number;
-export declare function sleep(ms: number): Promise<void>;

package/dist/utils/backoff.js

@@ -1,11 +0,0 @@
-export function computeBackoffMs(attempt, baseMs, maxMs, jitter) {
-    const exponential = Math.min(maxMs, baseMs * 2 ** Math.max(0, attempt - 1));
-    if (!jitter) {
-        return exponential;
-    }
-    const spread = Math.max(1, Math.floor(exponential * 0.2));
-    return exponential - spread + Math.floor(Math.random() * spread * 2);
-}
-export function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/dist/utils/backoff.test.js

@@ -1,8 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { computeBackoffMs } from "./backoff.js";
-test("computeBackoffMs grows exponentially without jitter", () => {
-    assert.equal(computeBackoffMs(1, 500, 8000, false), 500);
-    assert.equal(computeBackoffMs(2, 500, 8000, false), 1000);
-    assert.equal(computeBackoffMs(5, 500, 8000, false), 8000);
-});

package/dist/ws/client.d.ts

@@ -1,32 +0,0 @@
-import { EventEmitter } from "node:events";
-import type { ActionMessage, JoinMode } from "../types/messages.js";
-type WsOptions = {
-    wsUrl?: string;
-    agentId: string;
-    apiKey: string;
-    join: JoinMode;
-    reconnect?: {
-        enabled?: boolean;
-        baseMs?: number;
-        maxMs?: number;
-        jitter?: boolean;
-    };
-};
-export declare class APAWsClient extends EventEmitter {
-    private readonly wsUrl;
-    private readonly agentId;
-    private readonly apiKey;
-    private readonly join;
-    private readonly reconnect;
-    private socket;
-    private shouldRun;
-    private connectAttempt;
-    constructor(opts: WsOptions);
-    connect(): Promise<void>;
-    stop(): Promise<void>;
-    sendAction(action: ActionMessage): Promise<void>;
-    private openSocket;
-    private reconnectLoop;
-    private sendJoin;
-}
-export {};

package/dist/ws/client.js

@@ -1,116 +0,0 @@
-import { EventEmitter } from "node:events";
-import { computeBackoffMs, sleep } from "../utils/backoff.js";
-import { resolveWsUrl } from "../utils/config.js";
-const DEFAULT_RECONNECT = {
-    enabled: true,
-    baseMs: 500,
-    maxMs: 8000,
-    jitter: true
-};
-export class APAWsClient extends EventEmitter {
-    wsUrl;
-    agentId;
-    apiKey;
-    join;
-    reconnect;
-    socket = null;
-    shouldRun = true;
-    connectAttempt = 0;
-    constructor(opts) {
-        super();
-        this.wsUrl = resolveWsUrl(opts.wsUrl);
-        this.agentId = opts.agentId;
-        this.apiKey = opts.apiKey;
-        this.join = opts.join;
-        this.reconnect = {
-            enabled: opts.reconnect?.enabled ?? DEFAULT_RECONNECT.enabled,
-            baseMs: opts.reconnect?.baseMs ?? DEFAULT_RECONNECT.baseMs,
-            maxMs: opts.reconnect?.maxMs ?? DEFAULT_RECONNECT.maxMs,
-            jitter: opts.reconnect?.jitter ?? DEFAULT_RECONNECT.jitter
-        };
-    }
-    async connect() {
-        this.shouldRun = true;
-        await this.openSocket();
-        await this.sendJoin();
-    }
-    async stop() {
-        this.shouldRun = false;
-        if (this.socket) {
-            this.socket.close();
-            this.socket = null;
-        }
-    }
-    async sendAction(action) {
-        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
-            throw new Error("ws not connected");
-        }
-        this.socket.send(JSON.stringify(action));
-    }
-    async openSocket() {
-        const Impl = globalThis.WebSocket;
-        if (!Impl) {
-            throw new Error("WebSocket is unavailable in current Node runtime (requires Node 20+)");
-        }
-        await new Promise((resolve, reject) => {
-            const ws = new Impl(this.wsUrl);
-            this.socket = ws;
-            ws.onopen = () => {
-                this.connectAttempt = 0;
-                this.emit("connected");
-                resolve();
-            };
-            ws.onmessage = (evt) => {
-                try {
-                    const data = JSON.parse(String(evt.data));
-                    this.emit("event", data);
-                    this.emit(data.type, data);
-                }
-                catch (err) {
-                    this.emit("error", err);
-                }
-            };
-            ws.onerror = () => {
-                reject(new Error("ws connection failed"));
-            };
-            ws.onclose = async () => {
-                this.emit("disconnected");
-                if (!this.shouldRun || !this.reconnect.enabled) {
-                    return;
-                }
-                await this.reconnectLoop();
-            };
-        });
-    }
-    async reconnectLoop() {
-        while (this.shouldRun) {
-            this.connectAttempt += 1;
-            const waitMs = computeBackoffMs(this.connectAttempt, this.reconnect.baseMs, this.reconnect.maxMs, this.reconnect.jitter);
-            this.emit("reconnect", { attempt: this.connectAttempt, waitMs });
-            await sleep(waitMs);
-            try {
-                await this.openSocket();
-                await this.sendJoin();
-                return;
-            }
-            catch (err) {
-                this.emit("error", err);
-            }
-        }
-    }
-    async sendJoin() {
-        const msg = {
-            type: "join",
-            agent_id: this.agentId,
-            api_key: this.apiKey,
-            join_mode: this.join.mode
-        };
-        if (this.join.mode === "select") {
-            msg.room_id = this.join.roomId;
-        }
-        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
-            throw new Error("ws not connected for join");
-        }
-        this.socket.send(JSON.stringify(msg));
-    }
-}