@foldrun/core 0.4.0 → 0.6.0

package/dist/src/limits.js

@@ -0,0 +1,287 @@
+// Per-step call limits: how many times a step may call a tool before the
+// next call is refused.
+//
+//   limits:
+//     web.search: 40      # one action of the web tool
+//     web: 150            # every web action together
+//     crm: 20             # an API, script or MCP tool, by the name it is granted as
+//     calls: 300          # every tool call in the step, whatever the tool
+//
+// Counted per step and enforced in step-exec.ts's PreToolUse hook — the one
+// place every call passes, the step's own and its sub-agents', on the
+// in-process path and inside a run container alike. A call past a limit is
+// refused before it runs: the tool never sees it, so a paid search API is
+// never asked and the cost is capped exactly. The refusal counts toward
+// nothing. A retry of the step starts from zero; so does each fan-out
+// instance, which is its own step.
+//
+// Nearest wins per key: the account's AGENTS.md, then the workspace's, then
+// the agent's own `limits:`, then a flow step's `limits:` option.
+import { WEB_ACTIONS } from "./providers.js";
+import { DELEGATE_TOOLS } from "./subagents.js";
+/** The key that caps every call in the step. */
+export const TOTAL_KEY = "calls";
+/** SDK built-ins, counted under the foldrun group that grants them — and
+ *  under their own SDK name, so `Bash: 5` works for a Claude Code file. */
+const BUILTIN_GROUP = {
+    Read: "read", Glob: "read", Grep: "read",
+    Write: "write", Edit: "write", MultiEdit: "write", NotebookEdit: "write",
+    Bash: "code",
+};
+/** Retired spellings an author may still write as a key. */
+const KEY_ALIASES = { files: "write", bash: "code" };
+/** The platform's own in-process servers and the name each is granted as. */
+const PLATFORM_SERVERS = {
+    foldrun_search: "search",
+    foldrun_history: "history",
+    foldrun_desks: "desks",
+    foldrun_ask: "ask",
+};
+/** One spelling for comparing: `desk-email` and `desk_email` are the same
+ *  tool (a script tool's SDK name has its dashes made underscores). */
+export function normKey(key) {
+    const k = key.trim();
+    return (KEY_ALIASES[k] ?? k).replace(/-/g, "_");
+}
+const KEY_RE = /^[A-Za-z0-9_-]+(\.[a-z]+)?$/;
+/**
+ * A `limits:` block as written: the values that can be read, and a sentence
+ * for each that cannot. Shape only — whether a key names a tool this agent
+ * has is `limitKeyProblems`, which needs the grants.
+ */
+export function readLimits(raw, where = "limits") {
+    const limits = {};
+    const problems = [];
+    if (raw === undefined || raw === null)
+        return { limits, problems };
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        problems.push(`${where}: is a block of tool: count, e.g. \`limits: {web.search: 40, calls: 300}\`.`);
+        return { limits, problems };
+    }
+    // A YAML block written `web: {search: 40}` arrives nested; read it as the
+    // dotted keys it means rather than refusing a natural spelling.
+    const flat = [];
+    for (const [k, v] of Object.entries(raw)) {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+            for (const [sub, n] of Object.entries(v))
+                flat.push([`${k}.${sub}`, n]);
+        }
+        else
+            flat.push([k, v]);
+    }
+    for (const [key, value] of flat) {
+        const k = key.trim();
+        if (!KEY_RE.test(k)) {
+            problems.push(`${where}: "${k}" is not a key — a tool's name, web.<action>, or calls.`);
+            continue;
+        }
+        if (k.includes(".")) {
+            const [head, action] = k.split(".");
+            if (head !== "web" || !WEB_ACTIONS.includes(action)) {
+                problems.push(`${where}: "${k}" is not a key — the dotted keys are web.<action>: ${WEB_ACTIONS.map((a) => `web.${a}`).join(", ")}.`);
+                continue;
+            }
+        }
+        const n = typeof value === "number" ? value : typeof value === "string" && /^\s*\d+\s*$/.test(value) ? Number(value) : NaN;
+        if (!Number.isInteger(n) || n < 1) {
+            problems.push(`${where}: ${k}: ${String(value)} — a whole number of calls, 1 or more. To withhold a tool, leave it out of tools:.`);
+            continue;
+        }
+        limits[k] = n;
+    }
+    return { limits, problems };
+}
+/**
+ * The limits a step runs under, nearest last: account, workspace, agent,
+ * step. A key set nearer replaces the same key further out; the others
+ * stand. Unreadable values are dropped here — `check` and the deploy gate
+ * say so where they were written.
+ */
+export function cascadeLimits(levels) {
+    const out = {};
+    const at = new Map(); // normalised → the key as last written
+    for (const level of levels) {
+        for (const [k, n] of Object.entries(readLimits(level).limits)) {
+            const nk = normKey(k);
+            const prev = at.get(nk);
+            if (prev !== undefined)
+                delete out[prev];
+            out[k] = n;
+            at.set(nk, k);
+        }
+    }
+    return out;
+}
+/** SDK tool name → the foldrun name it is granted as, for the tools whose
+ *  SDK name does not say (an openapi tool's operations, a script whose name
+ *  was made safe). `apiOwners` is api-tools' own record of which API each
+ *  tool was built for — not guessed from the name, which cannot tell `crm`'s
+ *  operation `admin_list` from `crm_admin`'s `list`. Built host-side; plain
+ *  JSON so it crosses into a pod. */
+export function toolOwners(apiOwners, scripts) {
+    const out = { ...apiOwners };
+    for (const s of scripts)
+        out[`mcp__foldrun_scripts__${s.name}`] = s.name;
+    return out;
+}
+/**
+ * Every key one call counts under, `calls` included. Pure: the SDK's tool
+ * name, its input, and the owners map.
+ */
+export function limitKeysFor(toolName, input, owners = {}) {
+    const keys = [TOTAL_KEY];
+    const webAction = (action) => {
+        keys.push("web");
+        const a = typeof action === "string" ? action.trim().toLowerCase() : "";
+        if (a)
+            keys.push(`web.${a}`);
+    };
+    // A model provider's own search or fetch, standing in for the web tool's.
+    if (toolName === "WebSearch") {
+        webAction("search");
+        return keys;
+    }
+    if (toolName === "WebFetch") {
+        webAction("fetch");
+        return keys;
+    }
+    if (DELEGATE_TOOLS.includes(toolName))
+        return keys;
+    const owner = owners[toolName];
+    const mcp = /^mcp__(.+?)__(.+)$/.exec(toolName);
+    const name = owner
+        ?? (mcp
+            ? mcp[1] === "foldrun_scripts" ? mcp[2]
+                : mcp[1] === "foldrun_apis" ? mcp[2].replace(/^call_/, "")
+                    : mcp[1] === "foldrun_agents" ? mcp[2].replace(/^consult_/, "")
+                        : PLATFORM_SERVERS[mcp[1]] ?? mcp[1]
+            : null);
+    if (name !== null) {
+        if (normKey(name) === "web")
+            webAction(input?.action);
+        else
+            keys.push(name);
+        return keys;
+    }
+    const group = BUILTIN_GROUP[toolName];
+    if (group)
+        keys.push(group);
+    keys.push(toolName);
+    return keys;
+}
+/**
+ * One step's counts. `take` checks every key the call counts under and
+ * either refuses — counting nothing — or counts it under all of them.
+ */
+export class CallCounter {
+    limits = new Map();
+    used = new Map();
+    refused = 0;
+    constructor(limits) {
+        for (const [k, n] of Object.entries(limits ?? {}))
+            this.limits.set(normKey(k), { key: k, limit: n });
+    }
+    get active() {
+        return this.limits.size > 0;
+    }
+    take(keys) {
+        const norm = [...new Set(keys.map(normKey))];
+        for (const k of norm) {
+            const l = this.limits.get(k);
+            if (!l)
+                continue;
+            const used = this.used.get(k) ?? 0;
+            if (used >= l.limit) {
+                this.refused++;
+                return {
+                    key: l.key, used, limit: l.limit,
+                    message: `limit reached: ${l.key} ${used} of ${l.limit} in this step — work with what you have, or say what more you would need`,
+                };
+            }
+        }
+        for (const k of norm)
+            this.used.set(k, (this.used.get(k) ?? 0) + 1);
+        return null;
+    }
+    /** Give back a call that was counted and then refused by a later check. */
+    refund(keys) {
+        for (const k of new Set(keys.map(normKey))) {
+            const n = this.used.get(k) ?? 0;
+            if (n > 0)
+                this.used.set(k, n - 1);
+        }
+    }
+    count(key) {
+        return this.used.get(normKey(key)) ?? 0;
+    }
+    /** `limits: web.search 40/40, crm 3/20` — null when no limits are set. */
+    summary() {
+        if (!this.active)
+            return null;
+        const parts = [...this.limits.entries()].map(([k, l]) => `${l.key} ${this.used.get(k) ?? 0}/${l.limit}`);
+        return `limits: ${parts.join(", ")}${this.refused ? ` — ${this.refused} call${this.refused === 1 ? "" : "s"} refused` : ""}`;
+    }
+}
+/**
+ * Keys an agent's `limits:` names that it cannot use. `known` is every tool
+ * name in reach (built-ins, the workspace's and library's tools, this
+ * agent's APIs, scripts and MCP servers); `granted` is what this agent's
+ * `tools:` (and `apis:`, `scripts:`, `mcpServers:`) gives it. A key that
+ * names nothing is an error; a real tool this agent does not hold is a
+ * warning — the limit is harmless, and probably a leftover.
+ */
+export function limitKeyProblems(limits, ctx) {
+    const out = [];
+    const builtinKeys = ["read", "write", "code", ...Object.keys(BUILTIN_GROUP), "TodoWrite", "search", "history", "desks", "ask", "web"];
+    const known = new Set([...builtinKeys, ...ctx.known].map(normKey));
+    const granted = new Set([...ctx.granted].flatMap((g) => {
+        const n = normKey(g);
+        // A group grants its members' keys, and `write` holds Read too.
+        if (n === "write")
+            return [n, "read", "Read", "Write", "Edit", "MultiEdit", "NotebookEdit", "Glob", "Grep"];
+        if (n === "read")
+            return [n, "Read", "Glob", "Grep"];
+        if (n === "code")
+            return [n, "Bash"];
+        if (BUILTIN_GROUP[g])
+            return [n, BUILTIN_GROUP[g]];
+        return [n];
+    }).map(normKey));
+    for (const key of Object.keys(limits)) {
+        if (key === TOTAL_KEY)
+            continue;
+        const base = key.startsWith("web.") ? "web" : key;
+        const n = normKey(base);
+        if (!known.has(n)) {
+            const valid = [TOTAL_KEY, "web", ...WEB_ACTIONS.map((a) => `web.${a}`), ...[...new Set([...ctx.granted].map(String))].filter((g) => g !== "web")];
+            out.push({ level: "error", message: `limits: ${key} — not a tool this agent could call. The keys: ${[...new Set(valid)].join(", ")}.` });
+        }
+        else if (!granted.has(n)) {
+            out.push({ level: "warn", message: `limits: ${key} — this agent is not granted ${base}, so the limit never applies` });
+        }
+    }
+    return out;
+}
+/**
+ * A flow step's `limits:` option, written on one line:
+ * `limits: {web.search: 10, calls: 50}` (the braces are optional). Read by
+ * hand rather than as YAML, because `web.search` is a plain key here and one
+ * line is all a step option has.
+ */
+export function parseStepLimits(text) {
+    const body = text.trim().replace(/^\{/, "").replace(/\}$/, "").trim();
+    if (!body)
+        return { limits: {}, problems: ["a block of tool: count on one line, e.g. {web.search: 10, calls: 50}"] };
+    const raw = {};
+    const problems = [];
+    for (const part of body.split(",")) {
+        const m = /^\s*([^:\s]+)\s*:\s*(\S+)\s*$/.exec(part);
+        if (!m) {
+            problems.push(`"${part.trim()}" is not tool: count`);
+            continue;
+        }
+        raw[m[1]] = m[2];
+    }
+    const read = readLimits(raw, "limits");
+    return { limits: read.limits, problems: [...problems, ...read.problems.map((p) => p.replace(/^limits: /, ""))] };
+}

