@crewhaus/tool-money 0.7.0

package/dist/lib/allocate.js

@@ -0,0 +1,145 @@
+/**
+ * Splitting money without losing or inventing any.
+ *
+ * Allocating an order-level discount across lines, or tax across returned
+ * items, is the place cents go missing: divide, round each share, and the
+ * shares no longer sum to what you started with. The refund is then a cent
+ * short, or a cent over, and the ledger does not balance.
+ *
+ * Largest-remainder allocation fixes that by construction: the shares always
+ * sum to the total, exactly, whatever the weights.
+ */
+/**
+ * Split `totalMinor` across `weights` so the parts sum to it exactly.
+ *
+ * Each part is the floor of its exact share; the leftover units go to the
+ * largest remainders, ties broken by position so the answer is stable. With
+ * all-zero weights the total is spread evenly from the front rather than
+ * dropped, since dropping it would silently lose the money.
+ */
+export function allocateProportional(totalMinor, weights) {
+    if (!Number.isInteger(totalMinor))
+        throw new Error("totalMinor must be an integer");
+    if (weights.length === 0)
+        return [];
+    if (weights.some((w) => w < 0))
+        throw new Error("weights must not be negative");
+    const sum = weights.reduce((a, b) => a + b, 0);
+    const negative = totalMinor < 0;
+    const magnitude = Math.abs(totalMinor);
+    if (sum === 0) {
+        // Nothing to weigh by. Spread evenly rather than returning zeros, which
+        // would drop the amount entirely.
+        const base = Math.floor(magnitude / weights.length);
+        const parts = weights.map(() => base);
+        let leftover = magnitude - base * weights.length;
+        for (let i = 0; leftover > 0; i = (i + 1) % weights.length, leftover--) {
+            parts[i] = parts[i] + 1;
+        }
+        return negative ? parts.map((p) => -p) : parts;
+    }
+    const exact = weights.map((w) => (magnitude * w) / sum);
+    const parts = exact.map((value) => Math.floor(value));
+    let leftover = magnitude - parts.reduce((a, b) => a + b, 0);
+    const order = exact
+        .map((value, index) => ({ index, remainder: value - Math.floor(value) }))
+        .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
+    for (let i = 0; leftover > 0; i++, leftover--) {
+        const target = order[i % order.length]?.index;
+        parts[target] = parts[target] + 1;
+    }
+    return negative ? parts.map((p) => -p) : parts;
+}
+export const SHIPPING_POLICIES = ["none", "proportional", "full"];
+/**
+ * What to refund for a partial return.
+ *
+ * Both allocations are proportional to what the customer actually paid for
+ * the returned units: an order-level discount applies to them in the same
+ * proportion it applied to the order, and tax follows the discounted amount.
+ * Refunding the list price of a discounted item refunds more than was taken.
+ */
+export function computeRefund(lines, returned, options = {}) {
+    const index = new Map(lines.map((l) => [l.id, l]));
+    for (const item of returned) {
+        const line = index.get(item.lineId);
+        if (!line)
+            throw new Error(`returned line "${item.lineId}" is not in the order`);
+        if (!Number.isInteger(item.quantity) || item.quantity <= 0) {
+            throw new Error(`returned line "${item.lineId}" has quantity ${item.quantity}; it must be a positive integer`);
+        }
+        if (item.quantity > line.quantity) {
+            throw new Error(`returned line "${item.lineId}" returns ${item.quantity} of ${line.quantity} ordered`);
+        }
+    }
+    // The order discount is spread over ALL lines by their net value, then the
+    // returned fraction of each line's share comes back. Spreading it over the
+    // returned lines only would refund the whole discount on a partial return.
+    const lineNet = lines.map((l) => l.quantity * l.unitPriceMinor - (l.discountMinor ?? 0));
+    const orderDiscountShares = allocateProportional(options.orderDiscountMinor ?? 0, lineNet);
+    const shareByLine = new Map(lines.map((l, i) => [l.id, orderDiscountShares[i]]));
+    const results = [];
+    for (const item of returned) {
+        const line = index.get(item.lineId);
+        const fraction = [item.quantity, line.quantity];
+        const gross = line.unitPriceMinor * item.quantity;
+        const lineDiscount = splitByQuantity(line.discountMinor ?? 0, fraction);
+        const orderDiscount = splitByQuantity(shareByLine.get(line.id) ?? 0, fraction);
+        const tax = splitByQuantity(line.taxMinor ?? 0, fraction);
+        results.push({
+            lineId: line.id,
+            quantity: item.quantity,
+            grossMinor: gross,
+            lineDiscountMinor: lineDiscount,
+            orderDiscountMinor: orderDiscount,
+            taxMinor: tax,
+            refundMinor: gross - lineDiscount - orderDiscount + tax,
+        });
+    }
+    const fullReturn = lines.every((l) => (returned.find((r) => r.lineId === l.id)?.quantity ?? 0) === l.quantity);
+    const policy = options.shippingPolicy ?? "none";
+    const shippingTotal = options.shippingMinor ?? 0;
+    let shippingMinor = 0;
+    if (policy === "full" || (policy === "proportional" && fullReturn)) {
+        shippingMinor = shippingTotal;
+    }
+    else if (policy === "proportional") {
+        // Spread the shipping over EVERY line by its value, then take only the
+        // returned fraction of each share. Allocating across the returned lines
+        // and summing the parts gives back the whole amount every time — an
+        // allocation's parts always sum to what was allocated — so a one-item
+        // return refunded the entire shipping charge.
+        const shares = allocateProportional(shippingTotal, lines.map((l) => l.quantity * l.unitPriceMinor));
+        shippingMinor = lines.reduce((total, line, i) => {
+            const returnedQuantity = returned.find((r) => r.lineId === line.id)?.quantity ?? 0;
+            if (returnedQuantity === 0)
+                return total;
+            return total + splitByQuantity(shares[i], [returnedQuantity, line.quantity]);
+        }, 0);
+    }
+    const subtotalMinor = results.reduce((s, r) => s + r.grossMinor - r.lineDiscountMinor - r.orderDiscountMinor, 0);
+    const taxMinor = results.reduce((s, r) => s + r.taxMinor, 0);
+    const restockingFeeMinor = options.restockingFeeMinor ?? 0;
+    return {
+        lines: results,
+        shippingMinor,
+        restockingFeeMinor,
+        subtotalMinor,
+        taxMinor,
+        totalMinor: subtotalMinor + taxMinor + shippingMinor - restockingFeeMinor,
+        fullReturn,
+    };
+}
+/**
+ * The returned fraction of a line-level amount.
+ *
+ * Allocating across the line's units and summing the returned ones — rather
+ * than multiplying by a fraction and rounding — is what makes the parts of a
+ * fully returned line add back up to the whole.
+ */
+function splitByQuantity(amountMinor, [returned, total]) {
+    if (total <= 0 || amountMinor === 0)
+        return 0;
+    const perUnit = allocateProportional(amountMinor, new Array(total).fill(1));
+    return perUnit.slice(0, returned).reduce((a, b) => a + b, 0);
+}

