@fantastic.dev/better-stripe 0.11.0 → 0.13.0

package/src/client/costRecovery.test.ts

@@ -0,0 +1,76 @@
+import { componentsGeneric, type FunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "../component/schema.js";
+import { initConvexTest } from "./setup.test.js";
+import { BetterStripe } from "./index.js";
+import type { Component, RunCtx } from "./helpers.js";
+const modules = import.meta.glob("../component/**/*.{ts,js,tsx,jsx}");
+it("uses the real component through the public recovery client without any provider key", async () => {
+  const t = initConvexTest();
+  t.registerComponent("betterStripe", schema, modules);
+  const stripe = new BetterStripe(
+    componentsGeneric().betterStripe as unknown as Component,
+    {},
+  );
+  const ctx = {
+    runQuery: (
+      ref: FunctionReference<"query">,
+      args: Record<string, unknown>,
+    ) => t.query(ref, args),
+    runMutation: (
+      ref: FunctionReference<"mutation">,
+      args: Record<string, unknown>,
+    ) => t.mutation(ref, args),
+  } as unknown as RunCtx;
+  const recovery = stripe.costRecovery;
+  const scope = { accountId: "acct_owner", scopeKey: "store", currency: "usd" };
+  await recovery.recordClaim(ctx, {
+    ...scope,
+    claimKey: "fee:ch_original",
+    sourceChargeId: "ch_original",
+    sourceGross: 10000,
+    sourceProcessingFee: 320,
+    amountDue: 320,
+    revision: 1,
+  });
+  expect(
+    await recovery.getClaim(ctx, { claimKey: "fee:ch_original" }),
+  ).toMatchObject({ revision: 1, amountDue: 320 });
+  const result = await recovery.reserve(ctx, {
+    ...scope,
+    groupKey: "invoice:in_1",
+    operationKey: "invoice:in_1:batch-1",
+    sourceKind: "invoice",
+    sourceId: "in_1",
+    maxDebit: 10000,
+    maxCredit: 10000,
+  });
+  expect(result.reservation.amount).toBe(320);
+  expect(
+    (await recovery.listClaims(ctx, { ...scope, limit: 10 })).page,
+  ).toHaveLength(1);
+  await recovery.seal(ctx, { groupKey: "invoice:in_1" });
+  expect(
+    (await recovery.getGroup(ctx, { groupKey: "invoice:in_1" }))?.status,
+  ).toBe("sealed");
+  expect(
+    (
+      await recovery.getReservation(ctx, {
+        operationKey: "invoice:in_1:batch-1",
+      })
+    )?.amount,
+  ).toBe(320);
+  expect(
+    (
+      await recovery.finish(ctx, {
+        groupKey: "invoice:in_1",
+        outcome: "collect",
+      })
+    ).isDone,
+  ).toBe(true);
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    collectedAmount: 320,
+    outstanding: 0,
+    reservedAmount: 0,
+  });
+});

package/src/client/costRecovery.ts

