@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/src/client/affiliateRecovery/disputes.ts

@@ -0,0 +1,62 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { recoverSettlementTransfers } from "../settlement/reconciliation.js";
+import {
+  executeClaimedSlices,
+  type ReversalClaim,
+} from "../connect/reversalExecution.js";
+import { reconcileAffiliateCharge } from "./engine.js";
+
+/** Record proportional original commission exposure for a monetary dispute. */
+export async function reverseTransfersForDispute(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: {
+    sourceChargeId: string;
+    operationId: string;
+    chargeAmount: number;
+    amount: number;
+    finalized: boolean;
+    disputeState?: "open" | "lost" | "won";
+    refundedPrincipal?: number;
+  },
+) {
+  await recoverSettlementTransfers(stripe, component, ctx, opts.sourceChargeId);
+  const claim = (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "connect/mutations/claimReversalSlices"),
+    {
+      sourceChargeId: opts.sourceChargeId,
+      operationId: opts.operationId,
+      mode:
+        opts.disputeState === "won"
+          ? {
+              kind: "fraction",
+              chargeAmount: opts.chargeAmount,
+              amountRefunded: 0,
+            }
+          : { kind: "amount", amount: opts.amount },
+      commissionExposure: {
+        kind: "dispute",
+        chargeAmount: opts.chargeAmount,
+        principal: opts.amount,
+        finalized: opts.finalized,
+        disputeState: opts.disputeState,
+        refundedPrincipal: opts.refundedPrincipal,
+        disputeId: opts.operationId,
+      },
+    },
+  )) as ReversalClaim;
+  const result = await executeClaimedSlices(
+    stripe,
+    component,
+    ctx,
+    opts.operationId,
+    { ...claim, slices: claim.slices.filter((s) => !s.commissionTracked) },
+  );
+  await reconcileAffiliateCharge(stripe, component, ctx, opts.sourceChargeId);
+  return result;
+}

package/src/client/affiliateRecovery/engine.ts