package/dist/lib/coding.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Code invoice lines to a GL account and cost centre from operator rules.
+ *
+ * Most lines on most invoices are routine and code the same way every month.
+ * Spending a model turn on each one costs tokens and, worse, produces a
+ * coding nobody can reproduce at year end. Rules code the routine ones
+ * identically forever and leave the genuinely unclear ones in a review
+ * queue, which is the only part a person should see.
+ *
+ * Conditions are `@crewhaus/tool-schema`'s check grammar, the same one
+ * `Assert` and `Branch` use.
+ */
+import { type Check } from "@crewhaus/tool-schema";
+export type CodingRule = {
+    readonly id: string;
+    readonly when: ReadonlyArray<Check>;
+    readonly account: string;
+    readonly costCenter?: string;
+    readonly taxCode?: string;
+    /** Higher wins when several rules match. Defaults to 0. */
+    readonly priority?: number;
+};
+export type CodedLine = {
+    readonly lineId: string;
+    readonly account: string | null;
+    readonly costCenter: string | null;
+    readonly taxCode: string | null;
+    /** Rule ids that matched, highest priority first. */
+    readonly matched: ReadonlyArray<string>;
+    /** True when more than one rule matched at the winning priority. */
+    readonly ambiguous: boolean;
+    readonly needsReview: boolean;
+    readonly reason: string;
+};
+export type CodingResult = {
+    readonly lines: ReadonlyArray<CodedLine>;
+    readonly coded: number;
+    readonly needsReview: number;
+    readonly version: string | null;
+    readonly byAccount: ReadonlyArray<{
+        readonly account: string;
+        readonly lines: number;
+    }>;
+};
+export declare function codeLines(lines: ReadonlyArray<{
+    readonly id: string;
+} & Record<string, unknown>>, rules: ReadonlyArray<CodingRule>, options?: {
+    readonly version?: string;
+    readonly defaultAccount?: string;
+}): CodingResult;

