fullstackgtm 0.37.0 → 0.38.1

package/dist/cli.js

@@ -34,6 +34,8 @@ import { buildAcquirePlan, buildEnrichPlan, createFileEnrichRunStore, DEFAULT_ST
 import { loadMeter, recordConsumption, remaining, } from "./acquireMeter.js";
 import { crmContactKeys, fetchExploriumProspects, fetchPipe0CrustdataProspects, partitionFreshProspects, pipe0ResolveWorkEmails, prospectIdentityKeys, } from "./connectors/prospectSources.js";
 import { loadSeen, recordSeen } from "./acquireSeen.js";
+import { reportCounts, reportEvent } from "./runReport.js";
+import { createLinkedInProvider, discoverLinkedInProspects } from "./acquireLinkedIn.js";
 import { fitThreshold, icpFromAnswers, icpToCrustdataFilters, icpToExploriumFilters, parseIcp, scoreProspectAgainstIcp, INTERVIEW_SPEC, } from "./icp.js";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, } from "./enrichApollo.js";
 import { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, assertSingleLineLabel, hasControlChar, scheduleId, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, } from "./schedule.js";
@@ -54,7 +56,7 @@ Usage:
   fullstackgtm login salesforce --instance-url <url> [--no-validate]
   fullstackgtm login stripe [--no-validate]
   fullstackgtm login anthropic | openai        store an LLM API key for call parse/score
-  fullstackgtm login apollo                    store an Apollo API key for enrich pulls\n  fullstackgtm login pipe0 | explorium         store a discovery-provider key for enrich acquire\n  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|pipe0|explorium|broker>
+  fullstackgtm login apollo                    store an Apollo API key for enrich pulls\n  fullstackgtm login pipe0 | explorium         store a discovery-provider key for enrich acquire\n  fullstackgtm login heyreach                  store a HeyReach key for enrich acquire --source linkedin\n  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|pipe0|explorium|heyreach|broker>
 
   Secrets (tokens, client secrets) are NEVER passed as flags — they leak via
   the process list and shell history. Pipe them on stdin or enter them at the
@@ -129,9 +131,10 @@ Usage:
                                                deterministic survivor (richest = most populated data
                                                fields, ties to lowest id; oldest = lowest id). Approve and
                                                apply like any plan; merges are IRREVERSIBLE on apply.
-  fullstackgtm reassign --from <ownerId> --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--save] [--json] [--out <path>]
+  fullstackgtm reassign (--from <ownerId> | --assign-unowned) --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--save] [--json] [--out <path>]
                                                ownership handoff playbook: one bulk-update-style plan per
-                                               object type (ownerId=<from> → <to>). Extra --where scoping
+                                               object type (ownerId=<from> → <to>). --assign-unowned instead
+                                               claims every ownerless record (ownerId:empty) for --to. Extra --where scoping
                                                is account-lifted for deals/contacts (domain~.de becomes
                                                account.domain~.de); --except-deal-stage <stage> excludes
                                                deals in that stage AND every record whose account has an
