fullstackgtm 0.37.0 → 0.38.1

package/src/connectors/linkedin.ts

@@ -0,0 +1,272 @@
+/**
+ * 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[]>;
+}
+
+// ── 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 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 function createHeyReachProvider(options: HeyReachProviderOptions): LinkedInProvider {
+  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: string, method: "GET" | "POST", body?: unknown): Promise<any> {
+    let response: 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: any) => ({
+        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: LinkedInProspect[] = [];
+      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: unknown[]): string | undefined {
+  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: any): any[] {
+  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: any): LinkedInProspect {
+  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: LinkedInProspect[] = [
+  {
+    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 type FakeLinkedInOptions = {
+  prospects?: LinkedInProspect[];
+  sources?: LinkedInSource[];
+  connection?: ConnectionStatus;
+};
+
+export function createFakeLinkedInProvider(opts: FakeLinkedInOptions = {}): LinkedInProvider {
+  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/src/enrich.ts

@@ -3,6 +3,8 @@ import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.ts";
 import { HUBSPOT_DEFAULT_FIELD_MAPPINGS } from "./mappings.ts";
 import type { AcquireBudget } from "./acquireMeter.ts";
+import { parseAssignmentPolicy, resolveAssignment } from "./assign.ts";
+import type { AssignmentContext, AssignmentPolicy } from "./assign.ts";
 import type {
   CanonicalGtmSnapshot,
   CreateRecordPayload,
@@ -99,10 +101,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 = {
@@ -114,6 +118,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 const ENRICH_CONFIG_FILE_NAME = "enrich.config.json";
@@ -125,7 +135,7 @@ const OBJECT_TYPES: EnrichObjectType[] = ["company", "contact"];
 /** Match keys the matcher knows how to read off canonical snapshot records. */
 const MATCH_KEYS: Record<EnrichObjectType, string[]> = {
   company: ["domain", "name"],
-  contact: ["email", "name"],
+  contact: ["email", "name", "linkedin"],
 };
 
 /** API source ids the MVP can pull from. */
@@ -311,6 +321,16 @@ export function parseEnrichConfig(raw: string): EnrichConfig {
     fail('"fields" maps nothing — add at least one field entry (or an "acquire.create" mapping)');
   }
 
+  // Normalize + validate the assignment policy (fails loud on shape errors so a
+  // misconfigured rule never silently mis-routes a created lead).
+  if (config.acquire?.assign !== undefined) {
+    try {
+      config.acquire.assign = parseAssignmentPolicy(config.acquire.assign);
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+  }
+
   return config as EnrichConfig;
 }
 
