@crossmint/lobster.cash 0.1.1

package/src/config.ts

@@ -0,0 +1,50 @@
+const DEFAULT_SERVER_BASE_URL = "https://www.lobster.cash";
+const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+
+export type CrossmintPluginConfig = {
+  serverBaseUrl: string;
+  requestTimeoutMs: number;
+};
+
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/+$/, "");
+}
+
+export const crossmintConfigSchema = {
+  parse(value: unknown): CrossmintPluginConfig {
+    if (value !== undefined && value !== null && typeof value !== "object") {
+      throw new Error("Plugin config must be an object");
+    }
+
+    const cfg = (value ?? {}) as Record<string, unknown>;
+    const keys = Object.keys(cfg);
+    const allowedKeys = new Set(["serverBaseUrl", "requestTimeoutMs"]);
+    const unknownKeys = keys.filter((key) => !allowedKeys.has(key));
+    if (unknownKeys.length > 0) {
+      throw new Error(`Unknown plugin config keys: ${unknownKeys.join(", ")}`);
+    }
+
+    const serverBaseUrlRaw = cfg.serverBaseUrl;
+    if (serverBaseUrlRaw !== undefined && typeof serverBaseUrlRaw !== "string") {
+      throw new Error("serverBaseUrl must be a string");
+    }
+
+    const requestTimeoutMsRaw = cfg.requestTimeoutMs;
+    if (
+      requestTimeoutMsRaw !== undefined &&
+      (typeof requestTimeoutMsRaw !== "number" ||
+        !Number.isFinite(requestTimeoutMsRaw) ||
+        requestTimeoutMsRaw <= 0)
+    ) {
+      throw new Error("requestTimeoutMs must be a positive number");
+    }
+
+    const serverBaseUrl = normalizeBaseUrl(serverBaseUrlRaw || DEFAULT_SERVER_BASE_URL);
+    const requestTimeoutMs = requestTimeoutMsRaw ?? DEFAULT_REQUEST_TIMEOUT_MS;
+
+    return {
+      serverBaseUrl,
+      requestTimeoutMs,
+    };
+  },
+};

package/src/tools.test.ts

