@fantastic.dev/better-stripe 0.22.0 → 0.23.0

package/src/client/connect/payoutAdoptionAllocation.ts

@@ -0,0 +1,106 @@
+import { addSummaryAmounts as add } from "../../component/earnings/arithmetic.js";
+export type HistoricalFundingSource = {
+  stripeTransferId: string;
+  currency: string;
+  transactions: {
+    net: number;
+    created: number;
+    availableOn: number;
+    status: string;
+  }[];
+};
+export type HistoricalFundingPayout = {
+  stripePayoutId: string;
+  currency: string;
+  amount: number;
+  created: number;
+  returnedAt?: number;
+  allocations: { stripeTransferId: string; amount: number }[];
+};
+function integer(n: number) {
+  if (!Number.isSafeInteger(n))
+    throw new Error("Invalid historical funding arithmetic.");
+  return n;
+}
+function timestamp(n: number) {
+  if (integer(n) < 0) throw new Error("Invalid historical funding timestamp.");
+}
+/** Validate explicit historical cash provenance, not today's still-unpaid entitlement. */
+export function validateHistoricalFunding(
+  sources: HistoricalFundingSource[],
+  payouts: HistoricalFundingPayout[],
+): void {
+  const byId = new Map<string, HistoricalFundingSource>();
+  for (const s of sources) {
+    if (byId.has(s.stripeTransferId))
+      throw new Error("Duplicate historical funding source.");
+    if (!/^tr_\w+$/.test(s.stripeTransferId) || !/^[a-z]{3}$/.test(s.currency))
+      throw new Error("Invalid historical funding source.");
+    for (const t of s.transactions) {
+      integer(t.net);
+      timestamp(t.created);
+      timestamp(t.availableOn);
+      if (!["available", "pending"].includes(t.status))
+        throw new Error("Invalid historical funding status.");
+    }
+    byId.set(s.stripeTransferId, s);
+  }
+  const ids = new Set<string>();
+  for (const p of payouts) {
+    if (ids.has(p.stripePayoutId))
+      throw new Error("Duplicate historical payout.");
+    ids.add(p.stripePayoutId);
+    if (
+      !/^po_\w+$/.test(p.stripePayoutId) ||
+      !/^[a-z]{3}$/.test(p.currency) ||
+      integer(p.amount) <= 0
+    )
+      throw new Error("Invalid historical payout principal.");
+    timestamp(p.created);
+    if (p.returnedAt !== undefined) {
+      timestamp(p.returnedAt);
+      if (p.returnedAt < p.created)
+        throw new Error("Historical payout return predates the payout.");
+    }
+  }
+  const prior: HistoricalFundingPayout[] = [];
+  for (const p of [...payouts].sort(
+    (a, b) =>
+      a.created - b.created || a.stripePayoutId.localeCompare(b.stripePayoutId),
+  )) {
+    const seen = new Set<string>();
+    let principal = 0;
+    for (const a of p.allocations) {
+      if (seen.has(a.stripeTransferId))
+        throw new Error("Duplicate historical source allocation.");
+      seen.add(a.stripeTransferId);
+      if (integer(a.amount) <= 0)
+        throw new Error("Invalid historical principal allocation.");
+      principal = add(principal, a.amount);
+      const s = byId.get(a.stripeTransferId);
+      if (!s)
+        throw new Error("Historical payout funding source is unavailable.");
+      if (s.currency !== p.currency)
+        throw new Error("Historical payout currency allocation mismatch.");
+      let capacity = 0;
+      for (const t of s.transactions)
+        if (
+          t.status === "available" &&
+          Math.max(t.created, t.availableOn) <= p.created
+        )
+          capacity = add(capacity, t.net);
+      for (const old of prior)
+        if (old.returnedAt === undefined || old.returnedAt > p.created)
+          for (const allocation of old.allocations)
+            if (allocation.stripeTransferId === s.stripeTransferId)
+              capacity = add(capacity, -allocation.amount);
+      if (a.amount > capacity)
+        throw new Error(
+          "Historical payout exceeds verified mature source funding.",
+        );
+    }
+    if (principal !== p.amount)
+      throw new Error("Historical allocations do not equal payout principal.");
+    prior.push(p);
+  }
+}

package/src/client/connect/payoutReconciliation.test.ts

