@fantastic.dev/better-stripe 0.8.1 → 0.10.0

package/src/client/settlement/commissions.ts

@@ -0,0 +1,125 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { isBetterStripeError, throwStripeError } from "../errors.js";
+export type CommissionTerm = "forever" | "one_time";
+export type CommissionSelectionOptions = {
+  subscriptionId: string;
+  invoiceId: string;
+  affiliateAccountId?: string;
+  term?: CommissionTerm;
+  maxHistoryPages?: number;
+};
+export type CommissionDecision = {
+  eligible: boolean;
+  term: CommissionTerm;
+  firstPaidInvoiceId: string;
+  claimKey: string;
+  replay: boolean;
+};
+export type CommissionSelection =
+  | ({ status: "ready" } & CommissionDecision)
+  | { status: "not_payable"; eligible: false; reason: string };
+type Stored = {
+  subscriptionId: string;
+  term: CommissionTerm;
+  affiliateAccountId?: string;
+  firstPaidInvoiceId: string;
+};
+/** Durable selection only. Replay returns the same award key; execute through settleSale. */
+export async function selectCommissionInvoice(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: CommissionSelectionOptions,
+): Promise<CommissionSelection> {
+  try {
+    const invoice = await stripe.invoices.retrieve(opts.invoiceId);
+    const pointer = invoice.parent?.subscription_details?.subscription;
+    if (
+      (typeof pointer === "string" ? pointer : pointer?.id) !==
+      opts.subscriptionId
+    )
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Invoice does not belong to this subscription.",
+      );
+    if (invoice.status !== "paid" || invoice.amount_paid <= 0)
+      return {
+        status: "not_payable",
+        eligible: false,
+        reason: "invoice_not_paid_or_zero",
+      };
+    const stored = (await ctx.runQuery(
+      componentRef(component, "settlement/queries/getCommissionTerm"),
+      { subscriptionId: opts.subscriptionId },
+    )) as Stored | null;
+    let firstPaidInvoiceId = stored?.firstPaidInvoiceId ?? invoice.id;
+    const term = stored?.term ?? opts.term ?? "forever";
+    if (!stored && term === "one_time") {
+      const max = opts.maxHistoryPages ?? 100;
+      if (!Number.isInteger(max) || max < 1 || max > 1000)
+        throwStripeError(
+          "INVALID_CONFIGURATION",
+          "Invalid invoice history page bound.",
+        );
+      let cursor: string | undefined,
+        earliest: number = Infinity,
+        complete = false;
+      for (let i = 0; i < max; i++) {
+        const batch = await stripe.invoices.list({
+          subscription: opts.subscriptionId,
+          status: "paid",
+          limit: 100,
+          starting_after: cursor,
+        });
+        for (const row of batch.data)
+          if (row.amount_paid > 0) {
+            const paid = row.status_transitions.paid_at ?? row.created;
+            if (
+              paid < earliest ||
+              (paid === earliest && row.id < firstPaidInvoiceId)
+            ) {
+              earliest = paid;
+              firstPaidInvoiceId = row.id;
+            }
+          }
+        if (!batch.has_more) {
+          complete = true;
+          break;
+        }
+        const next = batch.data[batch.data.length - 1]?.id;
+        if (!next || next === cursor)
+          throwStripeError(
+            "STRIPE_API_ERROR",
+            "Invoice pagination did not advance.",
+          );
+        cursor = next;
+      }
+      if (!complete || !Number.isFinite(earliest))
+        throwStripeError(
+          "INVALID_CONFIGURATION",
+          "First paid invoice could not be established from complete history.",
+        );
+    }
+    const decision = (await runMutationOrThrow(
+      ctx,
+      componentRef(component, "settlement/mutations/claimCommissionInvoice"),
+      {
+        subscriptionId: opts.subscriptionId,
+        invoiceId: invoice.id,
+        firstPaidInvoiceId,
+        affiliateAccountId: opts.affiliateAccountId,
+        term,
+      },
+    )) as CommissionDecision;
+    return { status: "ready", ...decision };
+  } catch (error) {
+    if (isBetterStripeError(error)) throw error;
+    throwStripeError(
+      "STRIPE_API_ERROR",
+      "Could not select subscription commission invoice.",
+    );
+  }
+}

