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

package/dist/http/client.js

@@ -2,17 +2,27 @@ import { resolveApiBase } from "../utils/config.js";
 async function parseJson(res) {
     const text = await res.text();
     if (!text) {
-        throw new Error(`empty response (${res.status})`);
+        const err = new Error(`empty response (${res.status})`);
+        err.status = res.status;
+        throw err;
     }
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
     catch {
-        throw new Error(`invalid json response (${res.status})`);
+        const err = new Error(`invalid json response (${res.status})`);
+        err.status = res.status;
+        err.body = text;
+        throw err;
     }
     if (!res.ok) {
-        throw new Error(`${res.status} ${parsed?.error || text}`);
+        const p = parsed;
+        const err = new Error(`${res.status} ${p?.error || text}`);
+        err.status = res.status;
+        err.code = p?.error || "request_failed";
+        err.body = parsed;
+        throw err;
     }
     return parsed;
 }
@@ -29,10 +39,9 @@ export class APAHttpClient {
         });
         return parseJson(res);
     }
-    async getAgentStatus(apiKey) {
-        const res = await fetch(`${this.apiBase}/agents/status`, {
-            headers: { authorization: `Bearer ${apiKey}` }
-        });
+    async claimByCode(claimCode) {
+        const base = this.apiBase.replace(/\/api\/?$/, "");
+        const res = await fetch(`${base}/claim/${encodeURIComponent(claimCode)}`);
         return parseJson(res);
     }
     async getAgentMe(apiKey) {
@@ -56,6 +65,40 @@ export class APAHttpClient {
         });
         return parseJson(res);
     }
+    async listPublicRooms() {
+        const res = await fetch(`${this.apiBase}/public/rooms`);
+        return parseJson(res);
+    }
+    async createSession(input) {
+        const res = await fetch(`${this.apiBase}/agent/sessions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                agent_id: input.agentID,
+                api_key: input.apiKey,
+                join_mode: input.joinMode,
+                room_id: input.joinMode === "select" ? input.roomID : undefined
+            })
+        });
+        return parseJson(res);
+    }
+    async submitAction(input) {
+        const res = await fetch(`${this.apiBase}/agent/sessions/${input.sessionID}/actions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                request_id: input.requestID,
+                turn_id: input.turnID,
+                action: input.action,
+                amount: input.amount,
+                thought_log: input.thoughtLog || ""
+            })
+        });
+        return parseJson(res);
+    }
+    async closeSession(sessionID) {
+        await fetch(`${this.apiBase}/agent/sessions/${sessionID}`, { method: "DELETE" });
+    }
     async healthz() {
         const base = this.apiBase.replace(/\/api\/?$/, "");
         const res = await fetch(`${base}/healthz`);

package/dist/index.d.ts

@@ -1,4 +1 @@
 export { APAHttpClient } from "./http/client.js";
-export { createBot } from "./bot/createBot.js";
-export type { CreateBotOptions, PlayContext, StrategyFn, BotAction } from "./types/bot.js";
-export type { JoinMode, JoinResultEvent, StateUpdateEvent, ActionResultEvent, EventLogEvent, HandEndEvent, ServerEvent } from "./types/messages.js";

package/dist/index.js

@@ -1,2 +1 @@
 export { APAHttpClient } from "./http/client.js";
-export { createBot } from "./bot/createBot.js";

package/dist/loop/callback.d.ts

@@ -0,0 +1,20 @@
+export type DecisionAction = "fold" | "check" | "call" | "raise" | "bet";
+export type DecisionPayload = {
+    request_id: string;
+    action: DecisionAction;
+    amount?: number;
+    thought_log?: string;
+};
+export declare class DecisionCallbackServer {
+    private readonly addr;
+    private readonly decisions;
+    private server;
+    private callbackURL;
+    constructor(addr?: string);
+    start(): Promise<string>;
+    stop(): Promise<void>;
+    waitForDecision(requestID: string, timeoutMs: number): Promise<DecisionPayload>;
+    private handleRequest;
+    private reply;
+    private parseAddr;
+}

package/dist/loop/callback.js

@@ -0,0 +1,105 @@
+import http from "node:http";
+import { URL } from "node:url";
+export class DecisionCallbackServer {
+    addr;
+    decisions = new Map();
+    server = null;
+    callbackURL = "";
+    constructor(addr) {
+        this.addr = addr;
+    }
+    async start() {
+        if (this.server) {
+            return this.callbackURL;
+        }
+        const [host, port] = this.parseAddr();
+        this.server = http.createServer(this.handleRequest.bind(this));
+        await new Promise((resolve, reject) => {
+            this.server?.once("error", reject);
+            this.server?.listen(port, host, () => resolve());
+        });
+        const actual = this.server?.address();
+        if (!actual || typeof actual === "string") {
+            throw new Error("callback_server_address_unavailable");
+        }
+        this.callbackURL = `http://${actual.address}:${actual.port}/decision`;
+        return this.callbackURL;
+    }
+    async stop() {
+        const entries = [...this.decisions.values()];
+        this.decisions.clear();
+        for (const pending of entries) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error("callback_server_stopped"));
+        }
+        if (!this.server) {
+            return;
+        }
+        const s = this.server;
+        this.server = null;
+        await new Promise((resolve) => s.close(() => resolve()));
+    }
+    waitForDecision(requestID, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.decisions.delete(requestID);
+                reject(new Error("decision_timeout"));
+            }, timeoutMs);
+            this.decisions.set(requestID, { resolve, reject, timeout });
+        });
+    }
+    async handleRequest(req, res) {
+        const method = req.method || "";
+        const url = new URL(req.url || "/", "http://localhost");
+        if (method === "GET" && url.pathname === "/healthz") {
+            this.reply(res, 200, { ok: true });
+            return;
+        }
+        if (method !== "POST" || url.pathname !== "/decision") {
+            this.reply(res, 404, { error: "not_found" });
+            return;
+        }
+        let body = "";
+        req.setEncoding("utf8");
+        for await (const chunk of req) {
+            body += chunk;
+        }
+        let payload = null;
+        try {
+            payload = JSON.parse(body);
+        }
+        catch {
+            this.reply(res, 400, { error: "invalid_json" });
+            return;
+        }
+        if (!payload || typeof payload.request_id !== "string" || typeof payload.action !== "string") {
+            this.reply(res, 400, { error: "invalid_payload" });
+            return;
+        }
+        const pending = this.decisions.get(payload.request_id);
+        if (!pending) {
+            this.reply(res, 409, { error: "request_not_pending" });
+            return;
+        }
+        this.decisions.delete(payload.request_id);
+        clearTimeout(pending.timeout);
+        pending.resolve(payload);
+        this.reply(res, 200, { ok: true });
+    }
+    reply(res, status, payload) {
+        res.statusCode = status;
+        res.setHeader("content-type", "application/json");
+        res.end(`${JSON.stringify(payload)}\n`);
+    }
+    parseAddr() {
+        if (!this.addr) {
+            return ["127.0.0.1", 0];
+        }
+        const [host, portRaw] = this.addr.split(":");
+        const port = Number(portRaw);
+        if (!host || !Number.isFinite(port) || port <= 0) {
+            throw new Error(`invalid callback addr: ${this.addr}`);
+        }
+        return [host, port];
+    }
+}

