@agrentingai/paperclip-adapter 0.2.0

package/server/src/balance-monitor.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  checkBalance,
+  canSubmitTask,
+  formatLowBalanceComment,
+  formatInsufficientBalanceComment,
+} from "./balance-monitor.js";
+
+const mockConfig = {
+  agrentingUrl: "https://example.agrenting.com",
+  apiKey: "test-key",
+  agentDid: "did:agrenting:test",
+};
+
+function mockBalanceResponse(available: string, escrow = "0", total = available, currency = "USD") {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ available, escrow, total, currency }),
+    })
+  );
+}
+
+function mockFetchError() {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn().mockRejectedValue(new Error("Network error"))
+  );
+}
+
+beforeEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("checkBalance", () => {
+  it("returns balance info when API returns valid numbers", async () => {
+    mockBalanceResponse("50.00", "10.00", "60.00");
+    const result = await checkBalance({ config: mockConfig });
+    expect(result).toEqual({
+      available: 50,
+      escrow: 10,
+      total: 60,
+      currency: "USD",
+      isLow: false,
+      isInsufficient: false,
+    });
+  });
+
+  it("marks balance as low when below threshold", async () => {
+    mockBalanceResponse("5.00", "0", "5.00"); // $5, below $10 threshold
+    const result = await checkBalance({ config: mockConfig });
+    expect(result.isLow).toBe(true);
+    expect(result.isInsufficient).toBe(false);
+  });
+
+  it("marks balance as insufficient when below minimum submission", async () => {
+    mockBalanceResponse("0.50", "0", "0.50"); // $0.50, below $1 threshold
+    const result = await checkBalance({ config: mockConfig });
+    expect(result.isLow).toBe(true);
+    expect(result.isInsufficient).toBe(true);
+  });
+
+  it("handles NaN balance gracefully", async () => {
+    mockBalanceResponse("not-a-number", "0", "not-a-number");
+    const result = await checkBalance({ config: mockConfig });
+    expect(result).toEqual({
+      available: 0,
+      escrow: 0,
+      total: 0,
+      currency: "USD",
+      isLow: true,
+      isInsufficient: true,
+    });
+  });
+
+  it("handles fetch errors by returning insufficient balance", { timeout: 15_000 }, async () => {
+    mockFetchError();
+    const result = await checkBalance({ config: mockConfig });
+    expect(result).toEqual({
+      available: 0,
+      escrow: 0,
+      total: 0,
+      currency: "USD",
+      isLow: true,
+      isInsufficient: true,
+    });
+  });
+
+  it("respects custom thresholds", async () => {
+    mockBalanceResponse("20.00", "0", "20.00"); // $20
+    const result = await checkBalance({
+      config: mockConfig,
+      lowBalanceThresholdUsd: 50,
+      minSubmissionBalanceUsd: 5,
+    });
+    expect(result.isLow).toBe(true);
+    expect(result.isInsufficient).toBe(false);
+  });
+});
+
+describe("canSubmitTask", () => {
+  it("returns ok when balance is sufficient", async () => {
+    mockBalanceResponse("50.00");
+    const result = await canSubmitTask({ config: mockConfig });
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("returns reason when balance is insufficient", async () => {
+    mockBalanceResponse("0.50");
+    const result = await canSubmitTask({ config: mockConfig });
+    expect(result).toEqual({
+      ok: false,
+      reason: "Insufficient balance: $0.50. Minimum required: $1.00.",
+    });
+  });
+});
+
+describe("formatLowBalanceComment", () => {
+  it("returns a markdown warning comment", () => {
+    const comment = formatLowBalanceComment({
+      available: 8,
+      escrow: 2,
+      total: 10,
+      currency: "USD",
+      isLow: true,
+      isInsufficient: false,
+    });
+    expect(comment).toContain("**Agrenting balance warning**");
+    expect(comment).toContain("$8.00");
+  });
+});
+
+describe("formatInsufficientBalanceComment", () => {
+  it("returns a markdown blocking comment", () => {
+    const comment = formatInsufficientBalanceComment({
+      available: 0,
+      escrow: 0,
+      total: 0,
+      currency: "USD",
+      isLow: true,
+      isInsufficient: true,
+    });
+    expect(comment).toContain("**Agrenting task blocked**");
+    expect(comment).toContain("$0.00");
+  });
+});

package/server/src/balance-monitor.ts

@@ -0,0 +1,118 @@
+/**
+ * Balance monitoring for the Agrenting adapter.
+ *
+ * Monitors the platform balance via `GET /api/v1/ledger/balance`
+ * and provides low-balance warnings and pre-submission checks.
+ */
+
+import { AgrentingClient } from "./client.js";
+import type { AgrentingAdapterConfig } from "./types.js";
+
+export interface BalanceInfo {
+  available: number;
+  escrow: number;
+  total: number;
+  currency: string;
+  isLow: boolean;
+  isInsufficient: boolean;
+}
+
+export interface BalanceCheckOptions {
+  config: AgrentingAdapterConfig;
+  /** Low balance threshold in USD (default: $10) */
+  lowBalanceThresholdUsd?: number;
+  /** Minimum balance required to submit a task in USD (default: $1) */
+  minSubmissionBalanceUsd?: number;
+}
+
+/**
+ * Fetch the current platform balance and evaluate thresholds.
+ * The server returns { available, escrow, total } — we use `available`
+ * for threshold checks since escrowed funds are already committed.
+ */
+export async function checkBalance(
+  options: BalanceCheckOptions
+): Promise<BalanceInfo> {
+  const client = new AgrentingClient(options.config);
+  const lowThreshold = options.lowBalanceThresholdUsd ?? 10;
+  const minSubmission = options.minSubmissionBalanceUsd ?? 1;
+
+  try {
+    const raw = await client.getBalance();
+    const available = parseFloat(raw.available);
+    const escrow = parseFloat(raw.escrow);
+    const total = parseFloat(raw.total);
+
+    const anyNaN = Number.isNaN(available) || Number.isNaN(escrow) || Number.isNaN(total);
+    if (anyNaN) {
+      return {
+        available: 0,
+        escrow: 0,
+        total: 0,
+        currency: raw.currency ?? "USD",
+        isLow: true,
+        isInsufficient: true,
+      };
+    }
+
+    return {
+      available,
+      escrow,
+      total,
+      currency: raw.currency ?? "USD",
+      isLow: available < lowThreshold,
+      isInsufficient: available < minSubmission,
+    };
+  } catch {
+    // If we can't fetch balance, assume insufficient to avoid failed submissions
+    return {
+      available: 0,
+      escrow: 0,
+      total: 0,
+      currency: "USD",
+      isLow: true,
+      isInsufficient: true,
+    };
+  }
+}
+
+/**
+ * Pre-submission balance check.
+ * Returns { ok: true } if sufficient, or { ok: false, reason } if not.
+ */
+export async function canSubmitTask(
+  options: BalanceCheckOptions
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  const balanceInfo = await checkBalance(options);
+
+  if (balanceInfo.isInsufficient) {
+    return {
+      ok: false,
+      reason: `Insufficient balance: ${formatUsd(balanceInfo.available)}. Minimum required: ${formatUsd(options.minSubmissionBalanceUsd ?? 1)}.`,
+    };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Format a USD amount as a human-readable dollar string.
+ */
+function formatUsd(amount: number): string {
+  return `$${amount.toFixed(2)}`;
+}
+
+/**
+ * Generate a warning comment for low balance.
+ * Returns the markdown comment to post on the Paperclip issue.
+ */
+export function formatLowBalanceComment(balanceInfo: BalanceInfo): string {
+  return `**Agrenting balance warning** — Available: ${formatUsd(balanceInfo.available)} ${balanceInfo.currency} (Escrowed: ${formatUsd(balanceInfo.escrow)}). Funds are running low. Add credits to avoid task submission failures.`;
+}
+
+/**
+ * Generate a blocking comment for insufficient balance.
+ */
+export function formatInsufficientBalanceComment(balanceInfo: BalanceInfo): string {
+  return `**Agrenting task blocked** — Insufficient balance: ${formatUsd(balanceInfo.available)} ${balanceInfo.currency}. Please add credits to your Agrenting account before retrying.`;
+}