package/dist/lib/coding.js

@@ -0,0 +1,80 @@
+/**
+ * Code invoice lines to a GL account and cost centre from operator rules.
+ *
+ * Most lines on most invoices are routine and code the same way every month.
+ * Spending a model turn on each one costs tokens and, worse, produces a
+ * coding nobody can reproduce at year end. Rules code the routine ones
+ * identically forever and leave the genuinely unclear ones in a review
+ * queue, which is the only part a person should see.
+ *
+ * Conditions are `@crewhaus/tool-schema`'s check grammar, the same one
+ * `Assert` and `Branch` use.
+ */
+import { runChecks } from "@crewhaus/tool-schema";
+export function codeLines(lines, rules, options = {}) {
+    const seen = new Set();
+    for (const rule of rules) {
+        if (rule.when.length === 0) {
+            throw new Error(`rule "${rule.id}" has no conditions, so it would code every line`);
+        }
+        if (seen.has(rule.id))
+            throw new Error(`two rules share the id "${rule.id}"`);
+        seen.add(rule.id);
+    }
+    const results = [];
+    for (const line of lines) {
+        const matches = rules
+            .filter((rule) => runChecks(line, rule.when).ok)
+            .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        if (matches.length === 0) {
+            results.push({
+                lineId: line.id,
+                account: options.defaultAccount ?? null,
+                costCenter: null,
+                taxCode: null,
+                matched: [],
+                ambiguous: false,
+                // A default account is a place to put it, not a coding decision, so
+                // the line still goes to review rather than quietly landing in a
+                // suspense account nobody looks at.
+                needsReview: true,
+                reason: "no rule matched",
+            });
+            continue;
+        }
+        const top = matches[0];
+        const topPriority = top.priority ?? 0;
+        const tied = matches.filter((r) => (r.priority ?? 0) === topPriority);
+        // Two rules at the same priority disagreeing is a rule-set bug. Picking
+        // one would hide it, and the wrong account is found in an audit, not in
+        // a test.
+        const conflicting = tied.some((r) => r.account !== top.account);
+        results.push({
+            lineId: line.id,
+            account: conflicting ? null : top.account,
+            costCenter: conflicting ? null : (top.costCenter ?? null),
+            taxCode: conflicting ? null : (top.taxCode ?? null),
+            matched: matches.map((r) => r.id),
+            ambiguous: conflicting,
+            needsReview: conflicting,
+            reason: conflicting
+                ? `rules ${tied.map((r) => `"${r.id}"`).join(", ")} match at the same priority and disagree on the account`
+                : "",
+        });
+    }
+    const tally = new Map();
+    for (const line of results) {
+        if (line.account === null || line.needsReview)
+            continue;
+        tally.set(line.account, (tally.get(line.account) ?? 0) + 1);
+    }
+    return {
+        lines: results,
+        coded: results.filter((l) => !l.needsReview).length,
+        needsReview: results.filter((l) => l.needsReview).length,
+        version: options.version ?? null,
+        byAccount: [...tally.entries()]
+            .map(([account, count]) => ({ account, lines: count }))
+            .sort((a, b) => b.lines - a.lines || (a.account < b.account ? -1 : 1)),
+    };
+}

