Add honest accounting and automatic refund mechanism for completed jobs

Implement honest accounting post-job completion, calculating actual costs, adding margin, and enabling automatic refunds for overpayments via a new endpoint.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 418bf6f8-212b-4bb0-a7a5-8231a061da4e
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: c6386de2-d5f4-47cc-a557-73416f09e118
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/9f85e954-647c-46a5-90a7-396e495a805a/418bf6f8-212b-4bb0-a7a5-8231a061da4e/sPDHkg8
Replit-Helium-Checkpoint-Created: true

lib/api-zod/src/generated/api.ts

@@ -90,15 +90,70 @@ export const GetJobResponse = zod.object({
         .number()
         .optional()
         .describe("Raw Anthropic token cost (no infra, no margin)"),
-      estimatedCostUsd: zod.number().optional(),
+      actualChargeUsd: zod
+        .number()
+        .optional()
+        .describe(
+          "What we honestly charged in USD (actual token cost + DO infra + margin)",
+        ),
+      estimatedCostUsd: zod
+        .number()
+        .optional()
+        .describe("Original estimate used to create the work invoice"),
+      actualAmountSats: zod
+        .number()
+        .optional()
+        .describe(
+          "Honest sats charge (actual cost converted at the locked BTC price)",
+        ),
+      workAmountSats: zod
+        .number()
+        .optional()
+        .describe("Amount the user originally paid in sats"),
+      refundAmountSats: zod
+        .number()
+        .optional()
+        .describe(
+          "Sats owed back to the user (workAmountSats - actualAmountSats, >= 0)",
+        ),
+      refundState: zod
+        .enum(["not_applicable", "pending", "paid"])
+        .optional()
+        .describe("Lifecycle of the refund for this job"),
       marginPct: zod.number().optional(),
-      btcPriceUsd: zod.number().optional(),
+      btcPriceUsd: zod
+        .number()
+        .optional()
+        .describe("BTC\/USD price locked at invoice creation time"),
     })
     .optional()
-    .describe("Actual cost record stored after the job completes"),
+    .describe("Honest post-work accounting stored after the job completes"),
   errorMessage: zod.string().optional(),
 });
 
+/**
+ * After a job completes, if the actual cost (tokens used + infra + margin) was
+less than the work invoice amount, the difference is owed back to the user.
+Submit a BOLT11 invoice for exactly `refundAmountSats` to receive the payment.
+Idempotent: returns 409 if already paid or if no refund is owed.
+
+ * @summary Claim a refund for overpayment
+ */
+export const ClaimRefundParams = zod.object({
+  id: zod.coerce.string(),
+});
+
+export const ClaimRefundBody = zod.object({
+  invoice: zod.string().describe("BOLT11 invoice for exactly refundAmountSats"),
+});
+
+export const ClaimRefundResponse = zod.object({
+  ok: zod.boolean(),
+  refundAmountSats: zod.number(),
+  paymentHash: zod.string(),
+  message: zod.string(),
+});
+
 /**
  * Runs the agent without payment. Limited to 5 requests per IP per hour.
  * @summary Free demo (rate-limited)