@oxygen-agent/cli 1.1014.620 → 1.1014.773

package/node_modules/@oxygen/shared/dist/sequence-internals/esp-policy.d.ts

@@ -0,0 +1,225 @@
+/**
+ * ESP (email service provider) MATCHING mode for a sequence (settings.esp_matching).
+ * Deliverability lore: a send lands better when the SENDING mailbox and the
+ * RECIPIENT sit on the same provider (Google→Google, Microsoft→Microsoft), so at
+ * mailbox-pick the dispatcher can bias rotation toward a same-ESP mailbox.
+ *   - "off"    — no ESP bias; rotation is pure LRU / domain-spread.
+ *   - "prefer" — (DEFAULT) pick a same-ESP mailbox when one is available, else
+ *     fall back to any sendable mailbox (never blocks a send). On by default
+ *     because it only ever improves deliverability and cannot starve sends.
+ *   - "strict" — require a same-ESP mailbox; when none is available the action is
+ *     DEFERRED with a visible skipped_reason rather than sent cross-provider.
+ *     Power-user setting, reachable via CLI/MCP; the web "Provider Matching"
+ *     checkbox toggles off↔prefer only.
+ */
+export declare const ESP_MATCHING_MODES: readonly ["off", "prefer", "strict"];
+export type EspMatchingMode = (typeof ESP_MATCHING_MODES)[number];
+export declare const DEFAULT_ESP_MATCHING_MODE: EspMatchingMode;
+export declare function isEspMatchingMode(value: unknown): value is EspMatchingMode;
+/**
+ * Validate settings.esp_matching before persistence. Absent/null is valid and
+ * means DEFAULT_ESP_MATCHING_MODE, which is "prefer" — an unset sequence still
+ * biases rotation toward a same-provider sender, so a workspace whose senders on
+ * one provider are in bad standing concentrates that provider's recipients on
+ * them until an operator sets "off". Any other value must be one of the three
+ * modes. Pure; throws OxygenError("invalid_sequence_settings") on a bad value so
+ * the CLI / MCP / API report an identical error. Called from the tenant-db
+ * settings validator alongside the budget/prioritization checks.
+ */
+export declare function validateEspMatchingSetting(value: unknown): void;
+/**
+ * The MATCHABLE email-provider a recipient routes through — the narrow set ESP
+ * matching can act on. Kept intentionally aligned with EMAIL_MAILBOX_PROVIDERS in
+ * tenant-db so a mailbox's `provider` and a resolved recipient ESP compare
+ * directly: we can only bias rotation toward a provider we can actually SEND
+ * from, and the pool is Google/Microsoft only.
+ *
+ * This is deliberately NARROWER than RECIPIENT_ESP_FAMILIES (what we DISPLAY).
+ * A domain behind Proofpoint has family "proofpoint" but may still be matchable
+ * as "microsoft" — see resolveEspFamily.
+ */
+export declare const RECIPIENT_ESPS: readonly ["google", "microsoft"];
+export type RecipientEsp = (typeof RECIPIENT_ESPS)[number];
+/**
+ * WEIGHTED SENDER ROUTING — the object form of settings.esp_matching.
+ *
+ * The three scalar modes above answer one question ("bias toward the recipient's
+ * own provider, yes or no"), and they bake in the assumption that same-provider
+ * is always better. That assumption fails whenever one provider's senders are in
+ * bad standing: a workspace whose Google-hosted domains are refused by Gmail
+ * wants its Google-hosted RECIPIENTS served from Microsoft senders, which no
+ * scalar mode can express. "off" does not express it either, because free
+ * rotation still hands Google recipients a Google sender in proportion to the
+ * pool.
+ *
+ * So the object form states the routing directly, as SEND SHARES per recipient
+ * provider:
+ *
+ *   { mode: "prefer",
+ *     routes: { google: { microsoft: 100 }, microsoft: { microsoft: 100 } },
+ *     exclude: [{ domain: "burned.example", from_recipients: ["google"] }] }
+ *
+ * `routes` is keyed by the RECIPIENT's resolved provider; the inner map is the
+ * SENDER provider. Weights are relative shares, so { google: 3, microsoft: 1 }
+ * and { google: 75, microsoft: 25 } are the same policy and nothing has to sum
+ * to 100. An omitted weight is zero. A bucket whose entry is explicitly present
+ * but carries no positive weight means "no opinion, rotate freely for this
+ * recipient class"; a bucket the operator never mentioned keeps the historical
+ * same-provider default, so editing Google routing cannot silently change how
+ * Microsoft recipients are served.
+ *
+ * `exclude` is a hard never, not a preference: a sender domain listed here is
+ * removed from the candidate pool for the named recipient buckets (all buckets
+ * when `from_recipients` is absent) in EVERY mode, including "off", and it
+ * survives the prefer-fallback. A deliverability guard that a matching toggle
+ * could disarm would not be a guard.
+ *
+ * The scalar modes remain valid values and are read as policies, so there is one
+ * routing code path rather than two: "prefer" becomes { mode: "prefer" } with no
+ * routes, which resolves to the same-provider default and behaves exactly as it
+ * did before.
+ */
+export declare const ESP_ROUTE_BUCKETS: readonly ["google", "microsoft", "unknown"];
+/** The RECIPIENT side of a route: a matchable provider, or "unknown" when resolution failed. */
+export type EspRouteBucket = (typeof ESP_ROUTE_BUCKETS)[number];
+/** The SENDER side of a route: relative send shares per mailbox provider. */
+export type EspRouteWeights = Partial<Record<RecipientEsp, number>>;
+export type EspSenderExclusion = {
+    domain: string;
+    from_recipients?: EspRouteBucket[];
+};
+export type EspRoutingPolicy = {
+    mode?: EspMatchingMode;
+    routes?: Partial<Record<EspRouteBucket, EspRouteWeights>>;
+    exclude?: EspSenderExclusion[];
+};
+/** settings.esp_matching accepts either the legacy scalar or the routing policy. */
+export type EspMatchingSetting = EspMatchingMode | EspRoutingPolicy;
+/**
+ * A policy with every field present, which is what the dispatcher and the launch
+ * preview consume. Produced only by espPolicyFromSetting so both surfaces answer
+ * identically from the same stored value.
+ */
+export type ResolvedEspPolicy = {
+    mode: EspMatchingMode;
+    routes: Partial<Record<EspRouteBucket, EspRouteWeights>>;
+    exclude: Array<{
+        domain: string;
+        buckets: readonly EspRouteBucket[];
+    }>;
+};
+/** Cap on settings.esp_matching.exclude — a routing policy, not a suppression list. */
+export declare const MAX_ESP_SENDER_EXCLUSIONS = 50;
+/** Upper bound on a single route weight; relative shares never need more. */
+export declare const MAX_ESP_ROUTE_WEIGHT = 1000000;
+export declare function isEspRouteBucket(value: unknown): value is EspRouteBucket;
+/**
+ * A sending domain as the mailbox table stores it: lowercase, no leading "@".
+ * Mirrors lower(split_part(email_address, '@', 2)) in pickEmailMailbox so an
+ * exclusion the operator typed as "@Burned.Example " still matches.
+ */
+export declare function normalizeEspSenderDomain(value: string): string;
+/**
+ * LENIENT read of a persisted settings.esp_matching (never throws — a read must
+ * not break a send). Absent, null, or malformed reads as the default policy, and
+ * a malformed FIELD bails the WHOLE object rather than half-applying a routing
+ * policy, which is the readMailboxRampConfig convention in tenant-db. The strict
+ * counterpart that guards the write path is validateEspMatchingSetting.
+ */
+export declare function espPolicyFromSetting(value: unknown): ResolvedEspPolicy;
+/**
+ * The effective send shares for one recipient bucket. An explicitly-present
+ * entry wins even when it is empty or all-zero (that is the operator saying
+ * "rotate freely here"); a bucket that was never mentioned keeps the historical
+ * same-provider default, and "unknown" has no same-provider to default to.
+ */
+export declare function espRouteWeightsFor(policy: ResolvedEspPolicy, bucket: EspRouteBucket): EspRouteWeights;
+/**
+ * The sender providers to try, best first, for one recipient bucket — a
+ * deterministic weighted shuffle WITHOUT replacement.
+ *
+ * Returning an ORDER rather than a single draw is what makes "prefer" correct:
+ * a 90/10 Google policy over a pool holding no Google mailbox must send 100%
+ * from Microsoft, not defer and not fall through to provider-blind rotation.
+ * An empty result means "no opinion" and the caller rotates freely.
+ *
+ * Deterministic by construction: the seed carries the enrollment and step, never
+ * a clock or Math.random, so a dry-run preview and the later live send choose
+ * the same provider, and a replan after a defer re-derives the same route.
+ * Candidates are enumerated in RECIPIENT_ESPS order rather than object-key
+ * order, because jsonb does not preserve key order and a policy that round-trips
+ * through the database must not reroute the fleet.
+ */
+export declare function espRouteCandidates(input: {
+    policy: ResolvedEspPolicy;
+    recipient: EspRouteBucket;
+    seed: string;
+}): RecipientEsp[];
+/**
+ * Sending domains that must not serve this recipient bucket, normalized and
+ * de-duplicated for pickEmailMailbox. Applies in every mode and survives the
+ * prefer-fallback — see the exclude contract above.
+ */
+export declare function espExcludedSenderDomains(policy: ResolvedEspPolicy, bucket: EspRouteBucket): string[];
+/**
+ * The DISPLAY taxonomy: the mail-infrastructure family a recipient domain sits
+ * on. Wider than RecipientEsp because "everything that isn't Google or Microsoft"
+ * is not one thing — a list that is 23% Proofpoint is a very different
+ * deliverability problem from one that is 23% self-hosted, and collapsing both to
+ * null (today's behavior) hides that. Split into three groups:
+ *
+ *   - MAILBOX providers (google, microsoft) — imply a matchable ESP.
+ *   - GATEWAY vendors (proofpoint, mimecast, ...) — security filters that sit IN
+ *     FRONT of a mailbox provider. Their MX tells you the filter, NOT where the
+ *     mailbox lives; the SPF fallback is what sees behind them.
+ *   - OTHER mailbox hosts (zoho, yahoo, fastmail, ...) and self_hosted — real
+ *     destinations we simply cannot send as, so never matchable.
+ */
+export declare const RECIPIENT_ESP_FAMILIES: readonly ["google", "microsoft", "proofpoint", "mimecast", "barracuda", "cisco", "zscaler", "trendmicro", "sophos", "zoho", "yahoo", "apple", "proton", "fastmail", "gmx", "amazon", "self_hosted"];
+export type RecipientEspFamily = (typeof RECIPIENT_ESP_FAMILIES)[number];
+export declare function isRecipientEspFamily(value: unknown): value is RecipientEspFamily;
+export declare function isEspGatewayFamily(family: RecipientEspFamily | null | undefined): boolean;
+/**
+ * The matchable ESP a display family implies, or null when the family is a
+ * gateway (unknown until SPF) or a provider we cannot send as. The ONLY place
+ * family → esp is decided, so display and matching can't drift.
+ */
+export declare function matchableEspFromFamily(family: RecipientEspFamily | null | undefined): RecipientEsp | null;
+/**
+ * Map a domain's resolved MX exchange hostnames to a DISPLAY family. Returns null
+ * when no host matches any known vendor — the caller records that as
+ * "self_hosted" only once it is sure the lookup itself succeeded (an empty/failed
+ * answer is "unknown", which is a different fact).
+ */
+export declare function familyFromMxHosts(hosts: readonly string[] | null | undefined): RecipientEspFamily | null;
+/**
+ * Resolve the matchable ESP from a domain's TXT records by reading its SPF
+ * mechanisms. Scans every `v=spf1` record's include:/redirect= targets.
+ *
+ * AMBIGUITY IS NOT GUESSED: a domain mid-migration (or running Workspace
+ * alongside an Office tenant) can include BOTH vendors. Returning either one
+ * would be a coin flip that strict matching then acts on, so a both-match
+ * degrades to null ("unknown") and the caller falls back / defers honestly.
+ */
+export declare function espFromSpfRecords(records: readonly string[] | null | undefined): RecipientEsp | null;
+/**
+ * Infer a recipient's DISPLAY family from its domain string alone,
+ * DETERMINISTICALLY, for the well-known consumer/freemail domains. Returns null
+ * for any other domain — the caller then resolves via the cached MX (+ SPF)
+ * lookup, because a custom domain fronted by Workspace / M365 / a gateway is not
+ * decidable from the string. Pure: the single source of truth for the map.
+ */
+export declare function inferRecipientEspFamily(domain: string | null | undefined): RecipientEspFamily | null;
+/**
+ * Infer a recipient's MATCHABLE ESP from its domain string. Narrow by design:
+ * only the Google/Microsoft consumer domains resolve here, everything else
+ * (including yahoo/proton/icloud, which are real but unsendable-as) is null.
+ * Unchanged contract — the dispatcher's fast path still calls this.
+ */
+export declare function inferRecipientEsp(domain: string | null | undefined): RecipientEsp | null;
+/**
+ * Back-compat narrow view of familyFromMxHosts: MX hosts → matchable ESP. Now
+ * derived from the family table so the two can't drift, and gateway MX hosts
+ * correctly yield null here (they need the SPF signal to become matchable).
+ */
+export declare function espFromMxHosts(hosts: readonly string[] | null | undefined): RecipientEsp | null;