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)

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

@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.5.3 🍺
+ * Do not edit manually.
+ * Api
+ * API specification
+ * OpenAPI spec version: 0.1.0
+ */
+
+export interface ClaimRefundRequest {
+  /** BOLT11 invoice for exactly refundAmountSats */
+  invoice: string;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.5.3 🍺
+ * Do not edit manually.
+ * Api
+ * API specification
+ * OpenAPI spec version: 0.1.0
+ */
+
+export interface ClaimRefundResponse {
+  ok: boolean;
+  refundAmountSats: number;
+  paymentHash: string;
+  message: string;
+}

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

@@ -5,9 +5,10 @@
  * API specification
  * OpenAPI spec version: 0.1.0
  */
+import type { CostLedgerRefundState } from "./costLedgerRefundState";
 
 /**
- * Actual cost record stored after the job completes
+ * Honest post-work accounting stored after the job completes
  */
 export interface CostLedger {
   actualInputTokens?: number;
@@ -16,7 +17,19 @@ export interface CostLedger {
   totalTokens?: number;
   /** Raw Anthropic token cost (no infra, no margin) */
   actualCostUsd?: number;
+  /** What we honestly charged in USD (actual token cost + DO infra + margin) */
+  actualChargeUsd?: number;
+  /** Original estimate used to create the work invoice */
   estimatedCostUsd?: number;
+  /** Honest sats charge (actual cost converted at the locked BTC price) */
+  actualAmountSats?: number;
+  /** Amount the user originally paid in sats */
+  workAmountSats?: number;
+  /** Sats owed back to the user (workAmountSats - actualAmountSats, >= 0) */
+  refundAmountSats?: number;
+  /** Lifecycle of the refund for this job */
+  refundState?: CostLedgerRefundState;
   marginPct?: number;
+  /** BTC/USD price locked at invoice creation time */
   btcPriceUsd?: number;
 }

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

@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v8.5.3 🍺
+ * Do not edit manually.
+ * Api
+ * API specification
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Lifecycle of the refund for this job
+ */
+export type CostLedgerRefundState =
+  (typeof CostLedgerRefundState)[keyof typeof CostLedgerRefundState];
+
+export const CostLedgerRefundState = {
+  not_applicable: "not_applicable",
+  pending: "pending",
+  paid: "paid",
+} as const;

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

@@ -6,7 +6,10 @@
  * OpenAPI spec version: 0.1.0
  */
 
+export * from "./claimRefundRequest";
+export * from "./claimRefundResponse";
 export * from "./costLedger";
+export * from "./costLedgerRefundState";
 export * from "./createJobRequest";
 export * from "./createJobResponse";
 export * from "./demoResponse";