@fantastic.dev/better-stripe 0.11.0 → 0.13.0

package/dist/component/costRecovery/claims.js

@@ -0,0 +1,92 @@
+import { v } from "convex/values";
+import { observationFields, rollbackArgs } from "./schema.js";
+import { adjustTotals, getGroup, integer, sign, validateScope, } from "./helpers.js";
+const _observation = v.object(observationFields);
+export async function recordClaim(ctx, args) {
+    validateScope(args);
+    [
+        args.amountDue,
+        args.sourceGross,
+        args.sourceProcessingFee,
+        args.revision,
+    ].forEach(integer);
+    if (!args.claimKey ||
+        !args.sourceChargeId ||
+        args.sourceGross <= 0 ||
+        args.sourceProcessingFee < 0 ||
+        args.revision < 0)
+        throw new Error("Invalid recovery claim observation.");
+    const existing = await ctx.db
+        .query("recoveryClaims")
+        .withIndex("by_key", (q) => q.eq("claimKey", args.claimKey))
+        .unique();
+    if (existing) {
+        for (const key of [
+            "accountId",
+            "scopeKey",
+            "currency",
+            "sourceChargeId",
+            "sourceGross",
+            "sourceProcessingFee",
+        ])
+            if (existing[key] !== args[key])
+                throw new Error("Recovery claim source identity cannot change.");
+        if (args.revision < existing.revision)
+            return existing;
+        if (args.revision === existing.revision) {
+            if (args.amountDue !== existing.amountDue)
+                throw new Error("Recovery revision cannot be reused with a different amount.");
+            return existing;
+        }
+    }
+    const delta = integer(args.amountDue - (existing?.amountDue ?? 0));
+    const collectedAmount = existing?.collectedAmount ?? 0, reservedAmount = existing?.reservedAmount ?? 0;
+    const outstanding = integer(args.amountDue - collectedAmount - reservedAmount);
+    const fields = {
+        ...args,
+        collectedAmount,
+        reservedAmount,
+        outstanding,
+        sign: sign(outstanding),
+    };
+    let id = existing?._id;
+    if (id)
+        await ctx.db.patch("recoveryClaims", id, fields);
+    else
+        id = await ctx.db.insert("recoveryClaims", fields);
+    await adjustTotals(ctx, args, { amountDue: delta, outstanding: delta });
+    return (await ctx.db.get("recoveryClaims", id));
+}
+const _rollbackArgs = v.object(rollbackArgs);
+export async function rollbackClaim(ctx, args) {
+    integer(args.returnedPrincipal);
+    integer(args.revision);
+    const group = await getGroup(ctx, args.groupKey);
+    if (group.status !== "collected" ||
+        (group.sourceKind === "settlement"
+            ? !group.sourceGross
+            : !group.invoiceFunding))
+        throw new Error("Rollback requires a collected group with original funding economics.");
+    const funding = group.sourceKind === "settlement"
+        ? {
+            sourceChargeId: group.sourceId,
+            sourceGross: group.sourceGross,
+            sourceProcessingFee: group.sourceProcessingFee,
+        }
+        : group.invoiceFunding;
+    if (args.returnedPrincipal < 0 ||
+        args.returnedPrincipal > funding.sourceGross)
+        throw new Error("Returned principal exceeds the original funding sale.");
+    const abs = BigInt(Math.abs(group.amount)), gross = BigInt(funding.sourceGross), principal = BigInt(args.returnedPrincipal);
+    const rounded = Number((abs * principal + gross / 2n) / gross);
+    return recordClaim(ctx, {
+        accountId: group.accountId,
+        scopeKey: group.scopeKey,
+        currency: group.currency,
+        claimKey: `rollback:${group.groupKey}`,
+        ...funding,
+        amountDue: group.amount < 0 ? -rounded : rounded,
+        revision: args.revision,
+    });
+}
+//# sourceMappingURL=claims.js.map

package/dist/component/costRecovery/claims.js.map

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

package/dist/component/costRecovery/completion.d.ts

