@swarm-tips/client 0.0.0 → 0.1.1

package/dist/evm/wallet.js

@@ -0,0 +1,182 @@
+import { createConfig } from "wagmi";
+import { injected, walletConnect } from "wagmi/connectors";
+import { createWalletClient, fallback, http as viemHttp, } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { e2eTestModeEnabled } from "./testing.js";
+/**
+ * Resilient transport: a viem `fallback` across the given RPC URLs (fails over
+ * to the next on a transient RPC error), or the chain default when none are
+ * given. Public testnet RPCs (e.g. sepolia.base.org) intermittently reject
+ * `eth_sendRawTransaction` with -32602; failover keeps commit/reveal from
+ * dying on one bad endpoint.
+ */
+function buildTransport(rpcUrls) {
+    if (rpcUrls && rpcUrls.length > 0) {
+        return fallback(rpcUrls.map((url) => viemHttp(url)));
+    }
+    return viemHttp();
+}
+/**
+ * Read an E2E test private key from a `?<param>=<0x-hex>` query param, if
+ * present (default param `evmTestWallet`). Mirrors the Solana `?testWallet=`
+ * pattern so Playwright can drive the EVM path headlessly. Returns null off the
+ * happy path (no window, missing/malformed param) AND whenever the page isn't
+ * in E2E test mode — so a crafted prod link can't activate the connector.
+ */
+export function getEvmTestWalletKey(param = "evmTestWallet") {
+    if (typeof window === "undefined")
+        return null;
+    if (!e2eTestModeEnabled())
+        return null;
+    const raw = new URLSearchParams(window.location.search).get(param);
+    if (!raw)
+        return null;
+    const hex = raw.startsWith("0x") ? raw : `0x${raw}`;
+    // A secp256k1 private key is 32 bytes → 64 hex chars after the 0x prefix.
+    if (!/^0x[0-9a-fA-F]{64}$/.test(hex)) {
+        console.error("[evm-kit] ignoring malformed test wallet param");
+        return null;
+    }
+    return hex;
+}
+/**
+ * Read an E2E RPC override from `?evmRpc=<https-url>`. Lets Playwright point the
+ * page at a reliable provider (e.g. QuickNode) WITHOUT baking the key into the
+ * public bundle. Caller gates this to test mode (test wallet present) so a
+ * crafted link can't redirect a real user's wallet to a hostile RPC. Only https
+ * URLs are accepted. Also gated on E2E test mode (defense in depth — its only
+ * caller already requires a test wallet, which is itself test-mode-gated).
+ */
+export function getEvmRpcOverride(param = "evmRpc") {
+    if (typeof window === "undefined")
+        return null;
+    if (!e2eTestModeEnabled())
+        return null;
+    const raw = new URLSearchParams(window.location.search).get(param);
+    if (!raw)
+        return null;
+    try {
+        const url = new URL(raw);
+        if (url.protocol !== "https:") {
+            // Log for the same reason the malformed branch below does: a rejected
+            // override is either a hostile downgrade attempt or an e2e run pointed
+            // at http://, and silently returning null leaves no trace of either.
+            console.error(`[evm-kit] ignoring non-https evmRpc param (protocol ${url.protocol})`);
+            return null;
+        }
+        return url.toString();
+    }
+    catch {
+        console.error("[evm-kit] ignoring malformed evmRpc param");
+        return null;
+    }
+}
+/**
+ * A wagmi connector backed by a raw private key via a viem wallet client.
+ * Auto-connects and signs txs + messages without a browser extension, so
+ * Playwright can drive an EVM flow headlessly. Test-only — gated behind the
+ * test-wallet query param at config-build time.
+ */
+function evmTestConnector(key, chain, transport) {
+    const account = privateKeyToAccount(key);
+    const client = createWalletClient({ account, chain, transport });
+    // An EIP-1193 shim routing the wallet methods wagmi calls to the viem client;
+    // everything else falls through to the chain transport.
+    const request = async (args) => {
+        const params = args.params ?? [];
+        switch (args.method) {
+            case "eth_accounts":
+            case "eth_requestAccounts":
+                return [account.address];
+            case "eth_chainId":
+                return chain.id;
+            case "personal_sign": {
+                const [message] = params;
+                return client.signMessage({ message: { raw: message } });
+            }
+            case "eth_sendTransaction": {
+                // wagmi hands EIP-1193 params in RPC-hex form (gas/value/nonce as 0x
+                // strings). Passing those straight into viem's TYPED sendTransaction
+                // produces a signed tx that strict RPCs reject ("failed to decode signed
+                // transaction"). Take only the essential fields and let viem re-prepare
+                // gas/fees/nonce itself — the path a plain viem walletClient uses.
+                const [tx] = params;
+                return client.sendTransaction({
+                    to: tx.to,
+                    data: tx.data ?? tx.input,
+                    value: tx.value ? BigInt(tx.value) : undefined,
+                });
+            }
+            default:
+                return client.request({
+                    method: args.method,
+                    params,
+                });
+        }
+    };
+    // wagmi's injected connector subscribes to EIP-1193 events; provide no-op
+    // on/removeListener so connect() doesn't crash on the private-key provider.
+    return injected({
+        target: {
+            id: "evmTestWallet",
+            name: "EVM Test Wallet",
+            provider: { request, on: () => { }, removeListener: () => { } },
+        },
+    });
+}
+/**
+ * Choose the connector set for a config. Pure, so the precedence rule is
+ * unit-testable: the E2E test connector always wins (a live sweep must never be
+ * hijacked by a real wallet), then app-supplied connectors, then the built-in
+ * injected/WalletConnect pair.
+ */
+export function selectConnectors(testConnector, appConnectors, builtIn) {
+    if (testConnector)
+        return [testConnector];
+    if (appConnectors && appConnectors.length > 0)
+        return appConnectors;
+    return builtIn;
+}
+/**
+ * Build a wagmi config for one or several EVM chains. Multi-chain lets the
+ * wallet switch chains (e.g. Base Sepolia ↔ Ethereum Sepolia) so the same site
+ * plays each — each chain gets its own resilient transport. The `injected`
+ * connector serves humans; the private-key test connector serves E2E when the
+ * test-wallet query param is present (bound to the `?evmChain=<caip2>` chain,
+ * or the first listed chain).
+ */
+export function buildWagmiConfig(chains, opts = {}) {
+    const { walletConnectProjectId } = opts;
+    const list = chains;
+    const key = getEvmTestWalletKey();
+    // A `?evmRpc=` override is honored ONLY in test mode (test wallet present), so
+    // a crafted link can't point a real user's wallet at a hostile RPC. When set,
+    // use that single reliable endpoint (no fallback) — fail-fast-or-succeed.
+    const override = key ? getEvmRpcOverride() : null;
+    const transports = Object.fromEntries(list.map(({ chain, rpcUrls: chainRpcs }) => [
+        chain.id,
+        override ? viemHttp(override) : buildTransport(chainRpcs),
+    ]));
+    // Test connector binds to one chain: the `?evmChain=<eip155:id>` selection if
+    // it matches a listed chain, else the first. `useSwitchChain` in the game hook
+    // moves the wallet to the chain the player picked before any staking tx.
+    const testChain = pickTestChain(list) ?? list[0].chain;
+    const connectors = selectConnectors(key ? evmTestConnector(key, testChain, transports[testChain.id]) : null, opts.connectors, walletConnectProjectId
+        ? [injected(), walletConnect({ projectId: walletConnectProjectId })]
+        : [injected()]);
+    const chainTuple = list.map((c) => c.chain);
+    return createConfig({ chains: chainTuple, connectors, transports });
+}
+/** Which listed chain the E2E test wallet should bind to: the `?evmChain=`
+ *  eip155 selection when it matches, else null (caller defaults to first). */
+function pickTestChain(list) {
+    if (typeof window === "undefined")
+        return null;
+    const raw = new URLSearchParams(window.location.search).get("evmChain");
+    if (!raw)
+        return null;
+    const id = raw.startsWith("eip155:")
+        ? Number(raw.slice("eip155:".length))
+        : Number(raw);
+    return list.find((c) => c.chain.id === id)?.chain ?? null;
+}

