fullstackgtm 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.31.0] — 2026-06-18
+
+### Added
+
+- **Vendor logos in the market-map report.** `MarketVendor` gains an optional
+  `logo` field; `marketMapToHtml` renders it beside the name in the legend and
+  above the matrix column headers, degrading to the numbered swatch / plain name
+  when absent. Only `data:image/…` URIs are honored — keeping the report
+  self-contained (no external requests, survives being saved or emailed) and safe
+  under a strict `img-src data:` CSP. The hosted service extracts a canonical logo
+  from each vendor's homepage; CLI users can set `logo` by hand.
+
+## [0.30.0] — 2026-06-17
+
+Connector fixes — the two concrete defects a real HubSpot/Salesforce shop hits.
+
+### Added
+
+- **Salesforce `dedupe`/`merge_records` now works** (Accounts and Contacts) via
+  the SOAP `merge()` call — REST has no merge resource, but the OAuth token
+  doubles as the SOAP session id, so no extra auth. Groups larger than three are
+  merged in batches (master + 2 per call); failures are reported honestly with
+  what merged before the stop. **Opportunities remain unmergeable** (Salesforce
+  exposes no opportunity merge anywhere) and are refused with that explanation.
+  Merges still flow through the approval gate and the irreversible-op drift guard
+  (the survivor/loser existence check runs before the SOAP call). Exercised by
+  unit tests; validate against a sandbox before wiring into automation.
+
+### Fixed
+
+- **HubSpot closed/won detection is now pipeline-aware.** `isClosed`/`isWon`
+  were derived by substring-matching the stage against `closedwon`/`closedlost`,
+  so custom pipelines (opaque stage ids) read every deal as open and flooded
+  stale-deal / past-close findings with false positives. The connector now reads
+  the pipeline stage metadata (`/crm/v3/pipelines/deals`: `isClosed` +
+  `probability`) once per snapshot and derives closed/won from that, falling back
+  to the substring heuristic only when the pipelines read is unavailable.
+
 ## [0.29.0] — 2026-06-16
 
 ### Added

package/README.md

@@ -281,9 +281,9 @@ Connectors differ in what the provider's API allows — stated up front so nothi
 | Field writes (`set_field`, `clear_field`, `link_record`) | ✅ | ✅ | — |
 | `create_task` | ✅ | ✅ | — |
 | `archive_record` | ✅ | ✅ | — |
-| `merge_records` (`dedupe`) | ✅ | ❌ **not supported** | — |
+| `merge_records` (`dedupe`) | ✅ | ✅ Account/Contact (SOAP); ❌ Opportunity | — |
 
-**Salesforce merge** has no REST resource — it exists only in the SOAP API / Apex (Lead, Contact, Account, Case; max 3 records). This connector refuses a Salesforce `merge_records` operation honestly rather than half-merging; on Salesforce, deduplicate in the UI (or via SOAP/Apex), or use `bulk-update --archive` for the non-survivors. Native Salesforce merge is tracked future work, not a silent gap.
+**Salesforce merge** uses the SOAP `merge()` call (REST has no merge resource), so `dedupe` works on Salesforce **Accounts and Contacts** — the OAuth token doubles as the SOAP session, and groups larger than three records are merged in batches (master + 2 per call). **Opportunities cannot be merged** (Salesforce exposes no opportunity merge in the API or the UI) — for duplicate opportunities, pick a survivor and close/archive the rest. As always, merges are irreversible and go through the same approval gate + drift guard as every other write. (Validate against a sandbox first if you're wiring it into automation — the SOAP path is exercised by unit tests but a live Salesforce org is the real proof.)
 
 ### HubSpot: create a private app (~2 minutes, needs super-admin)
 

package/dist/connectors/hubspot.js

@@ -54,6 +54,37 @@ export function createHubspotConnector(options) {
         const text = await response.text();
         return text ? JSON.parse(text) : null;
     }
+    /**
+     * Map every deal stage id → its actual closed/won semantics, read from the
+     * pipeline definitions. Custom pipelines use opaque stage ids (e.g.
+     * "1234567"), so deriving closed/won by substring-matching the stage value
+     * against "closedwon"/"closedlost" mis-reads every custom-pipeline deal as
+     * open. The pipeline's own stage metadata is authoritative: `isClosed` marks
+     * a closed stage and `probability` 1.0 = won, 0.0 = lost. Best-effort — if
+     * the read is unavailable (e.g. missing scope) callers fall back to the
+     * substring heuristic so a partial-scope token still produces a snapshot.
+     */
+    async function fetchDealStageClose() {
+        const map = new Map();
+        try {
+            const data = await request("/crm/v3/pipelines/deals");
+            for (const pipeline of data?.results ?? []) {
+                for (const stage of pipeline?.stages ?? []) {
+                    if (!stage?.id)
+                        continue;
+                    const meta = stage.metadata ?? {};
+                    const isClosed = String(meta.isClosed).toLowerCase() === "true";
+                    const isWon = isClosed && Number(meta.probability) === 1;
+                    map.set(String(stage.id), { isClosed, isWon });
+                }
+            }
+        }
+        catch {
+            // Pipeline metadata unavailable — leave the map empty; the caller falls
+            // back to the substring heuristic.
+        }
+        return map;
+    }
     async function list(path) {
         const results = [];
         let after;
@@ -137,6 +168,7 @@ export function createHubspotConnector(options) {
             };
         });
         const dealProperties = `${mappedFields(mappings, "deals", HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals).join(",")},${PROVENANCE_PROPERTIES}`;