@@ -358,7 +361,7 @@ const HELP = {
     reassign: {
         summary: "ownership handoff: one plan per object type",
         phase: "Remediate",
-        synopsis: ["fullstackgtm reassign --from <ownerId> --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--save] [--json]"],
+        synopsis: ["fullstackgtm reassign (--from <ownerId> | --assign-unowned) --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--save] [--json]"],
         detail: "Extra `--where` scoping is account-lifted for deals/contacts. `--except-deal-stage <stage>` excludes that stage and any record whose account has an open deal in it, re-verified per record at apply.",
         seeAlso: ["bulk-update", "plans", "apply"],
     },
@@ -723,6 +726,11 @@ async function audit(args) {
     if (staleDealDays !== undefined)
         policy.staleDealDays = staleDealDays;
     const plan = auditSnapshot(snapshot, policy, rules);
+    reportCounts({
+        findings: plan.findings.length,
+        critical: plan.findings.filter((f) => f.severity === "critical").length,
+        warning: plan.findings.filter((f) => f.severity === "warning").length,
+    });
     const out = option(args, "--out");
     if (out) {
         writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(plan, null, 2)}\n`);
@@ -1599,7 +1607,7 @@ enrich append  [--source apollo] [--objects companies,contacts] [--save] [--conf
 enrich refresh [--source apollo] [--stale-days <n>] [--save] [--config <path>]
                [source options] [--run-label <label>] [--json]
 enrich ingest  <file.csv|payload.json> --source clay [--run-label <label>] [--objects companies|contacts] [--config <path>]
-enrich acquire [--source <id>] [--max <n>] [--save] [--config <path>] [--json]
+enrich acquire [--source <id>] [--max <n>] [--list <id>] [--assign-owner <id>] [--save] [--config <path>] [--json]
 enrich status  [--runs] [--source <id>] [--config <path>] [--json]
 
 acquire creates NET-NEW leads from a staged prospect list (ingest first):
@@ -1609,6 +1617,16 @@ it dedupes each sourced row against the CRM, skips matches and ambiguities
 remaining budget (records + spend, per day and per month; whichever is hit
 first). Approval-gated like every write: \`--save\` → plans approve → apply.
 The meter is charged only when a create actually lands at apply.
+Discovery sources (zero-config presets): explorium | pipe0 (ICP-driven search),
+and linkedin (reads a HeyReach lead list — pass --list <id>, key on the LinkedIn
+URL, $0/record; \`login heyreach\` or HEYREACH_API_KEY).
+
+Leads are never born ownerless: set an \`acquire.assign\` policy (fixed /
+round-robin / territory / account-owner) to stamp an owner at create time, or
+pass \`--assign-owner <id>\`. With a single-owner portal and no policy, acquire
+defaults every lead to that owner; with several owners and no policy it warns
+and leaves them unassigned. Backfill existing ownerless records with
+\`reassign --assign-unowned --to <ownerId>\`.
 
 append pulls from an api source (Apollo — BYO key via \`login apollo\` or
 APOLLO_API_KEY) or reads data staged by \`enrich ingest\` (Clay CSV exports,
@@ -1725,6 +1743,31 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         let cap = headroom.maxRecords;
         if (explicitMax !== undefined)
             cap = cap === null ? explicitMax : Math.min(cap, explicitMax);
+        // Assignment: never create an ownerless lead. An explicit `acquire.assign`
+        // policy wins; a `--assign-owner <id>` flag is a quick fixed override;
+        // otherwise, when the portal has exactly one active owner, default every
+        // lead to them. With multiple owners and no policy we refuse to guess —
+        // leads are left unassigned and the operator is told to configure a rule.
+        const assignOwnerFlag = option(rest, "--assign-owner");
+        if (!config.acquire.assign) {
+            if (assignOwnerFlag) {
+                config.acquire.assign = { strategy: "fixed", ownerId: assignOwnerFlag };
+            }
+            else {
+                const activeOwners = (snapshot.users ?? []).filter((u) => u.active !== false);
+                if (activeOwners.length === 1) {
+                    const sole = activeOwners[0].crmId ?? activeOwners[0].id;
+                    config.acquire.assign = { strategy: "fixed", ownerId: sole };
+                    console.error(`Assignment: no policy set — defaulting every lead to the portal's sole owner ` +
+                        `${activeOwners[0].name} (${sole}). Configure "acquire.assign" to route across reps.`);
+                }
+                else if (activeOwners.length > 1) {
+                    console.error(`⚠ Assignment: ${activeOwners.length} active owners and no "acquire.assign" policy — ` +
+                        `leads will be created OWNERLESS. Add an acquire.assign rule (fixed / round-robin / territory) ` +
+                        `or pass --assign-owner <id> so every lead lands with an owner.`);
+                }
+            }
+        }
         const result = buildAcquirePlan({
             config,
             source,
@@ -1733,6 +1776,19 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
             runLabel: option(rest, "--run-label") ?? `acquire-${source}-${today}`,
             maxRecords: cap,
         });
