fullstackgtm 0.44.0 → 0.46.0

package/dist/connector.d.ts

@@ -1,3 +1,4 @@
+import { type ProgressEmitter } from "./progress.ts";
 import type { GtmConnector, PatchPlan, PatchPlanRun } from "./types.ts";
 export type ApplyPatchPlanOptions = {
     /**
@@ -24,6 +25,28 @@ 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;
 };
 /**
  * Apply an approved subset of a patch plan through a connector.

package/dist/connector.js

@@ -1,4 +1,5 @@
 import { dedupeKey } from "./dedupe.js";
+import { APPLY_STAGES } from "./progress.js";
 import { requiresHumanInput } from "./rules.js";
 const IRREVERSIBLE_OPERATIONS = new Set(["merge_records", "archive_record"]);
 const IDENTITY_KEY_BY_TYPE = {
@@ -83,6 +84,8 @@ export async function applyPatchPlan(connector, plan, options) {
         throw new Error(`The ${connector.provider} connector is read-only.`);
     }
     const startedAt = new Date().toISOString();
+    const emitStage = (stage) => 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";
     const results = [];
@@ -157,6 +160,7 @@ export async function applyPatchPlan(connector, plan, options) {
                     : "Operation was not approved.",
             });
         }
+        emitStage("results");
         return {
             planId: plan.id,
             provider: connector.provider,
@@ -253,7 +257,48 @@ export async function applyPatchPlan(connector, plan, options) {
                 batched.set(result.operationId, result);
         }
     }
+    // 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);
@@ -342,6 +387,8 @@ export async function applyPatchPlan(connector, plan, options) {
             });
         }
     }
+    notifyProgress();
+    emitStage("results");
     return {
         planId: plan.id,
         provider: connector.provider,

package/dist/connectors/hubspot.d.ts

@@ -1,5 +1,6 @@
 import { type FieldMappings } from "../mappings.ts";
-import type { GtmConnector } from "../types.ts";
+import type { GtmConnector, SnapshotProgress } from "../types.ts";
+import { type ProgressEmitter } from "../progress.ts";
 export type HubspotConnectorOptions = {
     /** Returns a HubSpot access token (private app token or OAuth access token). */
     getAccessToken: () => string | Promise<string>;
@@ -8,6 +9,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;
 };
 /**
  * Reference connector for HubSpot.

package/dist/connectors/hubspot.js

@@ -1,4 +1,5 @@
 import { HUBSPOT_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, readMappedValue, } from "../mappings.js";
+import { SNAPSHOT_PULL_STAGES } from "../progress.js";
 const DEFAULT_API_BASE_URL = "https://api.hubapi.com";
 const OBJECT_PATHS = {
     account: "companies",
@@ -10,6 +11,14 @@ const MAPPING_OBJECT_TYPES = {
     contact: "contacts",
     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 = {
+    user: "owners",
+    account: "accounts",
+    contact: "contacts",
+    deal: "deals",
+};
 /**
  * Reference connector for HubSpot.
  *
@@ -30,6 +39,32 @@ export function createHubspotConnector(options) {
     // 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();
+    // 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();
+    // 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;
+    // Custom deal dedupe properties ensured (or confirmed missing) this run.
+    const ensuredDealProperties = new Map();
+    // 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;
+    const pullProgress = (objectType, fetched) => {
+        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, init = {}) {
         const token = await options.getAccessToken();
         let response;
@@ -89,7 +124,7 @@ export function createHubspotConnector(options) {
         }
         return map;
     }
-    async function list(path) {
+    async function list(path, onPage) {
         const results = [];
         let after;
         const seen = new Set();
@@ -104,12 +139,18 @@ export function createHubspotConnector(options) {
             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;
     }
     async function assembleSnapshot(fetchObjects) {
-        const owners = await list("/crm/v3/owners?limit=100");
+        const owners = await list("/crm/v3/owners?limit=100", (fetched) => pullProgress("user", fetched));
         const users = owners
             .filter((owner) => owner.id)
             .map((owner) => ({
@@ -222,6 +263,8 @@ export function createHubspotConnector(options) {
                 raw: deal,
             };
         });
+        // Deliver any throttled trailing items heartbeat before the pull returns.
+        options.progress?.flush();
         return {
             generatedAt: new Date().toISOString(),
             provider: "hubspot",
@@ -235,7 +278,8 @@ export function createHubspotConnector(options) {
         };
     }
     async function fetchSnapshot() {
-        return assembleSnapshot((objectType, properties, withAssociations) => list(`/crm/v3/objects/${objectType}?limit=100&properties=${properties}${withAssociations ? "&associations=companies" : ""}`));
+        const canonicalType = { companies: "account", contacts: "contact", deals: "deal" };
+        return assembleSnapshot((objectType, properties, withAssociations) => list(`/crm/v3/objects/${objectType}?limit=100&properties=${properties}${withAssociations ? "&associations=companies" : ""}`, (fetched) => pullProgress(canonicalType[objectType], fetched)));
     }
     const MODIFIED_DATE_PROPERTIES = {
         companies: "hs_lastmodifieddate",
@@ -499,12 +543,199 @@ export function createHubspotConnector(options) {
         createdCompaniesByName.set(cacheKey, id);
         return id;
     }
+    /** Exact-value deal lookup (by any searchable property) for resolve-first creates. */
+    async function searchDealsBy(property, value) {
+        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 ?? []).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) {
+        const cached = ensuredDealProperties.get(name);
+        if (cached !== undefined)
+            return cached;
+        let ok;
+        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;
+    }
     /**
-     * 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.
+     * 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) {
+        if (!dealPipelinesCache) {
+            dealPipelinesCache = request("/crm/v3/pipelines/deals").then((data) => (data?.results ?? []));
+            // 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;
+        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) => {
+            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) };
+    }
+    /**
+     * 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, payload, matchValue) {
+        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 = {
+            ...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) {
         const payload = operation.afterValue;
@@ -512,13 +743,16 @@ export function createHubspotConnector(options) {
             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/dist/connectors/hubspotAuth.js

@@ -1,4 +1,3 @@
-import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
 /**
  * HubSpot CLI authentication.
@@ -101,6 +100,11 @@ export async function runHubspotLoopbackLogin(options) {
     const log = options.log ?? ((message) => 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((resolve, reject) => {
         const server = createServer((request, response) => {
             const url = new URL(request.url ?? "/", `http://localhost:${port}`);

package/dist/connectors/linkedin.js

@@ -146,37 +146,37 @@ export function normalizeHeyReachLead(raw) {
 // ── Fake provider (tests / dry-run with no key, no network) ─────────────────
 export const FAKE_LINKEDIN_PROSPECTS = [
     {
-        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/dist/connectors/salesforce.d.ts

@@ -1,5 +1,6 @@
 import { type FieldMappings } from "../mappings.ts";
-import type { GtmConnector } from "../types.ts";
+import type { GtmConnector, SnapshotProgress } from "../types.ts";
+import { type ProgressEmitter } from "../progress.ts";
 export type SalesforceConnection = {
     accessToken: string;
     /** e.g. https://yourorg.my.salesforce.com */
