@crossmint/openclaw-wallet 0.2.2

package/src/api.test.ts

@@ -0,0 +1,211 @@
+import { Keypair } from "@solana/web3.js";
+import { describe, expect, it } from "vitest";
+import {
+  buildAmazonProductLocator,
+  buildDelegationUrl,
+  createOrder,
+  getOrder,
+  type CreateOrderRequest,
+  type CrossmintApiConfig,
+} from "./api.js";
+
+/**
+ * Live integration tests for Crossmint Amazon purchase API.
+ *
+ * Run with: CROSSMINT_API_KEY=your-key pnpm test extensions/crossmint/src/api.test.ts
+ *
+ * These tests make real API calls to Crossmint staging (devnet).
+ * They require a valid client-side API key with orders.create scope.
+ */
+
+const LIVE = process.env.CROSSMINT_API_KEY || process.env.LIVE;
+
+describe("crossmint api", () => {
+  describe("buildDelegationUrl", () => {
+    it("builds URL with public key parameter", () => {
+      const url = buildDelegationUrl("https://example.com/delegate", "ABC123");
+      expect(url).toBe("https://example.com/delegate/configure?pubkey=ABC123");
+    });
+
+    it("removes trailing slashes from base URL", () => {
+      const url = buildDelegationUrl("https://example.com/delegate///", "ABC123");
+      expect(url).toBe("https://example.com/delegate/configure?pubkey=ABC123");
+    });
+  });
+
+  describe("buildAmazonProductLocator", () => {
+    it("returns existing amazon: locator unchanged", () => {
+      const result = buildAmazonProductLocator("amazon:B00O79SKV6");
+      expect(result).toBe("amazon:B00O79SKV6");
+    });
+
+    it("wraps Amazon URL with amazon: prefix", () => {
+      const result = buildAmazonProductLocator("https://www.amazon.com/dp/B00O79SKV6");
+      expect(result).toBe("amazon:https://www.amazon.com/dp/B00O79SKV6");
+    });
+
+    it("wraps ASIN with amazon: prefix", () => {
+      const result = buildAmazonProductLocator("B00O79SKV6");
+      expect(result).toBe("amazon:B00O79SKV6");
+    });
+  });
+
+  describe.skipIf(!LIVE)("live: createOrder", () => {
+    const config: CrossmintApiConfig = {
+      apiKey: process.env.CROSSMINT_API_KEY!,
+      environment: "staging",
+    };
+
+    // Generate a test keypair for the payer address
+    const testKeypair = Keypair.generate();
+
+    it("creates an order for an Amazon product", async () => {
+      const request: CreateOrderRequest = {
+        recipient: {
+          email: "test@example.com",
+          physicalAddress: {
+            name: "Test User",
+            line1: "123 Test Street",
+            city: "San Francisco",
+            state: "CA",
+            postalCode: "94102",
+            country: "US",
+          },
+        },
+        payment: {
+          receiptEmail: "test@example.com",
+          method: "solana",
+          currency: "usdc",
+          payerAddress: testKeypair.publicKey.toBase58(),
+        },
+        lineItems: [
+          {
+            // Amazon Basics product - commonly available
+            productLocator: "amazon:B00O79SKV6",
+          },
+        ],
+      };
+
+      const order = await createOrder(config, request);
+
+      console.log("Created order:", JSON.stringify(order, null, 2));
+
+      // Verify order was created
+      expect(order.orderId).toBeDefined();
+      expect(order.phase).toBeDefined();
+
+      // The order should have a quote or be in quote phase
+      expect(["quote", "payment"]).toContain(order.phase);
+
+      // For headless checkout with delegated signer, we expect serializedTransaction
+      // Note: This may not always be present depending on quote status
+      if (order.phase === "payment") {
+        expect(order.payment?.preparation?.serializedTransaction).toBeDefined();
+      }
+    });
+
+    it("creates an order with SOL currency", async () => {
+      const request: CreateOrderRequest = {
+        recipient: {
+          email: "test@example.com",
+          physicalAddress: {
+            name: "Test User",
+            line1: "456 Test Avenue",
+            city: "Los Angeles",
+            state: "CA",
+            postalCode: "90001",
+            country: "US",
+          },
+        },
+        payment: {
+          receiptEmail: "test@example.com",
+          method: "solana",
+          currency: "sol",
+          payerAddress: testKeypair.publicKey.toBase58(),
+        },
+        lineItems: [
+          {
+            productLocator: "amazon:B00O79SKV6",
+          },
+        ],
+      };
+
+      const order = await createOrder(config, request);
+
+      console.log("Created SOL order:", JSON.stringify(order, null, 2));
+
+      expect(order.orderId).toBeDefined();
+      expect(order.phase).toBeDefined();
+    });
+
+    it("retrieves order status after creation", async () => {
+      // First create an order
+      const request: CreateOrderRequest = {
+        recipient: {
+          email: "test@example.com",
+          physicalAddress: {
+            name: "Test User",
+            line1: "789 Test Blvd",
+            city: "New York",
+            state: "NY",
+            postalCode: "10001",
+            country: "US",
+          },
+        },
+        payment: {
+          receiptEmail: "test@example.com",
+          method: "solana",
+          currency: "usdc",
+          payerAddress: testKeypair.publicKey.toBase58(),
+        },
+        lineItems: [
+          {
+            productLocator: "amazon:B00O79SKV6",
+          },
+        ],
+      };
+
+      const createdOrder = await createOrder(config, request);
+      expect(createdOrder.orderId).toBeDefined();
+
+      // Now retrieve the order
+      const retrievedOrder = await getOrder(config, createdOrder.orderId);
+
+      console.log("Retrieved order:", JSON.stringify(retrievedOrder, null, 2));
+
+      expect(retrievedOrder.orderId).toBe(createdOrder.orderId);
+      expect(retrievedOrder.phase).toBeDefined();
+    });
+
+    it("handles invalid product gracefully", async () => {
+      const request: CreateOrderRequest = {
+        recipient: {
+          email: "test@example.com",
+          physicalAddress: {
+            name: "Test User",
+            line1: "123 Test Street",
+            city: "San Francisco",
+            state: "CA",
+            postalCode: "94102",
+            country: "US",
+          },
+        },
+        payment: {
+          receiptEmail: "test@example.com",
+          method: "solana",
+          currency: "usdc",
+          payerAddress: testKeypair.publicKey.toBase58(),
+        },
+        lineItems: [
+          {
+            // Invalid ASIN
+            productLocator: "amazon:INVALID123",
+          },
+        ],
+      };
+
+      // Should throw an error for invalid product
+      await expect(createOrder(config, request)).rejects.toThrow();
+    });
+  });
+});

