@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/workflows/templates.ts

@@ -0,0 +1,86 @@
+import type { WorkflowDefinition, WorkflowTemplate } from "../types";
+
+/**
+ * Validate that all required template variables are provided.
+ * Returns a list of missing required variable names.
+ */
+export function validateTemplateVariables(
+  template: WorkflowTemplate,
+  provided: Record<string, unknown>,
+): string[] {
+  const missing: string[] = [];
+  for (const variable of template.variables) {
+    if (variable.required && !(variable.name in provided)) {
+      // Check if there's a default value
+      if (variable.default === undefined) {
+        missing.push(variable.name);
+      }
+    }
+  }
+  return missing;
+}
+
+/**
+ * Instantiate a workflow template with the given variables.
+ *
+ * 1. Validates all required variables are provided
+ * 2. Deep-clones the template definition
+ * 3. Replaces `{{variable}}` placeholders in all string fields
+ * 4. Returns a valid WorkflowDefinition
+ */
+export function instantiateTemplate(
+  template: WorkflowTemplate,
+  variables: Record<string, unknown>,
+): WorkflowDefinition {
+  // Validate required variables
+  const missing = validateTemplateVariables(template, variables);
+  if (missing.length > 0) {
+    throw new Error(`Missing required template variables: ${missing.join(", ")}`);
+  }
+
+  // Build resolved variables (apply defaults for missing optional vars)
+  const resolved: Record<string, unknown> = {};
+  for (const variable of template.variables) {
+    if (variable.name in variables) {
+      resolved[variable.name] = variables[variable.name];
+    } else if (variable.default !== undefined) {
+      resolved[variable.name] = variable.default;
+    }
+  }
+
+  // Deep-clone the definition and replace placeholders
+  const cloned = JSON.parse(JSON.stringify(template.definition)) as WorkflowDefinition;
+  return replaceVariables(cloned, resolved);
+}
+
+/**
+ * Deep-replace `{{variableName}}` placeholders in all string fields of an object.
+ */
+function replaceVariables<T>(obj: T, variables: Record<string, unknown>): T {
+  if (typeof obj === "string") {
+    return replaceStringPlaceholders(obj, variables) as T;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => replaceVariables(item, variables)) as T;
+  }
+  if (obj !== null && typeof obj === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = replaceVariables(value, variables);
+    }
+    return result as T;
+  }
+  return obj;
+}
+
+/**
+ * Replace `{{variableName}}` patterns in a string with variable values.
+ */
+function replaceStringPlaceholders(template: string, variables: Record<string, unknown>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_match, name: string) => {
+    const value = variables[name];
+    if (value === undefined) return _match; // Leave unresolved placeholders as-is
+    if (typeof value === "object" && value !== null) return JSON.stringify(value);
+    return String(value);
+  });
+}

package/src/workflows/triggers.ts

