fullstackgtm 0.47.0 → 0.49.0

package/src/route.ts

@@ -0,0 +1,278 @@
+import { resolveAssignment, type AssignmentContext, type AssignmentPolicy } from "./assign.ts";
+import { FREE_EMAIL_DOMAINS } from "./freeEmailDomains.ts";
+import { normalizeDomain } from "./merge.ts";
+import { stableHash } from "./rules.ts";
+import type { CanonicalAccount, CanonicalContact, CanonicalGtmSnapshot, PatchOperation, PatchPlan } from "./types.ts";
+
+/**
+ * Lead-to-account matching and routing recipes.
+ *
+ * This is the first packaged Traction-Complete-style workflow in the OSS CLI:
+ * take ownerless/unmatched leads, deterministically match them to accounts, and
+ * emit normal approval-gated patch operations. No writes happen here.
+ */
+
+export type LeadRouteOptions = {
+  /** Match contact email domains to account domains. Default true. */
+  matchByDomain?: boolean;
+  /** Also try raw company/name fields against account names when domain misses. */
+  matchByCompanyName?: boolean;
+  /** When an ownerless contact matches an owned account, set contact ownerId to the account owner. Default true. */
+  inheritAccountOwner?: boolean;
+  /** Reassign contacts that already have an owner when the matched account owner differs. Default false. */
+  reassignExistingOwner?: boolean;
+  /** Optional fallback policy for contacts that still do not have an owner. */
+  assignmentPolicy?: AssignmentPolicy;
+  /** Refuse to build larger plans unless explicitly raised. Default 500. */
+  maxOperations?: number;
+  reason?: string;
+};
+
+export type LeadRouteCounts = {
+  contactsScanned: number;
+  /** Contacts that ended with an unambiguous account context (existing link, domain match, or company-name match). */
+  matchedContacts: number;
+  matchedExistingAccount: number;
+  matchedByDomain: number;
+  matchedByCompanyName: number;
+  ambiguousAccountMatches: number;
+  skippedFreeEmail: number;
+  linkOperations: number;
+  /** Owner set_field operations proposed (account-owner inheritance + policy fallback). */
+  ownerOperations: number;
+  /** Alias for ownerOperations, named for reports that talk about owner-assigned leads. */
+  ownerAssigned: number;
+  policyAssigned: number;
+  unmatched: number;
+};
+
+export type LeadRouteResult = {
+  plan: PatchPlan;
+  counts: LeadRouteCounts;
+};
+
+function norm(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  const out = String(value).trim().toLowerCase();
+  return out || undefined;
+}
+
+function contactEmailDomain(contact: CanonicalContact): string | undefined {
+  const email = norm(contact.email);
+  if (!email || !email.includes("@")) return undefined;
+  return normalizeDomain(email.slice(email.lastIndexOf("@") + 1));
+}
+
+function rawString(record: { raw?: unknown }, keys: string[]): string | undefined {
+  if (!record.raw || typeof record.raw !== "object") return undefined;
+  const raw = record.raw as Record<string, unknown>;
+  for (const key of keys) {
+    const value = raw[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+    if (value && typeof value === "object") {
+      const nested = value as Record<string, unknown>;
+      for (const nestedKey of ["value", "name", "label"]) {
+        if (typeof nested[nestedKey] === "string" && String(nested[nestedKey]).trim()) {
+          return String(nested[nestedKey]).trim();
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+function companyNameFor(contact: CanonicalContact): string | undefined {
+  return rawString(contact, ["company", "companyName", "company_name", "account", "accountName", "account_name"]);
+}
+
+function uniqueAccount(matches: CanonicalAccount[]): CanonicalAccount | "ambiguous" | null {
+  const byId = new Map(matches.map((account) => [String(account.id), account]));
+  const unique = [...byId.values()];
+  if (unique.length === 0) return null;
+  if (unique.length > 1) return "ambiguous";
+  return unique[0];
+}
+
+function employeeBand(employeeCount: number | undefined): string | undefined {
+  if (employeeCount === undefined) return undefined;
+  if (employeeCount <= 10) return "1-10";
+  if (employeeCount <= 50) return "11-50";
+  if (employeeCount <= 200) return "51-200";
+  if (employeeCount <= 1000) return "201-1000";
+  return "1001+";
+}
+
+function routeContext(contact: CanonicalContact, account?: CanonicalAccount): AssignmentContext {
+  const geo = norm(rawString(contact, ["country", "countryCode", "country_code", "state", "region"])) ??
+    norm(rawString(account ?? { raw: undefined }, ["country", "countryCode", "country_code", "state", "region"]));
+  const department = norm(rawString(contact, ["department", "jobDepartment", "job_department"]));
+  return {
+    geo,
+    industry: norm(account?.industry),
+    employeeBand: employeeBand(account?.employeeCount),
+    department,
+    title: norm(contact.title),
+    accountOwnerId: account?.ownerId,
+  };
+}
+
+function activeOwnerIds(snapshot: CanonicalGtmSnapshot): Set<string> {
+  const ids = new Set<string>();
+  for (const user of snapshot.users) {
+    if (user.active === false) continue;
+    ids.add(String(user.id));
+    if (user.crmId) ids.add(String(user.crmId));
+  }
+  return ids;
+}
+
+export function buildLeadRoutePlan(snapshot: CanonicalGtmSnapshot, options: LeadRouteOptions = {}): LeadRouteResult {
+  const matchByDomain = options.matchByDomain ?? true;
+  const matchByCompanyName = options.matchByCompanyName ?? false;
+  const inheritAccountOwner = options.inheritAccountOwner ?? true;
+  const reassignExistingOwner = options.reassignExistingOwner ?? false;
+  const maxOperations = options.maxOperations ?? 500;
+
+  const accountsByDomain = new Map<string, CanonicalAccount[]>();
+  const accountsByName = new Map<string, CanonicalAccount[]>();
+  for (const account of snapshot.accounts) {
+    const domain = normalizeDomain(account.domain);
+    if (domain) accountsByDomain.set(domain, [...(accountsByDomain.get(domain) ?? []), account]);
+    const name = norm(account.name);
+    if (name) accountsByName.set(name, [...(accountsByName.get(name) ?? []), account]);
+  }
+
+  const operations: PatchOperation[] = [];
+  const counts: LeadRouteCounts = {
+    contactsScanned: 0,
+    matchedContacts: 0,
+    matchedExistingAccount: 0,
+    matchedByDomain: 0,
+    matchedByCompanyName: 0,
+    ambiguousAccountMatches: 0,
+    skippedFreeEmail: 0,
+    linkOperations: 0,
+    ownerOperations: 0,
+    ownerAssigned: 0,
+    policyAssigned: 0,
+    unmatched: 0,
+  };
+  const knownOwners = activeOwnerIds(snapshot);
+  let policyAssignmentIndex = 0;
+
+  for (const contact of snapshot.contacts) {
+    counts.contactsScanned += 1;
+    const currentAccount = contact.accountId ? snapshot.accounts.find((account) => account.id === contact.accountId) : undefined;
+    let matchedAccount: CanonicalAccount | undefined = currentAccount;
+    let matchRule: "existing" | "domain" | "company-name" | undefined = currentAccount ? "existing" : undefined;
+    if (currentAccount) counts.matchedExistingAccount += 1;
+
+    let skippedFreeEmail = false;
+    if (!matchedAccount && matchByDomain) {
+      const domain = contactEmailDomain(contact);
+      if (domain && FREE_EMAIL_DOMAINS.has(domain)) {
+        counts.skippedFreeEmail += 1;
+        skippedFreeEmail = true;
+      } else if (domain) {
+        const match = uniqueAccount(accountsByDomain.get(domain) ?? []);
+        if (match === "ambiguous") counts.ambiguousAccountMatches += 1;
+        else if (match) {
+          matchedAccount = match;
+          matchRule = "domain";
+          counts.matchedByDomain += 1;
+        }
+      }
+    }
+
+    if (!matchedAccount && matchByCompanyName && !skippedFreeEmail) {
+      const company = norm(companyNameFor(contact));
+      if (company && (accountsByName.get(company) ?? []).length > 0) {
+        // Name-only account matches are not safe enough to auto-link. Keep the
+        // contact unmatched and surface the skipped match as ambiguous.
+        counts.ambiguousAccountMatches += 1;
+      }
+    }
+
+    if (matchedAccount) counts.matchedContacts += 1;
+
+    const contactOps: PatchOperation[] = [];
+    if (matchedAccount && !contact.accountId) {
+      contactOps.push({
+        id: `op_${stableHash(`route:link:${contact.id}:${matchedAccount.id}`)}`,
+        objectType: "contact",
+        objectId: String(contact.id),
+        operation: "link_record",
+        field: "accountId",
+        beforeValue: contact.accountId ?? null,
+        afterValue: String(matchedAccount.id),
+        reason: options.reason ?? `Lead-to-account match by ${matchRule}: link contact to account ${matchedAccount.name} (${matchedAccount.id}).`,
+        riskLevel: "medium",
+        approvalRequired: true,
+        sourceRuleOrPolicy: "route.lead_to_account",
+      });
+      counts.linkOperations += 1;
+    }
+
+    let ownerId: string | null = null;
+    let ownerRule: string | undefined;
+    if (
+      inheritAccountOwner &&
+      matchedAccount?.ownerId &&
+      matchedAccount.ownerId !== contact.ownerId &&
+      (!contact.ownerId || reassignExistingOwner) &&
+      knownOwners.has(matchedAccount.ownerId)
+    ) {
+      ownerId = matchedAccount.ownerId;
+      ownerRule = "account-owner";
+    } else if (options.assignmentPolicy && !contact.ownerId) {
+      const assigned = resolveAssignment(options.assignmentPolicy, routeContext(contact, matchedAccount), policyAssignmentIndex, knownOwners);
+      policyAssignmentIndex += 1;
+      ownerId = assigned.ownerId;
+      ownerRule = assigned.rule;
+      if (ownerId) counts.policyAssigned += 1;
+    }
+
+    if (ownerId && ownerId !== contact.ownerId) {
+      contactOps.push({
+        id: `op_${stableHash(`route:owner:${contact.id}:${ownerId}`)}`,
+        objectType: "contact",
+        objectId: String(contact.id),
+        operation: "set_field",
+        field: "ownerId",
+        beforeValue: contact.ownerId ?? null,
+        afterValue: ownerId,
+        reason: options.reason ?? `Route contact owner by ${ownerRule ?? "policy"}${matchedAccount ? ` after matching account ${matchedAccount.name}` : ""}.`,
+        riskLevel: "medium",
+        approvalRequired: true,
+        sourceRuleOrPolicy: "route.owner_assignment",
+      });
+      counts.ownerOperations += 1;
+      counts.ownerAssigned = counts.ownerOperations;
+    }
+
+    if (contactOps.length > 1) {
+      const groupId = `grp_route_${contact.id}`;
+      for (const operation of contactOps) operation.groupId = groupId;
+    }
+    operations.push(...contactOps);
+
+    if (!matchedAccount) counts.unmatched += 1;
+  }
+
+  if (operations.length > maxOperations) {
+    throw new Error(`route would create ${operations.length} operations — above the ${maxOperations}-operation safety cap. Raise --max-operations after reviewing scope.`);
+  }
+
+  const plan: PatchPlan = {
+    id: `patch_plan_${stableHash(`route:${snapshot.provider}:${snapshot.generatedAt}:${operations.map((op) => op.id).join(",")}`)}`,
+    title: "Route leads: match contacts to accounts and owners",
+    createdAt: snapshot.generatedAt,
+    status: operations.length > 0 ? "needs_approval" : "draft",
+    dryRun: true,
+    summary: `${counts.matchedContacts} matched contact(s), ${counts.linkOperations} lead-to-account link(s), ${counts.ownerOperations} owner assignment(s), ${counts.ambiguousAccountMatches} ambiguous match(es), ${counts.unmatched} unmatched contact(s). Dry-run only; approve before apply.`,
+    findings: [],
+    operations,
+  };
+
+  return { plan, counts };
+}

package/src/rules.ts

@@ -7,6 +7,7 @@ import type {
   CanonicalGtmSnapshot,
   GtmAuditRule,
   GtmSnapshotIndex,
+  PatchPlanAssumption,
   RiskLevel,
 } from "./types.ts";
 
@@ -50,6 +51,109 @@ export function patchOperationId(ruleId: string, objectId: string) {
   return `op_${stableHash(`${ruleId}:${objectId}`)}`;
 }
 
+
+const OPEN_DEAL_FLAGS_ASSUMPTION: PatchPlanAssumption = {
+  id: "open-deal-derived-from-closed-won-flags",
+  text: "Derived open-deal status from canonical isClosed/isWon flags; a deal is open when neither flag is true.",
+  source: "CanonicalDeal.isClosed/isWon",
+  confidence: "derived",
+};
+
+const MISSING_CLOSED_WON_FLAGS_ASSUMPTION: PatchPlanAssumption = {
+  id: "missing-closed-won-flags-treated-open",
+  text: "Treated deals with missing isClosed/isWon flags as open so hygiene rules do not silently ignore active pipeline.",
+  source: "CanonicalDeal.isClosed/isWon",
+  confidence: "heuristic",
+};
+
+const ORPHAN_ACCOUNT_RELATIONSHIP_ASSUMPTION: PatchPlanAssumption = {
+  id: "account-without-contacts-or-deals-treated-orphan",
+  text: "Treated an account as orphaned when the snapshot has no contacts and no deals linked to that account.",
+  source: "snapshot account/contact/deal associations",
+  confidence: "derived",
+};
+
+const DEAL_OWNER_POLICY_ASSUMPTION: PatchPlanAssumption = {
+  id: "deal-owner-required-by-policy",
+  text: "Treated a missing or unknown deal owner as invalid when requireDealOwner policy is enabled.",
+  source: "GtmPolicy.requireDealOwner",
+  confidence: "heuristic",
+};
+
+const DEAL_ACCOUNT_POLICY_ASSUMPTION: PatchPlanAssumption = {
+  id: "deal-account-required-by-policy",
+  text: "Treated a missing or unknown deal account link as invalid when requireAccountForDeal policy is enabled.",
+  source: "GtmPolicy.requireAccountForDeal",
+  confidence: "heuristic",
+};
+
+const DEAL_AMOUNT_POLICY_ASSUMPTION: PatchPlanAssumption = {
+  id: "open-deal-amount-required-by-policy",
+  text: "Treated open deals with missing or zero amount as forecast-risk findings unless requireDealAmount is disabled.",
+  source: "GtmPolicy.requireDealAmount",
+  confidence: "heuristic",
+};
+
+const DUPLICATE_ACCOUNT_DOMAIN_ASSUMPTION: PatchPlanAssumption = {
+  id: "same-normalized-domain-duplicate-account",
+  text: "Treated accounts with the same normalized domain as duplicate-account candidates.",
+  source: "CanonicalAccount.domain",
+  confidence: "heuristic",
+};
+
+const DUPLICATE_CONTACT_EMAIL_ASSUMPTION: PatchPlanAssumption = {
+  id: "same-email-duplicate-contact",
+  text: "Treated contacts with the same lowercased email address as duplicate-contact candidates.",
+  source: "CanonicalContact.email",
+  confidence: "heuristic",
+};
+
+const DUPLICATE_OPEN_DEAL_ASSUMPTION: PatchPlanAssumption = {
+  id: "same-account-and-name-duplicate-open-deal",
+  text: "Treated open deals with the same normalized name on the same account scope as duplicate-opportunity candidates.",
+  source: "CanonicalDeal.accountId/name",
+  confidence: "heuristic",
+};
+
+const ACCOUNT_WITH_OPEN_DEAL_NEEDS_CONTACT_ASSUMPTION: PatchPlanAssumption = {
+  id: "open-pipeline-account-needs-contact",
+  text: "Treated accounts with open pipeline but no linked contacts as coverage gaps requiring a buying-committee contact.",
+  source: "snapshot account/contact/deal associations",
+  confidence: "heuristic",
+};
+
+const SINGLE_SOURCE_ACCOUNT_ASSUMPTION: PatchPlanAssumption = {
+  id: "single-source-account-is-cross-system-gap",
+  text: "Treated an account present in only one connected system as a cross-system reconciliation gap.",
+  source: "ProviderIdentity.provider",
+  confidence: "heuristic",
+};
+
+function staleDealPolicyAssumption(days: number): PatchPlanAssumption {
+  return {
+    id: "stale-deal-days-policy",
+    text: `Treated open deals with no recorded activity for more than ${days} days as stale.`,
+    source: "GtmPolicy.staleDealDays",
+    confidence: "heuristic",
+  };
+}
+
+function closingSoonPolicyAssumption(windowDays: number, idleDays: number): PatchPlanAssumption {
+  return {
+    id: "closing-soon-idle-policy",
+    text: `Treated open deals closing within ${windowDays} days and idle for more than ${idleDays} days as silent slip risk.`,
+    source: "GtmPolicy.closingSoonDays/closingSoonIdleDays",
+    confidence: "heuristic",
+  };
+}
+
+function assumptionsIfFindings(
+  findings: AuditFinding[],
+  assumptions: PatchPlanAssumption[],
+): PatchPlanAssumption[] | undefined {
+  return findings.length > 0 ? assumptions : undefined;
+}
+
 export function stableHash(value: string) {
   let hash = 0;
   for (let index = 0; index < value.length; index += 1) {
@@ -168,7 +272,11 @@ export const orphanAccountRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [ORPHAN_ACCOUNT_RELATIONSHIP_ASSUMPTION]),
+    };
   },
 };
 
@@ -198,7 +306,11 @@ export const missingDealOwnerRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [DEAL_OWNER_POLICY_ASSUMPTION]),
+    };
   },
 };
 