@@ -396,3 +396,19 @@ it("rejects a payout sent to a different bank than the immutable claim", async (
     await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
   ).toMatchObject([{ paidAmount: 0, reservedAmount: 1000 }]);
 });
+it("reconciles an explicitly adopted automatic payout without a package claim marker", async () => {
+  const s = await setup();
+  await s.t.run(async (ctx) => {
+    const c = await ctx.db.query("payoutReleaseClaims").first();
+    await ctx.db.patch("payoutReleaseClaims", c!._id, {
+      historical: true,
+      stripePayoutId: "po_one",
+      destinationId: "ba_one",
+    });
+  });
+  s.setPayout({ automatic: true, metadata: {} as never });
+  expect(await s.reconcile()).toMatchObject({
+    status: "updated",
+    claim: { status: "paid", historical: true },
+  });
+});

package/src/client/connect/payoutReconciliation.ts

@@ -132,7 +132,7 @@ export async function reconcileRecipientPayout(
   const receipt = await getRecipientPayoutReceipt(stripe, {
     accountId: options.accountId,
     stripePayoutId: payoutId,
-    operationKey: options.operationKey,
+    ...(claim.historical ? {} : { operationKey: options.operationKey }),
   });
   if (receipt.status !== "ready")
     return { status: "held", reason: receipt.reason };
@@ -151,7 +151,11 @@ export async function reconcileRecipientPayout(
     );
   // Current claims use the default card source balance. Other rails need a
   // persisted allocation contract before a provider receipt can be adopted.
-  if (receipt.sourceType !== "card")
+  if (
+    receipt.sourceType !== "card" ||
+    (claim.historical &&
+      (receipt.method !== "standard" || receipt.type !== "bank_account"))
+  )
     return { status: "held", reason: "source_allocation_required" };
   const fee = addSummaryAmounts(receipt.debit.fee, receipt.credit?.fee ?? 0);
   if (fee < 0) return { status: "held", reason: "fee_allocation_required" };

package/src/client/payoutPolicy.test.ts

@@ -318,3 +318,19 @@ it("rechecks delayed activation and cancels safely when funds arrive after prepa
     status: "ready",
   });
 });
+it("requires adoption for historical payouts even when today's balance is zero", async () => {
+  const { client, ctx, provider } = await setup();
+  provider.payouts.list.mockImplementation(
+    async (params?: { status?: string }) =>
+      ({
+        data: params?.status ? [] : [{ id: "po_old" }],
+        has_more: false,
+      }) as never,
+  );
+  expect(await client.prepare(ctx, options)).toMatchObject({
+    status: "migration_required",
+    reason: "existing_payout_history",
+  });
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+  expect(await client.get(ctx, scope)).toBeNull();
+});

package/src/client/payoutPolicy.ts

