@fantastic.dev/better-stripe 0.9.0 → 0.10.0

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;
+}

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

@@ -0,0 +1,139 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import { getVerifiedSale } from "./verifiedSale.js";
+function fixture() {
+  const payment = {
+    id: "pi_1",
+    status: "succeeded",
+    currency: "usd",
+    amount_received: 10000,
+    metadata: { seller: "store" },
+    latest_charge: {
+      id: "ch_1",
+      amount: 10000,
+      currency: "usd",
+      amount_refunded: 0,
+      disputed: false,
+      balance_transaction: { currency: "usd", fee: 320 },
+    },
+  };
+  const raw = {
+    paymentIntents: { retrieve: vi.fn().mockResolvedValue(payment) },
+    subscriptions: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "sub_1",
+        metadata: { ref: "a" },
+        items: {
+          data: [{ price: { id: "price_current", product: "prod_current" } }],
+        },
+      }),
+    },
+    invoices: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "in_1",
+        status: "paid",
+        amount_paid: 10000,
+        currency: "usd",
+        parent: { subscription_details: { subscription: "sub_1" } },
+      }),
+    },
+    invoicePayments: {
+      list: vi.fn().mockResolvedValue({
+        data: [{ status: "paid", payment: { payment_intent: "pi_1" } }],
+        has_more: false,
+      }),
+    },
+  };
+  return { payment, raw, stripe: raw as unknown as Stripe };
+}
+it("returns actual fees, verified invoice linkage and current price instead of stale metadata", async () => {
+  const { stripe, raw } = fixture();
+  expect(
+    await getVerifiedSale(stripe, {
+      paymentIntentId: "pi_1",
+      subscriptionId: "sub_1",
+      invoiceId: "in_1",
+    }),
+  ).toMatchObject({
+    status: "ready",
+    chargeId: "ch_1",
+    processingFee: 320,
+    currency: "usd",
+    stripePriceId: "price_current",
+    stripeProductId: "prod_current",
+    invoiceId: "in_1",
+  });
+  expect(raw.paymentIntents.retrieve).toHaveBeenCalledWith("pi_1", {
+    expand: ["latest_charge.balance_transaction"],
+  });
+});
+it("reports missing fees and unsuccessful payments as non-ready, never zero fees", async () => {
+  const { stripe, raw, payment } = fixture();
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    latest_charge: { ...payment.latest_charge, balance_transaction: null },
+  });
+  expect(await getVerifiedSale(stripe, { paymentIntentId: "pi_1" })).toEqual({
+    status: "pending",
+    reason: "processing_fee_unavailable",
+    retryable: true,
+  });
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    status: "requires_payment_method",
+  });
+  expect(
+    await getVerifiedSale(stripe, { paymentIntentId: "pi_1" }),
+  ).toMatchObject({ status: "not_payable", retryable: false });
+});
+it("rejects mismatched currencies and unrelated invoice payments", async () => {
+  const { stripe, raw, payment } = fixture();
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    latest_charge: {
+      ...payment.latest_charge,
+      balance_transaction: { currency: "eur", fee: 320 },
+    },
+  });
+  await expect(
+    getVerifiedSale(stripe, { paymentIntentId: "pi_1" }),
+  ).rejects.toThrow();
+  raw.paymentIntents.retrieve.mockResolvedValue(payment);
+  raw.invoicePayments.list.mockResolvedValue({
+    data: [{ status: "paid", payment: { payment_intent: "pi_other" } }],
+    has_more: false,
+  });
+  await expect(
+    getVerifiedSale(stripe, {
+      paymentIntentId: "pi_1",
+      invoiceId: "in_1",
+      subscriptionId: "sub_1",
+    }),
+  ).rejects.toThrow();
+});
+it("marks processing payments as retryable without paying recipients", async () => {
+  const { stripe, raw, payment } = fixture();
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    status: "processing",
+  });
+  expect(await getVerifiedSale(stripe, { paymentIntentId: "pi_1" })).toEqual({
+    status: "pending",
+    reason: "payment_processing",
+    retryable: true,
+  });
+});
+
+it("refuses partial invoice payments rather than awarding a fixed commission more than once", async () => {
+  const { stripe, raw } = fixture();
+  raw.invoices.retrieve.mockResolvedValue({
+    id: "in_1",
+    status: "paid",
+    amount_paid: 20000,
+    currency: "usd",
+    parent: { subscription_details: { subscription: "sub_1" } },
+  });
+  await expect(
+    getVerifiedSale(stripe, { paymentIntentId: "pi_1", invoiceId: "in_1" }),
+  ).rejects.toThrow("Partial invoice payments");
+});

package/src/client/settlement/verifiedSale.ts