@@ -0,0 +1,124 @@
+import crypto from "node:crypto";
+import { getWorkflow, getWorkflowsByScheduleId } from "../be/db";
+import type { ScheduledTask, TriggerConfig } from "../types";
+import { startWorkflowExecution } from "./engine";
+import type { ExecutorRegistry } from "./executors/registry";
+
+/**
+ * Handle an incoming webhook trigger for a workflow.
+ *
+ * 1. Loads the workflow and finds a webhook trigger in `triggers[]`
+ * 2. If `hmacSecret` is set, verifies HMAC-SHA256 signature
+ * 3. Starts the workflow execution with the webhook payload
+ */
+export async function handleWebhookTrigger(
+  workflowId: string,
+  payload: unknown,
+  signature: string | undefined,
+  signatureHeader: string | undefined,
+  registry: ExecutorRegistry,
+): Promise<{ runId: string }> {
+  const workflow = getWorkflow(workflowId);
+  if (!workflow) {
+    throw new WebhookError("Workflow not found", 404);
+  }
+
+  if (!workflow.enabled) {
+    throw new WebhookError("Workflow is disabled", 400);
+  }
+
+  // Find webhook trigger in triggers[]
+  const webhookTrigger = workflow.triggers.find((t: TriggerConfig) => t.type === "webhook");
+
+  // If the workflow has a webhook trigger with an hmacSecret, verify the signature
+  if (webhookTrigger && webhookTrigger.type === "webhook" && webhookTrigger.hmacSecret) {
+    if (!signature && !signatureHeader) {
+      throw new WebhookError("Missing signature", 401);
+    }
+
+    const rawSignature = signatureHeader || signature || "";
+    const isValid = verifyHmacSignature(
+      webhookTrigger.hmacSecret,
+      typeof payload === "string" ? payload : JSON.stringify(payload),
+      rawSignature,
+    );
+
+    if (!isValid) {
+      throw new WebhookError("Invalid signature", 401);
+    }
+  }
+
+  const runId = await startWorkflowExecution(workflow, payload, registry);
+  return { runId };
+}
+
+/**
+ * Handle a schedule trigger: find workflows linked to this schedule and execute them.
+ * Returns an array of workflow run IDs. Empty array means no workflows matched
+ * (caller should fall through to standalone task creation).
+ */
+export async function handleScheduleTrigger(
+  scheduleId: string,
+  schedule: ScheduledTask,
+  registry: ExecutorRegistry,
+): Promise<string[]> {
+  const workflows = getWorkflowsByScheduleId(scheduleId);
+  if (workflows.length === 0) return [];
+
+  const runIds: string[] = [];
+  for (const workflow of workflows) {
+    const triggerData = {
+      scheduleId,
+      scheduleName: schedule.name,
+      firedAt: new Date().toISOString(),
+    };
+    const runId = await startWorkflowExecution(workflow, triggerData, registry);
+    runIds.push(runId);
+    console.log(
+      `[Triggers] Schedule "${schedule.name}" triggered workflow "${workflow.name}" (run: ${runId})`,
+    );
+  }
+  return runIds;
+}
+
+/**
+ * Verify HMAC-SHA256 signature.
+ * Supports both `sha256=<hex>` format and raw hex.
+ */
+export function verifyHmacSignature(
+  secret: string,
+  body: string,
+  providedSignature: string,
+): boolean {
+  const hmac = crypto.createHmac("sha256", secret);
+  hmac.update(body);
+  const expectedHex = hmac.digest("hex");
+
+  // Support "sha256=<hex>" format (GitHub-style)
+  const normalizedProvided = providedSignature.startsWith("sha256=")
+    ? providedSignature.slice(7)
+    : providedSignature;
+
+  // Constant-time comparison
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(normalizedProvided, "hex"),
+      Buffer.from(expectedHex, "hex"),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Error class for webhook-specific errors with HTTP status codes.
+ */
+export class WebhookError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+  ) {
+    super(message);
+    this.name = "WebhookError";
+  }
+}

package/src/workflows/validation.ts