@@ -227,7 +339,11 @@ export const missingDealAccountRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [DEAL_ACCOUNT_POLICY_ASSUMPTION]),
+    };
   },
 };
 
@@ -256,7 +372,14 @@ export const pastCloseDateRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+      ]),
+    };
   },
 };
 
@@ -297,7 +420,15 @@ export const staleDealRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        staleDealPolicyAssumption(policy.staleDealDays),
+      ]),
+    };
   },
 };
 
@@ -327,7 +458,15 @@ export const missingDealAmountRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        DEAL_AMOUNT_POLICY_ASSUMPTION,
+      ]),
+    };
   },
 };
 
@@ -382,7 +521,11 @@ export const duplicateAccountDomainRule: GtmAuditRule = {
           "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [DUPLICATE_ACCOUNT_DOMAIN_ASSUMPTION]),
+    };
   },
 };
 
@@ -422,7 +565,11 @@ export const duplicateContactEmailRule: GtmAuditRule = {
           "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [DUPLICATE_CONTACT_EMAIL_ASSUMPTION]),
+    };
   },
 };
 
@@ -473,7 +620,15 @@ export const duplicateOpenDealRule: GtmAuditRule = {
           "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        DUPLICATE_OPEN_DEAL_ASSUMPTION,
+      ]),
+    };
   },
 };
 