@@ -1,3 +1,9 @@
+import { collectAdoptionProof } from "./connect/payoutActivationProof.js";
+import {
+  adoptRecipientPayouts,
+  type PayoutAdoptionOptions,
+} from "./connect/payoutAdoption.js";
+export type * from "./connect/payoutAdoption.js";
 import {
   releaseRecipientPayout,
   type PayoutReleaseOptions,
@@ -32,6 +38,7 @@ import {
   canonicalSchedule,
   canonicalThresholds,
   validateScope,
+  holdingDays,
 } from "../component/payoutPolicy/helpers.js";
 export type PayoutPolicy = Infer<typeof policyDoc>;
 export type PayoutPolicyOperation = Infer<typeof operationDoc>;
@@ -42,14 +49,18 @@ export type PayoutPolicyOptions = PayoutPolicyScope & {
   mode: PayoutPolicy["mode"];
   thresholds: PayoutPolicy["thresholds"];
   consent?: true;
+  /** Explicit funded-account adoption; historical payout mappings must already be imported. */
+  adoptExistingBalance?: true;
 };
 export type PayoutPolicyLimitation = {
   status: "unsupported" | "migration_required";
+  adoptionReason?: string;
   reason:
     | "provider_permission_denied"
     | "payout_control_unverified"
     | "country_unavailable"
     | "payouts_unavailable"
+    | "existing_payout_history"
     | "existing_balance"
     | "in_flight_payouts"
     | "existing_manual_schedule";
@@ -90,6 +101,9 @@ export class PayoutPolicyClient {
     private readonly component: Component,
     private readonly provider: () => Stripe,
   ) {}
+  adoptPayouts(ctx: RunCtx, opts: PayoutAdoptionOptions) {
+    return adoptRecipientPayouts(this.provider(), this.component, ctx, opts);
+  }
   release(ctx: RunCtx, opts: PayoutReleaseOptions) {
     return releaseRecipientPayout(
       this.provider(),
@@ -212,6 +226,15 @@ export class PayoutPolicyClient {
       if (payouts.has_more || payouts.data.length)
         return { status: "migration_required", reason: "in_flight_payouts" };
     }
+    const history = await stripe.payouts.list(
+      { limit: 1 },
+      { stripeAccount: scope.accountId },
+    );
+    if (history.has_more || history.data.length)
+      return {
+        status: "migration_required",
+        reason: "existing_payout_history",
+      };
     return null;
   }
   /** Persist restoration intent first. Existing mixed funds require explicit adoption; never infer ownership. */
@@ -250,7 +273,8 @@ export class PayoutPolicyClient {
       if (
         prior.mode !== opts.mode ||
         prior.expectedRevision !== opts.expectedRevision ||
-        !equal(prior.thresholds, thresholds)
+        !equal(prior.thresholds, thresholds) ||
+        Boolean(prior.adoption) !== Boolean(opts.adoptExistingBalance)
       )
         throw new Error("Payout policy operation identity cannot be reused.");
       return { status: "prepared", operation: prior };
@@ -266,14 +290,48 @@ export class PayoutPolicyClient {
       policy?.country,
     );
     if ("status" in controls) return controls;
+    let adoption: PayoutPolicyOperation["adoption"];
+    if (
+      opts.adoptExistingBalance &&
+      (opts.mode !== "custom" || policy?.mode !== "stripe_managed")
+    )
+      throw new Error("Funded adoption requires an owned automatic policy.");
     if (opts.mode === "custom" && policy?.mode !== "custom") {
       if (controls.schedule.interval === "manual")
         return {
           status: "migration_required",
           reason: "existing_manual_schedule",
         };
-      const migration = await this.migrationPreflight(opts);
-      if (migration) return migration;
+      if (opts.adoptExistingBalance) {
+        const proof = await collectAdoptionProof(
+          this.provider(),
+          this.component,
+          ctx,
+          opts,
+          policy!.revision,
+          thresholds.map((t) => t.currency),
+        );
+        if (proof.status !== "verified")
+          return {
+            status: "migration_required",
+            reason: "existing_balance",
+            adoptionReason: proof.reason,
+          };
+        adoption = proof.proof;
+        if (
+          adoption.oldestHeldAt !== undefined &&
+          adoption.oldestHeldAt + holdingDays(controls.country) * 86400000 <=
+            Date.now()
+        )
+          return {
+            status: "migration_required",
+            reason: "existing_balance",
+            adoptionReason: "holding_deadline_expired",
+          };
+      } else {
+        const migration = await this.migrationPreflight(opts);
+        if (migration) return migration;
+      }
     }
     const operation = (await runMutationOrThrow(
       ctx,
@@ -288,6 +346,7 @@ export class PayoutPolicyClient {
         country: controls.country,
         observedSchedule: controls.schedule,
         observedAt,
+        ...(adoption ? { adoption } : {}),
       },
     )) as PayoutPolicyOperation;
     return { status: "prepared", operation };
@@ -302,6 +361,11 @@ export class PayoutPolicyClient {
     | { status: "canceled"; operation: PayoutPolicyOperation }
     | PayoutPolicyLimitation
   > {
+    args = {
+      accountId: args.accountId,
+      ownerKey: args.ownerKey,
+      operationKey: args.operationKey,
+    };
     const operation = await this.operation(ctx, args);
     if (!operation) throw new Error("Payout policy operation is unavailable.");
     if (operation.status === "complete") return { status: "ready", operation };
@@ -334,6 +398,13 @@ export class PayoutPolicyClient {
     if ("status" in controls) return controls;
     if (operation.mode === "custom" && controls.country !== operation.country)
       return { status: "schedule_drift" };
+    if (
+      operation.adoption &&
+      !operation.attempted &&
+      equal(controls.schedule, operation.targetSchedule)
+    )
+      return { status: "schedule_drift" };
+    let freshAdoption: PayoutPolicyOperation["adoption"];
     if (!equal(controls.schedule, operation.targetSchedule)) {
       if (!equal(controls.schedule, operation.observedSchedule))
         return { status: "schedule_drift" };
@@ -342,7 +413,38 @@ export class PayoutPolicyClient {
         !operation.attempted &&
         policy?.mode === "stripe_managed"
       ) {
-        const migration = await this.migrationPreflight(args);
+        const result = operation.adoption
+          ? await collectAdoptionProof(
+              this.provider(),
+              this.component,
+              ctx,
+              args,
+              policy.revision,
+              operation.thresholds.map((t) => t.currency),
+            )
+          : null;
+        if (result?.status === "verified") freshAdoption = result.proof;
+        const ageExpired =
+          result?.status === "verified" &&
+          result.proof.oldestHeldAt !== undefined &&
+          result.proof.oldestHeldAt +
+            holdingDays(operation.country) * 86400000 <=
+            Date.now();
+        const migration: PayoutPolicyLimitation | null = ageExpired
+          ? {
+              status: "migration_required",
+              reason: "existing_balance",
+              adoptionReason: "holding_deadline_expired",
+            }
+          : result?.status === "held"
+            ? {
+                status: "migration_required",
+                reason: "existing_balance",
+                adoptionReason: result.reason,
+              }
+            : result
+              ? null
+              : await this.migrationPreflight(args);
         if (migration) {
           await runMutationOrThrow(
             ctx,
@@ -358,7 +460,7 @@ export class PayoutPolicyClient {
       await runMutationOrThrow(
         ctx,
         componentRef(this.component, "payoutPolicy/mutations/beginAttempt"),
-        args,
+        { ...args, ...(freshAdoption ? { adoption: freshAdoption } : {}) },
       );
       try {
         await this.provider().balanceSettings.update(

package/src/component/_generated/api.ts

@@ -34,13 +34,16 @@ import type * as lib_idempotency from "../lib/idempotency.js";
 import type * as lib_paymentSeller from "../lib/paymentSeller.js";
 import type * as lib_reversals from "../lib/reversals.js";
 import type * as lib_stripeFactory from "../lib/stripeFactory.js";
+import type * as payoutPolicy_adoption from "../payoutPolicy/adoption.js";
 import type * as payoutPolicy_helpers from "../payoutPolicy/helpers.js";
 import type * as payoutPolicy_mutations from "../payoutPolicy/mutations.js";
 import type * as payoutPolicy_queries from "../payoutPolicy/queries.js";
+import type * as payoutRelease_adoption from "../payoutRelease/adoption.js";
 import type * as payoutRelease_allocation from "../payoutRelease/allocation.js";
 import type * as payoutRelease_fees from "../payoutRelease/fees.js";
 import type * as payoutRelease_helpers from "../payoutRelease/helpers.js";
 import type * as payoutRelease_mutations from "../payoutRelease/mutations.js";
+import type * as payoutRelease_observation from "../payoutRelease/observation.js";
 import type * as payoutRelease_queries from "../payoutRelease/queries.js";
 import type * as products_mutations from "../products/mutations.js";
 import type * as products_queries from "../products/queries.js";
@@ -86,13 +89,16 @@ const fullApi: ApiFromModules<{
   "lib/paymentSeller": typeof lib_paymentSeller;
   "lib/reversals": typeof lib_reversals;
   "lib/stripeFactory": typeof lib_stripeFactory;
+  "payoutPolicy/adoption": typeof payoutPolicy_adoption;
   "payoutPolicy/helpers": typeof payoutPolicy_helpers;
   "payoutPolicy/mutations": typeof payoutPolicy_mutations;
   "payoutPolicy/queries": typeof payoutPolicy_queries;
+  "payoutRelease/adoption": typeof payoutRelease_adoption;
   "payoutRelease/allocation": typeof payoutRelease_allocation;
   "payoutRelease/fees": typeof payoutRelease_fees;
   "payoutRelease/helpers": typeof payoutRelease_helpers;
   "payoutRelease/mutations": typeof payoutRelease_mutations;
+  "payoutRelease/observation": typeof payoutRelease_observation;
   "payoutRelease/queries": typeof payoutRelease_queries;
   "products/mutations": typeof products_mutations;
   "products/queries": typeof products_queries;