@@ -0,0 +1,39 @@
+import type { MutationCtx } from "../_generated/server.js";
+import type { Infer } from "convex/values";
+declare const _finishArgs: import("convex/values").VObject<{
+    groupKey: string;
+    limit?: number | undefined;
+    outcome: "collect" | "release";
+}, {
+    groupKey: import("convex/values").VString<string, "required">;
+    outcome: import("convex/values").VUnion<"collect" | "release", [import("convex/values").VLiteral<"collect", "required">, import("convex/values").VLiteral<"release", "required">], "required", never>;
+    limit: import("convex/values").VFloat64<number | undefined, "optional">;
+}, "required", "groupKey" | "limit" | "outcome">;
+export declare function finishGroup(ctx: MutationCtx, args: Infer<typeof _finishArgs>): Promise<{
+    group: {
+        _creationTime: number;
+        _id: import("convex/values").GenericId<"recoveryGroups">;
+        accountId: string;
+        amount: number;
+        currency: string;
+        groupKey: string;
+        invoiceFunding?: {
+            sourceChargeId: string;
+            sourceGross: number;
+            sourceProcessingFee: number;
+        } | undefined;
+        invoiceItemId?: string | undefined;
+        maxCredit: number;
+        maxDebit: number;
+        pendingOperations: number;
+        scopeKey: string;
+        sourceGross?: number | undefined;
+        sourceId: string;
+        sourceKind: "invoice" | "settlement";
+        sourceProcessingFee?: number | undefined;
+        status: "collected" | "collecting" | "open" | "released" | "releasing" | "sealed";
+    };
+    isDone: boolean;
+}>;
+export {};
+//# sourceMappingURL=completion.d.ts.map

package/dist/component/costRecovery/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../../src/component/costRecovery/completion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAW3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,QAAA,MAAM,WAAW;;;;;;;;gDAAuB,CAAC;AACzC,wBAAsB,WAAW,CAC/B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,KAAK,CAAC,OAAO,WAAW,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;GA2EhC"}

package/dist/component/costRecovery/completion.js

@@ -0,0 +1,69 @@
+import { v } from "convex/values";
+import { finishArgs } from "./schema.js";
+import { adjustTotals, balance, batchLimit, getGroup, integer, sign, } from "./helpers.js";
+const _finishArgs = v.object(finishArgs);
+export async function finishGroup(ctx, args) {
+    const limit = args.limit ?? 10;
+    batchLimit(limit, 10);
+    const group = await getGroup(ctx, args.groupKey);
+    const collect = args.outcome === "collect", terminal = collect ? "collected" : "released", progress = collect ? "collecting" : "releasing";
+    if (group.status === terminal)
+        return { group, isDone: true };
+    if ((collect && ["released", "releasing"].includes(group.status)) ||
+        (!collect && ["collected", "collecting"].includes(group.status)))
+        throw new Error("Recovery outcome cannot change.");
+    if (collect && group.status === "open")
+        throw new Error("Seal recovery before confirming provider collection.");
+    const operations = await ctx.db
+        .query("recoveryReservations")
+        .withIndex("by_group_status", (q) => q.eq("groupKey", group.groupKey).eq("status", "reserved"))
+        .take(limit);
+    let amount = 0;
+    for (const operation of operations) {
+        for (const allocation of operation.allocations) {
+            const claim = await ctx.db.get("recoveryClaims", allocation.claimId);
+            if (!claim ||
+                claim.accountId !== group.accountId ||
+                claim.scopeKey !== group.scopeKey ||
+                claim.currency !== group.currency)
+                throw new Error("Recovery allocation identity does not match.");
+            const reservedAmount = integer(claim.reservedAmount - allocation.amount);
+            const collectedAmount = integer(claim.collectedAmount + (collect ? allocation.amount : 0));
+            const outstanding = integer(claim.amountDue - collectedAmount - reservedAmount);
+            await ctx.db.patch("recoveryClaims", claim._id, {
+                reservedAmount,
+                collectedAmount,
+                outstanding,
+                sign: sign(outstanding),
+            });
+        }
+        await ctx.db.patch("recoveryReservations", operation._id, {
+            status: terminal,
+        });
+        amount = integer(amount + operation.amount);
+    }
+    await adjustTotals(ctx, group, {
+        reservedAmount: -amount,
+        collectedAmount: collect ? amount : 0,
+        outstanding: collect ? 0 : amount,
+    });
+    const pendingOperations = group.pendingOperations - operations.length;
+    if (pendingOperations < 0)
+        throw new Error("Recovery operation count does not reconcile.");
+    await ctx.db.patch("recoveryGroups", group._id, {
+        pendingOperations,
+        status: pendingOperations ? progress : terminal,
+    });
+    if (!pendingOperations) {
+        const ledger = await balance(ctx, group);
+        if (ledger.activeGroupKey === group.groupKey)
+            await ctx.db.patch("recoveryBalances", ledger._id, {
+                activeGroupKey: undefined,
+            });
+    }
+    return {
+        group: (await ctx.db.get("recoveryGroups", group._id)),
+        isDone: pendingOperations === 0,
+    };
+}
+//# sourceMappingURL=completion.js.map

