@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/dist/component/affiliateEarnings/mutations.js

@@ -0,0 +1,160 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { earningFields } from "../affiliateRecovery/schema.js";
+import { balance, changeBalance, due, updateObligation, } from "../affiliateRecovery/accounting.js";
+const earningDoc = v.object({
+    ...earningFields,
+    _id: v.id("affiliateEarnings"),
+    _creationTime: v.number(),
+});
+export const reserveEarning = mutation({
+    args: { sourceChargeId: v.string(), affiliateAccountId: v.string() },
+    returns: earningDoc,
+    handler: async (ctx, args) => {
+        const existing = await ctx.db
+            .query("affiliateEarnings")
+            .withIndex("by_charge_affiliate", (q) => q
+            .eq("sourceChargeId", args.sourceChargeId)
+            .eq("affiliateAccountId", args.affiliateAccountId))
+            .unique();
+        if (existing)
+            return existing;
+        const allocation = await ctx.db
+            .query("settlementAllocations")
+            .withIndex("by_source_charge", (q) => q.eq("sourceChargeId", args.sourceChargeId))
+            .unique();
+        const leg = allocation?.transfers.find((t) => t.role === "affiliate" &&
+            t.destinationAccountId === args.affiliateAccountId);
+        if (!allocation || !leg)
+            throw new Error("Affiliate earning requires an immutable settlement allocation.");
+        const totals = await balance(ctx, args.affiliateAccountId, allocation.currency);
+        if (totals?.activePayoutKey)
+            throw new Error("Affiliate payout is pending reconciliation.");
+        if ((totals?.reservedRecovery ?? 0) > 0 ||
+            (totals?.reservedRestoration ?? 0) > 0)
+            throw new Error("Affiliate provider recovery is pending reconciliation; retry settlement.");
+        const debts = await ctx.db
+            .query("affiliateObligations")
+            .withIndex("by_affiliate_currency_debt", (q) => q
+            .eq("affiliateAccountId", args.affiliateAccountId)
+            .eq("currency", allocation.currency)
+            .eq("debtStatus", "open"))
+            .take(1001);
+        if (debts.length > 1000)
+            throw new Error("Affiliate debt batch limit exceeded; reconcile before releasing funds.");
+        let remaining = leg.amount;
+        const offsets = [];
+        for (const debt of debts) {
+            if (debt.sourceChargeId === args.sourceChargeId ||
+                debt.needsReconciliation)
+                continue;
+            if (debt.activeOperationId)
+                throw new Error("Affiliate debt has an unresolved provider operation.");
+            const amount = Math.min(remaining, due(debt));
+            if (amount > 0) {
+                offsets.push({ debt, amount });
+                remaining -= amount;
+            }
+            if (!remaining)
+                break;
+        }
+        const earningId = await ctx.db.insert("affiliateEarnings", {
+            ...args,
+            currency: allocation.currency,
+            originalCommission: leg.amount,
+            withheldAmount: leg.amount - remaining,
+            releaseAmount: remaining,
+            status: "reserved",
+            sourceInvoiceId: allocation.sourceInvoiceId,
+            paymentIntentId: allocation.paymentIntentId,
+        });
+        for (const { debt, amount } of offsets) {
+            await ctx.db.insert("affiliateOffsets", {
+                earningId,
+                obligationId: debt._id,
+                amount,
+            });
+            await updateObligation(ctx, debt, {
+                offsetAmount: (debt.offsetAmount ?? 0) + amount,
+                lastState: "offset",
+            });
+        }
+        const obligationId = await ctx.db.insert("affiliateObligations", {
+            sourceChargeId: allocation.sourceChargeId,
+            sourceInvoiceId: allocation.sourceInvoiceId,
+            paymentIntentId: allocation.paymentIntentId,
+            paymentId: allocation.paymentId,
+            storeAccountId: allocation.transfers.find((leg) => leg.role === "store")
+                ?.destinationAccountId,
+            affiliateAccountId: args.affiliateAccountId,
+            currency: allocation.currency,
+            chargeAmount: allocation.gross,
+            originalCommission: leg.amount,
+            releasedCommission: remaining,
+            earningId,
+            refundedPrincipal: 0,
+            disputedPrincipal: 0,
+            lostPrincipal: 0,
+            finalizedAmount: 0,
+            provisionalAmount: 0,
+            recoveredAmount: 0,
+            needsReconciliation: false,
+        });
+        await updateObligation(ctx, (await ctx.db.get("affiliateObligations", obligationId)), {});
+        await changeBalance(ctx, args.affiliateAccountId, allocation.currency, {
+            withheldAmount: leg.amount - remaining,
+            netPayable: remaining,
+        });
+        return (await ctx.db.get("affiliateEarnings", earningId));
+    },
+});
+export const confirmEarning = mutation({
+    args: {
+        earningId: v.id("affiliateEarnings"),
+        stripeTransferId: v.optional(v.string()),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const earning = await ctx.db.get("affiliateEarnings", args.earningId);
+        if (!earning)
+            throw new Error("Affiliate earning not found.");
+        if (earning.status === "paid") {
+            if (earning.stripeTransferId !== args.stripeTransferId)
+                throw new Error("Affiliate earning receipt cannot change.");
+            return null;
+        }
+        if (earning.releaseAmount > 0 !== !!args.stripeTransferId)
+            throw new Error("Affiliate release requires an exact transfer receipt.");
+        if (args.stripeTransferId) {
+            const transfer = await ctx.db
+                .query("transfers")
+                .withIndex("by_stripe_transfer_id", (q) => q.eq("stripeTransferId", args.stripeTransferId))
+                .unique();
+            if (!transfer ||
+                transfer.amount !== earning.releaseAmount ||
+                transfer.currency !== earning.currency ||
+                transfer.destinationAccountId !== earning.affiliateAccountId ||
+                transfer.sourceChargeId !== earning.sourceChargeId)
+                throw new Error("Affiliate release receipt does not match its earning.");
+        }
+        const obligation = await ctx.db
+            .query("affiliateObligations")
+            .withIndex("by_charge", (q) => q.eq("sourceChargeId", earning.sourceChargeId))
+            .take(1001);
+        const own = obligation.find((row) => row.earningId === earning._id);
+        if (!own || obligation.length > 1000)
+            throw new Error("Affiliate earning obligation requires reconciliation.");
+        await ctx.db.patch("affiliateObligations", own._id, {
+            stripeTransferId: args.stripeTransferId,
+        });
+        await ctx.db.patch("affiliateEarnings", earning._id, {
+            status: "paid",
+            stripeTransferId: args.stripeTransferId,
+        });
+        await changeBalance(ctx, earning.affiliateAccountId, earning.currency, {
+            netPayable: -earning.releaseAmount,
+        });
+        return null;
+    },
+});
+//# sourceMappingURL=mutations.js.map