package/dist/inbox/client.d.ts

@@ -0,0 +1,189 @@
+/**
+ * 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.
+ */
+export type NonceSigner = (nonce: string) => Promise<string>;
+export interface InboxSession {
+    session_id: string;
+    tier: string;
+}
+export interface InboxMessage {
+    /** Message id; also the paging + ack cursor (lexically ordered). */
+    msg_id: string;
+    /** CAIP-10 sender, e.g. "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:BASE58". */
+    from_wallet: string;
+    thread_id: string;
+    intent: string | null;
+    body: string;
+    /** RFC 3339 send timestamp. */
+    sent_at: string;
+    /** True for org seed-wallet traffic (server-tagged). */
+    seed?: boolean;
+    /** Present only under `include_sent` reads: "sent" = a mirror copy the
+     *  connected wallet wrote, "received" = an inbound message. Absent on
+     *  inbound-only reads (treat as "received"). */
+    direction?: "received" | "sent";
+}
+export interface MessagePage {
+    messages: InboxMessage[];
+    next_cursor: string | null;
+}
+/** One post on a public topic board (open-challenge / subcontract). Bodies
+ *  are third-party text — render as text, never HTML. */
+export interface TopicPost {
+    post_id: string;
+    topic_id: string;
+    /** CAIP-10 author id. */
+    author_wallet: string;
+    body: string;
+    /** post_id this replies to, or null for a root post. */
+    reply_to: string | null;
+    intent: string | null;
+    /** Unsigned-tx-flow / game / task id this post points at, or null. Drives
+     *  the join/claim CTA. */
+    ref_id: string | null;
+    reported_count: number;
+    /** RFC 3339 creation timestamp. */
+    created_at: string;
+    seed?: boolean;
+}
+export interface TopicPage {
+    topic_id: string;
+    posts: TopicPost[];
+    next_cursor: string | null;
+    /** Server-side count of posts dropped by the auto-hide moderation flag. */
+    filtered_hidden?: number;
+    /** Posts dropped for author trust below the requested `min_trust`. */
+    filtered_below_min_trust?: number;
+}
+export interface PublishReceipt {
+    published: boolean;
+    post_id: string;
+    posts_remaining_today?: number;
+}
+export interface ReportReceipt {
+    reported: boolean;
+    reported_count: number;
+    hidden: boolean;
+    already_reported: boolean;
+}
+/** Known public topic boards. `open-challenge` = game matchmaking,
+ *  `subcontract` = Shillbot task handoff. */
+export type TopicId = "open-challenge" | "subcontract";
+export interface SendReceipt {
+    msg_id: string;
+    thread_id: string;
+    sends_remaining_today?: number;
+}
+/** Non-2xx responses and client-side boundary rejections. `status` is the
+ *  HTTP status, or 0 for errors raised before any request was made. */
+export declare class InboxApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface InboxClientOpts {
+    /** REST base URL; default https://mcp.swarm.tips. Frontends thread their
+     *  VITE_ env override through this (same pattern as API_BASE_URL). */
+    baseUrl?: string;
+    /** Session cache. Defaults to window.localStorage; pass null to disable. */
+    storage?: StorageLike | null;
+    /** fetch implementation — tests inject a mock. */
+    fetchFn?: typeof fetch;
+}
+export declare class InboxClient {
+    private readonly baseUrl;
+    private readonly storage;
+    private readonly fetchFn;
+    private session;
+    private wallet;
+    private signNonce;
+    constructor(opts?: InboxClientOpts);
+    /** True when a cached session exists for `wallet` — opening the inbox will
+     *  not prompt a wallet signature. */
+    hasCachedSession(wallet: string): boolean;
+    /** 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. */
+    createSession(wallet: string, signNonce: NonceSigner): Promise<InboxSession>;
+    /** Drop the in-memory and cached session (e.g. on wallet disconnect). */
+    clearSession(wallet?: string): void;
+    /** Read a page of messages, newest first. Omit `threadId` for the whole
+     *  mailbox; pass the previous page's `next_cursor` to page older. */
+    getMessages(opts?: {
+        threadId?: string;
+        cursor?: string;
+        limit?: number;
+        /** Merge the sender's own mirror copies into the page so a thread read
+         *  shows both sides. Maps to `include_sent=true`. Sent messages carry
+         *  `direction:"sent"`. */
+        includeSent?: boolean;
+    }): Promise<MessagePage>;
+    /** 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). */
+    getThread(threadId: string, opts?: {
+        cursor?: string;
+        limit?: number;
+        includeSent?: boolean;
+    }): Promise<MessagePage>;
+    /** Send a message. Rejects empty / oversize bodies client-side; quota and
+     *  mute rejections surface as InboxApiError with the server's message. */
+    send(toWallet: string, body: string, threadId?: string, intent?: string): Promise<SendReceipt>;
+    /** Advance the read watermark up to a msg_id cursor. NOTE: the watermark is
+     *  mailbox-global — acking a cursor also acks every older message. */
+    ack(upToCursor: string): Promise<void>;
+    /** 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. */
+    readTopic(topicId: TopicId, opts?: {
+        cursor?: string;
+        limit?: number;
+        minTrust?: number;
+    }): Promise<TopicPage>;
+    /** 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. */
+    publishPost(topicId: TopicId, body: string, opts?: {
+        replyTo?: string;
+        intent?: string;
+        refId?: string;
+    }): Promise<PublishReceipt>;
+    /** Report a post for moderation. Session-gated. Idempotent per reporter —
+     *  a repeat report returns `already_reported: true`. */
+    reportPost(topicId: TopicId, postId: string): Promise<ReportReceipt>;
+    private getUnauthed;
+    private mintSession;
+    private postUnauthed;
+    private authed;
+    private doFetch;
+    private readCachedSession;
+    private writeCachedSession;
+}
+export {};