@fantastic.dev/better-stripe 0.24.0 → 0.25.0

package/src/client/connect/payoutWorker.ts

@@ -0,0 +1,144 @@
+import type { Infer } from "convex/values";
+import type { jobDoc } from "../../component/payoutWorker/schema.js";
+import type { policyDoc } from "../../component/payoutPolicy/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import type {
+  PayoutReleaseOptions,
+  PayoutReleaseResult,
+} from "./payoutExecution.js";
+import type {
+  PayoutReconciliationOptions,
+  PayoutReconciliation,
+} from "./payoutReconciliation.js";
+export type PayoutWorkerJob = Infer<typeof jobDoc>;
+export type PayoutWorkerScope = {
+  accountId: string;
+  ownerKey: string;
+  currency: string;
+};
+export type PayoutWorkerOptions = Omit<PayoutReleaseOptions, "operationKey"> & {
+  cadenceMs?: number;
+};
+type PageOptions = { cursor: string | null; numItems: number };
+type Page<T> = { page: T[]; continueCursor: string; isDone: boolean };
+type Held = { status: "held"; reason: string; nextAttemptAt?: number };
+export type PayoutWorkerResult =
+  | Held
+  | { status: "completed"; job: PayoutWorkerJob; payout: PayoutReleaseResult };
+/** Host cron only. No method on this worker represents a customer withdrawal request. */
+export class PayoutWorkerClient {
+  constructor(
+    private readonly component: Component,
+    private readonly release: (
+      ctx: RunCtx,
+      opts: PayoutReleaseOptions,
+    ) => Promise<PayoutReleaseResult>,
+    private readonly reconcile: (
+      ctx: RunCtx,
+      opts: PayoutReconciliationOptions,
+    ) => Promise<PayoutReconciliation>,
+  ) {}
+  get(ctx: RunCtx, scope: PayoutWorkerScope): Promise<PayoutWorkerJob | null> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/get"),
+      {
+        accountId: scope.accountId,
+        ownerKey: scope.ownerKey,
+        currency: scope.currency,
+      },
+    );
+  }
+  policies(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<Infer<typeof policyDoc>>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/policies"),
+      { paginationOpts },
+    );
+  }
+  recovering(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<PayoutWorkerJob>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/recovering"),
+      { paginationOpts },
+    );
+  }
+  changing(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<Infer<typeof policyDoc>>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/changing"),
+      { paginationOpts },
+    );
+  }
+  async run(
+    ctx: RunCtx,
+    opts: PayoutWorkerOptions,
+  ): Promise<PayoutWorkerResult> {
+    if (
+      !Number.isSafeInteger(opts.independentLiabilities) ||
+      opts.independentLiabilities < 0 ||
+      (opts.maxPages !== undefined &&
+        (!Number.isInteger(opts.maxPages) ||
+          opts.maxPages < 1 ||
+          opts.maxPages > 100))
+    )
+      throw new Error("Invalid automatic payout liabilities or page budget.");
+    const scope = {
+      accountId: opts.accountId,
+      ownerKey: opts.ownerKey,
+      currency: opts.currency,
+    };
+    const started = (await runMutationOrThrow(
+      ctx,
+      componentRef(this.component, "payoutWorker/mutations/begin"),
+      {
+        ...scope,
+        cadenceMs: opts.cadenceMs ?? 300000,
+      },
+    )) as
+      Held | { status: "run"; job: PayoutWorkerJob; reconcileOnly: boolean };
+    if (started.status === "held") return started;
+    const operationKey = started.job.operationKey!;
+    const finish = (reason: string) =>
+      runMutationOrThrow(
+        ctx,
+        componentRef(this.component, "payoutWorker/mutations/finish"),
+        { ...scope, operationKey, generation: started.job.generation, reason },
+      ) as Promise<PayoutWorkerJob>;
+    let payout: PayoutReleaseResult;
+    try {
+      payout = started.reconcileOnly
+        ? await this.reconcile(ctx, {
+            ...scope,
+            operationKey,
+            maxPages: opts.maxPages,
+          })
+        : await this.release(ctx, {
+            ...scope,
+            operationKey,
+            independentLiabilities: opts.independentLiabilities,
+            maxPages: opts.maxPages,
+          });
+    } catch (error) {
+      try {
+        await finish("worker_error");
+      } catch (completionError) {
+        throw new AggregateError(
+          [error, completionError],
+          "Payout worker outcome requires reconciliation.",
+        );
+      }
+      throw error;
+    }
+    const reason =
+      payout.status === "held" ? payout.reason : payout.claim.status;
+    return { status: "completed", job: await finish(reason), payout };
+  }
+}