+        const stageClose = await fetchDealStageClose();
         const hubspotDeals = await fetchObjects("deals", dealProperties, true);
         const deals = hubspotDeals
             .filter((deal) => deal.id)
@@ -145,13 +177,15 @@ export function createHubspotConnector(options) {
             const companyId = deal.associations?.companies?.results?.[0]?.id;
             const stage = stringOrUndefined(readMapped(props, "deals", "stage", "dealstage"));
             const normalizedStage = (stage ?? "").toLowerCase();
-            const isWon = normalizedStage.includes("closedwon");
-            const isClosed = isWon || normalizedStage.includes("closedlost");
-            const forecastCategory = isWon
-                ? "closed_won"
-                : normalizedStage.includes("closedlost")
-                    ? "closed_lost"
-                    : "pipeline";
+            // Prefer the pipeline stage's actual closed/won metadata; fall back to
+            // the substring heuristic only when the stage isn't in the pipeline map
+            // (pipelines unreadable, or a deal on a deleted stage).
+            const stageMeta = stage ? stageClose.get(stage) : undefined;
+            const isWon = stageMeta ? stageMeta.isWon : normalizedStage.includes("closedwon");
+            const isClosed = stageMeta
+                ? stageMeta.isClosed
+                : isWon || normalizedStage.includes("closedlost");
+            const forecastCategory = isWon ? "closed_won" : isClosed ? "closed_lost" : "pipeline";
             const lastActivityAt = stringOrUndefined(readMapped(props, "deals", "lastActivityAt", "hs_last_sales_activity_timestamp"));
             return {
                 id: String(deal.id),

package/dist/connectors/salesforce.js

@@ -5,6 +5,12 @@ const SOBJECT_TYPES = {
     contact: "Contact",
     deal: "Opportunity",
 };
+// SObjects the SOAP merge() call supports. Opportunity is deliberately absent —
+// Salesforce has no opportunity merge at all (API or UI).
+const SOAP_MERGEABLE = {
+    account: "Account",
+    contact: "Contact",
+};
 const MAPPING_OBJECT_TYPES = {
     account: "accounts",
     contact: "contacts",
@@ -282,6 +288,97 @@ export function createSalesforceConnector(options) {
             detail: `Deleted ${sobjectType}/${operation.objectId}.`,
         };
     }
+    function escapeXml(value) {
+        return value
+            .replace(/&/g, "&")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;")
+            .replace(/'/g, "&apos;");
+    }
+    /**
+     * One SOAP merge() call: master + up to 2 records to merge. Salesforce has no
+     * REST merge resource, but the Partner SOAP API's merge() works for Account,
+     * Contact, Lead, and Case, and accepts the OAuth access token as the SOAP
+     * session id. Returns ok/detail (the SOAP fault/error message is operational
+     * — MALFORMED_ID, entity-locked — not a data echo, so it's surfaced, capped).
+     */
+    async function soapMerge(sobjectType, masterId, loserIds) {
+        const connection = await options.getConnection();
+        const version = apiVersion.replace(/^v/, ""); // SOAP path uses "59.0", not "v59.0"
+        const url = `${connection.instanceUrl.replace(/\/$/, "")}/services/Soap/u/${version}`;
+        const toMerge = loserIds.map((id) => `<urn:recordToMergeIds>${escapeXml(id)}</urn:recordToMergeIds>`).join("");
+        const envelope = `<?xml version="1.0" encoding="UTF-8"?>` +
+            `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:partner.soap.sforce.com" xmlns:urn1="urn:sobject.partner.soap.sforce.com">` +
+            `<soapenv:Header><urn:SessionHeader><urn:sessionId>${escapeXml(connection.accessToken)}</urn:sessionId></urn:SessionHeader></soapenv:Header>` +
+            `<soapenv:Body><urn:merge><urn:request>` +
+            `<urn:masterRecord><urn1:type>${sobjectType}</urn1:type><urn1:Id>${escapeXml(masterId)}</urn1:Id></urn:masterRecord>` +
+            toMerge +
+            `</urn:request></urn:merge></soapenv:Body></soapenv:Envelope>`;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: "POST",
+                headers: { "Content-Type": "text/xml; charset=UTF-8", SOAPAction: '""' },
+                body: envelope,
+            });
+        }
+        catch (error) {
+            const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+            return { ok: false, detail: `Cannot reach the Salesforce SOAP endpoint${cause}.` };
+        }
+        const text = await response.text().catch(() => "");
+        if (!response.ok) {
+            const fault = /<faultstring>([\s\S]*?)<\/faultstring>/.exec(text)?.[1]?.trim();
+            return { ok: false, detail: `Salesforce SOAP merge failed (HTTP ${response.status})${fault ? `: ${fault.slice(0, 200)}` : ""}.` };
+        }
+        if (!/<success>\s*true\s*<\/success>/i.test(text)) {
+            const message = /<message>([\s\S]*?)<\/message>/.exec(text)?.[1]?.trim();
+            return { ok: false, detail: `Salesforce rejected the merge${message ? `: ${message.slice(0, 200)}` : ""}.` };
+        }
+        return { ok: true };
+    }
+    async function mergeRecords(operation) {
+        const sobjectType = SOAP_MERGEABLE[operation.objectType];
+        if (!sobjectType) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: operation.objectType === "deal"
+                    ? "Salesforce opportunities cannot be merged (no merge exists in the API or the UI). Pick a survivor and close/archive the duplicate opportunities instead."
+                    : `Salesforce merge supports Account and Contact only (not ${operation.objectType}).`,
+            };
+        }
+        const master = operation.objectId;
+        const group = Array.isArray(operation.beforeValue) ? operation.beforeValue.map(String) : [];
+        const losers = group.filter((id) => id !== master);
+        if (losers.length === 0) {
+            return { operationId: operation.id, status: "skipped", detail: "Nothing to merge — no records besides the survivor." };
+        }
+        // SOAP merge() takes the master + at most 2 records per call; batch larger
+        // duplicate groups. A mid-batch failure is reported with what was merged so
+        // far (merges are irreversible).
+        const merged = [];
+        for (let i = 0; i < losers.length; i += 2) {
+            const batch = losers.slice(i, i + 2);
+            const result = await soapMerge(sobjectType, master, batch);
+            if (!result.ok) {
+                return {
+                    operationId: operation.id,
+                    status: "failed",
+                    detail: `${result.detail} Merged ${merged.length} of ${losers.length} into ${master} before failing — IRREVERSIBLE; the remaining duplicates were not merged.`,
+                    providerData: { survivorId: master, mergedRecordIds: merged },
+                };
+            }
+            merged.push(...batch);
+        }
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Merged ${merged.length} ${sobjectType} record(s) into ${master} (irreversible).`,
+            providerData: { survivorId: master, mergedRecordIds: merged },
+        };
+    }
     async function applyOperation(operation) {
         try {
             switch (operation.operation) {
@@ -341,14 +438,7 @@ export function createSalesforceConnector(options) {
                 case "create_task":
                     return await createTask(operation);
                 case "merge_records":
-                    // Salesforce merge exists only in the SOAP API and Apex (Lead,
-                    // Contact, Account, Case; max 3 records) — there is no REST merge
-                    // resource. Surface that honestly instead of half-merging.
-                    return {
-                        operationId: operation.id,
-                        status: "skipped",
-                        detail: "Salesforce merge requires the SOAP API or Apex (Lead/Contact/Account/Case only) — this REST connector cannot merge. Merge in the Salesforce UI, or archive the duplicates explicitly.",
-                    };
+                    return await mergeRecords(operation);
                 case "archive_record":
                     return await archiveRecord(operation);
                 default:

package/dist/market.d.ts

@@ -81,6 +81,14 @@ export type MarketVendor = {
      * obvious from the vendor's own pricing page (which the map captures).
      */
     acvBand?: string;
+    /**
+     * Optional brand logo for the report (legend + matrix headers). A `data:` URI
+     * keeps the rendered report self-contained — no external requests, survives
+     * being saved or emailed. The hosted service extracts it from the vendor's
+     * homepage; CLI users can set it by hand. Renderers degrade gracefully to the
+     * numbered swatch when absent.
+     */
+    logo?: string;
     notes?: string;
 };
 export type MarketAxis = {

package/dist/marketReport.js

@@ -28,6 +28,17 @@ function escapeHtml(value) {
         .replace(/>/g, ">")
         .replace(/"/g, """);
 }
+/**
+ * A small brand logo for legend rows / matrix headers. Accepts only `data:image/`
+ * URIs — self-contained (no external request, survives save/email) and safe under
+ * the report's `img-src data:` CSP (an SVG loaded via <img> can't execute script).
+ * Returns "" when absent so callers fall back to the numbered swatch / plain name.
+ */
+function logoImg(logo, cls) {
+    if (typeof logo !== "string" || !logo.startsWith("data:image/"))
+        return "";
+    return `<img class="${cls}" src="${escapeHtml(logo)}" alt="" loading="lazy">`;
+}
 /**
  * Serialize JSON for embedding inside an inline <script> block. JSON.stringify
  * does not escape `<`, `>`, `&`, or the U+2028/U+2029 line separators, so a
@@ -291,6 +302,7 @@ function axisSectionsHtml(config, set) {
     // The number inside each bubble resolves dense clusters that name labels
     // never could; color is Okabe–Ito (colorblind-safe) keyed in the legend.
     const points = pointsFor(px, py);
+    const logoByVendor = new Map(config.vendors.map((vendor) => [vendor.id, vendor.logo]));
     const legendOrder = [...points].sort((a, b) => b.size - a.size || a.name.localeCompare(b.name));
     const numberByVendor = new Map(legendOrder.map((point, index) => [point.vendorId, index + 1]));
     const colorByVendor = new Map(legendOrder.map((point, index) => [point.vendorId, VENDOR_COLORS[index % VENDOR_COLORS.length]]));
@@ -305,7 +317,7 @@ function axisSectionsHtml(config, set) {
                 ? `${(share * 100).toFixed(1)}%`
                 : "—"
             : `${loudCounts.get(point.vendorId) ?? 0} loud`;
-        return `<tr data-v="${e(point.vendorId)}"${isAnchor ? ' class="anchor-row"' : ""}><td><span class="swatch" style="background:${color};color:${numeralColor(color)}">${number}</span></td><td>${e(point.name)}${isAnchor ? " ·&nbsp;anchor" : ""}</td><td class="num">${measure}</td></tr>`;
+        return `<tr data-v="${e(point.vendorId)}"${isAnchor ? ' class="anchor-row"' : ""}><td><span class="swatch" style="background:${color};color:${numeralColor(color)}">${number}</span></td><td>${logoImg(logoByVendor.get(point.vendorId), "v-logo")}${e(point.name)}${isAnchor ? " ·&nbsp;anchor" : ""}</td><td class="num">${measure}</td></tr>`;
     })
         .join("");
     const legendMeasureHead = useScale ? "est. share" : "loud";
@@ -426,7 +438,7 @@ export function marketMapToHtml(config, set) {
             `<td class="front"><span class="chip chip-${state}">${state.toUpperCase()}</span></td></tr>`);
     };
     const vendorHeads = config.vendors
-        .map((vendor) => `<th class="vh${vendor.id === anchor ? " anchor-col" : ""}"><span>${e(vendor.name)}</span></th>`)
+        .map((vendor) => `<th class="vh${vendor.id === anchor ? " anchor-col" : ""}">${logoImg(vendor.logo, "vh-logo")}<span>${e(vendor.name)}</span></th>`)
         .join("");
     // Claims grouped by front state, each group a collapsed <details> whose
     // summary carries the stats a skimmer needs; the full matrix is one click
@@ -562,6 +574,8 @@ tr.front-open th .claim-cap { color:var(--accent); font-weight:600; }
 figure.map { margin-top:16px; border:1px solid var(--line); position:relative; }
 g.bubble { cursor:pointer; }
 g.bubble.dim { opacity:0.25; transition:opacity .12s; }
+img.v-logo { width:15px; height:15px; border-radius:3px; object-fit:contain; vertical-align:-3px; margin-right:6px; background:#fff; }
+th.vh img.vh-logo { display:block; width:18px; height:18px; border-radius:3px; object-fit:contain; margin:0 auto 4px; background:#fff; }
 table.legend tbody tr { cursor:default; }
 table.legend tbody tr.hl td { background:var(--faint); }
 .map-tip { position:absolute; z-index:5; background:#1c1c1c; color:#fff; font-size:11.5px; line-height:1.45;

package/docs/roadmap-to-1.0.md

@@ -148,11 +148,6 @@ against the 0.28 surface: still accurate, still open.
 Found by exercising the published package as a fresh RevOps user with a real
 CRM (2026-06):
 
-- **Pipeline-aware closed-deal detection (HubSpot).** `isClosed`/`isWon` are
-  derived by substring-matching the raw `dealstage` value against
-  `closedwon`/`closedlost`. Custom pipelines use opaque stage ids, so closed
-  deals read as open and flood stale-deal/past-close findings. Fix: resolve
-  stage metadata from `/crm/v3/pipelines` once per snapshot.
 - **Rate-limit resilience.** No 429/retry/backoff handling anywhere; a
   mid-size portal snapshot is ~1,000+ sequential page requests and one
   transient failure aborts the run. Fix: honor `Retry-After`, retry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/src/connectors/hubspot.ts

@@ -88,6 +88,36 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     return text ? JSON.parse(text) : null;
   }
 
+  /**
+   * Map every deal stage id → its actual closed/won semantics, read from the
+   * pipeline definitions. Custom pipelines use opaque stage ids (e.g.
+   * "1234567"), so deriving closed/won by substring-matching the stage value
+   * against "closedwon"/"closedlost" mis-reads every custom-pipeline deal as
+   * open. The pipeline's own stage metadata is authoritative: `isClosed` marks
+   * a closed stage and `probability` 1.0 = won, 0.0 = lost. Best-effort — if
+   * the read is unavailable (e.g. missing scope) callers fall back to the
+   * substring heuristic so a partial-scope token still produces a snapshot.
+   */
+  async function fetchDealStageClose(): Promise<Map<string, { isClosed: boolean; isWon: boolean }>> {
+    const map = new Map<string, { isClosed: boolean; isWon: boolean }>();
+    try {
+      const data = await request("/crm/v3/pipelines/deals");
+      for (const pipeline of data?.results ?? []) {
+        for (const stage of pipeline?.stages ?? []) {
+          if (!stage?.id) continue;
+          const meta = stage.metadata ?? {};
+          const isClosed = String(meta.isClosed).toLowerCase() === "true";
+          const isWon = isClosed && Number(meta.probability) === 1;
+          map.set(String(stage.id), { isClosed, isWon });
+        }
+      }
+    } catch {
+      // Pipeline metadata unavailable — leave the map empty; the caller falls
+      // back to the substring heuristic.
+    }
+    return map;
+  }
+
   async function list(path: string): Promise<any[]> {
     const results: any[] = [];
     let after: string | undefined;
@@ -204,6 +234,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       "deals",
       HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals,
     ).join(",")},${PROVENANCE_PROPERTIES}`;