package/dist/loop/callback.test.js

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { DecisionCallbackServer } from "./callback.js";
+test("callback server receives decision and resolves pending request", async (t) => {
+    const server = new DecisionCallbackServer("127.0.0.1:18787");
+    let callbackURL = "";
+    try {
+        callbackURL = await server.start();
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : "";
+        if (code === "EPERM" || code === "EACCES") {
+            t.skip("listen not permitted in this environment");
+            return;
+        }
+        throw err;
+    }
+    const decisionPromise = server.waitForDecision("req_1", 2000);
+    const res = await fetch(callbackURL, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            request_id: "req_1",
+            action: "call",
+            thought_log: "ok"
+        })
+    });
+    assert.equal(res.status, 200);
+    const decision = await decisionPromise;
+    assert.equal(decision.request_id, "req_1");
+    assert.equal(decision.action, "call");
+    await server.stop();
+});

package/dist/loop/credentials.d.ts

@@ -0,0 +1,10 @@
+export type AgentCredential = {
+    api_base: string;
+    agent_name: string;
+    agent_id: string;
+    api_key: string;
+    updated_at: string;
+};
+export declare function defaultCredentialPath(): string;
+export declare function loadCredential(apiBase: string, _agentName: string | undefined, filePath?: string): Promise<AgentCredential | null>;
+export declare function saveCredential(record: Omit<AgentCredential, "updated_at">, filePath?: string): Promise<void>;

package/dist/loop/credentials.js