package/dist/lib/controls.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Spending controls and refund-abuse signals.
+ *
+ * An unattended harness that can move money needs a limit it cannot talk
+ * itself past. A limit a model is asked to respect is a suggestion; a limit
+ * computed from the record of what has already been spent is a limit.
+ *
+ * Both functions take the history as an argument and the clock as a
+ * parameter. Nothing here reads a database or the time, so the same facts
+ * always give the same verdict — which is what makes a refusal explicable
+ * afterwards.
+ */
+export type Spend = {
+    readonly id: string;
+    /** ISO-8601 with an offset. */
+    readonly at: string;
+    readonly amountMinor: number;
+    readonly counterparty?: string;
+};
+export type SpendLimits = {
+    /** Largest single payment allowed. */
+    readonly perTransactionMinor?: number;
+    readonly perHourMinor?: number;
+    readonly perDayMinor?: number;
+    readonly perWeekMinor?: number;
+    /** Cap on the total to any one counterparty within the day window. */
+    readonly perCounterpartyPerDayMinor?: number;
+    readonly maxTransactionsPerHour?: number;
+    /**
+     * Hours during which nothing may move, as UTC hours 0-23. The window is
+     * about when a human could notice, so it is deliberately absolute rather
+     * than local to anybody.
+     */
+    readonly quietHoursUtc?: ReadonlyArray<number>;
+    /** Payments to a counterparty never paid before are refused. */
+    readonly knownCounterpartiesOnly?: boolean;
+    readonly knownCounterparties?: ReadonlyArray<string>;
+};
+export type SpendDecision = {
+    readonly allowed: boolean;
+    /** Every limit the payment breaks, not just the first. */
+    readonly violations: ReadonlyArray<{
+        readonly limit: string;
+        readonly capMinor: number | null;
+        readonly wouldBeMinor: number | null;
+        readonly detail: string;
+    }>;
+    readonly windows: Readonly<Record<string, number>>;
+    readonly headroomMinor: number | null;
+};
+export declare function checkSpendLimit(proposed: {
+    readonly amountMinor: number;
+    readonly counterparty?: string;
+}, history: ReadonlyArray<Spend>, limits: SpendLimits, nowMs: number): SpendDecision;
+export type RefundEvent = {
+    readonly id: string;
+    readonly at: string;
+    readonly amountMinor: number;
+    readonly reason?: string;
+    readonly replacement?: boolean;
+};
+export type OrderEvent = {
+    readonly id: string;
+    readonly at: string;
+    readonly amountMinor: number;
+};
+export type AbuseSignals = {
+    readonly windows: ReadonlyArray<{
+        readonly days: number;
+        readonly refunds: number;
+        readonly refundedMinor: number;
+        readonly orders: number;
+        readonly spentMinor: number;
+        /** Refunded over spent, in basis points. 10000 is everything. */
+        readonly ratioBps: number | null;
+    }>;
+    readonly replacements: number;
+    readonly nonDeliveryClaims: number;
+    readonly flags: ReadonlyArray<string>;
+};
+/**
+ * Refund-abuse signals over fixed windows.
+ *
+ * This reports ratios and counts. It does not decide that somebody is a
+ * fraudster, and the tool that wraps it must not present it as if it had —
+ * a high ratio is also what a customer with one broken delivery looks like.
+ */
+export declare function refundAbuseSignals(refunds: ReadonlyArray<RefundEvent>, orders: ReadonlyArray<OrderEvent>, nowMs: number, thresholds?: {
+    readonly ratioBps?: number;
+    readonly refundCount?: number;
+}): AbuseSignals;

package/dist/lib/controls.js

