@aglyn/tenant-data-admin 1.0.0-beta.143

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

@@ -0,0 +1,317 @@
+/**
+ * @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 durable half.
+ *
+ * The policy is pure and lives in `@aglyn/shared-util-email`
+ * (`sender-reputation.ts`); this adds the counters that make a rate a fact
+ * rather than an intention, and the daily claim that paces a workspace's
+ * first week.
+ *
+ * ## One document per workspace per day
+ *
+ * `rateLimits/emailRep_{YYYY-MM-DD}_{orgId}` holds four numbers:
+ *
+ *  - `claimed` — campaign messages the day's ramp has granted. The PACING
+ *    counter, taken before a send and reconciled to what actually left.
+ *  - `accepted` — campaign messages that actually left. The DENOMINATOR every
+ *    rate divides by.
+ *  - `bounced`, `complained` — what the provider reported back.
+ *
+ * A day per document rather than a map of days on one, because the day is
+ * what the TTL policy can sweep: `rateLimits` already carries an `expiresAt`
+ * policy, and a document that ages out is a window that prunes itself. A map
+ * of every day a workspace has ever sent would grow forever and would have to
+ * be pruned by a job nobody would write.
+ *
+ * A per-ORG document rather than per-site, because the org is the tenant: the
+ * plan, the monthly allowance and the hourly share are all keyed on it, and a
+ * merchant with three sites on one domain is one sender to a mailbox
+ * provider.
+ *
+ * The window document deliberately carries **no `lastAtMs`** — the
+ * rate-limiter health probe queries this collection on that field, and a
+ * per-day document in its range would compete with the degradation markers it
+ * exists to find. The same reasoning as `sendRate_*` and `sendRateOrg_*`
+ * beside it.
+ *
+ * ## Which day a bounce is filed under
+ *
+ * The day the EVENT arrived, not the day the message was sent. The webhook
+ * knows the first and would need a per-message lookup for the second, and
+ * over a seven-day window the two differ only at the edges — a bounce lands
+ * within minutes and a complaint within hours or a day. Stated because the
+ * rate is a ratio of two things counted on slightly different clocks, and a
+ * reader comparing it against a provider's dashboard should know why they
+ * will not agree to the last decimal.
+ *
+ * ## Failure posture: OPEN, and that is not the usual answer here
+ *
+ * An unreadable counter grades `ok` and grants the send, matching
+ * `consumeEmailSendBudget` and `claimOrgEmailSendBudget`. The breaker is the
+ * one control in this file that could refuse a paying customer's campaign,
+ * and a refusal produced by a Firestore blip is an outage dressed as a policy
+ * decision. The reputation risk it fails to catch is bounded by an hour of
+ * sending; the refusal it would produce is not bounded by anything.
+ */
+import { type EmailRampVerdict, type EmailReputationCounts, type EmailReputationPolicy, type EmailReputationVerdict } from '@aglyn/shared-util-email';
+/** Id prefix for the per-org, per-day reputation documents. */
+export declare const EMAIL_REPUTATION_DOC_PREFIX = "emailRep_";
+/** The document id for one workspace's day. */
+export declare function emailReputationDocId(dayKey: string, orgId: string): string;
+/** The counted fields, so a writer cannot invent a fifth by typo. */
+export type EmailReputationCounter = 'claimed' | 'accepted' | 'bounced' | 'complained';
+/**
+ * Adds to one of a workspace's daily counters.
+ *
+ * **Never throws.** Reputation accounting runs after mail has gone out, or
+ * inside a webhook the provider will retry — a counter write that failed must
+ * not turn a delivered campaign into a 500 or a webhook into a retry storm.
+ * `FieldValue.increment` rather than a transaction because nothing decides
+ * anything from this write: the decision is made by a separate read, and an
+ * increment is the contention-free way to record a fact.
+ */
+export declare function recordEmailReputationEvent(options: {
+    orgId: string;
+    counter: EmailReputationCounter;
+    count?: number;
+    atMs?: number;
+    firestore?: any;
+}): Promise<void>;
+/** Campaign messages that actually left, for a workspace. The denominator. */
+export declare function recordCampaignAccepted(orgId: string, count: number, options?: {
+    atMs?: number;
+    firestore?: any;
+}): Promise<void>;
+/**
+ * A permanent bounce or a spam complaint, attributed to the workspace that
+ * sent it.
+ *
+ * The suppression the same event produces is a separate act and is not
+ * conditional on this: an address comes off the list whether or not the
+ * counter write lands.
+ */
+export declare function recordEmailReputationFailure(orgId: string, kind: 'bounce' | 'complaint', options?: {
+    atMs?: number;
+    firestore?: any;
+}): Promise<void>;
+/** The counts a workspace's window holds, plus what the ramp needs. */
+export interface SenderReputationWindow extends EmailReputationCounts {
+    /**
+     * Campaign messages the ramp has granted TODAY.
+     *
+     * Read here rather than by a second query because today's document is
+     * already in this window: the ramp needs one number off it and the rates
+     * need three off all of them, and two reads of one document to answer two
+     * questions about the same workspace is a round trip nobody has to pay.
+     */
+    claimedToday: number;
+    /** Days the window covers. */
+    windowDays: number;
+    /** True when the window could not be read and everything below is zero. */
+    degraded: boolean;
+}
+/**
+ * Sums a workspace's last {@link EMAIL_REPUTATION_WINDOW_DAYS} days.
+ *
+ * One `getAll` over the window's day documents — seven reads per campaign,
+ * not per message, and none at all for a workspace that has never sent. An
+ * absent day is a quiet day and reads as zero.
+ */
+export declare function readSenderReputationWindow(options: {
+    orgId: string;
+    now?: number;
+    windowDays?: number;
+    firestore?: any;
+}): Promise<SenderReputationWindow>;
+/** A workspace's reputation, and whether its campaigns may go out. */
+export interface SenderReputationRead extends EmailReputationVerdict {
+    /** True when the window could not be read, so nothing was graded. */
+    degraded: boolean;
+    /** The counts the grade was made from, so a caller can size a ramp too. */
+    window: SenderReputationWindow;
+}
+/**
+ * Grades one workspace.
+ *
+ * The policy and the grace period come from the ORG DOCUMENT, which the
+ * campaign sender has already read — passed in rather than re-fetched, so
+ * this costs the window read and nothing else.
+ */
+export declare function readSenderReputation(options: {
+    orgId: string;
+    policy?: unknown;
+    reinstatedUntilMs?: unknown;
+    now?: number;
+    firestore?: any;
+}): Promise<SenderReputationRead>;
+/**
+ * The ramp step a workspace has EARNED, from a window it has already read.
+ *
+ * A thin wrapper over the pure policy that supplies the one number the policy
+ * cannot know: what a graduated workspace's day is, which is a share of the
+ * live platform ceiling and therefore moves with a staff ramp.
+ */
+export declare function resolveOrgEmailRamp(options: {
+    /** Days since the workspace was created; null or absent graduates it. */
+    ageDays: number | null | undefined;
+    /** Campaign messages it has delivered inside the window. */
+    deliveredLifetime: number;
+    /** The live platform ceiling. */
+    platformPerHour: number;
+}): EmailRampVerdict;
+/** A workspace's ramp step, and whether the history behind it was readable. */
+export interface OrgEmailRampRead {
+    /** The step, from the age and the delivery history that resolved. */
+    ramp: EmailRampVerdict;
+    /**
+     * True when the ramp BINDS and the window it is sized from was unreadable,
+     * so {@link ramp} is a floor rather than an answer.
+     *
+     * A caller that pages a batch — the campaign path — may treat this as the
+     * step and carry on, because the floor is the lowest step and erring low
+     * defers mail rather than sending it. A caller that admits or refuses ONE
+     * message has no such third answer and must refuse: see
+     * {@link readOrgEmailRamp}.
+     */
+    degraded: boolean;
+}
+/**
+ * A workspace's ramp step, resolved from its record and its history.
+ *
+ * The reads {@link resolveOrgEmailRamp} needs, in the order that pays for
+ * the fewest of them. The platform ceiling comes first because it is process-
+ * cached for fifteen seconds and therefore free; the seven-day window is a
+ * `getAll` and is only paid when the ramp can still bind.
+ *
+ * ## A graduated workspace pays nothing
+ *
+ * Age alone decides graduation — delivery volume can only RAISE a step, never
+ * reach past the last one — so a workspace past its first week is answered
+ * from the org record with no window read at all. That is every existing
+ * customer and every org whose record predates the creation timestamp, which
+ * is to say almost every call.
+ *
+ * ## An unreadable window is `degraded`, and it is the caller's to answer
+ *
+ * The window read grades itself rather than throwing, and an unreadable one
+ * reads as zero delivered — the LOWEST step, which is the conservative
+ * direction for a ceiling. What it is not is a fact, so it is flagged: a
+ * surface admitting one message at a time cannot defer the remainder to
+ * tomorrow the way a campaign can, and a limiter with no answer must refuse
+ * rather than admit.
+ *
+ * ## The platform flag parks this control
+ *
+ * `enabled: false` on the send-rate config graduates every workspace here,
+ * exactly as it parks the hourly share and {@link claimOrgEmailSendDay} — one
+ * switch, and it turns the ramp off everywhere it is consulted.
+ */
+export declare function readOrgEmailRamp(options: {
+    orgId: string;
+    /** The org record's `createdAt`, in whatever shape it was stored. */
+    createdAt: unknown;
+    now?: number;
+    firestore?: any;
+}): Promise<OrgEmailRampRead>;
+/** The answer to a per-day ramp claim. Every field is a stated number. */
+export interface OrgEmailSendDayClaim {
+    allowed: boolean;
+    /** Messages claimed today BEFORE this send. */
+    used: number;
+    /** What this workspace may send today. */
+    ceiling: number;
+    /** Headroom after this send, floored at 0. */
+    remaining: number;
+    /** When the day rolls and a deferred campaign may go, ms. */
+    retryAtMs: number;
+    /** The ramp decision the ceiling came from. */
+    ramp: EmailRampVerdict;
+    /** True when the counter was unreachable and this failed open. */
+    degraded: boolean;
+    /**
+     * What to hand {@link reconcileOrgEmailSendDay} once the batch is done.
+     * Null when nothing was claimed — a graduated workspace, a parked control,
+     * or a refusal.
+     */
+    reservation: OrgEmailSendDayReservation | null;
+}
+/** A claim on a day's ramp, so an undelivered remainder can be given back. */
+export interface OrgEmailSendDayReservation {
+    orgId: string;
+    dayKey: string;
+    claimed: number;
+}
+/**
+ * THE NEW-SENDER RAMP, ENFORCED.
+ *
+ * Claims `count` campaign messages against what this workspace may send
+ * today, atomically. The transaction reads the counter and writes an ABSOLUTE
+ * value derived from that read rather than an increment, for the reason
+ * `reserveCampaignEmailSends` and `claimOrgEmailSendBudget` both do: the read
+ * is the authority for the decision, and an increment proves nothing about
+ * the value the decision was made from.
+ *
+ * The ceiling arrives as a resolved {@link EmailRampVerdict} rather than
+ * being derived here, because the caller has already paid the window read
+ * that decides which step the workspace is on — see
+ * {@link resolveOrgEmailRamp}. A graduated workspace claims nothing at all:
+ * the ramp does not bind it, and the hourly share that does has already been
+ * claimed by the time this runs.
+ *
+ * **Campaigns only**, like the hourly claim beside it. This function is not
+ * on `sendEmail`'s path and cannot be reached by a transactional message.
+ *
+ * A refused claim writes NOTHING — a campaign that resumes tomorrow must not
+ * have spent tomorrow's budget on being told no.
+ */
+export declare function claimOrgEmailSendDay(options: {
+    orgId: string;
+    /** Messages this batch would send. */
+    count: number;
+    /** What this workspace may send today, from {@link resolveOrgEmailRamp}. */
+    ramp: EmailRampVerdict;
+    /** False parks the control, exactly as the platform governor's flag does. */
+    enabled?: boolean;
+    now?: number;
+    firestore?: any;
+}): Promise<OrgEmailSendDayClaim>;
+/**
+ * Returns the undelivered part of a day's ramp claim.
+ *
+ * The hourly claim is deliberately never reconciled — its window is an hour
+ * and an unrefunded remainder costs the org the rest of it. A DAY is long
+ * enough that the same choice would cost a new workspace its whole first day
+ * over one failed batch, which is the opposite of what a ramp is for.
+ *
+ * **Never throws** and never drives the counter below zero, exactly as
+ * `reconcileCampaignSendReservation` does one surface over.
+ */
+export declare function reconcileOrgEmailSendDay(reservation: OrgEmailSendDayReservation | null | undefined, delivered: number, firestore?: any): Promise<void>;
+/**
+ * How old a workspace is, in days, from whatever its `createdAt` turns out to
+ * be.
+ *
+ * Firestore hands back a `Timestamp`, a restore or a fixture can leave a
+ * number, and an org written before the field existed has nothing. All three
+ * are handled and the last one answers `null`, which
+ * {@link claimOrgEmailSendDay} reads as graduated — the only safe direction,
+ * for the reason stated there.
+ */
+export declare function orgAgeDays(createdAt: unknown, now?: number): number | null;
+/** Re-exported so a caller reads one module for the whole control. */
+export type { EmailReputationPolicy, EmailRampVerdict };