@@ -0,0 +1,254 @@
+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";
+export type RecoveryScope = {
+  accountId: string;
+  scopeKey: string;
+  currency: string;
+};
+export type RecoveryObservation = RecoveryScope & {
+  claimKey: string;
+  sourceChargeId: string;
+  sourceGross: number;
+  sourceProcessingFee: number;
+  amountDue: number;
+  revision: number;
+};
+export type RecoveryClaim = RecoveryObservation & {
+  _id: string;
+  _creationTime: number;
+  collectedAmount: number;
+  reservedAmount: number;
+  outstanding: number;
+  sign: "positive" | "negative" | "zero";
+};
+export type RecoveryBalance = RecoveryScope & {
+  amountDue: number;
+  collectedAmount: number;
+  reservedAmount: number;
+  outstanding: number;
+  activeGroupKey?: string;
+};
+export type RecoveryGroupOptions = RecoveryScope & {
+  groupKey: string;
+  maxDebit: number;
+  maxCredit: number;
+} & (
+    | {
+        sourceKind: "settlement";
+        sourceId: string;
+        sourceGross: number;
+        sourceProcessingFee: number;
+      }
+    | {
+        sourceKind: "invoice";
+        sourceId: string;
+        sourceGross?: number;
+        sourceProcessingFee?: number;
+      }
+  );
+export type RecoveryGroup = RecoveryGroupOptions & {
+  _id: string;
+  _creationTime: number;
+  amount: number;
+  pendingOperations: number;
+  invoiceItemId?: string;
+  invoiceFunding?: {
+    sourceChargeId: string;
+    sourceGross: number;
+    sourceProcessingFee: number;
+  };
+  status:
+    "open" | "sealed" | "collecting" | "releasing" | "collected" | "released";
+};
+export type RecoveryReservation = {
+  _id: string;
+  _creationTime: number;
+  operationKey: string;
+  groupKey: string;
+  amount: number;
+  limit: number;
+  allocations: { claimId: string; claimKey: string; amount: number }[];
+  status: "reserved" | "collected" | "released" | "empty";
+};
+/** Host authorizes policy and scope. Provider methods verify invoice outcomes. */
+export class CostRecoveryClient {
+  constructor(
+    private readonly component: Component,
+    private readonly provider?: () => Stripe,
+  ) {}
+  private async mutate<T>(
+    ctx: RunCtx,
+    path: string,
+    args: Record<string, unknown>,
+  ): Promise<T> {
+    return (await runMutationOrThrow(
+      ctx,
+      componentRef(this.component, `costRecovery/${path}`),
+      args,
+    )) as T;
+  }
+  private async query<T>(
+    ctx: RunCtx,
+    path: string,
+    args: Record<string, unknown>,
+  ): Promise<T> {
+    return (await ctx.runQuery(
+      componentRef(this.component, `costRecovery/queries/${path}`),
+      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);
+  }
+  reserve(
+    ctx: RunCtx,
+    opts: RecoveryGroupOptions & { operationKey: string; limit?: number },
+  ) {
+    return this.mutate<{
+      reservation: RecoveryReservation;
+      group: RecoveryGroup;
+    }>(ctx, "mutations/reserve", opts);
+  }
+  seal(ctx: RunCtx, opts: { groupKey: string }) {
+    return this.mutate<RecoveryGroup>(ctx, "mutations/seal", opts);
+  }
+  finish(
+    ctx: RunCtx,
+    opts: { groupKey: string; outcome: "collect" | "release"; limit?: number },
+  ) {
+    return this.mutate<{ group: RecoveryGroup; isDone: boolean }>(
+      ctx,
+      "mutations/finish",
+      opts,
+    );
+  }
+  rollback(
+    ctx: RunCtx,
+    opts: { groupKey: string; returnedPrincipal: number; revision: number },
+  ) {
+    return this.mutate<RecoveryClaim>(ctx, "mutations/rollback", opts);
+  }
+  balance(ctx: RunCtx, opts: RecoveryScope) {
+    return this.query<RecoveryBalance>(ctx, "balance", opts);
+  }
+  listClaims(
+    ctx: RunCtx,
+    opts: RecoveryScope & { limit?: number; cursor?: string | null },
+  ) {
+    const { limit, cursor, ...scope } = opts;
+    return this.query<{
+      page: RecoveryClaim[];
+      continueCursor: string;
+      isDone: boolean;
+    }>(ctx, "listClaims", {
+      ...scope,
+      paginationOpts: { numItems: limit ?? 25, cursor: cursor ?? null },
+    });
+  }
+  getClaim(ctx: RunCtx, opts: { claimKey: string }) {
+    return this.query<RecoveryClaim | null>(ctx, "claim", opts);
+  }
+  getGroup(ctx: RunCtx, opts: { groupKey: string }) {
+    return this.query<RecoveryGroup | null>(ctx, "group", opts);
+  }
+  getReservation(ctx: RunCtx, opts: { operationKey: string }) {
+    return this.query<RecoveryReservation | null>(ctx, "reservation", opts);
+  }
+}

package/src/client/index.ts

@@ -1,3 +1,27 @@
+import { CostRecoveryClient } from "./costRecovery.js";
+export * from "./charge-currency.js";
+export * from "./costRecovery.js";
+import type { SubscriptionStatus } from "../component/billing/validators.js";
+import * as processingCostsImpl from "./settlement/processingCosts.js";
+export type {
+  ProcessingCostContext,
+  ProcessingCostOptions,
+  ProcessingCostTransaction,
+  ProcessingCostRecord,
+  ProcessingCostNotReadyReason,
+} from "./settlement/processingCosts.js";
+import * as balanceFundingImpl from "./billing/balanceFunding.js";
+export type {
+  BalanceFundingCapability,
+  BalanceFundingPreparation,
+  PrepareBalanceFundingOptions,
+  SetBalanceFundingOptions,
+} from "./billing/balanceFunding.js";
+import * as invoicePreviewImpl from "./billing/invoicePreview.js";
+export type {
+  UpcomingInvoicePreview,
+  UpcomingInvoicePreviewOptions,
+} from "./billing/invoicePreview.js";
 import type { HttpRouter } from "convex/server";
 import { registerClientRoutes } from "./previewRoutes.js";
 import {
@@ -47,10 +71,6 @@ import { v } from "convex/values";
 import Stripe from "stripe";
 
 import type { ComponentApi } from "../component/_generated/component.js";
-import type {
-  InvoiceStatus,
-  SubscriptionStatus,
-} from "../component/billing/validators.js";
 import type {
   DisputeStatus,
   PayoutStatus,
@@ -495,17 +515,7 @@ export class BetterStripe {
 
   // PRODUCT METHODS
 
-  async createProduct(
-    ctx: RunCtx,
-    opts: {
-      name: string;
-      description?: string;
-      active?: boolean;
-      accountId?: string;
-      metadata?: Record<string, string>;
-      idempotencyKey?: string;
-    },
-  ) {
+  async createProduct(ctx: RunCtx, opts: productsImpl.CreateProductOptions) {
     return productsImpl.createProduct(this.stripe(), this.component, ctx, {
       ...opts,
       // Stamp the per-store descriptor at create so it covers the first invoice
@@ -583,20 +593,7 @@ export class BetterStripe {
 
   // PRICE METHODS
 
-  async createPrice(
-    ctx: RunCtx,
-    opts: {
-      stripeProductId: string;
-      unitAmount: number;
-      currency?: string;
-      type: "one_time" | "recurring";
-      interval?: "day" | "week" | "month" | "year";
-      intervalCount?: number;
-      nickname?: string;
-      metadata?: Record<string, string>;
-      idempotencyKey?: string;
-    },
-  ) {
+  async createPrice(ctx: RunCtx, opts: pricesImpl.CreatePriceOptions) {
     return pricesImpl.createPrice(this.stripe(), this.component, ctx, opts);
   }
 
@@ -646,19 +643,7 @@ export class BetterStripe {
 
   async upsertPrice(
     ctx: RunCtx,
-    opts: {
-      stripePriceId: string;
-      productId: string;
-      stripeProductId: string;
-      nickname?: string;
-      unitAmount: number;
-      currency: string;
-      active: boolean;
-      type: "one_time" | "recurring";
-      interval?: "day" | "week" | "month" | "year";
-      intervalCount?: number;
-      metadata?: Record<string, unknown>;
-    },
+    opts: Parameters<typeof pricesImpl.upsertPrice>[2],
   ) {
     return pricesImpl.upsertPrice(this.component, ctx, opts);
   }
@@ -956,23 +941,7 @@ export class BetterStripe {
 
   async upsertSubscription(
     ctx: RunCtx,
-    opts: {
-      stripeSubscriptionId: string;
-      accountId?: string;
-      userId: string;
-      orgId?: string;
-      status: SubscriptionStatus;
-      priceId?: string;
-      quantity?: number;
-      currentPeriodStart?: string;
-      currentPeriodEnd?: string;
-      cancelAtPeriodEnd: boolean;
-      canceledAt?: string;
-      isTrialing: boolean;
-      trialStart?: string;
-      trialEnd?: string;
-      metadata?: Record<string, unknown>;
-    },
+    opts: Parameters<typeof subscriptionsImpl.upsertSubscription>[2],
   ) {
     return subscriptionsImpl.upsertSubscription(this.component, ctx, opts);
   }
@@ -1016,22 +985,7 @@ export class BetterStripe {
 
   async upsertInvoice(
     ctx: RunCtx,
-    opts: {
-      stripeInvoiceId: string;
-      userId: string;
-      orgId?: string;
-      accountId?: string;
-      subscriptionId?: string;
-      status: InvoiceStatus;
-      currency: string;
-      amountDue: number;
-      amountPaid: number;
-      hostedInvoiceUrl?: string;
-      invoicePdf?: string;
-      periodStart?: string;
-      periodEnd?: string;
-      metadata?: Record<string, unknown>;
-    },
+    opts: Parameters<typeof invoicesImpl.upsertInvoice>[2],
   ) {
     return invoicesImpl.upsertInvoice(this.component, ctx, opts);
   }
@@ -1044,6 +998,42 @@ export class BetterStripe {
     return configImpl.getStripeMode(this.component, ctx);
   }
 
+  getBalanceFundingCapability() {
+    return balanceFundingImpl.getBalanceFundingCapability(
+      this.stripeApiVersion,
+    );
+  }
+
+  async prepareBalanceFunding(
+    _ctx: RunCtx,
+    opts: balanceFundingImpl.PrepareBalanceFundingOptions,
+  ) {
+    return balanceFundingImpl.prepareBalanceFunding(
+      this.stripe(),
+      this.stripeApiVersion,
+      opts,
+    );
+  }
+
+  async setBalanceFunding(
+    _ctx: RunCtx,
+    opts: balanceFundingImpl.SetBalanceFundingOptions,
+  ) {
+    return balanceFundingImpl.setBalanceFunding(
+      this.stripe(),
+      this.stripeApiVersion,
+      opts,
+    );
+  }
+
+  /** Authorize the customer in the host; validates subscription ownership. */
+  async getUpcomingInvoicePreview(
+    _ctx: RunCtx,
+    opts: invoicePreviewImpl.UpcomingInvoicePreviewOptions,
+  ) {
+    return invoicePreviewImpl.getUpcomingInvoicePreview(this.stripe(), opts);
+  }
+
   async getInvoiceFromStripe(ctx: RunCtx, opts: { stripeInvoiceId: string }) {
     return invoicesImpl.getInvoiceFromStripe(this.stripe(), ctx, opts);
   }
@@ -1274,6 +1264,17 @@ export class BetterStripe {
   ) {
     return providerReads.getCouponFromStripe(this.stripe(), opts);
   }
+  get costRecovery() {
+    return new CostRecoveryClient(this.component, () => this.stripe());
+  }
+
+  async getProcessingCostContext(
+    _ctx: RunCtx,
+    opts: processingCostsImpl.ProcessingCostOptions,
+  ) {
+    return processingCostsImpl.getProcessingCostContext(this.stripe(), opts);
+  }
+
   async getVerifiedSale(
     _ctx: RunCtx,
     opts: saleContextImpl.VerifiedSaleOptions,

package/src/client/products/prices.ts

@@ -11,21 +11,23 @@ import { componentRef } from "../webhooks/helpers.js";
 // Price methods
 // =============================================================================
 
+export type CreatePriceOptions = {
+  stripeProductId: string;
+  unitAmount: number;
+  currency?: string;
+  type: "one_time" | "recurring";
+  interval?: "day" | "week" | "month" | "year";
+  intervalCount?: number;
+  nickname?: string;
+  metadata?: Record<string, string>;
+  idempotencyKey?: string;
+};
+
 export async function createPrice(
   stripe: Stripe,
   component: Component,
   ctx: RunCtx,
-  opts: {
-    stripeProductId: string;
-    unitAmount: number;
-    currency?: string;
-    type: "one_time" | "recurring";
-    interval?: "day" | "week" | "month" | "year";
-    intervalCount?: number;
-    nickname?: string;
-    metadata?: Record<string, string>;
-    idempotencyKey?: string;
-  },
+  opts: CreatePriceOptions,
 ) {
   // Validate the product exists in the component DB *before* writing to Stripe.
   // Creating the price first and throwing afterwards would orphan a price in

package/src/client/products/products.ts

@@ -54,20 +54,20 @@ async function resolveProductStatementDescriptor(
 // Product methods
 // =============================================================================
 
+export type CreateProductOptions = {
+  name: string;
+  description?: string;
+  active?: boolean;
+  accountId?: string;
+  metadata?: Record<string, string>;
+  idempotencyKey?: string;
+};
+
 export async function createProduct(
   stripe: Stripe,
   component: Component,
   ctx: RunCtx,
-  opts: {
-    name: string;
-    description?: string;
-    active?: boolean;
-    accountId?: string;
-    metadata?: Record<string, string>;
-    idempotencyKey?: string;
-    /** Platform default statement-descriptor suffix (BetterStripe option). */
-    defaultStatementDescriptorSuffix?: string;
-  },
+  opts: CreateProductOptions & { defaultStatementDescriptorSuffix?: string },
 ) {
   const statementDescriptor = await resolveProductStatementDescriptor(
     component,