@@ -0,0 +1,174 @@
+/**
+ * Spending controls and refund-abuse signals.
+ *
+ * An unattended harness that can move money needs a limit it cannot talk
+ * itself past. A limit a model is asked to respect is a suggestion; a limit
+ * computed from the record of what has already been spent is a limit.
+ *
+ * Both functions take the history as an argument and the clock as a
+ * parameter. Nothing here reads a database or the time, so the same facts
+ * always give the same verdict — which is what makes a refusal explicable
+ * afterwards.
+ */
+function instant(value, what) {
+    if (!/(?:Z|[+-]\d{2}:?\d{2})$/i.test(value.trim())) {
+        throw new Error(`${what} ("${value}") has no UTC offset`);
+    }
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed))
+        throw new Error(`${what} ("${value}") is not a valid ISO-8601 instant`);
+    return parsed;
+}
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+export function checkSpendLimit(proposed, history, limits, nowMs) {
+    const entries = history.map((s) => ({ ...s, atMs: instant(s.at, `spend "${s.id}" at`) }));
+    const since = (ms) => entries.filter((e) => nowMs - e.atMs < ms && e.atMs <= nowMs);
+    const sum = (list) => list.reduce((t, e) => t + e.amountMinor, 0);
+    const hour = since(HOUR);
+    const day = since(DAY);
+    const week = since(WEEK);
+    const windows = {
+        hourMinor: sum(hour),
+        dayMinor: sum(day),
+        weekMinor: sum(week),
+        hourCount: hour.length,
+    };
+    const violations = [];
+    const check = (name, cap, spent) => {
+        if (cap === undefined)
+            return;
+        const wouldBe = spent + proposed.amountMinor;
+        if (wouldBe > cap) {
+            violations.push({
+                limit: name,
+                capMinor: cap,
+                wouldBeMinor: wouldBe,
+                detail: `${spent} already spent in this window, ${proposed.amountMinor} proposed, cap ${cap}`,
+            });
+        }
+    };
+    if (limits.perTransactionMinor !== undefined &&
+        proposed.amountMinor > limits.perTransactionMinor) {
+        violations.push({
+            limit: "perTransaction",
+            capMinor: limits.perTransactionMinor,
+            wouldBeMinor: proposed.amountMinor,
+            detail: `a single payment of ${proposed.amountMinor} is over the ${limits.perTransactionMinor} ceiling`,
+        });
+    }
+    check("perHour", limits.perHourMinor, windows.hourMinor);
+    check("perDay", limits.perDayMinor, windows.dayMinor);
+    check("perWeek", limits.perWeekMinor, windows.weekMinor);
+    if (limits.perCounterpartyPerDayMinor !== undefined && proposed.counterparty !== undefined) {
+        const spent = sum(day.filter((e) => e.counterparty === proposed.counterparty));
+        check(`perCounterpartyPerDay:${proposed.counterparty}`, limits.perCounterpartyPerDayMinor, spent);
+    }
+    if (limits.maxTransactionsPerHour !== undefined &&
+        windows.hourCount + 1 > limits.maxTransactionsPerHour) {
+        violations.push({
+            limit: "maxTransactionsPerHour",
+            capMinor: null,
+            wouldBeMinor: null,
+            detail: `${windows.hourCount} payments in the last hour, cap ${limits.maxTransactionsPerHour}`,
+        });
+    }
+    if (limits.quietHoursUtc && limits.quietHoursUtc.length > 0) {
+        const hourUtc = new Date(nowMs).getUTCHours();
+        if (limits.quietHoursUtc.includes(hourUtc)) {
+            violations.push({
+                limit: "quietHours",
+                capMinor: null,
+                wouldBeMinor: null,
+                detail: `${hourUtc}:00 UTC is inside the quiet window, when nobody is watching`,
+            });
+        }
+    }
+    if (limits.knownCounterpartiesOnly) {
+        // When the operator supplies a list, that list IS the allow-list.
+        //
+        // Deriving "known" from payment history as well looked like a
+        // convenience and was a hole: one payment that got through by any means
+        // added its counterparty to the allow-list permanently, so the control
+        // stopped exactly one payment and then approved every one after it. A
+        // control that weakens itself the first time it is defeated is not a
+        // control.
+        //
+        // With no list supplied there is nothing else to go on, so history is
+        // used — a weaker rule, and one the result names.
+        const known = new Set(limits.knownCounterparties && limits.knownCounterparties.length > 0
+            ? limits.knownCounterparties
+            : entries.map((e) => e.counterparty).filter((c) => c !== undefined));
+        const basis = limits.knownCounterparties && limits.knownCounterparties.length > 0
+            ? "the declared allow-list"
+            : "counterparties paid before, since no allow-list was declared";
+        if (proposed.counterparty === undefined || !known.has(proposed.counterparty)) {
+            violations.push({
+                limit: "knownCounterpartiesOnly",
+                capMinor: null,
+                wouldBeMinor: null,
+                detail: proposed.counterparty === undefined
+                    ? "the payment names no counterparty, and only known ones are allowed"
+                    : `"${proposed.counterparty}" is not in ${basis}`,
+            });
+        }
+    }
+    // Headroom is the tightest remaining amount limit, which is the number a
+    // caller needs to propose something that would pass.
+    const caps = [
+        limits.perTransactionMinor,
+        limits.perHourMinor === undefined ? undefined : limits.perHourMinor - windows.hourMinor,
+        limits.perDayMinor === undefined ? undefined : limits.perDayMinor - windows.dayMinor,
+        limits.perWeekMinor === undefined ? undefined : limits.perWeekMinor - windows.weekMinor,
+    ].filter((v) => v !== undefined);
+    return {
+        allowed: violations.length === 0,
+        violations,
+        windows,
+        headroomMinor: caps.length === 0 ? null : Math.max(0, Math.min(...caps)),
+    };
+}
+/**
+ * Refund-abuse signals over fixed windows.
+ *
+ * This reports ratios and counts. It does not decide that somebody is a
+ * fraudster, and the tool that wraps it must not present it as if it had —
+ * a high ratio is also what a customer with one broken delivery looks like.
+ */
+export function refundAbuseSignals(refunds, orders, nowMs, thresholds = {}) {
+    const windows = [30, 90, 365].map((days) => {
+        const cutoff = nowMs - days * DAY;
+        const r = refunds.filter((x) => instant(x.at, `refund "${x.id}" at`) >= cutoff);
+        const o = orders.filter((x) => instant(x.at, `order "${x.id}" at`) >= cutoff);
+        const refundedMinor = r.reduce((s, x) => s + x.amountMinor, 0);
+        const spentMinor = o.reduce((s, x) => s + x.amountMinor, 0);
+        return {
+            days,
+            refunds: r.length,
+            refundedMinor,
+            orders: o.length,
+            spentMinor,
+            // Undefined rather than infinite when nothing was spent: a ratio
+            // against zero is not a large number, it is not a number.
+            ratioBps: spentMinor === 0 ? null : Math.round((refundedMinor * 10_000) / spentMinor),
+        };
+    });
+    const flags = [];
+    const ratioCap = thresholds.ratioBps;
+    const countCap = thresholds.refundCount;
+    for (const w of windows) {
+        if (ratioCap !== undefined && w.ratioBps !== null && w.ratioBps > ratioCap) {
+            flags.push(`refunded ${(w.ratioBps / 100).toFixed(1)}% of spend in ${w.days} days`);
+        }
+        if (countCap !== undefined && w.refunds > countCap) {
+            flags.push(`${w.refunds} refunds in ${w.days} days`);
+        }
+    }
+    return {
+        windows,
+        replacements: refunds.filter((r) => r.replacement).length,
+        nonDeliveryClaims: refunds.filter((r) => /not.?(delivered|received)|never arrived|missing/i.test(r.reason ?? "")).length,
+        flags,
+    };
+}