package/dist/component/affiliateEarnings/mutations.js.map

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

package/dist/component/affiliatePayouts/mutations.d.ts

@@ -0,0 +1,25 @@
+export declare const reservePayout: import("convex/server").RegisteredMutation<"public", {
+    affiliateAccountId: string;
+    amount: number;
+    currency: string;
+    minimumAmount: number;
+    now: number;
+    operationKey?: string | undefined;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"affiliatePayoutReleases">;
+    affiliateAccountId: string;
+    amount: number;
+    createdAt: number;
+    currency: string;
+    minimumAmount: number;
+    operationKey: string;
+    state: "failed" | "pending" | "submitted" | "unknown";
+    stripePayoutId?: string | undefined;
+} | null>>;
+export declare const finishPayout: import("convex/server").RegisteredMutation<"public", {
+    operationKey: string;
+    state: "failed" | "submitted" | "unknown";
+    stripePayoutId?: string | undefined;
+}, Promise<null>>;
+//# sourceMappingURL=mutations.d.ts.map

package/dist/component/affiliatePayouts/mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../../src/component/affiliatePayouts/mutations.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;UAuExB,CAAC;AACH,eAAO,MAAM,YAAY;;;;iBAuCvB,CAAC"}

package/dist/component/affiliatePayouts/mutations.js

