@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/dist/client/affiliateRecovery.d.ts

@@ -0,0 +1,131 @@
+import type Stripe from "stripe";
+import type { PaginationOptions } from "convex/server";
+import type { Component, RunCtx } from "./helpers.js";
+import type { RecoveryObligation, RecoveryOperation } from "./affiliateRecovery/provider.js";
+import type { Doc } from "../component/_generated/dataModel.js";
+export type AffiliateRecoveryObligation = RecoveryObligation;
+export type AffiliateRecoveryOperation = RecoveryOperation;
+export type AffiliateRecoveryBalance = Doc<"affiliateRecoveryBalances">;
+export type AffiliateRecoverySnapshot = {
+    balance: AffiliateRecoveryBalance | null;
+    obligations: {
+        page: RecoveryObligation[];
+        continueCursor: string;
+        isDone: boolean;
+    };
+};
+/** Server API. Host must authorize account ownership and operator retries. */
+export declare class AffiliateRecoveryClient {
+    private readonly component;
+    private readonly provider;
+    constructor(component: Component, provider: () => Stripe);
+    snapshot(ctx: RunCtx, opts: {
+        affiliateAccountId: string;
+        currency: string;
+        paginationOpts: PaginationOptions;
+    }): Promise<AffiliateRecoverySnapshot>;
+    obligation(ctx: RunCtx, opts: {
+        obligationId: string;
+    }): Promise<RecoveryObligation | null>;
+    history(ctx: RunCtx, opts: {
+        obligationId: string;
+        paginationOpts: PaginationOptions;
+    }): Promise<{
+        page: RecoveryOperation[];
+        continueCursor: string;
+        isDone: boolean;
+    }>;
+    reviewLegacy(ctx: RunCtx, opts: {
+        obligationId: string;
+        reversalIds: string[];
+        restorationTransferIds?: string[];
+        note: string;
+    }): Promise<{
+        _creationTime: number;
+        _id: import("convex/values").GenericId<"affiliateObligations">;
+        accounted?: boolean | undefined;
+        activeOperationId?: import("convex/values").GenericId<"affiliateRecoveryOperations"> | undefined;
+        affiliateAccountId: string;
+        chargeAmount: number;
+        creditAmount?: number | undefined;
+        currency: string;
+        debtAmount?: number | undefined;
+        debtStatus?: "open" | "settled" | undefined;
+        disputeId?: string | undefined;
+        disputeState?: "lost" | "open" | "won" | undefined;
+        disputedPrincipal: number;
+        earningId?: import("convex/values").GenericId<"affiliateEarnings"> | undefined;
+        finalizedAmount: number;
+        lastError?: string | undefined;
+        lastRefundId?: string | undefined;
+        lastState?: string | undefined;
+        legacyReceiptIds?: string[] | undefined;
+        legacyRestorationIds?: string[] | undefined;
+        lostPrincipal: number;
+        needsReconciliation: boolean;
+        offsetAmount?: number | undefined;
+        operationSequence?: number | undefined;
+        operatorNote?: string | undefined;
+        originalCommission: number;
+        paymentId?: string | undefined;
+        paymentIntentId?: string | undefined;
+        provisionalAmount: number;
+        recoveredAmount: number;
+        refundedPrincipal: number;
+        releasedCommission?: number | undefined;
+        reservedRecovery?: number | undefined;
+        reservedRestoration?: number | undefined;
+        restoredAmount?: number | undefined;
+        sourceChargeId: string;
+        sourceInvoiceId?: string | undefined;
+        storeAccountId?: string | undefined;
+        stripeTransferId?: string | undefined;
+    } | null>;
+    retry(ctx: RunCtx, opts: {
+        obligationId: string;
+    }): Promise<{
+        state: string;
+        reason: string;
+        error?: undefined;
+    } | {
+        reason?: undefined;
+        state: string;
+        error: string;
+    } | {
+        reason?: undefined;
+        error?: undefined;
+        state: string;
+    }>;
+    reconcilePayouts(ctx: RunCtx, opts: {
+        paginationOpts: PaginationOptions;
+        state: "pending" | "unknown";
+    }): Promise<{
+        page: Doc<"affiliatePayoutReleases">[];
+        continueCursor: string;
+        isDone: boolean;
+    }>;
+    /** Run from a host cron for both pending and unknown outcomes. */
+    reconcilePending(ctx: RunCtx, opts: {
+        paginationOpts: PaginationOptions;
+        state: "pending" | "unknown";
+    }): Promise<{
+        page: RecoveryOperation[];
+        continueCursor: string;
+        isDone: boolean;
+        results: ({
+            state: string;
+            reason: string;
+            error?: undefined;
+        } | {
+            reason?: undefined;
+            state: string;
+            error: string;
+        } | {
+            reason?: undefined;
+            error?: undefined;
+            state: string;
+        })[];
+    }>;
+}
+export { affiliateSnapshotValidator, affiliateObligationValidator, affiliateOperationValidator, } from "./affiliateRecovery/validators.js";
+//# sourceMappingURL=affiliateRecovery.d.ts.map

