fullstackgtm 0.44.0 → 0.46.0

package/src/connector.ts

@@ -1,4 +1,5 @@
 import { dedupeKey } from "./dedupe.ts";
+import { APPLY_STAGES, type ProgressEmitter } from "./progress.ts";
 import { requiresHumanInput } from "./rules.ts";
 import type {
   CanonicalGtmSnapshot,
@@ -105,6 +106,29 @@ export type ApplyPatchPlanOptions = {
    * edited mid-apply is conflicted out instead of overwritten. Default 25.
    */
   recheckEvery?: number;
+  /**
+   * Per-operation progress as the run executes (presentation only — a
+   * throwing callback never affects the run). `completed` counts every
+   * resolved operation including skips and conflicts; `total` is the plan's
+   * full operation count.
+   */
+  onOperation?: (progress: ApplyProgress) => void;
+  /**
+   * Shared progress vocabulary (src/progress.ts): the run emits the
+   * APPLY_STAGES (preflight → operations → results), one `opResult` per
+   * resolved operation (id + status only — no values), and `items` over the
+   * plan's operations. Additive alongside `onOperation`; presentation only.
+   */
+  progress?: ProgressEmitter;
+};
+
+export type ApplyProgress = {
+  completed: number;
+  total: number;
+  applied: number;
+  failed: number;
+  conflicts: number;
+  skipped: number;
 };
 
 const FIELD_WRITE_OPERATIONS = new Set(["set_field", "clear_field", "link_record"]);
@@ -132,6 +156,9 @@ export async function applyPatchPlan(
   }
 
   const startedAt = new Date().toISOString();
+  const emitStage = (stage: (typeof APPLY_STAGES)[number]) =>
+    options.progress?.stage(stage, APPLY_STAGES.indexOf(stage), APPLY_STAGES.length);
+  emitStage("preflight");
   const approved = new Set(options.approvedOperationIds);
   const checkConflicts =
     options.checkConflicts ?? typeof connector.readField === "function";
@@ -208,6 +235,7 @@ export async function applyPatchPlan(
           : "Operation was not approved.",
       });
     }
+    emitStage("results");
     return {
       planId: plan.id,
       provider: connector.provider,
@@ -313,7 +341,43 @@ export async function applyPatchPlan(
     }
   }
 
+  // Progress ticker state: every loop iteration below pushes at most one
+  // result; `lastNotified` guards the rare early-throw path so an iteration
+  // that pushed nothing reports nothing.
+  const progressCounts = { applied: 0, failed: 0, conflicts: 0, skipped: 0 };
+  const resultsBefore = results.length;
+  let lastNotified = results.length;
+  const notifyProgress = () => {
+    if ((!options.onOperation && !options.progress) || results.length === lastNotified) return;
+    lastNotified = results.length;
+    const last = results[results.length - 1];
+    if (last.status === "applied") progressCounts.applied += 1;
+    else if (last.status === "failed") progressCounts.failed += 1;
+    else if (last.status === "conflict") progressCounts.conflicts += 1;
+    else progressCounts.skipped += 1;
+    // Shared vocabulary: operation id + status only — a conflict/failure
+    // detail can echo field values, which never leave the machine.
+    options.progress?.opResult(last.operationId, last.status);
+    options.progress?.items(results.length - resultsBefore, plan.operations.length);
+    if (options.onOperation) {
+      try {
+        options.onOperation({
+          completed: results.length - resultsBefore,
+          total: plan.operations.length,
+          ...progressCounts,
+        });
+      } catch {
+        // progress is presentation-only
+      }
+    }
+  };
+
+  emitStage("operations");
   for (const operation of plan.operations) {
+    // Report the previous iteration's result (guarded: no-op if it pushed
+    // nothing). One-iteration lag keeps this a two-line hook instead of a
+    // notify after all ten push sites; the loop-exit call below flushes the last.
+    notifyProgress();
     const batchedResult = batched.get(operation.id);
     if (batchedResult) {
       results.push(batchedResult);
@@ -403,6 +467,8 @@ export async function applyPatchPlan(
       });
     }
   }