@@ -0,0 +1,104 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { balance } from "../affiliateRecovery/accounting.js";
+import { payoutReleaseFields } from "../affiliateRecovery/schema.js";
+const doc = v.object({
+    ...payoutReleaseFields,
+    _id: v.id("affiliatePayoutReleases"),
+    _creationTime: v.number(),
+});
+export const reservePayout = mutation({
+    args: {
+        affiliateAccountId: v.string(),
+        currency: v.string(),
+        amount: v.number(),
+        minimumAmount: v.number(),
+        operationKey: v.optional(v.string()),
+        now: v.number(),
+    },
+    returns: v.union(doc, v.null()),
+    handler: async (ctx, args) => {
+        const totals = await balance(ctx, args.affiliateAccountId, args.currency);
+        if (!totals)
+            return null;
+        if (!args.operationKey?.trim())
+            throw new Error("Affiliate payouts require a stable idempotency key.");
+        const existing = await ctx.db
+            .query("affiliatePayoutReleases")
+            .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+            .unique();
+        if (existing) {
+            if (existing.amount !== args.amount ||
+                existing.affiliateAccountId !== args.affiliateAccountId ||
+                existing.currency !== args.currency ||
+                existing.minimumAmount !== args.minimumAmount)
+                throw new Error("Affiliate payout operation identity cannot change.");
+            if (existing.state === "pending" || existing.state === "unknown") {
+                if (totals.outstandingDebt > 0 ||
+                    totals.reservedRecovery > 0 ||
+                    totals.reservedRestoration > 0 ||
+                    totals.activePayoutKey !== existing.operationKey)
+                    throw new Error("Affiliate recovery must be reconciled before payout release.");
+            }
+            return existing;
+        }
+        if (![args.amount, args.minimumAmount].every((n) => Number.isSafeInteger(n) && n > 0) ||
+            args.amount < args.minimumAmount)
+            throw new Error("Affiliate payout does not meet its currency minimum.");
+        if (totals.outstandingDebt > 0 ||
+            totals.reservedRecovery > 0 ||
+            totals.reservedRestoration > 0 ||
+            totals.activePayoutKey)
+            throw new Error("Affiliate recovery must be reconciled before payout release.");
+        const id = await ctx.db.insert("affiliatePayoutReleases", {
+            affiliateAccountId: args.affiliateAccountId,
+            currency: args.currency,
+            amount: args.amount,
+            minimumAmount: args.minimumAmount,
+            operationKey: args.operationKey,
+            createdAt: args.now,
+            state: "pending",
+        });
+        await ctx.db.patch("affiliateRecoveryBalances", totals._id, {
+            activePayoutKey: args.operationKey,
+            pendingPayoutAmount: args.amount,
+        });
+        return (await ctx.db.get("affiliatePayoutReleases", id));
+    },
+});
+export const finishPayout = mutation({
+    args: {
+        operationKey: v.string(),
+        state: v.union(v.literal("unknown"), v.literal("submitted"), v.literal("failed")),
+        stripePayoutId: v.optional(v.string()),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const row = await ctx.db
+            .query("affiliatePayoutReleases")
+            .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+            .unique();
+        if (!row)
+            throw new Error("Affiliate payout operation not found.");
+        if (row.state === "submitted") {
+            if (args.state === "submitted" &&
+                args.stripePayoutId !== row.stripePayoutId)
+                throw new Error("Affiliate payout receipt cannot change.");
+            return null;
+        }
+        if (args.state === "submitted" && !args.stripePayoutId)
+            throw new Error("Affiliate payout requires a provider receipt.");
+        const totals = (await balance(ctx, row.affiliateAccountId, row.currency));
+        if (args.state !== "unknown" && totals.activePayoutKey === row.operationKey)
+            await ctx.db.patch("affiliateRecoveryBalances", totals._id, {
+                activePayoutKey: undefined,
+                pendingPayoutAmount: 0,
+            });
+        await ctx.db.patch("affiliatePayoutReleases", row._id, {
+            state: args.state,
+            stripePayoutId: args.stripePayoutId,
+        });
+        return null;
+    },
+});
+//# sourceMappingURL=mutations.js.map

package/dist/component/affiliatePayouts/mutations.js.map

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

package/dist/component/affiliatePayouts/queries.d.ts

