@fantastic.dev/better-stripe 0.12.0 → 0.13.0

package/src/client/costRecovery-invoices.transport.test.ts

@@ -0,0 +1,107 @@
+import Stripe from "stripe";
+import { componentsGeneric } from "convex/server";
+import { expect, it } from "vitest";
+import { BetterStripe } from "./index.js";
+import { getStripeClient } from "./helpers.js";
+import type { Component, RunCtx } from "./helpers.js";
+import type { RecoveryGroup } from "./costRecovery.js";
+it.each(["2026-09-30.endive", "2026-09-30.preview"] as const)(
+  "preserves %s on every SDK page and finds existing items beyond the first page",
+  async (version) => {
+    const key = `sk_test_recovery_transport_${version}`;
+    const sdk = getStripeClient(key, version);
+    const group = {
+      _id: "group-durable",
+      _creationTime: 0,
+      accountId: "acct_owner",
+      scopeKey: "store",
+      currency: "usd",
+      groupKey: "in:1",
+      sourceKind: "invoice",
+      sourceId: "in_1",
+      status: "sealed",
+      amount: 320,
+      pendingOperations: 1,
+      maxDebit: 1000,
+      maxCredit: 1000,
+    } as RecoveryGroup;
+    const paths: string[] = [];
+    (
+      sdk as unknown as { _setApiField(field: string, value: unknown): void }
+    )._setApiField("httpClient", {
+      getClientName: () => "test",
+      makeRequest: async (
+        ...[, , path, method, headers]: Parameters<
+          ReturnType<typeof Stripe.createNodeHttpClient>["makeRequest"]
+        >
+      ) => {
+        expect(headers["Stripe-Version"]).toBe(version);
+        expect(method).toBe("GET");
+        paths.push(path);
+        const data = path.startsWith("/v1/invoices/")
+          ? {
+              id: "in_1",
+              customer_account: group.accountId,
+              currency: "usd",
+              status: "draft",
+            }
+          : path.includes("starting_after=")
+            ? {
+                object: "list",
+                has_more: false,
+                data: [
+                  {
+                    id: "ii_existing",
+                    invoice: "in_1",
+                    customer_account: group.accountId,
+                    currency: "usd",
+                    amount: 320,
+                    discountable: false,
+                    metadata: { bsRecoveryGroup: group._id },
+                  },
+                ],
+              }
+            : {
+                object: "list",
+                has_more: true,
+                data: Array.from({ length: 100 }, (_, i) => ({
+                  id: `ii_${i}`,
+                  metadata: {},
+                })),
+              };
+        return {
+          getStatusCode: () => 200,
+          getHeaders: () => ({}),
+          getRawResponse: () => ({}),
+          toJSON: async () => data,
+          toStream: () => {
+            throw new Error("unexpected stream");
+          },
+        };
+      },
+    });
+    let bound: string | undefined;
+    const ctx = {
+      runQuery: async () => group,
+      runMutation: async (_ref: unknown, args: { invoiceItemId: string }) => {
+        bound = args.invoiceItemId;
+        return { ...group, invoiceItemId: bound };
+      },
+    } as unknown as RunCtx;
+    const better = new BetterStripe(
+      componentsGeneric().betterStripe as unknown as Component,
+      { STRIPE_SECRET_KEY: key, stripeApiVersion: version },
+    );
+    const receipt = await better.costRecovery.attachInvoice(ctx, {
+      accountId: group.accountId,
+      scopeKey: group.scopeKey,
+      currency: group.currency,
+      groupKey: group.groupKey,
+    });
+    expect(receipt.invoiceItemId).toBe("ii_existing");
+    expect(bound).toBe("ii_existing");
+    expect(paths).toHaveLength(3);
+    expect(paths[2]).toContain("starting_after=ii_99");
+    expect(paths[2]).toContain("invoice=in_1");
+  },
+);

package/src/client/costRecovery-invoices.ts

