fullstackgtm 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.34.0] — 2026-06-18
+
+### Added
+
+- **`discoverCompetitors(category, { llm, anchorUrl?, exclude? })`** — propose the
+  real vendor set for a category via the LLM (BYOK through `forcedToolCall`), so a
+  cold-start map needs only a category. Returns canonical homepages + a
+  category-specific `productUrl` per vendor; excludes the anchor and supplied hosts,
+  de-dupes by registrable domain, and instructs the model to skip acquired/defunct
+  brands. Pairs with `findCategoryPage` / `detectDrift` / `fetchLogoDataUri` (0.33).
+
 ## [0.33.0] — 2026-06-18
 
 ### Added

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { buildWorksheet, classifyMarket, type ClassifyMarketOptions, type Classi
 export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, type CallDocument, type ClaimMentionStats, type DirectiveStat, type DirectiveType, type MarketDirective, type OverlayOptions, type OverlayStats, type VendorMentionStats, } from "./marketOverlay.ts";
 export { computeScaleIndex, dimensionForMetric, scaleReportToText, type ScaleDimension, type ScaleReport, type SignalEstimate, type VendorScale, } from "./marketScale.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
-export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, type FetchText, type FetchBytes, type ResolveUrl, } from "./marketSourcing.ts";
+export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, discoverCompetitors, type FetchText, type FetchBytes, type ResolveUrl, type DiscoveredVendor, type DiscoverCompetitorsOptions, } from "./marketSourcing.ts";
 export { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, cronMatches, crontabSentinels, expectedFirings, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, scheduleRunsDir, schedulesPath, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, type CronExpression, type CrontabIo, type ScheduleEntry, type ScheduleProvider, type ScheduleRunRecord, type ScheduleRunStore, type ScheduleRunTrigger, type ScheduleStore, } from "./schedule.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type { ApprovalStatus, AuditFinding, AuditFindingSeverity, CanonicalAccount, CanonicalActivity, CanonicalContact, CanonicalDeal, CanonicalGtmSnapshot, CanonicalUser, CrmProvider, GtmAuditRule, GtmConnector, GtmEvidence, GtmEvidenceSourceSystem, GtmObjectType, GtmPolicy, GtmRuleContext, GtmRuleResult, GtmSnapshotIndex, PatchOperation, PatchOperationResult, PatchOperationType, PatchPlan, PatchPlanRun, PatchPlanRunStatus, PatchVerification, PipelineFinding, PipelineFindingStatus, PipelineFindingType, ProviderIdentity, RiskLevel, SourceFreshness, } from "./types.ts";

package/dist/index.js

@@ -34,6 +34,6 @@ export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
 export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, } from "./marketOverlay.js";
 export { computeScaleIndex, dimensionForMetric, scaleReportToText, } from "./marketScale.js";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
-export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, } from "./marketSourcing.js";
+export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, discoverCompetitors, } from "./marketSourcing.js";
 export { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, cronMatches, crontabSentinels, expectedFirings, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, scheduleRunsDir, schedulesPath, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, } from "./schedule.js";
 export { suggestValues } from "./suggest.js";

package/dist/marketSourcing.d.ts

@@ -1,3 +1,4 @@
+import { type LlmCallOptions } from "./llm.ts";
 /** Fetch a text resource (sitemap, robots.txt); null on any failure. */
 export type FetchText = (url: string) => Promise<string | null>;
 /** Fetch raw bytes (a logo image); null on any failure. */
@@ -64,3 +65,27 @@ export declare function findCategoryPage(homepageHtml: string, homepageUrl: stri
  * Bounded to small raster/SVG (≤50KB).
  */
 export declare function fetchLogoDataUri(homepageUrl: string, html?: string, fetchBytes?: FetchBytes): Promise<string | null>;
+/** A vendor proposed by `discoverCompetitors`. */
+export type DiscoveredVendor = {
+    name: string;
+    /** Canonical homepage. */
+    url: string;
+    /** The page most specific to the category — the product page for multi-product
+     *  companies, else the homepage. Use as the capture seed. */
+    productUrl: string;
+};
+export type DiscoverCompetitorsOptions = {
+    llm: LlmCallOptions;
+    /** The user's own company: competitors are listed for it and it's excluded. */
+    anchorUrl?: string;
+    /** Vendor hosts already in the set, to exclude from results. */
+    exclude?: string[];
+};
+/**
+ * Propose the real vendor set for a category via the LLM — so a cold-start map
+ * needs only a category, not a hand-built vendor list. Returns canonical homepages
+ * plus a category-specific `productUrl` per vendor; excludes the anchor + any
+ * supplied hosts, de-dupes by registrable domain, and instructs the model to skip
+ * acquired/defunct brands. BYOK via the package's `forcedToolCall`.
+ */
+export declare function discoverCompetitors(category: string, options: DiscoverCompetitorsOptions): Promise<DiscoveredVendor[]>;

package/dist/marketSourcing.js

@@ -17,6 +17,7 @@
  *    headless browser, so the default fetch is sufficient even in the hosted layer.
  */
 import { assertPublicUrl } from "./market.js";
+import { DEFAULT_MODELS, forcedToolCall } from "./llm.js";
 const USER_AGENT = "fullstackgtm-market/0 (+https://github.com/fullstackgtm/core)";
 const FETCH_TIMEOUT_MS = 15_000;
 const MAX_REDIRECTS = 5;
@@ -403,3 +404,84 @@ export async function fetchLogoDataUri(homepageUrl, html, fetchBytes = defaultFe
     }
     return null;
 }