package/dist/client/affiliateRecovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"affiliateRecovery.d.ts","sourceRoot":"","sources":["../../src/client/affiliateRecovery.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtD,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sCAAsC,CAAC;AAChE,MAAM,MAAM,2BAA2B,GAAG,kBAAkB,CAAC;AAC7D,MAAM,MAAM,0BAA0B,GAAG,iBAAiB,CAAC;AAC3D,MAAM,MAAM,wBAAwB,GAAG,GAAG,CAAC,2BAA2B,CAAC,CAAC;AACxE,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACzC,WAAW,EAAE;QACX,IAAI,EAAE,kBAAkB,EAAE,CAAC;QAC3B,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH,CAAC;AACF,8EAA8E;AAC9E,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAF3B,YACmB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,MAAM,EACrC;IACE,QAAQ,CACZ,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QACJ,kBAAkB,EAAE,MAAM,CAAC;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,iBAAiB,CAAC;KACnC,GACA,OAAO,CAAC,yBAAyB,CAAC,CAQpC;IACK,UAAU,CACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAKpC;IACK,OAAO,CACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,iBAAiB,CAAA;KAAE;cASzD,iBAAiB,EAAE;wBACT,MAAM;gBACd,OAAO;OAElB;IACK,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QACJ,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;QAClC,IAAI,EAAE,MAAM,CAAC;KACd;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAWF;IACK,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;;OAOtD;IACK,gBAAgB,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,cAAc,EAAE,iBAAiB,CAAC;QAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;KAAE;cAMjE,GAAG,CAAC,yBAAyB,CAAC,EAAE;wBACtB,MAAM;gBACd,OAAO;OAiClB;IACD,kEAAkE;IAC5D,gBAAgB,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,cAAc,EAAE,iBAAiB,CAAC;QAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;KAAE;cASjE,iBAAiB,EAAE;wBACT,MAAM;gBACd,OAAO;;;;;;;;;;;;;;OAMlB;CACF;AACD,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,mCAAmC,CAAC"}

package/dist/client/affiliateRecovery.js