package/dist/component/costRecovery/completion.js.map

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

package/dist/component/costRecovery/helpers.d.ts

@@ -0,0 +1,68 @@
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+export type Scope = {
+    accountId: string;
+    scopeKey: string;
+    currency: string;
+};
+export declare function integer(value: number): number;
+export declare function validateScope(scope: Scope): void;
+export declare const sign: (value: number) => "negative" | "positive" | "zero";
+export declare const scopeOnly: (scope: Scope) => Scope;
+export declare const zeroTotals: {
+    amountDue: number;
+    collectedAmount: number;
+    reservedAmount: number;
+    outstanding: number;
+};
+export declare function readBalance(ctx: QueryCtx | MutationCtx, scope: Scope): Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryBalances">;
+    accountId: string;
+    activeGroupKey?: string | undefined;
+    amountDue: number;
+    collectedAmount: number;
+    currency: string;
+    outstanding: number;
+    reservedAmount: number;
+    scopeKey: string;
+} | null>;
+export declare function balance(ctx: MutationCtx, scope: Scope): Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryBalances">;
+    accountId: string;
+    activeGroupKey?: string | undefined;
+    amountDue: number;
+    collectedAmount: number;
+    currency: string;
+    outstanding: number;
+    reservedAmount: number;
+    scopeKey: string;
+}>;
+export declare function adjustTotals(ctx: MutationCtx, scope: Scope, delta: Partial<typeof zeroTotals>): Promise<void>;
+export declare function groupTarget(group: Doc<"recoveryGroups">, outstanding: number): number;
+export declare function getGroup(ctx: MutationCtx, key: string): Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryGroups">;
+    accountId: string;
+    amount: number;
+    currency: string;
+    groupKey: string;
+    invoiceFunding?: {
+        sourceChargeId: string;
+        sourceGross: number;
+        sourceProcessingFee: number;
+    } | undefined;
+    invoiceItemId?: string | undefined;
+    maxCredit: number;
+    maxDebit: number;
+    pendingOperations: number;
+    scopeKey: string;
+    sourceGross?: number | undefined;
+    sourceId: string;
+    sourceKind: "invoice" | "settlement";
+    sourceProcessingFee?: number | undefined;
+    status: "collected" | "collecting" | "open" | "released" | "releasing" | "sealed";
+}>;
+export declare function batchLimit(limit: number, max?: number): void;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/component/costRecovery/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/component/costRecovery/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,4BAA4B,CAAC;AACtD,MAAM,MAAM,KAAK,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAC9E,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,UAIpC;AACD,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,QAGzC;AACD,eAAO,MAAM,IAAI,UAAW,MAAM,qCAKT,CAAC;AAC1B,eAAO,MAAM,SAAS,UAAW,KAAK,KAAG,KAIvC,CAAC;AACH,eAAO,MAAM,UAAU;IACrB,SAAS;IACT,eAAe;IACf,cAAc;IACd,WAAW;CACZ,CAAC;AACF,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;UAUpE;AACD,wBAAsB,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;GAQ3D;AACD,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,OAAO,CAAC,OAAO,UAAU,CAAC,iBAYlC;AACD,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,gBAAgB,CAAC,EAAE,WAAW,EAAE,MAAM,UAK5E;AACD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;GAO3D;AACD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAM,QAGlD"}

package/dist/component/costRecovery/helpers.js