@@ -0,0 +1,60 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STORE_VERSION = 2;
+export function defaultCredentialPath() {
+    return path.join(process.cwd(), "credentials.json");
+}
+export async function loadCredential(apiBase, _agentName, filePath = defaultCredentialPath()) {
+    const store = await readStore(filePath);
+    if (!store.credential) {
+        return null;
+    }
+    if (store.credential.api_base !== apiBase) {
+        return null;
+    }
+    return store.credential;
+}
+export async function saveCredential(record, filePath = defaultCredentialPath()) {
+    const store = await readStore(filePath);
+    store.credential = {
+        ...record,
+        updated_at: new Date().toISOString()
+    };
+    await writeStore(store, filePath);
+}
+async function readStore(filePath) {
+    let raw = "";
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (isENOENT(err)) {
+            return { version: STORE_VERSION };
+        }
+        throw err;
+    }
+    if (!raw.trim()) {
+        return { version: STORE_VERSION };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { version: STORE_VERSION };
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return { version: STORE_VERSION };
+    }
+    if (parsed.credential && typeof parsed.credential === "object") {
+        return { version: STORE_VERSION, credential: parsed.credential };
+    }
+    return { version: STORE_VERSION };
+}
+async function writeStore(store, filePath) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+}
+function isENOENT(err) {
+    return Boolean(err && typeof err === "object" && err.code === "ENOENT");
+}

package/dist/loop/credentials.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/loop/credentials.test.js

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { loadCredential, saveCredential } from "./credentials.js";
+test("saveCredential and loadCredential roundtrip", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "apa-sdk-creds-"));
+    const filePath = path.join(dir, "credentials.json");
+    await saveCredential({
+        api_base: "http://localhost:8080/api",
+        agent_name: "BotA",
+        agent_id: "agent_1",
+        api_key: "apa_1"
+    }, filePath);
+    const loaded = await loadCredential("http://localhost:8080/api", "BotA", filePath);
+    assert.ok(loaded);
+    assert.equal(loaded?.agent_id, "agent_1");
+    assert.equal(loaded?.api_key, "apa_1");
+});
+test("loadCredential without agentName returns single match for api base", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "apa-sdk-creds-"));
+    const filePath = path.join(dir, "credentials.json");
+    await saveCredential({
+        api_base: "http://localhost:8080/api",
+        agent_name: "BotA",
+        agent_id: "agent_1",
+        api_key: "apa_1"
+    }, filePath);
+    const loaded = await loadCredential("http://localhost:8080/api", undefined, filePath);
+    assert.ok(loaded);
+    assert.equal(loaded?.agent_name, "BotA");
+});

package/dist/loop/decision_state.d.ts

@@ -0,0 +1,30 @@
+export type DecisionState = {
+    version?: number;
+    session_id?: string;
+    stream_url?: string;
+    last_event_id?: string;
+    last_turn_id?: string;
+    pending_decision?: {
+        decision_id: string;
+        session_id: string;
+        request_id: string;
+        turn_id: string;
+        callback_url: string;
+        legal_actions?: string[];
+        action_constraints?: {
+            bet?: {
+                min: number;
+                max: number;
+            };
+            raise?: {
+                min_to: number;
+                max_to: number;
+            };
+        };
+        created_at: string;
+    };
+    updated_at?: string;
+};
+export declare function defaultDecisionStatePath(): string;
+export declare function loadDecisionState(filePath?: string): Promise<DecisionState>;
+export declare function saveDecisionState(state: DecisionState, filePath?: string): Promise<void>;

package/dist/loop/decision_state.js

@@ -0,0 +1,43 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_VERSION = 1;
+export function defaultDecisionStatePath() {
+    return path.join(process.cwd(), "decision_state.json");
+}
+export async function loadDecisionState(filePath = defaultDecisionStatePath()) {
+    let raw = "";
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (isENOENT(err)) {
+            return { version: STATE_VERSION };
+        }
+        throw err;
+    }
+    if (!raw.trim()) {
+        return { version: STATE_VERSION };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            return { ...parsed, version: STATE_VERSION };
+        }
+    }
+    catch {
+        return { version: STATE_VERSION };
+    }
+    return { version: STATE_VERSION };
+}
+export async function saveDecisionState(state, filePath = defaultDecisionStatePath()) {
+    const record = {
+        ...state,
+        version: STATE_VERSION,
+        updated_at: new Date().toISOString()
+    };
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+}
+function isENOENT(err) {
+    return Boolean(err && typeof err === "object" && err.code === "ENOENT");
+}

package/dist/loop/state.d.ts

@@ -0,0 +1,9 @@
+export type TurnState = {
+    turn_id?: string;
+    my_seat?: number;
+    current_actor_seat?: number;
+};
+export declare class TurnTracker {
+    private readonly seenTurns;
+    shouldRequestDecision(state: TurnState): boolean;
+}

package/dist/loop/state.js

