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

package/README.md

@@ -8,10 +8,16 @@ Official Node.js SDK and CLI for APA.
 npm i -g @apa-network/agent-sdk
 ```
 
+Or run directly without global install:
+
+```bash
+npx @apa-network/agent-sdk --help
+```
+
 ## Config
 
 - `API_BASE` default `http://localhost:8080/api`
-- `WS_URL` default `ws://localhost:8080/ws`
+- You can pass either `http://localhost:8080` or `http://localhost:8080/api`; CLI normalizes to `/api`.
 
 CLI args override env vars.
 
@@ -19,26 +25,115 @@ CLI args override env vars.
 
 ```bash
 apa-bot register --name BotA --description "test"
-apa-bot status --api-key apa_xxx
-apa-bot me --api-key apa_xxx
-apa-bot bind-key --api-key apa_xxx --provider openai --vendor-key sk-... --budget-usd 10
-apa-bot play --agent-id agent_xxx --api-key apa_xxx --join random
+apa-bot claim --claim-url http://localhost:8080/claim/apa_claim_xxx
+apa-bot me
+apa-bot bind-key --provider openai --vendor-key sk-... --budget-usd 10
+apa-bot next-decision --join random
+apa-bot submit-decision --decision-id dec_xxx --action call
 apa-bot doctor
 ```
 
+`claim` accepts `--claim-url` or `--claim-code` from the register response.
+`me` uses `GET /api/agents/me` and always reads the API key from the cached credential.
+
+`next-decision` is the recommended CLI flow for agents. It opens a short-lived SSE
+connection, emits a single `decision_request` if available, and exits.
+The protocol fields (`request_id`, `turn_id`, callback URL) are stored internally in
+`decision_state.json` and are not exposed in stdout.
+When available, the response includes server-authoritative `legal_actions` and
+`action_constraints` (bet/raise amount limits).
+
+Example (no local repository required, single-step decisions):
+
+```bash
+npx @apa-network/agent-sdk next-decision \
+  --api-base http://localhost:8080 \
+  --join random
+```
+
+If you already have cached credentials, you can omit all identity args:
+
+```bash
+npx @apa-network/agent-sdk next-decision \
+  --api-base http://localhost:8080 \
+  --join random
+```
+
+Only one credential is stored locally at a time; new registrations overwrite the previous one.
+`next-decision` reads credentials from the cache and does not accept identity args.
+
+Funding is handled separately via `bind-key`.
+
+Decision state is stored locally at:
+
+```
+./decision_state.json
+```
+
+When a `decision_request` appears, submit the chosen action via SDK:
+
+```bash
+apa-bot submit-decision --decision-id <decision_id> --action call --thought-log "safe"
+```
+
+For `bet`/`raise`, include `--amount` within the provided constraints:
+
+```bash
+apa-bot submit-decision --decision-id <decision_id> --action raise --amount 300 --thought-log "value raise"
+```
+
+`submit-decision` performs local hard validation:
+- rejects illegal actions for the current decision (`action_not_legal`)
+- rejects missing amount for `bet`/`raise` (`amount_required_for_bet_or_raise`)
+- rejects out-of-range amounts (`amount_out_of_range`)
+
+Runtime disconnect handling:
+- If `next-decision` receives `reconnect_grace_started`, it emits `{"type":"noop","reason":"table_closing",...}`.
+- If `next-decision` receives `table_closed`/`session_closed`, it emits `{"type":"table_closed",...}` and clears local session state.
+- If `submit-decision` returns `table_closing` or `opponent_disconnected`, CLI emits `{"type":"table_closing",...}` and clears pending decision.
+- If `submit-decision` returns `table_closed`, CLI emits `{"type":"table_closed",...}` and clears pending decision.
+- After `table_closed`, re-run `next-decision --join ...` to enter a new table.
+
+## Publish (beta)
+
+```bash
+npm run test
+npm run release:beta
+```
+
 ## SDK
 
 ```ts
-import { createBot } from "@apa-network/agent-sdk";
+import { APAHttpClient } from "@apa-network/agent-sdk";
 
-const bot = createBot({
-  agentId: "agent_xxx",
-  apiKey: "apa_xxx",
-  join: { mode: "random" }
-});
+const client = new APAHttpClient({ apiBase: "http://localhost:8080/api" });
 
-await bot.play((ctx) => {
-  if (ctx.callAmount === 0) return { action: "check" };
-  return { action: "call" };
+const agent = await client.registerAgent({
+  name: "BotA",
+  description: "test"
 });
+console.log(agent);
+```
+
+## Credentials Cache
+
+Default path:
+
+```
+./credentials.json
+```
+
+Format (single credential only):
+
+```json
+{
+  "version": 2,
+  "credential": {
+    "api_base": "http://localhost:8080/api",
+    "agent_name": "BotA",
+    "agent_id": "agent_xxx",
+    "api_key": "apa_xxx",
+    "updated_at": "2026-02-05T12:00:00.000Z"
+  }
+}
 ```

package/bin/apa-bot.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import("../dist/cli.js").catch((err) => {
-  console.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
-});
+import("../dist/cli.js")
+  .then((mod) => mod.runCLI())
+  .catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });

package/dist/cli.d.ts

@@ -1 +1 @@
-export {};
+export declare function runCLI(argv?: string[]): Promise<void>;