@fantastic.dev/better-stripe 0.10.2 → 0.12.0

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":"AAGA,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,OAAO,KAAK,CAAC;AACf,CAAC;AACD,MAAM,UAAU,aAAa,CAAC,KAAY;IACxC,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;AAC1E,CAAC;AACD,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE,CACpC,KAAK,GAAG,CAAC;IACP,CAAC,CAAE,UAAoB;IACvB,CAAC,CAAC,KAAK,GAAG,CAAC;QACT,CAAC,CAAE,UAAoB;QACvB,CAAC,CAAE,MAAgB,CAAC;AAC1B,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAY,EAAS,EAAE,CAAC,CAAC;IACjD,SAAS,EAAE,KAAK,CAAC,SAAS;IAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;IACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;CACzB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,SAAS,EAAE,CAAC;IACZ,eAAe,EAAE,CAAC;IAClB,cAAc,EAAE,CAAC;IACjB,WAAW,EAAE,CAAC;CACf,CAAC;AACF,MAAM,UAAU,WAAW,CAAC,GAA2B,EAAE,KAAY;IACnE,OAAO,GAAG,CAAC,EAAE;SACV,KAAK,CAAC,kBAAkB,CAAC;SACzB,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAC3B,CAAC;SACE,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC;SAChC,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC;SAC9B,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAClC;SACA,MAAM,EAAE,CAAC;AACd,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAgB,EAAE,KAAY;IAC1D,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5C,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,kBAAkB,EAAE;QACjD,GAAG,SAAS,CAAC,KAAK,CAAC;QACnB,GAAG,UAAU;KACd,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAE,CAAC;AACrD,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAgB,EAChB,KAAY,EACZ,KAAiC;IAEjC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,EAAE,GAAG,UAAU,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAgC;QACtE,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvD,IACE,IAAI,CAAC,WAAW;QAChB,OAAO,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,cAAc,CAAC;QAEpE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC3D,CAAC;AACD,MAAM,UAAU,WAAW,CAAC,KAA4B,EAAE,WAAmB;IAC3E,OAAO,IAAI,CAAC,GAAG,CACb,CAAC,KAAK,CAAC,SAAS,EAChB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAC9D,CAAC;AACJ,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAgB,EAAE,GAAW;IAC1D,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,EAAE;SACvB,KAAK,CAAC,gBAAgB,CAAC;SACvB,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;SACjD,MAAM,EAAE,CAAC;IACZ,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC;AACf,CAAC;AACD,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,GAAG,GAAG,GAAG;IACjD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG;QACtD,MAAM,IAAI,KAAK,CAAC,8CAA8C,GAAG,GAAG,CAAC,CAAC;AAC1E,CAAC"}

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

@@ -0,0 +1,138 @@
+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;
+        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;
+    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;
+        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;
+}>>;
+//# 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":"AAcA,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"}

package/dist/component/costRecovery/mutations.js

@@ -0,0 +1,36 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { recordClaim, rollbackClaim } from "./claims.js";
+import { reserveGroup, sealGroup } from "./reservations.js";
+import { finishGroup } from "./completion.js";
+import { observationFields, claimDoc, groupDoc, reservationDoc, reserveArgs, rollbackArgs, finishArgs, } from "./schema.js";
+export const record = mutation({
+    args: observationFields,
+    returns: claimDoc,
+    handler: async (ctx, args) => {
+        if (args.claimKey.startsWith("rollback:"))
+            throw new Error("Rollback claim keys are reserved.");
+        return recordClaim(ctx, args);
+    },
+});
+export const rollback = mutation({
+    args: rollbackArgs,
+    returns: claimDoc,
+    handler: rollbackClaim,
+});
+export const reserve = mutation({
+    args: reserveArgs,
+    returns: v.object({ reservation: reservationDoc, group: groupDoc }),
+    handler: reserveGroup,
+});
+export const seal = mutation({
+    args: { groupKey: v.string() },
+    returns: groupDoc,
+    handler: sealGroup,
+});
+export const finish = mutation({
+    args: finishArgs,
+    returns: v.object({ group: groupDoc, isDone: v.boolean() }),
+    handler: finishGroup,
+});
+//# sourceMappingURL=mutations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.js","sourceRoot":"","sources":["../../../src/component/costRecovery/mutations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,WAAW,EACX,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,MAAM,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC;IAC7B,IAAI,EAAE,iBAAiB;IACvB,OAAO,EAAE,QAAQ;IACjB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,OAAO,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;CACF,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC/B,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,QAAQ;IACjB,OAAO,EAAE,aAAa;CACvB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;IAC9B,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IACnE,OAAO,EAAE,YAAY;CACtB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,QAAQ,CAAC;IAC3B,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;IAC9B,OAAO,EAAE,QAAQ;IACjB,OAAO,EAAE,SAAS;CACnB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC;IAC7B,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;IAC3D,OAAO,EAAE,WAAW;CACrB,CAAC,CAAC"}

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

