@dopamint-fun/open-sdk 0.1.0-dev.0

package/dist/tour.js

@@ -0,0 +1,129 @@
+/* Entering a tour and playing the seat it gives you, on a self-held key.
+ *
+ * This is the tour door, and it is not the offer door `session.ts` drives. An
+ * offer is a match somebody else already composed and invited this agent into,
+ * so it needs a table owner in the loop and it is played over the Participant
+ * Session at the authority. A tour seats the agent from a queue with nobody
+ * proposing anything, and it is played over the Product API - so there is no
+ * session base url, coordinator key or time-authority key to obtain here.
+ *
+ * Every request carries a freshly minted `AgentHttpCapability`. The nonce is
+ * single-use and the server records it, so a capability is never reused across
+ * two requests even inside its own validity window.
+ */
+import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
+import { textBytes } from "./bytes.js";
+/** One signed Product API call. `target` is origin-form, exactly as the server
+ *  will reconstruct it - a leading-slash path plus any query string. */
+async function signedFetch(client, method, target, body) {
+    const payload = body === undefined ? new Uint8Array() : textBytes(JSON.stringify(body));
+    const binding = {
+        method,
+        requestTarget: target,
+        body: payload,
+    };
+    const { header } = await mintAgentHttpCapability(client.agent, client.agentId, binding);
+    const headers = {
+        [AGENT_HTTP_CAPABILITY_HEADER]: header,
+    };
+    if (body !== undefined)
+        headers["content-type"] = "application/json";
+    const response = await fetch(`${client.productUrl.replace(/\/$/, "")}${target}`, {
+        method,
+        headers,
+        // The signature covers these exact bytes, so the body must be sent
+        // verbatim rather than re-serialized by fetch from an object.
+        body: body === undefined ? undefined : payload,
+    });
+    const text = await response.text();
+    return {
+        status: response.status,
+        json: text.length === 0 ? undefined : JSON.parse(text),
+    };
+}
+export async function enterTour(client, tour) {
+    const target = tour === "playground"
+        ? "/open/v1/tours/playground/entries"
+        : "/open/v1/tours/tournament/entries";
+    const { status, json } = await signedFetch(client, "POST", target);
+    if (status !== 200)
+        throw new Error(`tour entry refused (${status}): ${JSON.stringify(json)}`);
+    return json;
+}
+/** Enter and poll until seated.
+ *
+ *  Waiting is the normal answer, not a failure: the playground holds a place
+ *  for real opponents and only house-fills the leftover seats once the wait
+ *  elapses, so an agent that gives up early is the reason a table stays short.
+ *  The default timeout therefore outlasts the server's own fill wait. */
+export async function queueUntilSeated(client, tour, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const pollMs = options.pollMs ?? 3_000;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const entry = await enterTour(client, tour);
+        if (entry.state === "seated" || entry.state === "offered")
+            return entry;
+        if (entry.state !== "waiting")
+            throw new Error(`tour is not open: ${JSON.stringify(entry)}`);
+        options.onWaiting?.(entry);
+        if (Date.now() >= deadline)
+            throw new Error(`still waiting for a seat after ${timeoutMs} ms; the tour fills at ${entry.fillAtMs}`);
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+}
+export async function readPosition(client, tableId) {
+    const { status, json } = await signedFetch(client, "GET", `/open/v1/tables/${tableId}/decision`);
+    if (status !== 200)
+        throw new Error(`decision read refused (${status}): ${JSON.stringify(json)}`);
+    return json;
+}
+export async function act(client, tableId, move) {
+    const { status, json } = await signedFetch(client, "POST", `/open/v1/tables/${tableId}/actions`, move);
+    if (status !== 200)
+        throw new Error(`action refused (${status}): ${JSON.stringify(json)}`);
+    return json;
+}
+/** The reference strategy: never wager, call only what is free. It exists so
+ *  the journey can be demonstrated end to end, not because it plays well - an
+ *  agent that reasons about the hand replaces `decide`. */
+export function foldHeavy(turn) {
+    if (turn.canCheck)
+        return { action: "check" };
+    if (turn.callAmount === 0 && turn.canCall)
+        return { action: "call" };
+    return { action: turn.canFold ? "fold" : "check" };
+}
+/** Drive a seated tour table to a terminal disposition.
+ *
+ *  A lapsed turn is not an error: the authority acts for a silent seat on its
+ *  own clock, so a slow decision costs the hand rather than the match, and the
+ *  loop keeps reading. Only a refusal the server calls terminal stops it. */
+export async function playTour(client, tableId, decide = foldHeavy, options = {}) {
+    const pollMs = options.pollMs ?? 1_000;
+    let committedActions = 0;
+    const hands = new Set();
+    for (;;) {
+        const turn = await readPosition(client, tableId);
+        if (turn.state === "complete" || turn.state === "eliminated")
+            return { outcome: turn.state, committedActions, hands: hands.size };
+        if (turn.state !== "your_turn") {
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+            continue;
+        }
+        if (turn.handIndex !== undefined)
+            hands.add(turn.handIndex);
+        const move = decide(turn);
+        options.onTurn?.(turn, move);
+        try {
+            await act(client, tableId, move);
+            committedActions += 1;
+        }
+        catch (error) {
+            // 409 is the turn clock having resolved this seat already. Re-read
+            // rather than abort: the match continues without this action.
+            if (!(error instanceof Error) || !error.message.includes("(409)"))
+                throw error;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@dopamint-fun/open-sdk",
+  "version": "0.1.0-dev.0",
+  "description": "DOPA-OPEN client SDK: generate and hold your own agent key, sign registrations, and play a Participant Session",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CommandOSSLabs/dopamint-arena.git",
+    "directory": "libs/dopa-open-client-ts"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "dopa-open": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test --test-isolation=none \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@mysten/sui": "^2.20.1",
+    "@noble/hashes": "^2.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3"
+  }
+}