@@ -0,0 +1,144 @@
+import { getProcessingCostContext } from "./settlement/processingCosts.js";
+import type Stripe from "stripe";
+import type { RecoveryGroup, RecoveryScope } from "./costRecovery.js";
+export type RecoveryInvoiceOptions = RecoveryScope & { groupKey: string };
+const marker = "bsRecoveryGroup";
+const id = (value: string | { id: string } | null) =>
+  typeof value === "string" ? value : value?.id;
+
+/** One immutable item per sealed group. Host serializes provider operations per group. */
+export async function attachRecoveryInvoice(
+  stripe: Stripe,
+  group: RecoveryGroup | null,
+  opts: RecoveryInvoiceOptions,
+  bind: (invoiceItemId: string) => Promise<RecoveryGroup>,
+  create = true,
+) {
+  if (
+    !group ||
+    group.groupKey !== opts.groupKey ||
+    group.sourceKind !== "invoice" ||
+    group.accountId !== opts.accountId ||
+    group.scopeKey !== opts.scopeKey ||
+    group.currency !== opts.currency
+  )
+    throw new Error(
+      "Recovery invoice scope does not match the authorized group.",
+    );
+  if (
+    group.status === "open" ||
+    (create && ["released", "releasing"].includes(group.status))
+  )
+    throw new Error("Invoice recovery group must be sealed and active.");
+  const invoice = await stripe.invoices.retrieve(group.sourceId);
+  if (
+    invoice.id !== group.sourceId ||
+    invoice.customer_account !== group.accountId
+  )
+    throw new Error("Recovery invoice ownership does not match.");
+  if (invoice.currency !== group.currency)
+    throw new Error("Recovery invoice currency does not match.");
+  let found: Stripe.InvoiceItem | undefined;
+  for await (const item of stripe.invoiceItems.list({
+    invoice: invoice.id,
+    limit: 100,
+  })) {
+    if (item.metadata?.[marker] !== group._id) continue;
+    if (found)
+      throw new Error(
+        "Duplicate recovery invoice items require reconciliation.",
+      );
+    if (
+      id(item.invoice) !== invoice.id ||
+      item.customer_account !== group.accountId ||
+      item.currency !== group.currency ||
+      item.amount !== group.amount ||
+      item.discountable ||
+      (group.invoiceItemId && group.invoiceItemId !== item.id)
+    )
+      throw new Error(
+        "Recovery invoice item economics or identity do not match.",
+      );
+    found = item;
+  }
+  if (!found) {
+    if (group.invoiceItemId)
+      throw new Error(
+        "Bound recovery invoice item is missing; reconcile before retrying.",
+      );
+    if (!create)
+      throw new Error(
+        "Recovery invoice item is missing; no collection can be confirmed.",
+      );
+    if (group.status !== "sealed")
+      throw new Error(
+        "New recovery items require a sealed, uncompleted group.",
+      );
+    if (invoice.status !== "draft")
+      throw new Error("New recovery items require a draft invoice.");
+    found = await stripe.invoiceItems.create(
+      {
+        invoice: invoice.id,
+        customer_account: group.accountId,
+        currency: group.currency,
+        amount: group.amount,
+        discountable: false,
+        description: "Refund and dispute cost adjustment",
+        metadata: { [marker]: group._id },
+      },
+      { idempotencyKey: `better-stripe:recovery:${group._id}` },
+    );
+  }
+  const bound = group.invoiceItemId === found.id ? group : await bind(found.id);
+  return {
+    group: bound,
+    invoiceItemId: found.id,
+    invoiceStatus: invoice.status,
+  };
+}
+
+/** Refuse ambiguous cash/credit or multi-payment allocations instead of inventing economics. */
+export async function readInvoiceFunding(stripe: Stripe, group: RecoveryGroup) {
+  const invoice = await stripe.invoices.retrieve(group.sourceId);
+  if (
+    invoice.customer_account !== group.accountId ||
+    invoice.currency !== group.currency ||
+    invoice.status !== "paid"
+  )
+    throw new Error(
+      "Invoice funding ownership, currency or paid state does not match.",
+    );
+  const payments: Stripe.InvoicePayment[] = [];
+  for await (const payment of stripe.invoicePayments.list({
+    invoice: group.sourceId,
+    limit: 100,
+  })) {
+    if (
+      id(payment.invoice) !== group.sourceId ||
+      payment.currency !== group.currency
+    )
+      throw new Error("Invoice payment identity or currency does not match.");
+    if (payment.status === "paid") payments.push(payment);
+  }
+  const payment = payments[0];
+  if (
+    payments.length !== 1 ||
+    payment?.payment.type !== "payment_intent" ||
+    !payment.payment.payment_intent ||
+    payment.amount_paid !== invoice.amount_paid
+  )
+    return {
+      status: "not_ready" as const,
+      reason: "invoice_funding_allocation_required" as const,
+    };
+  const cost = await getProcessingCostContext(stripe, {
+    paymentIntentId: id(payment.payment.payment_intent)!,
+  });
+  if (cost.status === "not_ready") return cost;
+  if (cost.currency !== group.currency || cost.gross !== invoice.amount_paid)
+    return {
+      status: "not_ready" as const,
+      reason: "invoice_funding_allocation_required" as const,
+    };
+  return cost;
+}