package/src/client/index.ts

@@ -1,5 +1,7 @@
 import { AffiliateRecoveryClient } from "./affiliateRecovery.js";
 export * from "./affiliateRecovery.js";
+import { CheckoutRequestClient } from "./checkoutRequests.js";
+export type { PreparedCheckoutSession } from "./billing/preparedCheckout.js";
 import * as payoutSyncImpl from "./connect/payoutSync.js";
 export type {
   PayoutSyncOptions,
@@ -680,6 +682,14 @@ export class BetterStripe extends ReadContractClient {
   }
 
   // CHECKOUT METHODS
+  get checkoutRequests() {
+    return new CheckoutRequestClient(
+      this.component,
+      () => this.stripe(),
+      (fee) => this.resolveFee(fee),
+      this._statementDescriptorSuffix,
+    );
+  }
 
   async createCheckoutSession(ctx: RunCtx, opts: CreateCheckoutSessionOptions) {
     const { fee, ...rest } = opts;
@@ -699,27 +709,6 @@ export class BetterStripe extends ReadContractClient {
     );
   }
 
-  async getCheckoutSession(
-    ctx: RunCtx,
-    opts: { sessionId: string },
-  ): Promise<StripeComponentCheckoutSession | null> {
-    return checkoutImpl.getCheckoutSession(this.component, ctx, opts);
-  }
-
-  async getCheckoutSessionByStripeId(
-    ctx: RunCtx,
-    opts: { stripeSessionId: string },
-  ): Promise<StripeComponentCheckoutSession | null> {
-    return checkoutImpl.getCheckoutSessionByStripeId(this.component, ctx, opts);
-  }
-
-  async listCheckoutSessionsByUser(
-    ctx: RunCtx,
-    opts: { userId: string; status?: string },
-  ): Promise<StripeComponentCheckoutSession[]> {
-    return checkoutImpl.listCheckoutSessionsByUser(this.component, ctx, opts);
-  }
-
   async upsertCheckoutSession(
     ctx: RunCtx,
     opts: {

package/src/client/payoutPolicy.ts

@@ -1,3 +1,12 @@
+import { PayoutWorkerClient } from "./connect/payoutWorker.js";
+export type * from "./connect/payoutWorker.js";
+import {
+  collectPayoutSnapshot,
+  discardPayoutSnapshot,
+  type PayoutCollectionOptions,
+  type PayoutCollectionScope,
+} from "./connect/payoutCollection.js";
+export type * from "./connect/payoutCollection.js";
 import { collectAdoptionProof } from "./connect/payoutActivationProof.js";
 import {
   adoptRecipientPayouts,
@@ -97,10 +106,26 @@ const toProvider = (
 });
 /** Host authenticates owner/policy/consent. Provider I/O stays in this package. */
 export class PayoutPolicyClient {
+  readonly worker: PayoutWorkerClient;
   constructor(
     private readonly component: Component,
     private readonly provider: () => Stripe,
-  ) {}
+  ) {
+    this.worker = new PayoutWorkerClient(
+      component,
+      (ctx, opts) => this.release(ctx, opts),
+      (ctx, opts) => this.reconcilePayout(ctx, opts),
+    );
+  }
+  collectSnapshot(ctx: RunCtx, opts: PayoutCollectionOptions) {
+    return collectPayoutSnapshot(this.component, ctx, opts);
+  }
+  discardSnapshot(
+    ctx: RunCtx,
+    opts: PayoutCollectionScope & { batchSize?: number },
+  ) {
+    return discardPayoutSnapshot(this.component, ctx, opts);
+  }
   adoptPayouts(ctx: RunCtx, opts: PayoutAdoptionOptions) {
     return adoptRecipientPayouts(this.provider(), this.component, ctx, opts);
   }

package/src/client/readContracts.ts

@@ -1,9 +1,11 @@
+import * as checkoutImpl from "./billing/checkout.js";
 import * as payoutsImpl from "./connect/payouts.js";
 import type { ComponentApi } from "../component/_generated/component.js";
 import type { PaginationOptions, PaginationResult } from "convex/server";
 import type { Component, RunCtx } from "./helpers.js";
 import type { PayoutStatus } from "../component/connect/validators.js";
 import type {
+  StripeComponentCheckoutSession,
   StripeComponentPayout,
   StripeComponentProduct,
   StripeComponentPrice,
@@ -52,6 +54,27 @@ export class ReadContractClient {
     );
   }
 
+  async getCheckoutSession(
+    ctx: RunCtx,
+    opts: { sessionId: string },
+  ): Promise<StripeComponentCheckoutSession | null> {
+    return checkoutImpl.getCheckoutSession(this.component, ctx, opts);
+  }
+
+  async getCheckoutSessionByStripeId(
+    ctx: RunCtx,
+    opts: { stripeSessionId: string },
+  ): Promise<StripeComponentCheckoutSession | null> {
+    return checkoutImpl.getCheckoutSessionByStripeId(this.component, ctx, opts);
+  }
+
+  async listCheckoutSessionsByUser(
+    ctx: RunCtx,
+    opts: { userId: string; status?: string },
+  ): Promise<StripeComponentCheckoutSession[]> {
+    return checkoutImpl.listCheckoutSessionsByUser(this.component, ctx, opts);
+  }
+
   async getPayout(ctx: RunCtx, opts: { payoutId: string }) {
     return payoutsImpl.getPayout(this.component, ctx, opts);
   }

package/src/component/_generated/api.ts

@@ -27,6 +27,7 @@ import type * as connect_reversalReceipts from "../connect/reversalReceipts.js";
 import type * as connect_validators from "../connect/validators.js";
 import type * as core_mutations from "../core/mutations.js";
 import type * as core_queries from "../core/queries.js";
+import type * as core_resetSafety from "../core/resetSafety.js";
 import type * as core_validators from "../core/validators.js";
 import type * as costRecovery_claims from "../costRecovery/claims.js";
 import type * as costRecovery_completion from "../costRecovery/completion.js";
@@ -56,10 +57,17 @@ 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 payoutSnapshots_localState from "../payoutSnapshots/localState.js";
+import type * as payoutSnapshots_mutations from "../payoutSnapshots/mutations.js";
+import type * as payoutSnapshots_revisions from "../payoutSnapshots/revisions.js";
+import type * as payoutSnapshots_scope from "../payoutSnapshots/scope.js";
 import type * as payoutSync_helpers from "../payoutSync/helpers.js";
 import type * as payoutSync_mutations from "../payoutSync/mutations.js";
 import type * as payoutSync_queries from "../payoutSync/queries.js";
 import type * as payoutSync_validators from "../payoutSync/validators.js";
+import type * as payoutWorker_helpers from "../payoutWorker/helpers.js";
+import type * as payoutWorker_mutations from "../payoutWorker/mutations.js";
+import type * as payoutWorker_queries from "../payoutWorker/queries.js";
 import type * as products_mutations from "../products/mutations.js";
 import type * as products_queries from "../products/queries.js";
 import type * as products_validators from "../products/validators.js";
@@ -99,6 +107,7 @@ const fullApi: ApiFromModules<{
   "connect/validators": typeof connect_validators;
   "core/mutations": typeof core_mutations;
   "core/queries": typeof core_queries;
+  "core/resetSafety": typeof core_resetSafety;
   "core/validators": typeof core_validators;
   "costRecovery/claims": typeof costRecovery_claims;
   "costRecovery/completion": typeof costRecovery_completion;
@@ -128,10 +137,17 @@ const fullApi: ApiFromModules<{
   "payoutRelease/mutations": typeof payoutRelease_mutations;
   "payoutRelease/observation": typeof payoutRelease_observation;
   "payoutRelease/queries": typeof payoutRelease_queries;
+  "payoutSnapshots/localState": typeof payoutSnapshots_localState;
+  "payoutSnapshots/mutations": typeof payoutSnapshots_mutations;
+  "payoutSnapshots/revisions": typeof payoutSnapshots_revisions;
+  "payoutSnapshots/scope": typeof payoutSnapshots_scope;
   "payoutSync/helpers": typeof payoutSync_helpers;
   "payoutSync/mutations": typeof payoutSync_mutations;
   "payoutSync/queries": typeof payoutSync_queries;
   "payoutSync/validators": typeof payoutSync_validators;
+  "payoutWorker/helpers": typeof payoutWorker_helpers;
+  "payoutWorker/mutations": typeof payoutWorker_mutations;
+  "payoutWorker/queries": typeof payoutWorker_queries;
   "products/mutations": typeof products_mutations;
   "products/queries": typeof products_queries;
   "products/validators": typeof products_validators;

package/src/component/_generated/component.ts

@@ -3683,6 +3683,161 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    payoutSnapshots: {
+      mutations: {
+        advance: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            batchSize?: number;
+            expectedStep: number;
+            operationKey: string;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            allocationCount: number;
+            allocationCursor?: string;
+            claimCount: number;
+            claimCursor?: string;
+            deferredPositiveChanges: boolean;
+            expectedRevision: number;
+            expiresAt: number;
+            feeCount: number;
+            feeCursor?: string;
+            initialRevision: number;
+            initialRiskRevision: number;
+            observedRevision: number;
+            operationKey: string;
+            ownerKey: string;
+            phase:
+              | "sources"
+              | "allocations"
+              | "fees"
+              | "claims"
+              | "repair"
+              | "check"
+              | "local_ready"
+              | "invalidated"
+              | "discarding";
+            policyMode?: string;
+            policyOperationKey?: string;
+            providerChanged: boolean;
+            readOnly: boolean;
+            reason?: string;
+            riskRevision: number;
+            sourceCount: number;
+            sourceCursor?: string;
+            sourceFence: number;
+            step: number;
+          },
+          Name
+        >;
+        begin: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            expectedRevision: number;
+            operationKey: string;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            allocationCount: number;
+            allocationCursor?: string;
+            claimCount: number;
+            claimCursor?: string;
+            deferredPositiveChanges: boolean;
+            expectedRevision: number;
+            expiresAt: number;
+            feeCount: number;
+            feeCursor?: string;
+            initialRevision: number;
+            initialRiskRevision: number;
+            observedRevision: number;
+            operationKey: string;
+            ownerKey: string;
+            phase:
+              | "sources"
+              | "allocations"
+              | "fees"
+              | "claims"
+              | "repair"
+              | "check"
+              | "local_ready"
+              | "invalidated"
+              | "discarding";
+            policyMode?: string;
+            policyOperationKey?: string;
+            providerChanged: boolean;
+            readOnly: boolean;
+            reason?: string;
+            riskRevision: number;
+            sourceCount: number;
+            sourceCursor?: string;
+            sourceFence: number;
+            step: number;
+          },
+          Name
+        >;
+        discard: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            batchSize?: number;
+            operationKey: string;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            allocationCount: number;
+            allocationCursor?: string;
+            claimCount: number;
+            claimCursor?: string;
+            deferredPositiveChanges: boolean;
+            expectedRevision: number;
+            expiresAt: number;
+            feeCount: number;
+            feeCursor?: string;
+            initialRevision: number;
+            initialRiskRevision: number;
+            observedRevision: number;
+            operationKey: string;
+            ownerKey: string;
+            phase:
+              | "sources"
+              | "allocations"
+              | "fees"
+              | "claims"
+              | "repair"
+              | "check"
+              | "local_ready"
+              | "invalidated"
+              | "discarding";
+            policyMode?: string;
+            policyOperationKey?: string;
+            providerChanged: boolean;
+            readOnly: boolean;
+            reason?: string;
+            riskRevision: number;
+            sourceCount: number;
+            sourceCursor?: string;
+            sourceFence: number;
+            step: number;
+          } | null,
+          Name
+        >;
+      };
+    };
     payoutSync: {
       mutations: {
         begin: FunctionReference<
@@ -3765,6 +3920,212 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    payoutWorker: {
+      mutations: {
+        begin: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            cadenceMs: number;
+            currency: string;
+            ownerKey: string;
+          },
+          | { nextAttemptAt?: number; reason: string; status: "held" }
+          | {
+              job: {
+                _creationTime: number;
+                _id: string;
+                accountId: string;
+                cadenceMs: number;
+                completedGeneration?: number;
+                completedOperationKey?: string;
+                currency: string;
+                generation: number;
+                hasOperation: boolean;
+                lastAttemptAt?: number;
+                lastReason?: string;
+                leaseUntil?: number;
+                nextAttemptAt: number;
+                operationKey?: string;
+                ownerKey: string;
+                sequence: number;
+              };
+              reconcileOnly: boolean;
+              status: "run";
+            },
+          Name
+        >;
+        finish: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            currency: string;
+            generation: number;
+            operationKey: string;
+            ownerKey: string;
+            reason: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            cadenceMs: number;
+            completedGeneration?: number;
+            completedOperationKey?: string;
+            currency: string;
+            generation: number;
+            hasOperation: boolean;
+            lastAttemptAt?: number;
+            lastReason?: string;
+            leaseUntil?: number;
+            nextAttemptAt: number;
+            operationKey?: string;
+            ownerKey: string;
+            sequence: number;
+          },
+          Name
+        >;
+      };
+      queries: {
+        changing: FunctionReference<
+          "query",
+          "internal",
+          {
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId: string;
+              country: string;
+              holdDeadline?: number;
+              mode: "stripe_managed" | "custom";
+              operationKey: string;
+              ownerKey: string;
+              previousSchedule?: {
+                interval: "daily" | "weekly" | "monthly" | "manual";
+                monthlyDays?: Array<number>;
+                weeklyDays?: Array<string>;
+              };
+              revision: number;
+              status: "changing" | "ready";
+              thresholds: Array<{ amount: number; currency: string }>;
+            }>;
+          },
+          Name
+        >;
+        get: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; currency: string; ownerKey: string },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            cadenceMs: number;
+            completedGeneration?: number;
+            completedOperationKey?: string;
+            currency: string;
+            generation: number;
+            hasOperation: boolean;
+            lastAttemptAt?: number;
+            lastReason?: string;
+            leaseUntil?: number;
+            nextAttemptAt: number;
+            operationKey?: string;
+            ownerKey: string;
+            sequence: number;
+          } | null,
+          Name
+        >;
+        policies: FunctionReference<
+          "query",
+          "internal",
+          {
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId: string;
+              country: string;
+              holdDeadline?: number;
+              mode: "stripe_managed" | "custom";
+              operationKey: string;
+              ownerKey: string;
+              previousSchedule?: {
+                interval: "daily" | "weekly" | "monthly" | "manual";
+                monthlyDays?: Array<number>;
+                weeklyDays?: Array<string>;
+              };
+              revision: number;
+              status: "changing" | "ready";
+              thresholds: Array<{ amount: number; currency: string }>;
+            }>;
+          },
+          Name
+        >;
+        recovering: FunctionReference<
+          "query",
+          "internal",
+          {
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId: string;
+              cadenceMs: number;
+              completedGeneration?: number;
+              completedOperationKey?: string;
+              currency: string;
+              generation: number;
+              hasOperation: boolean;
+              lastAttemptAt?: number;
+              lastReason?: string;
+              leaseUntil?: number;
+              nextAttemptAt: number;
+              operationKey?: string;
+              ownerKey: string;
+              sequence: number;
+            }>;
+          },
+          Name
+        >;
+      };
+    };
     products: {
       mutations: {
         upsertPrice: FunctionReference<