package/src/api.ts

@@ -0,0 +1,495 @@
+import type { Keypair } from "@solana/web3.js";
+import bs58 from "bs58";
+
+export type CrossmintApiConfig = {
+  apiKey: string;
+  environment: "staging"; // Only staging (Solana devnet) supported for now
+};
+
+export type CrossmintBalance = {
+  token: string;
+  amount: string;
+  decimals: number;
+  rawAmount?: string;
+};
+
+export type CrossmintTransaction = {
+  id: string;
+  status: string;
+  hash?: string;
+  explorerLink?: string;
+  onChain?: {
+    status?: string;
+    chain?: string;
+    txId?: string;
+  };
+};
+
+// Only staging (Solana devnet) is supported for now
+function getBaseUrl(_env: "staging"): string {
+  // Production URL reserved for future use: https://www.crossmint.com/api
+  return "https://staging.crossmint.com/api";
+}
+
+async function fetchCrossmint(
+  config: CrossmintApiConfig,
+  endpoint: string,
+  options: RequestInit = {},
+): Promise<Response> {
+  const baseUrl = getBaseUrl(config.environment);
+  const url = `${baseUrl}${endpoint}`;
+
+  const headers: Record<string, string> = {
+    "X-API-KEY": config.apiKey,
+    "Content-Type": "application/json",
+    ...(options.headers as Record<string, string>),
+  };
+
+  const response = await fetch(url, {
+    ...options,
+    headers,
+  });
+
+  return response;
+}
+
+export async function getWalletBalance(
+  config: CrossmintApiConfig,
+  walletAddress: string,
+): Promise<CrossmintBalance[]> {
+  const response = await fetchCrossmint(
+    config,
+    `/2025-06-09/wallets/${encodeURIComponent(walletAddress)}/balances?tokens=sol,usdc&chains=solana`,
+    { method: "GET" },
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to get balance: ${error}`);
+  }
+
+  const data = await response.json();
+
+  const balances: CrossmintBalance[] = [];
+
+  // Parse the response array
+  if (Array.isArray(data)) {
+    for (const token of data) {
+      balances.push({
+        token: token.symbol || "Unknown",
+        amount: token.amount || "0",
+        decimals: token.decimals || 9,
+        rawAmount: token.rawAmount,
+      });
+    }
+  }
+
+  return balances;
+}
+
+export async function getTransactionStatus(
+  config: CrossmintApiConfig,
+  walletAddress: string,
+  transactionId: string,
+): Promise<CrossmintTransaction> {
+  const response = await fetchCrossmint(
+    config,
+    `/2025-06-09/wallets/${encodeURIComponent(walletAddress)}/transactions/${encodeURIComponent(transactionId)}`,
+    { method: "GET" },
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to get transaction status: ${error}`);
+  }
+
+  const data = await response.json();
+
+  return {
+    id: data.id,
+    status: data.status,
+    hash: data.onChain?.txId || data.hash,
+    explorerLink: data.onChain?.txId
+      ? `https://explorer.solana.com/tx/${data.onChain.txId}?cluster=devnet`
+      : undefined,
+    onChain: data.onChain,
+  };
+}
+
+export async function waitForTransaction(
+  config: CrossmintApiConfig,
+  walletAddress: string,
+  transactionId: string,
+  timeoutMs: number = 60000,
+  pollIntervalMs: number = 2000,
+): Promise<CrossmintTransaction> {
+  const startTime = Date.now();
+  
+  while (Date.now() - startTime < timeoutMs) {
+    const tx = await getTransactionStatus(config, walletAddress, transactionId);
+    
+    // Terminal states
+    if (tx.status === "success" || tx.status === "completed") {
+      return tx;
+    }
+    if (tx.status === "failed" || tx.status === "rejected" || tx.status === "cancelled") {
+      return tx;
+    }
+    
+    // Still pending, wait and retry
+    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+  }
+  
+  // Timeout - return last known status
+  return getTransactionStatus(config, walletAddress, transactionId);
+}
+
+export async function createTransfer(
+  config: CrossmintApiConfig,
+  walletAddress: string,
+  recipient: string,
+  token: string,
+  amount: string,
+  keypair: Keypair,
+): Promise<CrossmintTransaction> {
+  // Token locator format for Solana: solana:tokenAddress or solana:sol for native
+  const tokenLocator = token.toLowerCase() === "sol" ? "solana:sol" : `solana:${token}`;
+
+  // Step 1: Create the transfer transaction
+  const createResponse = await fetchCrossmint(
+    config,
+    `/2025-06-09/wallets/${encodeURIComponent(walletAddress)}/tokens/${encodeURIComponent(tokenLocator)}/transfers`,
+    {
+      method: "POST",
+      body: JSON.stringify({
+        recipient,
+        amount,
+        signer: `external-wallet:${keypair.publicKey.toBase58()}`,
+      }),
+    },
+  );
+
+  if (!createResponse.ok) {
+    const error = await createResponse.text();
+    throw new Error(`Failed to create transfer: ${error}`);
+  }
+
+  const txData = await createResponse.json();
+
+  // Step 2: If approval is needed, sign and submit
+  if (txData.status === "awaiting-approval" && txData.approvals?.pending?.length > 0) {
+    const approval = txData.approvals.pending[0];
+    if (approval?.message) {
+      // Sign the approval message using ed25519
+      // Message is base58 encoded (Solana standard), not hex
+      const messageBytes = bs58.decode(approval.message);
+      const nacl = (await import("tweetnacl")).default;
+      const signature = nacl.sign.detached(messageBytes, keypair.secretKey);
+      const signatureBase58 = bs58.encode(signature);
+
+      // Submit approval
+      const approveResponse = await fetchCrossmint(
+        config,
+        `/2025-06-09/wallets/${encodeURIComponent(walletAddress)}/transactions/${txData.id}/approvals`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            approvals: [
+              {
+                signer: `external-wallet:${keypair.publicKey.toBase58()}`,
+                signature: signatureBase58,
+              },
+            ],
+          }),
+        },
+      );
+
+      if (!approveResponse.ok) {
+        const error = await approveResponse.text();
+        throw new Error(`Failed to approve transfer: ${error}`);
+      }
+
+      const approvedData = await approveResponse.json();
+      return {
+        id: approvedData.id || txData.id,
+        status: approvedData.status || "pending",
+        hash: approvedData.hash,
+        explorerLink: approvedData.explorerLink,
+      };
+    }
+  }
+
+  return {
+    id: txData.id,
+    status: txData.status,
+    hash: txData.hash,
+    explorerLink: txData.explorerLink,
+  };
+}
+
+export function buildDelegationUrl(
+  delegationBaseUrl: string,
+  publicAddress: string,
+): string {
+  // URL format: {baseUrl}/configure?pubkey={publicKey}
+  const baseUrl = delegationBaseUrl.replace(/\/+$/, ""); // Remove trailing slashes
+  return `${baseUrl}/configure?pubkey=${publicAddress}`;
+}
+
+// ============================================================================
+// Headless Checkout Types (Amazon purchases with delegated signer)
+// ============================================================================
+
+export type OrderRecipient = {
+  email: string;
+  physicalAddress: {
+    name: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string; // ISO 3166-1 alpha-2 (e.g., "US")
+  };
+};
+
+export type OrderLineItem = {
+  productLocator: string; // e.g., "amazon:B00O79SKV6"
+};
+
+export type OrderPayment = {
+  receiptEmail: string;
+  method: "solana";
+  currency: string; // e.g., "usdc"
+  payerAddress: string; // Smart wallet address that pays
+};
+
+export type CreateOrderRequest = {
+  recipient: OrderRecipient;
+  payment: OrderPayment;
+  lineItems: OrderLineItem[];
+};
+
+export type OrderPhase = "quote" | "payment" | "delivery" | "completed" | "failed";
+
+export type CrossmintOrder = {
+  orderId: string;
+  phase: OrderPhase;
+  quote?: {
+    status: string;
+    totalPrice?: { amount: string; currency: string };
+  };
+  payment?: {
+    status: string;
+    preparation?: {
+      serializedTransaction?: string; // Transaction to sign for payment
+    };
+  };
+  delivery?: {
+    status: string;
+    items?: Array<{
+      status: string;
+      packageTracking?: {
+        carrierName: string;
+        carrierTrackingNumber: string;
+      };
+    }>;
+  };
+  lineItems?: Array<{
+    metadata?: {
+      title?: string;
+      imageUrl?: string;
+      price?: { amount: string; currency: string };
+    };
+  }>;
+};
+
+export type TransactionResponse = {
+  id: string;
+  status: string;
+  approvals?: {
+    pending?: Array<{
+      signer: string;
+      message: string; // Message to sign
+    }>;
+  };
+};
+
+// ============================================================================
+// Headless Checkout API Functions (Delegated Signer Flow)
+// ============================================================================
+
+/**
+ * Step 1: Create an order for purchasing products (e.g., from Amazon)
+ * Returns order with serializedTransaction to use in step 2
+ */
+export async function createOrder(
+  config: CrossmintApiConfig,
+  request: CreateOrderRequest,
+): Promise<CrossmintOrder> {
+  const response = await fetchCrossmint(config, "/2022-06-09/orders", {
+    method: "POST",
+    body: JSON.stringify(request),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to create order: ${error}`);
+  }
+
+  // API returns { clientSecret, order } - extract the order
+  const data = await response.json();
+  return data.order;
+}
+
+/**
+ * Step 2a: Create transaction from serialized transaction
+ * Returns transactionId and message to sign
+ */
+export async function createTransaction(
+  config: CrossmintApiConfig,
+  payerAddress: string,
+  serializedTransaction: string,
+  signerAddress?: string,
+): Promise<TransactionResponse> {
+  const response = await fetchCrossmint(
+    config,
+    `/2025-06-09/wallets/${encodeURIComponent(payerAddress)}/transactions`,
+    {
+      method: "POST",
+      body: JSON.stringify({
+        params: {
+          transaction: serializedTransaction,
+          ...(signerAddress && { signer: `external-wallet:${signerAddress}` }),
+        },
+      }),
+    },
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to create transaction: ${error}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Step 2b: Submit approval with signed message
+ */
+export async function submitApproval(
+  config: CrossmintApiConfig,
+  payerAddress: string,
+  transactionId: string,
+  signerAddress: string,
+  signature: string,
+): Promise<TransactionResponse> {
+  const response = await fetchCrossmint(
+    config,
+    `/2025-06-09/wallets/${encodeURIComponent(payerAddress)}/transactions/${encodeURIComponent(transactionId)}/approvals`,
+    {
+      method: "POST",
+      body: JSON.stringify({
+        approvals: [
+          {
+            signer: `external-wallet:${signerAddress}`,
+            signature,
+          },
+        ],
+      }),
+    },
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to submit approval: ${error}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Get order status
+ */
+export async function getOrder(
+  config: CrossmintApiConfig,
+  orderId: string,
+): Promise<CrossmintOrder> {
+  const response = await fetchCrossmint(
+    config,
+    `/2022-06-09/orders/${encodeURIComponent(orderId)}`,
+    { method: "GET" },
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to get order: ${error}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Complete Amazon purchase flow with delegated signer
+ * Combines all 3 API calls + local signing
+ */
+export async function purchaseProduct(
+  config: CrossmintApiConfig,
+  request: CreateOrderRequest,
+  keypair: Keypair,
+): Promise<{ order: CrossmintOrder; transactionId: string }> {
+  // Step 1: Create order
+  const order = await createOrder(config, request);
+
+  const serializedTransaction = order.payment?.preparation?.serializedTransaction;
+  if (!serializedTransaction) {
+    throw new Error(
+      `Order created but no serialized transaction returned. Payment status: ${order.payment?.status || "unknown"}`,
+    );
+  }
+
+  // Step 2a: Create transaction with delegated signer
+  const txResponse = await createTransaction(
+    config,
+    request.payment.payerAddress,
+    serializedTransaction,
+    keypair.publicKey.toBase58(),
+  );
+
+  const messageToSign = txResponse.approvals?.pending?.[0]?.message;
+  if (!messageToSign) {
+    throw new Error("Transaction created but no message to sign");
+  }
+
+  // Step 2 (local): Sign the message with ed25519
+  // Message is base58 encoded (Solana standard) - same as transfers
+  const messageBytes = bs58.decode(messageToSign);
+  const nacl = (await import("tweetnacl")).default;
+  const signature = nacl.sign.detached(messageBytes, keypair.secretKey);
+  const signatureBase58 = bs58.encode(signature);
+
+  // Step 2b: Submit approval
+  await submitApproval(
+    config,
+    request.payment.payerAddress,
+    txResponse.id,
+    keypair.publicKey.toBase58(),
+    signatureBase58,
+  );
+
+  return { order, transactionId: txResponse.id };
+}
+
+/**
+ * Build Amazon product locator from ASIN or URL
+ */
+export function buildAmazonProductLocator(productIdOrUrl: string): string {
+  if (productIdOrUrl.startsWith("amazon:")) {
+    return productIdOrUrl;
+  }
+  if (productIdOrUrl.includes("amazon.com")) {
+    return `amazon:${productIdOrUrl}`;
+  }
+  // Assume it's an ASIN
+  return `amazon:${productIdOrUrl}`;
+}

package/src/config.ts

@@ -0,0 +1,11 @@
+// Hardcoded configuration - no user config needed
+export const DELEGATION_URL = "https://www.lobster.cash/";
+export const ENVIRONMENT = "staging" as const;
+
+export type CrossmintPluginConfig = Record<string, never>;
+
+export const crossmintConfigSchema = {
+  parse(_value: unknown): CrossmintPluginConfig {
+    return {};
+  },
+};