@@ -0,0 +1,354 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import {
+  completeSetup,
+  configureWallet,
+  getOrCreateWallet,
+  getWallet,
+  updateSetupPending,
+} from "./wallet.js";
+import {
+  createCrossmintBalanceTool,
+  createCrossmintConfigureTool,
+  createCrossmintOrderStatusTool,
+  createCrossmintSetupTool,
+  createCrossmintWalletInfoTool,
+} from "./tools.js";
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+    },
+  });
+}
+
+describe("tools (server flow)", () => {
+  let tmpDir: string;
+  let previousWalletDir: string | undefined;
+
+  const fetchMock = vi.fn();
+
+  const config = {
+    serverBaseUrl: "https://example.com",
+    requestTimeoutMs: 5000,
+  };
+
+  const context = {
+    agentId: "agent-test",
+  } as OpenClawPluginToolContext;
+
+  beforeEach(async () => {
+    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "openclaw-plugin-tools-"));
+    previousWalletDir = process.env.CROSSMINT_WALLETS_DIR;
+    process.env.CROSSMINT_WALLETS_DIR = tmpDir;
+
+    fetchMock.mockReset();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(async () => {
+    vi.unstubAllGlobals();
+
+    if (previousWalletDir === undefined) {
+      delete process.env.CROSSMINT_WALLETS_DIR;
+    } else {
+      process.env.CROSSMINT_WALLETS_DIR = previousWalletDir;
+    }
+
+    await fs.promises.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("starts setup and returns consent URL", async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({ pairingId: "pair-1", pairingNonce: "nonce-1", expiresAt: 12345 })
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          verified: true,
+          consentUrl: "https://example.com/setup/consent?pairingId=pair-1",
+        })
+      );
+
+    const tool = createCrossmintSetupTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    expect(result.content[0]?.type).toBe("text");
+    expect((result.content[0] as { text: string }).text).toContain(
+      "https://example.com/setup/consent?pairingId=pair-1"
+    );
+
+    const wallet = getWallet("agent-test");
+    expect(wallet?.pairingId).toBe("pair-1");
+    expect(wallet?.consentUrl).toBe("https://example.com/setup/consent?pairingId=pair-1");
+    expect(wallet?.setupStatus).toBe("awaiting-consent");
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("https://example.com/api/claw/setup/start");
+    expect(fetchMock.mock.calls[1]?.[0]).toBe("https://example.com/api/claw/setup/verify");
+  });
+
+  it("returns already configured when setup is complete", async () => {
+    getOrCreateWallet("agent-test");
+    completeSetup("agent-test", "wallet-1", "access-token", "refresh-token", 9999999999);
+
+    const tool = createCrossmintSetupTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    expect((result.content[0] as { text: string }).text).toContain("Wallet already configured");
+    expect((result.details as { status?: string }).status).toBe("already_configured");
+    expect(fetchMock).toHaveBeenCalledTimes(0);
+  });
+
+  it("returns migration guidance when setup sees legacy wallet data", async () => {
+    getOrCreateWallet("agent-test");
+    configureWallet("agent-test", "legacy-wallet", "legacy-api-key");
+
+    const tool = createCrossmintSetupTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    expect((result.content[0] as { text: string }).text).toContain(
+      "Legacy wallet configuration detected"
+    );
+    expect((result.details as { status?: string }).status).toBe("legacy_detected");
+    expect(fetchMock).toHaveBeenCalledTimes(0);
+  });
+
+  it("keeps setup pending when user has not approved consent yet", async () => {
+    getOrCreateWallet("agent-test");
+    updateSetupPending(
+      "agent-test",
+      "pair-approval",
+      "https://example.com/setup/consent?pairingId=pair-approval"
+    );
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ status: "verified-awaiting-consent", expiresAt: 12345 })
+    );
+
+    const tool = createCrossmintSetupTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+    const wallet = getWallet("agent-test");
+
+    expect((result.content[0] as { text: string }).text).toContain(
+      "waiting for user consent for agent"
+    );
+    expect((result.details as { status?: string }).status).toBe("awaiting-approval");
+    expect(wallet?.pairingId).toBe("pair-approval");
+    expect(wallet?.setupStatus).toBe("awaiting-approval");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("clears pairing and marks setup denied when consent is denied", async () => {
+    getOrCreateWallet("agent-test");
+    updateSetupPending("agent-test", "pair-denied", "https://example.com/setup/consent");
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ status: "denied" }));
+
+    const tool = createCrossmintSetupTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+    const wallet = getWallet("agent-test");
+
+    expect((result.content[0] as { text: string }).text).toContain("Setup was denied");
+    expect(wallet?.setupStatus).toBe("denied");
+    expect(wallet?.pairingId).toBeUndefined();
+    expect(wallet?.consentUrl).toBeUndefined();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("clears pairing and marks setup expired when setup window expires", async () => {
+    getOrCreateWallet("agent-test");
+    updateSetupPending("agent-test", "pair-expired", "https://example.com/setup/consent");
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ status: "expired" }));
+
+    const tool = createCrossmintSetupTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+    const wallet = getWallet("agent-test");
+
+    expect((result.content[0] as { text: string }).text).toContain("Setup request expired");
+    expect(wallet?.setupStatus).toBe("expired");
+    expect(wallet?.pairingId).toBeUndefined();
+    expect(wallet?.consentUrl).toBeUndefined();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("finalizes setup when pairing is approved", async () => {
+    getOrCreateWallet("agent-test");
+    updateSetupPending(
+      "agent-test",
+      "pair-2",
+      "https://example.com/setup/consent?pairingId=pair-2"
+    );
+
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({ status: "approved", retrievalNonce: "retrieval-nonce", expiresAt: 12345 })
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          walletAddress: "wallet-1",
+          accessToken: "access-token",
+          refreshToken: "refresh-token",
+          expiresAt: 9999999999,
+        })
+      );
+
+    const tool = createCrossmintSetupTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    expect((result.content[0] as { text: string }).text).toContain(
+      "Wallet configured successfully"
+    );
+
+    const wallet = getWallet("agent-test");
+    expect(wallet?.walletAddress).toBe("wallet-1");
+    expect(wallet?.accessToken).toBe("access-token");
+    expect(wallet?.refreshToken).toBe("refresh-token");
+    expect(wallet?.setupStatus).toBe("configured");
+    expect(wallet?.pairingId).toBeUndefined();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://example.com/api/claw/setup/status?pairingId=pair-2"
+    );
+    expect(fetchMock.mock.calls[1]?.[0]).toBe("https://example.com/api/claw/setup/retrieve");
+  });
+
+  it("refreshes expired access token and retries balance", async () => {
+    getOrCreateWallet("agent-test");
+    completeSetup("agent-test", "wallet-1", "old-access-token", "old-refresh-token", 9999999999);
+
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse(
+          {
+            error: {
+              code: "ACCESS_TOKEN_EXPIRED",
+              message: "expired",
+            },
+          },
+          401
+        )
+      )
+      .mockResolvedValueOnce(jsonResponse({ nonceId: "nonce-id", refreshNonce: "refresh-nonce" }))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          accessToken: "new-access-token",
+          refreshToken: "new-refresh-token",
+          expiresAt: 9999999999,
+        })
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          balances: [{ token: "usdc", amount: "5" }],
+        })
+      );
+
+    const tool = createCrossmintBalanceTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    const text = (result.content[0] as { text: string }).text;
+    expect(text).toContain("usdc: 5");
+
+    const wallet = getWallet("agent-test");
+    expect(wallet?.accessToken).toBe("new-access-token");
+    expect(wallet?.refreshToken).toBe("new-refresh-token");
+
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://example.com/api/proxy/wallets/wallet-1/balance"
+    );
+    expect(fetchMock.mock.calls[1]?.[0]).toBe("https://example.com/api/claw/token/refresh/init");
+    expect(fetchMock.mock.calls[2]?.[0]).toBe("https://example.com/api/claw/token/refresh");
+    expect(fetchMock.mock.calls[3]?.[0]).toBe(
+      "https://example.com/api/proxy/wallets/wallet-1/balance"
+    );
+  });
+
+  it("refreshes expiring tokens before first authenticated request", async () => {
+    getOrCreateWallet("agent-test");
+    completeSetup(
+      "agent-test",
+      "wallet-1",
+      "almost-expired-token",
+      "refresh-token",
+      Math.floor(Date.now() / 1000) + 10
+    );
+
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({ nonceId: "nonce-id", refreshNonce: "refresh-nonce-proactive" })
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          accessToken: "fresh-access-token",
+          refreshToken: "fresh-refresh-token",
+          expiresAt: 9999999999,
+        })
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          balances: [{ token: "usdc", amount: "9" }],
+        })
+      );
+
+    const tool = createCrossmintBalanceTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    expect((result.content[0] as { text: string }).text).toContain("usdc: 9");
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("https://example.com/api/claw/token/refresh/init");
+    expect(fetchMock.mock.calls[1]?.[0]).toBe("https://example.com/api/claw/token/refresh");
+    expect(fetchMock.mock.calls[2]?.[0]).toBe(
+      "https://example.com/api/proxy/wallets/wallet-1/balance"
+    );
+  });
+
+  it("returns deprecation guidance from crossmint_configure when wallet is not configured", async () => {
+    const tool = createCrossmintConfigureTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    expect((result.content[0] as { text: string }).text).toContain(
+      "crossmint_configure is deprecated"
+    );
+  });
+
+  it("returns already configured from crossmint_configure after setup", async () => {
+    getOrCreateWallet("agent-test");
+    completeSetup("agent-test", "wallet-1", "access-token", "refresh-token", 9999999999);
+
+    const tool = createCrossmintConfigureTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    expect((result.content[0] as { text: string }).text).toContain("already configured");
+    expect((result.details as { status?: string }).status).toBe("already_configured");
+  });
+
+  it("returns wallet info for legacy configuration", async () => {
+    getOrCreateWallet("agent-test");
+    configureWallet("agent-test", "legacy-wallet", "legacy-api-key");
+
+    const tool = createCrossmintWalletInfoTool({} as never, config);
+    const result = await tool.execute("id", {}, context);
+
+    expect((result.content[0] as { text: string }).text).toContain("legacy config");
+    expect((result.details as { legacy?: boolean }).legacy).toBe(true);
+  });
+
+  it("order status tool returns hint when client secret is not available", async () => {
+    getOrCreateWallet("agent-test");
+    completeSetup("agent-test", "wallet-1", "access-token", "refresh-token", 9999999999);
+
+    const tool = createCrossmintOrderStatusTool({} as never, config);
+    const result = await tool.execute("id", { orderId: "order-missing" }, context);
+
+    expect((result.content[0] as { text: string }).text).toContain("No stored clientSecret");
+    expect(fetchMock).toHaveBeenCalledTimes(0);
+  });
+});