@fantastic.dev/better-stripe 0.12.0 → 0.14.0

package/src/client/costRecovery-invoices.ts

@@ -0,0 +1,176 @@
+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;
+
+type InvoiceReceipt = {
+  group: RecoveryGroup;
+  invoiceItemId: string;
+  invoiceStatus: Stripe.Invoice["status"];
+};
+type BindInvoiceItem = (invoiceItemId: string) => Promise<RecoveryGroup>;
+
+/** Attachment always produces an item; reconciliation can release an unbound void invoice. */
+export function attachRecoveryInvoice(
+  stripe: Stripe,
+  group: RecoveryGroup | null,
+  opts: RecoveryInvoiceOptions,
+  bind: BindInvoiceItem,
+  create?: true,
+): Promise<InvoiceReceipt>;
+export function attachRecoveryInvoice(
+  stripe: Stripe,
+  group: RecoveryGroup | null,
+  opts: RecoveryInvoiceOptions,
+  bind: BindInvoiceItem,
+  create: false,
+): Promise<
+  | InvoiceReceipt
+  | (Omit<InvoiceReceipt, "invoiceItemId"> & { invoiceItemId: null })
+>;
+
+/** 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 &&
+      invoice.status === "void" &&
+      ["sealed", "releasing", "released"].includes(group.status)
+    )
+      return { group, invoiceItemId: null, invoiceStatus: invoice.status };
+    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";
@@ -21,6 +26,12 @@ export type RecoveryClaim = RecoveryObservation & {
   reservedAmount: number;
   outstanding: number;
   sign: "positive" | "negative" | "zero";
+  openingCollection?: {
+    operationKey: string;
+    amountDue: number;
+    revision: number;
+    collectedAmount: number;
+  };
 };
 export type RecoveryBalance = RecoveryScope & {
   amountDue: number;
@@ -52,6 +63,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 +82,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 +109,107 @@ 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,
+      }),
+    };
+  }
+  /** Import a host-verified opening collection. Never overwrites a live claim. */
+  importClaim(
+    ctx: RunCtx,
+    opts: RecoveryObservation & {
+      operationKey: string;
+      collectedAmount: number;
+    },
+  ) {
+    return this.mutate<RecoveryClaim>(ctx, "mutations/importClaim", opts);
+  }
   recordClaim(ctx: RunCtx, opts: RecoveryObservation) {
     return this.mutate<RecoveryClaim>(ctx, "mutations/record", opts);
   }

package/src/client/errors.ts

@@ -9,6 +9,7 @@ export type BetterStripeErrorCode =
   | "SUBSCRIPTION_UPDATE_FAILED"
   | "REFUND_CREATE_FAILED"
   | "REFUND_UNAUTHORIZED"
+  | "DISPUTE_UPLOAD_FAILED"
   | "DISPUTE_UPDATE_FAILED"
   | "DISPUTE_UNAUTHORIZED"
   | "CHECKOUT_CREATE_FAILED"

package/src/client/index.ts

@@ -94,6 +94,8 @@ export { computeFee, computeSplit } from "./core/fees.js";
 export type { FeeBreakdown, SplitResult, SplitTransfer } from "./core/fees.js";
 export { groupSubscriptionsByStore } from "./billing/subscriptions.js";
 export {
+  type DisputeEvidenceUploadOptions,
+  type DisputeEvidenceFileField,
   buildDisputeEvidence,
   disputeEvidenceCountdown,
 } from "./connect/disputes.js";