@@ -0,0 +1,104 @@
+import type { ExecutorMeta, WorkflowNode } from "../types";
+import type { ExecutorRegistry } from "./executors/registry";
+
+export type ValidationOutcome = "pass" | "halt" | "retry";
+
+export interface ValidationRunResult {
+  outcome: ValidationOutcome;
+  /** Context additions if retry is needed */
+  retryContext?: Record<string, unknown>;
+}
+
+/**
+ * Normalize executor output to a pass/fail boolean.
+ *
+ * Different executors use different output shapes to indicate success.
+ * This adapter maps each executor type's convention to a uniform boolean.
+ */
+export function extractPassResult(executorType: string, output: unknown): boolean {
+  if (!output || typeof output !== "object") return false;
+  const o = output as Record<string, unknown>;
+
+  switch (executorType) {
+    case "validate":
+      return o.pass === true;
+    case "script":
+      return o.exitCode === 0;
+    case "property-match":
+      return o.passed === true;
+    case "raw-llm":
+      // For raw-llm used as validator, check if the LLM output contains a structured pass result
+      if (typeof o.result === "object" && o.result !== null) {
+        return (o.result as Record<string, unknown>).pass === true;
+      }
+      return false;
+    default:
+      // Generic fallback: check for common pass indicators
+      return o.pass === true || o.passed === true || o.exitCode === 0;
+  }
+}
+
+/**
+ * Run per-step validation after a step completes.
+ *
+ * If the node has no validation config, returns "pass" immediately.
+ * Otherwise runs the validation executor and returns the outcome.
+ */
+export async function runStepValidation(
+  registry: ExecutorRegistry,
+  stepNode: WorkflowNode,
+  stepOutput: unknown,
+  context: Record<string, unknown>,
+  meta: ExecutorMeta,
+): Promise<ValidationRunResult> {
+  if (!stepNode.validation) {
+    return { outcome: "pass" };
+  }
+
+  const validation = stepNode.validation;
+  const executorType = validation.executor || "validate";
+
+  const executor = registry.get(executorType);
+  const validationConfig = {
+    targetNodeId: meta.nodeId,
+    ...validation.config,
+  };
+
+  // Build a context that includes the step output under its nodeId
+  const validationContext: Record<string, unknown> = {
+    ...context,
+    [meta.nodeId]: stepOutput,
+  };
+
+  const result = await executor.run({
+    config: validationConfig,
+    context: validationContext,
+    meta: {
+      ...meta,
+      stepId: crypto.randomUUID(), // Validation gets its own step ID
+    },
+  });
+
+  const passed = result.status === "success" && extractPassResult(executorType, result.output);
+
+  if (passed) {
+    return { outcome: "pass" };
+  }
+
+  // Validation failed
+  if (validation.mustPass) {
+    if (validation.retry) {
+      return {
+        outcome: "retry",
+        retryContext: {
+          previousOutput: stepOutput,
+          validationResult: result.output,
+        },
+      };
+    }
+    return { outcome: "halt" };
+  }
+
+  // mustPass is false — treat failure as pass (advisory validation)
+  return { outcome: "pass" };
+}

package/src/workflows/version.ts

@@ -0,0 +1,44 @@
+import { createWorkflowVersion, getWorkflow, getWorkflowVersions } from "../be/db";
+import type { WorkflowSnapshot, WorkflowVersion } from "../types";
+
+/**
+ * Create a version snapshot of a workflow's current state.
+ *
+ * Call this BEFORE applying an update to preserve the pre-update state.
+ *
+ * 1. Load current workflow state
+ * 2. Get max version number for this workflow
+ * 3. Insert workflow_versions row with version+1 and full snapshot
+ */
+export function snapshotWorkflow(workflowId: string, changedByAgentId?: string): WorkflowVersion {
+  const workflow = getWorkflow(workflowId);
+  if (!workflow) {
+    throw new Error(`Workflow ${workflowId} not found — cannot create snapshot`);
+  }
+
+  // Get existing versions to determine next version number
+  const existingVersions = getWorkflowVersions(workflowId);
+  const maxVersion = existingVersions.length > 0 ? existingVersions[0]!.version : 0;
+  const nextVersion = maxVersion + 1;
+
+  // Build snapshot of current state
+  const snapshot: WorkflowSnapshot = {
+    name: workflow.name,
+    description: workflow.description,
+    definition: workflow.definition,
+    triggers: workflow.triggers,
+    cooldown: workflow.cooldown,
+    input: workflow.input,
+    triggerSchema: workflow.triggerSchema,
+    dir: workflow.dir,
+    vcsRepo: workflow.vcsRepo,
+    enabled: workflow.enabled,
+  };
+
+  return createWorkflowVersion({
+    workflowId,
+    version: nextVersion,
+    snapshot,
+    changedByAgentId,
+  });
+}