@@ -0,0 +1,102 @@
+export declare const balance: import("convex/server").RegisteredQuery<"public", {
+    accountId: string;
+    currency: string;
+    scopeKey: string;
+}, Promise<{
+    accountId: string;
+    scopeKey: string;
+    currency: string;
+    amountDue: number;
+    collectedAmount: number;
+    reservedAmount: number;
+    outstanding: number;
+    activeGroupKey?: string | undefined;
+}>>;
+export declare const listClaims: import("convex/server").RegisteredQuery<"public", {
+    accountId: string;
+    currency: string;
+    paginationOpts: {
+        id?: number;
+        endCursor?: string | null;
+        maximumRowsRead?: number;
+        maximumBytesRead?: number;
+        numItems: number;
+        cursor: string | null;
+    };
+    scopeKey: string;
+}, Promise<{
+    page: {
+        _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;
+    }[];
+    continueCursor: string;
+    isDone: boolean;
+}>>;
+export declare const group: import("convex/server").RegisteredQuery<"public", {
+    groupKey: string;
+}, Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryGroups">;
+    accountId: string;
+    amount: number;
+    currency: string;
+    groupKey: string;
+    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";
+} | null>>;
+export declare const reservation: import("convex/server").RegisteredQuery<"public", {
+    operationKey: string;
+}, Promise<{
+    _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";
+} | null>>;
+export declare const claim: import("convex/server").RegisteredQuery<"public", {
+    claimKey: string;
+}, 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;
+} | null>>;
+//# sourceMappingURL=queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/costRecovery/queries.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,OAAO;;;;;;;;;;;;;GAiBlB,CAAC;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BrB,CAAC;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;UAQhB,CAAC;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;UAQtB,CAAC;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;UAQhB,CAAC"}

package/dist/component/costRecovery/queries.js

@@ -0,0 +1,73 @@
+import { paginationOptsValidator } from "convex/server";
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { balanceFields, claimDoc, groupDoc, scopeFields, reservationDoc, } from "./schema.js";
+import { readBalance, scopeOnly, validateScope, batchLimit, } from "./helpers.js";
+export const balance = query({
+    args: scopeFields,
+    returns: v.object(balanceFields),
+    handler: async (ctx, args) => {
+        validateScope(args);
+        const stored = await readBalance(ctx, args);
+        return {
+            ...scopeOnly(args),
+            amountDue: stored?.amountDue ?? 0,
+            collectedAmount: stored?.collectedAmount ?? 0,
+            reservedAmount: stored?.reservedAmount ?? 0,
+            outstanding: stored?.outstanding ?? 0,
+            ...(stored?.activeGroupKey
+                ? { activeGroupKey: stored.activeGroupKey }
+                : {}),
+        };
+    },
+});
+export const listClaims = query({
+    args: { ...scopeFields, paginationOpts: paginationOptsValidator },
+    returns: v.object({
+        page: v.array(claimDoc),
+        continueCursor: v.string(),
+        isDone: v.boolean(),
+    }),
+    handler: async (ctx, args) => {
+        validateScope(args);
+        batchLimit(args.paginationOpts.numItems);
+        const result = await ctx.db
+            .query("recoveryClaims")
+            .withIndex("by_scope", (q) => q
+            .eq("accountId", args.accountId)
+            .eq("scopeKey", args.scopeKey)
+            .eq("currency", args.currency))
+            .order("desc")
+            .paginate(args.paginationOpts);
+        return {
+            page: result.page,
+            continueCursor: result.continueCursor,
+            isDone: result.isDone,
+        };
+    },
+});
+export const group = query({
+    args: { groupKey: v.string() },
+    returns: v.union(groupDoc, v.null()),
+    handler: (ctx, args) => ctx.db
+        .query("recoveryGroups")
+        .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
+        .unique(),
+});
+export const reservation = query({
+    args: { operationKey: v.string() },
+    returns: v.union(reservationDoc, v.null()),
+    handler: (ctx, args) => ctx.db
+        .query("recoveryReservations")
+        .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+        .unique(),
+});
+export const claim = query({
+    args: { claimKey: v.string() },
+    returns: v.union(claimDoc, v.null()),
+    handler: (ctx, args) => ctx.db
+        .query("recoveryClaims")
+        .withIndex("by_key", (q) => q.eq("claimKey", args.claimKey))
+        .unique(),
+});
+//# sourceMappingURL=queries.js.map

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

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

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