package/src/client/settlement/execution.test.ts

@@ -0,0 +1,186 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import type { Component, RunCtx } from "../helpers.js";
+import { executeResolvedTransfers } from "./execution.js";
+const TO_REF = Symbol.for("toReferencePath");
+const ref = (path: string) => ({ [TO_REF]: `betterStripe/${path}` });
+const component = {
+  settlement: {
+    claims: {
+      reserve: ref("settlement/mutations/reserveSettlementAllocation"),
+    },
+  },
+  connect: {
+    queries: {
+      listTransfersByCharge: ref("connect/queries/listTransfersByCharge"),
+    },
+    mutations: { upsertTransfer: ref("connect/mutations/upsertTransfer") },
+  },
+} as unknown as Component;
+it("recovers provider success after a ledger failure even without an idempotency cache", async () => {
+  let claimed: unknown;
+  const ledger: unknown[] = [],
+    provider: Record<string, unknown>[] = [];
+  let fail = true;
+  const runMutation = vi.fn(
+    async (r: Record<symbol, string>, args: Record<string, unknown>) => {
+      if (r[TO_REF].endsWith("/reserveSettlementAllocation"))
+        return claimed ?? (claimed = { ...args });
+      if (fail) {
+        fail = false;
+        throw new Error("ledger unavailable");
+      }
+      ledger.push(args);
+    },
+  );
+  const ctx = {
+    runMutation,
+    runQuery: vi.fn(async () => ledger),
+  } as unknown as RunCtx;
+  const raw = {
+    charges: { retrieve: vi.fn().mockResolvedValue({ created: 1 }) },
+    transfers: {
+      list: vi.fn(async () => ({ data: provider, has_more: false })),
+      create: vi.fn(async (args) => {
+        const transfer = {
+          id: `tr_${provider.length}`,
+          destination: args.destination,
+          ...args,
+        };
+        provider.push(transfer);
+        return transfer;
+      }),
+    },
+  };
+  const opts = {
+    sourceChargeId: "ch_1",
+    gross: 100,
+    currency: "usd",
+    processingFee: 3,
+    platformNet: 7,
+    transfers: [
+      { destinationAccountId: "acct_c", role: "store" as const, amount: 80 },
+      {
+        destinationAccountId: "acct_a",
+        role: "affiliate" as const,
+        amount: 10,
+      },
+    ],
+  };
+  await expect(
+    executeResolvedTransfers(raw as unknown as Stripe, component, ctx, opts),
+  ).rejects.toThrow("ledger unavailable");
+  const result = await executeResolvedTransfers(
+    raw as unknown as Stripe,
+    component,
+    ctx,
+    {
+      ...opts,
+      platformNet: 17,
+      transfers: [{ ...opts.transfers[0], amount: 70 }, opts.transfers[1]],
+    },
+  );
+  expect(raw.transfers.create).toHaveBeenCalledTimes(2);
+  expect(result.transfers.map((t) => t.amount)).toEqual([80, 10]);
+  expect(ledger).toHaveLength(2);
+  await executeResolvedTransfers(
+    raw as unknown as Stripe,
+    component,
+    ctx,
+    opts,
+  );
+  expect(raw.transfers.create).toHaveBeenCalledTimes(2);
+});
+it("recovers an orphaned original leg for refund/dispute clawback without creating more transfers", async () => {
+  const { recoverSettlementTransfers } = await import("./reconciliation.js");
+  const claim = {
+    sourceChargeId: "ch_refund",
+    gross: 100,
+    currency: "usd",
+    processingFee: 3,
+    platformNet: 7,
+    transfers: [
+      { destinationAccountId: "acct_c", role: "store" as const, amount: 90 },
+    ],
+  };
+  const provider = {
+    id: "tr_orphan",
+    destination: "acct_c",
+    amount: 90,
+    currency: "usd",
+    source_transaction: "ch_refund",
+    amount_reversed: 20,
+    metadata: { bsSourceCharge: "ch_refund", bsRole: "store" },
+  };
+  const raw = {
+    transfers: {
+      list: vi.fn().mockResolvedValue({ data: [provider], has_more: false }),
+      create: vi.fn(),
+    },
+  };
+  const runMutation = vi.fn(),
+    ctx = {
+      runQuery: vi.fn().mockResolvedValue(claim),
+      runMutation,
+    } as unknown as RunCtx;
+  await recoverSettlementTransfers(
+    raw as unknown as Stripe,
+    component,
+    ctx,
+    "ch_refund",
+  );
+  expect(runMutation).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      stripeTransferId: "tr_orphan",
+      sourceChargeId: "ch_refund",
+      amount: 90,
+      reversedAmount: 20,
+    }),
+  );
+  expect(raw.transfers.create).not.toHaveBeenCalled();
+});
+it("finds legacy transfers without a transfer group before issuing a new request", async () => {
+  const legacy = {
+    id: "tr_legacy",
+    destination: "acct_c",
+    amount: 90,
+    currency: "usd",
+    source_transaction: "ch_old",
+    metadata: { bsSourceCharge: "ch_old", bsRole: "store" },
+  };
+  const raw = {
+    charges: { retrieve: vi.fn().mockResolvedValue({ created: 1 }) },
+    transfers: {
+      list: vi.fn(async (params: { transfer_group?: string }) => ({
+        data: params.transfer_group ? [] : [legacy],
+        has_more: false,
+      })),
+      create: vi.fn().mockResolvedValue({ id: "tr_duplicate" }),
+    },
+  };
+  const opts = {
+    sourceChargeId: "ch_old",
+    gross: 100,
+    currency: "usd",
+    processingFee: 3,
+    platformNet: 7,
+    transfers: [
+      { destinationAccountId: "acct_c", role: "store" as const, amount: 90 },
+    ],
+  };
+  const ctx = {
+    runQuery: vi.fn().mockResolvedValue([]),
+    runMutation: vi.fn(async (r: Record<symbol, string>, args: unknown) =>
+      r[TO_REF].endsWith("reserveSettlementAllocation") ? args : null,
+    ),
+  } as unknown as RunCtx;
+  const result = await executeResolvedTransfers(
+    raw as unknown as Stripe,
+    component,
+    ctx,
+    opts,
+  );
+  expect(result.executedTransfers[0].stripeTransferId).toBe("tr_legacy");
+  expect(raw.transfers.create).not.toHaveBeenCalled();
+});

