crawlmark-mcp 0.1.0 → 0.1.2

package/dist/lib/provider-data.js

@@ -11,7 +11,7 @@
  * - No key, and nothing derived from one, is ever stored: the mark records only the key's source.
  */
 import { ENV_FILE_KEYS, env } from "../config.js";
-import { pruneSemrushIssueSnapshots, stripSourceFromIssueSnapshots } from "./issue-snapshots.js";
+import { stripSourceFromIssueSnapshots } from "./issue-snapshots.js";
 import { purgeExpired } from "./cache.js";
 import { pruneSnapshots } from "./snapshots.js";
 import { db } from "./store.js";
@@ -20,6 +20,7 @@ let processEntry = "cli";
 export function setProcessEntry(e) {
     processEntry = e;
 }
+/** Stored issue items from a provider's Site Audit, removed with the rest of its data. (Semrush has none now; an older build may have stored some.) */
 const SITE_AUDIT_SOURCE = { ahrefs: "ahrefs_site_audit", semrush: "semrush_site_audit" };
 const KEY_VAR = { ahrefs: "AHREFS_API_KEY", semrush: "SEMRUSH_API_KEY" };
 /** Remember that a cache entry holds this provider's data for this client, so a purge can delete it. */
@@ -94,7 +95,6 @@ export function reconcileRemovedKeys(entry = processEntry) {
 export function retentionSweep(now = Date.now()) {
     purgeExpired();
     pruneSnapshots(now);
-    pruneSemrushIssueSnapshots(now);
 }
 let reconciled = false;
 /** reconcileRemovedKeys once per process; a purge is reported on stderr (never stdout: the MCP channel). */

package/dist/lib/vendor-mcp.js

@@ -0,0 +1,155 @@
+import { parse as parseToml } from "smol-toml";
+import { tomlEqual } from "./codex-config.js";
+/**
+ * Semrush's and Ahrefs' own remote MCP servers, which the setup wizard can add to a user's AI apps for ad-hoc
+ * questions. crawlmark itself never calls them (its Semrush and Ahrefs integrations use API keys). Entries are
+ * URL-only: sign-in is OAuth in the app, so no key or header is ever written to an app config.
+ */
+export const VENDOR_IDS = ["semrush", "ahrefs"];
+export const VENDORS = {
+    semrush: {
+        id: "semrush",
+        label: "Semrush",
+        name: "semrush",
+        url: "https://mcp.semrush.com/v2/mcp",
+        notice: "This adds Semrush's own MCP server to your AI app. You sign in to Semrush in the app (OAuth). Its calls spend your Semrush API units directly; crawlmark's caps, cache and reports don't cover them.",
+    },
+    ahrefs: {
+        id: "ahrefs",
+        label: "Ahrefs",
+        name: "ahrefs",
+        url: "https://api.ahrefs.com/mcp/mcp",
+        notice: "This adds Ahrefs' own MCP server to your AI app. You sign in to Ahrefs in the app (OAuth). Its calls spend your Ahrefs API units directly (per Ahrefs' docs, it needs a paid plan from Lite, and OAuth creates a key limited to 200,000 units a month by default); crawlmark's caps, cache and reports don't cover them.",
+    },
+};
+const isRecord = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+/** Claude Code: `claude mcp add --transport http -s user <name> <url>` (argv after `claude`). */
+export function claudeCodeVendorArgs(v) {
+    return ["mcp", "add", "--transport", "http", "-s", "user", v.name, v.url];
+}
+/** Codex: `codex mcp add <name> --url <url>` (argv after `codex`). */
+export function codexVendorArgs(v) {
+    return ["mcp", "add", v.name, "--url", v.url];
+}
+/** Cursor's `mcpServers` entry. */
+export function cursorVendorEntry(v) {
+    return { url: v.url };
+}
+/** Parse `claude mcp get <name>`: its URL (HTTP/SSE servers) or Command (stdio), and scope. */
+export function parseClaudeVendorGet(stdout) {
+    const text = stdout.replace(/\u001b\[[0-9;]*m/g, "");
+    const url = /^\s*URL:\s*(\S+)/im.exec(text)?.[1];
+    const command = /^\s*Command:\s*(.+)$/im.exec(text)?.[1]?.trim();
+    const scopeText = /^\s*Scope:\s*(\w+)/im.exec(text)?.[1]?.toLowerCase();
+    const scope = scopeText?.startsWith("user") ? "user" : scopeText?.startsWith("local") ? "local" : scopeText?.startsWith("project") ? "project" : undefined;
+    if (!url && !command)
+        return undefined;
+    return { ...(url ? { url } : {}), ...(command ? { command } : {}), ...(scope ? { scope } : {}) };
+}
+/** Parse `codex mcp get <name> --json`: a streamable-HTTP server's URL, or a stdio server's command. */
+export function parseCodexVendorGet(stdout) {
+    let data;
+    try {
+        data = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(data))
+        return undefined;
+    const t = isRecord(data.transport) ? data.transport : data;
+    if (typeof t.url === "string" && t.url)
+        return { url: t.url };
+    if (typeof t.command === "string" && t.command)
+        return { command: t.command };
+    return undefined;
+}
+/** `mcp_servers.<name>` in config.toml text (read-only). */
+export function readCodexVendorToml(text, name) {
+    if (text === undefined || text.trim() === "")
+        return { kind: "absent" };
+    let parsed;
+    try {
+        parsed = parseToml(text);
+    }
+    catch {
+        return { kind: "unreadable" };
+    }
+    const servers = isRecord(parsed) ? parsed.mcp_servers : undefined;
+    if (servers === undefined)
+        return { kind: "absent" };
+    if (!isRecord(servers))
+        return { kind: "unreadable" };
+    const e = servers[name];
+    if (e === undefined)
+        return { kind: "absent" };
+    if (!isRecord(e))
+        return { kind: "unreadable" };
+    if (typeof e.url === "string")
+        return { kind: "entry", url: e.url };
+    if (typeof e.command === "string")
+        return { kind: "entry", command: e.command };
+    return { kind: "unreadable" };
+}
+/** The block a user can paste into config.toml. */
+export function codexVendorSnippet(v) {
+    return `[mcp_servers.${v.name}]\nurl = ${JSON.stringify(v.url)}`;
+}
+/**
+ * Add `[mcp_servers.<name>] url = "..."` to config.toml text (pure). Only an absent entry is added (appended after a
+ * blank line, every other byte untouched, then re-parsed: other servers and keys must be deep-equal and the entry must
+ * be the intended one). The same URL already there is "no change". A different entry is refused: with no CLI the wizard
+ * never rewrites a table it didn't write.
+ */
+export function planCodexVendorTomlEdit(existing, v) {
+    const source = existing ?? "";
+    let before;
+    try {
+        before = parseToml(source);
+    }
+    catch (err) {
+        return { ok: false, reason: `The Codex config isn't valid TOML (${err.message.split("\n")[0]}); fix it by hand first.` };
+    }
+    const servers = before.mcp_servers;
+    if (servers !== undefined && !isRecord(servers))
+        return { ok: false, reason: "The Codex config's mcp_servers isn't a table; fix it by hand first." };
+    const current = (servers ?? {});
+    const otherServers = Object.keys(current).filter((k) => k !== v.name);
+    const intended = { url: v.url };
+    if (current[v.name] !== undefined) {
+        if (tomlEqual(current[v.name], intended))
+            return { ok: true, text: source, changed: false, otherServers };
+        return { ok: false, reason: `The Codex config already has a different ${v.name} entry; change it by hand.` };
+    }
+    const eol = source.includes("\r\n") ? "\r\n" : "\n";
+    const block = codexVendorSnippet(v).split("\n").map((l) => l + eol).join("");
+    const endsWithNewline = /\n$/.test(source);
+    const endsWithBlankLine = /\n[ \t]*\r?\n$/.test(source);
+    const lead = source === "" ? "" : (endsWithNewline ? "" : eol) + (endsWithBlankLine ? "" : eol);
+    const text = source + lead + block;
+    let after;
+    try {
+        after = parseToml(text);
+    }
+    catch {
+        return { ok: false, reason: "The edited Codex config wouldn't parse, so nothing was changed. Add the entry by hand." };
+    }
+    const afterServers = isRecord(after.mcp_servers) ? after.mcp_servers : {};
+    const ok = [...new Set([...Object.keys(before), ...Object.keys(after)])].every((k) => k === "mcp_servers" || tomlEqual(before[k], after[k])) &&
+        Object.keys(current).every((k) => tomlEqual(current[k], afterServers[k])) &&
+        tomlEqual(afterServers[v.name], intended);
+    if (!ok)
+        return { ok: false, reason: "The edit would have changed more than the new entry, so nothing was changed. Add the entry by hand." };
+    return { ok: true, text, changed: true, otherServers };
+}
+/** Claude Desktop can't take remote servers in its JSON config: the exact steps for the app's own UI. */
+export function desktopConnectorSteps(v) {
+    return [
+        "1. Open Claude Desktop, then Settings > Connectors.",
+        '2. Choose "Add custom connector".',
+        `3. Name: ${v.label}`,
+        `4. URL: ${v.url}`,
+        `5. Save, then sign in to ${v.label} when Claude Desktop asks (OAuth).`,
+    ];
+}
+//# sourceMappingURL=vendor-mcp.js.map

package/dist/prompts/templates/keyword-research.md

@@ -8,7 +8,7 @@ Keyword ideas and competitor gaps are **paid** through the client's SEO data pro
    - If `wouldExceed` is true, read me the `message`: it names a smaller `limit` that fits (`fits`), or the cap to raise. Offer the smaller limit; never raise a cap yourself.
 4. **Ask.** Ask whether to run it. Don't call the tool without `estimateOnly` until I say yes. After a yes, call it with exactly the arguments I agreed to.
 5. **Present.** Group the results by search intent: use `intent` when the provider gives it (DataForSEO), otherwise infer it from the wording (informational: how, what, why, cost, ideas; commercial: best, vs, reviews, near me; transactional: buy, hire, quote, service, price; navigational: brand names). For each group, show a short table: keyword, monthly volume, difficulty (name the scale from `difficulty.metric`: "dataforseo_kd", "ahrefs_kd" and "semrush_kd" are different 0-100 scales, never compare them) and, for a gap, which competitors rank and where. Then suggest which existing page from step 1 should target each group, or say a new page is needed when none fits. Quote volumes as numbers, not adjectives.
-   - Mention any `notes` (for example Semrush returning fewer lines than asked, which can mean a low unit balance, or Ahrefs using the client's Search Console to drop keywords it already ranks for), the actual cost (`costUsd` or `units`), and `fromCache`.
+   - Mention any `notes` (for example Ahrefs using the client's Search Console to drop keywords it already ranks for), the actual cost (`costUsd` or `units`), and `fromCache`.
 6. **Track (optional).** Ask whether to track any of the keywords. Only after I name them, call `add_keywords` for `{{client}}` with those keywords and `source: "suggested"`. Tracked keywords show up in `check_ranks`, `rank_history` and monthly reports.
 
 Prefer the free tools (Search Console, the saved lists) where they answer the question. If a tool returns an error or the data is unavailable (no key for the client's provider, no country for Ahrefs or Semrush, no competitors saved), give me the error and its fix in plain words instead of guessing or switching to another provider. Keep the conversation brief.

package/dist/providers/ahrefs-shape.js

@@ -5,8 +5,8 @@
  *
  * Source of truth: docs/research/ahrefs-api-v3.md (Ahrefs' OpenAPI spec and guides,
  * accessed 2026-10-13). Parameter names, enums, field costs and headers come from
- * there; anything listed under its "Not confirmed" takes the spec's safe reading
- * (specs/2026-10-13-1500-phase-9-seo-data-providers.md 9.11 N1-N6), marked below.
+ * there; anything listed under its "Not confirmed" takes the spec's safe reading,
+ * marked below.
  */
 import { stripControl } from "../lib/terminal-text.js";
 const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);

package/dist/providers/semrush-shape.js

@@ -1,94 +1,13 @@
-/**
- * Pure Semrush helpers (Phase 9): the v3 CSV parser with header checking, error
- * parsing and classification (v3 `ERROR n :: text` bodies and v4 JSON errors), the
- * balance parser, unit prices and estimates, and mappers to crawlmark's types. No I/O.
- *
- * Source of truth: docs/research/semrush-api.md (Semrush developer docs, accessed
- * 2026-10-13). Column codes and header texts, report prices, error codes and the
- * database list come from there; items under its "Not confirmed" take the spec's safe
- * reading (specs/2026-10-13-1500-phase-9-seo-data-providers.md 9.11 N7-N15), marked below.
- */
-import { stripControl } from "../lib/terminal-text.js";
-// ------------------------------------------------------------------ columns and prices
-/** v3 column code -> the display-name header Semrush returns for it ("Column names can't be changed"). */
-export const SEMRUSH_HEADER_TEXT = {
-    Ph: "Keyword",
-    Nq: "Search Volume",
-    Cp: "CPC",
-    Co: "Competition",
-    Nr: "Number of Results",
-    Td: "Trends",
-    Po: "Position",
-    Pp: "Previous Position",
-    Pd: "Position Difference",
-    Ur: "Url",
-    Tr: "Traffic (%)",
-    Tg: "Traffic",
-    Tc: "Traffic Cost (%)",
-    Dn: "Domain",
-    Cr: "Competitor Relevance",
-    Np: "Common Keywords",
-    Or: "Organic Keywords",
-    Ot: "Organic Traffic",
-    Oc: "Organic Cost",
-    Ad: "Adwords Keywords",
-    // Phase 12 B (keyword reports and domain_domains). Not confirmed: the Kd header text (see SEMRUSH_HEADER_ALTERNATES).
-    Kd: "Keyword Difficulty",
-    // v3 backlinks_overview returns its export_columns names as the header.
-    ascore: "ascore",
-    total: "total",
-    domains_num: "domains_num",
-    // Phase 13 B: domain_rank_history's date column.
-    Dt: "Date",
-};
-/**
- * Other header texts accepted for a column whose exact header isn't documented (Phase 12 B, to confirm in the
- * live check): Kd has appeared as "Keyword Difficulty Index" in older Semrush output.
- */
-export const SEMRUSH_HEADER_ALTERNATES = {
-    Kd: ["Keyword Difficulty Index"],
-};
-export const SEMRUSH_COLUMNS = {
-    phrase_these: ["Ph", "Nq", "Cp", "Co"],
-    /** Tg is estimated traffic (visits); Tr is a percentage share and is never requested. */
-    domain_organic: ["Ph", "Po", "Nq", "Ur", "Tg"],
-    domain_organic_organic: ["Dn", "Np", "Ot"],
-    backlinks_overview: ["ascore", "total", "domains_num"],
-    /** Phase 12 B keyword ideas: phrase_related (40/line) and phrase_fullsearch (20/line). */
-    phrase_related: ["Ph", "Nq", "Cp", "Co", "Kd"],
-    phrase_fullsearch: ["Ph", "Nq", "Cp", "Co", "Kd"],
-    /** Phase 12 B keyword gap (Domain vs Domain): P0 is the first domain's position (the competitor), P1 the client's. */
-    domain_domains: ["Ph", "P0", "P1", "Nq", "Kd"],
-    /** Phase 13 B: organic visibility now (domain_rank, 10/line), monthly history (domain_rank_history, 10/line) and competitors with their keyword counts. */
-    domain_rank: ["Dn", "Or", "Ot"],
-    domain_rank_history: ["Dt", "Or", "Ot"],
-    domain_organic_organic_full: ["Dn", "Np", "Or", "Ot"],
-};
 export const SEMRUSH_V4_BACKLINK_FIELDS = ["backlinks_count", "domains_count", "new_count", "lost_count", "score"];
-/** Documented prices: per line returned for the reports, per request for the backlinks overviews. */
+/** Documented prices per request: the v4 backlinks overview and v4 Get Keyword Metrics (one keyword each). */
 export const SEMRUSH_UNITS = {
-    phrase_these: 10,
-    domain_organic: 10,
-    domain_organic_organic: 40,
     backlinks_overview_v4: 45,
-    backlinks_overview_v3: 40,
-    phrase_related: 40,
-    phrase_fullsearch: 20,
-    domain_domains: 80,
-    domain_rank: 10,
-    domain_rank_history: 10,
+    keyword_metrics_v4: 20,
 };
-const PER_REQUEST = new Set(["backlinks_overview_v4", "backlinks_overview_v3"]);
-/** Units for `lines` returned (per-line reports) or one request (backlinks). Empty responses cost nothing. */
-export function estimateSemrushUnits(type, lines) {
-    if (PER_REQUEST.has(type))
-        return lines > 0 ? SEMRUSH_UNITS[type] : 0;
-    return SEMRUSH_UNITS[type] * Math.max(0, lines);
-}
 /**
- * A keyword list made safe to price and send: entries split on `;` (Semrush's phrase separator)
- * and line breaks, trimmed, empties dropped and exact duplicates removed. Estimates, batches and
- * cache keys all use this list, so one entry can't smuggle in extra billed keywords.
+ * A keyword list made safe to price and send: entries split on `;` and line breaks, trimmed, empties dropped and exact
+ * duplicates removed. Estimates, requests and cache keys all use this list, so one entry can't smuggle in extra billed
+ * keywords. (Shared with Ahrefs.)
  */
 export function normalizeKeywordList(keywords) {
     const out = [];
@@ -104,79 +23,7 @@ export function normalizeKeywordList(keywords) {
     }
     return out;
 }
-/** Keywords per phrase_these request ("up to 100 keywords"). */
-export const SEMRUSH_KEYWORD_BATCH = 100;
-// ------------------------------------------------------------------ CSV
-export class SemrushFormatError extends Error {
-    name = "SemrushFormatError";
-}
-/** Split one CSV line on `;`, honouring double-quoted fields (export_escape=1, with "" as an escaped quote). */
-function splitLine(line) {
-    const out = [];
-    let cur = "";
-    let quoted = false;
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-        if (quoted) {
-            if (ch === '"' && line[i + 1] === '"') {
-                cur += '"';
-                i++;
-            }
-            else if (ch === '"')
-                quoted = false;
-            else
-                cur += ch;
-        }
-        else if (ch === '"' && cur === "")
-            quoted = true;
-        else if (ch === ";") {
-            out.push(cur);
-            cur = "";
-        }
-        else
-            cur += ch;
-    }
-    out.push(cur);
-    return out;
-}
-/**
- * Parse a v3 report: semicolon-separated, header row first (display names, not codes).
- * Columns are mapped by the position of the `exportColumns` crawlmark sent, and each
- * header cell is checked against SEMRUSH_HEADER_TEXT, so a changed format is a
- * SemrushFormatError, never a silent mis-map. Commas inside a field (the Trends
- * value), CRLF, a trailing newline and quoted fields are fine. Extra trailing columns are ignored.
- */
-export function parseSemrushCsv(text, exportColumns, 
-/** Extra header checks for columns whose header isn't a fixed text (domain_domains' P0/P1 name the domains). */
-accept = {}) {
-    const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/).filter((l) => l.trim() !== "");
-    if (lines.length === 0)
-        return [];
-    const header = splitLine(lines[0]).map((h) => h.trim());
-    exportColumns.forEach((code, i) => {
-        const custom = accept[code];
-        if (custom) {
-            if (!custom(header[i] ?? ""))
-                throw new SemrushFormatError(`Semrush returned an unexpected header: column ${i + 1} is ${JSON.stringify(header[i] ?? "(missing)")} for ${code}.`);
-            return;
-        }
-        const want = SEMRUSH_HEADER_TEXT[code];
-        if (want === undefined)
-            throw new SemrushFormatError(`Unknown Semrush column code ${code}.`);
-        if (header[i] !== want && !(SEMRUSH_HEADER_ALTERNATES[code] ?? []).includes(header[i] ?? "")) {
-            throw new SemrushFormatError(`Semrush returned an unexpected header: column ${i + 1} is ${JSON.stringify(header[i] ?? "(missing)")}, expected ${JSON.stringify(want)} for ${code}.`);
-        }
-    });
-    return lines.slice(1).map((line) => {
-        const cells = splitLine(line);
-        return Object.fromEntries(exportColumns.map((code, i) => [code, (cells[i] ?? "").trim()]));
-    });
-}
-/** A v3 error body, `ERROR <n> :: <text>` (whatever the HTTP status: N10), else null. */
-export function parseSemrushError(text) {
-    const m = /^\s*ERROR (\d+) :: (.*)/s.exec(text);
-    return m ? { code: Number(m[1]), text: m[2].trim() } : null;
-}
+// ------------------------------------------------------------------ errors
 /** A v4 JSON error body: `{ meta, error: { code, message, retryable } }`, else null. */
 export function parseSemrushV4Error(json) {
     const j = json;
@@ -190,42 +37,20 @@ export function parseSemrushV4Error(json) {
         status: typeof j.meta?.status_code === "number" ? j.meta.status_code : null,
     };
 }
-const KEY_REJECTED = "Semrush rejected the API key (SEMRUSH_API_KEY, or SEMRUSH_V4_API_KEY for v4 calls).";
-const DISABLED = "Semrush API is not enabled for this account or report (needs an SEO Business plan plus an API unit package).";
-const ZERO_BALANCE = "Semrush API units balance is zero; buy units under Subscription info > API units.";
+export const KEY_REJECTED = "Semrush rejected the API key. crawlmark uses Semrush's v4 API: create a key under your profile > API keys and run setup --step semrush.";
+const ZERO_BALANCE = "Semrush API units balance is zero; check your units under Subscription info > API units.";
 const RATE = "Semrush request limit hit (10 requests/s, 10 at once); try again shortly.";
-/** The user-facing message for a v3 error code (spec 9.2). `text` is already redacted. */
-export function classifySemrushError(e, database) {
-    const c = e.code;
-    if (c === 110 || c === 120 || c === 402)
-        return { kind: "auth", message: KEY_REJECTED };
-    if (c === 130 || c === 135)
-        return { kind: "disabled", message: DISABLED };
-    if (c === 132)
-        return { kind: "balance", message: ZERO_BALANCE };
-    if (c === 131 || c === 134 || c === 429)
-        return { kind: "rate", message: RATE };
-    if (c === 133)
-        return { kind: "database", message: `Semrush denied access to database ${database ?? "(unknown)"} on this plan.` };
-    if ((c >= 40 && c <= 46) || (c >= 10000 && c <= 10040) || c === 605 || c === 613) {
-        return { kind: "request", message: `Semrush rejected the request (${c}: ${e.text}). This is likely a crawlmark bug; please report it.` };
-    }
-    return { kind: "server", message: `Semrush error ${c}: ${e.text}` };
-}
 /**
- * A v4 error (HTTP status plus the JSON body). N11: how ERROR 132 shows up on v4 isn't
- * documented, so error.code 132, or a 403 whose message mentions units, is the zero balance;
- * any other 403 is "not enabled".
+ * A v4 error (HTTP status plus the JSON body). How a zero balance shows up on v4 isn't documented, so error.code 132,
+ * or a 403 whose message mentions units, is the zero balance; 401 and any other 403 are a rejected key.
  */
 export function classifySemrushV4Error(status, body) {
     const code = body?.code ?? status;
     const message = body?.message ?? "";
     if (code === 132 || (status === 403 && /unit/i.test(message)))
         return { kind: "balance", message: ZERO_BALANCE };
-    if (status === 401 || code === 401)
+    if (status === 401 || status === 403 || code === 401 || code === 403)
         return { kind: "auth", message: KEY_REJECTED };
-    if (status === 403 || code === 403)
-        return { kind: "disabled", message: DISABLED };
     if (status === 429 || code === 429)
         return { kind: "rate", message: RATE };
     if (status === 400 || status === 404 || status === 409) {
@@ -233,54 +58,22 @@ export function classifySemrushV4Error(status, body) {
     }
     return { kind: "server", message: `Semrush v4 error ${code}: ${message || `HTTP ${status}`}` };
 }
-/** The countapiunits body: a number with thousands separators and whitespace (N9), e.g. `1,000\n` -> 1000. Null if it isn't one. */
-export function parseUnitsBalance(text) {
-    const t = text.replace(/[\s,]/g, "");
-    return /^\d+$/.test(t) ? Number(t) : null;
-}
 // ------------------------------------------------------------------ mappers
-const num = (v) => {
-    if (v === undefined || v.trim() === "")
-        return null;
-    const n = Number(v);
-    return Number.isFinite(n) ? n : null;
-};
-const str = (v) => (v && v.trim() !== "" ? v.trim() : null);
-/** Co (0-1 competitive density) -> LOW (< 0.34), MEDIUM (< 0.67), HIGH. */
+/** Co / competitive density (0-1) -> LOW (< 0.34), MEDIUM (< 0.67), HIGH. */
 export function competitionLevel(co) {
     if (co === null)
         return null;
     return co < 0.34 ? "LOW" : co < 0.67 ? "MEDIUM" : "HIGH";
 }
-/** phrase_these rows -> KeywordVolume, in request order; a keyword with no line comes back with nulls (N13). Cp is already USD. */
-export function mapSemrushKeywordVolumes(rows, requested) {
-    const byKey = new Map();
-    for (const r of rows) {
-        const keyword = str(r.Ph);
-        if (!keyword)
-            continue;
-        byKey.set(keyword.toLowerCase(), { keyword, search_volume: num(r.Nq), competition: competitionLevel(num(r.Co)), cpc: num(r.Cp) });
-    }
-    return requested.map((k) => byKey.get(k.toLowerCase()) ?? { keyword: k, search_volume: null, competition: null, cpc: null });
-}
-/** domain_organic rows -> RankedKeywordsResult. Position 0 means not ranked (null). Tg is the traffic estimate. */
-export function mapSemrushRankedKeywords(rows, target) {
-    const items = rows.flatMap((r) => {
-        const keyword = str(r.Ph);
-        const pos = num(r.Po);
-        return keyword ? [{ keyword, position: pos === 0 ? null : pos, searchVolume: num(r.Nq), url: str(r.Ur), estimatedTraffic: num(r.Tg) }] : [];
-    });
-    return { target, totalCount: items.length, items };
-}
-/** domain_organic_organic rows -> CompetitorsResult (avgPosition null). */
-export function mapSemrushCompetitors(rows, target) {
-    const items = rows.flatMap((r) => {
-        const domain = str(r.Dn);
-        return domain ? [{ domain, intersectingKeywords: num(r.Np), avgPosition: null, estimatedTraffic: num(r.Ot) }] : [];
-    });
-    return { target, totalCount: items.length, items };
-}
 const jnum = (v) => (typeof v === "number" && Number.isFinite(v) ? v : typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v)) ? Number(v) : null);
+/** Sent with v4 keyword metrics: cpc's unit and competitive_density's scale aren't documented. */
+export const SEMRUSH_V4_METRICS_NOTE = "Semrush v4 keyword metrics are Early Access. cpc is passed through as Semrush returns it (its unit isn't documented; the sample value 1245 may be cents), and competition is derived from competitive_density read as 0-100 (also undocumented).";
+/** v4 Get Keyword Metrics response -> KeywordVolume (search_volume and cpc arrive as strings). */
+export function mapSemrushKeywordMetricsV4(json, keyword) {
+    const d = (json?.data ?? {});
+    const density = jnum(d.competitive_density);
+    return { keyword, search_volume: jnum(d.search_volume), competition: competitionLevel(density === null ? null : density / 100), cpc: jnum(d.cpc) };
+}
 /** v4 backlinks overview `data` -> BacklinksSummary (new/lost from new_count/lost_count; `score` as semrush_score). */
 export function mapSemrushBacklinksV4(json, target) {
     const d = (json?.data ?? {});
@@ -295,91 +88,4 @@ export function mapSemrushBacklinksV4(json, target) {
         authority: { metric: "semrush_score", value: jnum(d.score) },
     };
 }
-/** v3 backlinks_overview row -> BacklinksSummary (no new/lost in v3; `ascore` as semrush_score). Null when there is no row. */
-export function mapSemrushBacklinksV3(rows, target) {
-    const r = rows[0];
-    if (!r)
-        return null;
-    return {
-        target,
-        backlinks: num(r.total),
-        referringDomains: num(r.domains_num),
-        rank: null,
-        spamScore: null,
-        newBacklinks: null,
-        lostBacklinks: null,
-        authority: { metric: "semrush_score", value: num(r.ascore) },
-    };
-}
-/** D13: a per-line report shorter than requested may have been cut short by a low balance. */
-export function partialLinesNote(returned, requested) {
-    return returned < requested
-        ? `Semrush returned ${returned} of ${requested} requested lines; if your unit balance is low, results may be cut short (semrush_status shows the balance).`
-        : undefined;
-}
-// ------------------------------------------------------------------ keyword ideas and gap (Phase 12 B)
-/** phrase_related / phrase_fullsearch rows -> ideas (Cp is USD; Co is 0-1; Kd is Semrush's 0-100 difficulty). */
-export function mapSemrushIdeas(rows, seed) {
-    return rows.flatMap((r) => {
-        const keyword = str(r.Ph)?.replace(/\s+/g, " ");
-        return keyword ? [{ keyword, volume: num(r.Nq), cpc: num(r.Cp), competition: num(r.Co), difficulty: { metric: "semrush_kd", value: num(r.Kd) }, intent: null, seed }] : [];
-    });
-}
-/** `*|or|<competitor>|-|or|<client>`: keywords the competitor has and the client lacks (research S2). */
-export const domainVsDomain = (competitor, client) => `*|or|${competitor}|-|or|${client}`;
-/**
- * domain_domains rows -> gap rows. P0 is the competitor's position (0 means not ranked: null); Semrush
- * gives no URL in this report (null).
- */
-export function mapSemrushGapRows(rows) {
-    return rows.flatMap((r) => {
-        const keyword = str(r.Ph)?.replace(/\s+/g, " ");
-        const pos = num(r.P0);
-        return keyword ? [{ keyword, volume: num(r.Nq), difficulty: num(r.Kd), position: pos === 0 ? null : pos, url: null }] : [];
-    });
-}
-/**
- * Not confirmed (live check): the header text of domain_domains' position columns. Accepted: the domain
- * itself (any case, with or without www.), the column code, or a text naming a position.
- */
-export function positionHeaderFor(domain, code) {
-    const d = domain.toLowerCase().replace(/^www\./, "");
-    return (h) => {
-        const t = h.trim().toLowerCase().replace(/^www\./, "");
-        return t === d || t === code.toLowerCase() || /position/.test(t);
-    };
-}
-// ------------------------------------------------------------------ Phase 13 B: visibility, history, competitors
-export const SEMRUSH_TRAFFIC_LABEL = "Semrush organic traffic";
-/** D6: Semrush's API reports no keywords by position band, so the bands are null. */
-const NO_BANDS = { top3: null, pos4_10: null, pos11_20: null, pos21_100: null };
-/** domain_rank's one line -> visibility figures (Or keywords, Ot traffic; bands null). Null figures when there is no line. */
-export function mapSemrushVisibility(rows) {
-    const r = rows[0];
-    return { keywords: num(r?.Or), ...NO_BANDS, traffic: num(r?.Ot), trafficLabel: SEMRUSH_TRAFFIC_LABEL };
-}
-/** domain_rank_history lines (Dt is YYYYMMDD; Semrush dates monthly points mid-month) -> points, oldest first. */
-export function mapSemrushVisibilityHistory(rows) {
-    const out = [];
-    for (const r of rows) {
-        const m = /^(\d{4})(\d{2})(\d{2})$/.exec((r.Dt ?? "").trim());
-        if (!m)
-            continue;
-        out.push({ day: `${m[1]}-${m[2]}-${m[3]}`, keywords: num(r.Or), ...NO_BANDS, traffic: num(r.Ot), trafficLabel: SEMRUSH_TRAFFIC_LABEL });
-    }
-    return out.sort((a, b) => a.day.localeCompare(b.day));
-}
-/** domain_organic_organic (Dn, Np, Or, Ot) -> competitors; the target and empty domains dropped; domains stripControl'd. */
-export function mapSemrushCompetitorsFull(rows, target) {
-    const own = target.toLowerCase().replace(/^www\./, "");
-    const out = [];
-    for (const r of rows) {
-        const raw = str(r.Dn);
-        const domain = raw ? stripControl(raw).trim().toLowerCase().replace(/^www\./, "") : null;
-        if (!domain || domain === own || out.some((o) => o.domain === domain))
-            continue;
-        out.push({ domain, commonKeywords: num(r.Np), keywords: num(r.Or), traffic: num(r.Ot), inProviderList: true });
-    }
-    return out;
-}
 //# sourceMappingURL=semrush-shape.js.map