@@ -0,0 +1,196 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import {
+  classifyRecoveryError,
+  findReceipt,
+  verifyConnectPath,
+  type RecoveryObligation,
+  type RecoveryOperation,
+} from "./provider.js";
+export async function reconcileObligation(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  obligationId: string,
+) {
+  let row = (await ctx.runQuery(
+    componentRef(component, "affiliateRecovery/queries/getObligation"),
+    { obligationId },
+  )) as RecoveryObligation | null;
+  if (!row || row.needsReconciliation)
+    return {
+      state: "unsupported",
+      reason: "Original commission provenance requires reconciliation.",
+    };
+  // Finish uncertain recovery before restoring its actual proceeds. Each pass
+  // claims one immutable operation atomically with debt/offset reservations.
+  let lastState = "settled";
+  for (let pass = 0; pass < 2; pass++) {
+    const net =
+      row.recoveredAmount + (row.offsetAmount ?? 0) - (row.restoredAmount ?? 0);
+    const kind =
+      net > row.finalizedAmount + row.provisionalAmount
+        ? "restoration"
+        : "recovery";
+    const op = (await runMutationOrThrow(
+      ctx,
+      componentRef(component, "affiliateRecovery/mutations/reserveOperation"),
+      { obligationId, kind, now: Date.now() },
+    )) as RecoveryOperation | null;
+    if (!op) {
+      if ((row.debtAmount ?? 0) > 0) lastState = "offset_required";
+      break;
+    }
+    try {
+      const receiptId = op.attempted
+        ? await findReceipt(stripe, op, row)
+        : null;
+      if (!receiptId && op.attempted && op.kind === "recovery") {
+        const original = await stripe.transfers.retrieve(row.stripeTransferId!);
+        if (
+          original.amount_reversed >
+          (op.providerBaseline ?? row.recoveredAmount)
+        ) {
+          const error =
+            "Provider reversal aggregate changed without an attributable operation receipt; operator receipt review is required.";
+          await runMutationOrThrow(
+            ctx,
+            componentRef(
+              component,
+              "affiliateRecovery/mutations/completeOperation",
+            ),
+            { operationId: op._id, state: "unknown", error },
+          );
+          return { state: "unknown", error };
+        }
+      }
+      let confirmed = receiptId;
+      if (!confirmed) {
+        const started = (await runMutationOrThrow(
+          ctx,
+          componentRef(component, "affiliateRecovery/mutations/beginOperation"),
+          { operationId: op._id },
+        )) as RecoveryOperation;
+        if (!["pending", "unknown"].includes(started.state)) {
+          lastState = started.state;
+          if (started.state === "canceled") {
+            row = (await ctx.runQuery(
+              componentRef(
+                component,
+                "affiliateRecovery/queries/getObligation",
+              ),
+              { obligationId },
+            )) as RecoveryObligation;
+            continue;
+          }
+          break;
+        }
+        const capability = await verifyConnectPath(stripe, row, op.kind);
+        if (!capability.supported) {
+          await runMutationOrThrow(
+            ctx,
+            componentRef(
+              component,
+              "affiliateRecovery/mutations/completeOperation",
+            ),
+            {
+              operationId: op._id,
+              state: op.attempted ? "unknown" : "unsupported",
+              error: capability.reason,
+            },
+          );
+          return {
+            state: op.attempted ? "unknown" : "unsupported",
+            reason: capability.reason,
+          };
+        }
+        const metadata = {
+          bsRecoveryOperation: op._id,
+          bsOriginalCharge: row.sourceChargeId,
+        };
+        if (op.kind === "recovery") {
+          const receipt = await stripe.transfers.createReversal(
+            row.stripeTransferId!,
+            { amount: op.amount, metadata },
+            { idempotencyKey: `bs_affiliate_${op._id}` },
+          );
+          if (receipt.amount !== op.amount)
+            throw new Error("Affiliate provider reversal amount mismatch.");
+          confirmed = receipt.id;
+        } else {
+          const receipt = await stripe.transfers.create(
+            {
+              amount: op.amount,
+              currency: row.currency,
+              destination: row.affiliateAccountId,
+              transfer_group: `bs_restore_${row._id}`,
+              metadata,
+            },
+            { idempotencyKey: `bs_affiliate_${op._id}` },
+          );
+          if (receipt.amount !== op.amount || receipt.currency !== row.currency)
+            throw new Error("Affiliate provider restoration amount mismatch.");
+          confirmed = receipt.id;
+        }
+      }
+      const confirmedTransferReversed =
+        op.kind === "recovery"
+          ? (await stripe.transfers.retrieve(row.stripeTransferId!))
+              .amount_reversed
+          : undefined;
+      await runMutationOrThrow(
+        ctx,
+        componentRef(
+          component,
+          "affiliateRecovery/mutations/completeOperation",
+        ),
+        {
+          operationId: op._id,
+          state: "succeeded",
+          receiptId: confirmed,
+          confirmedTransferReversed,
+        },
+      );
+      lastState = "succeeded";
+    } catch (error) {
+      const outcome = classifyRecoveryError(error);
+      // This write deliberately occurs outside the provider/receipt transaction.
+      // Unknown outcomes retain the reservation and block commission release.
+      await runMutationOrThrow(
+        ctx,
+        componentRef(
+          component,
+          "affiliateRecovery/mutations/completeOperation",
+        ),
+        { operationId: op._id, ...outcome },
+      );
+      return outcome;
+    }
+    row = (await ctx.runQuery(
+      componentRef(component, "affiliateRecovery/queries/getObligation"),
+      { obligationId },
+    )) as RecoveryObligation;
+  }
+  return { state: lastState };
+}
+export async function reconcileAffiliateCharge(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  sourceChargeId: string,
+) {
+  const rows = (await ctx.runQuery(
+    componentRef(component, "affiliateRecovery/queries/chargeObligations"),
+    { sourceChargeId },
+  )) as RecoveryObligation[] | null;
+  const results = [];
+  for (const row of rows ?? [])
+    if (
+      typeof row._id === "string" &&
+      typeof row.originalCommission === "number"
+    )
+      results.push(await reconcileObligation(stripe, component, ctx, row._id));
+  return results;
+}