+        if (result.counts.unassigned > 0 && result.counts.created > 0) {
+            console.error(`⚠ ${result.counts.unassigned}/${result.counts.created} proposed lead(s) have no owner ` +
+                `(policy could not place them). They will be created ownerless.`);
+        }
+        // Observability: headline metrics for the web run timeline (paired users).
+        reportCounts({
+            sourced: result.counts.fetched,
+            created: result.counts.created,
+            withheldByMeter: result.counts.withheldByMeter,
+            skippedInCrm: apiSkippedCrm,
+            skippedSeen: apiSkippedSeen,
+            estCostUsd: result.estCostUsd,
+        });
         const meterLine = formatAcquireMeter(headroom, costPerRecord);
         if (!save) {
             if (rest.includes("--json")) {
@@ -1750,6 +1806,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         if (result.plan.operations.length > 0) {
             await createFilePlanStore().save(result.plan);
             planIds.push(result.plan.id);
+            reportEvent("plan_saved", result.plan.id);
         }
         await store.update({
             ...run,
@@ -1861,6 +1918,12 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     // Pull keys the source had no data for count as fetched-but-unmatched.
     result.counts.fetched += missCount;
     result.counts.unmatched += missCount;
+    reportCounts({
+        fetched: result.counts.fetched,
+        matched: result.counts.matched,
+        unmatched: result.counts.unmatched,
+        opsEmitted: result.counts.opsEmitted,
+    });
     if (!save) {
         if (rest.includes("--json")) {
             console.log(JSON.stringify(result.plan, null, 2));
@@ -1906,7 +1969,7 @@ function formatEnrichCounts(counts, ambiguities) {
 /** Best-effort enrich-config load for apply-time acquire-budget enforcement. */
 /** Provider API key: env override first, then the credential store (`login`). */
 function providerKey(provider) {
-    const envName = provider === "explorium" ? "EXPLORIUM_API_KEY" : "PIPE0_API_KEY";
+    const envName = provider === "explorium" ? "EXPLORIUM_API_KEY" : provider === "pipe0" ? "PIPE0_API_KEY" : "HEYREACH_API_KEY";
     if (process.env[envName])
         return process.env[envName];
     const stored = getCredential(provider);
@@ -2006,8 +2069,18 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen) {
         const filters = icp ? icpToCrustdataFilters(icp) : (disc.filters ?? {});
         prospects = await fetchPipe0CrustdataProspects({ apiKey: providerKey("pipe0"), filters, limit: size });
     }
+    else if (disc.provider === "linkedin" || disc.provider === "heyreach") {
+        // LinkedIn reads a pre-populated lead list (not an ICP-driven query); the ICP
+        // scores the pulled list below. List id: disc.listId or --list <id>.
+        const listId = disc.listId ?? option(rest, "--list") ?? undefined;
+        if (!listId) {
+            throw new Error("enrich acquire --source linkedin needs a HeyReach lead-list id: pass --list <id> or set acquire.discovery.linkedin.listId.");
+        }
+        const provider = createLinkedInProvider(disc.provider, providerKey("heyreach"));
+        prospects = await discoverLinkedInProspects(provider, { sourceId: listId, max: size });
+    }
     else {
-        throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (explorium | pipe0).`);
+        throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (explorium | pipe0 | linkedin).`);
     }
     // 2. ICP fit scoring BEFORE paying for emails — only above-threshold prospects
     //    proceed to (credit-spending) email resolution.
@@ -2807,8 +2880,9 @@ async function dedupeCommand(args) {
 async function reassignCommand(args) {
     const from = option(args, "--from");
     const to = option(args, "--to");
-    if (!from || !to) {
-        throw new Error("Usage: fullstackgtm reassign --from <ownerId> --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]");
+    const assignUnowned = args.includes("--assign-unowned");
+    if (!to || (!from && !assignUnowned)) {
+        throw new Error("Usage: fullstackgtm reassign (--from <ownerId> | --assign-unowned) --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]\n\n--assign-unowned claims every OWNERLESS record (ownerId:empty) for --to — the backfill twin of `enrich acquire`'s create-time assignment.");
     }
     const objects = option(args, "--objects")
         ?.split(",")
@@ -2816,8 +2890,9 @@ async function reassignCommand(args) {
         .filter(Boolean);
     const snapshot = await readSnapshot(args);
     const plans = buildReassignPlans(snapshot, {
-        fromOwnerId: from,
+        fromOwnerId: from ?? undefined,
         toOwnerId: to,
+        assignUnowned,
         objects,
         where: repeatedOption(args, "--where"),
         exceptDealStage: option(args, "--except-deal-stage") ?? undefined,
@@ -3159,6 +3234,11 @@ async function apply(args) {
             recordConsumption(new Date(), landed.length, spend);
         }
     }
+    // Observability: apply-outcome tallies for the web run timeline.
+    const applyTally = { applied: 0, conflict: 0, skipped: 0, failed: 0 };
+    for (const result of run.results)
+        applyTally[result.status] = (applyTally[result.status] ?? 0) + 1;
+    reportCounts(applyTally);
     if (args.includes("--json")) {
         console.log(JSON.stringify(run, null, 2));
     }
@@ -3603,7 +3683,7 @@ async function login(args) {
         console.log(`Stored Apollo API key in ${credentialsPath()}. \`fullstackgtm enrich append|refresh\` use it automatically.`);
         return;
     }
-    if (provider === "pipe0" || provider === "explorium") {
+    if (provider === "pipe0" || provider === "explorium" || provider === "heyreach") {
         rejectArgvSecret(args, "--token", "--key", "--api-key");
         const key = await readSecret(`${provider} API key`);
         if (!key)

package/dist/connectors/hubspot.js

@@ -493,18 +493,27 @@ export function createHubspotConnector(options) {
             }
             return { operationId: operation.id, status: "applied", detail: `Resolved/created company "${matchValue}" (${id}).`, providerData: { id } };
         }
-        // contact — resolve-first on the dedupe key (email by default)
+        // contact — resolve-first on the dedupe key (email by default). The match
+        // key is canonical (e.g. "linkedin"); translate it to the HubSpot property
+        // name ("hs_linkedin_url") before searching — HubSpot 400s on a filter
+        // against a property it doesn't have (there is no property named "linkedin").
         const matchKey = payload.matchKey || "email";
+        const searchProperty = HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts[matchKey] ?? matchKey;
         const matchKeyLower = `${matchKey}:${matchValue.toLowerCase()}`;
         if (createdContactsByMatch.has(matchKeyLower)) {
             return { operationId: operation.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: createdContactsByMatch.get(matchKeyLower), existing: true } };
         }
-        const existing = await searchContactsBy(matchKey, matchValue);
+        const existing = await searchContactsBy(searchProperty, matchValue);
         if (existing.length > 0) {
             createdContactsByMatch.set(matchKeyLower, existing[0]);
             return { operationId: operation.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existing.join(", ")}); resolve-first declined to create.`, providerData: { id: existing[0], existing: true } };
         }
         const properties = { ...payload.properties };
+        // Stamp ownership at create time so the lead is never born ownerless. The
+        // canonical ownerId maps to HubSpot's standard owner property.
+        if (payload.ownerId && !properties.hubspot_owner_id) {
+            properties.hubspot_owner_id = String(payload.ownerId);
+        }
         let created;
         try {
             created = await request(`/crm/v3/objects/${objectPath}`, {

package/dist/connectors/linkedin.d.ts

@@ -0,0 +1,78 @@
+/**
+ * LinkedIn connector — Phase 1 discovery (read-only).
+ *
+ * A provider-agnostic surface for pulling prospects out of LinkedIn via a
+ * rented execution layer (default: HeyReach; Unipile is a drop-in alternative).
+ * Deliberately decoupled from the acquire spine — the `Icp`→filter and
+ * `LinkedInProspect`→`Prospect` bridges live in the `enrich acquire --source
+ * linkedin` wiring, not here — so this layer can land and be tested on its own.
+ *
+ * Phase 2 (future) extends `LinkedInProvider` with send actions
+ * (connect/message) routed through the plan/apply gate. Spec:
+ * docs/linkedin-connector-spec.md. Nothing here ever writes or sends.
+ */
+export type LinkedInProspect = {
+    firstName: string;
+    lastName: string;
+    fullName?: string;
+    headline?: string;
+    jobTitle?: string;
+    company?: string;
+    /** Canonical LinkedIn profile URL — the identity key dedup uses downstream. */
+    profileUrl: string;
+    location?: string;
+    email?: string;
+    emailStatus?: string;
+    /** The raw provider payload, preserved for debugging and later mapping. */
+    raw?: unknown;
+};
+export type LinkedInSource = {
+    /** Provider-native id of a prospect source (HeyReach: a lead-list id). */
+    id: string;
+    name: string;
+    /** Approximate prospect count, when the provider reports it. */
+    count?: number;
+};
+export type FetchProspectsOptions = {
+    /** Which source to read (HeyReach lead-list id); provider may have a default. */
+    sourceId?: string;
+    /** Hard cap on prospects returned; also bounds pagination. */
+    max?: number;
+};
+export type ConnectionStatus = {
+    ok: boolean;
+    detail: string;
+};
+/**
+ * Provider-agnostic LinkedIn discovery surface (Phase 1). Read-only: it
+ * enumerates prospect sources and pulls normalized prospects, never sends.
+ */
+export interface LinkedInProvider {
+    readonly name: string;
+    /** Cheap auth/connectivity check; never throws — returns ok:false instead. */
+    checkConnection(): Promise<ConnectionStatus>;
+    /** Enumerate prospect sources (HeyReach lead lists). */
+    listSources(): Promise<LinkedInSource[]>;
+    /** Pull prospects from a source, normalized + capped. */
+    fetchProspects(options?: FetchProspectsOptions): Promise<LinkedInProspect[]>;
+}
+export declare const HEYREACH_BASE = "https://api.heyreach.io/api/public";
+export type HeyReachProviderOptions = {
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    baseUrl?: string;
+    /** Lead-list id used when fetchProspects is called without an explicit sourceId. */
+    defaultListId?: string;
+    /** Page size for paginated reads (≤ server max). Lower in tests. */
+    pageSize?: number;
+};
+export declare function createHeyReachProvider(options: HeyReachProviderOptions): LinkedInProvider;
+/** Map a HeyReach lead (nested `profile` or flat) into the normalized shape. */
+export declare function normalizeHeyReachLead(raw: any): LinkedInProspect;
+export declare const FAKE_LINKEDIN_PROSPECTS: LinkedInProspect[];
+export type FakeLinkedInOptions = {
+    prospects?: LinkedInProspect[];
+    sources?: LinkedInSource[];
+    connection?: ConnectionStatus;
+};
+export declare function createFakeLinkedInProvider(opts?: FakeLinkedInOptions): LinkedInProvider;

package/dist/connectors/linkedin.js

@@ -0,0 +1,199 @@
+/**
+ * LinkedIn connector — Phase 1 discovery (read-only).
+ *
+ * A provider-agnostic surface for pulling prospects out of LinkedIn via a
+ * rented execution layer (default: HeyReach; Unipile is a drop-in alternative).
+ * Deliberately decoupled from the acquire spine — the `Icp`→filter and
+ * `LinkedInProspect`→`Prospect` bridges live in the `enrich acquire --source
+ * linkedin` wiring, not here — so this layer can land and be tested on its own.
+ *
+ * Phase 2 (future) extends `LinkedInProvider` with send actions
+ * (connect/message) routed through the plan/apply gate. Spec:
+ * docs/linkedin-connector-spec.md. Nothing here ever writes or sends.
+ */
+// ── HeyReach adapter ────────────────────────────────────────────────────────
+// Base + auth verified 2026-06-20: POST endpoints, `X-API-KEY` header, 300
+// req/min (429). Confirmed live: /auth/CheckApiKey, /list/GetAll. The
+// leads-from-list path has a documented gap in HeyReach's public docs and is
+// marked to reconcile at live validation (step 3, needs a real key).
+export const HEYREACH_BASE = "https://api.heyreach.io/api/public";
+const HEYREACH_MAX_PAGE = 100;
+export function createHeyReachProvider(options) {
+    const apiKey = options.apiKey;
+    if (!apiKey) {
+        throw new Error("HeyReach API key is required (`login heyreach` or HEYREACH_API_KEY).");
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const baseUrl = (options.baseUrl ?? HEYREACH_BASE).replace(/\/$/, "");
+    const pageSize = Math.max(1, Math.min(options.pageSize ?? HEYREACH_MAX_PAGE, HEYREACH_MAX_PAGE));
+    async function call(path, method, body) {
+        let response;
+        try {
+            response = await fetchImpl(`${baseUrl}${path}`, {
+                method,
+                // Secret travels in the header, never the URL (no leak via logs/history).
+                headers: {
+                    "X-API-KEY": apiKey,
+                    ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch {
+            throw new Error(`Cannot reach HeyReach at ${baseUrl}${path}. Check network access.`);
+        }
+        if (response.status === 429) {
+            const retry = response.headers.get("Retry-After");
+            throw new Error(`HeyReach rate limit (429)${retry ? `; retry after ${retry}s` : ""}. The cap is 300 requests/min.`);
+        }
+        if (!response.ok) {
+            await response.text().catch(() => undefined);
+            throw new Error(`HeyReach API error ${response.status} on ${path}. Check the API key and request.`);
+        }
+        if (response.status === 204)
+            return undefined;
+        return response.json().catch(() => undefined);
+    }
+    return {
+        name: "heyreach",
+        async checkConnection() {
+            try {
+                await call("/auth/CheckApiKey", "GET");
+                return { ok: true, detail: "HeyReach API key valid." };
+            }
+            catch (error) {
+                return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        async listSources() {
+            const data = await call("/list/GetAll", "POST", { offset: 0, limit: HEYREACH_MAX_PAGE });
+            return toArray(data).map((item) => ({
+                id: String(item?.id ?? item?.listId ?? ""),
+                name: String(item?.name ?? item?.title ?? "(unnamed list)"),
+                count: typeof item?.totalItemsCount === "number"
+                    ? item.totalItemsCount
+                    : typeof item?.count === "number"
+                        ? item.count
+                        : undefined,
+            }));
+        },
+        async fetchProspects(opts = {}) {
+            const listId = opts.sourceId ?? options.defaultListId;
+            if (!listId) {
+                throw new Error("HeyReach fetchProspects needs a sourceId (lead-list id) or a configured defaultListId — list them with listSources().");
+            }
+            const max = opts.max ?? Number.POSITIVE_INFINITY;
+            const out = [];
+            let offset = 0;
+            while (out.length < max) {
+                const data = await call("/list/GetLeadsFromList", "POST", { listId, offset, limit: pageSize });
+                const items = toArray(data);
+                if (items.length === 0)
+                    break;
+                for (const item of items) {
+                    out.push(normalizeHeyReachLead(item));
+                    if (out.length >= max)
+                        break;
+                }
+                if (items.length < pageSize)
+                    break;
+                offset += items.length;
+            }
+            return out;
+        },
+    };
+}
+/** First value that is a non-empty string, else undefined (treats "" as absent). */
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+    }
+    return undefined;
+}
+/** HeyReach wraps list payloads as `{ items: [...] }` on some routes, bare arrays on others. */
+function toArray(data) {
+    if (Array.isArray(data))
+        return data;
+    if (Array.isArray(data?.items))
+        return data.items;
+    return [];
+}
+/** Map a HeyReach lead (nested `profile` or flat) into the normalized shape. */
+export function normalizeHeyReachLead(raw) {
+    const p = (raw && typeof raw === "object" && raw.profile) || raw || {};
+    const first = p.firstName ?? raw?.firstName ?? "";
+    const last = p.lastName ?? raw?.lastName ?? "";
+    const full = (p.fullName ?? raw?.fullName ?? `${first} ${last}`.trim()) || undefined;
+    return {
+        firstName: String(first ?? ""),
+        lastName: String(last ?? ""),
+        fullName: full,
+        headline: p.headline ?? raw?.headline ?? undefined,
+        jobTitle: p.position ?? p.jobTitle ?? raw?.position ?? undefined,
+        company: p.companyName ?? p.company ?? raw?.companyName ?? undefined,
+        profileUrl: String(p.profileUrl ?? p.linkedInUrl ?? raw?.profileUrl ?? raw?.linkedin_url ?? ""),
+        location: p.location ?? raw?.location ?? undefined,
+        // HeyReach exposes the raw `emailAddress` plus its own enrichment outputs
+        // (`enrichedEmailAddress`, `customEmailAddress`) — verified against the live
+        // /list/GetLeadsFromList schema 2026-06-20. Unresolved emails come back as
+        // "", so pick the first NON-EMPTY value (?? would keep the empty string).
+        email: firstNonEmpty(p.emailAddress, p.enrichedEmailAddress, p.customEmailAddress, p.email, raw?.emailAddress),
+        emailStatus: p.emailStatus ?? raw?.emailStatus ?? undefined,
+        raw,
+    };
+}
+// ── Fake provider (tests / dry-run with no key, no network) ─────────────────
+export const FAKE_LINKEDIN_PROSPECTS = [
+    {
+        firstName: "Dana",
+        lastName: "Okafor",
+        fullName: "Dana Okafor",
+        headline: "VP RevOps",
+        jobTitle: "VP Revenue Operations",
+        company: "Northwind Logistics",
+        profileUrl: "https://www.linkedin.com/in/dana-okafor",
+        location: "Chicago, IL",
+        email: "dana@northwind.example",
+        emailStatus: "verified",
+    },
+    {
+        firstName: "Priya",
+        lastName: "Raman",
+        fullName: "Priya Raman",
+        headline: "Head of Sales Ops",
+        jobTitle: "Head of Sales Operations",
+        company: "Cobalt Health",
+        profileUrl: "https://www.linkedin.com/in/priya-raman",
+        location: "Austin, TX",
+    },
+    {
+        firstName: "Marco",
+        lastName: "Bianchi",
+        fullName: "Marco Bianchi",
+        headline: "RevOps Manager",
+        jobTitle: "Revenue Operations Manager",
+        company: "Ferro Systems",
+        profileUrl: "https://www.linkedin.com/in/marco-bianchi",
+        location: "Remote",
+        email: "marco@ferro.example",
+        emailStatus: "guessed",
+    },
+];
+export function createFakeLinkedInProvider(opts = {}) {
+    const prospects = opts.prospects ?? FAKE_LINKEDIN_PROSPECTS;
+    const sources = opts.sources ?? [{ id: "list_demo", name: "Demo ICP list", count: prospects.length }];
+    return {
+        name: "fake",
+        async checkConnection() {
+            return opts.connection ?? { ok: true, detail: "fake LinkedIn provider" };
+        },
+        async listSources() {
+            return sources.map((s) => ({ ...s }));
+        },
+        async fetchProspects(options = {}) {
+            const capped = options.max != null ? prospects.slice(0, options.max) : prospects;
+            return capped.map((p) => ({ ...p }));
+        },
+    };
+}

package/dist/enrich.d.ts

@@ -1,4 +1,5 @@
 import type { AcquireBudget } from "./acquireMeter.ts";
+import type { AssignmentContext, AssignmentPolicy } from "./assign.ts";
 import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
 /**
  * The enrich layer: governed append/refresh of third-party data into the CRM.
@@ -75,10 +76,12 @@ export type AcquireCreateMap = {
  * real emails (e.g. explorium discovers, pipe0 resolves the work email).
  */
 export type AcquireDiscoveryConfig = {
-    provider: "explorium" | "pipe0";
+    provider: "explorium" | "pipe0" | "linkedin" | "heyreach";
     filters?: Record<string, unknown>;
     size?: number;
     resolveEmailsWith?: "pipe0";
+    /** LinkedIn sources only: the provider-native list id to read (HeyReach lead-list id). */
+    listId?: string;
 };
 export type AcquireConfig = {
     /** Windowed budget enforced by the acquire meter; absent = unmetered. */
@@ -89,6 +92,12 @@ export type AcquireConfig = {
     create: Partial<Record<EnrichObjectType, AcquireCreateMap>>;
     /** Net-new discovery params for API sources, by source id. */
     discovery?: Record<string, AcquireDiscoveryConfig>;
+    /**
+     * Ownership rule stamped onto every created lead so it is never born
+     * ownerless. Absent = no auto-assignment (the CLI may still default to the
+     * portal's sole active owner). Shared with `reassign --assign-unowned`.
+     */
+    assign?: AssignmentPolicy;
 };
 export declare const ENRICH_CONFIG_FILE_NAME = "enrich.config.json";
 export declare const DEFAULT_STALE_DAYS = 90;
@@ -216,6 +225,10 @@ export type AcquireCounts = {
     created: number;
     /** unmatched rows that would have been created but for the meter ceiling. */
     withheldByMeter: number;
+    /** created ops that got an owner stamped (a subset of `created`). */
+    assigned: number;
+    /** created ops left ownerless (no policy, or policy could not place them). */
+    unassigned: number;
 };
 export type AcquirePlanResult = {
     plan: PatchPlan;
@@ -232,6 +245,13 @@ export type BuildAcquirePlanOptions = {
     maxRecords?: number | null;
     now?: () => Date;
 };
+/**
+ * Lift a prospect/source payload into the routing attributes a territory rule
+ * reads. Tolerant of provider spellings (explorium vs pipe0); absent attributes
+ * stay undefined, so a rule that routes on them simply won't match (falling to
+ * the policy fallback) instead of mis-routing.
+ */
+export declare function acquireAssignmentContext(payload: Record<string, unknown>, companyName: string | undefined, accountOwnerByName: ReadonlyMap<string, string>): AssignmentContext;
 /**
  * Match each sourced record against the snapshot and route it: matched =
  * already in the CRM (skip), ambiguous = a possible duplicate exists (skip —