@oxygen-agent/cli 1.987.20 → 1.1010.1

package/node_modules/@oxygen/shared/dist/dnc-rules.js

@@ -0,0 +1,221 @@
+/**
+ * The workspace do-not-contact RULE CATALOG: which events may put somebody on the
+ * DNC list, and what the workspace has decided each one should do.
+ *
+ * WHY THIS EXISTS. Suppression ENFORCEMENT has always been absolute and layered —
+ * enrollment, plan and a dispatch-time re-check per channel — and none of that is
+ * configurable, on purpose: once an identity is on a ledger it always blocks. What
+ * was equally hardcoded, and should not have been, is ENTRY. Six writers decided
+ * unilaterally who lands on the list, and one of them was blunt enough to be a
+ * product complaint in its own right: ANY inbound LinkedIn message suppressed that
+ * person org-wide, forever, so a lead who replied "sure, send me pricing" could
+ * never be enrolled in another campaign again.
+ *
+ * The split this module draws is therefore: the workspace owns WHO GETS ON the
+ * list; the platform still owns WHAT A LIST ENTRY DOES. A rule resolves to one of
+ * three effects:
+ *
+ *   off       — the event is observed and recorded as it always was, but writes no
+ *               suppression. Nothing else about the event changes.
+ *   stop_only — end THIS enrollment, do not write the permanent ledger row. The
+ *               missing middle: "a reply stops the cadence" without "blacklist this
+ *               human from every future campaign".
+ *   suppress  — stop and write the ledger row. The default for every rule that
+ *               shipped before this catalog existed, which is what makes the
+ *               defaults a byte-for-byte reproduction of previous behaviour.
+ *
+ * DEFAULTS ARE THE OLD BEHAVIOUR. Every pre-existing rule defaults to `suppress`
+ * with the exact reason its writer used to hardcode, and every rule introduced with
+ * this catalog defaults to `off`. A workspace that never opens the Rules page keeps
+ * precisely the product it had, and a policy read that fails resolves to these
+ * defaults rather than dropping a suppression on the floor.
+ *
+ * COMPLIANCE RULES ARE CONFIGURABLE, AND FLAGGED. `email_unsubscribe_click` and
+ * `email_hard_bounce` carry `compliance: true`. That flag does not lock them — the
+ * product owner's decision (2026-09-19) is that a workspace may set any rule to any
+ * allowed effect — it marks the two whose surfaces must say plainly what turning
+ * them down means: an explicit unsubscribe request that is not honoured, and a
+ * hard-bounced address that keeps being mailed from the shared pool (which is also
+ * the numerator of the mailbox auto-pause). The warning is the product's job; the
+ * decision is the customer's.
+ */
+/** What a rule does when its event fires. */
+export const DNC_RULE_EFFECTS = ["off", "stop_only", "suppress"];
+export const DNC_RULE_EFFECT_LABELS = {
+    off: "Do nothing",
+    stop_only: "Stop this enrollment only",
+    suppress: "Stop and add to do-not-contact",
+};
+/**
+ * Which ledger a rule writes when it resolves to `suppress`. This decides which
+ * reason enum the configured reason is validated against, so a rule can never be
+ * saved with a reason its target table's CHECK constraint would reject at write
+ * time — the failure has to land on the person changing the setting, not on the
+ * inbound webhook hours later.
+ */
+export const DNC_RULE_LEDGERS = ["email", "contact", "phone"];
+const ALL_EFFECTS = DNC_RULE_EFFECTS;
+const OFF_OR_SUPPRESS = ["off", "suppress"];
+/**
+ * The writers that existed before this catalog, each pinned to the reason and
+ * ledger it used to hardcode. Changing a `defaultEffect` or `defaultReason` here
+ * silently changes every workspace that has not overridden that rule, which is why
+ * `dnc-rules.test.ts` pins every one of them.
+ *
+ * `whatsapp_reply` is the LinkedIn rule's twin and was found the same way: an
+ * inbound WhatsApp message suppressed the lead org-wide with no way to say
+ * otherwise. Its DNC identity is the normalized chat JID rather than a lead
+ * provider id, because `whatsapp_message` is excluded from lead resolution — see
+ * the note in whatsapp-inbox-service.ts about why it is deliberately NOT the
+ * phone ledger.
+ */
+export const DNC_BUILTIN_RULES = [
+    {
+        key: "email_hard_bounce",
+        label: "Email hard bounce",
+        description: "A message to this address bounced permanently.",
+        ledger: "email",
+        defaultEffect: "suppress",
+        defaultReason: "hard_bounce",
+        allowedEffects: ALL_EFFECTS,
+        compliance: true,
+        group: "automatic",
+    },
+    {
+        key: "email_unsubscribe_click",
+        label: "One-click unsubscribe",
+        description: "The recipient used the unsubscribe link in one of your emails.",
+        ledger: "email",
+        defaultEffect: "suppress",
+        defaultReason: "unsubscribe",
+        allowedEffects: ALL_EFFECTS,
+        compliance: true,
+        group: "automatic",
+    },
+    {
+        key: "email_optout_phrase",
+        label: "Opt-out wording in an email reply",
+        description: 'The reply contains an explicit opt-out phrase such as "unsubscribe" or "take me off".',
+        ledger: "email",
+        defaultEffect: "suppress",
+        defaultReason: "unsubscribe",
+        allowedEffects: ALL_EFFECTS,
+        group: "automatic",
+    },
+    {
+        key: "linkedin_reply",
+        label: "LinkedIn reply received",
+        description: "Any inbound LinkedIn message from a lead, whatever it says.",
+        ledger: "contact",
+        defaultEffect: "suppress",
+        defaultReason: "replied",
+        allowedEffects: ALL_EFFECTS,
+        group: "automatic",
+    },
+    {
+        key: "whatsapp_reply",
+        label: "WhatsApp reply received",
+        description: "Any inbound WhatsApp message from a lead, whatever it says.",
+        ledger: "contact",
+        defaultEffect: "suppress",
+        defaultReason: "replied",
+        allowedEffects: ALL_EFFECTS,
+        group: "automatic",
+    },
+    {
+        key: "call_do_not_call",
+        label: 'Call marked "do not call"',
+        description: "A rep set the do-not-call disposition on a call task.",
+        ledger: "phone",
+        defaultEffect: "suppress",
+        defaultReason: "do_not_call",
+        allowedEffects: OFF_OR_SUPPRESS,
+        group: "automatic",
+    },
+    {
+        key: "call_wrong_number",
+        label: 'Call marked "wrong number"',
+        description: "A rep set the wrong-number disposition on a call task.",
+        ledger: "phone",
+        defaultEffect: "suppress",
+        defaultReason: "wrong_number",
+        allowedEffects: OFF_OR_SUPPRESS,
+        group: "automatic",
+    },
+];
+/**
+ * Reply-classification rules are addressed by label key, so an org's own inbox
+ * labels get rules on exactly the same footing as the shipped ones. The prefix
+ * keeps that namespace from ever colliding with a builtin key.
+ */
+export const DNC_REPLY_STATUS_RULE_PREFIX = "reply_status:";
+export function replyStatusRuleKey(labelKey) {
+    return `${DNC_REPLY_STATUS_RULE_PREFIX}${labelKey}`;
+}
+export function replyStatusLabelKey(ruleKey) {
+    if (!ruleKey.startsWith(DNC_REPLY_STATUS_RULE_PREFIX))
+        return null;
+    const labelKey = ruleKey.slice(DNC_REPLY_STATUS_RULE_PREFIX.length).trim();
+    return labelKey.length > 0 ? labelKey : null;
+}
+/**
+ * Build the rule definition for one inbox label. `ledger: "email"` is not a claim
+ * that the rule is email-only — it names which reason enum the reason is validated
+ * against. The applier picks the ledger per identity at write time, because the
+ * same classified conversation can carry an email address, a LinkedIn person, or
+ * both, and a classified LinkedIn DM must be able to suppress the LinkedIn person.
+ */
+export function replyStatusRule(label) {
+    const name = label.name?.trim() || label.key;
+    return {
+        key: replyStatusRuleKey(label.key),
+        label: `Reply classified "${name}"`,
+        description: `A reply in the inbox was classified as ${name}.`,
+        ledger: "email",
+        // New behaviour ships off. Classification is a model judgement, so turning one
+        // of these on is a deliberate act, never something a workspace wakes up to.
+        defaultEffect: "off",
+        defaultReason: "unsubscribe",
+        allowedEffects: ALL_EFFECTS,
+        group: "reply_classification",
+    };
+}
+const BUILTIN_BY_KEY = new Map(DNC_BUILTIN_RULES.map((rule) => [rule.key, rule]));
+/** The builtin definition for a key, or null when the key is not a builtin. */
+export function builtinDncRule(key) {
+    return BUILTIN_BY_KEY.get(key) ?? null;
+}
+export function isDncRuleEffect(value) {
+    return typeof value === "string" && DNC_RULE_EFFECTS.includes(value);
+}
+/**
+ * Resolve a stored rule key to its definition. A `reply_status:*` key resolves even
+ * when the org has since renamed or archived the label, so an override never
+ * becomes unreadable (and therefore unresettable) because a label moved.
+ */
+export function resolveDncRuleDefinition(key, labels) {
+    const builtin = builtinDncRule(key);
+    if (builtin)
+        return builtin;
+    const labelKey = replyStatusLabelKey(key);
+    if (!labelKey)
+        return null;
+    const label = labels?.find((candidate) => candidate.key === labelKey);
+    return replyStatusRule(label ?? { key: labelKey });
+}
+/**
+ * The full catalog a surface renders: the six builtins, then one rule per inbox
+ * label the workspace can classify a reply as.
+ */
+export function dncRuleCatalog(labels = []) {
+    const seen = new Set();
+    const replyRules = [];
+    for (const label of labels) {
+        const key = label.key?.trim();
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        replyRules.push(replyStatusRule(label));
+    }
+    return [...DNC_BUILTIN_RULES, ...replyRules];
+}