package/dist/lib/identifiers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Payment identifier validation.
+ *
+ * Every one of these carries a checksum precisely so a typo is caught before
+ * money moves, and every one of them is arithmetic — there is nothing for a
+ * model to judge. Getting it wrong is expensive in a way that most wrong
+ * answers are not, so each algorithm here is the published one and the tests
+ * use published vectors.
+ *
+ * A valid checksum means the identifier is well-formed. It does not mean the
+ * account exists, is open, or belongs to who you think. Nothing here reaches
+ * a network, and the result says as much.
+ */
+export declare const IDENTIFIER_KINDS: readonly ["iban", "bic", "aba", "card", "sortcode"];
+export type IdentifierKind = (typeof IDENTIFIER_KINDS)[number];
+export type IdentifierResult = {
+    readonly kind: IdentifierKind;
+    readonly valid: boolean;
+    /** The canonical form: spacing removed, case normalized. */
+    readonly normalized: string;
+    /** How it should be shown to a person, where a convention exists. */
+    readonly formatted: string;
+    /** Empty when valid; otherwise the specific thing that is wrong. */
+    readonly reason: string;
+    /** Whatever the identifier itself encodes — country, bank, check digits. */
+    readonly parts: Readonly<Record<string, string>>;
+};
+export declare function validateIban(raw: string): IdentifierResult;
+export declare function validateBic(raw: string): IdentifierResult;
+/** ABA routing number: a weighted sum over nine digits, 3-7-1 repeating. */
+export declare function validateAba(raw: string): IdentifierResult;
+/** Luhn, as used by payment cards. */
+export declare function luhnOk(digits: string): boolean;
+/**
+ * Validate a card number's checksum.
+ *
+ * Only the last four digits are ever echoed. A validator that returned the
+ * number it was given would take a value the caller has to protect and copy
+ * it into a log, a transcript and a model's context.
+ */
+export declare function validateCard(raw: string): IdentifierResult;
+/** UK sort code: six digits, and no checksum exists to check. */
+export declare function validateSortCode(raw: string): IdentifierResult;
+/** Guess which kind an identifier is, for callers that do not know. */
+export declare function detectKind(raw: string): IdentifierKind | null;
+export declare function validateIdentifier(raw: string, kind: IdentifierKind): IdentifierResult;