+    const stageClose = await fetchDealStageClose();
     const hubspotDeals = await fetchObjects("deals", dealProperties, true);
     const deals: CanonicalDeal[] = hubspotDeals
       .filter((deal) => deal.id)
@@ -212,13 +243,15 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
         const companyId = deal.associations?.companies?.results?.[0]?.id;
         const stage = stringOrUndefined(readMapped(props, "deals", "stage", "dealstage"));
         const normalizedStage = (stage ?? "").toLowerCase();
-        const isWon = normalizedStage.includes("closedwon");
-        const isClosed = isWon || normalizedStage.includes("closedlost");
-        const forecastCategory = isWon
-          ? "closed_won"
-          : normalizedStage.includes("closedlost")
-            ? "closed_lost"
-            : "pipeline";
+        // Prefer the pipeline stage's actual closed/won metadata; fall back to
+        // the substring heuristic only when the stage isn't in the pipeline map
+        // (pipelines unreadable, or a deal on a deleted stage).
+        const stageMeta = stage ? stageClose.get(stage) : undefined;
+        const isWon = stageMeta ? stageMeta.isWon : normalizedStage.includes("closedwon");
+        const isClosed = stageMeta
+          ? stageMeta.isClosed
+          : isWon || normalizedStage.includes("closedlost");
+        const forecastCategory = isWon ? "closed_won" : isClosed ? "closed_lost" : "pipeline";
         const lastActivityAt = stringOrUndefined(
           readMapped(props, "deals", "lastActivityAt", "hs_last_sales_activity_timestamp"),
         );

