project-cpu-mcp 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 projectcpu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# project-cpu-mcp
+
+MCP (Model Context Protocol) server for **Project CPU** — a blockchain game on EVM. It lets an
+AI agent play on your behalf: read the world map, reveal cells, build and mine, craft, move
+resources, trade at marketplaces, and cash out to on-chain $CPU. Runs locally over stdio and is distributed via npm, so
+you start it with a single `npx` command from any MCP client.
+
+## Installation
+
+Pick your client below and add the server. The only required setting is your wallet's `PRIVATE_KEY` (`0x` + 64 hex chars) — replace `0x…` with yours.
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add project-cpu -s user -e PRIVATE_KEY=0x… -- npx -y project-cpu-mcp@latest
+```
+
+- `-s user` installs it across all your projects; omit it (or use `-s local`) for the current project only.
+- `-e PRIVATE_KEY=…` sets the required env var; `--` separates Claude's flags from the server command.
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`), then restart the app:
+
+```json
+{
+  "mcpServers": {
+    "project-cpu": {
+      "command": "npx",
+      "args": ["-y", "project-cpu-mcp@latest"],
+      "env": { "PRIVATE_KEY": "0x…" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (this project):
+
+```json
+{
+  "mcpServers": {
+    "project-cpu": {
+      "command": "npx",
+      "args": ["-y", "project-cpu-mcp@latest"],
+      "env": { "PRIVATE_KEY": "0x…" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code (Copilot agent mode)</strong></summary>
+
+Create `.vscode/mcp.json` — VS Code prompts for the key at startup instead of storing it:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "privateKey", "description": "Project CPU private key", "password": true }
+  ],
+  "servers": {
+    "project-cpu": {
+      "command": "npx",
+      "args": ["-y", "project-cpu-mcp@latest"],
+      "env": { "PRIVATE_KEY": "${input:privateKey}" }
+    }
+  }
+}
+```
+
+(In user `settings.json`, wrap the whole object in an `"mcp": { … }` key.)
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`, then restart Windsurf:
+
+```json
+{
+  "mcpServers": {
+    "project-cpu": {
+      "command": "npx",
+      "args": ["-y", "project-cpu-mcp@latest"],
+      "env": { "PRIVATE_KEY": "0x…" }
+    }
+  }
+}
+```
+
+</details>
+
+Every command above pins `@latest`, so restarting the server is how you update — `npx` re-resolves the registry on each launch. The server also watches for new releases on its own: a backwards-compatible one is mentioned once in a tool's response, a breaking one blocks every tool until you restart.
+
+## Environment variables
+
+**Required**
+
+| Variable | Description |
+| --- | --- |
+| `PRIVATE_KEY` | Your wallet private key — `0x` followed by 64 hex chars (32 bytes). |
+
+**Optional** — has a sensible default; normal users can omit it.
+
+| Variable | Default | When you need it |
+| --- | --- | --- |
+| `RPC_URL` | chain's public RPC | A custom RPC endpoint for sending on-chain transactions (e.g. `cpu_reveal`). |
+
+Session state (JWT / session keys) is persisted to `~/.project-cpu/`.
+
+## What the agent can do
+
+Once connected, the server exposes tools grouped by area:
+
+- **Session** — `cpu_authenticate`, `cpu_get_game_config` (static rulebook: resources, costs, contract
+  addresses), `cpu_get_balance` (spendable $CPU + gas).
+- **World** — `cpu_get_map`, `cpu_get_cell`, `cpu_get_changes` (react to other players),
+  `cpu_get_attention` (your owner-scoped to-do list).
+- **Reveal & build** — `cpu_reveal` (surface a cell's deposits on-chain), `cpu_build` (place a
+  building), `cpu_demolish`, `cpu_start_mining` (an extractor then mines a batch of the resource each
+  cycle), `cpu_get_mining_status`, `cpu_claim_mining`.
+- **Transport** — `cpu_route_network` (the waypoint road map: nodes, legal hops, gaps),
+  `cpu_next_hops` (survey the legal waypoints around a cell) — both take the cargo `resourceId` and show
+  the exact per-hub transit fee for it — `cpu_quote_transport`, `cpu_transport`,
+  `cpu_get_transport_status`, `cpu_list_my_transports`, `cpu_finalize_delivery`.
+- **Crafting** — `cpu_list_recipes`, `cpu_craft`, `cpu_get_craft_status`, `cpu_claim_craft`.
+- **Trading** — `cpu_get_markets`, `cpu_list_lots`, `cpu_get_lot`, `cpu_quote_buy`, `cpu_buy_lot`, `cpu_create_lot`,
+  `cpu_cancel_lot`, `cpu_list_my_lots`, and `cpu_set_sale_fee` (a hub owner sets the per-resource sale-fee
+  rate on their own hub). See [CONTEXT.md](./CONTEXT.md) for the fee vocabulary.
+- **Syndicates** — `cpu_list_syndicates` (browse the registry by name/size, sort, page), `cpu_get_syndicate`
+  (one syndicate's card plus a page of its members), `cpu_get_syndicate_membership` (check an address's
+  membership, defaults to your own), `cpu_join_syndicate` (join by id for same-clan discounts; reports your
+  exit cooldown), `cpu_leave_syndicate` (leave after the cooldown; re-join anywhere immediately),
+  `cpu_create_syndicate` (found your own — name, link, four rates, optional manager — you auto-join),
+  `cpu_set_syndicate_params` (replace your syndicate's full parameters — no partial patches), and
+  `cpu_transfer_syndicate_manager` (hand the manager role and its tax stream to a successor, irreversible).
+  See [CONTEXT.md](./CONTEXT.md) for the syndicate vocabulary.
+- **Tokens** — `cpu_quote_swap`, `cpu_swap` (trade ETH ↔ $CPU on the token pool), `cpu_withdraw` (cash a
+  cell's wCPU out to on-chain $CPU, 1:1).
+
+Paid routes and on-chain actions are settled automatically; always check `cpu_get_balance` before
+a paid action.
+
+## Requirements
+
+- Node.js ≥ 20
+
+## License
+
+[MIT](./LICENSE)

package/dist/api/client.d.ts

@@ -0,0 +1,38 @@
+import { type ApiClientOptions, type ApiResponse, type IAuthenticator, type ServerHealthView } from './types.js';
+import type { SessionManager } from '../session/manager.js';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface RequestOptions {
+    method: HttpMethod;
+    body: unknown | null;
+}
+export declare class ApiClient {
+    private readonly baseUrl;
+    private readonly session;
+    private readonly logger;
+    private authenticator;
+    private serverReachable;
+    private serverDownReason;
+    constructor(options: ApiClientOptions);
+    setAuthenticator(authenticator: IAuthenticator): void;
+    /**
+     * Low-level request without auth. Use for public endpoints (SIWE nonce/verify, device flow).
+     */
+    request<T>(path: string, options?: RequestOptions | null): Promise<ApiResponse<T>>;
+    /**
+     * The outcome is kept out of the reachability signal: this may target an endpoint an older server
+     * does not serve at all, which says nothing about the API being up.
+     */
+    requestWithTimeout<T>(path: string, timeoutMs: number): Promise<ApiResponse<T>>;
+    /**
+     * Request with a `Authorization: Bearer <jwt>` header. The token is obtained from the
+     * authenticator (which (re-)logs in when missing/expired). On a 401 the authenticator is
+     * asked to re-authenticate and the request is retried exactly once.
+     */
+    authenticatedRequest<T>(path: string, options?: RequestOptions | null): Promise<ApiResponse<T>>;
+    private send;
+    private setReachable;
+    getServerHealth(): ServerHealthView;
+    getBaseUrl(): string;
+    getSession(): SessionManager;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAEhB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACxB;AAED,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,gBAAgB,CAAuB;gBAEnC,OAAO,EAAE,gBAAgB;IAMrC,gBAAgB,CAAC,aAAa,EAAE,cAAc,GAAG,IAAI;IAIrD;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAc,GAAG,IAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI9F;;;OAGG;IACG,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAIrF;;;;OAIG;IACG,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAc,GAAG,IAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAoB7F,IAAI;IAyDlB,OAAO,CAAC,YAAY;IAapB,eAAe,IAAI,gBAAgB;IAInC,UAAU,IAAI,MAAM;IAIpB,UAAU,IAAI,cAAc;CAG/B"}

package/dist/api/client.js

@@ -0,0 +1,116 @@
+import { parseJsonBody } from './response.utils.js';
+import { HttpStatus, } from './types.js';
+import { errorMessage } from '../utils/error.utils.js';
+export class ApiClient {
+    baseUrl;
+    session;
+    logger;
+    authenticator = null;
+    serverReachable = true;
+    serverDownReason = null;
+    constructor(options) {
+        this.baseUrl = options.baseUrl;
+        this.session = options.session;
+        this.logger = options.logger;
+    }
+    setAuthenticator(authenticator) {
+        this.authenticator = authenticator;
+    }
+    /**
+     * Low-level request without auth. Use for public endpoints (SIWE nonce/verify, device flow).
+     */
+    async request(path, options = null) {
+        return this.send(path, options?.method ?? 'GET', options?.body ?? null, null);
+    }
+    /**
+     * The outcome is kept out of the reachability signal: this may target an endpoint an older server
+     * does not serve at all, which says nothing about the API being up.
+     */
+    async requestWithTimeout(path, timeoutMs) {
+        return this.send(path, 'GET', null, null, timeoutMs, false);
+    }
+    /**
+     * Request with a `Authorization: Bearer <jwt>` header. The token is obtained from the
+     * authenticator (which (re-)logs in when missing/expired). On a 401 the authenticator is
+     * asked to re-authenticate and the request is retried exactly once.
+     */
+    async authenticatedRequest(path, options = null) {
+        if (!this.authenticator) {
+            throw new Error('ApiClient: no authenticator configured for authenticated requests');
+        }
+        const method = options?.method ?? 'GET';
+        const body = options?.body ?? null;
+        const token = await this.authenticator.getAccessToken();
+        const first = await this.send(path, method, body, { Authorization: `Bearer ${token}` });
+        if (first.status !== HttpStatus.Unauthorized) {
+            return first;
+        }
+        this.logger.warn('authenticated request got 401 — re-authenticating and retrying once', { path });
+        const fresh = await this.authenticator.reauthenticate();
+        return this.send(path, method, body, { Authorization: `Bearer ${fresh}` });
+    }
+    async send(path, method, body, extraHeaders, timeoutMs = null, trackHealth = true) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            ...(extraHeaders ?? {}),
+        };
+        const init = { method, headers };
+        if (timeoutMs !== null) {
+            init.signal = AbortSignal.timeout(timeoutMs);
+        }
+        if (body !== undefined && body !== null) {
+            init.body = JSON.stringify(body);
+        }
+        this.logger.debug('api request', { method, path });
+        let response;
+        try {
+            response = await fetch(url, init);
+        }
+        catch (error) {
+            if (trackHealth) {
+                this.setReachable(false, errorMessage(error));
+            }
+            throw new Error(`Cannot reach the game API at ${this.baseUrl} — the server is likely down or unreachable. ` +
+                `Retry shortly. (${errorMessage(error)})`);
+        }
+        let data;
+        try {
+            data = await parseJsonBody(response);
+        }
+        catch (error) {
+            if (trackHealth) {
+                this.setReachable(false, errorMessage(error));
+            }
+            throw error;
+        }
+        if (trackHealth) {
+            this.setReachable(true, null);
+        }
+        this.logger.debug('api response', { method, path, status: response.status });
+        return { status: response.status, data };
+    }
+    setReachable(reachable, reason) {
+        const changed = this.serverReachable !== reachable;
+        this.serverReachable = reachable;
+        this.serverDownReason = reachable ? null : reason;
+        if (changed) {
+            if (reachable) {
+                this.logger.info('game API reachable again');
+            }
+            else {
+                this.logger.warn('game API unreachable', { reason });
+            }
+        }
+    }
+    getServerHealth() {
+        return { reachable: this.serverReachable, reason: this.serverDownReason };
+    }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    getSession() {
+        return this.session;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/api/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const RESPONSE_BODY_SNIPPET_LENGTH = 200;
+export declare const HTTP_OK = 200;
+export declare const HTTP_MULTIPLE_CHOICES = 300;
+export declare const OPEN_REVEAL_REQUESTS_PATH = "/api/v1/reveal/requests";
+//# sourceMappingURL=constants.d.ts.map

package/dist/api/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/api/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAGhD,eAAO,MAAM,OAAO,MAAM,CAAC;AAC3B,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,eAAO,MAAM,yBAAyB,4BAA4B,CAAC"}

package/dist/api/constants.js

@@ -0,0 +1,8 @@
+// Max characters of a non-JSON response body echoed back in the error message — enough to identify
+// a gateway/error page without dumping a full HTML document into the agent's context.
+export const RESPONSE_BODY_SNIPPET_LENGTH = 200;
+// Inclusive lower / exclusive upper bounds of the 2xx success range.
+export const HTTP_OK = 200;
+export const HTTP_MULTIPLE_CHOICES = 300;
+export const OPEN_REVEAL_REQUESTS_PATH = '/api/v1/reveal/requests';
+//# sourceMappingURL=constants.js.map

package/dist/api/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/api/constants.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,sFAAsF;AACtF,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,qEAAqE;AACrE,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAC;AAC3B,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAyB,CAAC"}

package/dist/api/response.utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads the body once and parses it as JSON. An empty body on a 2xx response is a legitimate
+ * "no content" answer and resolves to `null`. On a non-JSON body — a down server / proxy error page
+ * (`<html>...`) — throws a clear, agent-readable error instead of letting a bare
+ * `SyntaxError: Unexpected token '<'` surface from `response.json()`.
+ */
+export declare function parseJsonBody<T>(response: Response): Promise<T>;
+export declare function describeApiError(data: unknown): string;
+//# sourceMappingURL=response.utils.d.ts.map

package/dist/api/response.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.utils.d.ts","sourceRoot":"","sources":["../../src/api/response.utils.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAerE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAMtD"}

package/dist/api/response.utils.js

@@ -0,0 +1,30 @@
+import { HTTP_MULTIPLE_CHOICES, HTTP_OK, RESPONSE_BODY_SNIPPET_LENGTH } from './constants.js';
+/**
+ * Reads the body once and parses it as JSON. An empty body on a 2xx response is a legitimate
+ * "no content" answer and resolves to `null`. On a non-JSON body — a down server / proxy error page
+ * (`<html>...`) — throws a clear, agent-readable error instead of letting a bare
+ * `SyntaxError: Unexpected token '<'` surface from `response.json()`.
+ */
+export async function parseJsonBody(response) {
+    const text = await response.text();
+    if (text.trim() === '' && response.status >= HTTP_OK && response.status < HTTP_MULTIPLE_CHOICES) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        const contentType = response.headers.get('content-type') ?? 'unknown';
+        const snippet = text.trim().replace(/\s+/g, ' ').slice(0, RESPONSE_BODY_SNIPPET_LENGTH);
+        throw new Error(`The game API returned a non-JSON response (HTTP ${response.status}, content-type "${contentType}"). ` +
+            `The server is likely down or unreachable — retry shortly. Body started: ${snippet}`);
+    }
+}
+export function describeApiError(data) {
+    if (data !== null && typeof data === 'object' && 'message' in data) {
+        const message = data.message;
+        return Array.isArray(message) ? message.map(String).join('; ') : String(message);
+    }
+    return JSON.stringify(data);
+}
+//# sourceMappingURL=response.utils.js.map

package/dist/api/response.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.utils.js","sourceRoot":"","sources":["../../src/api/response.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAE9F;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,QAAkB;IACrD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,QAAQ,CAAC,MAAM,IAAI,OAAO,IAAI,QAAQ,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QAC9F,OAAO,IAAS,CAAC;IACrB,CAAC;IACD,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACL,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,SAAS,CAAC;QACtE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,4BAA4B,CAAC,CAAC;QACxF,MAAM,IAAI,KAAK,CACX,mDAAmD,QAAQ,CAAC,MAAM,mBAAmB,WAAW,MAAM;YAClG,2EAA2E,OAAO,EAAE,CAC3F,CAAC;IACN,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC1C,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACjE,MAAM,OAAO,GAAI,IAA6B,CAAC,OAAO,CAAC;QACvD,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC"}

package/dist/api/reveal-requests.client.d.ts

@@ -0,0 +1,8 @@
+import { type IRevealRequestsReader, type OpenRevealRequestsView, type RevealRequestsClientOptions } from './types.js';
+export declare class RevealRequestsClient implements IRevealRequestsReader {
+    private readonly api;
+    private readonly logger;
+    constructor(options: RevealRequestsClientOptions);
+    listOpenRequests(owner: string): Promise<OpenRevealRequestsView>;
+}
+//# sourceMappingURL=reveal-requests.client.d.ts.map

package/dist/api/reveal-requests.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reveal-requests.client.d.ts","sourceRoot":"","sources":["../../src/api/reveal-requests.client.ts"],"names":[],"mappings":"AAIA,OAAO,EAIH,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EACnC,MAAM,YAAY,CAAC;AAIpB,qBAAa,oBAAqB,YAAW,qBAAqB;IAC9D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;gBAErB,OAAO,EAAE,2BAA2B;IAK1C,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;CA+BzE"}

package/dist/api/reveal-requests.client.js

@@ -0,0 +1,38 @@
+import { getAddress } from 'viem';
+import { OPEN_REVEAL_REQUESTS_PATH } from './constants.js';
+import { describeApiError } from './response.utils.js';
+import { apiOpenRevealRequestsSchema, HttpStatus, } from './types.js';
+import { buildQuery } from '../utils/query.utils.js';
+export class RevealRequestsClient {
+    api;
+    logger;
+    constructor(options) {
+        this.api = options.api;
+        this.logger = options.logger;
+    }
+    async listOpenRequests(owner) {
+        const address = owner.trim();
+        if (address === '') {
+            throw new Error('Cannot read open reveal requests without an owner address — an unscoped read answers with ' +
+                "every player's requests, not yours.");
+        }
+        const path = `${OPEN_REVEAL_REQUESTS_PATH}${buildQuery({ owner: address })}`;
+        const response = await this.api.request(path);
+        if (response.status !== HttpStatus.Ok) {
+            throw new Error(`Failed to read open reveal requests for ${address} (HTTP ${response.status}): ` +
+                describeApiError(response.data));
+        }
+        const parsed = apiOpenRevealRequestsSchema.parse(response.data);
+        this.logger.debug('read open reveal requests', { owner: address, count: parsed.requests.length });
+        return {
+            serverTime: parsed.serverTime,
+            requests: parsed.requests.map((request) => ({
+                requestId: request.requestId,
+                source: getAddress(request.source),
+                tokenId: request.tokenId,
+                requestedAt: request.requestedAt,
+            })),
+        };
+    }
+}
+//# sourceMappingURL=reveal-requests.client.js.map

package/dist/api/reveal-requests.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reveal-requests.client.js","sourceRoot":"","sources":["../../src/api/reveal-requests.client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACH,2BAA2B,EAC3B,UAAU,GAKb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,MAAM,OAAO,oBAAoB;IACZ,GAAG,CAAa;IAChB,MAAM,CAAU;IAEjC,YAAY,OAAoC;QAC5C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,KAAa;QAChC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACX,4FAA4F;gBACxF,qCAAqC,CAC5C,CAAC;QACN,CAAC;QAED,MAAM,IAAI,GAAG,GAAG,yBAAyB,GAAG,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC7E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAU,IAAI,CAAC,CAAC;QACvD,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CACX,2CAA2C,OAAO,UAAU,QAAQ,CAAC,MAAM,KAAK;gBAC5E,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,CACtC,CAAC;QACN,CAAC;QAED,MAAM,MAAM,GAAG,2BAA2B,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAElG,OAAO;YACH,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBACxC,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;gBAClC,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,WAAW,EAAE,OAAO,CAAC,WAAW;aACnC,CAAC,CAAC;SACN,CAAC;IACN,CAAC;CACJ"}