fullstackgtm 0.47.0 → 0.48.0

package/dist/relationships.d.ts

@@ -0,0 +1,39 @@
+import type { CanonicalGtmSnapshot } from "./types.ts";
+export type StakeholderRole = "economic_buyer" | "decision_maker" | "technical_buyer" | "champion" | "influencer" | "unknown";
+export type StakeholderSentiment = "positive" | "neutral" | "negative" | "unknown";
+export type StakeholderNode = {
+    contactId: string;
+    name: string;
+    title?: string;
+    email?: string;
+    role: StakeholderRole;
+    sentiment: StakeholderSentiment;
+    lastActivityAt?: string;
+    evidence: string[];
+};
+export type RelationshipMap = {
+    account: {
+        accountId: string;
+        name: string;
+        domain?: string;
+    };
+    stakeholders: StakeholderNode[];
+    openDeals: Array<{
+        dealId: string;
+        name: string;
+        stage?: string;
+        amount?: number;
+        ownerId?: string;
+    }>;
+    gaps: string[];
+    counts: {
+        stakeholders: number;
+        openDeals: number;
+        activities: number;
+    };
+};
+export declare function buildRelationshipMap(snapshot: CanonicalGtmSnapshot, selector: {
+    accountId?: string;
+    domain?: string;
+}): RelationshipMap;
+export declare function relationshipMapToMarkdown(map: RelationshipMap): string;

package/dist/relationships.js

@@ -0,0 +1,101 @@
+import { normalizeDomain } from "./merge.js";
+function fullName(contact) {
+    return [contact.firstName, contact.lastName].filter(Boolean).join(" ") || contact.email || contact.id;
+}
+function inferRole(title) {
+    const t = (title ?? "").toLowerCase();
+    if (/\b(cfo|ceo|coo|cro|chief|founder|owner|president)\b/.test(t))
+        return "economic_buyer";
+    if (/\b(vp|vice president|head of|director|gm|general manager)\b/.test(t))
+        return "decision_maker";
+    if (/\b(cto|cio|security|it|engineering|architect|developer|technical|data)\b/.test(t))
+        return "technical_buyer";
+    if (/\b(champion|revops|sales ops|revenue operations|operations)\b/.test(t))
+        return "champion";
+    if (t)
+        return "influencer";
+    return "unknown";
+}
+function inferSentiment(text) {
+    const lower = text.toLowerCase();
+    if (/\b(blocked|concern|risk|no budget|not interested|detractor|negative|unhappy)\b/.test(lower))
+        return "negative";
+    if (/\b(champion|excited|interested|positive|approved|referred|next step|pilot)\b/.test(lower))
+        return "positive";
+    return "neutral";
+}
+function maxSentiment(a, b) {
+    const rank = { unknown: 0, neutral: 1, positive: 2, negative: 3 };
+    return rank[b] > rank[a] ? b : a;
+}
+function findAccount(snapshot, selector) {
+    if (selector.accountId)
+        return snapshot.accounts.find((account) => String(account.id) === selector.accountId) ?? null;
+    if (selector.domain) {
+        const domain = normalizeDomain(selector.domain);
+        return snapshot.accounts.find((account) => normalizeDomain(account.domain) === domain) ?? null;
+    }
+    return null;
+}
+export function buildRelationshipMap(snapshot, selector) {
+    const account = findAccount(snapshot, selector);
+    if (!account)
+        throw new Error("relationships: account not found (use --account-id or --domain)");
+    const contacts = snapshot.contacts.filter((contact) => contact.accountId === account.id);
+    const contactIds = new Set(contacts.map((contact) => contact.id));
+    const activities = snapshot.activities.filter((activity) => activity.accountId === account.id || (activity.contactId ? contactIds.has(activity.contactId) : false));
+    const evidenceByContact = new Map();
+    const sentimentByContact = new Map();
+    for (const activity of activities) {
+        if (!activity.contactId || !contactIds.has(activity.contactId))
+            continue;
+        const text = [activity.subject, activity.type, activity.occurredAt].filter(Boolean).join(" — ");
+        evidenceByContact.set(activity.contactId, [...(evidenceByContact.get(activity.contactId) ?? []), text]);
+        sentimentByContact.set(activity.contactId, maxSentiment(sentimentByContact.get(activity.contactId) ?? "unknown", inferSentiment(text)));
+    }
+    const stakeholders = contacts.map((contact) => ({
+        contactId: String(contact.id),
+        name: fullName(contact),
+        ...(contact.title ? { title: contact.title } : {}),
+        ...(contact.email ? { email: contact.email } : {}),
+        role: inferRole(contact.title),
+        sentiment: sentimentByContact.get(contact.id) ?? "unknown",
+        ...(contact.lastActivityAt ? { lastActivityAt: contact.lastActivityAt } : {}),
+        evidence: evidenceByContact.get(contact.id) ?? [],
+    })).sort((a, b) => a.role.localeCompare(b.role) || a.name.localeCompare(b.name));
+    const openDeals = snapshot.deals.filter((deal) => deal.accountId === account.id && !deal.isClosed).map((deal) => ({
+        dealId: String(deal.id),
+        name: deal.name,
+        ...(deal.stage ? { stage: deal.stage } : {}),
+        ...(deal.amount !== undefined ? { amount: deal.amount } : {}),
+        ...(deal.ownerId ? { ownerId: deal.ownerId } : {}),
+    }));
+    const roles = new Set(stakeholders.map((s) => s.role));
+    const gaps = [];
+    if (!roles.has("economic_buyer"))
+        gaps.push("No obvious economic buyer found from titles.");
+    if (!roles.has("decision_maker"))
+        gaps.push("No obvious decision maker found from titles.");
+    if (stakeholders.every((s) => s.sentiment === "unknown"))
+        gaps.push("No stakeholder activity evidence attached to this account.");
+    return { account: { accountId: String(account.id), name: account.name, ...(account.domain ? { domain: account.domain } : {}) }, stakeholders, openDeals, gaps, counts: { stakeholders: stakeholders.length, openDeals: openDeals.length, activities: activities.length } };
+}
+export function relationshipMapToMarkdown(map) {
+    const lines = [`# Relationship map: ${map.account.name}`, "", `${map.counts.stakeholders} stakeholder(s), ${map.counts.openDeals} open deal(s), ${map.counts.activities} activity record(s).`, "", "## Stakeholders"];
+    for (const s of map.stakeholders) {
+        lines.push(`- ${s.name} — ${s.role}, ${s.sentiment}${s.title ? ` (${s.title})` : ""}`);
+        for (const evidence of s.evidence.slice(0, 3))
+            lines.push(`  - evidence: ${evidence}`);
+    }
+    if (map.openDeals.length) {
+        lines.push("", "## Open deals");
+        for (const deal of map.openDeals)
+            lines.push(`- ${deal.name} (${deal.dealId})${deal.stage ? ` — ${deal.stage}` : ""}${deal.amount !== undefined ? ` — ${deal.amount}` : ""}`);
+    }
+    if (map.gaps.length) {
+        lines.push("", "## Gaps");
+        for (const gap of map.gaps)
+            lines.push(`- ${gap}`);
+    }
+    return lines.join("\n");
+}