package/src/client/affiliateRecovery/payoutGate.ts

@@ -0,0 +1,65 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import type { Doc } from "../../component/_generated/dataModel.js";
+export async function reserveAffiliatePayout(
+  component: Component,
+  ctx: RunCtx,
+  opts: {
+    stripeAccountId: string;
+    currency?: string;
+    amount: number;
+    minimumAmount?: number;
+    idempotencyKey?: string;
+  },
+) {
+  return runMutationOrThrow(
+    ctx,
+    componentRef(component, "affiliatePayouts/mutations/reservePayout"),
+    {
+      affiliateAccountId: opts.stripeAccountId,
+      currency: opts.currency ?? "usd",
+      amount: opts.amount,
+      minimumAmount: opts.minimumAmount ?? 1,
+      operationKey: opts.idempotencyKey,
+      now: Date.now(),
+    },
+  ) as Promise<Doc<"affiliatePayoutReleases"> | null>;
+}
+export async function completeAffiliatePayout(
+  component: Component,
+  ctx: RunCtx,
+  operationKey: string,
+  state: "unknown" | "submitted" | "failed",
+  stripePayoutId?: string,
+) {
+  return runMutationOrThrow(
+    ctx,
+    componentRef(component, "affiliatePayouts/mutations/finishPayout"),
+    { operationKey, state, stripePayoutId },
+  );
+}
+export async function reconcileAffiliatePayout(
+  stripe: Stripe,
+  release: Doc<"affiliatePayoutReleases">,
+) {
+  let count = 0;
+  for await (const receipt of stripe.payouts.list(
+    { created: { gte: Math.floor(release.createdAt / 1000) }, limit: 100 },
+    { stripeAccount: release.affiliateAccountId },
+  )) {
+    if (++count > 1000)
+      throw new Error(
+        "Affiliate payout history requires operator reconciliation.",
+      );
+    if (receipt.metadata?.bsAffiliatePayout !== release._id) continue;
+    if (
+      receipt.currency !== release.currency ||
+      receipt.amount !== release.amount
+    )
+      throw new Error("Affiliate payout receipt mismatch.");
+    return receipt.id;
+  }
+  return null;
+}

package/src/client/affiliateRecovery/provider.ts