+  notifyProgress();
+  emitStage("results");
 
   return {
     planId: plan.id,

package/src/connectors/hubspot.ts

@@ -18,7 +18,9 @@ import type {
   GtmObjectType,
   PatchOperation,
   PatchOperationResult,
+  SnapshotProgress,
 } from "../types.ts";
+import { SNAPSHOT_PULL_STAGES, type ProgressEmitter } from "../progress.ts";
 
 const DEFAULT_API_BASE_URL = "https://api.hubapi.com";
 
@@ -30,6 +32,14 @@ export type HubspotConnectorOptions = {
   apiBaseUrl?: string;
   /** Injectable fetch for testing. */
   fetchImpl?: typeof fetch;
+  /** Per-page snapshot-pull progress (presentation only — errors are swallowed). */
+  onProgress?: (progress: SnapshotProgress) => void;
+  /**
+   * Shared progress vocabulary (src/progress.ts): the snapshot pull emits a
+   * `stage` per object type and an `items` heartbeat per page. Additive
+   * alongside the legacy `onProgress` callback; both are presentation-only.
+   */
+  progress?: ProgressEmitter;
 };
 
 const OBJECT_PATHS: Partial<Record<GtmObjectType, string>> = {
@@ -44,6 +54,15 @@ const MAPPING_OBJECT_TYPES: Partial<Record<GtmObjectType, Exclude<CrmObjectType,
   deal: "deals",
 };
 
+// SnapshotProgress object types → the shared SNAPSHOT_PULL_STAGES names, so
+// the CLI checklist and the app StageTimeline read the same stage labels.
+const PULL_STAGE_BY_TYPE: Record<SnapshotProgress["objectType"], (typeof SNAPSHOT_PULL_STAGES)[number]> = {
+  user: "owners",
+  account: "accounts",
+  contact: "contacts",
+  deal: "deals",
+};
+
 /**
  * Reference connector for HubSpot.
  *
@@ -64,6 +83,32 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   // match value (email): HubSpot search is eventually consistent, so a contact
   // created earlier in this apply run is invisible to a later search.
   const createdContactsByMatch = new Map<string, string>();
+  // Same-run dedup for `create_record` deal creates, keyed by
+  // matchKey:matchValue (e.g. stripe_invoice_id:in_123) — same
+  // eventual-consistency rationale as the contact cache.
+  const createdDealsByMatch = new Map<string, string>();
+  // One /crm/v3/pipelines/deals read per connector lifetime (one apply run):
+  // pipeline/stage metadata doesn't change mid-run, and deal creates resolve
+  // the closed-won stage from it per operation.
+  let dealPipelinesCache: Promise<any[]> | undefined;
+  // Custom deal dedupe properties ensured (or confirmed missing) this run.
+  const ensuredDealProperties = new Map<string, boolean>();
+
+  // Per-page snapshot-pull progress: the legacy onProgress callback plus the
+  // shared emitter (stage on the first page of each object type, items per
+  // page). Both are presentation-only — callers already swallow errors.
+  let lastPullStage: string | undefined;
+  const pullProgress = (objectType: SnapshotProgress["objectType"], fetched: number) => {
+    options.onProgress?.({ objectType, fetched });
+    const emitter = options.progress;
+    if (!emitter) return;
+    const stage = PULL_STAGE_BY_TYPE[objectType];
+    if (stage !== lastPullStage) {
+      lastPullStage = stage;
+      emitter.stage(stage, SNAPSHOT_PULL_STAGES.indexOf(stage), SNAPSHOT_PULL_STAGES.length);
+    }
+    emitter.items(fetched);
+  };
 
   async function request(path: string, init: RequestInit = {}): Promise<any> {
     const token = await options.getAccessToken();
@@ -123,7 +168,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     return map;
   }
 
-  async function list(path: string): Promise<any[]> {
+  async function list(path: string, onPage?: (fetched: number) => void): Promise<any[]> {
     const results: any[] = [];
     let after: string | undefined;
     const seen = new Set<string>();
@@ -137,6 +182,11 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       const separator = path.includes("?") ? "&" : "?";
       const data = await request(`${path}${after ? `${separator}after=${encodeURIComponent(after)}` : ""}`);
       results.push(...(data.results ?? []));
+      try {
+        onPage?.(results.length);
+      } catch {
+        // progress is presentation-only; never let it fail a pull
+      }
       after = data.paging?.next?.after;
     } while (after);
     return results;
@@ -149,7 +199,9 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       withAssociations: boolean,
     ) => Promise<any[]>,
   ): Promise<CanonicalGtmSnapshot> {
-    const owners = await list("/crm/v3/owners?limit=100");
+    const owners = await list("/crm/v3/owners?limit=100", (fetched) =>
+      pullProgress("user", fetched),
+    );
     const users: CanonicalUser[] = owners
       .filter((owner) => owner.id)
       .map((owner) => ({
@@ -296,6 +348,9 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
         };
       });
 
+    // Deliver any throttled trailing items heartbeat before the pull returns.
+    options.progress?.flush();
+
     return {
       generatedAt: new Date().toISOString(),
       provider: "hubspot",
@@ -310,9 +365,11 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   }
 
   async function fetchSnapshot(): Promise<CanonicalGtmSnapshot> {
+    const canonicalType = { companies: "account", contacts: "contact", deals: "deal" } as const;
     return assembleSnapshot((objectType, properties, withAssociations) =>
       list(
         `/crm/v3/objects/${objectType}?limit=100&properties=${properties}${withAssociations ? "&associations=companies" : ""}`,
+        (fetched) => pullProgress(canonicalType[objectType], fetched),
       ),
     );
   }
@@ -597,12 +654,215 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     return id;
   }
 
+  /** Exact-value deal lookup (by any searchable property) for resolve-first creates. */
+  async function searchDealsBy(property: string, value: string): Promise<string[]> {
+    const data = await request(`/crm/v3/objects/deals/search`, {
+      method: "POST",
+      body: JSON.stringify({
+        filterGroups: [{ filters: [{ propertyName: property, operator: "EQ", value }] }],
+        properties: [property],
+        limit: 3,
+      }),
+    });
+    return ((data?.results ?? []) as Array<{ id: string }>).map((row) => String(row.id));
+  }
+
+  /**
+   * Make sure the deal dedupe property (e.g. "stripe_invoice_id") exists so
+   * both the resolve-first search and the stamped value are real. Best-effort
+   * create on a confirmed miss; returns false when the property can neither
+   * be read nor created — the caller must SKIP then (creating a deal without
+   * its dedupe key would make every replay a duplicate).
+   */
+  async function ensureDealProperty(name: string): Promise<boolean> {
+    const cached = ensuredDealProperties.get(name);
+    if (cached !== undefined) return cached;
+    let ok: boolean;
+    try {
+      await request(`/crm/v3/properties/deals/${encodeURIComponent(name)}`);
+      ok = true;
+    } catch {
+      // Missing (404) or unreadable — try to create it; a failure here means
+      // we cannot guarantee the dedupe key, so report false.
+      try {
+        await request(`/crm/v3/properties/deals`, {
+          method: "POST",
+          body: JSON.stringify({
+            name,
+            label: name,
+            type: "string",
+            fieldType: "text",
+            groupName: "dealinformation",
+            hasUniqueValue: false,
+          }),
+        });
+        ok = true;
+      } catch {
+        ok = false;
+      }
+    }
+    ensuredDealProperties.set(name, ok);
+    return ok;
+  }
+
+  /**
+   * Resolve the target pipeline and its closed-won stage from the portal's
+   * own pipeline metadata (one read per run). The pipeline is picked by id or
+   * case-insensitive label (`hint`), else the default (lowest displayOrder);
+   * the closed-won stage is the one whose metadata says isClosed with
+   * probability 1 — NEVER a substring guess against stage names. Returns null
+   * when either is unresolvable so the caller skips instead of guessing.
+   */
+  async function resolveClosedWonStage(
+    hint: string | undefined,
+  ): Promise<{ pipelineId: string; stageId: string } | null> {
+    if (!dealPipelinesCache) {
+      dealPipelinesCache = request("/crm/v3/pipelines/deals").then(
+        (data) => (data?.results ?? []) as any[],
+      );
+      // A failed read must not poison the cache for the rest of the run.
+      dealPipelinesCache = dealPipelinesCache.catch(() => []);
+    }
+    const pipelines = await dealPipelinesCache;
+    if (pipelines.length === 0) return null;
+    let pipeline: any | undefined;
+    if (hint) {
+      const wanted = hint.trim().toLowerCase();
+      pipeline = pipelines.find(
+        (candidate) =>
+          String(candidate?.id ?? "").toLowerCase() === wanted ||
+          String(candidate?.label ?? "").trim().toLowerCase() === wanted,
+      );
+      if (!pipeline) return null; // an explicit hint that matches nothing is an error, not "use default"
+    } else {
+      pipeline = [...pipelines].sort(
+        (a, b) => Number(a?.displayOrder ?? 0) - Number(b?.displayOrder ?? 0),
+      )[0];
+    }
+    if (!pipeline?.id) return null;
+    const stage = (pipeline.stages ?? []).find((candidate: any) => {
+      const meta = candidate?.metadata ?? {};
+      return (
+        candidate?.id &&
+        String(meta.isClosed).toLowerCase() === "true" &&
+        Number(meta.probability) === 1
+      );
+    });
+    if (!stage) return null;
+    return { pipelineId: String(pipeline.id), stageId: String(stage.id) };
+  }
+
   /**
-   * Create a NET-NEW record (a sourced lead). Resolve-first: re-checks the
-   * dedupe key against the live CRM (the plan-time snapshot can be stale) and
-   * creates ONLY on a confirmed miss — a record a concurrent writer already
-   * added is returned as `skipped`, never duplicated. Contacts can be linked
-   * to a resolved-or-created company in the same step.
+   * Deal branch of create_record (backfill: one closed-won deal per paid
+   * invoice). Resolve-first on the custom dedupe property (ensured to exist
+   * first), stage resolved from pipeline metadata, company association
+   * best-effort — same contract as the contact branch.
+   */
+  async function createDealRecord(
+    operation: PatchOperation,
+    payload: CreateRecordPayload,
+    matchValue: string,
+  ): Promise<PatchOperationResult> {
+    const matchKey = String(payload.matchKey ?? "").trim();
+    if (!matchKey) {
+      return { operationId: operation.id, status: "skipped", detail: "create_record for deals needs a matchKey (the dedupe property, e.g. stripe_invoice_id)." };
+    }
+    const dedupeKey = `${matchKey}:${matchValue.toLowerCase()}`;
+    const alreadyCreated = createdDealsByMatch.get(dedupeKey);
+    if (alreadyCreated) {
+      return { operationId: operation.id, status: "skipped", detail: `Deal ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: alreadyCreated, existing: true } };
+    }
+
+    // The dedupe property is usually CUSTOM — ensure it exists before the
+    // search; searching a property HubSpot doesn't have 400s, and creating a
+    // deal without the key stamped would defeat every future resolve-first.
+    const propertyOk = await ensureDealProperty(matchKey);
+    if (!propertyOk) {
+      return { operationId: operation.id, status: "skipped", detail: `Deal dedupe property "${matchKey}" does not exist and could not be created; refusing to create a deal without its dedupe key.` };
+    }
+
+    const existing = await searchDealsBy(matchKey, matchValue);
+    if (existing.length > 0) {
+      createdDealsByMatch.set(dedupeKey, existing[0]);
+      return { operationId: operation.id, status: "skipped", detail: `Deal ${matchKey}=${matchValue} already exists (${existing.join(", ")}); resolve-first declined to create.`, providerData: { id: existing[0], existing: true } };
+    }
+
+    // Stage: only the provider-neutral "closed_won" sentinel is understood,
+    // and it must resolve to a real stage id from pipeline metadata.
+    if (payload.dealStage !== "closed_won") {
+      return { operationId: operation.id, status: "skipped", detail: 'create_record for deals needs dealStage "closed_won" (the connector resolves the real stage id from pipeline metadata).' };
+    }
+    const resolved = await resolveClosedWonStage(payload.dealPipeline);
+    if (!resolved) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: payload.dealPipeline
+          ? `Could not resolve pipeline "${payload.dealPipeline}" (by id or label) to a closed-won stage; not guessing a stage.`
+          : "Could not resolve the default deal pipeline's closed-won stage (isClosed + probability 1) from pipeline metadata; not guessing a stage.",
+      };
+    }
+
+    const properties: Record<string, string> = {
+      ...payload.properties,
+      [matchKey]: matchValue,
+      pipeline: resolved.pipelineId,
+      dealstage: resolved.stageId,
+    };
+    if (payload.ownerId && !properties.hubspot_owner_id) {
+      properties.hubspot_owner_id = String(payload.ownerId);
+    }
+    let created;
+    try {
+      created = await request(`/crm/v3/objects/deals`, {
+        method: "POST",
+        body: JSON.stringify({ properties: { ...properties, hs_object_source_detail_2: `fullstackgtm backfill (${operation.id})` } }),
+      });
+    } catch {
+      // Some portals reject writes to source-detail properties — the provenance
+      // stamp is best-effort, the create is not.
+      created = await request(`/crm/v3/objects/deals`, {
+        method: "POST",
+        body: JSON.stringify({ properties }),
+      });
+    }
+    const dealId = String(created.id);
+    createdDealsByMatch.set(dedupeKey, dealId);
+
+    let companyNote = "";
+    if (payload.associateCompanyName) {
+      try {
+        const companyId = await resolveOrCreateCompany(payload.associateCompanyName, payload.associateCompanyDomain, operation.id);
+        if (companyId) {
+          await request(
+            `/crm/v4/objects/deals/${encodeURIComponent(dealId)}/associations/default/companies/${encodeURIComponent(companyId)}`,
+            { method: "PUT" },
+          );
+          const domainNote = payload.associateCompanyDomain ? ` (${payload.associateCompanyDomain})` : "";
+          companyNote = ` Linked to company "${payload.associateCompanyName}"${domainNote} (${companyId}).`;
+        } else {
+          companyNote = ` Company "${payload.associateCompanyName}" was ambiguous; left unlinked.`;
+        }
+      } catch (error) {
+        // Association is best-effort — the deal create already succeeded.
+        companyNote = ` (company link failed: ${error instanceof Error ? error.message : String(error)})`;
+      }
+    }
+    return {
+      operationId: operation.id,
+      status: "applied",
+      detail: `Created deal ${matchKey}=${matchValue} (${dealId}) in stage ${resolved.stageId}.${companyNote}`,
+      providerData: { id: dealId, created: true, pipelineId: resolved.pipelineId, stageId: resolved.stageId },
+    };
+  }
+
+  /**
+   * Create a NET-NEW record (a sourced lead, or a backfilled deal).
+   * Resolve-first: re-checks the dedupe key against the live CRM (the
+   * plan-time snapshot can be stale) and creates ONLY on a confirmed miss — a
+   * record a concurrent writer already added is returned as `skipped`, never
+   * duplicated. Contacts and deals can be linked to a resolved-or-created
+   * company in the same step.
    */
   async function createRecord(operation: PatchOperation): Promise<PatchOperationResult> {
     const payload = operation.afterValue as CreateRecordPayload | undefined;
@@ -610,14 +870,18 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       return { operationId: operation.id, status: "skipped", detail: "create_record needs a CreateRecordPayload afterValue." };
     }
     const objectPath = OBJECT_PATHS[operation.objectType];
-    if (operation.objectType !== "contact" && operation.objectType !== "account") {
-      return { operationId: operation.id, status: "skipped", detail: "create_record supports contacts and accounts." };
+    if (operation.objectType !== "contact" && operation.objectType !== "account" && operation.objectType !== "deal") {
+      return { operationId: operation.id, status: "skipped", detail: "create_record supports contacts, accounts, and deals." };
     }
     const matchValue = String(payload.matchValue ?? "").trim();
     if (!matchValue) {
       return { operationId: operation.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." };
     }
 
+    if (operation.objectType === "deal") {
+      return createDealRecord(operation, payload, matchValue);
+    }
+
     if (operation.objectType === "account") {
       const id = await resolveOrCreateCompany(matchValue, stringOrUndefined(payload.properties?.domain), operation.id);
       if (id === null) {

package/src/connectors/hubspotAuth.ts

@@ -1,4 +1,3 @@
-import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
 
 /**
@@ -153,6 +152,11 @@ export async function runHubspotLoopbackLogin(
   const log = options.log ?? ((message: string) => console.error(message));
   const redirectUri = `http://localhost:${port}/callback`;
   const state = randomBytes(16).toString("hex");
+  // Deferred: `node:http` transitively compiles node's bundled undici on
+  // import (~10ms+, 12% of a demo-audit run's CPU profile). This module is in
+  // the eager graph of every CLI invocation via help.ts/auth.ts, but the
+  // server is only needed during the interactive OAuth loopback login.
+  const { createServer } = await import("node:http");
 
   const code = await new Promise<string>((resolve, reject) => {
     const server = createServer((request, response) => {

package/src/connectors/linkedin.ts

@@ -212,37 +212,37 @@ export function normalizeHeyReachLead(raw: any): LinkedInProspect {
 
 export const FAKE_LINKEDIN_PROSPECTS: LinkedInProspect[] = [
   {
-    firstName: "Dana",
-    lastName: "Okafor",
-    fullName: "Dana Okafor",
+    firstName: "Example",
+    lastName: "ProspectAlpha",
+    fullName: "Example Prospect Alpha",
     headline: "VP RevOps",
     jobTitle: "VP Revenue Operations",
     company: "Northwind Logistics",
-    profileUrl: "https://www.linkedin.com/in/dana-okafor",
+    profileUrl: "https://example.com/linkedin/example-prospect-alpha",
     location: "Chicago, IL",
-    email: "dana@northwind.example",
+    email: "prospect.alpha@example.com",
     emailStatus: "verified",
   },
   {
-    firstName: "Priya",
-    lastName: "Raman",
-    fullName: "Priya Raman",
+    firstName: "Example",
+    lastName: "ProspectBeta",
+    fullName: "Example Prospect Beta",
     headline: "Head of Sales Ops",
     jobTitle: "Head of Sales Operations",
     company: "Cobalt Health",
-    profileUrl: "https://www.linkedin.com/in/priya-raman",
+    profileUrl: "https://example.com/linkedin/example-prospect-beta",
     location: "Austin, TX",
   },
   {
-    firstName: "Marco",
-    lastName: "Bianchi",
-    fullName: "Marco Bianchi",
+    firstName: "Example",
+    lastName: "ProspectGamma",
+    fullName: "Example Prospect Gamma",
     headline: "RevOps Manager",
     jobTitle: "Revenue Operations Manager",
     company: "Ferro Systems",
-    profileUrl: "https://www.linkedin.com/in/marco-bianchi",
+    profileUrl: "https://example.com/linkedin/example-prospect-gamma",
     location: "Remote",
-    email: "marco@ferro.example",
+    email: "prospect.gamma@example.com",
     emailStatus: "guessed",
   },
 ];

package/src/connectors/salesforce.ts

@@ -17,7 +17,9 @@ import type {
   GtmObjectType,
   PatchOperation,
   PatchOperationResult,
+  SnapshotProgress,
 } from "../types.ts";
+import { SNAPSHOT_PULL_STAGES, type ProgressEmitter } from "../progress.ts";
 
 const DEFAULT_API_VERSION = "v59.0";
 
@@ -35,6 +37,14 @@ export type SalesforceConnectorOptions = {
   apiVersion?: string;
   /** Injectable fetch for testing. */
   fetchImpl?: typeof fetch;
+  /** Per-page snapshot-pull progress (presentation only — errors are swallowed). */
+  onProgress?: (progress: SnapshotProgress) => void;
+  /**
+   * Shared progress vocabulary (src/progress.ts): the snapshot pull emits a
+   * `stage` per object type and an `items` heartbeat per page. Additive
+   * alongside the legacy `onProgress` callback; both are presentation-only.
+   */
+  progress?: ProgressEmitter;
 };
 
 const SOBJECT_TYPES: Partial<Record<GtmObjectType, string>> = {
@@ -56,6 +66,15 @@ const MAPPING_OBJECT_TYPES: Partial<Record<GtmObjectType, Exclude<CrmObjectType,
   deal: "deals",
 };
 
+// SnapshotProgress object types → the shared SNAPSHOT_PULL_STAGES names, so
+// the CLI checklist and the app StageTimeline read the same stage labels.
+const PULL_STAGE_BY_TYPE: Record<SnapshotProgress["objectType"], (typeof SNAPSHOT_PULL_STAGES)[number]> = {
+  user: "owners",
+  account: "accounts",
+  contact: "contacts",
+  deal: "deals",
+};
+
 /**
  * Reference connector for Salesforce.
  *
@@ -161,7 +180,7 @@ export function createSalesforceConnector(
     return text ? JSON.parse(text) : null;
   }
 
-  async function query(soql: string): Promise<any[]> {
+  async function query(soql: string, onPage?: (fetched: number) => void): Promise<any[]> {
     const records: any[] = [];
     let next: string | undefined = `/services/data/${apiVersion}/query?q=${encodeURIComponent(soql)}`;
     const seen = new Set<string>();
@@ -171,6 +190,11 @@ export function createSalesforceConnector(
       seen.add(next);
       const data = await request(next);
       records.push(...(data?.records ?? []));
+      try {
+        onPage?.(records.length);
+      } catch {
+        // progress is presentation-only; never let it fail a pull
+      }
       next = data?.nextRecordsUrl ?? undefined;
     }
     return records;
@@ -194,7 +218,25 @@ export function createSalesforceConnector(
   }
 
   async function assembleSnapshot(whereClause: string): Promise<CanonicalGtmSnapshot> {
-    const sfUsers = await query(`SELECT ${selectFields("owners")} FROM User${whereClause}`);
+    // Per-page snapshot-pull progress: the legacy onProgress callback plus the
+    // shared emitter (stage on the first page of each object type, items per
+    // page). Both are presentation-only — `query` already swallows errors.
+    let lastPullStage: string | undefined;
+    const progressFor = (objectType: SnapshotProgress["objectType"]) => (fetched: number) => {
+      options.onProgress?.({ objectType, fetched });
+      const emitter = options.progress;
+      if (!emitter) return;
+      const stage = PULL_STAGE_BY_TYPE[objectType];
+      if (stage !== lastPullStage) {
+        lastPullStage = stage;
+        emitter.stage(stage, SNAPSHOT_PULL_STAGES.indexOf(stage), SNAPSHOT_PULL_STAGES.length);
+      }
+      emitter.items(fetched);
+    };
+    const sfUsers = await query(
+      `SELECT ${selectFields("owners")} FROM User${whereClause}`,
+      progressFor("user"),
+    );
     const users: CanonicalUser[] = sfUsers.map((user) => {
       const id = String(readMapped(user, "owners", "id", "Id"));
       const email = stringOrUndefined(readMapped(user, "owners", "email", "Email"));
@@ -212,6 +254,7 @@ export function createSalesforceConnector(
 
     const sfAccounts = await query(
       `SELECT ${selectFields("accounts")} FROM Account${whereClause}`,
+      progressFor("account"),
     );
     const accounts: CanonicalAccount[] = sfAccounts.map((account) => {
       const id = String(readMapped(account, "accounts", "id", "Id"));
@@ -236,6 +279,7 @@ export function createSalesforceConnector(
 
     const sfContacts = await query(
       `SELECT ${selectFields("contacts")} FROM Contact${whereClause}`,
+      progressFor("contact"),
     );
     const contacts: CanonicalContact[] = sfContacts.map((contact) => {
       const id = String(readMapped(contact, "contacts", "id", "Id"));
@@ -257,6 +301,7 @@ export function createSalesforceConnector(
 
     const sfOpportunities = await query(
       `SELECT ${selectFields("deals")} FROM Opportunity${whereClause}`,
+      progressFor("deal"),
     );
     const deals: CanonicalDeal[] = sfOpportunities.map((opportunity) => {
       const id = String(readMapped(opportunity, "deals", "id", "Id"));
@@ -306,6 +351,9 @@ export function createSalesforceConnector(
       };
     });
 
+    // Deliver any throttled trailing items heartbeat before the pull returns.
+    options.progress?.flush();
+
     return {
       generatedAt: new Date().toISOString(),
       provider: "salesforce",
@@ -550,7 +598,7 @@ export function createSalesforceConnector(
       return { operationId: operation.id, status: "skipped", detail: "create_record needs a CreateRecordPayload afterValue." };
     }
     if (operation.objectType !== "contact" && operation.objectType !== "account") {
-      return { operationId: operation.id, status: "skipped", detail: "create_record supports contacts and accounts." };
+      return { operationId: operation.id, status: "skipped", detail: "create_record supports contacts and accounts on Salesforce (deal/Opportunity creation is HubSpot-only for now)." };
     }
     const matchValue = String(payload.matchValue ?? "").trim();
     if (!matchValue) {