@@ -0,0 +1,69 @@
+import { reconcileAffiliatePayout, completeAffiliatePayout, } from "./affiliateRecovery/payoutGate.js";
+import { verifiedLegacyReview } from "./affiliateRecovery/review.js";
+import { runMutationOrThrow } from "./helpers.js";
+import { createPayout } from "./connect/payouts.js";
+import { componentRef } from "./webhooks/helpers.js";
+import { reconcileObligation } from "./affiliateRecovery/engine.js";
+/** Server API. Host must authorize account ownership and operator retries. */
+export class AffiliateRecoveryClient {
+    component;
+    provider;
+    constructor(component, provider) {
+        this.component = component;
+        this.provider = provider;
+    }
+    async snapshot(ctx, opts) {
+        return ctx.runQuery(componentRef(this.component, "affiliateRecovery/queries/recoverySnapshot"), opts);
+    }
+    async obligation(ctx, opts) {
+        return ctx.runQuery(componentRef(this.component, "affiliateRecovery/queries/getObligation"), opts);
+    }
+    async history(ctx, opts) {
+        return ctx.runQuery(componentRef(this.component, "affiliateRecovery/queries/operationHistory"), opts);
+    }
+    async reviewLegacy(ctx, opts) {
+        const row = await this.obligation(ctx, opts);
+        if (!row)
+            throw new Error("Affiliate obligation not found.");
+        const review = await verifiedLegacyReview(this.provider(), row, opts);
+        await runMutationOrThrow(ctx, componentRef(this.component, "affiliateRecovery/mutations/reviewLegacy"), review);
+        return this.obligation(ctx, opts);
+    }
+    async retry(ctx, opts) {
+        return reconcileObligation(this.provider(), this.component, ctx, opts.obligationId);
+    }
+    async reconcilePayouts(ctx, opts) {
+        const page = (await ctx.runQuery(componentRef(this.component, "affiliatePayouts/queries/pendingPayouts"), opts));
+        for (const row of page.page) {
+            try {
+                // Confirm money already moved even when new debt blocks another attempt.
+                const receipt = await reconcileAffiliatePayout(this.provider(), row);
+                if (receipt) {
+                    await completeAffiliatePayout(this.component, ctx, row.operationKey, "submitted", receipt);
+                    continue;
+                }
+                await createPayout(this.provider(), ctx, {
+                    stripeAccountId: row.affiliateAccountId,
+                    currency: row.currency,
+                    amount: row.amount,
+                    minimumAmount: row.minimumAmount,
+                    idempotencyKey: row.operationKey,
+                }, this.component);
+            }
+            catch {
+                /* The payout gate retains the durable failure/unknown outcome. */
+            }
+        }
+        return page;
+    }
+    /** Run from a host cron for both pending and unknown outcomes. */
+    async reconcilePending(ctx, opts) {
+        const page = (await ctx.runQuery(componentRef(this.component, "affiliateRecovery/queries/pendingOperations"), opts));
+        const results = [];
+        for (const op of page.page)
+            results.push(await this.retry(ctx, { obligationId: op.obligationId }));
+        return { ...page, results };
+    }
+}
+export { affiliateSnapshotValidator, affiliateObligationValidator, affiliateOperationValidator, } from "./affiliateRecovery/validators.js";
+//# sourceMappingURL=affiliateRecovery.js.map

package/dist/client/affiliateRecovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"affiliateRecovery.js","sourceRoot":"","sources":["../../src/client/affiliateRecovery.ts"],"names":[],"mappings":"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"}

package/dist/client/connect/commissionReceipts.d.ts

@@ -0,0 +1,4 @@
+import type Stripe from "stripe";
+/** Locate the exact receipt, never infer operation success from an aggregate. */
+export declare function findCommissionReversal(stripe: Stripe, stripeTransferId: string, operationId: string, amount: number): Promise<Stripe.TransferReversal | null>;
+//# sourceMappingURL=commissionReceipts.d.ts.map

package/dist/client/connect/commissionReceipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commissionReceipts.d.ts","sourceRoot":"","sources":["../../../src/client/connect/commissionReceipts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,iFAAiF;AACjF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,2CAef"}

package/dist/client/connect/commissionReceipts.js

@@ -0,0 +1,17 @@
+/** Locate the exact receipt, never infer operation success from an aggregate. */
+export async function findCommissionReversal(stripe, stripeTransferId, operationId, amount) {
+    let count = 0;
+    for await (const receipt of stripe.transfers.listReversals(stripeTransferId, {
+        limit: 100,
+    })) {
+        if (++count > 1000)
+            throw new Error("Commission reversal receipt lookup limit exceeded.");
+        if (receipt.metadata?.bsReversalOperation === operationId) {
+            if (receipt.amount !== amount)
+                throw new Error("Commission reversal receipt amount mismatch.");
+            return receipt;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=commissionReceipts.js.map

package/dist/client/connect/commissionReceipts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commissionReceipts.js","sourceRoot":"","sources":["../../../src/client/connect/commissionReceipts.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAc,EACd,gBAAwB,EACxB,WAAmB,EACnB,MAAc;IAEd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,gBAAgB,EAAE;QAC3E,KAAK,EAAE,GAAG;KACX,CAAC,EAAE,CAAC;QACH,IAAI,EAAE,KAAK,GAAG,IAAI;YAChB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,IAAI,OAAO,CAAC,QAAQ,EAAE,mBAAmB,KAAK,WAAW,EAAE,CAAC;YAC1D,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;gBAC3B,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;YAClE,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}