fullstackgtm 0.42.0 → 0.44.0

package/src/connectors/hubspot.ts

@@ -506,18 +506,34 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     };
   }
 
-  /** Exact-name company lookup for resolve-first creates. Returns matching ids (max 3 fetched). */
-  async function searchCompaniesByName(name: string): Promise<string[]> {
+  /** Exact-value company lookup (by `name` or `domain`) for resolve-first creates. */
+  async function searchCompaniesBy(property: string, value: string): Promise<string[]> {
     const data = await request(`/crm/v3/objects/companies/search`, {
       method: "POST",
       body: JSON.stringify({
-        filterGroups: [{ filters: [{ propertyName: "name", operator: "EQ", value: name }] }],
-        properties: ["name"],
+        filterGroups: [{ filters: [{ propertyName: property, operator: "EQ", value }] }],
+        properties: [property],
         limit: 3,
       }),
     });
     return ((data?.results ?? []) as Array<{ id: string }>).map((row) => String(row.id));
   }
+  const searchCompaniesByName = (name: string) => searchCompaniesBy("name", name);
+
+  /** Stamp `domain` on a company only when it has none (fill-blank, never clobber). */
+  async function fillCompanyDomainIfEmpty(companyId: string, domain: string): Promise<void> {
+    try {
+      const data = await request(`/crm/v3/objects/companies/${encodeURIComponent(companyId)}?properties=domain`);
+      const current = data?.properties?.domain;
+      if (typeof current === "string" && current.trim()) return; // already has one — leave it
+      await request(`/crm/v3/objects/companies/${encodeURIComponent(companyId)}`, {
+        method: "PATCH",
+        body: JSON.stringify({ properties: { domain } }),
+      });
+    } catch {
+      // Best-effort: a failed domain fill must not sink the contact create.
+    }
+  }
 
   /** Exact-value contact lookup (by any searchable property) for resolve-first creates. */
   async function searchContactsBy(property: string, value: string): Promise<string[]> {
@@ -533,36 +549,51 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   }
 
   /**
-   * Resolve a company by exact name, creating it on a confirmed miss. Returns
-   * the company id, or null on ambiguity (≥2 existing) so the caller skips the
-   * association rather than guessing. Same-run safe via createdCompaniesByName.
+   * Resolve a company to a real account record, creating it on a confirmed miss.
+   * Matches by DOMAIN first (the accurate key) and falls back to exact name;
+   * creates with the domain stamped, and fills the domain on a name-matched
+   * account that lacks one — so the account is signal-watchable. Returns null on
+   * ambiguity (≥2 matches) so the caller skips the association rather than
+   * guessing. Same-run safe via createdCompaniesByName.
    */
-  async function resolveOrCreateCompanyByName(name: string, opId: string): Promise<string | null> {
-    const nameKey = name.toLowerCase();
-    const already = createdCompaniesByName.get(nameKey);
+  async function resolveOrCreateCompany(name: string, domain: string | undefined, opId: string): Promise<string | null> {
+    const cacheKey = domain ? `d:${domain.toLowerCase()}` : `n:${name.toLowerCase()}`;
+    const already = createdCompaniesByName.get(cacheKey);
     if (already) return already;
-    const matches = await searchCompaniesByName(name);
-    if (matches.length > 1) return null;
-    if (matches.length === 1) {
-      createdCompaniesByName.set(nameKey, matches[0]);
-      return matches[0];
+
+    // 1. Domain-first match (accurate; an account matched here already has it).
+    if (domain) {
+      const byDomain = await searchCompaniesBy("domain", domain);
+      if (byDomain.length > 1) return null;
+      if (byDomain.length === 1) {
+        createdCompaniesByName.set(cacheKey, byDomain[0]);
+        return byDomain[0];
+      }
     }
+    // 2. Exact-name match; stamp the domain if the account has none.
+    const byName = await searchCompaniesByName(name);
+    if (byName.length > 1) return null;
+    if (byName.length === 1) {
+      if (domain) await fillCompanyDomainIfEmpty(byName[0], domain);
+      createdCompaniesByName.set(cacheKey, byName[0]);
+      return byName[0];
+    }
+    // 3. Create with name + domain (provenance is best-effort).
+    const props: Record<string, string> = { name, ...(domain ? { domain } : {}) };
     let created;
     try {
       created = await request(`/crm/v3/objects/companies`, {
         method: "POST",
-        body: JSON.stringify({
-          properties: { name, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` },
-        }),
+        body: JSON.stringify({ properties: { ...props, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` } }),
       });
     } catch {
       created = await request(`/crm/v3/objects/companies`, {
         method: "POST",
-        body: JSON.stringify({ properties: { name } }),
+        body: JSON.stringify({ properties: props }),
       });
     }
     const id = String(created.id);
-    createdCompaniesByName.set(nameKey, id);
+    createdCompaniesByName.set(cacheKey, id);
     return id;
   }
 
@@ -588,7 +619,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     }
 
     if (operation.objectType === "account") {
-      const id = await resolveOrCreateCompanyByName(matchValue, operation.id);
+      const id = await resolveOrCreateCompany(matchValue, stringOrUndefined(payload.properties?.domain), operation.id);
       if (id === null) {
         return { operationId: operation.id, status: "skipped", detail: `create_record: ambiguous — multiple companies named "${matchValue}". Not creating.` };
       }
@@ -637,13 +668,14 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     let companyNote = "";
     if (payload.associateCompanyName) {
       try {
-        const companyId = await resolveOrCreateCompanyByName(payload.associateCompanyName, operation.id);
+        const companyId = await resolveOrCreateCompany(payload.associateCompanyName, payload.associateCompanyDomain, operation.id);
         if (companyId) {
           await request(
             `/crm/v4/objects/contacts/${encodeURIComponent(contactId)}/associations/default/companies/${encodeURIComponent(companyId)}`,
             { method: "PUT" },
           );
-          companyNote = ` Linked to company "${payload.associateCompanyName}" (${companyId}).`;
+          const domainNote = payload.associateCompanyDomain ? ` (${payload.associateCompanyDomain})` : "";
+          companyNote = ` Linked to company "${payload.associateCompanyName}"${domainNote} (${companyId}).`;
         } else {
           companyNote = ` Company "${payload.associateCompanyName}" was ambiguous; left unlinked.`;
         }

package/src/connectors/outboxChannel.ts

@@ -0,0 +1,202 @@
+/**
+ * Outbox channel connector — the governed SEND-side terminus of the outbound
+ * loop (signal → judge → draft → approve → apply → outbox), and the mirror image
+ * of the webhook spool. It is a `GtmConnector` whose `applyOperation` RENDERS an
+ * approved drafted opener to a local outbox artifact instead of writing a CRM —
+ * so it reuses the entire governed apply machinery (approval set, integrity/HMAC
+ * verification, idempotency, run recording) with no change to the apply engine.
+ *
+ * THE INVARIANT IT KEEPS: the CLI **transmits nothing**. Rendering an approved
+ * opener to `<home>/signals/outbox/<channel>.jsonl` is a local file write, never
+ * an SMTP/API connection. A downstream sender (the hosted product, or the
+ * operator's own MTA) drains the outbox and does the actual transmission. This
+ * is the send-side half of the open-core boundary: the governed artifact + its
+ * format are open; always-on transmission infrastructure is hosted/opt-in.
+ *
+ * Governance: it only renders ops that came from `draft` (a `create_task` op
+ * whose policy is `draft:<channel>`); any other op is `skipped` (it is not a
+ * general CRM writer). Idempotent on the operation id — re-applying an approved
+ * plan never duplicates an outbox row. Read paths (`fetchSnapshot`) intentionally
+ * throw: a channel has no snapshot, and `applyPatchPlan` never calls it for a
+ * draft plan (no guards/filter/irreversible ops → no snapshot needed).
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureSecureHomeDir, writeSecureFile } from "../credentials.ts";
+import { signalsOutboxDir } from "../signals.ts";
+import type { CanonicalGtmSnapshot, GtmConnector, PatchOperation, PatchOperationResult } from "../types.ts";
+
+/** One approved, ready-to-send touch — a governed send INTENT, not a sent message. */
+export type OutboxEntry = {
+  /** Idempotency key = the source operation id (stable per draft op). */
+  id: string;
+  /** email | linkedin | task — from the draft op's `draft:<channel>` policy. */
+  channel: string;
+  /** The CRM target the opener is addressed to (a sender resolves id → address). */
+  objectType: string;
+  objectId: string;
+  /** The APPROVED opener, verbatim as it was signed in the plan op. */
+  body: string;
+  /** The draft op's human-readable reason (carries the account + trigger). */
+  reason?: string;
+  /** Evidence ids the opener was grounded in (the verbatim signal quote). */
+  evidenceIds: string[];
+  /** ISO 8601 — when the CLI rendered this to the outbox (NOT a send time). */
+  renderedAt: string;
+};
+
+/** Channel ids this build can render to. */
+export const CHANNELS = ["outbox"] as const;
+
+export type OutboxChannelOptions = {
+  /** Outbox directory; defaults to the profile-scoped `signalsOutboxDir()`. */
+  outboxDir?: string;
+  /** Injectable clock for deterministic tests. */
+  now?: () => Date;
+};
+
+const DRAFT_POLICY_PREFIX = "draft:";
+
+/**
+ * Build the outbox channel connector. With no `outboxDir`, writes to the
+ * profile-scoped conventional outbox and locks the home down (0700/0600) like
+ * the signal store; with an explicit `outboxDir` (tests), it writes there
+ * without touching the real home.
+ */
+export function createOutboxChannelConnector(options: OutboxChannelOptions = {}): GtmConnector {
+  const usingDefaultHome = options.outboxDir === undefined;
+  const dir = options.outboxDir ?? signalsOutboxDir();
+  const now = options.now ?? (() => new Date());
+
+  function fileFor(channel: string): string {
+    if (!/^[\w.-]+$/.test(channel)) throw new Error(`Invalid outbox channel name: ${channel}`);
+    return join(dir, `${channel}.jsonl`);
+  }
+
+  /** Existing entry ids in a channel file (for idempotent re-apply). */
+  function existingIds(channel: string): Set<string> {
+    const ids = new Set<string>();
+    let raw: string;
+    try {
+      raw = readFileSync(fileFor(channel), "utf8");
+    } catch {
+      return ids; // no file yet
+    }
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const id = (JSON.parse(t) as { id?: unknown }).id;
+        if (typeof id === "string") ids.add(id);
+      } catch {
+        // Skip a corrupt line rather than fail the whole apply.
+      }
+    }
+    return ids;
+  }
+
+  function append(channel: string, entry: OutboxEntry): void {
+    if (usingDefaultHome) ensureSecureHomeDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = fileFor(channel);
+    // Owner-only like the signal store: outbox carries opener text + CRM ids.
+    if (!existsSync(path)) writeSecureFile(path, "");
+    appendFileSync(path, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+  }
+
+  async function applyOperation(operation: PatchOperation): Promise<PatchOperationResult> {
+    const policy = String(operation.sourceRuleOrPolicy ?? "");
+    if (operation.operation !== "create_task" || !policy.startsWith(DRAFT_POLICY_PREFIX)) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail:
+          "The outbox channel only renders drafted openers (create_task ops from `draft`). " +
+          "Apply other operations through a CRM connector (--provider hubspot|salesforce).",
+      };
+    }
+    const channel = policy.slice(DRAFT_POLICY_PREFIX.length) || "task";
+
+    // Idempotent: a re-applied approved plan must not duplicate the row.
+    if (existingIds(channel).has(operation.id)) {
+      return {
+        operationId: operation.id,
+        status: "applied",
+        detail: `Already in outbox (${channel}.jsonl); idempotent — not duplicated. Nothing transmitted.`,
+      };
+    }
+
+    const entry: OutboxEntry = {
+      id: operation.id,
+      channel,
+      objectType: operation.objectType,
+      objectId: operation.objectId,
+      body: typeof operation.afterValue === "string" ? operation.afterValue : String(operation.afterValue ?? ""),
+      ...(operation.reason ? { reason: operation.reason } : {}),
+      evidenceIds: operation.evidenceIds ?? [],
+      renderedAt: now().toISOString(),
+    };
+    append(channel, entry);
+    return {
+      operationId: operation.id,
+      status: "applied",
+      detail: `Rendered to outbox (${channel}.jsonl) for a downstream sender. Nothing was transmitted.`,
+    };
+  }
+
+  async function fetchSnapshot(): Promise<CanonicalGtmSnapshot> {
+    // A channel has no readable state. apply never calls this for a draft plan
+    // (no guards/filter/irreversible ops); make the misuse explicit if it does.
+    throw new Error(
+      "The outbox channel has no snapshot to read — it is a send-side render target. " +
+        "Use it only to `apply` an approved draft plan (`apply --plan-id <id> --channel outbox`).",
+    );
+  }
+
+  return {
+    provider: "outbox",
+    fetchSnapshot,
+    applyOperation,
+  };
+}
+
+/** Resolve a channel connector by id (mirrors the source-connector registry). */
+export function createChannelConnector(id: string, options: OutboxChannelOptions = {}): GtmConnector {
+  if (id === "outbox") return createOutboxChannelConnector(options);
+  throw new Error(`Unknown channel: ${id} (one of: ${CHANNELS.join(", ")}).`);
+}
+
+/**
+ * Read every outbox entry across all channel files in `dir` (default: the
+ * conventional outbox), newest-appended last. The reader a downstream sender (or
+ * a future `signals outbox` command) uses to drain the queue.
+ */
+export function listOutbox(dir?: string): OutboxEntry[] {
+  const outboxDir = dir ?? signalsOutboxDir();
+  let names: string[];
+  try {
+    names = readdirSync(outboxDir).filter((name) => name.endsWith(".jsonl")).sort();
+  } catch {
+    return [];
+  }
+  const out: OutboxEntry[] = [];
+  for (const name of names) {
+    let raw: string;
+    try {
+      raw = readFileSync(join(outboxDir, name), "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        out.push(JSON.parse(t) as OutboxEntry);
+      } catch {
+        // Skip corrupt lines.
+      }
+    }
+  }
+  return out;
+}

package/src/connectors/prospectSources.ts

@@ -166,6 +166,63 @@ function strField(field: { value?: unknown } | undefined): string | undefined {
   return typeof v === "string" && v.trim() ? v : undefined;
 }
 
+// ---------------------------------------------------------------------------
+// TAM universe count — "how many ACCOUNTS match this ICP firmographic?"
+//
+// Verified empirically (2026-06-25) against the live providers, because the
+// obvious endpoints lie about totals:
+//   - Explorium /v1/prospects `total_results` == the PAGE size (1→1, 10→10), not
+//     the universe — useless for sizing. So is /v1/businesses for tiny pages? No:
+//   - Explorium /v1/businesses `total_results` IS a real COUNT of matching
+//     companies (US+10000-emp → 9,754; Liechtenstein+10000 → 11), capped at
+//     EXPLORIUM_BUSINESS_COUNT_CAP. At/above the cap it saturates at exactly that
+//     number, so the caller must treat a capped reading as a FLOOR, not a count.
+//   - pipe0/Crustdata people search returns only a pagination cursor, NO total —
+//     it cannot size a universe at all (callers use it for discovery, not counting).
+// So the TAM count source is Explorium /v1/businesses (a company/account count).
+
+export const EXPLORIUM_BUSINESS_COUNT_CAP = 60_000;
+
+export type BusinessCountProbe = {
+  /** matching companies (the account universe); == cap when saturated. */
+  total: number;
+  /** true when total hit EXPLORIUM_BUSINESS_COUNT_CAP — treat total as a lower bound. */
+  capped: boolean;
+};
+
+/**
+ * Count the COMPANIES (accounts) matching an ICP firmographic via Explorium
+ * /v1/businesses. Returns the real total (capped at 60k — `capped` flags the
+ * ceiling) or null if the response carries no `total_results`. Use
+ * `icpToExploriumBusinessFilters` to build `filters` (firmographic field names
+ * differ from /v1/prospects).
+ */
+export async function probeExploriumBusinessCount(opts: {
+  apiKey: string;
+  filters: Record<string, { values?: string[] }>;
+  apiBaseUrl?: string;
+  fetchImpl?: FetchImpl;
+}): Promise<BusinessCountProbe | null> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = (opts.apiBaseUrl ?? "https://api.explorium.ai").replace(/\/$/, "");
+  const response = await fetchImpl(`${base}/v1/businesses`, {
+    method: "POST",
+    headers: { "api_key": opts.apiKey, "Content-Type": "application/json" },
+    // page_size 1: we want the envelope's total_results, not the rows. CRITICAL:
+    // do NOT send `size` — Explorium caps total_results to `size` when present
+    // (verified: size:1 → total_results:1; omitted → the real count, e.g. 19,058).
+    body: JSON.stringify({ mode: "full", page_size: 1, page: 1, filters: opts.filters }),
+  });
+  if (!response.ok) {
+    throw new Error(`Explorium /v1/businesses count failed: HTTP ${response.status} ${await safeText(response)}`);
+  }
+  const body = (await response.json()) as { total_results?: unknown };
+  const total = body.total_results;
+  if (typeof total !== "number" || !Number.isFinite(total) || total < 0) return null;
+  const rounded = Math.round(total);
+  return { total: rounded, capped: rounded >= EXPLORIUM_BUSINESS_COUNT_CAP };
+}
+
 function normalizeLinkedin(value: string | undefined): string | undefined {
   if (!value) return undefined;
   const v = value.trim().replace(/^https?:\/\//i, "").replace(/\/$/, "");

package/src/connectors/salesforce.ts

@@ -80,28 +80,52 @@ export function createSalesforceConnector(
   // confirmed miss is created, and an ambiguous name (>1 match) is refused.
   // Caches within the run so the same name is never created twice — shared by
   // `link_record`'s create:<Name> path and `create_record`'s company linking.
-  async function resolveOrCreateAccountByName(
+  async function resolveOrCreateAccount(
     name: string,
+    domain?: string,
   ): Promise<{ id: string; createdNew: boolean } | { ambiguous: number }> {
-    const nameKey = name.toLowerCase();
-    const cached = createdAccountsByName.get(nameKey);
+    const cacheKey = domain ? `d:${domain.toLowerCase()}` : `n:${name.toLowerCase()}`;
+    const cached = createdAccountsByName.get(cacheKey);
     if (cached) return { id: cached, createdNew: false };
-    const soqlName = name.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-    const matches = await query(`SELECT Id FROM Account WHERE Name = '${soqlName}' LIMIT 3`);
-    if (matches.length > 1) return { ambiguous: matches.length };
+    const esc = (v: string) => v.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+
+    // 1. Domain-first match on Website (the accurate key; Website often stores a
+    //    full URL, so match by substring).
+    if (domain) {
+      const byDomain = await query(`SELECT Id FROM Account WHERE Website LIKE '%${esc(domain)}%' LIMIT 3`);
+      if (byDomain.length > 1) return { ambiguous: byDomain.length };
+      if (byDomain.length === 1) {
+        const id = String(byDomain[0].Id);
+        createdAccountsByName.set(cacheKey, id);
+        return { id, createdNew: false };
+      }
+    }
+    // 2. Exact-name match; stamp Website if the account has none (fill-blank).
+    const byName = await query(`SELECT Id, Website FROM Account WHERE Name = '${esc(name)}' LIMIT 3`);
+    if (byName.length > 1) return { ambiguous: byName.length };
     let id: string;
     let createdNew = false;
-    if (matches.length === 1) {
-      id = String(matches[0].Id);
+    if (byName.length === 1) {
+      id = String(byName[0].Id);
+      if (domain && !stringOrUndefined(byName[0].Website)) {
+        try {
+          await request(`/services/data/${apiVersion}/sobjects/Account/${encodeURIComponent(id)}`, {
+            method: "PATCH",
+            body: JSON.stringify({ Website: domain }),
+          });
+        } catch {
+          // best-effort fill — a failed Website stamp must not sink the create.
+        }
+      }
     } else {
       const created = await request(`/services/data/${apiVersion}/sobjects/Account`, {
         method: "POST",
-        body: JSON.stringify({ Name: name }),
+        body: JSON.stringify({ Name: name, ...(domain ? { Website: domain } : {}) }),
       });
       id = String(created.id);
       createdNew = true;
     }
-    createdAccountsByName.set(nameKey, id);
+    createdAccountsByName.set(cacheKey, id);
     return { id, createdNew };
   }
 
@@ -534,7 +558,7 @@ export function createSalesforceConnector(
     }
 
     if (operation.objectType === "account") {
-      const resolved = await resolveOrCreateAccountByName(matchValue);
+      const resolved = await resolveOrCreateAccount(matchValue);
       if ("ambiguous" in resolved) {
         return { operationId: operation.id, status: "skipped", detail: `create_record: ambiguous — ${resolved.ambiguous} accounts named "${matchValue}". Not creating.` };
       }
@@ -574,7 +598,7 @@ export function createSalesforceConnector(
     let companyNote = "";
     if (payload.associateCompanyName) {
       try {
-        const resolved = await resolveOrCreateAccountByName(payload.associateCompanyName);
+        const resolved = await resolveOrCreateAccount(payload.associateCompanyName, payload.associateCompanyDomain);
         if ("ambiguous" in resolved) {
           companyNote = ` Account "${payload.associateCompanyName}" was ambiguous; left unlinked.`;
         } else {
@@ -582,7 +606,8 @@ export function createSalesforceConnector(
             method: "PATCH",
             body: JSON.stringify({ AccountId: resolved.id }),
           });
-          companyNote = ` Linked to account "${payload.associateCompanyName}" (${resolved.id}).`;
+          const domainNote = payload.associateCompanyDomain ? ` (${payload.associateCompanyDomain})` : "";
+          companyNote = ` Linked to account "${payload.associateCompanyName}"${domainNote} (${resolved.id}).`;
         }
       } catch (error) {
         // Association is best-effort — the contact create already succeeded.
@@ -726,7 +751,7 @@ export function createSalesforceConnector(
             if (!name) {
               return { operationId: operation.id, status: "skipped", detail: "create: needs an account name (create:<Name>)." };
             }
-            const resolved = await resolveOrCreateAccountByName(name);
+            const resolved = await resolveOrCreateAccount(name);
             if ("ambiguous" in resolved) {
               return {
                 operationId: operation.id,