+const DISCOVERY_SCHEMA = {
+    type: "object",
+    required: ["competitors"],
+    properties: {
+        competitors: {
+            type: "array",
+            description: "Real vendors competing in this category today, each with its canonical https homepage URL.",
+            items: {
+                type: "object",
+                required: ["name", "url"],
+                properties: {
+                    name: { type: "string" },
+                    url: { type: "string", description: "Canonical homepage, https://domain, no tracking path." },
+                    productUrl: {
+                        type: "string",
+                        description: "URL of the page on THIS vendor's site most specific to the category. For a multi-product company (e.g. SAP, Oracle) this is the product/solution page for this category, NOT the corporate homepage. For a focused single-product vendor, repeat the homepage.",
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * Propose the real vendor set for a category via the LLM — so a cold-start map
+ * needs only a category, not a hand-built vendor list. Returns canonical homepages
+ * plus a category-specific `productUrl` per vendor; excludes the anchor + any
+ * supplied hosts, de-dupes by registrable domain, and instructs the model to skip
+ * acquired/defunct brands. BYOK via the package's `forcedToolCall`.
+ */
+export async function discoverCompetitors(category, options) {
+    const model = options.llm.model ?? DEFAULT_MODELS[options.llm.provider];
+    const anchorHost = options.anchorUrl ? hostOf(options.anchorUrl) : null;
+    const anchorNote = anchorHost
+        ? `The user's own company is ${anchorHost} — list its direct competitors and do NOT include ${anchorHost} itself.`
+        : "";
+    const prompt = `List the most significant vendors competing in the category "${category}" today.
+${anchorNote}
+Rules:
+- Real companies only, each with its canonical https homepage URL (domain root, no tracking path).
+- 7-9 vendors: a mix of established leaders and notable challengers.
+- EXCLUDE vendors that have been acquired and folded into another brand, or are defunct — i.e. anything whose own site now redirects to a different company. (Name the current independent players instead.)
+- For each, also give productUrl: the page most specific to "${category}". For a big multi-product company, that's its product/solution page for THIS category, not the corporate homepage.
+- No duplicates.`;
+    const result = (await forcedToolCall(prompt, "discover_competitors", DISCOVERY_SCHEMA, model, options.llm));
+    const excluded = new Set((options.exclude ?? []).map(hostOf).filter((h) => Boolean(h)));
+    if (anchorHost)
+        excluded.add(anchorHost);
+    const seenDomain = new Set();
+    const out = [];
+    for (const c of result?.competitors ?? []) {
+        let u;
+        try {
+            u = new URL(String(c.url));
+        }
+        catch {
+            continue;
+        }
+        if (u.protocol !== "http:" && u.protocol !== "https:")
+            continue;
+        const host = u.hostname.replace(/^www\./, "");
+        if (excluded.has(host))
+            continue;
+        const dom = registrableDomain(host);
+        if (seenDomain.has(dom))
+            continue;
+        seenDomain.add(dom);
+        let productUrl = u.toString();
+        if (c.productUrl) {
+            try {
+                const p = new URL(String(c.productUrl));
+                if (p.protocol === "http:" || p.protocol === "https:")
+                    productUrl = p.toString();
+            }
+            catch {
+                /* keep homepage */
+            }
+        }
+        out.push({ name: c.name || host, url: u.toString(), productUrl });
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.33.0",
+  "version": "0.34.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/index.ts

@@ -301,9 +301,12 @@ export {
   findCategoryPageInSitemap,
   findCategoryPage,
   fetchLogoDataUri,
+  discoverCompetitors,
   type FetchText,
   type FetchBytes,
   type ResolveUrl,
+  type DiscoveredVendor,
+  type DiscoverCompetitorsOptions,
 } from "./marketSourcing.ts";
 export {
   computeMissedFirings,

package/src/marketSourcing.ts

@@ -17,6 +17,7 @@
  *    headless browser, so the default fetch is sufficient even in the hosted layer.
  */
 import { assertPublicUrl } from "./market.ts";
+import { DEFAULT_MODELS, forcedToolCall, type LlmCallOptions } from "./llm.ts";
 
 const USER_AGENT = "fullstackgtm-market/0 (+https://github.com/fullstackgtm/core)";
 const FETCH_TIMEOUT_MS = 15_000;
@@ -403,3 +404,106 @@ export async function fetchLogoDataUri(
   }
   return null;
 }
+
+// ── Competitor discovery ─────────────────────────────────────────────────────
+
+/** A vendor proposed by `discoverCompetitors`. */
+export type DiscoveredVendor = {
+  name: string;
+  /** Canonical homepage. */
+  url: string;
+  /** The page most specific to the category — the product page for multi-product
+   *  companies, else the homepage. Use as the capture seed. */
+  productUrl: string;
+};
+
+export type DiscoverCompetitorsOptions = {
+  llm: LlmCallOptions;
+  /** The user's own company: competitors are listed for it and it's excluded. */
+  anchorUrl?: string;
+  /** Vendor hosts already in the set, to exclude from results. */
+  exclude?: string[];
+};
+
+const DISCOVERY_SCHEMA = {
+  type: "object",
+  required: ["competitors"],
+  properties: {
+    competitors: {
+      type: "array",
+      description: "Real vendors competing in this category today, each with its canonical https homepage URL.",
+      items: {
+        type: "object",
+        required: ["name", "url"],
+        properties: {
+          name: { type: "string" },
+          url: { type: "string", description: "Canonical homepage, https://domain, no tracking path." },
+          productUrl: {
+            type: "string",
+            description:
+              "URL of the page on THIS vendor's site most specific to the category. For a multi-product company (e.g. SAP, Oracle) this is the product/solution page for this category, NOT the corporate homepage. For a focused single-product vendor, repeat the homepage.",
+          },
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Propose the real vendor set for a category via the LLM — so a cold-start map
+ * needs only a category, not a hand-built vendor list. Returns canonical homepages
+ * plus a category-specific `productUrl` per vendor; excludes the anchor + any
+ * supplied hosts, de-dupes by registrable domain, and instructs the model to skip
+ * acquired/defunct brands. BYOK via the package's `forcedToolCall`.
+ */
+export async function discoverCompetitors(
+  category: string,
+  options: DiscoverCompetitorsOptions,
+): Promise<DiscoveredVendor[]> {
+  const model = options.llm.model ?? DEFAULT_MODELS[options.llm.provider];
+  const anchorHost = options.anchorUrl ? hostOf(options.anchorUrl) : null;
+  const anchorNote = anchorHost
+    ? `The user's own company is ${anchorHost} — list its direct competitors and do NOT include ${anchorHost} itself.`
+    : "";
+  const prompt = `List the most significant vendors competing in the category "${category}" today.
+${anchorNote}
+Rules:
+- Real companies only, each with its canonical https homepage URL (domain root, no tracking path).
+- 7-9 vendors: a mix of established leaders and notable challengers.
+- EXCLUDE vendors that have been acquired and folded into another brand, or are defunct — i.e. anything whose own site now redirects to a different company. (Name the current independent players instead.)
+- For each, also give productUrl: the page most specific to "${category}". For a big multi-product company, that's its product/solution page for THIS category, not the corporate homepage.
+- No duplicates.`;
+  const result = (await forcedToolCall(prompt, "discover_competitors", DISCOVERY_SCHEMA, model, options.llm)) as {
+    competitors?: Array<{ name?: string; url?: string; productUrl?: string }>;
+  };
+
+  const excluded = new Set((options.exclude ?? []).map(hostOf).filter((h): h is string => Boolean(h)));
+  if (anchorHost) excluded.add(anchorHost);
+  const seenDomain = new Set<string>();
+  const out: DiscoveredVendor[] = [];
+  for (const c of result?.competitors ?? []) {
+    let u: URL;
+    try {
+      u = new URL(String(c.url));
+    } catch {
+      continue;
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:") continue;
+    const host = u.hostname.replace(/^www\./, "");
+    if (excluded.has(host)) continue;
+    const dom = registrableDomain(host);
+    if (seenDomain.has(dom)) continue;
+    seenDomain.add(dom);
+    let productUrl = u.toString();
+    if (c.productUrl) {
+      try {
+        const p = new URL(String(c.productUrl));
+        if (p.protocol === "http:" || p.protocol === "https:") productUrl = p.toString();
+      } catch {
+        /* keep homepage */
+      }
+    }
+    out.push({ name: c.name || host, url: u.toString(), productUrl });
+  }
+  return out;
+}