fullstackgtm 0.43.0 → 0.45.0

package/dist/connectors/signalSources.js

@@ -0,0 +1,264 @@
+/**
+ * Source connectors for the `signals` layer — the connection-based intake that
+ * generalizes the no-auth ATS adapters (`atsBoards.ts`) and the hand-staged
+ * `--from <file.json>` path into one contract: a platform connection in, a list
+ * of evidence-bearing staged signal rows out.
+ *
+ * Design (see docs/spec-connectors-signals-outbound.md):
+ *   - Zero runtime deps: global `fetch` only, injectable for tests.
+ *   - Read-only: a source never writes a CRM record and never emits a
+ *     PatchOperation. `signals fetch` stays read-only re: the CRM.
+ *   - Verbatim evidence: every row carries a non-empty `quote`; a row that
+ *     cannot ground a why-now is dropped, never faked. The central
+ *     `stagedRowToSignal` gate enforces this again.
+ *   - Secrets via the credential ladder: API keys come from
+ *     `ctx.getApiKey(provider)` (login store -> env -> broker), NEVER from argv.
+ *     `ctx.options` carries non-secret knobs only (a file path, a query term).
+ *   - Per-source resilience: a connector's own failure yields `[]` (logged by
+ *     the caller), it must never sink a multi-source run — the per-provider
+ *     try/catch idiom of atsBoards/prospectSources.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { SIGNAL_BUCKETS } from "../signals.js";
+import { parseSpoolText, spoolFilesIn } from "../spoolFiles.js";
+// ---------------------------------------------------------------------------
+// file — local JSON / JSONL intake (also the webhook landing-zone reader)
+/**
+ * Read staged rows from a local path — the webhook landing-zone reader. The path
+ * (from `options.path`/`options.file`) may be:
+ *   - a single FILE: a JSON array, or newline-delimited JSON (one row per line);
+ *   - a DIRECTORY (the conventional spool): every `*.jsonl` / `*.json` file in
+ *     it is read and concatenated (sorted by name), so multiple receivers can
+ *     each append their own file (`rb2b.jsonl`, `hubspot.jsonl`) and they all
+ *     land in one fetch.
+ * No auth. This is how every push platform (RB2B, Trigify, HubSpot webhooks)
+ * reaches the CLI: a receiver appends a row to the spool, this reads it on the
+ * next `signals fetch`. The CLI defaults the path to the conventional spool dir
+ * (`signalsSpoolDir`) when `--connector file` is used with no path; a bare
+ * library call with no path is inactive (returns []).
+ *
+ * Resilient: a missing path / unreadable file yields [] (an empty source, not a
+ * crash), and one unreadable file in a spool directory is skipped. A file that
+ * IS present but malformed throws — a corrupt spool is a real error to surface,
+ * not silent data loss. The central `stagedRowToSignal` gate validates rows.
+ */
+export const fileSource = {
+    id: "file",
+    bucket: "company",
+    shape: "pull",
+    auth: "none",
+    async fetch(ctx) {
+        const path = ctx.options?.path ?? ctx.options?.file;
+        if (!path)
+            return []; // no spool configured (the CLI fills the default dir)
+        const abs = resolve(process.cwd(), path);
+        let isDir;
+        try {
+            isDir = statSync(abs).isDirectory();
+        }
+        catch {
+            return []; // missing path: an empty source, not a crash
+        }
+        // Container parsing lives in the shared spool reader (src/spoolFiles.ts) so
+        // `signals fetch --from`, `enrich ingest`, and `market observe --from` read
+        // the same convention; the "file source" label keeps error text unchanged.
+        const files = isDir ? spoolFilesIn(abs) : [abs];
+        const rows = [];
+        for (const file of files) {
+            let raw;
+            try {
+                raw = readFileSync(file, "utf8");
+            }
+            catch {
+                continue; // one unreadable file in a spool dir must not sink the rest
+            }
+            rows.push(...parseSpoolText(raw, file, "file source"));
+        }
+        return rows.map((row) => coerceRow(row, this.bucket));
+    },
+};
+// ---------------------------------------------------------------------------
+// serpapi-news — funding/company signals from a news REST query (API key)
+const SERPAPI_BASE_URL = "https://serpapi.com";
+/**
+ * Pull recent news per watchlist account and stage funding/company signals. One
+ * query per account (`q="<domain>"`, Google News engine); each result becomes a
+ * row whose verbatim `quote` is the headline (+ source), so the downstream judge
+ * can ground a why-now on a real, linkable article. API key via the credential
+ * ladder (provider "serpapi"); no key -> [] (the source is simply inactive).
+ *
+ * Bucket defaults to `funding`; override per run with `--connector-opt bucket=company`.
+ */
+export const serpapiNewsSource = {
+    id: "serpapi-news",
+    bucket: "funding",
+    shape: "pull",
+    auth: "api_key",
+    async fetch(ctx) {
+        const apiKey = ctx.getApiKey ? await ctx.getApiKey("serpapi") : null;
+        if (!apiKey)
+            return [];
+        const fetchImpl = ctx.fetchImpl ?? fetch;
+        const base = (ctx.options?.apiBaseUrl ?? SERPAPI_BASE_URL).replace(/\/$/, "");
+        const bucket = pickBucket(ctx.options?.bucket, this.bucket);
+        const out = [];
+        for (const account of ctx.watchlist) {
+            const domain = account.domain.trim();
+            if (!domain)
+                continue;
+            try {
+                const url = `${base}/search.json?engine=google_news&q=${encodeURIComponent(`"${domain}"`)}` +
+                    `&api_key=${encodeURIComponent(apiKey)}`;
+                const response = await fetchImpl(url, { headers: { Accept: "application/json" } });
+                if (!response.ok)
+                    continue;
+                const data = (await response.json());
+                for (const item of data.news_results ?? []) {
+                    const title = typeof item.title === "string" ? item.title.trim() : "";
+                    if (!title)
+                        continue; // no headline -> no verbatim evidence -> drop
+                    const sourceName = typeof item.source === "string" ? item.source : item.source?.name ?? "";
+                    const quote = sourceName ? `${title} — ${sourceName}` : title;
+                    out.push({
+                        bucket,
+                        accountDomain: domain,
+                        trigger: `news: ${title}`,
+                        quote,
+                        sourceUrl: typeof item.link === "string" ? item.link : "",
+                    });
+                }
+            }
+            catch {
+                continue; // one account's outage must not sink the run
+            }
+        }
+        return out;
+    },
+};
+// ---------------------------------------------------------------------------
+// hubspot-forms — first-party demand from recent HubSpot form submissions
+const HUBSPOT_BASE_URL = "https://api.hubapi.com";
+/**
+ * Stage `demand` signals from recent HubSpot form submissions — the first real
+ * `demand`-bucket producer (a form fill is first-party demand). Reuses the
+ * EXISTING HubSpot credential via the ladder (provider "hubspot"); no separate
+ * login. Each submission whose email carries a company domain becomes a row
+ * whose verbatim `quote` is the form name + submitted email (the evidence a rep
+ * can verify). Submissions without a corporate domain (free-mail) are dropped —
+ * no account to attach demand to.
+ *
+ * Phase 1 is a pull over the Forms submissions API; the form-submission webhook
+ * (push) lands in Phase 2 via the spool + `file` source.
+ */
+export const hubspotFormsSource = {
+    id: "hubspot-forms",
+    bucket: "demand",
+    shape: "pull",
+    auth: "oauth",
+    async fetch(ctx) {
+        const token = ctx.getApiKey ? await ctx.getApiKey("hubspot") : null;
+        if (!token)
+            return [];
+        const fetchImpl = ctx.fetchImpl ?? fetch;
+        const base = (ctx.options?.apiBaseUrl ?? HUBSPOT_BASE_URL).replace(/\/$/, "");
+        const out = [];
+        let forms = [];
+        try {
+            const response = await fetchImpl(`${base}/marketing/v3/forms`, {
+                headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+            });
+            if (!response.ok)
+                return [];
+            const data = (await response.json());
+            forms = data.results ?? [];
+        }
+        catch {
+            return [];
+        }
+        for (const form of forms) {
+            const formId = form.guid ?? form.id;
+            if (!formId)
+                continue;
+            const formName = typeof form.name === "string" && form.name ? form.name : "form";
+            try {
+                const response = await fetchImpl(`${base}/form-integrations/v1/submissions/forms/${encodeURIComponent(formId)}?limit=50`, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" } });
+                if (!response.ok)
+                    continue;
+                const data = (await response.json());
+                for (const submission of data.results ?? []) {
+                    const email = fieldValue(submission.values, "email");
+                    const domain = corporateDomain(email);
+                    if (!domain)
+                        continue; // free-mail / no email: no account to attach to
+                    const submittedAt = typeof submission.submittedAt === "number"
+                        ? new Date(submission.submittedAt).toISOString()
+                        : undefined;
+                    out.push({
+                        bucket: "demand",
+                        accountDomain: domain,
+                        trigger: `form: ${formName}`,
+                        quote: `Submitted "${formName}" — ${email}`,
+                        sourceUrl: "",
+                        ...(submittedAt ? { firstSeen: submittedAt } : {}),
+                    });
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return out;
+    },
+};
+// ---------------------------------------------------------------------------
+// Registry
+const CONNECTORS = [fileSource, serpapiNewsSource, hubspotFormsSource];
+const REGISTRY = new Map(CONNECTORS.map((c) => [c.id, c]));
+/** All registered source connectors (stable order). */
+export function listSignalSources() {
+    return [...CONNECTORS];
+}
+/** Resolve a connector by id, or null when unknown. */
+export function getSignalSource(id) {
+    return REGISTRY.get(id) ?? null;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+function coerceRow(row, defaultBucket) {
+    // Fill the bucket from the connector default when a file row omits it; the
+    // central validator still rejects an unknown bucket and an empty quote.
+    const bucket = row.bucket === undefined ? defaultBucket : row.bucket;
+    return { ...row, bucket };
+}
+function pickBucket(raw, fallback) {
+    if (raw && SIGNAL_BUCKETS.includes(raw))
+        return raw;
+    return fallback;
+}
+function fieldValue(values, name) {
+    for (const field of values ?? []) {
+        if (field.name === name && typeof field.value === "string")
+            return field.value.trim();
+    }
+    return "";
+}
+const FREE_MAIL = new Set([
+    "gmail.com",
+    "yahoo.com",
+    "hotmail.com",
+    "outlook.com",
+    "icloud.com",
+    "aol.com",
+    "proton.me",
+    "protonmail.com",
+]);
+/** Company domain from an email, or "" for free-mail / no email. */
+function corporateDomain(email) {
+    if (!email.includes("@"))
+        return "";
+    const domain = email.split("@").at(-1).trim().toLowerCase();
+    if (!domain || FREE_MAIL.has(domain))
+        return "";
+    return domain;
+}

package/dist/connectors/theirstack.d.ts

@@ -0,0 +1,84 @@
+/**
+ * TheirStack — technographic company discovery.
+ *
+ * Explorium can only size a firmographic universe (NAICS/size/geo) and can't even
+ * return the list. For a CRM-hygiene/RevOps tool the real buying signal is
+ * "company runs a CRM", and the deliverable is an actual list of those companies.
+ * TheirStack does both: filter companies by the technology they use (Salesforce,
+ * HubSpot, Pipedrive, …) plus firmographics, and return real records (name,
+ * domain, employee_count, …). A cheap count sizes the market; a paged search
+ * materializes the list. Both cost ~3 credits per company RETURNED — counting
+ * still returns 1 row (the API rejects limit:0), so a count is ~3 credits, not
+ * free; a list pull is ~3 × the rows.
+ *
+ * API: POST https://api.theirstack.com/v1/companies/search, Bearer auth.
+ * Verified live (2026-06-29): filters company_technology_slug_or /
+ * company_country_code_or / min_employee_count / max_employee_count; the total is
+ * `metadata.total_results` with include_total_results:true; limit must be ≥ 1
+ * (limit:0 → 422, the count gotcha — cf. Explorium's `size`-caps-the-total).
+ */
+type FetchImpl = typeof fetch;
+/** TheirStack charges per company RETURNED — verified live (a list pull of N
+ *  companies spends 3N). The count (limit:1) returns 1 row, so it's ~3 credits. */
+export declare const THEIRSTACK_CREDITS_PER_COMPANY = 3;
+export type TheirStackCost = {
+    companies: number;
+    credits: number;
+    /** USD estimate — present ONLY when a per-credit rate is supplied (no
+     *  fabricated default; TheirStack pricing varies ~$0.04–$0.11/credit by tier). */
+    usd?: number;
+};
+/** Deterministic cost of pulling `companies` records (the credits are the hard
+ *  fact; the dollar figure needs an explicit rate). */
+export declare function theirStackPullCost(companies: number, usdPerCredit?: number): TheirStackCost;
+/** Firmographic + technographic filter for TheirStack company search. */
+export type TheirStackFilters = {
+    /** technology slugs, OR-matched — e.g. ["salesforce","hubspot","pipedrive"]. */
+    company_technology_slug_or?: string[];
+    min_employee_count?: number;
+    max_employee_count?: number;
+    /** ISO2 country codes, OR-matched — e.g. ["US"]. */
+    company_country_code_or?: string[];
+};
+/** A real company record from TheirStack (the materialized list element). */
+export type TheirStackCompany = {
+    name?: string;
+    domain?: string;
+    employeeCount?: number;
+    countryCode?: string;
+    city?: string;
+    linkedinUrl?: string;
+    /** the matched technology slugs that put this company in the list. */
+    technologies?: string[];
+};
+/** Read the total-match count from the response envelope (field name varies). */
+export declare function readTheirStackTotal(body: unknown): number | null;
+/**
+ * Count companies matching the technographic + firmographic filter — the real
+ * TAM size. Uses `limit: 1` (the API rejects `limit: 0` with a 422 — verified
+ * live) + `include_total_results`, and reads `metadata.total_results`. Costs the
+ * 1 returned company's credits; the total itself is the point.
+ * Returns null if the envelope carries no total.
+ */
+export declare function theirStackCountCompanies(opts: {
+    apiKey: string;
+    filters: TheirStackFilters;
+    apiBaseUrl?: string;
+    fetchImpl?: FetchImpl;
+}): Promise<number | null>;
+/**
+ * Pull a page of real companies matching the filter — the materialized list.
+ * Returns the records plus the total (when the envelope reports it).
+ */
+export declare function theirStackSearchCompanies(opts: {
+    apiKey: string;
+    filters: TheirStackFilters;
+    limit?: number;
+    page?: number;
+    apiBaseUrl?: string;
+    fetchImpl?: FetchImpl;
+}): Promise<{
+    companies: TheirStackCompany[];
+    total: number | null;
+}>;
+export {};

package/dist/connectors/theirstack.js

@@ -0,0 +1,125 @@
+/**
+ * TheirStack — technographic company discovery.
+ *
+ * Explorium can only size a firmographic universe (NAICS/size/geo) and can't even
+ * return the list. For a CRM-hygiene/RevOps tool the real buying signal is
+ * "company runs a CRM", and the deliverable is an actual list of those companies.
+ * TheirStack does both: filter companies by the technology they use (Salesforce,
+ * HubSpot, Pipedrive, …) plus firmographics, and return real records (name,
+ * domain, employee_count, …). A cheap count sizes the market; a paged search
+ * materializes the list. Both cost ~3 credits per company RETURNED — counting
+ * still returns 1 row (the API rejects limit:0), so a count is ~3 credits, not
+ * free; a list pull is ~3 × the rows.
+ *
+ * API: POST https://api.theirstack.com/v1/companies/search, Bearer auth.
+ * Verified live (2026-06-29): filters company_technology_slug_or /
+ * company_country_code_or / min_employee_count / max_employee_count; the total is
+ * `metadata.total_results` with include_total_results:true; limit must be ≥ 1
+ * (limit:0 → 422, the count gotcha — cf. Explorium's `size`-caps-the-total).
+ */
+/** TheirStack charges per company RETURNED — verified live (a list pull of N
+ *  companies spends 3N). The count (limit:1) returns 1 row, so it's ~3 credits. */
+export const THEIRSTACK_CREDITS_PER_COMPANY = 3;
+/** Deterministic cost of pulling `companies` records (the credits are the hard
+ *  fact; the dollar figure needs an explicit rate). */
+export function theirStackPullCost(companies, usdPerCredit) {
+    const n = Math.max(0, Math.round(companies));
+    const credits = n * THEIRSTACK_CREDITS_PER_COMPANY;
+    return {
+        companies: n,
+        credits,
+        ...(usdPerCredit && usdPerCredit > 0 ? { usd: Math.round(credits * usdPerCredit) } : {}),
+    };
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+const BASE = "https://api.theirstack.com";
+const SEARCH_PATH = "/v1/companies/search";
+function buildBody(filters, limit, page, includeTotal) {
+    // Drop undefined keys so we never send empty filters the API rejects.
+    const body = { limit, page };
+    if (includeTotal)
+        body.include_total_results = true;
+    if (filters.company_technology_slug_or?.length)
+        body.company_technology_slug_or = filters.company_technology_slug_or;
+    if (filters.company_country_code_or?.length)
+        body.company_country_code_or = filters.company_country_code_or;
+    if (typeof filters.min_employee_count === "number")
+        body.min_employee_count = filters.min_employee_count;
+    if (typeof filters.max_employee_count === "number")
+        body.max_employee_count = filters.max_employee_count;
+    return JSON.stringify(body);
+}
+/** Read the total-match count from the response envelope (field name varies). */
+export function readTheirStackTotal(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const obj = body;
+    const meta = (obj.metadata ?? obj.meta ?? obj);
+    for (const key of ["total_results", "total_companies", "total_count", "total", "count"]) {
+        const v = meta[key];
+        if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+            return Math.round(v);
+    }
+    return null;
+}
+function mapCompany(row) {
+    const str = (v) => (typeof v === "string" && v.trim() ? v : undefined);
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+    const slugs = row.technology_slugs ?? row.technology_names;
+    return {
+        name: str(row.name),
+        domain: str(row.domain),
+        employeeCount: num(row.employee_count),
+        countryCode: str(row.country_code),
+        city: str(row.city),
+        linkedinUrl: str(row.linkedin_url),
+        technologies: Array.isArray(slugs) ? slugs.filter((s) => typeof s === "string") : undefined,
+    };
+}
+/**
+ * Count companies matching the technographic + firmographic filter — the real
+ * TAM size. Uses `limit: 1` (the API rejects `limit: 0` with a 422 — verified
+ * live) + `include_total_results`, and reads `metadata.total_results`. Costs the
+ * 1 returned company's credits; the total itself is the point.
+ * Returns null if the envelope carries no total.
+ */
+export async function theirStackCountCompanies(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? BASE).replace(/\/$/, "");
+    const res = await fetchImpl(`${base}${SEARCH_PATH}`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
+        body: buildBody(opts.filters, 1, 0, true),
+    });
+    if (!res.ok) {
+        throw new Error(`TheirStack count failed: HTTP ${res.status} ${await safeText(res)}`);
+    }
+    return readTheirStackTotal(await res.json());
+}
+/**
+ * Pull a page of real companies matching the filter — the materialized list.
+ * Returns the records plus the total (when the envelope reports it).
+ */
+export async function theirStackSearchCompanies(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? BASE).replace(/\/$/, "");
+    const limit = Math.min(Math.max(opts.limit ?? 25, 1), 100);
+    const res = await fetchImpl(`${base}${SEARCH_PATH}`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
+        body: buildBody(opts.filters, limit, opts.page ?? 0, true),
+    });
+    if (!res.ok) {
+        throw new Error(`TheirStack search failed: HTTP ${res.status} ${await safeText(res)}`);
+    }
+    const body = (await res.json());
+    const rows = body.data ?? body.results ?? [];
+    return { companies: rows.map(mapCompany), total: readTheirStackTotal(body) };
+}

package/dist/icp.d.ts

@@ -23,6 +23,10 @@ export type Icp = {
         employeeBands?: string[];
         /** ISO country codes, lowercased, e.g. ["us"] */
         geos?: string[];
+        /** technographic targeting: technology slugs the account must use, e.g.
+         *  ["salesforce","hubspot","pipedrive"] — the real CRM/MAP buying signal,
+         *  consumed by TheirStack company search. OR-matched. */
+        technologies?: string[];
     };
     persona: {
         /** seniority: "cxo","vp","director","manager","owner","senior" */
@@ -47,13 +51,57 @@ export declare function icpToExploriumFilters(icp: Icp): Record<string, {
     values?: string[];
     value?: boolean;
 }>;
+/**
+ * Explorium /v1/businesses filters from the ICP — the COMPANY (account) side, for
+ * sizing the account universe (TAM). Firmographics only, no persona: the count is
+ * of matching companies. Field names differ from /v1/prospects (verified live):
+ * `country_code` (not company_country_code), `company_size` (same employee bands),
+ * `naics_category`. `/v1/businesses` total_results is a real count, capped at
+ * 60,000 (see EXPLORIUM_BUSINESS_COUNT_CAP in the connector).
+ */
+export declare function icpToExploriumBusinessFilters(icp: Icp): Record<string, {
+    values?: string[];
+}>;
+/**
+ * Collapse provider-agnostic employee bands ("51-200","10001+") into a single
+ * {min,max} envelope for APIs that take integer bounds (TheirStack). An open
+ * top band ("10001+") leaves max undefined.
+ */
+export declare function employeeBandsToRange(bands: string[] | undefined): {
+    min?: number;
+    max?: number;
+};
+/**
+ * TheirStack company-search filter from the ICP: the technographic targeting that
+ * Explorium can't do. `company_technology_slug_or` is the CRM/MAP buying signal
+ * (firmographics.technologies); employee bands become min/max bounds; geos become
+ * ISO2 codes (uppercased).
+ */
+export declare function icpToTheirStackFilters(icp: Icp): {
+    company_technology_slug_or?: string[];
+    min_employee_count?: number;
+    max_employee_count?: number;
+    company_country_code_or?: string[];
+};
 /**
  * pipe0 Crustdata people-search config.filters from the ICP. `current_job_titles`
  * matches real LinkedIn title strings (case-sensitive), so keywords are Title
- * Cased. Seniority + industry are mapped to Crustdata's controlled vocab via the
- * tables above. NOTE: the exact pipe0→Crustdata value set could not be re-run
- * live (pipe0 credits were exhausted) — validate when credits refill; fit
- * scoring is the safety net for persona precision regardless.
+ * Cased. Industry is mapped to Crustdata's controlled vocab via the table above.
+ *
+ * LIVE FINDINGS (2026-06-26, re-confirmed 2026-07-02 with fresh credits):
+ * `current_job_titles` works; `current_title` is rejected (422). The culprit
+ * that zeroed the full ICP filter is `current_seniority_levels`: ANY non-empty
+ * `include` returns 0 results through pipe0's people:profiles:crustdata@1 —
+ * including Crustdata's own documented values ("CXO", "Director",
+ * "Vice President"), lowercase, and SNAKE_CASE variants — while the identical
+ * search without it returns results. (An array instead of the
+ * {include, exclude} object is a 422, so the shape was right; the filter is
+ * broken upstream.) So job levels are NOT sent to the provider: persona
+ * seniority is enforced by fit scoring (scoreProspectAgainstIcp weights
+ * jobLevels), which was always the precision backstop. `locations` and
+ * `current_employers_linkedin_industries` (both-taxonomy hedge) are live-
+ * verified working in combination with titles. Note fit-scoring backs up
+ * PERSONA precision but NOT industry, so the industry filter is load-bearing.
  */
 export declare function icpToCrustdataFilters(icp: Icp): Record<string, unknown>;
 export type IcpFit = {