package/dist/src/locale.d.ts

@@ -0,0 +1,47 @@
+export interface RegionChoice {
+    /** ISO 3166-1 alpha-2, upper-case: AU, IR, DE. Null when nobody said and
+     *  the language tag carries none. */
+    region: string | null;
+    from: "agent" | "flow" | "workspace" | "account" | "env" | "language" | "none";
+    lines: string[];
+}
+export declare function normalizeRegion(raw: unknown): string | null;
+export declare function regionProblem(raw: unknown): string | null;
+export declare function resolveRegion(levels: {
+    level: RegionChoice["from"];
+    value: unknown;
+}[], languageTag: string, env?: Record<string, string | undefined>): RegionChoice;
+export type Units = "metric" | "imperial";
+export interface LocaleFacts {
+    /** The BCP-47 tag Intl was asked with, e.g. fa-IR. */
+    tag: string;
+    language: string;
+    region: string | null;
+    currency: string | null;
+    units: Units;
+    /** The calendar in use — Intl's first for the locale, or the override. */
+    calendar: string;
+    /** Other calendars the locale commonly uses, e.g. gregory beside persian. */
+    calendars: string[];
+    /** Today in that calendar, formatted for the locale. Null when it is
+     *  gregory and would only repeat FOLDRUN_DATE. */
+    dateLocal: string | null;
+    /** 1 = Monday … 7 = Sunday, ISO. */
+    weekStart: number | null;
+    weekend: number[];
+    direction: "ltr" | "rtl";
+    hourCycle: "h12" | "h23" | null;
+    /** A sample date, so the model sees the order without being told. */
+    dateSample: string;
+}
+export declare const dayName: (n: number) => string;
+export declare function localeProblems(front: Record<string, unknown>): string[];
+export declare function deriveLocale(language: string, region: string | null, overrides?: {
+    currency?: unknown;
+    calendar?: unknown;
+    units?: unknown;
+}, timeZone?: string, now?: Date): LocaleFacts;
+/** The sentence block the prompt carries. Only what is true for this
+ *  locale; nothing hedged, nothing the model has to guess at. */
+export declare function localeProse(f: LocaleFacts, languageName: string, regionName: string | null): string;
+export declare function regionName(code: string | null): string | null;