@@ -348,6 +368,35 @@ export function builtinEnrichPreset(source: string | undefined): EnrichConfig |
  */
 export function builtinAcquirePreset(source: string | undefined): EnrichConfig | undefined {
   const provider = source ?? "pipe0";
+  if (provider === "linkedin" || provider === "heyreach") {
+    // LinkedIn discovery reads our OWN HeyReach lead list, so it costs $0/record
+    // (no spend budget) and keys on the LinkedIn URL — leads are sparse on email,
+    // so email-keying would drop most of them. listId is supplied via --list.
+    return {
+      sources: { linkedin: { kind: "api" } },
+      match: { contact: { keys: ["linkedin", "email"], onAmbiguous: "skip" } },
+      fields: {},
+      policy: { overwrite: "never" },
+      acquire: {
+        budget: { records: { perDay: 50, perMonth: 500 } },
+        costPerRecord: { linkedin: 0 },
+        discovery: { linkedin: { provider: "linkedin", size: 25 } },
+        create: {
+          contact: {
+            matchKey: "linkedin",
+            properties: {
+              hs_linkedin_url: "linkedin",
+              firstname: "firstName",
+              lastname: "lastName",
+              jobtitle: "jobTitle",
+              company: "companyName",
+              email: "email",
+            },
+          },
+        },
+      },
+    };
+  }
   if (provider !== "pipe0" && provider !== "explorium") return undefined;
   return {
     sources: { [provider]: { kind: "api" } },
@@ -542,12 +591,16 @@ function normalizeKeyValue(key: string, value: unknown): string {
       .replace(/^www\./, "")
       .replace(/\/.*$/, "");
   }
+  if (key === "linkedin") {
+    // Match crmContactKeys' `li:` normalization (lowercased, trailing slash stripped).
+    return text.trim().replace(/\/+$/, "");
+  }
   return text.replace(/\s+/g, " ");
 }
 
 function crmKeyValue(
   objectType: EnrichObjectType,
-  record: { name?: string; domain?: string; email?: string; firstName?: string; lastName?: string },
+  record: { name?: string; domain?: string; email?: string; firstName?: string; lastName?: string; linkedin?: string },
   key: string,
 ): string {
   if (objectType === "company") {
@@ -556,6 +609,7 @@ function crmKeyValue(
     return "";
   }
   if (key === "email") return normalizeKeyValue("email", record.email);
+  if (key === "linkedin") return normalizeKeyValue("linkedin", record.linkedin);
   if (key === "name") {
     return normalizeKeyValue("name", `${record.firstName ?? ""} ${record.lastName ?? ""}`.trim());
   }
@@ -922,6 +976,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 = {
@@ -941,6 +999,44 @@ export type BuildAcquirePlanOptions = {
   now?: () => Date;
 };
 
+/** First non-empty value among several candidate paths in a source payload. */
+function firstSourceValue(payload: Record<string, unknown>, paths: string[]): string | undefined {
+  for (const path of paths) {
+    const value = sourceValueAt(payload, path);
+    if (!isEmptyValue(value)) return String(value).trim();
+  }
+  return undefined;
+}
+
+/**
+ * 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 function acquireAssignmentContext(
+  payload: Record<string, unknown>,
+  companyName: string | undefined,
+  accountOwnerByName: ReadonlyMap<string, string>,
+): AssignmentContext {
+  const ctx: AssignmentContext = {};
+  const title = firstSourceValue(payload, ["jobTitle", "job_title", "title"]);
+  if (title) ctx.title = title.toLowerCase();
+  const geo = firstSourceValue(payload, ["geo", "country", "company_country_code", "companyCountry"]);
+  if (geo) ctx.geo = geo.toLowerCase();
+  const industry = firstSourceValue(payload, ["industry", "company_industry", "companyIndustry"]);
+  if (industry) ctx.industry = industry.toLowerCase();
+  const employeeBand = firstSourceValue(payload, ["employeeBand", "company_size", "companySize"]);
+  if (employeeBand) ctx.employeeBand = employeeBand;
+  const department = firstSourceValue(payload, ["department", "job_department", "jobDepartment"]);
+  if (department) ctx.department = department.toLowerCase();
+  if (companyName) {
+    const owner = accountOwnerByName.get(companyName.trim().toLowerCase());
+    if (owner) ctx.accountOwnerId = owner;
+  }
+  return ctx;
+}
+
 /**
  * Match each sourced record against the snapshot and route it: matched =
  * already in the CRM (skip), ambiguous = a possible duplicate exists (skip —
@@ -969,9 +1065,30 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
     unmatched: 0,
     created: 0,
     withheldByMeter: 0,
+    assigned: 0,
+    unassigned: 0,
   };
   let estCostUsd = 0;
 
+  // Assignment context (built once): the set of owner ids the CRM will accept
+  // (active users), and a company-name → account-owner lookup for the
+  // "account-owner" inherit strategy. Empty when no assign policy is set.
+  const assignPolicy = acquire.assign;
+  const knownOwnerIds = new Set<string>();
+  const accountOwnerByName = new Map<string, string>();
+  if (assignPolicy) {
+    for (const user of snapshot.users ?? []) {
+      if (user.active === false) continue;
+      if (user.crmId) knownOwnerIds.add(user.crmId);
+      if (user.id) knownOwnerIds.add(user.id);
+    }
+    for (const account of snapshot.accounts ?? []) {
+      if (account.name && account.ownerId) {
+        accountOwnerByName.set(account.name.trim().toLowerCase(), account.ownerId);
+      }
+    }
+  }
+
   for (const record of records) {
     const createMap = acquire.create[record.objectType];
     const match = config.match[record.objectType];
@@ -1024,6 +1141,20 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
     );
     evidence.push(recordEvidence);
 
+    // Resolve ownership BEFORE the meter-charged create lands, so the lead is
+    // never born ownerless. `counts.created` is the within-run index, giving
+    // round-robin deterministic, even distribution with no persisted cursor.
+    let ownerId: string | undefined;
+    let assignedBy: string | undefined;
+    if (assignPolicy) {
+      const ctx = acquireAssignmentContext(record.payload, associateCompanyName, accountOwnerByName);
+      const resolved = resolveAssignment(assignPolicy, ctx, counts.created, knownOwnerIds);
+      if (resolved.ownerId) {
+        ownerId = resolved.ownerId;
+        assignedBy = resolved.rule;
+      }
+    }
+
     const payload: CreateRecordPayload = {
       properties,
       matchKey: createMap.matchKey,
@@ -1031,6 +1162,7 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
       source,
       estCostUsd: costPerRecord,
       associateCompanyName,
+      ...(ownerId ? { ownerId, assignedBy } : {}),
     };
     operations.push({
       id: `op_acq_${fnv1a(`${source}:${record.objectType}:${matchValue}`)}`,
@@ -1048,6 +1180,8 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
       rollback: "Archive the created record (it was net-new).",
       evidenceIds: [recordEvidence.id],
     });
+    if (ownerId) counts.assigned += 1;
+    else counts.unassigned += 1;
     counts.created += 1;
     estCostUsd += costPerRecord;
   }

package/src/index.ts

@@ -1,4 +1,14 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
+export {
+  matchesTerritory,
+  parseAssignmentPolicy,
+  resolveAssignment,
+  type AssignmentContext,
+  type AssignmentPolicy,
+  type AssignmentResult,
+  type AssignmentStrategy,
+  type TerritoryRule,
+} from "./assign.ts";
 export { buildBulkUpdatePlan, isFilterableField, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
 export { buildDedupePlan, dedupeKey, type DedupeOptions } from "./dedupe.ts";
 export { buildReassignPlans, type ReassignObjectType, type ReassignOptions } from "./reassign.ts";

package/src/reassign.ts

@@ -28,10 +28,19 @@ import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
 export type ReassignObjectType = "account" | "contact" | "deal";
 
 export type ReassignOptions = {
-  /** the owner whose records are being handed off */
-  fromOwnerId: string;
+  /**
+   * the owner whose records are being handed off. Ignored (and not required)
+   * when `assignUnowned` is set — that mode targets ownerless records instead.
+   */
+  fromOwnerId?: string;
   /** the receiving owner — must be a known user in the snapshot */
   toOwnerId: string;
+  /**
+   * Backfill mode: instead of moving records from one owner to another, claim
+   * every OWNERLESS record (ownerId:empty) for `toOwnerId`. Shares the create-
+   * time assignment intent with `enrich acquire`, applied to existing debt.
+   */
+  assignUnowned?: boolean;
   /** which object types to compile plans for (default all three) */
   objects?: ReassignObjectType[];
   /** extra --where scoping, AND-ed into every plan (account fields lifted) */
@@ -65,11 +74,16 @@ export function buildReassignPlans(
   snapshot: CanonicalGtmSnapshot,
   options: ReassignOptions,
 ): PatchPlan[] {
-  if (!options.fromOwnerId || !options.toOwnerId) {
-    throw new Error("reassign requires both --from <ownerId> and --to <ownerId>.");
+  if (!options.toOwnerId) {
+    throw new Error("reassign requires --to <ownerId>.");
   }
-  if (options.fromOwnerId === options.toOwnerId) {
-    throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+  if (!options.assignUnowned) {
+    if (!options.fromOwnerId) {
+      throw new Error("reassign requires --from <ownerId> (or --assign-unowned to claim ownerless records).");
+    }
+    if (options.fromOwnerId === options.toOwnerId) {
+      throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+    }
   }
   // The receiving owner must exist: a typo'd --to would otherwise write an
   // invalid owner onto every matched record.
@@ -88,7 +102,7 @@ export function buildReassignPlans(
   }
 
   return objects.map((objectType) => {
-    const where = [`ownerId=${options.fromOwnerId}`];
+    const where = [options.assignUnowned ? "ownerId:empty" : `ownerId=${options.fromOwnerId}`];
     if (objectType === "deal" && !options.includeClosedDeals) {
       where.push("isClosed=false"); // closed deals keep their historical owner
     }
@@ -110,7 +124,9 @@ export function buildReassignPlans(
       set: { ownerId: options.toOwnerId },
       reason:
         options.reason ??
-        `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`,
+        (options.assignUnowned
+          ? `reassign: claim ownerless ${objectType}s for owner ${options.toOwnerId}`
+          : `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`),
       maxOperations: options.maxOperations,
     });
   });

package/src/runReport.ts

@@ -0,0 +1,76 @@
+/**
+ * Opt-in CLI → hosted-app observability. When the user has paired the CLI
+ * (`login --via <url>` → broker token), each command fire-and-forgets a run
+ * record to the hosted app's `/api/cli/run`, authenticated by the broker token.
+ *
+ * Invariants: the CLI never requires web login; this does nothing when unpaired;
+ * it never throws and never changes the CLI's exit code or output. Reporting is
+ * pure added value for users who granted it.
+ */
+import { getCredential } from "./credentials.ts";
+
+type RunEvent = { ts: number; type: string; detail?: string };
+
+let counts: Record<string, unknown> | undefined;
+const events: RunEvent[] = [];
+
+/** A command annotates its headline metrics (merged). */
+export function reportCounts(values: Record<string, unknown>): void {
+  counts = { ...(counts ?? {}), ...values };
+}
+
+/** A command annotates a structured event (plan saved, meter charged, …). */
+export function reportEvent(type: string, detail?: string): void {
+  events.push({ ts: Date.now(), type, detail });
+}
+
+// Setup/inspection verbs aren't interesting as "runs" — skip the noise.
+const SKIP_COMMANDS = new Set([
+  "login",
+  "logout",
+  "doctor",
+  "help",
+  "profiles",
+  "--help",
+  "-h",
+  "--version",
+  "-v",
+]);
+
+/**
+ * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
+ * swallows every error. Call once per process from the entry point.
+ */
+export async function flushRunReport(
+  args: string[],
+  status: "success" | "partial" | "error",
+  startedAt: number,
+  error?: string,
+): Promise<void> {
+  const command = args[0];
+  if (!command || SKIP_COMMANDS.has(command)) return;
+  const broker = getCredential("broker");
+  if (!broker?.baseUrl || !broker.accessToken) return; // opt-in: only when paired
+
+  const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
+  const finishedAt = Date.now();
+  try {
+    await fetch(`${broker.baseUrl.replace(/\/+$/, "")}/api/cli/run`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        command: `${command}${sub}`,
+        status,
+        startedAt,
+        finishedAt,
+        durationMs: finishedAt - startedAt,
+        counts,
+        events: events.length ? events : undefined,
+        error,
+      }),
+      signal: AbortSignal.timeout(4000),
+    });
+  } catch {
+    // Observability is best-effort; never affect the CLI outcome.
+  }
+}

package/src/types.ts

@@ -68,6 +68,14 @@ export type CreateRecordPayload = {
   source: string;
   estCostUsd?: number;
   associateCompanyName?: string;
+  /**
+   * Owner to stamp on the new record (canonical owner id). The connector maps
+   * it to the CRM's owner property (HubSpot `hubspot_owner_id`) at create time
+   * so a lead is never born ownerless. Absent = leave unassigned.
+   */
+  ownerId?: string;
+  /** Audit label for how the owner was chosen (e.g. "fixed", "territory:0"). */
+  assignedBy?: string;
 };
 
 export type AuditFindingSeverity = "info" | "warning" | "critical";