package/node_modules/@oxygen/shared/dist/enrichment-intents.d.ts

@@ -0,0 +1,107 @@
+export declare const ENRICHMENT_INTENT_GROUPS: readonly ["person", "contact", "company", "decision_maker", "signal"];
+export type EnrichmentIntentGroup = (typeof ENRICHMENT_INTENT_GROUPS)[number];
+export declare const ENRICHMENT_INTENT_GROUP_LABELS: Record<EnrichmentIntentGroup, string>;
+export type EnrichmentIntentKind = "profile" | "enrichment" | "verification" | "search" | "signal" | "formula" | "template";
+/**
+ * default      — a managed provider chain runs it today; the add path is exact.
+ * selectable   — wired and reachable, but not offered as a one-click default.
+ * no_default   — declared, but no managed default chain yet (an honest refusal
+ *                with the reason and, where known, the candidate providers).
+ * coming_soon  — founder-named for a later slice; projected with no add path.
+ * rejected     — deliberately not offered; carries the decision id.
+ */
+export type EnrichmentIntentStatus = "default" | "selectable" | "no_default" | "coming_soon" | "rejected";
+export type EnrichmentIntentOutputField = {
+    key: string;
+    label: string;
+    /** `company.*` / `person.*` semantic type (packages/tenant-db/src/model.ts) or null. */
+    semanticType: string | null;
+    dataType: "text" | "numeric" | "boolean" | "jsonb" | "timestamptz";
+    /** Read from another field's payload at 0 credits; never fetched on its own. */
+    derived?: true;
+};
+export type EnrichmentIntentSurfaces = {
+    /** `columns add --capability <id>` / MCP column capability. */
+    capability?: string;
+    /** `columns add --preset <id>` / MCP preset. */
+    preset?: string;
+    /**
+     * Company field-catalog keys this row materialises: they point a field at its
+     * row and price a waterfall row. Never a preset flag — no preset takes a field
+     * list since the founder decision of 2026-09-24.
+     */
+    companyFields?: readonly string[];
+    /** One-shot CLI verb, e.g. "find email". */
+    find?: string;
+    /** Managed Functions library id (apps/web/src/lib/managed-functions/catalog.ts). */
+    managedFunction?: string;
+    /** `columns catalog` template key. */
+    template?: string;
+    /** tenant-db ENRICHMENT_COLUMN_CATALOG entry id this row projects into. */
+    catalogEntry?: string;
+    registryFunction?: "enrichment" | "people_search" | "company_search" | "signals";
+    /** Registry intent id whose chains materialise this row. */
+    registryIntent?: string;
+    /** For per-field company rows: the exact `field:<key>` chains of `enrich_company`. */
+    registryInputShapes?: readonly string[];
+};
+export type EnrichmentIntentTaxonomyEntry = {
+    /** Stable id: registry intent id, `enrich_company:<group>`, `people_search:<intent>`, `signals:<intent>`, or a slug. */
+    id: string;
+    /** Customer label: the DATA, never a vendor. */
+    label: string;
+    /** ONE founder-voice line. No vendor names, no cost-structure words. */
+    description: string;
+    entity: "person" | "company";
+    group: EnrichmentIntentGroup;
+    kind: EnrichmentIntentKind;
+    /** ORDER IS THE PRODUCT DECISION: unique, ascending; pickers sort by it. */
+    rank: number;
+    /** Customer phrasings that mean this row; lower-case; feeds discovery. */
+    aliases: readonly string[];
+    /** Identity inputs the customer must hold, in customer words. */
+    inputShapes: readonly string[];
+    outputFields: readonly EnrichmentIntentOutputField[];
+    surfaces: EnrichmentIntentSurfaces;
+    status: EnrichmentIntentStatus;
+    /** Required for no_default | coming_soon | rejected; customer-readable. */
+    statusReason?: string;
+    /** Ledger id (docs/gtm-program/decisions.md); required for rejected rows. */
+    decision?: string;
+    /** Provider ids (metadata only) that document the data, for no_default / coming_soon rows. */
+    candidateProviders?: readonly string[];
+};
+export declare const ENRICHMENT_INTENT_TAXONOMY: readonly EnrichmentIntentTaxonomyEntry[];
+/** True when a customer-facing string leaks vendor cost structure (OXYGEN_PRODUCT.md 2026-08-10). */
+export declare function leaksCostStructure(text: string): boolean;
+export declare function listEnrichmentIntents(filter?: {
+    group?: EnrichmentIntentGroup;
+    status?: EnrichmentIntentStatus | readonly EnrichmentIntentStatus[];
+    entity?: "person" | "company";
+}): EnrichmentIntentTaxonomyEntry[];
+export declare function getEnrichmentIntent(id: string): EnrichmentIntentTaxonomyEntry | null;
+/**
+ * Best taxonomy row for a customer phrasing: the longest alias contained in the
+ * query wins, so "personal email" beats "email" and "decision makers at each
+ * account" beats "account". Rejected rows never match. Null when nothing does.
+ */
+/**
+ * The pointer an older pricing surface carries back to the catalogue, so a
+ * customer who asks "what can I add and what does it cost" on `tools search
+ * --for-table` or `find company --list-fields` is handed the exact catalogue
+ * command instead of a ceiling. The 2026-09-19 blind acceptance run priced a
+ * whole pilot from those two surfaces and never reached `enrichment catalog`,
+ * although the skill it read named it: a new place to look is invisible until
+ * the place the question is asked points at it.
+ */
+export type EnrichmentCatalogPointer = {
+    /** The single data type when the entry maps to exactly one row; null when it fans out to a group. */
+    intent: string | null;
+    group: EnrichmentIntentGroup;
+    exact_command: string;
+};
+/** Catalogue pointer for a column-catalogue entry id such as `preset:company_enrich` or `capability:work_email`. */
+export declare function catalogPointerForEntry(entryId: string): EnrichmentCatalogPointer | null;
+/** Catalogue pointer for one company enrichment field key such as `technologies` or `latest_funding_round`. */
+export declare function catalogPointerForCompanyField(field: string): EnrichmentCatalogPointer | null;
+export declare function findEnrichmentIntentByAlias(query: string): EnrichmentIntentTaxonomyEntry | null;