@@ -0,0 +1,23 @@
+export declare const pendingPayouts: import("convex/server").RegisteredQuery<"public", {
+    paginationOpts: {
+        id?: number;
+        endCursor?: string | null;
+        maximumRowsRead?: number;
+        maximumBytesRead?: number;
+        numItems: number;
+        cursor: string | null;
+    };
+    state: "pending" | "unknown";
+}, Promise<import("convex/server").PaginationResult<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"affiliatePayoutReleases">;
+    affiliateAccountId: string;
+    amount: number;
+    createdAt: number;
+    currency: string;
+    minimumAmount: number;
+    operationKey: string;
+    state: "failed" | "pending" | "submitted" | "unknown";
+    stripePayoutId?: string | undefined;
+}>>>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/component/affiliatePayouts/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/affiliatePayouts/queries.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;IAoBzB,CAAC"}

package/dist/component/affiliatePayouts/queries.js

@@ -0,0 +1,23 @@
+import { paginationOptsValidator, paginationResultValidator, } from "convex/server";
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { payoutReleaseFields } from "../affiliateRecovery/schema.js";
+export const pendingPayouts = query({
+    args: {
+        state: v.union(v.literal("pending"), v.literal("unknown")),
+        paginationOpts: paginationOptsValidator,
+    },
+    returns: paginationResultValidator(v.object({
+        ...payoutReleaseFields,
+        _id: v.id("affiliatePayoutReleases"),
+        _creationTime: v.number(),
+    })),
+    handler: (ctx, args) => ctx.db
+        .query("affiliatePayoutReleases")
+        .withIndex("by_state", (q) => q.eq("state", args.state))
+        .paginate({
+        ...args.paginationOpts,
+        numItems: Math.min(10, args.paginationOpts.numItems),
+    }),
+});
+//# sourceMappingURL=queries.js.map

package/dist/component/affiliatePayouts/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../../src/component/affiliatePayouts/queries.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;IAClC,IAAI,EAAE;QACJ,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC1D,cAAc,EAAE,uBAAuB;KACxC;IACD,OAAO,EAAE,yBAAyB,CAChC,CAAC,CAAC,MAAM,CAAC;QACP,GAAG,mBAAmB;QACtB,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,yBAAyB,CAAC;QACpC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;KAC1B,CAAC,CACH;IACD,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CACrB,GAAG,CAAC,EAAE;SACH,KAAK,CAAC,yBAAyB,CAAC;SAChC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;SACvD,QAAQ,CAAC;QACR,GAAG,IAAI,CAAC,cAAc;QACtB,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC;KACrD,CAAC;CACP,CAAC,CAAC"}

package/dist/component/affiliatePayouts/recipientGuard.d.ts

@@ -0,0 +1,12 @@
+import type { MutationCtx } from "../_generated/server.js";
+type Identity = {
+    accountId: string;
+    currency: string;
+    operationKey: string;
+};
+/** Share the recovery lock with combined seller/affiliate payout claims. */
+export declare function reserveRecoveryGuard(ctx: MutationCtx, identity: Identity, amount: number): Promise<void>;
+/** Only a verified outcome or a never-attempted cancellation releases the lock. */
+export declare function releaseRecoveryGuard(ctx: MutationCtx, identity: Identity): Promise<void>;
+export {};
+//# sourceMappingURL=recipientGuard.d.ts.map

package/dist/component/affiliatePayouts/recipientGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipientGuard.d.ts","sourceRoot":"","sources":["../../../src/component/affiliatePayouts/recipientGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG3D,KAAK,QAAQ,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAI9E,4EAA4E;AAC5E,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,iBAiBf;AAED,mFAAmF;AACnF,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,QAAQ,iBAQnB"}

package/dist/component/affiliatePayouts/recipientGuard.js