@@ -0,0 +1,16 @@
+export class TurnTracker {
+    seenTurns = new Set();
+    shouldRequestDecision(state) {
+        const turnID = typeof state.turn_id === "string" ? state.turn_id : "";
+        const mySeat = Number(state.my_seat ?? -1);
+        const actorSeat = Number(state.current_actor_seat ?? -2);
+        if (!turnID || mySeat !== actorSeat) {
+            return false;
+        }
+        if (this.seenTurns.has(turnID)) {
+            return false;
+        }
+        this.seenTurns.add(turnID);
+        return true;
+    }
+}

package/dist/loop/state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/loop/state.test.js

@@ -0,0 +1,14 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { TurnTracker } from "./state.js";
+test("TurnTracker requests exactly once for my new turn", () => {
+    const tracker = new TurnTracker();
+    const state = { turn_id: "turn_1", my_seat: 0, current_actor_seat: 0 };
+    assert.equal(tracker.shouldRequestDecision(state), true);
+    assert.equal(tracker.shouldRequestDecision(state), false);
+});
+test("TurnTracker ignores opponent turn", () => {
+    const tracker = new TurnTracker();
+    const state = { turn_id: "turn_2", my_seat: 0, current_actor_seat: 1 };
+    assert.equal(tracker.shouldRequestDecision(state), false);
+});

package/dist/utils/config.d.ts

@@ -1,5 +1,4 @@
 export declare const DEFAULT_API_BASE = "http://localhost:8080/api";
-export declare const DEFAULT_WS_URL = "ws://localhost:8080/ws";
+export declare function normalizeApiBase(raw: string): string;
 export declare function resolveApiBase(override?: string): string;
-export declare function resolveWsUrl(override?: string): string;
 export declare function requireArg(name: string, value?: string): string;

package/dist/utils/config.js

@@ -1,10 +1,13 @@
 export const DEFAULT_API_BASE = "http://localhost:8080/api";
-export const DEFAULT_WS_URL = "ws://localhost:8080/ws";
-export function resolveApiBase(override) {
-    return (override || process.env.API_BASE || DEFAULT_API_BASE).trim();
+export function normalizeApiBase(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    if (trimmed.endsWith("/api")) {
+        return trimmed;
+    }
+    return `${trimmed}/api`;
 }
-export function resolveWsUrl(override) {
-    return (override || process.env.WS_URL || DEFAULT_WS_URL).trim();
+export function resolveApiBase(override) {
+    return normalizeApiBase(override || process.env.API_BASE || DEFAULT_API_BASE);
 }
 export function requireArg(name, value) {
     if (value && value.trim() !== "") {

package/dist/utils/config.test.js

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { DEFAULT_API_BASE, resolveApiBase } from "./config.js";
+import { DEFAULT_API_BASE, normalizeApiBase, resolveApiBase } from "./config.js";
 test("resolveApiBase prefers override", () => {
     assert.equal(resolveApiBase("http://x/api"), "http://x/api");
 });
@@ -10,3 +10,9 @@ test("resolveApiBase falls back to default", () => {
     assert.equal(resolveApiBase(undefined), DEFAULT_API_BASE);
     process.env.API_BASE = old;
 });
+test("normalizeApiBase appends /api when missing", () => {
+    assert.equal(normalizeApiBase("http://localhost:8080"), "http://localhost:8080/api");
+});
+test("normalizeApiBase keeps existing /api", () => {
+    assert.equal(normalizeApiBase("http://localhost:8080/api"), "http://localhost:8080/api");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apa-network/agent-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.10",
   "description": "APA Agent SDK and CLI",
   "type": "module",
   "bin": {
@@ -14,7 +14,12 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test dist/**/*.test.js"
+    "test": "npm run build && node --test dist/*.test.js dist/**/*.test.js",
+    "prepublishOnly": "npm run test",
+    "release:beta": "npm publish --tag beta --access public"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "engines": {
     "node": ">=20"

package/dist/bot/createBot.d.ts

@@ -1,14 +0,0 @@
-import type { CreateBotOptions, StrategyFn } from "../types/bot.js";
-import type { EventLogEvent, HandEndEvent, JoinResultEvent } from "../types/messages.js";
-type BotEvents = {
-    join: JoinResultEvent;
-    handEnd: HandEndEvent;
-    error: unknown;
-    eventLog: EventLogEvent;
-};
-export declare function createBot(opts: CreateBotOptions): {
-    play: (strategy: StrategyFn) => Promise<void>;
-    stop: () => Promise<void>;
-    on: <K extends keyof BotEvents>(event: K, cb: (payload: BotEvents[K]) => void) => void;
-};
-export {};