package/src/connectors/salesforce.ts

@@ -42,6 +42,13 @@ const SOBJECT_TYPES: Partial<Record<GtmObjectType, string>> = {
   deal: "Opportunity",
 };
 
+// SObjects the SOAP merge() call supports. Opportunity is deliberately absent —
+// Salesforce has no opportunity merge at all (API or UI).
+const SOAP_MERGEABLE: Partial<Record<GtmObjectType, string>> = {
+  account: "Account",
+  contact: "Contact",
+};
+
 const MAPPING_OBJECT_TYPES: Partial<Record<GtmObjectType, Exclude<CrmObjectType, "owners">>> = {
   account: "accounts",
   contact: "contacts",
@@ -378,6 +385,105 @@ export function createSalesforceConnector(
     };
   }
 
+  function escapeXml(value: string): string {
+    return value
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&apos;");
+  }
+
+  /**
+   * One SOAP merge() call: master + up to 2 records to merge. Salesforce has no
+   * REST merge resource, but the Partner SOAP API's merge() works for Account,
+   * Contact, Lead, and Case, and accepts the OAuth access token as the SOAP
+   * session id. Returns ok/detail (the SOAP fault/error message is operational
+   * — MALFORMED_ID, entity-locked — not a data echo, so it's surfaced, capped).
+   */
+  async function soapMerge(
+    sobjectType: string,
+    masterId: string,
+    loserIds: string[],
+  ): Promise<{ ok: boolean; detail?: string }> {
+    const connection = await options.getConnection();
+    const version = apiVersion.replace(/^v/, ""); // SOAP path uses "59.0", not "v59.0"
+    const url = `${connection.instanceUrl.replace(/\/$/, "")}/services/Soap/u/${version}`;
+    const toMerge = loserIds.map((id) => `<urn:recordToMergeIds>${escapeXml(id)}</urn:recordToMergeIds>`).join("");
+    const envelope =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:partner.soap.sforce.com" xmlns:urn1="urn:sobject.partner.soap.sforce.com">` +
+      `<soapenv:Header><urn:SessionHeader><urn:sessionId>${escapeXml(connection.accessToken)}</urn:sessionId></urn:SessionHeader></soapenv:Header>` +
+      `<soapenv:Body><urn:merge><urn:request>` +
+      `<urn:masterRecord><urn1:type>${sobjectType}</urn1:type><urn1:Id>${escapeXml(masterId)}</urn1:Id></urn:masterRecord>` +
+      toMerge +
+      `</urn:request></urn:merge></soapenv:Body></soapenv:Envelope>`;
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        method: "POST",
+        headers: { "Content-Type": "text/xml; charset=UTF-8", SOAPAction: '""' },
+        body: envelope,
+      });
+    } catch (error) {
+      const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+      return { ok: false, detail: `Cannot reach the Salesforce SOAP endpoint${cause}.` };
+    }
+    const text = await response.text().catch(() => "");
+    if (!response.ok) {
+      const fault = /<faultstring>([\s\S]*?)<\/faultstring>/.exec(text)?.[1]?.trim();
+      return { ok: false, detail: `Salesforce SOAP merge failed (HTTP ${response.status})${fault ? `: ${fault.slice(0, 200)}` : ""}.` };
+    }
+    if (!/<success>\s*true\s*<\/success>/i.test(text)) {
+      const message = /<message>([\s\S]*?)<\/message>/.exec(text)?.[1]?.trim();
+      return { ok: false, detail: `Salesforce rejected the merge${message ? `: ${message.slice(0, 200)}` : ""}.` };
+    }
+    return { ok: true };
+  }
+
+  async function mergeRecords(operation: PatchOperation): Promise<PatchOperationResult> {
+    const sobjectType = SOAP_MERGEABLE[operation.objectType];
+    if (!sobjectType) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail:
+          operation.objectType === "deal"
+            ? "Salesforce opportunities cannot be merged (no merge exists in the API or the UI). Pick a survivor and close/archive the duplicate opportunities instead."
+            : `Salesforce merge supports Account and Contact only (not ${operation.objectType}).`,
+      };
+    }
+    const master = operation.objectId;
+    const group = Array.isArray(operation.beforeValue) ? (operation.beforeValue as unknown[]).map(String) : [];
+    const losers = group.filter((id) => id !== master);
+    if (losers.length === 0) {
+      return { operationId: operation.id, status: "skipped", detail: "Nothing to merge — no records besides the survivor." };
+    }
+    // SOAP merge() takes the master + at most 2 records per call; batch larger
+    // duplicate groups. A mid-batch failure is reported with what was merged so
+    // far (merges are irreversible).
+    const merged: string[] = [];
+    for (let i = 0; i < losers.length; i += 2) {
+      const batch = losers.slice(i, i + 2);
+      const result = await soapMerge(sobjectType, master, batch);
+      if (!result.ok) {
+        return {
+          operationId: operation.id,
+          status: "failed",
+          detail: `${result.detail} Merged ${merged.length} of ${losers.length} into ${master} before failing — IRREVERSIBLE; the remaining duplicates were not merged.`,
+          providerData: { survivorId: master, mergedRecordIds: merged },
+        };
+      }
+      merged.push(...batch);
+    }
+    return {
+      operationId: operation.id,
+      status: "applied",
+      detail: `Merged ${merged.length} ${sobjectType} record(s) into ${master} (irreversible).`,
+      providerData: { survivorId: master, mergedRecordIds: merged },
+    };
+  }
+
   async function applyOperation(operation: PatchOperation): Promise<PatchOperationResult> {
     try {
       switch (operation.operation) {
@@ -438,15 +544,7 @@ export function createSalesforceConnector(
         case "create_task":
           return await createTask(operation);
         case "merge_records":
-          // Salesforce merge exists only in the SOAP API and Apex (Lead,
-          // Contact, Account, Case; max 3 records) — there is no REST merge
-          // resource. Surface that honestly instead of half-merging.
-          return {
-            operationId: operation.id,
-            status: "skipped",
-            detail:
-              "Salesforce merge requires the SOAP API or Apex (Lead/Contact/Account/Case only) — this REST connector cannot merge. Merge in the Salesforce UI, or archive the duplicates explicitly.",
-          };
+          return await mergeRecords(operation);
         case "archive_record":
           return await archiveRecord(operation);
         default:

package/src/market.ts

@@ -94,6 +94,14 @@ export type MarketVendor = {
    * obvious from the vendor's own pricing page (which the map captures).
    */
   acvBand?: string;
+  /**
+   * Optional brand logo for the report (legend + matrix headers). A `data:` URI
+   * keeps the rendered report self-contained — no external requests, survives
+   * being saved or emailed. The hosted service extracts it from the vendor's
+   * homepage; CLI users can set it by hand. Renderers degrade gracefully to the
+   * numbered swatch when absent.
+   */
+  logo?: string;
   notes?: string;
 };
 

package/src/marketReport.ts

@@ -40,6 +40,17 @@ function escapeHtml(value: string): string {
     .replace(/"/g, """);
 }
 
+/**
+ * A small brand logo for legend rows / matrix headers. Accepts only `data:image/`
+ * URIs — self-contained (no external request, survives save/email) and safe under
+ * the report's `img-src data:` CSP (an SVG loaded via <img> can't execute script).
+ * Returns "" when absent so callers fall back to the numbered swatch / plain name.
+ */
+function logoImg(logo: string | undefined, cls: string): string {
+  if (typeof logo !== "string" || !logo.startsWith("data:image/")) return "";
+  return `<img class="${cls}" src="${escapeHtml(logo)}" alt="" loading="lazy">`;
+}
+
 /**
  * Serialize JSON for embedding inside an inline <script> block. JSON.stringify
  * does not escape `<`, `>`, `&`, or the U+2028/U+2029 line separators, so a
@@ -342,6 +353,7 @@ function axisSectionsHtml(
   // The number inside each bubble resolves dense clusters that name labels
   // never could; color is Okabe–Ito (colorblind-safe) keyed in the legend.
   const points = pointsFor(px, py);
+  const logoByVendor = new Map(config.vendors.map((vendor) => [vendor.id, vendor.logo]));
   const legendOrder = [...points].sort((a, b) => b.size - a.size || a.name.localeCompare(b.name));
   const numberByVendor = new Map(legendOrder.map((point, index) => [point.vendorId, index + 1]));
   const colorByVendor = new Map(legendOrder.map((point, index) => [point.vendorId, VENDOR_COLORS[index % VENDOR_COLORS.length]]));
@@ -356,7 +368,7 @@ function axisSectionsHtml(
           ? `${(share * 100).toFixed(1)}%`
           : "—"
         : `${loudCounts.get(point.vendorId) ?? 0} loud`;
-      return `<tr data-v="${e(point.vendorId)}"${isAnchor ? ' class="anchor-row"' : ""}><td><span class="swatch" style="background:${color};color:${numeralColor(color)}">${number}</span></td><td>${e(point.name)}${isAnchor ? " ·&nbsp;anchor" : ""}</td><td class="num">${measure}</td></tr>`;
+      return `<tr data-v="${e(point.vendorId)}"${isAnchor ? ' class="anchor-row"' : ""}><td><span class="swatch" style="background:${color};color:${numeralColor(color)}">${number}</span></td><td>${logoImg(logoByVendor.get(point.vendorId), "v-logo")}${e(point.name)}${isAnchor ? " ·&nbsp;anchor" : ""}</td><td class="num">${measure}</td></tr>`;
     })
     .join("");
   const legendMeasureHead = useScale ? "est. share" : "loud";
@@ -488,7 +500,7 @@ export function marketMapToHtml(config: MarketConfig, set: ObservationSet): stri
   const vendorHeads = config.vendors
     .map(
       (vendor) =>
-        `<th class="vh${vendor.id === anchor ? " anchor-col" : ""}"><span>${e(vendor.name)}</span></th>`,
+        `<th class="vh${vendor.id === anchor ? " anchor-col" : ""}">${logoImg(vendor.logo, "vh-logo")}<span>${e(vendor.name)}</span></th>`,
     )
     .join("");
 
@@ -632,6 +644,8 @@ tr.front-open th .claim-cap { color:var(--accent); font-weight:600; }
 figure.map { margin-top:16px; border:1px solid var(--line); position:relative; }
 g.bubble { cursor:pointer; }
 g.bubble.dim { opacity:0.25; transition:opacity .12s; }
+img.v-logo { width:15px; height:15px; border-radius:3px; object-fit:contain; vertical-align:-3px; margin-right:6px; background:#fff; }
+th.vh img.vh-logo { display:block; width:18px; height:18px; border-radius:3px; object-fit:contain; margin:0 auto 4px; background:#fff; }
 table.legend tbody tr { cursor:default; }
 table.legend tbody tr.hl td { background:var(--faint); }
 .map-tip { position:absolute; z-index:5; background:#1c1c1c; color:#fff; font-size:11.5px; line-height:1.45;