package/src/client/costRecovery.ts

@@ -1,3 +1,8 @@
+import type Stripe from "stripe";
+import {
+  readInvoiceFunding,
+  attachRecoveryInvoice,
+} from "./costRecovery-invoices.js";
 import type { Component, RunCtx } from "./helpers.js";
 import { runMutationOrThrow } from "./helpers.js";
 import { componentRef } from "./webhooks/helpers.js";
@@ -52,6 +57,12 @@ export type RecoveryGroup = RecoveryGroupOptions & {
   _creationTime: number;
   amount: number;
   pendingOperations: number;
+  invoiceItemId?: string;
+  invoiceFunding?: {
+    sourceChargeId: string;
+    sourceGross: number;
+    sourceProcessingFee: number;
+  };
   status:
     "open" | "sealed" | "collecting" | "releasing" | "collected" | "released";
 };
@@ -65,9 +76,12 @@ export type RecoveryReservation = {
   allocations: { claimId: string; claimKey: string; amount: number }[];
   status: "reserved" | "collected" | "released" | "empty";
 };
-/** Durable bookkeeping only. Host authorizes policy and verifies provider outcomes. */
+/** Host authorizes policy and scope. Provider methods verify invoice outcomes. */
 export class CostRecoveryClient {
-  constructor(private readonly component: Component) {}
+  constructor(
+    private readonly component: Component,
+    private readonly provider?: () => Stripe,
+  ) {}
   private async mutate<T>(
     ctx: RunCtx,
     path: string,
@@ -89,6 +103,97 @@ export class CostRecoveryClient {
       args,
     )) as T;
   }
