@crewhaus/tool-notify 0.7.0

package/dist/lib/preflight.js

@@ -0,0 +1,291 @@
+/**
+ * The questions worth asking about a message BEFORE a socket opens.
+ *
+ * `EmailSend` refuses a message it cannot build, and refuses it one reason
+ * at a time, at the moment the caller has already decided to send. That is
+ * the right behaviour for a send and the wrong one for a check: what a
+ * caller wants before committing is every reason at once, including the ones
+ * that are not refusals at all - an empty body, a subject still carrying
+ * `{{release}}`, the same mailbox on both To and Bcc.
+ *
+ * So the rules live here, pure, and the tool composes them. Two properties
+ * keep the result honest:
+ *
+ *   - **The composer stays the authority.** Everything here is a report;
+ *     the real `composeMessage` runs afterwards and its verdict is the one
+ *     that decides whether the message can be built at all. Where a rule
+ *     below and the composer ask the same question - a header name, a
+ *     message id - they call the SAME predicate out of `./mime`, because a
+ *     preflight that passes against its own copy of a rule and a send that
+ *     then refuses is a preflight nobody can act on.
+ *   - **A check that could not run says so.** `unknown` is a status, not an
+ *     absent `fail`. An attachment that could not be read and an attachment
+ *     that is fine are different answers, and only one of them means the
+ *     message is ready.
+ */
+import { isMessageId, isReservedHeaderName, isValidAddress, isValidHeaderName } from "./mime";
+import { templatePlaceholders } from "./template";
+/** Locale-free order, so two runs list the same faults in the same place. */
+function byString(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** A value a header or a body can hold and still be empty. */
+const isBlank = (text) => text.trim() === "";
+/**
+ * The comparison key for "is this the same mailbox twice".
+ *
+ * Case only, deliberately. Gmail folds `a.b@` and `ab@` to one mailbox and
+ * strips `+tags`; most providers do neither, so folding them here would
+ * report two genuinely separate recipients as one duplicate on every domain
+ * that keeps them apart. Which domains fold is configuration this package
+ * does not carry, so the narrow, always-true rule is the one implemented -
+ * and it never rewrites an address, only the key two addresses are compared
+ * on.
+ */
+const mailboxKey = (address) => address.trim().toLowerCase();
+/**
+ * How the envelope folds, counted the way the composer counts it.
+ *
+ * The trap this exists to avoid: comparing on a case-folded key and then
+ * reporting a conclusion about a composer that de-duplicates on the exact
+ * string. `ops@example.com` on To and `OPS@example.com` on Bcc is ONE
+ * mailbox by the key above and TWO entries in `composeMessage`'s envelope
+ * Set, so "it will be sent one copy, not two" is false for exactly that
+ * case - which is the case a caller runs a preflight to find. Both facts are
+ * returned so the caller is told which one applies, and the count reported
+ * is the composer's, never the key's.
+ */
+export function envelopeFolding(lists) {
+    const groups = new Map();
+    for (const list of lists) {
+        for (const mailbox of list) {
+            const key = mailboxKey(mailbox.address);
+            const spellings = groups.get(key);
+            if (spellings === undefined)
+                groups.set(key, [mailbox.address]);
+            else
+                spellings.push(mailbox.address);
+        }
+    }
+    const folded = [];
+    const variants = [];
+    let envelopeSize = 0;
+    for (const [key, spellings] of groups) {
+        const distinct = [...new Set(spellings)].sort(byString);
+        envelopeSize += distinct.length;
+        if (spellings.length > distinct.length)
+            folded.push(key);
+        if (distinct.length > 1)
+            variants.push(distinct);
+    }
+    return {
+        folded: folded.sort(byString),
+        // Sorted by first spelling, so two runs list the groups in one order.
+        variants: variants.sort((a, b) => byString(a[0], b[0])),
+        envelopeSize,
+    };
+}
+/** `{{placeholder}}` names still standing in the text a recipient would read. */
+export function leftoverPlaceholders(draft) {
+    const names = new Set();
+    for (const field of [draft.subject, draft.text, draft.html ?? ""]) {
+        for (const name of templatePlaceholders(field))
+            names.add(name);
+    }
+    return [...names].sort(byString);
+}
+function checkSender(draft) {
+    if (!isValidAddress(draft.from.address)) {
+        return {
+            check: "sender",
+            status: "fail",
+            // The address is echoed with its line breaks escaped: an unparseable
+            // From is usually unparseable for a reason worth seeing.
+            detail: `From "${draft.from.address.replace(/[\r\n]/g, "\\n")}" is not a deliverable addr-spec, so there is no sender and no domain to build a Message-ID from`,
+        };
+    }
+    return {
+        check: "sender",
+        status: "pass",
+        detail: `From is ${draft.from.address}`,
+    };
+}
+function checkEnvelope(draft) {
+    const all = [...draft.to, ...draft.cc, ...draft.bcc];
+    if (all.length === 0) {
+        return {
+            check: "envelope",
+            status: "fail",
+            detail: "no recipients: to, cc and bcc are all empty, so there is no envelope to send",
+        };
+    }
+    const bad = all
+        .map((m) => m.address)
+        .filter((address) => !isValidAddress(address))
+        .map((address) => address.replace(/[\r\n]/g, "\\n"))
+        .sort(byString);
+    if (bad.length > 0) {
+        return {
+            check: "envelope",
+            status: "fail",
+            detail: `${bad.length} recipient address${bad.length === 1 ? " is" : "es are"} not deliverable: ${bad.join(", ")}`,
+        };
+    }
+    const replyToBad = draft.replyTo
+        .map((m) => m.address)
+        .filter((address) => !isValidAddress(address))
+        .map((address) => address.replace(/[\r\n]/g, "\\n"))
+        .sort(byString);
+    if (replyToBad.length > 0) {
+        return {
+            check: "envelope",
+            status: "fail",
+            detail: `reply-to is not deliverable: ${replyToBad.join(", ")}`,
+        };
+    }
+    const folding = envelopeFolding([draft.to, draft.cc, draft.bcc]);
+    const size = folding.envelopeSize;
+    const rcpt = `${size} envelope recipient${size === 1 ? "" : "s"}`;
+    // Said in the order of how wrong it can go. A spelling variant is the one
+    // that costs a real second delivery, so it is reported even when an exact
+    // repeat is also present - the caller fixes a different thing for each.
+    if (folding.variants.length > 0) {
+        const groups = folding.variants.map((group) => group.join(" and ")).join("; ");
+        return {
+            check: "envelope",
+            status: "warn",
+            detail: `${rcpt}: ${groups} differ only in case or surrounding space. EmailSend builds its envelope from the exact addresses, so each spelling gets its own RCPT TO and the mailbox is likely to receive one copy per spelling - list it once`,
+        };
+    }
+    if (folding.folded.length > 0) {
+        return {
+            check: "envelope",
+            status: "warn",
+            detail: `${rcpt}: ${folding.folded.join(", ")} ${folding.folded.length === 1 ? "is" : "are"} listed more than once across to/cc/bcc; identical spellings fold into one envelope entry, so one copy is sent, not two`,
+        };
+    }
+    return {
+        check: "envelope",
+        status: "pass",
+        detail: `${rcpt} across to, cc and bcc`,
+    };
+}
+function checkDate(draft) {
+    const when = new Date(draft.date);
+    if (Number.isNaN(when.getTime())) {
+        return {
+            check: "date",
+            status: "fail",
+            detail: `"${draft.date}" is not an instant - use ISO-8601 with an offset, e.g. 2026-09-17T09:30:00Z`,
+        };
+    }
+    return {
+        check: "date",
+        status: "pass",
+        detail: `the Date header will read ${when.toISOString()}`,
+    };
+}
+function checkHeaders(draft) {
+    const faults = [];
+    for (const name of Object.keys(draft.headers ?? {})) {
+        if (!isValidHeaderName(name))
+            faults.push(`"${name}" is not a valid header name`);
+        else if (isReservedHeaderName(name)) {
+            faults.push(`"${name}" is built by the composer and cannot be overridden here`);
+        }
+    }
+    if (draft.inReplyTo !== undefined && draft.inReplyTo !== "" && !isMessageId(draft.inReplyTo)) {
+        faults.push("inReplyTo is not one message id in angle brackets");
+    }
+    for (const reference of draft.references ?? []) {
+        if (!isMessageId(reference)) {
+            faults.push(`references entry "${reference.replace(/[\r\n]/g, "\\n")}" is not a message id in angle brackets`);
+        }
+    }
+    if (faults.length > 0) {
+        // Every fault at once, sorted: the composer stops at the first, and
+        // finding them one send at a time is the experience this tool exists to
+        // replace.
+        return { check: "headers", status: "fail", detail: faults.sort(byString).join("; ") };
+    }
+    const extra = Object.keys(draft.headers ?? {}).length;
+    return {
+        check: "headers",
+        status: "pass",
+        detail: extra === 0 ? "no extra headers" : `${extra} extra header${extra === 1 ? "" : "s"}`,
+    };
+}
+function checkSubject(draft) {
+    if (isBlank(draft.subject)) {
+        return {
+            check: "subject",
+            status: "warn",
+            detail: "the Subject header is empty; it is legal, and it is also one of the things a spam filter scores",
+        };
+    }
+    return { check: "subject", status: "pass", detail: `${draft.subject.length} characters` };
+}
+function checkBody(draft) {
+    const textBlank = isBlank(draft.text);
+    const htmlBlank = draft.html === undefined || isBlank(draft.html);
+    if (textBlank && htmlBlank) {
+        return {
+            check: "body",
+            status: "fail",
+            detail: "the message has no body: text is empty and there is no html alternative. A send would succeed and deliver nothing",
+        };
+    }
+    if (textBlank) {
+        return {
+            check: "body",
+            status: "warn",
+            detail: "text is empty and only the html part carries anything; a client that shows text/plain shows an empty message",
+        };
+    }
+    return {
+        check: "body",
+        status: "pass",
+        detail: htmlBlank
+            ? `${draft.text.length} characters of text`
+            : `${draft.text.length} characters of text and ${draft.html.length} of html`,
+    };
+}
+function checkPlaceholders(draft) {
+    const left = leftoverPlaceholders(draft);
+    if (left.length > 0) {
+        return {
+            check: "placeholders",
+            status: "warn",
+            // MessageTemplate treats a missing key as an error for this reason;
+            // a message that reads "deploy of  failed" still gets acted on.
+            detail: `still unfilled: ${left.map((n) => `{{${n}}}`).join(", ")} - if these came from a template, the render did not happen`,
+        };
+    }
+    return { check: "placeholders", status: "pass", detail: "no unfilled {{placeholders}}" };
+}
+/** Every rule that needs nothing but the draft itself, in a fixed order. */
+export function draftChecks(draft) {
+    return [
+        checkSender(draft),
+        checkEnvelope(draft),
+        checkDate(draft),
+        checkSubject(draft),
+        checkBody(draft),
+        checkHeaders(draft),
+        checkPlaceholders(draft),
+    ];
+}
+/**
+ * The one-word answer, from the rows.
+ *
+ * `incomplete` exists so a check that could not run cannot be mistaken for
+ * one that passed: a message whose attachment could not be read is not ready
+ * to send, and it is not blocked either - somebody has to look.
+ */
+export function verdictFrom(checks) {
+    if (checks.some((c) => c.status === "fail"))
+        return "blocked";
+    if (checks.some((c) => c.status === "unknown"))
+        return "incomplete";
+    return "ready";
+}

package/dist/lib/quiet.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Quiet hours: may this notification go out now, and if not, when?
+ *
+ * The rule this file exists to enforce is that a harness does not wake
+ * somebody at 03:00 for something that will read identically at 09:00. The
+ * rule it exists to NOT break is determinism: nothing here reads the clock.
+ * `now` is an argument, always, so the same question asked twice gets the
+ * same answer and a test can ask about a Sunday in a timezone nobody is in.
+ *
+ * Timezones come from `Intl`, which every runtime this ships on carries with
+ * the full IANA database. That means real DST behaviour rather than a fixed
+ * offset: a window of 22:00–07:00 in `America/New_York` is nine hours in
+ * November and eight on the spring-forward night, which is what the person
+ * asleep experiences.
+ */
+export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+export type QuietWindow = {
+    /** Days the window STARTS on. Omitted means every day. */
+    readonly days?: readonly Weekday[];
+    /** `HH:MM`, 24-hour, in the schedule's timezone. */
+    readonly start: string;
+    /** `HH:MM`. Earlier than `start` means the window wraps past midnight. */
+    readonly end: string;
+};
+export type QuietSchedule = {
+    /** IANA name, e.g. `Europe/Berlin`. */
+    readonly timezone: string;
+    readonly quietWindows: readonly QuietWindow[];
+    /** `YYYY-MM-DD` dates that are quiet all day, in the schedule's timezone. */
+    readonly blackoutDates?: readonly string[];
+};
+export type QuietDecision = {
+    readonly allowed: boolean;
+    readonly reason: string;
+    /** The instant the next non-quiet moment begins, ISO-8601 UTC. */
+    readonly nextAllowed?: string;
+    /** Local wall-clock time of `now` in the schedule's timezone. */
+    readonly localTime: string;
+    readonly localDate: string;
+    readonly localWeekday: Weekday;
+};
+export type QuietError = {
+    readonly error: string;
+};
+/** Minutes past local midnight, or `null` when `text` is not `HH:MM`. */
+export declare function parseClock(text: string): number | null;
+/** Validate a schedule up front, so a bad window is one error and not silence. */
+export declare function validateSchedule(schedule: QuietSchedule): string | null;
+/**
+ * Decide whether a notification may be sent at `nowMs`, and when it may next
+ * be.
+ *
+ * The search is exact rather than sampled: quiet can only end at a window's
+ * end, or at local midnight when a blackout date rolls over, so those are
+ * the only instants examined. Nine days of them is enough to escape any
+ * weekly schedule; a schedule that blacks out more than nine consecutive
+ * days is reported as such rather than answered with a guess.
+ */
+export declare function quietDecision(schedule: QuietSchedule, nowMs: number): QuietDecision | QuietError;

package/dist/lib/quiet.js

@@ -0,0 +1,217 @@
+/**
+ * Quiet hours: may this notification go out now, and if not, when?
+ *
+ * The rule this file exists to enforce is that a harness does not wake
+ * somebody at 03:00 for something that will read identically at 09:00. The
+ * rule it exists to NOT break is determinism: nothing here reads the clock.
+ * `now` is an argument, always, so the same question asked twice gets the
+ * same answer and a test can ask about a Sunday in a timezone nobody is in.
+ *
+ * Timezones come from `Intl`, which every runtime this ships on carries with
+ * the full IANA database. That means real DST behaviour rather than a fixed
+ * offset: a window of 22:00–07:00 in `America/New_York` is nine hours in
+ * November and eight on the spring-forward night, which is what the person
+ * asleep experiences.
+ */
+const WEEKDAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const CLOCK = /^([0-9]{1,2}):([0-9]{2})$/;
+/** Minutes past local midnight, or `null` when `text` is not `HH:MM`. */
+export function parseClock(text) {
+    const match = text.trim().match(CLOCK);
+    if (match === null)
+        return null;
+    const hours = Number.parseInt(match[1], 10);
+    const minutes = Number.parseInt(match[2], 10);
+    if (hours > 24 || minutes > 59)
+        return null;
+    if (hours === 24 && minutes !== 0)
+        return null;
+    return hours * 60 + minutes;
+}
+/** A cached formatter per timezone — building one per call is the slow path. */
+const formatters = new Map();
+function formatterFor(timeZone) {
+    let formatter = formatters.get(timeZone);
+    if (formatter === undefined) {
+        formatter = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            hourCycle: "h23",
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+        });
+        formatters.set(timeZone, formatter);
+    }
+    return formatter;
+}
+/** The wall-clock reading of an instant in a timezone. */
+function zonedParts(instant, timeZone) {
+    const parts = formatterFor(timeZone).formatToParts(new Date(instant));
+    const get = (type) => {
+        const found = parts.find((p) => p.type === type);
+        return found === undefined ? 0 : Number.parseInt(found.value, 10);
+    };
+    return {
+        year: get("year"),
+        month: get("month"),
+        day: get("day"),
+        hour: get("hour"),
+        minute: get("minute"),
+        second: get("second"),
+    };
+}
+/** The zone's UTC offset, in milliseconds, at a given instant. */
+function offsetAt(instant, timeZone) {
+    const z = zonedParts(instant, timeZone);
+    return Date.UTC(z.year, z.month - 1, z.day, z.hour, z.minute, z.second) - instant;
+}
+/**
+ * The instant at which a zone reads a given wall clock.
+ *
+ * Two passes, which is the standard way to invert a zone lookup: guess with
+ * the offset at the naive instant, then correct with the offset at the
+ * guess. A wall time that a DST jump skipped entirely has no instant; the
+ * second pass lands on the moment the clock jumped, which is the earliest
+ * real time at or after the requested one, and that is the right answer for
+ * "when may I send".
+ */
+function instantFor(timeZone, year, month, day, minutesOfDay) {
+    const naive = Date.UTC(year, month - 1, day, 0, 0, 0) + minutesOfDay * 60_000;
+    let instant = naive - offsetAt(naive, timeZone);
+    instant = naive - offsetAt(instant, timeZone);
+    return instant;
+}
+function weekdayOf(z) {
+    const index = new Date(Date.UTC(z.year, z.month - 1, z.day)).getUTCDay();
+    return WEEKDAYS[index];
+}
+function pad(value, width) {
+    return String(value).padStart(width, "0");
+}
+function isoDate(z) {
+    return `${pad(z.year, 4)}-${pad(z.month, 2)}-${pad(z.day, 2)}`;
+}
+/** Validate a schedule up front, so a bad window is one error and not silence. */
+export function validateSchedule(schedule) {
+    try {
+        formatterFor(schedule.timezone);
+    }
+    catch {
+        return `"${schedule.timezone}" is not a timezone this runtime knows — use an IANA name such as Europe/Berlin`;
+    }
+    if (schedule.quietWindows.length === 0 && (schedule.blackoutDates ?? []).length === 0) {
+        return "the schedule has no quiet windows and no blackout dates, so it would never block anything — omit it instead";
+    }
+    for (const window of schedule.quietWindows) {
+        if (parseClock(window.start) === null) {
+            return `quiet window start "${window.start}" is not HH:MM`;
+        }
+        if (parseClock(window.end) === null) {
+            return `quiet window end "${window.end}" is not HH:MM`;
+        }
+        if (parseClock(window.start) === parseClock(window.end)) {
+            return `quiet window "${window.start}"–"${window.end}" is empty; use 00:00–24:00 for a whole day`;
+        }
+        for (const day of window.days ?? []) {
+            if (!WEEKDAYS.includes(day))
+                return `"${day}" is not a weekday name (mon…sun)`;
+        }
+    }
+    for (const date of schedule.blackoutDates ?? []) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+            return `blackout date "${date}" is not YYYY-MM-DD`;
+        }
+    }
+    return null;
+}
+/** Is `instant` inside a quiet window or a blackout date? */
+function isQuiet(schedule, instant) {
+    const z = zonedParts(instant, schedule.timezone);
+    const date = isoDate(z);
+    if ((schedule.blackoutDates ?? []).includes(date))
+        return true;
+    const minutes = z.hour * 60 + z.minute;
+    const today = weekdayOf(z);
+    const yesterday = WEEKDAYS[(WEEKDAYS.indexOf(today) + 6) % 7];
+    for (const window of schedule.quietWindows) {
+        const start = parseClock(window.start);
+        const end = parseClock(window.end);
+        if (start === null || end === null)
+            continue;
+        const days = window.days;
+        const startsToday = days === undefined || days.includes(today);
+        const startedYesterday = days === undefined || days.includes(yesterday);
+        if (start < end) {
+            if (startsToday && minutes >= start && minutes < end)
+                return true;
+        }
+        else {
+            // Wraps past midnight: the tail belongs to the day the window started.
+            if (startsToday && minutes >= start)
+                return true;
+            if (startedYesterday && minutes < end)
+                return true;
+        }
+    }
+    return false;
+}
+/** Days ahead searched for the next allowed moment before giving up. */
+const SEARCH_DAYS = 9;
+/**
+ * Decide whether a notification may be sent at `nowMs`, and when it may next
+ * be.
+ *
+ * The search is exact rather than sampled: quiet can only end at a window's
+ * end, or at local midnight when a blackout date rolls over, so those are
+ * the only instants examined. Nine days of them is enough to escape any
+ * weekly schedule; a schedule that blacks out more than nine consecutive
+ * days is reported as such rather than answered with a guess.
+ */
+export function quietDecision(schedule, nowMs) {
+    const invalid = validateSchedule(schedule);
+    if (invalid !== null)
+        return { error: invalid };
+    const z = zonedParts(nowMs, schedule.timezone);
+    const local = {
+        localTime: `${pad(z.hour, 2)}:${pad(z.minute, 2)}`,
+        localDate: isoDate(z),
+        localWeekday: weekdayOf(z),
+    };
+    if (!isQuiet(schedule, nowMs)) {
+        return { allowed: true, reason: "not inside any quiet window", ...local };
+    }
+    const candidates = new Set();
+    for (let offset = 0; offset <= SEARCH_DAYS; offset++) {
+        const dayStart = new Date(Date.UTC(z.year, z.month - 1, z.day + offset));
+        const year = dayStart.getUTCFullYear();
+        const month = dayStart.getUTCMonth() + 1;
+        const day = dayStart.getUTCDate();
+        candidates.add(instantFor(schedule.timezone, year, month, day, 0));
+        for (const window of schedule.quietWindows) {
+            const end = parseClock(window.end);
+            if (end === null)
+                continue;
+            candidates.add(instantFor(schedule.timezone, year, month, day, end));
+        }
+    }
+    const next = [...candidates]
+        .filter((instant) => instant > nowMs)
+        .sort((a, b) => a - b)
+        .find((instant) => !isQuiet(schedule, instant));
+    if (next === undefined) {
+        return {
+            allowed: false,
+            reason: `inside a quiet window, and no allowed moment was found within ${SEARCH_DAYS} days — check the schedule, which may block continuously`,
+            ...local,
+        };
+    }
+    return {
+        allowed: false,
+        reason: "inside a quiet window",
+        nextAllowed: new Date(next).toISOString(),
+        ...local,
+    };
+}