package/src/x402/cli.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+/**
+ * x402 CLI — Test x402 payments from the command line.
+ *
+ * Usage:
+ *   bun src/x402/cli.ts fetch <url>         Make a paid request to a URL
+ *   bun src/x402/cli.ts status              Show spending summary
+ *   bun src/x402/cli.ts check               Check if x402 is configured
+ *
+ * Signer backends (auto-detected):
+ *   Openfort:  OPENFORT_API_KEY + OPENFORT_WALLET_SECRET
+ *   Viem:      EVM_PRIVATE_KEY (0x-prefixed hex)
+ *
+ * Environment:
+ *   X402_SIGNER_TYPE        "openfort" or "viem" (auto-detected if not set)
+ *   OPENFORT_API_KEY        Openfort API key (sk_test_ or sk_live_)
+ *   OPENFORT_WALLET_SECRET  Openfort wallet secret (base64 P-256 key)
+ *   EVM_PRIVATE_KEY         Raw wallet private key (0x-prefixed)
+ *   X402_MAX_AUTO_APPROVE   Max USD per request (default: 1.00)
+ *   X402_DAILY_LIMIT        Daily USD limit (default: 10.00)
+ *   X402_NETWORK            CAIP-2 network ID (default: eip155:84532)
+ */
+
+import { createX402Client } from "./client.ts";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+async function main() {
+  switch (command) {
+    case "fetch": {
+      const url = args[1];
+      if (!url) {
+        console.error("Usage: x402 fetch <url>");
+        process.exit(1);
+      }
+
+      const method = (args[2] || "GET").toUpperCase();
+      console.log(`Making ${method} request to ${url} with x402 payment support...\n`);
+
+      const client = await createX402Client();
+      const summary = client.getSpendingSummary();
+      console.log(`Signer: ${client.config.signerType} | Wallet: ${client.walletAddress}`);
+      console.log(
+        `Spending limits: $${summary.maxPerRequest.toFixed(2)}/request, ` +
+          `$${summary.dailyLimit.toFixed(2)}/day ` +
+          `($${summary.dailyRemaining.toFixed(2)} remaining)\n`,
+      );
+
+      const response = await client.fetch(url, { method });
+
+      console.log(`Status: ${response.status} ${response.statusText}`);
+      console.log("Headers:");
+      for (const [key, value] of response.headers.entries()) {
+        if (key.toLowerCase().startsWith("payment") || key.toLowerCase() === "content-type") {
+          console.log(`  ${key}: ${value}`);
+        }
+      }
+
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("json")) {
+        const body = await response.json();
+        console.log("\nResponse body:");
+        console.log(JSON.stringify(body, null, 2));
+      } else {
+        const body = await response.text();
+        console.log(`\nResponse body (${body.length} chars):`);
+        console.log(body.slice(0, 2000));
+        if (body.length > 2000) console.log("... (truncated)");
+      }
+
+      const updatedSummary = client.getSpendingSummary();
+      console.log(
+        `\nSpending: $${updatedSummary.todaySpent.toFixed(2)} today ` +
+          `(${updatedSummary.todayCount} payments, ` +
+          `$${updatedSummary.dailyRemaining.toFixed(2)} remaining)`,
+      );
+      break;
+    }
+
+    case "status": {
+      const client = await createX402Client();
+      const summary = client.getSpendingSummary();
+      console.log("x402 Spending Status");
+      console.log("====================");
+      console.log(`Signer:            ${client.config.signerType}`);
+      console.log(`Wallet:            ${client.walletAddress}`);
+      console.log(`Per-request limit: $${summary.maxPerRequest.toFixed(2)}`);
+      console.log(`Daily limit:       $${summary.dailyLimit.toFixed(2)}`);
+      console.log(`Today spent:       $${summary.todaySpent.toFixed(2)}`);
+      console.log(`Today remaining:   $${summary.dailyRemaining.toFixed(2)}`);
+      console.log(`Today payments:    ${summary.todayCount}`);
+      break;
+    }
+
+    case "check": {
+      try {
+        const client = await createX402Client();
+        console.log("x402 Configuration");
+        console.log("==================");
+        console.log(`Signer type:     ${client.config.signerType}`);
+        console.log(`Wallet address:  ${client.walletAddress}`);
+        console.log(`Max per request: $${client.config.maxAutoApprove.toFixed(2)}`);
+        console.log(`Daily limit:     $${client.config.dailyLimit.toFixed(2)}`);
+        console.log(`Network:         ${client.config.network}`);
+        console.log("\nx402 is configured and ready.");
+      } catch (error) {
+        console.error(
+          `x402 configuration error: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        process.exit(1);
+      }
+      break;
+    }
+
+    default:
+      console.log("x402 CLI — Test x402 payments\n");
+      console.log("Commands:");
+      console.log("  fetch <url> [method]  Make a paid request (default: GET)");
+      console.log("  status               Show spending summary");
+      console.log("  check                Check if x402 is configured");
+      console.log("\nSigner backends (auto-detected):");
+      console.log("  Openfort:  OPENFORT_API_KEY + OPENFORT_WALLET_SECRET");
+      console.log("  Viem:      EVM_PRIVATE_KEY (0x-prefixed hex)");
+      console.log("\nEnvironment variables:");
+      console.log("  X402_SIGNER_TYPE        'openfort' or 'viem' (auto-detected)");
+      console.log("  OPENFORT_API_KEY        Openfort API key");
+      console.log("  OPENFORT_WALLET_SECRET  Openfort wallet auth secret");
+      console.log("  EVM_PRIVATE_KEY         Raw private key (0x-prefixed)");
+      console.log("  X402_MAX_AUTO_APPROVE   Max USD per request (default: 1.00)");
+      console.log("  X402_DAILY_LIMIT        Daily USD limit (default: 10.00)");
+      console.log("  X402_NETWORK            CAIP-2 network ID (default: eip155:84532)");
+      break;
+  }
+}
+
+main().catch((error) => {
+  console.error("Error:", error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/x402/client.ts

@@ -0,0 +1,192 @@
+/**
+ * x402 Payment Client
+ *
+ * A reusable payment client that wraps fetch() with automatic x402 payment handling
+ * and configurable spending limits.
+ *
+ * Supports two signer backends:
+ *   - Openfort (default) — managed backend wallet, no raw keys in env
+ *   - viem — raw EVM_PRIVATE_KEY for local signing
+ *
+ * Usage:
+ *   import { createX402Fetch, createX402Client } from "@/x402";
+ *
+ *   // Quick: get a paid fetch function
+ *   const paidFetch = await createX402Fetch();
+ *   const response = await paidFetch("https://api.example.com/paid-endpoint");
+ *
+ *   // Advanced: get the full client with spending info
+ *   const client = await createX402Client();
+ *   const response = await client.fetch("https://api.example.com/paid-endpoint");
+ *   console.log(client.getSpendingSummary());
+ */
+
+import { x402Client } from "@x402/core/client";
+import type { ClientEvmSigner } from "@x402/evm";
+import { toClientEvmSigner } from "@x402/evm";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { createPublicClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base, baseSepolia } from "viem/chains";
+import { loadX402Config, type X402Config, type X402SafeConfig } from "./config.ts";
+import { createOpenfortSigner } from "./openfort-signer.ts";
+import { SpendingTracker } from "./spending-tracker.ts";
+
+export interface X402PaymentClient {
+  /** A fetch function that automatically handles x402 402 responses */
+  fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+  /** The underlying x402Client instance */
+  x402Client: x402Client;
+  /** The spending tracker for monitoring limits */
+  spendingTracker: SpendingTracker;
+  /** Get a summary of today's spending */
+  getSpendingSummary: () => ReturnType<SpendingTracker["getSummary"]>;
+  /** The wallet address used for payments */
+  walletAddress: `0x${string}`;
+  /** Safe config subset (no secrets) */
+  config: X402SafeConfig;
+}
+
+/**
+ * Map CAIP-2 network ID to viem chain config.
+ */
+function getChainForNetwork(network: string) {
+  if (network === "eip155:8453") return base;
+  return baseSepolia; // Default to testnet
+}
+
+/**
+ * Create a signer based on the config's signerType.
+ */
+async function buildSigner(
+  config: X402Config,
+): Promise<{ signer: ClientEvmSigner; walletAddress: `0x${string}` }> {
+  if (config.signerType === "openfort") {
+    if (!config.openfortApiKey || !config.openfortWalletSecret) {
+      throw new Error("Openfort signer requires OPENFORT_API_KEY and OPENFORT_WALLET_SECRET.");
+    }
+
+    const chain = getChainForNetwork(config.network);
+    const signer = await createOpenfortSigner({
+      apiKey: config.openfortApiKey,
+      walletSecret: config.openfortWalletSecret,
+      walletAddress: config.openfortWalletAddress,
+      chain,
+    });
+
+    return { signer, walletAddress: signer.address };
+  }
+
+  // viem signer (raw private key)
+  if (!config.evmPrivateKey) {
+    throw new Error("Viem signer requires EVM_PRIVATE_KEY.");
+  }
+
+  const account = privateKeyToAccount(config.evmPrivateKey);
+  const chain = getChainForNetwork(config.network);
+  const publicClient = createPublicClient({ chain, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+
+  return { signer, walletAddress: account.address };
+}
+
+/**
+ * Create a full x402 payment client with spending controls.
+ *
+ * NOTE: This is async because Openfort signer requires API calls to create/retrieve wallets.
+ *
+ * @param configOverrides - Optional config overrides (otherwise loaded from env vars)
+ * @returns An X402PaymentClient with fetch, spending tracker, and config
+ */
+export async function createX402Client(
+  configOverrides?: Partial<X402Config>,
+): Promise<X402PaymentClient> {
+  const envConfig = loadX402Config();
+  const config = { ...envConfig, ...configOverrides };
+
+  // Build the signer (async for Openfort, instant for viem)
+  const { signer, walletAddress } = await buildSigner(config);
+
+  // Create and configure x402 client
+  const client = new x402Client();
+  registerExactEvmScheme(client, { signer });
+
+  // Create spending tracker
+  const spendingTracker = new SpendingTracker(config.maxAutoApprove, config.dailyLimit);
+
+  // Register a spending-limit hook that blocks over-budget payments.
+  // NOTE: This check has a TOCTOU race — concurrent requests could both pass the
+  // limit check before either records its payment. Acceptable for agent workloads
+  // (typically sequential), but not suitable for high-concurrency scenarios.
+  client.onBeforePaymentCreation(async (context) => {
+    const { selectedRequirements } = context;
+
+    // V2 PaymentRequirements uses `amount` (smallest unit, e.g. "10000" for $0.01 USDC)
+    const rawValue = selectedRequirements.amount;
+    const amountUsd = usdcToUsd(rawValue);
+
+    const url = context.paymentRequired.resource?.url || "unknown";
+    const blockReason = spendingTracker.checkSpendingLimit(amountUsd, url);
+
+    if (blockReason) {
+      return { abort: true, reason: blockReason };
+    }
+  });
+
+  // Track successful payments
+  client.onAfterPaymentCreation(async (context) => {
+    const rawValue = context.selectedRequirements.amount;
+    const amountUsd = usdcToUsd(rawValue);
+    const url = context.paymentRequired.resource?.url || "unknown";
+    spendingTracker.recordPayment(amountUsd, url);
+  });
+
+  // Wrap fetch with payment handling
+  const paidFetch = wrapFetchWithPayment(globalThis.fetch, client);
+
+  // Expose a safe config subset — never leak secrets
+  const {
+    evmPrivateKey: _key,
+    openfortApiKey: _apiKey,
+    openfortWalletSecret: _secret,
+    ...safeConfig
+  } = config;
+
+  return {
+    fetch: paidFetch as (input: string | URL | Request, init?: RequestInit) => Promise<Response>,
+    x402Client: client,
+    spendingTracker,
+    getSpendingSummary: () => spendingTracker.getSummary(),
+    walletAddress,
+    config: safeConfig,
+  };
+}
+
+/**
+ * Create a simple paid fetch function.
+ * This is the easiest way to get started — just replace `fetch` with this.
+ *
+ * @param configOverrides - Optional config overrides
+ * @returns A fetch function that automatically handles x402 payments
+ */
+export async function createX402Fetch(
+  configOverrides?: Partial<X402Config>,
+): Promise<(input: string | URL | Request, init?: RequestInit) => Promise<Response>> {
+  return (await createX402Client(configOverrides)).fetch;
+}
+
+/**
+ * Convert USDC raw value (6 decimals) to USD.
+ * USDC uses 6 decimal places, so 1000000 = $1.00
+ */
+function usdcToUsd(rawValue: string): number {
+  try {
+    return Number(BigInt(rawValue)) / 1_000_000;
+  } catch {
+    // If the value can't be parsed as BigInt, fall back to parseFloat
+    const parsed = Number.parseFloat(rawValue);
+    if (Number.isNaN(parsed)) return 0;
+    return parsed / 1_000_000;
+  }
+}