@@ -514,7 +669,15 @@ export const activeDealAccountWithoutContactsRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        ACCOUNT_WITH_OPEN_DEAL_NEEDS_CONTACT_ASSUMPTION,
+      ]),
+    };
   },
 };
 
@@ -559,13 +722,22 @@ export const closingSoonInactiveRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        closingSoonPolicyAssumption(windowDays, idleDays),
+      ]),
+    };
   },
 };
 
 export const accountSingleSourceRule: GtmAuditRule = {
   id: "account-single-source",
   title: "Account exists in only one connected system",
+  emitsOperations: false,
   description:
     "On merged multi-system snapshots, flags accounts known to just one source — the seams where GTM systems disagree.",
   category: "cross-system",
@@ -597,10 +769,18 @@ export const accountSingleSourceRule: GtmAuditRule = {
           "Check whether the account is missing from the other systems or matched under a different domain/name.",
       });
     }
-    return { findings, operations: [] };
+    return {
+      findings,
+      operations: [],
+      assumptions: assumptionsIfFindings(findings, [SINGLE_SOURCE_ACCOUNT_ASSUMPTION]),
+    };
   },
 };
 
+export function isFindingsOnlyRule(rule: GtmAuditRule): boolean {
+  return rule.emitsOperations === false;
+}
+
 export const builtinAuditRules: GtmAuditRule[] = [
   orphanAccountRule,
   missingDealOwnerRule,