@@ -0,0 +1,26 @@
+import { balance, changeBalance } from "../affiliateRecovery/accounting.js";
+const key = (identity) => `bs:recipient-payout:${identity.operationKey}`;
+/** Share the recovery lock with combined seller/affiliate payout claims. */
+export async function reserveRecoveryGuard(ctx, identity, amount) {
+    await changeBalance(ctx, identity.accountId, identity.currency, {});
+    const totals = (await balance(ctx, identity.accountId, identity.currency));
+    if (totals.outstandingDebt > 0 ||
+        totals.reservedRecovery > 0 ||
+        totals.reservedRestoration > 0 ||
+        (totals.activePayoutKey && totals.activePayoutKey !== key(identity)))
+        throw new Error("Affiliate recovery must be reconciled before payout release.");
+    await ctx.db.patch("affiliateRecoveryBalances", totals._id, {
+        activePayoutKey: key(identity),
+        pendingPayoutAmount: amount,
+    });
+}
+/** Only a verified outcome or a never-attempted cancellation releases the lock. */
+export async function releaseRecoveryGuard(ctx, identity) {
+    const totals = await balance(ctx, identity.accountId, identity.currency);
+    if (totals?.activePayoutKey === key(identity))
+        await ctx.db.patch("affiliateRecoveryBalances", totals._id, {
+            activePayoutKey: undefined,
+            pendingPayoutAmount: 0,
+        });
+}
+//# sourceMappingURL=recipientGuard.js.map

package/dist/component/affiliatePayouts/recipientGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipientGuard.js","sourceRoot":"","sources":["../../../src/component/affiliatePayouts/recipientGuard.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAG5E,MAAM,GAAG,GAAG,CAAC,QAAkB,EAAE,EAAE,CACjC,uBAAuB,QAAQ,CAAC,YAAY,EAAE,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAgB,EAChB,QAAkB,EAClB,MAAc;IAEd,MAAM,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAE,CAAC;IAC5E,IACE,MAAM,CAAC,eAAe,GAAG,CAAC;QAC1B,MAAM,CAAC,gBAAgB,GAAG,CAAC;QAC3B,MAAM,CAAC,mBAAmB,GAAG,CAAC;QAC9B,CAAC,MAAM,CAAC,eAAe,IAAI,MAAM,CAAC,eAAe,KAAK,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEpE,MAAM,IAAI,KAAK,CACb,8DAA8D,CAC/D,CAAC;IACJ,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,2BAA2B,EAAE,MAAM,CAAC,GAAG,EAAE;QAC1D,eAAe,EAAE,GAAG,CAAC,QAAQ,CAAC;QAC9B,mBAAmB,EAAE,MAAM;KAC5B,CAAC,CAAC;AACL,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAgB,EAChB,QAAkB;IAElB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzE,IAAI,MAAM,EAAE,eAAe,KAAK,GAAG,CAAC,QAAQ,CAAC;QAC3C,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,2BAA2B,EAAE,MAAM,CAAC,GAAG,EAAE;YAC1D,eAAe,EAAE,SAAS;YAC1B,mBAAmB,EAAE,CAAC;SACvB,CAAC,CAAC;AACP,CAAC"}

package/dist/component/affiliateRecovery/accounting.d.ts

@@ -0,0 +1,28 @@
+import type { Doc } from "../_generated/dataModel.js";
+import type { MutationCtx } from "../_generated/server.js";
+export type Obligation = Omit<Doc<"affiliateObligations">, "_id" | "_creationTime">;
+export declare const target: (row: Obligation) => number;
+export declare const netRecovery: (row: Obligation) => number;
+export declare const due: (row: Obligation) => number;
+export declare const credit: (row: Obligation) => number;
+export declare function balance(ctx: MutationCtx, account: string, currency: string): Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"affiliateRecoveryBalances">;
+    activePayoutKey?: string | undefined;
+    affiliateAccountId: string;
+    currency: string;
+    netPayable: number;
+    offsetAmount: number;
+    originalCommission: number;
+    outstandingDebt: number;
+    pendingPayoutAmount?: number | undefined;
+    recoveredAmount: number;
+    reservedRecovery: number;
+    reservedRestoration: number;
+    restorationDue: number;
+    restoredAmount: number;
+    withheldAmount: number;
+} | null>;
+export declare function changeBalance(ctx: MutationCtx, account: string, currency: string, changes: Partial<Record<"originalCommission" | "recoveredAmount" | "offsetAmount" | "restoredAmount" | "outstandingDebt" | "reservedRecovery" | "reservedRestoration" | "restorationDue" | "withheldAmount" | "netPayable", number>>): Promise<void>;
+export declare function updateObligation(ctx: MutationCtx, previous: Doc<"affiliateObligations">, patch: Partial<Obligation>): Promise<void>;
+//# sourceMappingURL=accounting.d.ts.map

