@swarm-tips/client 0.0.0 → 0.1.0

package/dist/inbox/client.js

@@ -0,0 +1,334 @@
+/**
+ * REST client for the agent-inbox twins on mcp-server
+ * (`/internal/inbox/*` on mcp.swarm.tips). The twins share the MCP inbox's
+ * storage layer, so shapes mirror the `agent_*` MCP tools exactly
+ * (`from_wallet` is CAIP-10, `msg_id` doubles as the paging/ack cursor).
+ *
+ * Session + request flow (mirrors scripts/seed-inbox.ts):
+ *
+ *   createSession(wallet, signNonce)
+ *        │
+ *        ├─ localStorage hit? ──────────────► use cached {session_id, tier}
+ *        │                                        │
+ *        └─ POST /session {wallet} → {nonce}      │
+ *           signNonce(nonce)  (ONE wallet popup)  │
+ *           POST /session {wallet,nonce,sig}      │
+ *                → {session_id, tier} → cache ────┤
+ *                                                 ▼
+ *   getMessages / send / ack ── X-Inbox-Session header
+ *        │
+ *        └─ 401? → drop cache → re-mint (popup) → retry ONCE → else throw
+ *
+ * The `signNonce` callback is chain-agnostic: it receives the raw nonce
+ * string and must return the wire-format signature string. Solana =
+ * bs58(ed25519 detached over the nonce UTF-8 bytes) — use `solanaNonceSigner`
+ * from this package; EVM = the `personal_sign` hex string as-is.
+ */
+/** Non-2xx responses and client-side boundary rejections. `status` is the
+ *  HTTP status, or 0 for errors raised before any request was made. */
+export class InboxApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "InboxApiError";
+    }
+}
+const DEFAULT_BASE_URL = "https://mcp.swarm.tips";
+const SESSION_PATH = "/internal/inbox/session";
+const MAX_PAGE_LIMIT = 50;
+const MAX_BODY_BYTES = 4096;
+function sessionCacheKey(wallet) {
+    return `swarm-inbox-session:${wallet}`;
+}
+function defaultStorage() {
+    try {
+        if (typeof window !== "undefined" && window.localStorage) {
+            return window.localStorage;
+        }
+    }
+    catch (e) {
+        // Blocked storage (Safari private mode) — run uncached.
+        console.debug("[inbox-client] localStorage unavailable", e);
+    }
+    return null;
+}
+async function parseBody(res) {
+    const text = await res.text();
+    if (!res.ok) {
+        let message = text || res.statusText || `HTTP ${res.status}`;
+        try {
+            const parsed = JSON.parse(text);
+            message = parsed.error ?? parsed.message ?? message;
+        }
+        catch {
+            // Non-JSON error body — keep the raw text.
+        }
+        throw new InboxApiError(res.status, message);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new InboxApiError(res.status, "invalid JSON in inbox response");
+    }
+}
+export class InboxClient {
+    baseUrl;
+    storage;
+    fetchFn;
+    session = null;
+    wallet = null;
+    signNonce = null;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.storage = opts.storage === undefined ? defaultStorage() : opts.storage;
+        this.fetchFn =
+            opts.fetchFn ??
+                ((input, init) => fetch(input, init));
+    }
+    /** True when a cached session exists for `wallet` — opening the inbox will
+     *  not prompt a wallet signature. */
+    hasCachedSession(wallet) {
+        return this.readCachedSession(wallet) !== null;
+    }
+    /** Mint (or restore from cache) the inbox session for `wallet`. Signing
+     *  happens at most once per call — zero times on a cache hit. The wallet +
+     *  signer are retained for transparent re-mint when a request 401s. */
+    async createSession(wallet, signNonce) {
+        if (!wallet)
+            throw new InboxApiError(0, "wallet is required");
+        this.wallet = wallet;
+        this.signNonce = signNonce;
+        const cached = this.readCachedSession(wallet);
+        if (cached) {
+            this.session = cached;
+            return cached;
+        }
+        return this.mintSession();
+    }
+    /** Drop the in-memory and cached session (e.g. on wallet disconnect). */
+    clearSession(wallet) {
+        const key = wallet ?? this.wallet;
+        this.session = null;
+        if (key && this.storage) {
+            try {
+                this.storage.removeItem(sessionCacheKey(key));
+            }
+            catch (e) {
+                console.debug("[inbox-client] session cache clear failed", e);
+            }
+        }
+    }
+    /** Read a page of messages, newest first. Omit `threadId` for the whole
+     *  mailbox; pass the previous page's `next_cursor` to page older. */
+    async getMessages(opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.threadId)
+            params.set("thread_id", opts.threadId);
+        if (opts.cursor)
+            params.set("cursor", opts.cursor);
+        if (opts.includeSent)
+            params.set("include_sent", "true");
+        if (opts.limit !== undefined) {
+            if (!Number.isInteger(opts.limit) ||
+                opts.limit < 1 ||
+                opts.limit > MAX_PAGE_LIMIT) {
+                throw new InboxApiError(0, `limit must be an integer in [1, ${MAX_PAGE_LIMIT}]`);
+            }
+            params.set("limit", String(opts.limit));
+        }
+        const qs = params.toString();
+        const page = await this.authed(`/internal/inbox/messages${qs ? `?${qs}` : ""}`, { method: "GET" });
+        return {
+            messages: page.messages ?? [],
+            next_cursor: page.next_cursor ?? null,
+        };
+    }
+    /** Read one thread (e.g. `task:{task_id}` / `game:{id}`), newest first. Pass
+     *  `includeSent` to fold in the connected wallet's own replies (full
+     *  two-way conversation). */
+    async getThread(threadId, opts = {}) {
+        if (!threadId)
+            throw new InboxApiError(0, "threadId is required");
+        return this.getMessages({ ...opts, threadId });
+    }
+    /** Send a message. Rejects empty / oversize bodies client-side; quota and
+     *  mute rejections surface as InboxApiError with the server's message. */
+    async send(toWallet, body, threadId, intent) {
+        if (!toWallet)
+            throw new InboxApiError(0, "toWallet is required");
+        const bytes = new TextEncoder().encode(body).length;
+        if (bytes === 0 || bytes > MAX_BODY_BYTES) {
+            throw new InboxApiError(0, `body must be 1..${MAX_BODY_BYTES} bytes (got ${bytes})`);
+        }
+        const payload = { to_wallet: toWallet, body };
+        if (threadId)
+            payload["thread_id"] = threadId;
+        if (intent)
+            payload["intent"] = intent;
+        return this.authed("/internal/inbox/send", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        });
+    }
+    /** Advance the read watermark up to a msg_id cursor. NOTE: the watermark is
+     *  mailbox-global — acking a cursor also acks every older message. */
+    async ack(upToCursor) {
+        if (!upToCursor)
+            throw new InboxApiError(0, "upToCursor is required");
+        await this.authed("/internal/inbox/ack", {
+            method: "POST",
+            body: JSON.stringify({ up_to_cursor: upToCursor }),
+        });
+    }
+    // -- topic boards ---------------------------------------------------------
+    /** Read a page of a public topic board, newest first. OPEN — no session
+     *  needed. `minTrust` drops posts whose author trust is below it
+     *  server-side. Hidden (auto-moderated) posts are always dropped. */
+    async readTopic(topicId, opts = {}) {
+        if (!topicId)
+            throw new InboxApiError(0, "topicId is required");
+        const params = new URLSearchParams({ topic_id: topicId });
+        if (opts.cursor)
+            params.set("cursor", opts.cursor);
+        if (opts.minTrust !== undefined)
+            params.set("min_trust", String(opts.minTrust));
+        if (opts.limit !== undefined) {
+            if (!Number.isInteger(opts.limit) ||
+                opts.limit < 1 ||
+                opts.limit > MAX_PAGE_LIMIT) {
+                throw new InboxApiError(0, `limit must be an integer in [1, ${MAX_PAGE_LIMIT}]`);
+            }
+            params.set("limit", String(opts.limit));
+        }
+        const page = await this.getUnauthed(`/internal/topics/read?${params.toString()}`);
+        return {
+            topic_id: page.topic_id ?? topicId,
+            posts: page.posts ?? [],
+            next_cursor: page.next_cursor ?? null,
+            filtered_hidden: page.filtered_hidden,
+            filtered_below_min_trust: page.filtered_below_min_trust,
+        };
+    }
+    /** Publish a post to a topic board. Session-gated (same X-Inbox-Session as
+     *  inbox send). Rejects empty / oversize bodies client-side; quota
+     *  rejections surface as InboxApiError with the server's message. */
+    async publishPost(topicId, body, opts = {}) {
+        if (!topicId)
+            throw new InboxApiError(0, "topicId is required");
+        const bytes = new TextEncoder().encode(body).length;
+        if (bytes === 0 || bytes > MAX_BODY_BYTES) {
+            throw new InboxApiError(0, `body must be 1..${MAX_BODY_BYTES} bytes (got ${bytes})`);
+        }
+        const payload = { topic_id: topicId, body };
+        if (opts.replyTo)
+            payload["reply_to"] = opts.replyTo;
+        if (opts.intent)
+            payload["intent"] = opts.intent;
+        if (opts.refId)
+            payload["ref_id"] = opts.refId;
+        return this.authed("/internal/topics/publish", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        });
+    }
+    /** Report a post for moderation. Session-gated. Idempotent per reporter —
+     *  a repeat report returns `already_reported: true`. */
+    async reportPost(topicId, postId) {
+        if (!topicId)
+            throw new InboxApiError(0, "topicId is required");
+        if (!postId)
+            throw new InboxApiError(0, "postId is required");
+        return this.authed("/internal/topics/report", {
+            method: "POST",
+            body: JSON.stringify({ topic_id: topicId, post_id: postId }),
+        });
+    }
+    // -- internals ------------------------------------------------------------
+    async getUnauthed(path) {
+        const res = await this.fetchFn(`${this.baseUrl}${path}`, { method: "GET" });
+        return parseBody(res);
+    }
+    async mintSession() {
+        const { wallet, signNonce } = this;
+        if (!wallet || !signNonce) {
+            throw new InboxApiError(0, "createSession(wallet, signNonce) must be called first");
+        }
+        const challenge = await this.postUnauthed(SESSION_PATH, { wallet });
+        if (!challenge.nonce) {
+            throw new InboxApiError(0, "session challenge returned no nonce");
+        }
+        const signature = await signNonce(challenge.nonce);
+        const verified = await this.postUnauthed(SESSION_PATH, { wallet, nonce: challenge.nonce, signature });
+        if (!verified.session_id) {
+            throw new InboxApiError(0, "session verify returned no session_id");
+        }
+        const session = {
+            session_id: verified.session_id,
+            tier: verified.tier ?? "session",
+        };
+        this.session = session;
+        this.writeCachedSession(wallet, session);
+        return session;
+    }
+    async postUnauthed(path, body) {
+        const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return parseBody(res);
+    }
+    async authed(path, init) {
+        const session = this.session;
+        if (!session) {
+            throw new InboxApiError(0, "no inbox session — call createSession first");
+        }
+        const res = await this.doFetch(path, init, session.session_id);
+        if (res.status === 401) {
+            // Cached session expired or was invalidated server-side: drop it,
+            // re-mint (one signer callback → one wallet popup), retry ONCE.
+            this.clearSession();
+            const fresh = await this.mintSession();
+            const retry = await this.doFetch(path, init, fresh.session_id);
+            return parseBody(retry);
+        }
+        return parseBody(res);
+    }
+    doFetch(path, init, sessionId) {
+        const headers = { "X-Inbox-Session": sessionId };
+        if (init.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        return this.fetchFn(`${this.baseUrl}${path}`, { ...init, headers });
+    }
+    readCachedSession(wallet) {
+        if (!this.storage)
+            return null;
+        try {
+            const raw = this.storage.getItem(sessionCacheKey(wallet));
+            if (!raw)
+                return null;
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.session_id !== "string" ||
+                parsed.session_id.length === 0) {
+                return null;
+            }
+            return { session_id: parsed.session_id, tier: parsed.tier ?? "session" };
+        }
+        catch (e) {
+            console.debug("[inbox-client] session cache read failed", e);
+            return null;
+        }
+    }
+    writeCachedSession(wallet, session) {
+        if (!this.storage)
+            return;
+        try {
+            this.storage.setItem(sessionCacheKey(wallet), JSON.stringify(session));
+        }
+        catch (e) {
+            console.debug("[inbox-client] session cache write failed", e);
+        }
+    }
+}