@@ -0,0 +1,127 @@
+import type Stripe from "stripe";
+import type { Doc } from "../../component/_generated/dataModel.js";
+export type RecoveryOperation = Doc<"affiliateRecoveryOperations">;
+export type RecoveryObligation = Doc<"affiliateObligations">;
+export async function findReceipt(
+  stripe: Stripe,
+  op: RecoveryOperation,
+  row: RecoveryObligation,
+) {
+  let count = 0;
+  if (op.kind === "recovery") {
+    if (!row.stripeTransferId) return null;
+    for await (const receipt of stripe.transfers.listReversals(
+      row.stripeTransferId,
+      { limit: 100 },
+    )) {
+      if (++count > 1000)
+        throw new Error("Affiliate receipt history exceeds supported bound.");
+      if (receipt.metadata?.bsRecoveryOperation !== op._id) continue;
+      if (receipt.amount !== op.amount)
+        throw new Error("Affiliate reversal receipt amount mismatch.");
+      return receipt.id;
+    }
+  } else {
+    for await (const receipt of stripe.transfers.list({
+      transfer_group: `bs_restore_${row._id}`,
+      limit: 100,
+    })) {
+      if (++count > 1000)
+        throw new Error(
+          "Affiliate restoration history exceeds supported bound.",
+        );
+      if (receipt.metadata?.bsRecoveryOperation !== op._id) continue;
+      const destination =
+        typeof receipt.destination === "string"
+          ? receipt.destination
+          : receipt.destination?.id;
+      if (
+        receipt.amount !== op.amount ||
+        receipt.currency !== row.currency ||
+        destination !== row.affiliateAccountId
+      )
+        throw new Error("Affiliate restoration receipt identity mismatch.");
+      return receipt.id;
+    }
+  }
+  return null;
+}
+export async function verifyConnectPath(
+  stripe: Stripe,
+  row: RecoveryObligation,
+  kind: RecoveryOperation["kind"],
+) {
+  const account = await stripe.v2.core.accounts.retrieve(
+    row.affiliateAccountId,
+    { include: ["configuration.recipient"] },
+  );
+  const capability =
+    account.configuration?.recipient?.capabilities?.stripe_balance
+      ?.stripe_transfers;
+  if (capability?.status !== "active")
+    return {
+      supported: false,
+      reason:
+        "Connect recipient stripe_transfers capability is not active; operator review required.",
+    };
+  if (kind === "recovery") {
+    if (!row.stripeTransferId)
+      return {
+        supported: false,
+        reason:
+          "No original Connect transfer; recover through future commissions.",
+      };
+    const original = await stripe.transfers.retrieve(row.stripeTransferId);
+    const destination =
+      typeof original.destination === "string"
+        ? original.destination
+        : original.destination?.id;
+    if (
+      destination !== row.affiliateAccountId ||
+      original.currency !== row.currency ||
+      original.source_transaction !== row.sourceChargeId ||
+      original.amount !== (row.releasedCommission ?? row.originalCommission)
+    )
+      return {
+        supported: false,
+        reason:
+          "Original Connect transfer identity does not match the commission; operator review required.",
+      };
+  }
+  return {
+    supported: true,
+    reason:
+      "Original Connect path verified; reversal remains subject to available balance and provider restrictions.",
+  };
+}
+export function classifyRecoveryError(error: unknown): {
+  state: "unknown" | "insufficient_balance" | "unsupported" | "failed";
+  error: string;
+} {
+  const value = error as { code?: string; type?: string; message?: string };
+  const code = value.code ?? "";
+  const state = ["balance_insufficient", "insufficient_funds"].includes(code)
+    ? "insufficient_balance"
+    : [
+          "account_invalid",
+          "transfers_not_allowed",
+          "resource_missing",
+          "platform_account_required",
+        ].includes(code)
+      ? "unsupported"
+      : [
+            "StripeConnectionError",
+            "StripeAPIError",
+            "StripeRateLimitError",
+          ].includes(value.type ?? "") ||
+          code === "idempotency_key_in_use" ||
+          !value.type
+        ? "unknown"
+        : "failed";
+  return {
+    state,
+    error: (
+      value.message ?? "Affiliate provider outcome requires reconciliation."
+    ).slice(0, 500),
+  };
+}

package/src/client/affiliateRecovery/review.ts