package/src/client/settlement/execution.ts

@@ -0,0 +1,134 @@
+import {
+  sourceTransfers,
+  matchingTransfer,
+  recordSettlementTransfer,
+} from "./reconciliation.js";
+import type Stripe from "stripe";
+import type { SplitTransfer } from "../core/fees.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+export type ResolvedSettlement = {
+  sourceChargeId: string;
+  paymentIntentId?: string;
+  sourceInvoiceId?: string;
+  gross: number;
+  currency: string;
+  processingFee: number;
+  platformNet: number;
+  adjustmentAmount?: number;
+  transfers: SplitTransfer[];
+  paymentId?: string;
+};
+export type SettlementResult = ResolvedSettlement & {
+  status: "settled";
+  executedTransfers: {
+    stripeTransferId: string;
+    destinationAccountId: string;
+    role: string;
+    amount: number;
+  }[];
+};
+type Ledger = {
+  stripeTransferId: string;
+  destinationAccountId: string;
+  role?: string;
+  amount: number;
+  currency: string;
+};
+/** Shared transfer engine for webhook splits and verified, host-resolved allocations. */
+export async function executeResolvedTransfers(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: ResolvedSettlement,
+): Promise<SettlementResult> {
+  const saved = (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "settlement/mutations/reserveSettlementAllocation"),
+    opts,
+  )) as ResolvedSettlement;
+  const claim: ResolvedSettlement = {
+    sourceChargeId: saved.sourceChargeId,
+    paymentIntentId: saved.paymentIntentId,
+    sourceInvoiceId: saved.sourceInvoiceId,
+    gross: saved.gross,
+    currency: saved.currency,
+    processingFee: saved.processingFee,
+    platformNet: saved.platformNet,
+    adjustmentAmount: saved.adjustmentAmount,
+    transfers: saved.transfers,
+    paymentId: saved.paymentId,
+  };
+  const existing = ((await ctx.runQuery(
+    componentRef(component, "connect/queries/listTransfersByCharge"),
+    { sourceChargeId: claim.sourceChargeId },
+  )) ?? []) as Ledger[];
+  let provider = await sourceTransfers(stripe, claim.sourceChargeId);
+  if (
+    claim.transfers.some(
+      (leg) =>
+        leg.amount > 0 &&
+        !existing.some(
+          (t) =>
+            t.destinationAccountId === leg.destinationAccountId &&
+            t.role === leg.role,
+        ) &&
+        !matchingTransfer(provider, claim, leg),
+    )
+  ) {
+    provider = [
+      ...new Map(
+        [
+          ...provider,
+          ...(await sourceTransfers(stripe, claim.sourceChargeId, true)),
+        ].map((t) => [t.id, t]),
+      ).values(),
+    ];
+  }
+  const executedTransfers: SettlementResult["executedTransfers"] = [];
+  for (const leg of claim.transfers) {
+    if (leg.amount === 0) continue;
+    const recorded = existing.find(
+      (t) =>
+        t.destinationAccountId === leg.destinationAccountId &&
+        t.role === leg.role,
+    );
+    if (
+      recorded &&
+      (recorded.amount !== leg.amount || recorded.currency !== claim.currency)
+    )
+      throw new Error("Recorded transfer conflicts with immutable settlement.");
+    let transferId = recorded?.stripeTransferId;
+    if (!transferId) {
+      const recovered = matchingTransfer(provider, claim, leg);
+      const transfer =
+        recovered ??
+        (await stripe.transfers.create(
+          {
+            amount: leg.amount,
+            currency: claim.currency,
+            destination: leg.destinationAccountId,
+            source_transaction: claim.sourceChargeId,
+            transfer_group: claim.sourceChargeId,
+            metadata: {
+              bsRole: leg.role,
+              bsSourceCharge: claim.sourceChargeId,
+            },
+          },
+          {
+            idempotencyKey: `bs_split_${claim.sourceChargeId}_${leg.destinationAccountId}_${leg.role}`,
+          },
+        ));
+      transferId = transfer.id;
+      await recordSettlementTransfer(component, ctx, claim, leg, transfer);
+    }
+    executedTransfers.push({
+      stripeTransferId: transferId,
+      destinationAccountId: leg.destinationAccountId,
+      role: leg.role,
+      amount: leg.amount,
+    });
+  }
+  return { ...claim, status: "settled", executedTransfers };
+}