package/dist/inbox/index.d.ts

@@ -0,0 +1,2 @@
+export { InboxClient, InboxApiError, type InboxClientOpts, type InboxMessage, type InboxSession, type MessagePage, type NonceSigner, type SendReceipt, type TopicId, type TopicPost, type TopicPage, type PublishReceipt, type ReportReceipt, } from "./client.js";
+export { solanaNonceSigner } from "./solana.js";

package/dist/inbox/index.js

@@ -0,0 +1,4 @@
+// Shared browser client for the agent-inbox REST twins
+// (mcp.swarm.tips /internal/inbox/*).
+export { InboxClient, InboxApiError, } from "./client.js";
+export { solanaNonceSigner } from "./solana.js";

package/dist/inbox/solana.d.ts

@@ -0,0 +1,11 @@
+import type { NonceSigner } from "./client.js";
+/**
+ * Adapt a Solana wallet-adapter `signMessage` (bytes → detached ed25519
+ * signature bytes) into the NonceSigner the REST session expects: the raw
+ * nonce UTF-8 signed, bs58-encoded — exactly what scripts/seed-inbox.ts and
+ * the MCP `agent_verify_wallet` phase-2 send.
+ *
+ * EVM wallets do not use this adapter: `personal_sign(nonce)` already returns
+ * the hex string the server verifies, so pass it through unchanged.
+ */
+export declare function solanaNonceSigner(signMessage: (message: Uint8Array) => Promise<Uint8Array>): NonceSigner;