@@ -0,0 +1,71 @@
+export function integer(value) {
+    if (!Number.isSafeInteger(value))
+        throw new Error("Recovery amounts must be safe integers.");
+    return value;
+}
+export function validateScope(scope) {
+    if (!scope.accountId || !scope.scopeKey || !/^[a-z]{3}$/.test(scope.currency))
+        throw new Error("Recovery account, scope and currency are required.");
+}
+export const sign = (value) => value > 0
+    ? "positive"
+    : value < 0
+        ? "negative"
+        : "zero";
+export const scopeOnly = (scope) => ({
+    accountId: scope.accountId,
+    scopeKey: scope.scopeKey,
+    currency: scope.currency,
+});
+export const zeroTotals = {
+    amountDue: 0,
+    collectedAmount: 0,
+    reservedAmount: 0,
+    outstanding: 0,
+};
+export function readBalance(ctx, scope) {
+    return ctx.db
+        .query("recoveryBalances")
+        .withIndex("by_scope", (q) => q
+        .eq("accountId", scope.accountId)
+        .eq("scopeKey", scope.scopeKey)
+        .eq("currency", scope.currency))
+        .unique();
+}
+export async function balance(ctx, scope) {
+    const found = await readBalance(ctx, scope);
+    if (found)
+        return found;
+    const id = await ctx.db.insert("recoveryBalances", {
+        ...scopeOnly(scope),
+        ...zeroTotals,
+    });
+    return (await ctx.db.get("recoveryBalances", id));
+}
+export async function adjustTotals(ctx, scope, delta) {
+    const stored = await balance(ctx, scope);
+    const next = { ...zeroTotals };
+    for (const key of Object.keys(zeroTotals))
+        next[key] = integer(stored[key] + (delta[key] ?? 0));
+    if (next.outstanding !==
+        integer(next.amountDue - next.collectedAmount - next.reservedAmount))
+        throw new Error("Recovery totals do not reconcile.");
+    await ctx.db.patch("recoveryBalances", stored._id, next);
+}
+export function groupTarget(group, outstanding) {
+    return Math.max(-group.maxCredit, Math.min(group.maxDebit, integer(outstanding + group.amount)));
+}
+export async function getGroup(ctx, key) {
+    const group = await ctx.db
+        .query("recoveryGroups")
+        .withIndex("by_key", (q) => q.eq("groupKey", key))
+        .unique();
+    if (!group)
+        throw new Error("Recovery group is missing.");
+    return group;
+}
+export function batchLimit(limit, max = 100) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > max)
+        throw new Error(`Recovery batch limit must be between 1 and ${max}.`);
+}
+//# sourceMappingURL=helpers.js.map

package/dist/component/costRecovery/helpers.js.map

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

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