+  /** Host authorizes the account, scope and invoice group; call from an action. */
+  async attachInvoice(ctx: RunCtx, opts: RecoveryScope & { groupKey: string }) {
+    if (!this.provider)
+      throw new Error("Invoice recovery requires a Stripe client.");
+    const group = await this.getGroup(ctx, { groupKey: opts.groupKey });
+    return attachRecoveryInvoice(
+      this.provider(),
+      group,
+      opts,
+      (invoiceItemId) =>
+        this.mutate<RecoveryGroup>(ctx, "mutations/bindInvoiceItem", {
+          groupKey: opts.groupKey,
+          invoiceItemId,
+        }),
+    );
+  }
+  /** Re-read Stripe; keep unpaid items reserved. Repeat until isDone after terminal outcomes. */
+  async reconcileInvoice(
+    ctx: RunCtx,
+    opts: RecoveryScope & { groupKey: string; releaseUncollectible?: boolean },
+  ) {
+    if (!this.provider)
+      throw new Error("Invoice recovery requires a Stripe client.");
+    const group = await this.getGroup(ctx, { groupKey: opts.groupKey });
+    const receipt = await attachRecoveryInvoice(
+      this.provider(),
+      group,
+      opts,
+      (invoiceItemId) =>
+        this.mutate<RecoveryGroup>(ctx, "mutations/bindInvoiceItem", {
+          groupKey: opts.groupKey,
+          invoiceItemId,
+        }),
+      false,
+    );
+    const outcome =
+      receipt.invoiceStatus === "paid"
+        ? "collect"
+        : receipt.invoiceStatus === "void" ||
+            (receipt.invoiceStatus === "uncollectible" &&
+              opts.releaseUncollectible === true)
+          ? "release"
+          : null;
+    if (!outcome) return { ...receipt, isDone: false };
+    return {
+      ...receipt,
+      ...(await this.finish(ctx, { groupKey: opts.groupKey, outcome })),
+    };
+  }
+  /** Reconcile a returned funding charge without changing the original cost claims. */
+  async rollbackInvoice(
+    ctx: RunCtx,
+    opts: RecoveryScope & { groupKey: string; revision: number },
+  ) {
+    if (!this.provider)
+      throw new Error("Invoice recovery requires a Stripe client.");
+    const stripe = this.provider();
+    const group = await this.getGroup(ctx, { groupKey: opts.groupKey });
+    const receipt = await attachRecoveryInvoice(
+      stripe,
+      group,
+      opts,
+      (invoiceItemId) =>
+        this.mutate<RecoveryGroup>(ctx, "mutations/bindInvoiceItem", {
+          groupKey: opts.groupKey,
+          invoiceItemId,
+        }),
+      false,
+    );
+    if (
+      receipt.group.status !== "collected" ||
+      receipt.invoiceStatus !== "paid"
+    )
+      throw new Error("Invoice rollback requires verified collection.");
+    const cost = await readInvoiceFunding(stripe, receipt.group);
+    if (cost.status === "not_ready") return cost;
+    await this.mutate<RecoveryGroup>(ctx, "mutations/bindInvoiceFunding", {
+      groupKey: opts.groupKey,
+      sourceChargeId: cost.chargeId,
+      sourceGross: cost.gross,
+      sourceProcessingFee: cost.processingFee,
+    });
+    return {
+      status: "ready" as const,
+      claim: await this.rollback(ctx, {
+        groupKey: opts.groupKey,
+        returnedPrincipal: cost.principalReturned,
+        revision: opts.revision,
+      }),
+    };
+  }
   recordClaim(ctx: RunCtx, opts: RecoveryObservation) {
     return this.mutate<RecoveryClaim>(ctx, "mutations/record", opts);
   }

package/src/client/index.ts