package/src/client/settlement/reconciliation.ts

@@ -0,0 +1,119 @@
+import type Stripe from "stripe";
+import type { SplitTransfer } from "../core/fees.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import type { ResolvedSettlement } from "./execution.js";
+export async function sourceTransfers(
+  stripe: Stripe,
+  sourceChargeId: string,
+  legacy = false,
+): Promise<Stripe.Transfer[]> {
+  const rows: Stripe.Transfer[] = [];
+  let cursor: string | undefined;
+  const charge = legacy ? await stripe.charges.retrieve(sourceChargeId) : null;
+  const created =
+    charge && charge.created <= Math.floor(Date.now() / 1000)
+      ? { gte: charge.created }
+      : undefined;
+  for (let page = 0; page < 100; page++) {
+    const batch = await stripe.transfers.list({
+      ...(legacy ? { created } : { transfer_group: sourceChargeId }),
+      limit: 100,
+      starting_after: cursor,
+    });
+    rows.push(...batch.data);
+    if (!batch.has_more) return rows;
+    const next = batch.data[batch.data.length - 1]?.id;
+    if (!next || next === cursor)
+      throw new Error("Settlement transfer reconciliation did not advance.");
+    cursor = next;
+  }
+  throw new Error(
+    "Settlement transfer reconciliation exceeded its page bound; review before retrying.",
+  );
+}
+export function matchingTransfer(
+  provider: Stripe.Transfer[],
+  claim: ResolvedSettlement,
+  leg: SplitTransfer,
+) {
+  const matches = provider.filter(
+    (t) =>
+      (typeof t.destination === "string"
+        ? t.destination
+        : t.destination?.id) === leg.destinationAccountId &&
+      (t.metadata.bsRole ?? t.metadata.role) === leg.role &&
+      (t.metadata.bsSourceCharge ?? t.metadata.storeSaleChargeId) ===
+        claim.sourceChargeId,
+  );
+  if (
+    matches.length > 1 ||
+    matches.some(
+      (t) =>
+        t.amount !== leg.amount ||
+        t.currency !== claim.currency ||
+        t.source_transaction !== claim.sourceChargeId,
+    )
+  )
+    throw new Error(
+      "Provider transfers conflict with claimed settlement; manual review required.",
+    );
+  return matches[0];
+}
+export async function recordSettlementTransfer(
+  component: Component,
+  ctx: RunCtx,
+  claim: ResolvedSettlement,
+  leg: SplitTransfer,
+  transfer: Stripe.Transfer,
+) {
+  await runMutationOrThrow(
+    ctx,
+    componentRef(component, "connect/mutations/upsertTransfer"),
+    {
+      stripeTransferId: transfer.id,
+      sourceChargeId: claim.sourceChargeId,
+      sourceInvoiceId: claim.sourceInvoiceId,
+      destinationAccountId: leg.destinationAccountId,
+      amount: leg.amount,
+      currency: claim.currency,
+      role: leg.role,
+      status: "paid",
+      paymentId: claim.paymentId,
+      reversedAmount: transfer.amount_reversed ?? 0,
+    },
+  );
+}
+/** Recover provider-success/ledger-failure legs before sizing refunds or disputes. */
+export async function recoverSettlementTransfers(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  sourceChargeId: string,
+) {
+  const claim = (await ctx.runQuery(
+    componentRef(component, "settlement/queries/getSettlementAllocation"),
+    { sourceChargeId },
+  )) as ResolvedSettlement | null;
+  if (!claim || typeof claim.sourceChargeId !== "string") return;
+  let provider = await sourceTransfers(stripe, sourceChargeId);
+  if (
+    claim.transfers.some(
+      (leg) => leg.amount > 0 && !matchingTransfer(provider, claim, leg),
+    )
+  )
+    provider = [
+      ...new Map(
+        [
+          ...provider,
+          ...(await sourceTransfers(stripe, sourceChargeId, true)),
+        ].map((t) => [t.id, t]),
+      ).values(),
+    ];
+  for (const leg of claim.transfers) {
+    const transfer = matchingTransfer(provider, claim, leg);
+    if (transfer)
+      await recordSettlementTransfer(component, ctx, claim, leg, transfer);
+  }
+}