@@ -0,0 +1,159 @@
+import type Stripe from "stripe";
+import { isBetterStripeError, throwStripeError } from "../errors.js";
+export type VerifiedSaleOptions = {
+  paymentIntentId: string;
+  subscriptionId?: string;
+  invoiceId?: string;
+};
+export type VerifiedSale =
+  | { status: "pending" | "not_payable"; reason: string; retryable: boolean }
+  | {
+      status: "ready";
+      paymentIntentId: string;
+      chargeId: string;
+      gross: number;
+      processingFee: number;
+      currency: string;
+      metadata: Record<string, string>;
+      invoiceId?: string;
+      subscriptionId?: string;
+      stripePriceId?: string;
+      stripeProductId?: string;
+    };
+const id = (value: string | { id: string } | null | undefined) =>
+  typeof value === "string" ? value : value?.id;
+export async function getVerifiedSale(
+  stripe: Stripe,
+  opts: VerifiedSaleOptions,
+): Promise<VerifiedSale> {
+  try {
+    const payment = await stripe.paymentIntents.retrieve(opts.paymentIntentId, {
+      expand: ["latest_charge.balance_transaction"],
+    });
+    if (payment.status === "processing")
+      return {
+        status: "pending",
+        reason: "payment_processing",
+        retryable: true,
+      };
+    if (payment.status !== "succeeded")
+      return {
+        status: "not_payable",
+        reason: "payment_not_succeeded",
+        retryable: false,
+      };
+    const charge = payment.latest_charge;
+    if (!charge || typeof charge === "string")
+      return {
+        status: "pending",
+        reason: "charge_unavailable",
+        retryable: true,
+      };
+    if (charge.amount_refunded > 0 || charge.disputed)
+      return {
+        status: "not_payable",
+        reason: "charge_refunded_or_disputed",
+        retryable: false,
+      };
+    const balance = charge.balance_transaction;
+    if (!balance || typeof balance === "string")
+      return {
+        status: "pending",
+        reason: "processing_fee_unavailable",
+        retryable: true,
+      };
+    if (
+      balance.currency !== payment.currency ||
+      charge.currency !== payment.currency
+    )
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Settlement currency must match the payment and processing currency.",
+      );
+    if (
+      ![payment.amount_received, balance.fee].every(Number.isSafeInteger) ||
+      balance.fee < 0 ||
+      balance.fee > payment.amount_received ||
+      charge.amount !== payment.amount_received
+    )
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Unsupported payment or processing amounts.",
+      );
+    if (opts.subscriptionId && !opts.invoiceId)
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Subscription settlement requires a paid invoice.",
+      );
+    const invoice = opts.invoiceId
+      ? await stripe.invoices.retrieve(opts.invoiceId)
+      : null;
+    if (invoice && invoice.status !== "paid")
+      return { status: "pending", reason: "invoice_not_paid", retryable: true };
+    const subscriptionId = id(
+      invoice?.parent?.subscription_details?.subscription,
+    );
+    if (
+      invoice &&
+      (invoice.currency !== payment.currency ||
+        (opts.subscriptionId && subscriptionId !== opts.subscriptionId))
+    )
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Invoice currency or subscription does not match settlement.",
+      );
+    if (invoice) {
+      if (invoice.amount_paid !== payment.amount_received)
+        throwStripeError(
+          "INVALID_CONFIGURATION",
+          "Partial invoice payments require an explicitly resolved invoice allocation.",
+        );
+      const linked = await stripe.invoicePayments.list({
+        invoice: invoice.id,
+        limit: 100,
+        status: "paid",
+        payment: { type: "payment_intent", payment_intent: payment.id },
+      });
+      if (
+        !linked.data.some(
+          (row) =>
+            row.status === "paid" &&
+            id(row.payment.payment_intent) === payment.id,
+        )
+      )
+        throwStripeError(
+          "INVALID_CONFIGURATION",
+          "Payment does not belong to this paid invoice.",
+        );
+    }
+    const subscription = subscriptionId
+      ? await stripe.subscriptions.retrieve(subscriptionId)
+      : null;
+    if (subscription && subscription.items.data.length !== 1)
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Resolve multi-price subscription allocations explicitly.",
+      );
+    const price = subscription?.items.data[0]?.price;
+    const metadata = subscription?.metadata ?? payment.metadata;
+    return {
+      status: "ready",
+      paymentIntentId: payment.id,
+      chargeId: charge.id,
+      gross: payment.amount_received,
+      processingFee: balance.fee,
+      currency: payment.currency,
+      metadata,
+      invoiceId: invoice?.id,
+      subscriptionId,
+      stripePriceId: price?.id ?? metadata.stripePriceId,
+      stripeProductId: id(price?.product) ?? metadata.stripeProductId,
+    };
+  } catch (error) {
+    if (isBetterStripeError(error)) throw error;
+    throwStripeError(
+      "STRIPE_API_ERROR",
+      "Could not retrieve verified sale context.",
+    );
+  }
+}

package/src/client/webhooks/asyncHooks.ts

@@ -0,0 +1,38 @@
+import type { AsyncHooks, AsyncHookCtx } from "../types.js";
+import type { AsyncHookName } from "../types/triggers.js";
+/** Route async webhook hooks through the shared public callback contract. */
+export function buildAsyncHookRoutes(hooks: AsyncHooks | undefined) {
+  const routes: Record<
+    AsyncHookName,
+    ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined
+  > = {
+    afterAccountUpdated: hooks?.onAccountUpdated as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterCheckoutCompleted: hooks?.onCheckoutCompleted as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterSubscriptionUpdated: hooks?.onSubscriptionUpdated as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterSubscriptionCanceled: hooks?.onSubscriptionCanceled as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterTrialEnding: hooks?.onTrialEnding as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterInvoicePaid: hooks?.onInvoicePaid as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterInvoicePaymentFailed: hooks?.onInvoicePaymentFailed as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterPaymentSucceeded: hooks?.onPaymentSucceeded as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterPaymentFailed: hooks?.onPaymentFailed as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterPayoutCompleted: hooks?.onPayoutCompleted as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterRefundCreated: hooks?.onRefundCreated as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterDisputeCreated: hooks?.onDisputeCreated as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterDisputeClosed: hooks?.onDisputeClosed as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+  };
+
+  return routes;
+}