@@ -1265,7 +1267,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(
@@ -1403,13 +1405,6 @@ export class BetterStripe {
     return disputesImpl.listDisputes(this.component, ctx, opts);
   }
 
-  /**
-   * Submit or stage dispute evidence. Stripe's `submit` defaults to TRUE, so
-   * this method stages by default: EVERY call sends an explicit
-   * `submit: false` — evidence-bearing or metadata-only — unless you pass
-   * `submit: true` to submit to the bank (one-shot, outcome-affecting;
-   * BTS-61, BTS-72). See {@link disputesImpl.updateDispute}.
-   */
   async updateDispute(
     ctx: RunCtx,
     opts: {
@@ -1418,23 +1413,29 @@ export class BetterStripe {
       metadata?: Record<string, string>;
       submit?: boolean;
       stripeAccountId?: string;
-      /**
-       * Who is acting on the dispute (BTS-107). A platform admin may act on any
-       * dispute; a seller may act only on a dispute for a sale routed to their
-       * own account. Omit for platform-initiated (unrestricted) actions.
-       */
       actor?: RefundActor;
     },
   ): Promise<{ success: true }> {
     return disputesImpl.updateDispute(this.stripe(), this.component, ctx, opts);
   }
 
+  async uploadDisputeEvidence(
+    ctx: RunCtx,
+    opts: disputesImpl.DisputeEvidenceUploadOptions,
+  ) {
+    return disputesImpl.uploadDisputeEvidence(
+      this.stripe(),
+      this.component,
+      ctx,
+      opts,
+    );
+  }
+
   async closeDispute(
     ctx: RunCtx,
     opts: {
       stripeDisputeId: string;
       stripeAccountId?: string;
-      /** See {@link updateDispute}'s `actor` (BTS-107). Omit for unrestricted. */
       actor?: RefundActor;
     },
   ): Promise<{ success: true }> {

package/src/component/_generated/api.ts

@@ -20,6 +20,7 @@ import type * as core_validators from "../core/validators.js";
 import type * as costRecovery_claims from "../costRecovery/claims.js";
 import type * as costRecovery_completion from "../costRecovery/completion.js";
 import type * as costRecovery_helpers from "../costRecovery/helpers.js";
+import type * as costRecovery_imports from "../costRecovery/imports.js";
 import type * as costRecovery_mutations from "../costRecovery/mutations.js";
 import type * as costRecovery_queries from "../costRecovery/queries.js";
 import type * as costRecovery_reservations from "../costRecovery/reservations.js";
@@ -57,6 +58,7 @@ const fullApi: ApiFromModules<{
   "costRecovery/claims": typeof costRecovery_claims;
   "costRecovery/completion": typeof costRecovery_completion;
   "costRecovery/helpers": typeof costRecovery_helpers;
+  "costRecovery/imports": typeof costRecovery_imports;
   "costRecovery/mutations": typeof costRecovery_mutations;
   "costRecovery/queries": typeof costRecovery_queries;
   "costRecovery/reservations": typeof costRecovery_reservations;

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;
@@ -1626,6 +1707,47 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        importClaim: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            amountDue: number;
+            claimKey: string;
+            collectedAmount: number;
+            currency: string;
+            operationKey: string;
+            revision: number;
+            scopeKey: string;
+            sourceChargeId: string;
+            sourceGross: number;
+            sourceProcessingFee: number;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            amountDue: number;
+            claimKey: string;
+            collectedAmount: number;
+            currency: string;
+            openingCollection?: {
+              amountDue: number;
+              collectedAmount: number;
+              operationKey: string;
+              revision: number;
+            };
+            outstanding: number;
+            reservedAmount: number;
+            revision: number;
+            scopeKey: string;
+            sign: "positive" | "negative" | "zero";
+            sourceChargeId: string;
+            sourceGross: number;
+            sourceProcessingFee: number;
+          },
+          Name
+        >;
         record: FunctionReference<
           "mutation",
           "internal",
@@ -1648,6 +1770,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             claimKey: string;
             collectedAmount: number;
             currency: string;
+            openingCollection?: {
+              amountDue: number;
+              collectedAmount: number;
+              operationKey: string;
+              revision: number;
+            };
             outstanding: number;
             reservedAmount: number;
             revision: number;
@@ -1684,6 +1812,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;
@@ -1729,6 +1863,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             claimKey: string;
             collectedAmount: number;
             currency: string;
+            openingCollection?: {
+              amountDue: number;
+              collectedAmount: number;
+              operationKey: string;
+              revision: number;
+            };
             outstanding: number;
             reservedAmount: number;
             revision: number;
@@ -1751,6 +1891,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;
@@ -1799,6 +1945,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             claimKey: string;
             collectedAmount: number;
             currency: string;
+            openingCollection?: {
+              amountDue: number;
+              collectedAmount: number;
+              operationKey: string;
+              revision: number;
+            };
             outstanding: number;
             reservedAmount: number;
             revision: number;
@@ -1821,6 +1973,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;
@@ -1866,6 +2024,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               claimKey: string;
               collectedAmount: number;
               currency: string;
+              openingCollection?: {
+                amountDue: number;
+                collectedAmount: number;
+                operationKey: string;
+                revision: number;
+              };
               outstanding: number;
               reservedAmount: number;
               revision: 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,
   });