@fantastic.dev/better-stripe 0.22.0 → 0.23.1

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;

package/src/component/_generated/component.ts

@@ -2199,11 +2199,41 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         beginAttempt: FunctionReference<
           "mutation",
           "internal",
-          { accountId: string; operationKey: string; ownerKey: string },
+          {
+            accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
+            operationKey: string;
+            ownerKey: string;
+          },
           {
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2249,6 +2279,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2294,6 +2337,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2327,6 +2383,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           "internal",
           {
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             country: string;
             expectedRevision: number;
             mode: "stripe_managed" | "custom";
@@ -2344,6 +2413,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2444,6 +2526,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2476,6 +2571,94 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
     };
     payoutRelease: {
       mutations: {
+        adoptHistoricalBatch: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            expectedClaims: Array<{
+              fingerprint: string;
+              operationKey: string;
+            }>;
+            expectedRevision: number;
+            observations: Array<{
+              currency: string;
+              ledgerFingerprint: string;
+              matureNet: number;
+              observedAt: number;
+              pendingCredits: number;
+              stripeTransferId: string;
+              transactionIds: Array<string>;
+            }>;
+            ownerKey: string;
+            payouts: Array<{
+              allocations: Array<{
+                amount: number;
+                role?: "store" | "affiliate" | "other";
+                stripeTransferId: string;
+              }>;
+              payout: {
+                amount: number;
+                created: number;
+                currency: string;
+                debitFee: number;
+                debitTransactionId: string;
+                destinationId: string;
+                returnFee?: number;
+                returnTransactionId?: string;
+                status: "paid" | "returned";
+                stripePayoutId: string;
+              };
+            }>;
+          },
+          {
+            claims: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId: string;
+              allocations: Array<{
+                amount: number;
+                role?: "store" | "affiliate" | "other";
+                stripeTransferId: string;
+              }>;
+              amount: number;
+              attemptedAt?: number;
+              currency: string;
+              debitFee?: number;
+              debitTransactionId?: string;
+              destinationId?: string;
+              expectedRevision: number;
+              feeRevision?: number;
+              historical?: boolean;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              operationKey: string;
+              ownerKey: string;
+              providerFee?: number;
+              rejection?: {
+                code: "balance_insufficient" | "amount_too_small";
+                requestId: string;
+              };
+              returnTransactionId?: string;
+              status:
+                | "reserved"
+                | "submitted"
+                | "paid"
+                | "returned"
+                | "canceled"
+                | "rejected";
+              stripePayoutId?: string;
+            }>;
+          },
+          Name
+        >;
         beginAttempt: FunctionReference<
           "mutation",
           "internal",
@@ -2497,6 +2680,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2546,6 +2730,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2613,6 +2798,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               destinationId?: string;
               expectedRevision: number;
               feeRevision?: number;
+              historical?: boolean;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2685,6 +2871,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2740,6 +2927,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2798,6 +2986,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2861,6 +3050,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               destinationId?: string;
               expectedRevision: number;
               feeRevision?: number;
+              historical?: boolean;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2913,6 +3103,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 destinationId?: string;
                 expectedRevision: number;
                 feeRevision?: number;
+                historical?: boolean;
                 observations: Array<{
                   currency: string;
                   ledgerFingerprint: string;