@@ -0,0 +1,83 @@
+import type { MutationCtx } from "../_generated/server.js";
+import type { Infer } from "convex/values";
+declare const _reserveArgs: import("convex/values").VObject<{
+    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;
+}, {
+    accountId: import("convex/values").VString<string, "required">;
+    scopeKey: import("convex/values").VString<string, "required">;
+    currency: import("convex/values").VString<string, "required">;
+    groupKey: import("convex/values").VString<string, "required">;
+    sourceKind: import("convex/values").VUnion<"invoice" | "settlement", [import("convex/values").VLiteral<"settlement", "required">, import("convex/values").VLiteral<"invoice", "required">], "required", never>;
+    sourceId: import("convex/values").VString<string, "required">;
+    sourceGross: import("convex/values").VFloat64<number | undefined, "optional">;
+    sourceProcessingFee: import("convex/values").VFloat64<number | undefined, "optional">;
+    maxDebit: import("convex/values").VFloat64<number, "required">;
+    maxCredit: import("convex/values").VFloat64<number, "required">;
+    operationKey: import("convex/values").VString<string, "required">;
+    limit: import("convex/values").VFloat64<number | undefined, "optional">;
+}, "required", "accountId" | "currency" | "groupKey" | "limit" | "maxCredit" | "maxDebit" | "operationKey" | "scopeKey" | "sourceGross" | "sourceId" | "sourceKind" | "sourceProcessingFee">;
+export declare function reserveGroup(ctx: MutationCtx, args: Infer<typeof _reserveArgs>): 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;
+        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 sealGroup(ctx: MutationCtx, args: {
+    groupKey: string;
+}): Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"recoveryGroups">;
+    accountId: string;
+    amount: number;
+    currency: string;
+    groupKey: string;
+    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 {};
+//# sourceMappingURL=reservations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reservations.d.ts","sourceRoot":"","sources":["../../../src/component/costRecovery/reservations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAY3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;4LAAwB,CAAC;AAC3C,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,KAAK,CAAC,OAAO,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyIjC;AACD,wBAAsB,SAAS,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;GAQ3E"}

package/dist/component/costRecovery/reservations.js