@@ -0,0 +1,117 @@
+import type Stripe from "stripe";
+import type { RecoveryObligation } from "./provider.js";
+import { successfulRefundPrincipal } from "../connect/refundPrincipal.js";
+/** Operator-selected provenance is verified against exact provider receipts. */
+export async function verifiedLegacyReview(
+  stripe: Stripe,
+  row: RecoveryObligation,
+  opts: {
+    reversalIds: string[];
+    restorationTransferIds?: string[];
+    note: string;
+  },
+) {
+  if (
+    !opts.note.trim() ||
+    opts.reversalIds.length > 100 ||
+    new Set(opts.reversalIds).size !== opts.reversalIds.length ||
+    (opts.restorationTransferIds?.length ?? 0) > 100
+  )
+    throw new Error("Provide a review note and at most 100 unique receipts.");
+  if (!row.stripeTransferId)
+    throw new Error("Legacy review requires an original Connect transfer.");
+  const original = await stripe.transfers.retrieve(row.stripeTransferId);
+  const destination =
+    typeof original.destination === "string"
+      ? original.destination
+      : original.destination?.id;
+  if (
+    destination !== row.affiliateAccountId ||
+    original.currency !== row.currency ||
+    original.source_transaction !== row.sourceChargeId
+  )
+    throw new Error("Legacy transfer identity mismatch.");
+  const receipts = [];
+  for (const id of opts.reversalIds) {
+    const receipt = await stripe.transfers.retrieveReversal(
+      row.stripeTransferId,
+      id,
+    );
+    if (
+      receipt.transfer !== row.stripeTransferId ||
+      receipt.currency !== row.currency ||
+      receipt.id !== id
+    )
+      throw new Error("Legacy reversal receipt identity mismatch.");
+    receipts.push({ id, amount: receipt.amount });
+  }
+  const recoveredAmount = receipts.reduce((sum, r) => sum + r.amount, 0);
+  if (recoveredAmount > original.amount_reversed)
+    throw new Error("Legacy receipts exceed confirmed provider reversals.");
+  let restoredAmount = 0;
+  const restorationIds = opts.restorationTransferIds ?? [];
+  if (new Set(restorationIds).size !== restorationIds.length)
+    throw new Error("Restoration receipts must be unique.");
+  for (const id of restorationIds) {
+    const transfer = await stripe.transfers.retrieve(id);
+    const recipient =
+      typeof transfer.destination === "string"
+        ? transfer.destination
+        : transfer.destination?.id;
+    if (
+      recipient !== row.affiliateAccountId ||
+      transfer.currency !== row.currency ||
+      transfer.metadata.bsReinstateOf !== row.sourceChargeId
+    )
+      throw new Error("Legacy restoration receipt identity mismatch.");
+    restoredAmount += transfer.amount;
+  }
+  const charge = await stripe.charges.retrieve(row.sourceChargeId);
+  const refundedPrincipal = await successfulRefundPrincipal(
+    stripe,
+    row.sourceChargeId,
+  );
+  const disputes = [];
+  for await (const dispute of stripe.disputes.list({
+    charge: row.sourceChargeId,
+    limit: 100,
+  })) {
+    if (disputes.length >= 10)
+      throw new Error(
+        "Legacy dispute history requires manual source allocation.",
+      );
+    if (
+      !dispute.status.startsWith("warning_") &&
+      dispute.status !== "prevented"
+    )
+      disputes.push(dispute);
+  }
+  if (disputes.length > 1)
+    throw new Error(
+      "Multiple monetary disputes require manual source allocation.",
+    );
+  const dispute = disputes[0];
+  return {
+    obligationId: row._id,
+    recoveredAmount,
+    restoredAmount,
+    receipts,
+    restorationIds,
+    note: opts.note,
+    exposure: {
+      kind: dispute ? ("dispute" as const) : ("refund" as const),
+      chargeAmount: charge.amount,
+      principal: dispute?.amount ?? refundedPrincipal,
+      finalized: dispute ? dispute.status === "lost" : true,
+      refundedPrincipal,
+      disputeId: dispute?.id,
+      disputeState: dispute
+        ? dispute.status === "won"
+          ? ("won" as const)
+          : dispute.status === "lost"
+            ? ("lost" as const)
+            : ("open" as const)
+        : undefined,
+    },
+  };
+}

package/src/client/affiliateRecovery/validators.ts

@@ -0,0 +1,38 @@
+import { v } from "convex/values";
+import { obligationFields } from "../../component/settlement/clawbackSchema.js";
+import {
+  balanceFields,
+  operationFields,
+} from "../../component/affiliateRecovery/schema.js";
+export const affiliateObligationValidator = v.object({
+  ...obligationFields,
+  _id: v.string(),
+  _creationTime: v.number(),
+  earningId: v.optional(v.string()),
+  activeOperationId: v.optional(v.string()),
+});
+export const affiliateOperationValidator = v.object({
+  ...operationFields,
+  _id: v.string(),
+  _creationTime: v.number(),
+  obligationId: v.string(),
+});
+export const affiliateSnapshotValidator = v.object({
+  balance: v.union(
+    v.object({ ...balanceFields, _id: v.string(), _creationTime: v.number() }),
+    v.null(),
+  ),
+  obligations: v.object({
+    page: v.array(affiliateObligationValidator),
+    continueCursor: v.string(),
+    isDone: v.boolean(),
+    splitCursor: v.optional(v.union(v.string(), v.null())),
+    pageStatus: v.optional(
+      v.union(
+        v.literal("SplitRecommended"),
+        v.literal("SplitRequired"),
+        v.null(),
+      ),
+    ),
+  }),
+});