@@ -13,6 +14,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;
 };
 /**
  * Reference connector for Salesforce.

package/dist/connectors/salesforce.js

@@ -1,4 +1,5 @@
 import { SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, readMappedValue, } from "../mappings.js";
+import { SNAPSHOT_PULL_STAGES } from "../progress.js";
 const DEFAULT_API_VERSION = "v59.0";
 const SOBJECT_TYPES = {
     account: "Account",
@@ -16,6 +17,14 @@ const MAPPING_OBJECT_TYPES = {
     contact: "contacts",
     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 = {
+    user: "owners",
+    account: "accounts",
+    contact: "contacts",
+    deal: "deals",
+};
 /**
  * Reference connector for Salesforce.
  *
@@ -116,7 +125,7 @@ export function createSalesforceConnector(options) {
         const text = await response.text();
         return text ? JSON.parse(text) : null;
     }
-    async function query(soql) {
+    async function query(soql, onPage) {
         const records = [];
         let next = `/services/data/${apiVersion}/query?q=${encodeURIComponent(soql)}`;
         const seen = new Set();
@@ -127,6 +136,12 @@ export function createSalesforceConnector(options) {
             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;
@@ -138,7 +153,23 @@ export function createSalesforceConnector(options) {
         return mappedFields(mappings, objectType, SALESFORCE_DEFAULT_FIELD_MAPPINGS[objectType]).join(", ");
     }
     async function assembleSnapshot(whereClause) {
-        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;
+        const progressFor = (objectType) => (fetched) => {
+            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 = sfUsers.map((user) => {
             const id = String(readMapped(user, "owners", "id", "Id"));
             const email = stringOrUndefined(readMapped(user, "owners", "email", "Email"));
@@ -153,7 +184,7 @@ export function createSalesforceConnector(options) {
                 active: Boolean(readMapped(user, "owners", "isActive", "IsActive")),
             };
         });
-        const sfAccounts = await query(`SELECT ${selectFields("accounts")} FROM Account${whereClause}`);
+        const sfAccounts = await query(`SELECT ${selectFields("accounts")} FROM Account${whereClause}`, progressFor("account"));
         const accounts = sfAccounts.map((account) => {
             const id = String(readMapped(account, "accounts", "id", "Id"));
             return {
@@ -170,7 +201,7 @@ export function createSalesforceConnector(options) {
                 raw: account,
             };
         });
-        const sfContacts = await query(`SELECT ${selectFields("contacts")} FROM Contact${whereClause}`);
+        const sfContacts = await query(`SELECT ${selectFields("contacts")} FROM Contact${whereClause}`, progressFor("contact"));
         const contacts = sfContacts.map((contact) => {
             const id = String(readMapped(contact, "contacts", "id", "Id"));
             return {
@@ -188,7 +219,7 @@ export function createSalesforceConnector(options) {
                 raw: contact,
             };
         });
-        const sfOpportunities = await query(`SELECT ${selectFields("deals")} FROM Opportunity${whereClause}`);
+        const sfOpportunities = await query(`SELECT ${selectFields("deals")} FROM Opportunity${whereClause}`, progressFor("deal"));
         const deals = sfOpportunities.map((opportunity) => {
             const id = String(readMapped(opportunity, "deals", "id", "Id"));
             const probability = numberOrUndefined(readMapped(opportunity, "deals", "probability", "Probability"));
@@ -228,6 +259,8 @@ export function createSalesforceConnector(options) {
                 raw: opportunity,
             };
         });
+        // Deliver any throttled trailing items heartbeat before the pull returns.
+        options.progress?.flush();
         return {
             generatedAt: new Date().toISOString(),
             provider: "salesforce",
@@ -444,7 +477,7 @@ export function createSalesforceConnector(options) {
             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) {