@@ -0,0 +1,210 @@
+export declare const record: import("convex/server").RegisteredMutation<"public", {
+    accountId: string;
+    amountDue: number;
+    claimKey: string;
+    currency: string;
+    revision: number;
+    scopeKey: string;
+    sourceChargeId: string;
+    sourceGross: number;
+    sourceProcessingFee: number;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryClaims">;
+    accountId: string;
+    amountDue: number;
+    claimKey: string;
+    collectedAmount: number;
+    currency: string;
+    outstanding: number;
+    reservedAmount: number;
+    revision: number;
+    scopeKey: string;
+    sign: "negative" | "positive" | "zero";
+    sourceChargeId: string;
+    sourceGross: number;
+    sourceProcessingFee: number;
+}>>;
+export declare const rollback: import("convex/server").RegisteredMutation<"public", {
+    groupKey: string;
+    returnedPrincipal: number;
+    revision: number;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryClaims">;
+    accountId: string;
+    amountDue: number;
+    claimKey: string;
+    collectedAmount: number;
+    currency: string;
+    outstanding: number;
+    reservedAmount: number;
+    revision: number;
+    scopeKey: string;
+    sign: "negative" | "positive" | "zero";
+    sourceChargeId: string;
+    sourceGross: number;
+    sourceProcessingFee: number;
+}>>;
+export declare const reserve: import("convex/server").RegisteredMutation<"public", {
+    accountId: string;
+    currency: string;
+    groupKey: string;
+    limit?: number | undefined;
+    maxCredit: number;
+    maxDebit: number;
+    operationKey: string;
+    scopeKey: string;
+    sourceGross?: number | undefined;
+    sourceId: string;
+    sourceKind: "invoice" | "settlement";
+    sourceProcessingFee?: number | undefined;
+}, Promise<{
+    reservation: {
+        _creationTime: number;
+        _id: import("convex/values").GenericId<"recoveryReservations">;
+        allocations: {
+            amount: number;
+            claimId: import("convex/values").GenericId<"recoveryClaims">;
+            claimKey: string;
+        }[];
+        amount: number;
+        groupKey: string;
+        limit: number;
+        operationKey: string;
+        status: "collected" | "empty" | "released" | "reserved";
+    };
+    group: {
+        _creationTime: number;
+        _id: import("convex/values").GenericId<"recoveryGroups">;
+        accountId: string;
+        amount: number;
+        currency: string;
+        groupKey: string;
+        invoiceFunding?: {
+            sourceChargeId: string;
+            sourceGross: number;
+            sourceProcessingFee: number;
+        } | undefined;
+        invoiceItemId?: string | undefined;
+        maxCredit: number;
+        maxDebit: number;
+        pendingOperations: number;
+        scopeKey: string;
+        sourceGross?: number | undefined;
+        sourceId: string;
+        sourceKind: "invoice" | "settlement";
+        sourceProcessingFee?: number | undefined;
+        status: "collected" | "collecting" | "open" | "released" | "releasing" | "sealed";
+    };
+}>>;
+export declare const seal: import("convex/server").RegisteredMutation<"public", {
+    groupKey: string;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryGroups">;
+    accountId: string;
+    amount: number;
+    currency: string;
+    groupKey: string;
+    invoiceFunding?: {
+        sourceChargeId: string;
+        sourceGross: number;
+        sourceProcessingFee: number;
+    } | undefined;
+    invoiceItemId?: string | undefined;
+    maxCredit: number;
+    maxDebit: number;
+    pendingOperations: number;
+    scopeKey: string;
+    sourceGross?: number | undefined;
+    sourceId: string;
+    sourceKind: "invoice" | "settlement";
+    sourceProcessingFee?: number | undefined;
+    status: "collected" | "collecting" | "open" | "released" | "releasing" | "sealed";
+}>>;
+export declare const finish: import("convex/server").RegisteredMutation<"public", {
+    groupKey: string;
+    limit?: number | undefined;
+    outcome: "collect" | "release";
+}, Promise<{
+    group: {
+        _creationTime: number;
+        _id: import("convex/values").GenericId<"recoveryGroups">;
+        accountId: string;
+        amount: number;
+        currency: string;
+        groupKey: string;
+        invoiceFunding?: {
+            sourceChargeId: string;
+            sourceGross: number;
+            sourceProcessingFee: number;
+        } | undefined;
+        invoiceItemId?: string | undefined;
+        maxCredit: number;
+        maxDebit: number;
+        pendingOperations: number;
+        scopeKey: string;
+        sourceGross?: number | undefined;
+        sourceId: string;
+        sourceKind: "invoice" | "settlement";
+        sourceProcessingFee?: number | undefined;
+        status: "collected" | "collecting" | "open" | "released" | "releasing" | "sealed";
+    };
+    isDone: boolean;
+}>>;
+export declare const bindInvoiceItem: import("convex/server").RegisteredMutation<"public", {
+    groupKey: string;
+    invoiceItemId: string;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryGroups">;
+    accountId: string;
+    amount: number;
+    currency: string;
+    groupKey: string;
+    invoiceFunding?: {
+        sourceChargeId: string;
+        sourceGross: number;
+        sourceProcessingFee: number;
+    } | undefined;
+    invoiceItemId?: string | undefined;
+    maxCredit: number;
+    maxDebit: number;
+    pendingOperations: number;
+    scopeKey: string;
+    sourceGross?: number | undefined;
+    sourceId: string;
+    sourceKind: "invoice" | "settlement";
+    sourceProcessingFee?: number | undefined;
+    status: "collected" | "collecting" | "open" | "released" | "releasing" | "sealed";
+}>>;
+export declare const bindInvoiceFunding: import("convex/server").RegisteredMutation<"public", {
+    groupKey: string;
+    sourceChargeId: string;
+    sourceGross: number;
+    sourceProcessingFee: number;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryGroups">;
+    accountId: string;
+    amount: number;
+    currency: string;
+    groupKey: string;
+    invoiceFunding?: {
+        sourceChargeId: string;
+        sourceGross: number;
+        sourceProcessingFee: number;
+    } | undefined;
+    invoiceItemId?: string | undefined;
+    maxCredit: number;
+    maxDebit: number;
+    pendingOperations: number;
+    scopeKey: string;
+    sourceGross?: number | undefined;
+    sourceId: string;
+    sourceKind: "invoice" | "settlement";
+    sourceProcessingFee?: number | undefined;
+    status: "collected" | "collecting" | "open" | "released" | "releasing" | "sealed";
+}>>;
+//# sourceMappingURL=mutations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../../src/component/costRecovery/mutations.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;GAQjB,CAAC;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;GAInB,CAAC;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAIlB,CAAC;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;GAIf,CAAC;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAIjB,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;GA0B1B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyC7B,CAAC"}