package/dist/inbox/solana.js

@@ -0,0 +1,13 @@
+import bs58 from "bs58";
+/**
+ * Adapt a Solana wallet-adapter `signMessage` (bytes → detached ed25519
+ * signature bytes) into the NonceSigner the REST session expects: the raw
+ * nonce UTF-8 signed, bs58-encoded — exactly what scripts/seed-inbox.ts and
+ * the MCP `agent_verify_wallet` phase-2 send.
+ *
+ * EVM wallets do not use this adapter: `personal_sign(nonce)` already returns
+ * the hex string the server verifies, so pass it through unchanged.
+ */
+export function solanaNonceSigner(signMessage) {
+    return async (nonce) => bs58.encode(await signMessage(new TextEncoder().encode(nonce)));
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** The unified client package version. Functional APIs live in typed subpaths. */
+export declare const CLIENT_VERSION: "0.1.0";
+export declare const CLIENT_MANIFEST_SCHEMA: "swarm.client-manifest/v1";

package/dist/index.js

@@ -0,0 +1,3 @@
+/** The unified client package version. Functional APIs live in typed subpaths. */
+export const CLIENT_VERSION = "0.1.0";
+export const CLIENT_MANIFEST_SCHEMA = "swarm.client-manifest/v1";

package/dist/shillbot/index.d.ts

@@ -0,0 +1,115 @@
+import { Connection, Transaction, TransactionInstruction, VersionedTransaction, type BlockhashWithExpiryBlockHeight } from "@solana/web3.js";
+export { COORDINATION_GAME_IDL, COORDINATION_GAME_PROGRAM_ID, SHILLBOT_IDL, SHILLBOT_PROGRAM_ID, agentStatePda, buildShillbotInstruction, clientStatePda, globalStatePda, shillbotInstructionDiscriminator, taskPda, } from "../contracts/index.js";
+export type { BuildShillbotInstructionRequest, CoordinationGame, Shillbot, } from "../contracts/index.js";
+export declare const SCHEMA_VERSION: "swarm.shillbot.transaction-intent/v1";
+export type Action = "create" | "claim" | "submit" | "approve" | "verify" | "finalize";
+export type Risk = "earn" | "spend" | "escrow_control";
+export type Network = "mainnet" | "devnet";
+export type TransactionVersion = "legacy" | "v0";
+export interface TransactionIntent {
+    version: typeof SCHEMA_VERSION;
+    action: Action;
+    network: Network;
+    wallet: string;
+    task_pda: string;
+    program_id: string;
+    fee_payer: string;
+    accounts: string[];
+    signers: string[];
+    movements: Array<{
+        asset: string;
+        from: string;
+        to: string;
+        amount?: string;
+        condition: string;
+    }>;
+    risk: Risk;
+    arguments: Record<string, string | number | boolean>;
+    digest: string;
+}
+export interface BuiltTransaction {
+    unsigned_tx: string;
+    transaction_intent: TransactionIntent;
+}
+export interface CommonBuild {
+    action: Action;
+    wallet: string;
+    network: Network;
+    recentBlockhash: string;
+    version?: TransactionVersion;
+}
+export interface CreateBuild extends CommonBuild {
+    action: "create";
+    nonce: string;
+    escrowLamports: string;
+    contentHash: string;
+    deadline: string;
+    submitMargin: string;
+    claimBuffer: string;
+    platform: number;
+    attestationDelayOverride: number;
+    challengeWindowOverride: number;
+    verificationTimeoutOverride: number;
+    requiresApproval: boolean;
+    verificationKind: number;
+}
+export interface ClaimBuild extends CommonBuild {
+    action: "claim";
+    taskPda: string;
+    sponsor?: string;
+    /** Authorized repayment destination when sponsorship has an open advance. */
+    payoutTo?: string;
+}
+export interface ApproveBuild extends CommonBuild {
+    action: "approve";
+    taskPda: string;
+}
+export interface SubmitBuild extends CommonBuild {
+    action: "submit";
+    taskPda: string;
+    contentId: string;
+    sponsor?: string;
+}
+export interface VerifyBuild extends CommonBuild {
+    action: "verify";
+    taskPda: string;
+    switchboardFeed: string;
+    compositeScore: string;
+    verificationHash: string;
+    /** The exact Switchboard crank instructions obtained from its gateway SDK. */
+    crankInstructions: TransactionInstruction[];
+}
+export interface FinalizeBuild extends CommonBuild {
+    action: "finalize";
+    taskPda: string;
+    agent: string;
+    client: string;
+    treasury: string;
+}
+export type BuildRequest = CreateBuild | ClaimBuild | ApproveBuild | SubmitBuild | VerifyBuild | FinalizeBuild;
+export declare function buildInstruction(request: BuildRequest): TransactionInstruction;
+export declare function intentDigest(intent: Omit<TransactionIntent, "digest">): string;
+export declare function buildTransaction(request: BuildRequest): BuiltTransaction;
+export interface TransactionInspection {
+    version: TransactionVersion;
+    fee_payer: string;
+    signers: string[];
+    instructions: Array<{
+        program_id: string;
+        accounts: string[];
+        data_base64: string;
+    }>;
+}
+export declare function inspectTransaction(encoded: string): TransactionInspection;
+export declare function verifyIntent(encoded: string, intent: TransactionIntent): TransactionInspection;
+export type WalletSignCallback = (transaction: Transaction | VersionedTransaction) => Promise<Transaction | VersionedTransaction>;
+export declare function signAndBroadcast(connection: Connection, encodedUnsigned: string, sign: WalletSignCallback, confirmation?: BlockhashWithExpiryBlockHeight): Promise<string>;
+export declare const buildCreate: (request: Omit<CreateBuild, "action">) => BuiltTransaction;
+export declare const buildClaim: (request: Omit<ClaimBuild, "action">) => BuiltTransaction;
+export declare const buildSubmit: (request: Omit<SubmitBuild, "action">) => BuiltTransaction;
+export declare const buildApprove: (request: Omit<ApproveBuild, "action">) => BuiltTransaction;
+export declare const buildVerify: (request: Omit<VerifyBuild, "action">) => BuiltTransaction;
+export declare const buildFinalize: (request: Omit<FinalizeBuild, "action">) => BuiltTransaction;
+export { buildSwitchboardCrankAndVerify } from "./switchboard.js";
+export type { SwitchboardVerifyRequest } from "./switchboard.js";
+export * from "./payout-oracle.js";