package/dist/component/affiliateRecovery/accounting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounting.d.ts","sourceRoot":"","sources":["../../../src/component/affiliateRecovery/accounting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,MAAM,MAAM,UAAU,GAAG,IAAI,CAC3B,GAAG,CAAC,sBAAsB,CAAC,EAC3B,KAAK,GAAG,eAAe,CACxB,CAAC;AACF,eAAO,MAAM,MAAM,QAAS,UAAU,WACO,CAAC;AAC9C,eAAO,MAAM,WAAW,QAAS,UAAU,WACgC,CAAC;AAC5E,eAAO,MAAM,GAAG,QAAS,UAAU,WACU,CAAC;AAC9C,eAAO,MAAM,MAAM,QAAS,UAAU,WACqC,CAAC;AAC5E,wBAAsB,OAAO,CAC3B,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM;;;;;;;;;;;;;;;;;UAQjB;AACD,wBAAsB,aAAa,CACjC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,CACd,MAAM,CACF,oBAAoB,GACpB,iBAAiB,GACjB,cAAc,GACd,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,GACrB,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,EACd,MAAM,CACP,CACF,iBA2BF;AACD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,GAAG,CAAC,sBAAsB,CAAC,EACrC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,iBAmC3B"}

package/dist/component/affiliateRecovery/accounting.js

@@ -0,0 +1,71 @@
+export const target = (row) => row.finalizedAmount + row.provisionalAmount;
+export const netRecovery = (row) => row.recoveredAmount + (row.offsetAmount ?? 0) - (row.restoredAmount ?? 0);
+export const due = (row) => Math.max(0, target(row) - netRecovery(row));
+export const credit = (row) => row.needsReconciliation ? 0 : Math.max(0, netRecovery(row) - target(row));
+export async function balance(ctx, account, currency) {
+    return ctx.db
+        .query("affiliateRecoveryBalances")
+        .withIndex("by_affiliate_currency", (q) => q.eq("affiliateAccountId", account).eq("currency", currency))
+        .unique();
+}
+export async function changeBalance(ctx, account, currency, changes) {
+    const existing = await balance(ctx, account, currency);
+    const base = existing ?? {
+        affiliateAccountId: account,
+        currency,
+        originalCommission: 0,
+        recoveredAmount: 0,
+        offsetAmount: 0,
+        restoredAmount: 0,
+        outstandingDebt: 0,
+        reservedRecovery: 0,
+        reservedRestoration: 0,
+        restorationDue: 0,
+        withheldAmount: 0,
+        netPayable: 0,
+    };
+    const patch = {};
+    for (const key of Object.keys(changes)) {
+        const next = base[key] + (changes[key] ?? 0);
+        if (!Number.isSafeInteger(next) || next < 0)
+            throw new Error(`Invalid affiliate balance ${key}.`);
+        patch[key] = next;
+    }
+    if (existing)
+        await ctx.db.patch("affiliateRecoveryBalances", existing._id, patch);
+    else
+        await ctx.db.insert("affiliateRecoveryBalances", { ...base, ...patch });
+}
+export async function updateObligation(ctx, previous, patch) {
+    if (!previous.accounted) {
+        await changeBalance(ctx, previous.affiliateAccountId, previous.currency, {
+            originalCommission: previous.originalCommission,
+            recoveredAmount: previous.recoveredAmount,
+            offsetAmount: previous.offsetAmount ?? 0,
+            restoredAmount: previous.restoredAmount ?? 0,
+            outstandingDebt: due(previous),
+            restorationDue: credit(previous),
+            reservedRecovery: previous.reservedRecovery ?? 0,
+            reservedRestoration: previous.reservedRestoration ?? 0,
+        });
+    }
+    const next = { ...previous, ...patch };
+    const debtAmount = due(next), creditAmount = credit(next);
+    await changeBalance(ctx, next.affiliateAccountId, next.currency, {
+        outstandingDebt: debtAmount - (previous.debtAmount ?? due(previous)),
+        restorationDue: creditAmount - (previous.creditAmount ?? credit(previous)),
+        recoveredAmount: next.recoveredAmount - previous.recoveredAmount,
+        offsetAmount: (next.offsetAmount ?? 0) - (previous.offsetAmount ?? 0),
+        restoredAmount: (next.restoredAmount ?? 0) - (previous.restoredAmount ?? 0),
+        reservedRecovery: (next.reservedRecovery ?? 0) - (previous.reservedRecovery ?? 0),
+        reservedRestoration: (next.reservedRestoration ?? 0) - (previous.reservedRestoration ?? 0),
+    });
+    await ctx.db.patch("affiliateObligations", previous._id, {
+        ...patch,
+        accounted: true,
+        debtAmount,
+        creditAmount,
+        debtStatus: debtAmount > 0 ? "open" : "settled",
+    });
+}
+//# sourceMappingURL=accounting.js.map