package/dist/route.d.ts

@@ -0,0 +1,46 @@
+import { type AssignmentPolicy } from "./assign.ts";
+import type { CanonicalGtmSnapshot, 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;
+};
+export declare function buildLeadRoutePlan(snapshot: CanonicalGtmSnapshot, options?: LeadRouteOptions): LeadRouteResult;

package/dist/route.js

@@ -0,0 +1,228 @@
+import { resolveAssignment } from "./assign.js";
+import { FREE_EMAIL_DOMAINS } from "./freeEmailDomains.js";
+import { normalizeDomain } from "./merge.js";
+import { stableHash } from "./rules.js";
+function norm(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const out = String(value).trim().toLowerCase();
+    return out || undefined;
+}
+function contactEmailDomain(contact) {
+    const email = norm(contact.email);
+    if (!email || !email.includes("@"))
+        return undefined;
+    return normalizeDomain(email.slice(email.lastIndexOf("@") + 1));
+}
+function rawString(record, keys) {
+    if (!record.raw || typeof record.raw !== "object")
+        return undefined;
+    const raw = record.raw;
+    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;
+            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) {
+    return rawString(contact, ["company", "companyName", "company_name", "account", "accountName", "account_name"]);
+}
+function uniqueAccount(matches) {
+    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) {
+    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, account) {
+    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) {
+    const ids = new Set();
+    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, options = {}) {
+    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();
+    const accountsByName = new Map();
+    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 = [];
+    const counts = {
+        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 = currentAccount;
+        let matchRule = 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 = [];
+        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 = null;
+        let ownerRule;
+        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 = {
+        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/dist/rules.d.ts

@@ -34,4 +34,5 @@ export declare const duplicateOpenDealRule: GtmAuditRule;
 export declare const activeDealAccountWithoutContactsRule: GtmAuditRule;
 export declare const closingSoonInactiveRule: GtmAuditRule;
 export declare const accountSingleSourceRule: GtmAuditRule;
+export declare function isFindingsOnlyRule(rule: GtmAuditRule): boolean;
 export declare const builtinAuditRules: GtmAuditRule[];