@swarm-tips/client 0.1.1 → 0.2.1

package/dist/http.js

@@ -0,0 +1,101 @@
+import { SwarmClientError, errorMessage } from "./errors.js";
+export class HttpClient {
+    baseUrl;
+    network;
+    fetchImpl;
+    getToken;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.network = options.network;
+        const candidate = options.fetch ?? globalThis.fetch;
+        if (!candidate)
+            throw new SwarmClientError({
+                code: "INVALID_ARGUMENT",
+                operation: "http.constructor",
+                message: "A fetch implementation is required",
+            });
+        this.fetchImpl = candidate.bind(globalThis);
+        this.getToken = options.getToken;
+    }
+    withNetwork(path) {
+        if (!this.network || this.network === "mainnet")
+            return path;
+        const separator = path.includes("?") ? "&" : "?";
+        return `${path}${separator}network=${encodeURIComponent(this.network)}`;
+    }
+    async request(path, init = {}) {
+        const operation = `${init.method ?? "GET"} ${path}`;
+        const token = init.token ?? this.getToken?.();
+        const headers = {
+            "Content-Type": "application/json",
+            ...init.headers,
+        };
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${this.withNetwork(path)}`, {
+                ...init,
+                headers,
+            });
+        }
+        catch (cause) {
+            throw new SwarmClientError({
+                code: "NETWORK_ERROR",
+                operation,
+                message: errorMessage(cause, "Network request failed"),
+                retryable: true,
+                cause,
+            });
+        }
+        if (!response.ok) {
+            const raw = await response.text().catch(() => "");
+            let message = `HTTP ${response.status}`;
+            try {
+                const body = JSON.parse(raw);
+                message = body.message ?? body.error ?? message;
+            }
+            catch {
+                if (raw.trim())
+                    message = raw.slice(0, 500);
+            }
+            throw new SwarmClientError({
+                code: "HTTP_ERROR",
+                operation,
+                message,
+                retryable: response.status === 408 || response.status === 429 || response.status >= 500,
+                status: response.status,
+            });
+        }
+        if (response.status === 204)
+            return undefined;
+        try {
+            return (await response.json());
+        }
+        catch (cause) {
+            throw new SwarmClientError({
+                code: "INVALID_RESPONSE",
+                operation,
+                message: "Response was not valid JSON",
+                cause,
+            });
+        }
+    }
+    get(path, token) {
+        return this.request(path, { method: "GET", token });
+    }
+    post(path, body, token) {
+        return this.request(path, {
+            method: "POST",
+            body: body === undefined ? undefined : JSON.stringify(body),
+            token,
+        });
+    }
+    patch(path, body, token) {
+        return this.request(path, {
+            method: "PATCH",
+            body: body === undefined ? undefined : JSON.stringify(body),
+            token,
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 /** The unified client package version. Functional APIs live in typed subpaths. */
-export declare const CLIENT_VERSION: "0.1.0";
+export declare const CLIENT_VERSION: "0.2.1";
 export declare const CLIENT_MANIFEST_SCHEMA: "swarm.client-manifest/v1";
+export { SwarmClientError } from "./errors.js";
+export type { SwarmClientErrorCode, SwarmClientErrorOptions } from "./errors.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 /** The unified client package version. Functional APIs live in typed subpaths. */
-export const CLIENT_VERSION = "0.1.0";
+export const CLIENT_VERSION = "0.2.1";
 export const CLIENT_MANIFEST_SCHEMA = "swarm.client-manifest/v1";
+export { SwarmClientError } from "./errors.js";

package/dist/shillbot/api.d.ts

@@ -0,0 +1,76 @@
+import { Connection, type BlockhashWithExpiryBlockHeight } from "@solana/web3.js";
+import { HttpClient, type HttpClientOptions } from "../http.js";
+import { type Action, type TransactionInspection, type WalletSignCallback } from "./index.js";
+export interface PreparedTransactionResponse {
+    message?: string;
+    task_id?: string;
+    transaction: string;
+    task_pda?: string;
+    evm_call?: unknown;
+}
+export interface ConfirmTransactionRequest {
+    tx_signature: string;
+    action: Action;
+    task_pda?: string;
+}
+export interface TaskListResponse<TTask = unknown> {
+    tasks: TTask[];
+    next_cursor?: string | null;
+}
+export interface CampaignListResponse<TCampaign = unknown> {
+    campaigns: TCampaign[];
+    next_cursor?: string | null;
+}
+export declare class ShillbotApiClient {
+    readonly http: HttpClient;
+    constructor(options: HttpClientOptions);
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    listTasks<TTask = unknown>(limit?: number): Promise<TaskListResponse<TTask>>;
+    listAgentTasks<TTask = unknown>(): Promise<TaskListResponse<TTask> | TTask[]>;
+    listPendingApproval<TTask = unknown>(): Promise<TaskListResponse<TTask> | TTask[]>;
+    listCampaigns<TCampaign = unknown>(): Promise<CampaignListResponse<TCampaign> | TCampaign[]>;
+    campaign<TCampaign = unknown>(id: string): Promise<TCampaign>;
+    campaignTasks<TTask = unknown>(id: string): Promise<TaskListResponse<TTask>>;
+    campaignMetrics<TMetrics = unknown>(id: string): Promise<TMetrics>;
+    createCampaign<TResponse = {
+        campaign_id: string;
+    }>(body: unknown): Promise<TResponse>;
+    updateCampaign<TResponse = unknown>(id: string, action: string): Promise<TResponse>;
+    fundCampaignTask(id: string, body: unknown): Promise<PreparedTransactionResponse>;
+    onboard<TResponse = unknown>(): Promise<TResponse>;
+    earnings<TResponse = unknown>(): Promise<TResponse>;
+    claimTask(id: string, sponsor?: string): Promise<PreparedTransactionResponse>;
+    submitTask(id: string, body: unknown): Promise<PreparedTransactionResponse>;
+    approveTask(id: string): Promise<PreparedTransactionResponse>;
+    buildVerify(id: string): Promise<PreparedTransactionResponse>;
+    buildFinalize(id: string): Promise<PreparedTransactionResponse>;
+    confirmTask<TResponse = unknown>(id: string, body: ConfirmTransactionRequest): Promise<TResponse>;
+}
+export interface PreparedTransactionExpectation {
+    action: Action;
+    network: "mainnet" | "devnet";
+    wallet: string;
+    taskPda?: string;
+    feePayer?: string;
+    escrowLamports?: bigint;
+    allowedProgramIds?: string[];
+}
+export declare function permittedPreparedProgramIds(action: Action, network: "mainnet" | "devnet"): string[];
+/**
+ * Fail-closed local validation for a server-prepared Shillbot transaction.
+ * The network is an explicit part of the expectation; callers must construct
+ * their Connection for that same network before signing.
+ */
+export declare function validatePreparedTransaction(encoded: string, expected: PreparedTransactionExpectation): TransactionInspection;
+export declare function signBroadcastPreparedTransaction(input: {
+    connection: Connection;
+    transaction: string;
+    expected: PreparedTransactionExpectation;
+    sign: WalletSignCallback;
+    confirmation?: BlockhashWithExpiryBlockHeight;
+    timeoutMs?: number;
+    setTimeout?: typeof globalThis.setTimeout;
+    clearTimeout?: typeof globalThis.clearTimeout;
+}): Promise<string>;

package/dist/shillbot/api.js

@@ -0,0 +1,114 @@
+import { Buffer } from "buffer";
+import { ComputeBudgetProgram, Secp256k1Program, SystemProgram } from "@solana/web3.js";
+import { HttpClient } from "../http.js";
+import { SwarmClientError } from "../errors.js";
+import { SHILLBOT_PROGRAM_ID, inspectTransaction, shillbotInstructionDiscriminator, signAndBroadcast, } from "./index.js";
+export class ShillbotApiClient {
+    http;
+    constructor(options) { this.http = new HttpClient(options); }
+    get(path) { return this.http.get(path); }
+    post(path, body) { return this.http.post(path, body); }
+    patch(path, body) { return this.http.patch(path, body); }
+    listTasks(limit = 50) { return this.get(`/tasks?limit=${encodeURIComponent(String(limit))}`); }
+    listAgentTasks() { return this.get("/agent/tasks"); }
+    listPendingApproval() { return this.get("/tasks?status=pending_approval"); }
+    listCampaigns() { return this.get("/campaigns"); }
+    campaign(id) { return this.get(`/campaigns/${encodeURIComponent(id)}`); }
+    campaignTasks(id) { return this.get(`/campaigns/${encodeURIComponent(id)}/tasks`); }
+    campaignMetrics(id) { return this.get(`/campaigns/${encodeURIComponent(id)}/metrics`); }
+    createCampaign(body) { return this.post("/campaigns", body); }
+    updateCampaign(id, action) { return this.patch(`/campaigns/${encodeURIComponent(id)}`, { action }); }
+    fundCampaignTask(id, body) { return this.post(`/campaigns/${encodeURIComponent(id)}/fund`, body); }
+    onboard() { return this.post("/agent/onboard"); }
+    earnings() { return this.get("/agent/earnings"); }
+    claimTask(id, sponsor = "auto") { return this.post(`/tasks/${encodeURIComponent(id)}/claim?sponsor=${encodeURIComponent(sponsor)}`); }
+    submitTask(id, body) { return this.post(`/tasks/${encodeURIComponent(id)}/submit`, body); }
+    approveTask(id) { return this.post(`/tasks/${encodeURIComponent(id)}/approve`); }
+    buildVerify(id) { return this.post(`/tasks/${encodeURIComponent(id)}/build-verify`); }
+    buildFinalize(id) { return this.post(`/tasks/${encodeURIComponent(id)}/build-finalize`); }
+    confirmTask(id, body) { return this.post(`/tasks/${encodeURIComponent(id)}/confirm`, body); }
+}
+const SWITCHBOARD_PROGRAM_IDS = {
+    mainnet: "SBondMDrcV3K4kxZR1HNVT7osZxAHVHgYXL5Ze1oMUv",
+    devnet: "Aio4gaXjXzJNVLtzwtNVmSqGKpANtXhybbkhtAC94ji2",
+};
+export function permittedPreparedProgramIds(action, network) {
+    return action === "verify"
+        ? [SWITCHBOARD_PROGRAM_IDS[network], Secp256k1Program.programId.toBase58()]
+        : [];
+}
+function lifecycleName(action) {
+    if (action === "create")
+        return "create_task";
+    if (action === "submit")
+        return "submit_work";
+    return `${action}_task`;
+}
+function matchesDiscriminator(dataBase64, action) {
+    const data = Buffer.from(dataBase64, "base64");
+    return data.subarray(0, 8).equals(shillbotInstructionDiscriminator(lifecycleName(action)));
+}
+/**
+ * Fail-closed local validation for a server-prepared Shillbot transaction.
+ * The network is an explicit part of the expectation; callers must construct
+ * their Connection for that same network before signing.
+ */
+export function validatePreparedTransaction(encoded, expected) {
+    if (expected.network !== "mainnet" && expected.network !== "devnet") {
+        throw new SwarmClientError({ code: "INVALID_ARGUMENT", operation: "shillbot.validatePreparedTransaction", message: "Unsupported network" });
+    }
+    const inspected = inspectTransaction(encoded);
+    if (!inspected.signers.includes(expected.wallet)) {
+        throw new SwarmClientError({ code: "TRANSACTION_MISMATCH", operation: "shillbot.validatePreparedTransaction", message: "Wallet is not a required signer" });
+    }
+    if (expected.feePayer && inspected.fee_payer !== expected.feePayer) {
+        throw new SwarmClientError({ code: "TRANSACTION_MISMATCH", operation: "shillbot.validatePreparedTransaction", message: "Fee payer differs from expectation" });
+    }
+    const shillbotId = SHILLBOT_PROGRAM_ID.toBase58();
+    const lifecycle = inspected.instructions.filter((instruction) => instruction.program_id === shillbotId && matchesDiscriminator(instruction.data_base64, expected.action));
+    if (lifecycle.length !== 1) {
+        throw new SwarmClientError({ code: "TRANSACTION_MISMATCH", operation: "shillbot.validatePreparedTransaction", message: "Expected exactly one matching Shillbot lifecycle instruction" });
+    }
+    if (expected.taskPda && !lifecycle[0].accounts.includes(expected.taskPda)) {
+        throw new SwarmClientError({ code: "TRANSACTION_MISMATCH", operation: "shillbot.validatePreparedTransaction", message: "Task PDA differs from expectation" });
+    }
+    const alwaysAllowed = new Set([
+        shillbotId,
+        ComputeBudgetProgram.programId.toBase58(),
+        SystemProgram.programId.toBase58(),
+        ...permittedPreparedProgramIds(expected.action, expected.network),
+        ...(expected.allowedProgramIds ?? []),
+    ]);
+    const unrelated = inspected.instructions.find((instruction) => !alwaysAllowed.has(instruction.program_id));
+    if (unrelated) {
+        throw new SwarmClientError({ code: "TRANSACTION_MISMATCH", operation: "shillbot.validatePreparedTransaction", message: `Unexpected program ${unrelated.program_id}` });
+    }
+    if (expected.action === "create" && expected.escrowLamports !== undefined) {
+        const data = Buffer.from(lifecycle[0].data_base64, "base64");
+        if (data.length < 24)
+            throw new SwarmClientError({ code: "TRANSACTION_MISMATCH", operation: "shillbot.validatePreparedTransaction", message: "Create instruction is truncated" });
+        const view = new DataView(data.buffer, data.byteOffset + 16, 8);
+        const amount = view.getBigUint64(0, true);
+        if (amount !== expected.escrowLamports) {
+            throw new SwarmClientError({ code: "TRANSACTION_MISMATCH", operation: "shillbot.validatePreparedTransaction", message: `Escrow amount ${amount} differs from expected ${expected.escrowLamports}` });
+        }
+    }
+    return inspected;
+}
+export async function signBroadcastPreparedTransaction(input) {
+    validatePreparedTransaction(input.transaction, input.expected);
+    const timeoutMs = input.timeoutMs ?? 60_000;
+    let timeout;
+    try {
+        return await Promise.race([
+            signAndBroadcast(input.connection, input.transaction, input.sign, input.confirmation),
+            new Promise((_, reject) => {
+                timeout = (input.setTimeout ?? globalThis.setTimeout)(() => reject(new SwarmClientError({ code: "TIMEOUT", operation: "shillbot.signBroadcastPreparedTransaction", message: `Transaction did not confirm within ${timeoutMs}ms`, retryable: true })), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout !== undefined)
+            (input.clearTimeout ?? globalThis.clearTimeout)(timeout);
+    }
+}

package/dist/swarm/index.d.ts

@@ -0,0 +1,84 @@
+import { HttpClient, type FetchLike } from "../http.js";
+export interface AgentJob {
+    source: string;
+    source_id: string;
+    source_url: string;
+    title: string;
+    description: string;
+    category: string;
+    vertical?: string;
+    tags: string[];
+    reward_amount: string;
+    reward_token: string;
+    reward_chain: string;
+    reward_usd_estimate?: number;
+    payment_model: string;
+    escrow: boolean;
+    posted_at: string;
+    deadline?: string | null;
+    status: string;
+    claims_remaining?: number | null;
+    required_capabilities?: string[];
+    client_address?: string;
+    how_to_start?: string;
+    indexed_at: string;
+    slots_open?: number;
+}
+export interface RankingSignals {
+    bm25_score: number;
+    final_score: number;
+    quality_prior: number;
+    source_count: number;
+    github_stars: number | null;
+    npm_weekly_downloads: number | null;
+    upstream_quality_score: number | null;
+    llm_confidence: number | null;
+}
+export interface SearchHit {
+    name: string;
+    title: string | null;
+    description: string | null;
+    endpoint: string | null;
+    transport: string | null;
+    github_repo: string | null;
+    npm_package: string | null;
+    category: string | null;
+    currencies: string[];
+    provenance: string;
+    ranking_signals: RankingSignals;
+}
+export interface EigenTrustRecord {
+    wallet: string;
+    eigentrust_score: number;
+    rank: number;
+    rank_normalized: number;
+    settlements_received: number;
+    settlements_paid: number;
+    counterparty_count: number;
+    computed_at: string;
+}
+export interface AgentReputation {
+    wallet: string;
+    web_position: number | null;
+    extensions_received: number;
+    has_standing: boolean;
+    eigentrust?: EigenTrustRecord | null;
+}
+export interface SwarmClientOptions {
+    baseUrl: string;
+    fetch?: FetchLike;
+}
+export declare class SwarmClient {
+    readonly http: HttpClient;
+    private readonly fetchImpl;
+    readonly baseUrl: string;
+    constructor(options: SwarmClientOptions);
+    listings(): Promise<AgentJob[]>;
+    search(query: string, limit?: number): Promise<{
+        results: SearchHit[];
+        corpus_size: number;
+    }>;
+    reputation(wallet: string, network?: string): Promise<AgentReputation>;
+    leaderboard(limit?: number): Promise<EigenTrustRecord[]>;
+    toolCount(): Promise<number | null>;
+}

package/dist/swarm/index.js

@@ -0,0 +1,71 @@
+import { HttpClient } from "../http.js";
+function parseRpc(body) {
+    const trimmed = body.trimStart();
+    if (trimmed.startsWith("{")) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return null;
+        }
+    }
+    for (const line of body.split("\n")) {
+        const value = line.trim();
+        if (!value.startsWith("data:"))
+            continue;
+        try {
+            return JSON.parse(value.slice(5).trim());
+        }
+        catch { /* continue */ }
+    }
+    return null;
+}
+export class SwarmClient {
+    http;
+    fetchImpl;
+    baseUrl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.fetchImpl = (options.fetch ?? globalThis.fetch).bind(globalThis);
+        this.http = new HttpClient(options);
+    }
+    async listings() { return this.http.get("/internal/listings"); }
+    async search(query, limit = 30) {
+        const params = new URLSearchParams();
+        if (query)
+            params.set("query", query);
+        params.set("limit", String(limit));
+        return this.http.get(`/internal/mcp/search?${params.toString()}`);
+    }
+    reputation(wallet, network = "mainnet") {
+        if (!wallet)
+            return Promise.reject(new TypeError("wallet is required"));
+        return this.http.get(`/internal/agent-reputation?wallet=${encodeURIComponent(wallet)}&network=${encodeURIComponent(network)}`);
+    }
+    async leaderboard(limit = 25) {
+        const body = await this.http.get(`/internal/reputation/leaderboard?limit=${encodeURIComponent(String(limit))}`);
+        return body.agents ?? [];
+    }
+    async toolCount() {
+        const headers = { "Content-Type": "application/json", Accept: "application/json, text/event-stream" };
+        try {
+            const init = await this.fetchImpl(`${this.baseUrl}/mcp`, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "swarm-client", version: "0.2.1" } } }) });
+            if (!init.ok)
+                return null;
+            const session = init.headers.get("mcp-session-id");
+            await init.text();
+            if (!session)
+                return null;
+            const sessionHeaders = { ...headers, "mcp-session-id": session };
+            await this.fetchImpl(`${this.baseUrl}/mcp`, { method: "POST", headers: sessionHeaders, body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) });
+            const listed = await this.fetchImpl(`${this.baseUrl}/mcp`, { method: "POST", headers: sessionHeaders, body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }) });
+            if (!listed.ok)
+                return null;
+            const tools = parseRpc(await listed.text())?.result?.tools;
+            return Array.isArray(tools) && tools.length ? tools.length : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarm-tips/client",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Typed browser and Node.js clients for Swarm Tips, Shillbot, and Coordination Game",
   "type": "module",
   "main": "dist/index.js",
@@ -17,11 +17,36 @@
       "import": "./dist/shillbot/index.js",
       "require": "./dist/shillbot/index.js"
     },
+    "./shillbot/api": {
+      "types": "./dist/shillbot/api.d.ts",
+      "import": "./dist/shillbot/api.js",
+      "require": "./dist/shillbot/api.js"
+    },
     "./coordination-game": {
       "types": "./dist/coordination-game/index.d.ts",
       "import": "./dist/coordination-game/index.js",
       "require": "./dist/coordination-game/index.js"
     },
+    "./coordination-game/solana": {
+      "types": "./dist/coordination-game/solana.d.ts",
+      "import": "./dist/coordination-game/solana.js",
+      "require": "./dist/coordination-game/solana.js"
+    },
+    "./coordination-game/evm": {
+      "types": "./dist/coordination-game/evm/index.d.ts",
+      "import": "./dist/coordination-game/evm/index.js",
+      "require": "./dist/coordination-game/evm/index.js"
+    },
+    "./coordination-game/api": {
+      "types": "./dist/coordination-game/api.d.ts",
+      "import": "./dist/coordination-game/api.js",
+      "require": "./dist/coordination-game/api.js"
+    },
+    "./swarm": {
+      "types": "./dist/swarm/index.d.ts",
+      "import": "./dist/swarm/index.js",
+      "require": "./dist/swarm/index.js"
+    },
     "./evm": {
       "types": "./dist/evm/index.d.ts",
       "import": "./dist/evm/index.js",