package/src/client/settlement/settleSale.ts

@@ -0,0 +1,59 @@
+import type Stripe from "stripe";
+import type { SplitTransfer } from "../core/fees.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { throwStripeError } from "../errors.js";
+import { getVerifiedSale, type VerifiedSaleOptions } from "./verifiedSale.js";
+import {
+  executeResolvedTransfers,
+  type SettlementResult,
+} from "./execution.js";
+export type SettleSaleOptions = VerifiedSaleOptions & {
+  allocation: {
+    gross: number;
+    currency: string;
+    processingFee: number;
+    platformNet: number;
+    adjustmentAmount?: number;
+    transfers: SplitTransfer[];
+  };
+  paymentId?: string;
+  onSettled?: (result: SettlementResult) => Promise<void>;
+};
+export async function settleSale(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: SettleSaleOptions,
+): Promise<
+  | SettlementResult
+  | Exclude<Awaited<ReturnType<typeof getVerifiedSale>>, { status: "ready" }>
+> {
+  const sale = await getVerifiedSale(stripe, opts);
+  if (sale.status !== "ready") return sale;
+  const prior = (await ctx.runQuery(
+    componentRef(component, "settlement/queries/getSettlementAllocation"),
+    {
+      sourceChargeId: sale.chargeId,
+    },
+  )) as SettlementResult | null;
+  const allocation = prior ?? opts.allocation;
+  if (
+    allocation.gross !== sale.gross ||
+    allocation.currency !== sale.currency ||
+    allocation.processingFee !== sale.processingFee
+  )
+    throwStripeError(
+      "INVALID_CONFIGURATION",
+      "Allocation must use verified payment currency, gross and actual processing cost.",
+    );
+  const result = await executeResolvedTransfers(stripe, component, ctx, {
+    ...opts.allocation,
+    sourceChargeId: sale.chargeId,
+    paymentIntentId: sale.paymentIntentId,
+    sourceInvoiceId: sale.invoiceId,
+    paymentId: opts.paymentId,
+  });
+  await opts.onSettled?.(result);
+  return result;
+}