fullstackgtm 0.45.0 → 0.47.0

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;
@@ -115,7 +150,7 @@ export function createHubspotConnector(options) {
         return results;
     }
     async function assembleSnapshot(fetchObjects) {
-        const owners = await list("/crm/v3/owners?limit=100", (fetched) => options.onProgress?.({ objectType: "user", fetched }));
+        const owners = await list("/crm/v3/owners?limit=100", (fetched) => pullProgress("user", fetched));
         const users = owners
             .filter((owner) => owner.id)
             .map((owner) => ({
@@ -228,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",
@@ -242,7 +279,7 @@ export function createHubspotConnector(options) {
     }
     async function fetchSnapshot() {
         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) => options.onProgress?.({ objectType: canonicalType[objectType], fetched })));
+        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",
@@ -506,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;
@@ -519,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) {
@@ -830,6 +1057,173 @@ export function createHubspotConnector(options) {
             detail: `Archived ${objectPath}/${operation.objectId}.`,
         };
     }
+    function fieldMapping(operation) {
+        const objectPath = OBJECT_PATHS[operation.objectType];
+        const mappingType = MAPPING_OBJECT_TYPES[operation.objectType];
+        if (!objectPath || !mappingType || !operation.field)
+            return null;
+        const defaults = HUBSPOT_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+        return { objectPath, property: mappedField(mappings, mappingType, operation.field, defaults[operation.field] ?? operation.field) };
+    }
+    function normalizeHubspotReadValue(field, value) {
+        if (field === "closeDate" && typeof value === "string")
+            return value.split("T")[0];
+        return value ?? null;
+    }
+    function normalizeForComparison(value) {
+        if (value === undefined || value === null || value === "")
+            return null;
+        return String(value);
+    }
+    function batchErrorIds(error) {
+        const context = error?.context ?? {};
+        const ids = context.ids ?? context.id ?? error?.id ?? error?.objectId;
+        if (Array.isArray(ids))
+            return ids.map(String);
+        if (ids !== undefined && ids !== null)
+            return [String(ids)];
+        return [];
+    }
+    function batchErrorDetail(error) {
+        const category = error?.category ? `${String(error.category)}: ` : "";
+        return `${category}${String(error?.message ?? "HubSpot batch row failed.")}`;
+    }
+    async function applySetFieldBatch(operations) {
+        const out = new Map();
+        const mapped = operations.map((operation) => ({ operation, mapping: fieldMapping(operation) }));
+        for (const item of mapped) {
+            if (!item.mapping) {
+                out.set(item.operation.id, {
+                    operationId: item.operation.id,
+                    status: "skipped",
+                    detail: "Field writes are only supported for accounts, contacts, and deals with an explicit field.",
+                });
+            }
+        }
+        const clean = mapped.filter((item) => Boolean(item.mapping));
+        if (clean.length === 0)
+            return operations.map((operation) => out.get(operation.id));
+        const objectPath = clean[0].mapping.objectPath;
+        const properties = [...new Set(clean.map((item) => item.mapping.property))];
+        const liveById = new Map();
+        const ids = [...new Set(clean.map((item) => item.operation.objectId))];
+        for (let i = 0; i < ids.length; i += 100) {
+            const chunkIds = ids.slice(i, i + 100);
+            const data = await request(`/crm/v3/objects/${objectPath}/batch/read`, {
+                method: "POST",
+                body: JSON.stringify({ properties, inputs: chunkIds.map((id) => ({ id })) }),
+            });
+            for (const row of data?.results ?? []) {
+                if (row?.id)
+                    liveById.set(String(row.id), row.properties ?? {});
+            }
+        }
+        const toWrite = [];
+        for (const { operation, mapping } of clean) {
+            const props = liveById.get(operation.objectId);
+            const current = normalizeHubspotReadValue(operation.field, props?.[mapping.property] ?? null);
+            const expected = normalizeForComparison(operation.beforeValue);
+            const found = normalizeForComparison(current);
+            if (!props || expected !== found) {
+                out.set(operation.id, {
+                    operationId: operation.id,
+                    status: "conflict",
+                    detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
+                    providerData: { currentValue: current ?? null },
+                });
+                continue;
+            }
+            toWrite.push({ operation, property: mapping.property });
+        }
+        for (let i = 0; i < toWrite.length; i += 100) {
+            const chunk = toWrite.slice(i, i + 100);
+            let data;
+            try {
+                data = await request(`/crm/v3/objects/${objectPath}/batch/update`, {
+                    method: "POST",
+                    body: JSON.stringify({
+                        inputs: chunk.map(({ operation, property }) => ({
+                            id: operation.objectId,
+                            properties: { [property]: operation.operation === "clear_field" ? "" : String(operation.afterValue ?? "") },
+                        })),
+                    }),
+                });
+            }
+            catch (error) {
+                for (const { operation } of chunk)
+                    out.set(operation.id, { operationId: operation.id, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+                continue;
+            }
+            const opByObjectId = new Map(chunk.map(({ operation }) => [operation.objectId, operation]));
+            for (const error of data?.errors ?? []) {
+                for (const id of batchErrorIds(error)) {
+                    const operation = opByObjectId.get(id);
+                    if (operation)
+                        out.set(operation.id, { operationId: operation.id, status: "failed", detail: batchErrorDetail(error) });
+                }
+            }
+            for (const result of data?.results ?? []) {
+                const operation = opByObjectId.get(String(result?.id));
+                if (operation && !out.has(operation.id))
+                    out.set(operation.id, { operationId: operation.id, status: "applied", detail: `Set ${chunk.find((item) => item.operation.id === operation.id)?.property ?? "field"} on ${objectPath}/${operation.objectId}.`, providerData: { id: result?.id } });
+            }
+            for (const { operation, property } of chunk) {
+                if (!out.has(operation.id))
+                    out.set(operation.id, { operationId: operation.id, status: "applied", detail: `Set ${property} on ${objectPath}/${operation.objectId}.` });
+            }
+        }
+        return operations.map((operation) => out.get(operation.id) ?? { operationId: operation.id, status: "failed", detail: "Batch update did not process this operation." });
+    }
+    async function applyArchiveBatch(operations) {
+        const objectPath = OBJECT_PATHS[operations[0]?.objectType];
+        if (!objectPath)
+            return operations.map((operation) => ({ operationId: operation.id, status: "skipped", detail: "archive_record is supported for accounts, contacts, and deals." }));
+        const out = new Map();
+        for (let i = 0; i < operations.length; i += 100) {
+            const chunk = operations.slice(i, i + 100);
+            let data;
+            try {
+                data = await request(`/crm/v3/objects/${objectPath}/batch/archive`, {
+                    method: "POST",
+                    body: JSON.stringify({ inputs: chunk.map((operation) => ({ id: operation.objectId })) }),
+                });
+            }
+            catch (error) {
+                for (const operation of chunk)
+                    out.set(operation.id, { operationId: operation.id, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+                continue;
+            }
+            const opByObjectId = new Map(chunk.map((operation) => [operation.objectId, operation]));
+            for (const error of data?.errors ?? []) {
+                for (const id of batchErrorIds(error)) {
+                    const operation = opByObjectId.get(id);
+                    if (operation)
+                        out.set(operation.id, { operationId: operation.id, status: "failed", detail: batchErrorDetail(error) });
+                }
+            }
+            for (const result of data?.results ?? []) {
+                const operation = opByObjectId.get(String(result?.id));
+                if (operation && !out.has(operation.id))
+                    out.set(operation.id, { operationId: operation.id, status: "applied", detail: `Archived ${objectPath}/${operation.objectId}.` });
+            }
+            for (const operation of chunk) {
+                if (!out.has(operation.id))
+                    out.set(operation.id, { operationId: operation.id, status: "applied", detail: `Archived ${objectPath}/${operation.objectId}.` });
+            }
+        }
+        return operations.map((operation) => out.get(operation.id) ?? { operationId: operation.id, status: "failed", detail: "Batch archive did not process this operation." });
+    }
+    async function applyBatch(operations) {
+        if (operations.length === 0)
+            return [];
+        if (operations.every((operation) => (operation.operation === "set_field" || operation.operation === "clear_field") && operation.objectType === operations[0].objectType)) {
+            return applySetFieldBatch(operations);
+        }
+        if (operations.every((operation) => operation.operation === "archive_record" && operation.objectType === operations[0].objectType)) {
+            return applyArchiveBatch(operations);
+        }
+        return operations.map((operation) => ({ operationId: operation.id, status: "skipped", detail: "This mixed operation batch is not supported." }));
+    }
     /**
      * Merge a duplicate group into the approved survivor via HubSpot's v3
      * merge API (supported for contacts, companies, deals, and tickets).
@@ -955,10 +1349,7 @@ export function createHubspotConnector(options) {
         // single-object read here returns HubSpot's raw "2026-03-07T00:00:00Z", which
         // made compare-and-set see a spurious drift and refuse every date-field write.
         // Mirror the snapshot's normalization so the comparison is apples-to-apples.
-        if (field === "closeDate" && typeof value === "string") {
-            return value.split("T")[0];
-        }
-        return value;
+        return normalizeHubspotReadValue(field, value);
     }
     return {
         provider: "hubspot",
@@ -966,6 +1357,8 @@ export function createHubspotConnector(options) {
         fetchChanges,
         applyOperation,
         applyCreateContactsBatch,
+        applyBatch,
+        applyBatchLimit: 100,
         readField,
     };
 }

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, SnapshotProgress } from "../types.ts";
+import { type ProgressEmitter } from "../progress.ts";
 export type SalesforceConnection = {
     accessToken: string;
     /** e.g. https://yourorg.my.salesforce.com */
@@ -15,6 +16,12 @@ export type SalesforceConnectorOptions = {
     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.
@@ -25,4 +32,4 @@ export type SalesforceConnectorOptions = {
  * surface the gaps). Probabilities are normalized to 0..1 to match the
  * canonical model.
  */
-export declare function createSalesforceConnector(options: SalesforceConnectorOptions): Required<GtmConnector>;
+export declare function createSalesforceConnector(options: SalesforceConnectorOptions): GtmConnector;