@aglyn/shared-util-email 1.0.0-beta.143

package/src/lib/sender-reputation.d.ts

@@ -0,0 +1,357 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * PER-TENANT SENDING REPUTATION — the policy half.
+ *
+ * Every tenant's marketing mail leaves on one shared sending domain under
+ * `p=reject`. A mailbox provider grades that domain, not the tenant, so one
+ * merchant's bad list is felt by every other merchant's campaigns AND by the
+ * transactional mail — password resets, receipts, booking reminders — that
+ * shares the domain with them. Nothing in the product computed a rate at any
+ * scope, so there was no number to act on and no point at which anything
+ * stopped.
+ *
+ * This module is the decision, as a pure function of counts. The durable
+ * counters live in `@aglyn/tenant-data-admin` (`email-sender-reputation.ts`),
+ * which is the only layer that may hold the Admin SDK — the same split
+ * `send-rate.ts` draws beside it, for the same reason.
+ *
+ * ## What it may do, and what it may never do
+ *
+ * **It refuses a SEND. It never touches a person or their data.** No contact
+ * is deleted, no audience is trimmed, nobody is unsubscribed and no list
+ * membership changes. That is the enforce-at-the-reduction rule
+ * (`over-limit.ts`): a limit that refuses a person or their data leaks, so a
+ * capacity control gates the DROP and never the holding. A send is a flow —
+ * refusing one strands nobody's data, and the merchant can send it after
+ * cleaning the list.
+ *
+ * **It may only ever refuse a CAMPAIGN.** A transactional message can never
+ * reach this decision: {@link emailReputationVerdict} is consulted from the campaign
+ * sender alone, and both layers underneath it — `emailSendRateVerdict` and
+ * `sendEmail` itself — independently refuse to drop a transactional priority
+ * whatever a control above them says. A password reset refused by a
+ * reputation breaker converts a deliverability risk into an outage on
+ * somebody else's business, and the mail explaining why is itself mail that
+ * would not send.
+ *
+ * ## The three numbers, and the two that are not rates
+ *
+ * A rate on its own is not evidence. Two guards stand in front of every
+ * threshold and both have to clear:
+ *
+ *  - {@link EMAIL_REPUTATION_MIN_VOLUME} — a denominator below which a rate
+ *    is noise. One complaint out of four is 25% and means nothing.
+ *  - {@link EMAIL_REPUTATION_MIN_EVENTS} — a numerator below which a rate is
+ *    one person having a bad day. M3AAWG's own sizing caveat is that test
+ *    sends below ten thousand recipients do not yield statistically
+ *    significant results; at our volumes the honest response is not to pretend
+ *    otherwise but to require that the signal be repeated before it bites.
+ *
+ * A threshold crossed with either guard unmet is reported as a FINDING and
+ * changes nothing. That is deliberate: the operator surface has to show a
+ * rate climbing before it trips, or the first anybody hears of the control is
+ * a refused campaign.
+ *
+ * ## The thresholds
+ *
+ * `complaintRate` is graded against Google's published bulk-sender rule —
+ * keep spam complaints under 0.10% and never at or above 0.30% — so the watch
+ * level and the trip level are the two numbers Google itself names rather
+ * than two we picked.
+ *
+ * `bounceRate` has no published cross-provider number; 5% watch and 10% trip
+ * is the shape Amazon SES enforces on its own senders, and it is the one
+ * decision here taken from a vendor rather than from a standard.
+ */
+/** Days of history a rate is computed over. */
+export declare const EMAIL_REPUTATION_WINDOW_DAYS = 7;
+/**
+ * Messages a window must carry before any rate in it is actionable.
+ *
+ * 200 is the first ramp step (see {@link EMAIL_RAMP_STEPS}), so a brand-new
+ * tenant cannot be tripped by its very first day of sending — it has to send
+ * a second day, by which time there is a real denominator.
+ */
+export declare const EMAIL_REPUTATION_MIN_VOLUME = 200;
+/** Bad events a finding must carry before it is actionable. */
+export declare const EMAIL_REPUTATION_MIN_EVENTS = 3;
+/** Google's "keep it under this" spam rate. */
+export declare const EMAIL_COMPLAINT_RATE_WATCH = 0.001;
+/** Google's "never reach this" spam rate. */
+export declare const EMAIL_COMPLAINT_RATE_TRIP = 0.003;
+/** Bounce rate that earns a warning. */
+export declare const EMAIL_BOUNCE_RATE_WATCH = 0.05;
+/** Bounce rate that stops the sender. */
+export declare const EMAIL_BOUNCE_RATE_TRIP = 0.1;
+/**
+ * What a tenant's findings are allowed to do to it.
+ *
+ * The three Amazon SES publishes for its own tenant isolation, and the names
+ * are theirs because the behaviors are theirs. **These are persisted values**
+ * — they are stored on the org — so they are added to and never renamed.
+ */
+export type EmailReputationPolicy = 
+/** Stop the sender on a high-severity finding. The default. */
+'standard'
+/** Stop the sender on any finding at all. */
+ | 'strict'
+/** Record only. Never stops anything. */
+ | 'none';
+export declare const EMAIL_REPUTATION_POLICIES: readonly EmailReputationPolicy[];
+/** The default when an org has configured nothing. */
+export declare const EMAIL_REPUTATION_DEFAULT_POLICY: EmailReputationPolicy;
+/**
+ * Reads a stored policy, falling back to the default.
+ *
+ * Never falls back to `'none'`. An unreadable policy that parked the breaker
+ * would be a control switched off by a typo, which is the shape where a
+ * ceiling silently stops existing.
+ */
+export declare function normalizeEmailReputationPolicy(raw: unknown): EmailReputationPolicy;
+/**
+ * WHICH POLICY THIS SENDER IS ACTUALLY GRADED ON, given whose domain it is.
+ *
+ * A pooled sender shares one domain with every other site that has no domain
+ * of its own, so a complaint it earns is charged to their receipts as much as
+ * to its own. That asymmetry used to be handled by keeping marketing off the
+ * pool altogether. It is handled here instead: on the pool a campaign is
+ * graded `strict`, which stops it on the WATCH thresholds — Google's "keep
+ * under" 0.10% complaint rate and a 5% bounce rate — rather than waiting for
+ * the trip levels three and two times higher.
+ *
+ * On a domain the merchant owns, the org's own setting stands. The reputation
+ * being spent there is theirs alone, and how fast they spend it is theirs to
+ * decide.
+ *
+ * ## The pool overrides `none`, and that is the point
+ *
+ * A workspace that has switched its own breaker off must not thereby switch
+ * off the one protecting the other sites on its pool member. Same posture as
+ * the platform marketing frequency ceiling, which is the same number on every
+ * plan for the same reason: a control that exists to protect tenants from each
+ * other cannot be something one tenant sets aside.
+ *
+ * @param source the resolved {@link SendingIdentitySource}. Anything that is
+ *        not `'shared'` — a custom domain, the platform's own identity, or an
+ *        unresolved send — takes the configured policy, because only the pool
+ *        spends somebody else's reputation.
+ */
+export declare function effectiveReputationPolicy(source: string | null | undefined, configured: unknown): EmailReputationPolicy;
+/** Which measurement produced a finding. */
+export type EmailReputationFindingCode = 'complaint-rate' | 'bounce-rate';
+/** How badly. `high` is what a `standard` policy stops on. */
+export type EmailReputationSeverity = 'low' | 'high';
+/** One measurement that crossed a threshold, with the numbers behind it. */
+export interface EmailReputationFinding {
+    code: EmailReputationFindingCode;
+    severity: EmailReputationSeverity;
+    /** The measured rate, as a fraction. */
+    rate: number;
+    /** The threshold it crossed, as a fraction. */
+    threshold: number;
+    /** Events in the window — the numerator. */
+    events: number;
+    /** Messages in the window — the denominator. */
+    volume: number;
+    /**
+     * False when a guard was unmet, so this finding is reported and cannot
+     * stop anything. See the header for why both guards exist.
+     */
+    actionable: boolean;
+    /** Human-readable, and the text a surface may show verbatim. */
+    detail: string;
+}
+/** The counts a window holds. Every field is a message count. */
+export interface EmailReputationCounts {
+    /** Campaign messages handed to the sender in the window. The denominator. */
+    accepted: number;
+    /** Permanent bounces reported against them. */
+    bounced: number;
+    /** Spam complaints reported against them. */
+    complained: number;
+}
+/** A tenant's reputation state. */
+export type EmailReputationState = 
+/** No finding, or none actionable. */
+'ok'
+/** A finding this policy does not stop on. */
+ | 'watch'
+/** The sender is stopped. */
+ | 'tripped'
+/**
+ * Findings stand but a grace period is ignoring them, so a tenant that has
+ * fixed its list can send again without an operator having to time the
+ * moment the window rolls off. SES's own `Reinstated`.
+ */
+ | 'reinstated';
+/** The reconciled reputation of one tenant. */
+export interface EmailReputationVerdict {
+    state: EmailReputationState;
+    /** True only when a campaign may not go out. */
+    blocked: boolean;
+    policy: EmailReputationPolicy;
+    complaintRate: number;
+    bounceRate: number;
+    /** Messages the window measured. */
+    volume: number;
+    /** Days the window covers. */
+    windowDays: number;
+    /** Every threshold crossed, actionable or not. */
+    findings: EmailReputationFinding[];
+    /**
+     * Why a merchant cannot send, in words they can act on. Empty when
+     * {@link blocked} is false — a surface must never show a reason for a
+     * state that is not blocking.
+     */
+    reason: string;
+    /** When a grace period ends, ms. Null unless {@link state} is `reinstated`. */
+    reinstatedUntilMs: number | null;
+}
+/** `events / volume`, or 0 when there is no denominator. */
+export declare function emailReputationRate(events: number, volume: number): number;
+/** A fraction as the percentage a person reads, to two places. */
+export declare function formatReputationRate(rate: number): string;
+export interface EmailReputationVerdictInput {
+    counts: EmailReputationCounts;
+    policy?: EmailReputationPolicy;
+    /** Days the counts cover, for the message. */
+    windowDays?: number;
+    /** A grace period that ignores active findings, ms since epoch. */
+    reinstatedUntilMs?: number | null;
+    /** Injectable for tests. */
+    now?: number;
+}
+/**
+ * Grades one tenant's window, and says whether a campaign may go out.
+ *
+ * Pure and total: no input throws, because this runs on the path that decides
+ * whether a campaign sends and a thrown grade would be an outage caused by
+ * bookkeeping. That is the posture `describeEmailCeilings` takes beside it.
+ *
+ * A tenant with no history at all grades `ok` — an absent counter is a tenant
+ * that has not sent, not a tenant with a perfect record and not one to
+ * refuse. The direction matters: the opposite reading would refuse every
+ * first campaign on the platform, which is the stubbed-resolver failure where
+ * a clamp goes green having stopped everything.
+ */
+export declare function emailReputationVerdict(input: EmailReputationVerdictInput): EmailReputationVerdict;
+/** One step of the ramp. */
+export interface EmailRampStep {
+    /** Days since the workspace was created before this step is reachable. */
+    minAgeDays: number;
+    /** Campaign messages it must have delivered before this step is reachable. */
+    minDelivered: number;
+    /** Campaign messages a day at this step. */
+    perDay: number;
+}
+/**
+ * The ramp, lowest step first.
+ *
+ * The first step is SES's published sandbox figure. Each step after it is
+ * roughly a five-fold increase gated on having actually delivered most of the
+ * step below it, which is the warm-up curve every deliverability guide
+ * describes and the one a mailbox provider's own reputation model is built to
+ * see.
+ */
+export declare const EMAIL_RAMP_STEPS: readonly EmailRampStep[];
+/**
+ * Age at which the ramp stops binding entirely.
+ *
+ * Past this the hourly share and the plan are the only ceilings, which is
+ * what they were before the ramp existed. Seven days matches the last step's
+ * reach and is short enough that it is a warm-up rather than a tier.
+ */
+export declare const EMAIL_RAMP_GRADUATION_DAYS = 7;
+/** What the ramp allows a tenant today. */
+export interface EmailRampVerdict {
+    /** True when the ramp no longer binds and the hourly share is the ceiling. */
+    graduated: boolean;
+    /** Campaign messages this tenant may send today. */
+    perDay: number;
+    /**
+     * The step as a FRACTION of a graduated day, in `(0, 1]`.
+     *
+     * The same restriction {@link perDay} states, in the form a surface with a
+     * different daily allowance can apply — see the surfaces note in the header
+     * above. 1 when graduated, which is the identity every consumer wants for
+     * an established workspace.
+     */
+    share: number;
+    /** Which step it is on, 0-based. Equals the step count when graduated. */
+    step: number;
+    /** Days until the next step is reachable on age alone. Null when graduated. */
+    daysToNextStep: number | null;
+    /** Human-readable, and the text a surface may show verbatim. */
+    detail: string;
+}
+export interface EmailRampInput {
+    /**
+     * Days since the workspace was created. A negative, unreadable or absent
+     * value GRADUATES — see the header for why that direction is the only safe
+     * one.
+     */
+    ageDays: number | null | undefined;
+    /** Campaign messages this workspace has delivered, all time. */
+    deliveredLifetime: number;
+    /**
+     * The hourly share expressed as a day, which is the ceiling a graduated
+     * tenant has. A ramp step is never allowed to exceed it — a step above the
+     * ceiling underneath it would be a number that can never be reached.
+     */
+    graduatedPerDay: number;
+}
+/**
+ * The daily campaign ceiling for one tenant.
+ *
+ * Pure and total, like every other ceiling in this library.
+ */
+export declare function emailRampVerdict(input: EmailRampInput): EmailRampVerdict;
+/**
+ * A daily allowance, held to the share of it a young workspace has earned.
+ *
+ * The ramp applied to a surface whose day is a plan figure rather than the
+ * graduated campaign ceiling — see the share note in the header. A graduated
+ * workspace, and an absent verdict, get the allowance untouched, so a caller
+ * that cannot resolve a ramp is not silently throttling anybody.
+ *
+ * ## The two clamps, and why each is the direction it is
+ *
+ * FLOORED AT 1 while the allowance is positive, the same reasoning
+ * `orgHourlyCampaignCeiling` floors its own share at 1: the first step is a
+ * small fraction of a graduated day, and a plan band low enough to round that
+ * fraction away must throttle a workspace to a trickle rather than stop it
+ * dead. A ceiling of zero on day one is indistinguishable from a plan that
+ * carries no one-to-one email at all, and the two have to stay tellable
+ * apart.
+ *
+ * An allowance of ZERO stays zero, because that is not a small band — it is
+ * a plan with no allowance, and a ramp that raised it to 1 would sell a
+ * feature the tier does not carry. Pacing never grants.
+ *
+ * An INFINITE allowance stays infinite. It is the sentinel a contract with no
+ * ceiling is written as, a share of it is still unbounded, and the clamp
+ * below would read the infinity as a corrupt counter and answer zero — a
+ * ramp that refused the agreements that buy the most.
+ */
+export declare function rampedDailyAllowance(allowance: number, ramp: EmailRampVerdict | null | undefined): number;
+/** Days between two instants, floored. Negative inputs read as 0. */
+export declare function daysBetween(fromMs: number, toMs: number): number;
+/** The UTC day a timestamp falls in, as `YYYY-MM-DD`. */
+export declare function reputationDayKey(atMs?: number): string;
+/** The `YYYY-MM-DD` keys of the window ending on `atMs`, oldest first. */
+export declare function reputationWindowDayKeys(atMs?: number, windowDays?: number): string[];