@fantastic.dev/better-stripe 0.21.0 → 0.23.0

package/src/client/payoutPolicy.ts

@@ -1,3 +1,14 @@
+import { collectAdoptionProof } from "./connect/payoutActivationProof.js";
+import {
+  adoptRecipientPayouts,
+  type PayoutAdoptionOptions,
+} from "./connect/payoutAdoption.js";
+export type * from "./connect/payoutAdoption.js";
+import {
+  releaseRecipientPayout,
+  type PayoutReleaseOptions,
+} from "./connect/payoutExecution.js";
+export type * from "./connect/payoutExecution.js";
 import {
   reconcileRecipientPayout,
   type PayoutReconciliationOptions,
@@ -27,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>;
@@ -37,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";
@@ -85,6 +101,18 @@ 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(),
+      this.component,
+      ctx,
+      opts,
+      () => this.verify(ctx, opts),
+    );
+  }
   reconcilePayout(ctx: RunCtx, opts: PayoutReconciliationOptions) {
     return reconcileRecipientPayout(this.provider(), this.component, ctx, opts);
   }
@@ -198,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. */
@@ -236,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 };
@@ -252,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,
@@ -274,6 +346,7 @@ export class PayoutPolicyClient {
         country: controls.country,
         observedSchedule: controls.schedule,
         observedAt,
+        ...(adoption ? { adoption } : {}),
       },
     )) as PayoutPolicyOperation;
     return { status: "prepared", operation };
@@ -288,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 };
@@ -320,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" };
@@ -328,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,
@@ -344,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",
@@ -2494,8 +2677,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2542,8 +2727,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2578,6 +2765,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           {
             accountId: string;
             currency: string;
+            destinationId?: string;
             expectedRevision: number;
             independentLiabilities: number;
             observations: Array<{
@@ -2607,8 +2795,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               currency: string;
               debitFee?: number;
               debitTransactionId?: string;
+              destinationId?: string;
               expectedRevision: number;
               feeRevision?: number;
+              historical?: boolean;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2678,8 +2868,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2732,8 +2924,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2789,8 +2983,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2851,8 +3047,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               currency: string;
               debitFee?: number;
               debitTransactionId?: string;
+              destinationId?: string;
               expectedRevision: number;
               feeRevision?: number;
+              historical?: boolean;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2882,6 +3080,79 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        snapshot: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; ownerKey: string },
+          | { reason: "snapshot_limit"; status: "held" }
+          | {
+              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;
+              }>;
+              status: "ready";
+              transfers: Array<{
+                _creationTime: number;
+                _id: string;
+                amount: number;
+                currency: string;
+                destinationAccountId: string;
+                metadata?: any;
+                paymentId?: string;
+                reinstatement?: boolean;
+                reversalClaimedAmount?: number;
+                reversalStatus?: "partially_reversed" | "fully_reversed";
+                reversedAmount?: number;
+                role?: "store" | "affiliate" | "other";
+                sourceChargeId?: string;
+                sourceInvoiceId?: string;
+                status: "pending" | "paid" | "failed" | "reversed";
+                stripeTransferId: string;
+                totalsRecorded?: true;
+              }>;
+            },
+          Name
+        >;
       };
     };
     products: {