@oxygen-agent/cli 1.1014.619 → 1.1014.771

package/node_modules/@oxygen/shared/dist/sequences.d.ts

@@ -89,231 +89,7 @@ export declare const SEQUENCE_EMAIL_COLUMN_KEYS: readonly ["email", "email_addre
  * Returns the trimmed raw value (callers normalize/lowercase as needed) or null.
  */
 export declare function recipientEmailFromRow(rowValues: Record<string, unknown> | null | undefined, emailColumnKey?: string | null): string | null;
-/**
- * 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;
+export { ESP_MATCHING_MODES, type EspMatchingMode, DEFAULT_ESP_MATCHING_MODE, isEspMatchingMode, validateEspMatchingSetting, RECIPIENT_ESPS, type RecipientEsp, ESP_ROUTE_BUCKETS, type EspRouteBucket, type EspRouteWeights, type EspSenderExclusion, type EspRoutingPolicy, type EspMatchingSetting, type ResolvedEspPolicy, MAX_ESP_SENDER_EXCLUSIONS, MAX_ESP_ROUTE_WEIGHT, isEspRouteBucket, normalizeEspSenderDomain, espPolicyFromSetting, espRouteWeightsFor, espRouteCandidates, espExcludedSenderDomains, RECIPIENT_ESP_FAMILIES, type RecipientEspFamily, isRecipientEspFamily, isEspGatewayFamily, matchableEspFromFamily, familyFromMxHosts, espFromSpfRecords, inferRecipientEspFamily, inferRecipientEsp, espFromMxHosts, } from "./sequence-internals/esp-policy.js";
 /**
  * row_values keys an enrollment's phone number may live under, in
  * send-precedence order, for WhatsApp sends. The enroll path resolves the FIRST
@@ -1284,4 +1060,3 @@ export declare function secondsSinceSendWindowStart(window: SequenceSendWindow,
  * never hand back an instant the gate would reject.
  */
 export declare function nextSendWindowOpenAt(window: SequenceSendWindow, now: Date, timezone?: string): Date | null;
-export {};