package/dist/component/affiliateRecovery/accounting.js.map

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

package/dist/component/affiliateRecovery/mutations.d.ts

@@ -0,0 +1,65 @@
+export declare const reserveOperation: import("convex/server").RegisteredMutation<"public", {
+    kind: "recovery" | "restoration";
+    now: number;
+    obligationId: import("convex/values").GenericId<"affiliateObligations">;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"affiliateRecoveryOperations">;
+    amount: number;
+    attempted: boolean;
+    createdAt: number;
+    error?: string | undefined;
+    kind: "recovery" | "restoration";
+    obligationId: import("convex/values").GenericId<"affiliateObligations">;
+    providerBaseline?: number | undefined;
+    receiptId?: string | undefined;
+    sourceEventId?: string | undefined;
+    state: "canceled" | "failed" | "insufficient_balance" | "pending" | "succeeded" | "unknown" | "unsupported";
+} | null>>;
+/** Persist intent before contacting Stripe. Retries keep the exact operation ID. */
+export declare const beginOperation: import("convex/server").RegisteredMutation<"public", {
+    operationId: import("convex/values").GenericId<"affiliateRecoveryOperations">;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"affiliateRecoveryOperations">;
+    attempted: boolean;
+    amount: number;
+    createdAt: number;
+    error?: string | undefined;
+    kind: "recovery" | "restoration";
+    obligationId: import("convex/values").GenericId<"affiliateObligations">;
+    providerBaseline?: number | undefined;
+    receiptId?: string | undefined;
+    sourceEventId?: string | undefined;
+    state: "canceled" | "failed" | "insufficient_balance" | "pending" | "succeeded" | "unknown" | "unsupported";
+}>>;
+export declare const completeOperation: import("convex/server").RegisteredMutation<"public", {
+    confirmedTransferReversed?: number | undefined;
+    error?: string | undefined;
+    operationId: import("convex/values").GenericId<"affiliateRecoveryOperations">;
+    receiptId?: string | undefined;
+    state: "canceled" | "failed" | "insufficient_balance" | "pending" | "succeeded" | "unknown" | "unsupported";
+}, Promise<null>>;
+/** Trusted operator API; the client verifies provider facts before this write. */
+export declare const reviewLegacy: import("convex/server").RegisteredMutation<"public", {
+    exposure: {
+        chargeAmount: number;
+        disputeId?: string | undefined;
+        disputeState?: "lost" | "open" | "won" | undefined;
+        finalized: boolean;
+        kind: "dispute" | "refund";
+        principal: number;
+        refundId?: string | undefined;
+        refundedPrincipal?: number | undefined;
+    };
+    note: string;
+    obligationId: import("convex/values").GenericId<"affiliateObligations">;
+    receipts: {
+        amount: number;
+        id: string;
+    }[];
+    recoveredAmount: number;
+    restorationIds: string[];
+    restoredAmount: number;
+}, Promise<null>>;
+//# sourceMappingURL=mutations.d.ts.map

package/dist/component/affiliateRecovery/mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../../src/component/affiliateRecovery/mutations.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;UAgE3B,CAAC;AACH,oFAAoF;AACpF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;GA4BzB,CAAC;AACH,eAAO,MAAM,iBAAiB;;;;;;iBA2G5B,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;iBAyDvB,CAAC"}