package/dist/lib/ratelimit.d.ts

@@ -0,0 +1,57 @@
+/**
+ * "Have I already told them about this?" — as a pure function over a state
+ * record the caller keeps.
+ *
+ * A harness that notices the same broken thing on every loop iteration will
+ * notify about it on every loop iteration unless something remembers. That
+ * memory has to live somewhere the harness controls (a KV entry, a file, a
+ * field on its own state) rather than inside a tool, because a tool's
+ * process-local memory dies with the process and the flood comes back after
+ * the first restart. So this takes the state in and hands the next state
+ * back, and the caller persists it wherever its state already lives.
+ *
+ * Fixed windows, not a sliding log. A sliding window needs every timestamp
+ * retained, which grows without bound in exactly the situation the gate
+ * exists for; a fixed window costs two numbers per key and is easy to
+ * reason about out loud ("at most 3 per hour per key").
+ */
+export type RateEntry = {
+    /** Start of the current window, in epoch milliseconds. */
+    readonly windowStart: number;
+    /** How many sends have been recorded in that window. */
+    readonly count: number;
+    /** When the most recent send was recorded. */
+    readonly last: number;
+};
+export type RateState = Readonly<Record<string, RateEntry>>;
+export type RateDecision = {
+    readonly allowed: boolean;
+    readonly reason: string;
+    /** Sends recorded for this key in the current window, after this call. */
+    readonly count: number;
+    readonly limit: number;
+    /** Milliseconds until the window resets. Present only when refused. */
+    readonly retryAfterMs?: number;
+    /** When the window resets, ISO-8601 UTC. Present only when refused. */
+    readonly retryAt?: string;
+    /** The record to persist. Unchanged from the input when refused. */
+    readonly nextState: RateState;
+    /** Keys dropped because their window had long expired. */
+    readonly pruned: readonly string[];
+};
+export type RateOptions = {
+    readonly key: string;
+    readonly nowMs: number;
+    readonly windowMs: number;
+    /** How many sends the window allows. Default 1 — "tell me once". */
+    readonly limit?: number;
+    /**
+     * `"consume"` records the send when it is allowed; `"peek"` answers the
+     * question without changing anything, for a caller that wants to decide
+     * before it has built the message.
+     */
+    readonly mode?: "consume" | "peek";
+    readonly state?: RateState;
+};
+/** Decide, and hand back the record to persist. */
+export declare function rateLimitGate(options: RateOptions): RateDecision;