@@ -1265,7 +1265,7 @@ export class BetterStripe {
     return providerReads.getCouponFromStripe(this.stripe(), opts);
   }
   get costRecovery() {
-    return new CostRecoveryClient(this.component);
+    return new CostRecoveryClient(this.component, () => this.stripe());
   }
 
   async getProcessingCostContext(

package/src/component/_generated/component.ts

@@ -1594,6 +1594,81 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
     };
     costRecovery: {
       mutations: {
+        bindInvoiceFunding: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            groupKey: string;
+            sourceChargeId: string;
+            sourceGross: number;
+            sourceProcessingFee: number;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            amount: number;
+            currency: string;
+            groupKey: string;
+            invoiceFunding?: {
+              sourceChargeId: string;
+              sourceGross: number;
+              sourceProcessingFee: number;
+            };
+            invoiceItemId?: string;
+            maxCredit: number;
+            maxDebit: number;
+            pendingOperations: number;
+            scopeKey: string;
+            sourceGross?: number;
+            sourceId: string;
+            sourceKind: "settlement" | "invoice";
+            sourceProcessingFee?: number;
+            status:
+              | "open"
+              | "sealed"
+              | "collecting"
+              | "releasing"
+              | "collected"
+              | "released";
+          },
+          Name
+        >;
+        bindInvoiceItem: FunctionReference<
+          "mutation",
+          "internal",
+          { groupKey: string; invoiceItemId: string },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            amount: number;
+            currency: string;
+            groupKey: string;
+            invoiceFunding?: {
+              sourceChargeId: string;
+              sourceGross: number;
+              sourceProcessingFee: number;
+            };
+            invoiceItemId?: string;
+            maxCredit: number;
+            maxDebit: number;
+            pendingOperations: number;
+            scopeKey: string;
+            sourceGross?: number;
+            sourceId: string;
+            sourceKind: "settlement" | "invoice";
+            sourceProcessingFee?: number;
+            status:
+              | "open"
+              | "sealed"
+              | "collecting"
+              | "releasing"
+              | "collected"
+              | "released";
+          },
+          Name
+        >;
         finish: FunctionReference<
           "mutation",
           "internal",
@@ -1606,6 +1681,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               amount: number;
               currency: string;
               groupKey: string;
+              invoiceFunding?: {
+                sourceChargeId: string;
+                sourceGross: number;
+                sourceProcessingFee: number;
+              };
+              invoiceItemId?: string;
               maxCredit: number;
               maxDebit: number;
               pendingOperations: number;
@@ -1684,6 +1765,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               amount: number;
               currency: string;
               groupKey: string;
+              invoiceFunding?: {
+                sourceChargeId: string;
+                sourceGross: number;
+                sourceProcessingFee: number;
+              };
+              invoiceItemId?: string;
               maxCredit: number;
               maxDebit: number;
               pendingOperations: number;
@@ -1751,6 +1838,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             currency: string;
             groupKey: string;
+            invoiceFunding?: {
+              sourceChargeId: string;
+              sourceGross: number;
+              sourceProcessingFee: number;
+            };
+            invoiceItemId?: string;
             maxCredit: number;
             maxDebit: number;
             pendingOperations: number;
@@ -1821,6 +1914,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             currency: string;
             groupKey: string;
+            invoiceFunding?: {
+              sourceChargeId: string;
+              sourceGross: number;
+              sourceProcessingFee: number;
+            };
+            invoiceItemId?: string;
             maxCredit: number;
             maxDebit: number;
             pendingOperations: number;

package/src/component/costRecovery/claims.ts