package/dist/src/locale.js

@@ -0,0 +1,177 @@
+// Everything a country changes that a language does not — derived, not
+// declared. `region:` is the one key; from language + region the runtime
+// works out the currency, the units, the calendar (and today's date in it),
+// which days are the weekend, the text direction, and how dates and hours
+// read. Overrides exist only where derivation can be wrong for a business:
+// `currency:`, `calendar:`, `units:`. Nothing else is a key, so there is no
+// eighth setting to forget.
+//
+// Intl does the deriving. Every accessor here has a fallback to the older
+// property form (Node 20) and to "unknown", because a runtime that cannot
+// say the weekend must not say Saturday.
+import { normalizeLanguage } from "./language.js";
+export function normalizeRegion(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const m = /^[a-z]{2}$/i.exec(raw.trim());
+    return m ? raw.trim().toUpperCase() : null;
+}
+export function regionProblem(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (normalizeRegion(raw))
+        return null;
+    return `region: ${JSON.stringify(raw)} is not a country code — write the two letters, like \`au\`, \`ir\` or \`de\`.`;
+}
+export function resolveRegion(levels, languageTag, env = process.env) {
+    const lines = [];
+    for (const { level, value } of levels) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        const r = normalizeRegion(value);
+        if (r)
+            return { region: r, from: level, lines };
+        lines.push(`region: ${level} says ${JSON.stringify(value)}, which is not a country code — using the next level`);
+    }
+    const fromEnv = normalizeRegion(env.FOLDRUN_REGION);
+    if (fromEnv)
+        return { region: fromEnv, from: "env", lines };
+    const tag = normalizeLanguage(languageTag);
+    const fromTag = tag && tag.includes("-") ? tag.split("-")[1] : null;
+    if (fromTag)
+        return { region: fromTag, from: "language", lines };
+    return { region: null, from: "none", lines };
+}
+// ISO 4217 by region, for the regions a business here is likely to name.
+// Intl has no region→currency table; this is the smallest one that is not
+// wrong. Absent means "no currency assumed", which is better than a guess.
+const CURRENCY = {
+    AU: "AUD", NZ: "NZD", US: "USD", CA: "CAD", GB: "GBP", IE: "EUR", DE: "EUR", FR: "EUR", IT: "EUR", ES: "EUR",
+    NL: "EUR", BE: "EUR", AT: "EUR", PT: "EUR", FI: "EUR", GR: "EUR", CH: "CHF", SE: "SEK", NO: "NOK", DK: "DKK",
+    PL: "PLN", CZ: "CZK", TR: "TRY", RU: "RUB", UA: "UAH", IR: "IRR", IQ: "IQD", AF: "AFN", PK: "PKR", IN: "INR",
+    BD: "BDT", LK: "LKR", NP: "NPR", AE: "AED", SA: "SAR", QA: "QAR", KW: "KWD", BH: "BHD", OM: "OMR", JO: "JOD",
+    IL: "ILS", EG: "EGP", MA: "MAD", ZA: "ZAR", NG: "NGN", KE: "KES", CN: "CNY", HK: "HKD", TW: "TWD", JP: "JPY",
+    KR: "KRW", SG: "SGD", MY: "MYR", ID: "IDR", TH: "THB", VN: "VND", PH: "PHP", BR: "BRL", MX: "MXN", AR: "ARS",
+    CL: "CLP", CO: "COP",
+};
+const IMPERIAL = new Set(["US", "LR", "MM"]);
+const DAY = ["", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+export const dayName = (n) => DAY[n] ?? String(n);
+export function localeProblems(front) {
+    const out = [];
+    const r = regionProblem(front.region);
+    if (r)
+        out.push(r);
+    if (front.currency !== undefined && front.currency !== null && front.currency !== "") {
+        if (!/^[A-Za-z]{3}$/.test(String(front.currency)))
+            out.push(`currency: ${JSON.stringify(front.currency)} is not a currency code — three letters, like \`AUD\`, \`IRR\` or \`EUR\`.`);
+    }
+    if (front.units !== undefined && front.units !== null && front.units !== "") {
+        if (!["metric", "imperial"].includes(String(front.units).toLowerCase()))
+            out.push(`units: ${JSON.stringify(front.units)} — write \`metric\` or \`imperial\`.`);
+    }
+    if (front.calendar !== undefined && front.calendar !== null && front.calendar !== "") {
+        const known = supportedCalendars();
+        if (known.length && !known.includes(String(front.calendar).toLowerCase())) {
+            out.push(`calendar: ${JSON.stringify(front.calendar)} is not a calendar this runtime knows — one of ${known.join(", ")}.`);
+        }
+    }
+    return out;
+}
+function supportedCalendars() {
+    try {
+        const f = Intl.supportedValuesOf;
+        return f ? f("calendar") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function localeInfo(tag) {
+    try {
+        const L = new Intl.Locale(tag);
+        const call = (m, p) => {
+            const fn = L[m];
+            if (typeof fn === "function")
+                return fn.call(L);
+            return L[p];
+        };
+        const wk = call("getWeekInfo", "weekInfo");
+        const ti = call("getTextInfo", "textInfo");
+        const cals = call("getCalendars", "calendars") ?? [];
+        const hc = call("getHourCycles", "hourCycles")?.[0];
+        return {
+            weekStart: wk?.firstDay ?? null,
+            weekend: wk?.weekend ?? [],
+            direction: ti?.direction === "rtl" ? "rtl" : "ltr",
+            calendars: cals,
+            hourCycle: hc === "h12" || hc === "h23" ? hc : null,
+        };
+    }
+    catch {
+        return { weekStart: null, weekend: [], direction: "ltr", calendars: [], hourCycle: null };
+    }
+}
+export function deriveLocale(language, region, overrides = {}, timeZone = "UTC", now = new Date()) {
+    const lang = normalizeLanguage(language) ?? "en";
+    const base = lang.split("-")[0];
+    const tag = region ? `${base}-${region}` : lang;
+    const info = localeInfo(tag);
+    const calendar = typeof overrides.calendar === "string" && overrides.calendar ? overrides.calendar.toLowerCase() : info.calendars[0] ?? "gregory";
+    const currency = typeof overrides.currency === "string" && overrides.currency ? overrides.currency.toUpperCase() : region ? CURRENCY[region] ?? null : null;
+    const units = typeof overrides.units === "string" && ["metric", "imperial"].includes(overrides.units.toLowerCase())
+        ? overrides.units.toLowerCase()
+        : region && IMPERIAL.has(region) ? "imperial" : "metric";
+    const fmt = (opts, cal = calendar) => {
+        try {
+            return new Intl.DateTimeFormat(`${tag}-u-ca-${cal}`, { ...opts, timeZone }).format(now);
+        }
+        catch {
+            return new Intl.DateTimeFormat("en", { ...opts, timeZone }).format(now);
+        }
+    };
+    return {
+        tag,
+        language: lang,
+        region,
+        currency,
+        units,
+        calendar,
+        calendars: info.calendars.filter((c) => c !== calendar),
+        dateLocal: calendar === "gregory" ? null : fmt({ dateStyle: "long" }),
+        weekStart: info.weekStart,
+        weekend: info.weekend,
+        direction: info.direction,
+        hourCycle: info.hourCycle,
+        dateSample: fmt({ dateStyle: "medium" }, "gregory"),
+    };
+}
+/** The sentence block the prompt carries. Only what is true for this
+ *  locale; nothing hedged, nothing the model has to guess at. */
+export function localeProse(f, languageName, regionName) {
+    const parts = [];
+    parts.push(`Language: ${languageName} (\`${f.language}\`)${regionName ? `. Region: ${regionName} (\`${f.region}\`)` : ""}.`);
+    if (f.currency)
+        parts.push(`Currency: ${f.currency}.`);
+    parts.push(`Units: ${f.units}.`);
+    if (f.calendar !== "gregory") {
+        parts.push(`Calendar: ${f.calendar}${f.dateLocal ? ` — today is ${f.dateLocal}` : ""}${f.calendars.length ? ` (also ${f.calendars.join(", ")})` : ""}.`);
+    }
+    if (f.weekStart) {
+        parts.push(`Week starts ${dayName(f.weekStart)}; weekend ${f.weekend.map(dayName).join(" and ") || "unknown"}.`);
+    }
+    parts.push(`Dates read like ${f.dateSample}${f.hourCycle ? `; ${f.hourCycle === "h23" ? "24-hour" : "12-hour"} time` : ""}.`);
+    if (f.direction === "rtl")
+        parts.push(`Text runs right to left: anything you render — HTML, email, PDF — needs dir="rtl".`);
+    return parts.join(" ");
+}
+export function regionName(code) {
+    if (!code)
+        return null;
+    try {
+        return new Intl.DisplayNames(["en"], { type: "region" }).of(code) ?? code;
+    }
+    catch {
+        return code;
+    }
+}

package/dist/src/mail.d.ts

@@ -0,0 +1,88 @@
+export type MailCategory = "security" | "invites" | "billing" | "account" | "run-alerts" | "approvals" | "low-balance" | "product-updates";
+export interface MailCategoryInfo {
+    id: MailCategory;
+    label: string;
+    /** Required mail cannot be turned off — see `why`. */
+    required: boolean;
+    /** Can be turned off for one workspace while the rest still send. */
+    perWorkspace: boolean;
+    /** What it is, for the settings page and `foldrun notifications`. */
+    description: string;
+    /** For a required category: why it cannot be refused. */
+    why?: string;
+}
+export declare const MAIL_CATEGORIES: readonly MailCategoryInfo[];
+export declare function mailCategory(id: string): MailCategoryInfo | null;
+export declare function isRequiredCategory(id: string): boolean;
+/** How long a token in a mail keeps working. Long: a person unsubscribes
+ *  from a mail they kept, often months later, and an unsubscribe link that
+ *  has died is the one that sends them to the spam button instead. */
+export declare const UNSUBSCRIBE_TTL_MS: number;
+export interface UnsubscribeClaim {
+    tenant: string;
+    email: string;
+    category: MailCategory;
+    /** The workspace the mail was about, when its category is per workspace. */
+    workspace: string | null;
+    /** Epoch ms. */
+    expiresAt: number;
+}
+/**
+ * `<payload>.<signature>`: the payload is base64url JSON of who, what and
+ * until when; the signature is an HMAC under the install key, so the token
+ * is derived, never stored, and a key rotation kills every old one.
+ */
+export declare function unsubscribeToken(c: Omit<UnsubscribeClaim, "expiresAt"> & {
+    expiresAt?: number;
+}, now?: number): string;
+/** What a presented token says, or why it says nothing. */
+export declare function readUnsubscribeToken(token: string | null | undefined, now?: number): {
+    claim: UnsubscribeClaim;
+} | {
+    error: string;
+    status: 400 | 401 | 410;
+};
+/** The page a person opens, and the URL a mail client POSTs to. Null when
+ *  the install does not know its own address — then there is no link. */
+export declare function unsubscribeLinks(claim: Omit<UnsubscribeClaim, "expiresAt">, now?: number): {
+    page: string;
+    oneClick: string;
+} | null;
+/** The RFC 8058 pair, for a mail whose category may be turned off. */
+export declare function unsubscribeHeaders(claim: Omit<UnsubscribeClaim, "expiresAt">, now?: number): Record<string, string>;
+export interface MailMessage {
+    tenant: string;
+    /** The Resend key and sender — platformMail(), accountMail() or notifyMail(). */
+    mail: {
+        key: string;
+        from: string;
+    };
+    to: string | string[];
+    subject: string;
+    text: string;
+    html?: string;
+    category: MailCategory;
+    /** The workspace the mail is about, for per-workspace preferences. */
+    workspace?: string | null;
+}
+export interface MailResult {
+    /** True when every recipient who wanted it was handed to the provider —
+     *  and when nobody wanted it, which is not a failure. */
+    ok: boolean;
+    /** The HTTP status of the last send, when one was made. */
+    status?: number;
+    /** The provider's own words on a refusal, trimmed. */
+    error?: string;
+    sent: string[];
+    /** Recipients who turned this category off. */
+    suppressed: string[];
+}
+/** Does this person take this category of mail? Required mail: always. */
+export declare function mailWanted(tenant: string, email: string, category: MailCategory, workspace?: string | null): Promise<boolean>;
+/**
+ * Send one message, honouring each recipient's preference for its
+ * category. Optional mail is sent one recipient at a time so each copy
+ * carries that reader's own unsubscribe token; required mail goes as one.
+ * Never throws: a mail that fails is an `ok: false` with the reason.
+ */
+export declare function sendMail(m: MailMessage): Promise<MailResult>;