@@ -0,0 +1,134 @@
+import { v } from "convex/values";
+import { reserveArgs } from "./schema.js";
+import { balance, batchLimit, getGroup, groupTarget, integer, sign, validateScope, } from "./helpers.js";
+const _reserveArgs = v.object(reserveArgs);
+export async function reserveGroup(ctx, args) {
+    validateScope(args);
+    const limit = args.limit ?? 100;
+    batchLimit(limit);
+    [args.maxDebit, args.maxCredit].forEach(integer);
+    if (!args.groupKey.trim() ||
+        !args.operationKey.trim() ||
+        !args.sourceId ||
+        args.maxDebit < 0 ||
+        args.maxCredit < 0)
+        throw new Error("Invalid recovery operation identity or limits.");
+    if (args.sourceGross !== undefined && integer(args.sourceGross) <= 0)
+        throw new Error("Funding gross must be positive.");
+    if (args.sourceProcessingFee !== undefined &&
+        integer(args.sourceProcessingFee) < 0)
+        throw new Error("Funding processing fee must be nonnegative.");
+    if (args.sourceKind === "settlement" &&
+        (!args.sourceGross || args.sourceProcessingFee === undefined))
+        throw new Error("Settlement recovery requires original funding gross.");
+    let group = await ctx.db
+        .query("recoveryGroups")
+        .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
+        .unique();
+    const existing = await ctx.db
+        .query("recoveryReservations")
+        .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+        .unique();
+    if (group)
+        for (const key of [
+            "accountId",
+            "scopeKey",
+            "currency",
+            "sourceKind",
+            "sourceId",
+            "sourceGross",
+            "sourceProcessingFee",
+            "maxDebit",
+            "maxCredit",
+        ])
+            if (group[key] !== args[key])
+                throw new Error("Recovery group identity and limits cannot change.");
+    if (existing) {
+        if (existing.groupKey !== args.groupKey ||
+            existing.limit !== limit ||
+            !group)
+            throw new Error("Recovery operation identity cannot change.");
+        return { reservation: existing, group };
+    }
+    const ledger = await balance(ctx, args);
+    if (ledger.activeGroupKey && ledger.activeGroupKey !== args.groupKey)
+        throw new Error("Another recovery boundary is pending.");
+    if (group && group.status !== "open")
+        throw new Error("Recovery group is sealed; replay its existing operations.");
+    if (!group) {
+        const { operationKey: _operationKey, limit: _limit, ...input } = args;
+        const id = await ctx.db.insert("recoveryGroups", {
+            ...input,
+            amount: 0,
+            pendingOperations: 0,
+            status: "open",
+        });
+        group = (await ctx.db.get("recoveryGroups", id));
+    }
+    const delta = integer(groupTarget(group, ledger.outstanding) - group.amount);
+    const direction = sign(delta);
+    let remaining = Math.abs(delta), amount = 0;
+    const allocations = [];
+    if (direction !== "zero") {
+        const claims = await ctx.db
+            .query("recoveryClaims")
+            .withIndex("by_sign", (q) => q
+            .eq("accountId", args.accountId)
+            .eq("scopeKey", args.scopeKey)
+            .eq("currency", args.currency)
+            .eq("sign", direction))
+            .take(limit);
+        for (const claim of claims) {
+            if (!remaining)
+                break;
+            const take = Math.min(remaining, Math.abs(claim.outstanding)) * (delta < 0 ? -1 : 1);
+            const reservedAmount = integer(claim.reservedAmount + take), outstanding = integer(claim.outstanding - take);
+            await ctx.db.patch("recoveryClaims", claim._id, {
+                reservedAmount,
+                outstanding,
+                sign: sign(outstanding),
+            });
+            allocations.push({
+                claimId: claim._id,
+                claimKey: claim.claimKey,
+                amount: take,
+            });
+            amount = integer(amount + take);
+            remaining -= Math.abs(take);
+        }
+    }
+    const reservationId = await ctx.db.insert("recoveryReservations", {
+        operationKey: args.operationKey,
+        groupKey: args.groupKey,
+        amount,
+        limit,
+        allocations,
+        status: allocations.length ? "reserved" : "empty",
+    });
+    if (allocations.length) {
+        await ctx.db.patch("recoveryBalances", ledger._id, {
+            reservedAmount: integer(ledger.reservedAmount + amount),
+            outstanding: integer(ledger.outstanding - amount),
+            activeGroupKey: group.groupKey,
+        });
+        await ctx.db.patch("recoveryGroups", group._id, {
+            amount: integer(group.amount + amount),
+            pendingOperations: group.pendingOperations + 1,
+        });
+    }
+    return {
+        reservation: (await ctx.db.get("recoveryReservations", reservationId)),
+        group: (await ctx.db.get("recoveryGroups", group._id)),
+    };
+}
+export async function sealGroup(ctx, args) {
+    const group = await getGroup(ctx, args.groupKey);
+    if (group.status !== "open")
+        return group;
+    const ledger = await balance(ctx, group);
+    if (groupTarget(group, ledger.outstanding) !== group.amount)
+        throw new Error("Recovery needs another reservation batch before sealing.");
+    await ctx.db.patch("recoveryGroups", group._id, { status: "sealed" });
+    return (await ctx.db.get("recoveryGroups", group._id));
+}
+//# sourceMappingURL=reservations.js.map