@@ -83,16 +83,28 @@ export async function rollbackClaim(
   const group = await getGroup(ctx, args.groupKey);
   if (
     group.status !== "collected" ||
-    group.sourceKind !== "settlement" ||
-    !group.sourceGross
+    (group.sourceKind === "settlement"
+      ? !group.sourceGross
+      : !group.invoiceFunding)
   )
     throw new Error(
-      "Rollback requires a collected settlement group with original funding economics.",
+      "Rollback requires a collected group with original funding economics.",
     );
-  if (args.returnedPrincipal < 0 || args.returnedPrincipal > group.sourceGross)
+  const funding =
+    group.sourceKind === "settlement"
+      ? {
+          sourceChargeId: group.sourceId,
+          sourceGross: group.sourceGross!,
+          sourceProcessingFee: group.sourceProcessingFee!,
+        }
+      : group.invoiceFunding!;
+  if (
+    args.returnedPrincipal < 0 ||
+    args.returnedPrincipal > funding.sourceGross
+  )
     throw new Error("Returned principal exceeds the original funding sale.");
   const abs = BigInt(Math.abs(group.amount)),
-    gross = BigInt(group.sourceGross),
+    gross = BigInt(funding.sourceGross),
     principal = BigInt(args.returnedPrincipal);
   const rounded = Number((abs * principal + gross / 2n) / gross);
   return recordClaim(ctx, {
@@ -100,9 +112,7 @@ export async function rollbackClaim(
     scopeKey: group.scopeKey,
     currency: group.currency,
     claimKey: `rollback:${group.groupKey}`,
-    sourceChargeId: group.sourceId,
-    sourceGross: group.sourceGross,
-    sourceProcessingFee: group.sourceProcessingFee!,
+    ...funding,
     amountDue: group.amount < 0 ? -rounded : rounded,
     revision: args.revision,
   });

package/src/component/costRecovery/mutations.ts

@@ -1,3 +1,4 @@
+import { getGroup, integer } from "./helpers.js";
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
 import { recordClaim, rollbackClaim } from "./claims.js";
@@ -41,3 +42,74 @@ export const finish = mutation({
   returns: v.object({ group: groupDoc, isDone: v.boolean() }),
   handler: finishGroup,
 });
+
+export const bindInvoiceItem = mutation({
+  args: { groupKey: v.string(), invoiceItemId: v.string() },
+  returns: groupDoc,
+  handler: async (ctx, args) => {
+    const group = await ctx.db
+      .query("recoveryGroups")
+      .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
+      .unique();
+    if (
+      !group ||
+      group.sourceKind !== "invoice" ||
+      group.status === "open" ||
+      group.status === "released" ||
+      group.status === "releasing"
+    )
+      throw new Error("Invoice recovery group must be sealed and active.");
+    if (
+      !args.invoiceItemId ||
+      (group.invoiceItemId && group.invoiceItemId !== args.invoiceItemId)
+    )
+      throw new Error("Recovery invoice item identity cannot change.");
+    await ctx.db.patch("recoveryGroups", group._id, {
+      invoiceItemId: args.invoiceItemId,
+    });
+    return (await ctx.db.get("recoveryGroups", group._id))!;
+  },
+});
+
+export const bindInvoiceFunding = mutation({
+  args: {
+    groupKey: v.string(),
+    sourceChargeId: v.string(),
+    sourceGross: v.number(),
+    sourceProcessingFee: v.number(),
+  },
+  returns: groupDoc,
+  handler: async (ctx, args) => {
+    const group = await getGroup(ctx, args.groupKey);
+    if (group.sourceKind !== "invoice" || group.status !== "collected")
+      throw new Error(
+        "Invoice funding requires a collected invoice recovery group.",
+      );
+    integer(args.sourceGross);
+    integer(args.sourceProcessingFee);
+    if (
+      !args.sourceChargeId ||
+      args.sourceGross <= 0 ||
+      args.sourceProcessingFee < 0
+    )
+      throw new Error("Invalid invoice funding economics.");
+    const funding = {
+      sourceChargeId: args.sourceChargeId,
+      sourceGross: args.sourceGross,
+      sourceProcessingFee: args.sourceProcessingFee,
+    };
+    if (
+      group.invoiceFunding &&
+      Object.keys(funding).some(
+        (key) =>
+          group.invoiceFunding![key as keyof typeof funding] !==
+          funding[key as keyof typeof funding],
+      )
+    )
+      throw new Error("Original invoice funding economics cannot change.");
+    await ctx.db.patch("recoveryGroups", group._id, {
+      invoiceFunding: funding,
+    });
+    return (await ctx.db.get("recoveryGroups", group._id))!;
+  },
+});

package/src/component/costRecovery/schema.ts

@@ -56,6 +56,14 @@ export const groupFields = {
   ...groupInput,
   amount: v.number(),
   pendingOperations: v.number(),
+  invoiceItemId: v.optional(v.string()),
+  invoiceFunding: v.optional(
+    v.object({
+      sourceChargeId: v.string(),
+      sourceGross: v.number(),
+      sourceProcessingFee: v.number(),
+    }),
+  ),
   status: v.union(
     v.literal("open"),
     v.literal("sealed"),