@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/marketing.mjs

@@ -1,396 +1,396 @@
-/**
- * Tool family: marketing - being found, and the list you already own.
- *
- * Workstream B1. Before this family a client's Claude could see their pipeline,
- * their diary and their money, and had no idea KM Hub also ran their search
- * visibility and their newsletter. Asked "does it do my newsletter" it answered
- * from its tool list and understated the product by a whole department.
- *
- *   km_list_seo_sites    -> GET /marketing/seo/sites
- *   km_list_seo_posts    -> GET /marketing/seo/posts
- *   km_get_seo_post      -> GET /marketing/seo/posts/:id
- *   km_list_newsletters  -> GET /marketing/newsletters
- *   km_get_newsletter    -> GET /marketing/newsletters/:id
- *   km_newsletter_audience -> GET /marketing/audience
- *   km_list_broadcasts   -> GET /marketing/broadcasts
- *   km_lists             -> GET /marketing/lists
- *   km_import_list       -> POST /marketing/lists/import   (free)
- *
- * 🚨 NOTHING HERE SENDS. No tool in this family sends a newsletter, publishes a
- * post, or changes a schedule: a send is irreversible against a list somebody
- * spent years building. When a user asks to send, say plainly that it happens
- * in KM Hub and do not look for another route to it.
- *
- * BUILDING a list is allowed (16-Sep-2026). "If I give you a CSV can you create
- * lists for me inside kmhub" was being answered "no" from the tool list, and the
- * answer is yes: km_import_list takes the file's rows, files each person as a
- * client tagged with the list name, and saves the segment. It is 'free' class -
- * internal, reversible, nobody outside sees it.
- *
- * These routes ship on the API side separately from this connector, so each tool
- * degrades in plain words when the route is not there yet: an older KM Hub is not
- * a broken KM Hub.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-import { readFileSync } from 'node:fs';
-
-export const FAMILY = 'marketing';
-
-export const TOOLS = [
-  'km_list_seo_sites',
-  'km_list_seo_posts',
-  'km_get_seo_post',
-  'km_list_newsletters',
-  'km_get_newsletter',
-  'km_newsletter_audience',
-  'km_list_broadcasts',
-  'km_lists',
-  'km_import_list',
-];
-
-/** Rows per import call, matching the API's IMPORT_MAX_ROWS. Bigger files are chunked. */
-const IMPORT_CHUNK = 500;
-
-/**
- * RFC 4180 CSV -> array of objects keyed by the header row. Quoted fields, doubled
- * quotes, embedded newlines and a BOM are handled; the delimiter (',' ';' or tab)
- * is sniffed from the header line. No dependency: the connector ships with none
- * it does not need.
- */
-export function parseCsv(input) {
-  const src = String(input || '').replace(/^/, '');
-  const firstLine = src.split(/\r?\n/, 1)[0] || '';
-  const delim = [',', ';', '\t']
-    .map((d) => [d, firstLine.split(d).length - 1])
-    .sort((a, b) => b[1] - a[1])[0][0];
-  const rows = [];
-  let row = [];
-  let field = '';
-  let quoted = false;
-  for (let i = 0; i < src.length; i += 1) {
-    const c = src[i];
-    if (quoted) {
-      if (c === '"') {
-        if (src[i + 1] === '"') { field += '"'; i += 1; } else quoted = false;
-      } else field += c;
-      continue;
-    }
-    if (c === '"') { quoted = true; continue; }
-    if (c === delim) { row.push(field); field = ''; continue; }
-    if (c === '\r') continue;
-    if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; continue; }
-    field += c;
-  }
-  if (field !== '' || row.length) { row.push(field); rows.push(row); }
-  const nonEmpty = rows.filter((r) => r.some((v) => String(v).trim() !== ''));
-  if (nonEmpty.length < 2) return { headers: nonEmpty[0] || [], rows: [] };
-  const headers = nonEmpty[0].map((h) => String(h).trim());
-  return {
-    headers,
-    rows: nonEmpty.slice(1).map((r) => Object.fromEntries(headers.map((h, i) => [h, String(r[i] ?? '').trim()]))),
-  };
-}
-
-/** Map whatever the file calls its columns onto the fields the API takes. */
-const COLUMN_ALIASES = {
-  email: ['email', 'e-mail', 'email address', 'emailaddress', 'mail', 'primary email', 'email_address'],
-  name: ['name', 'full name', 'fullname', 'contact', 'contact name', 'client', 'client name', 'customer', 'customer name'],
-  first_name: ['first name', 'first', 'firstname', 'first_name', 'given name'],
-  last_name: ['last name', 'last', 'lastname', 'last_name', 'surname', 'family name'],
-  phone: ['phone', 'phone number', 'mobile', 'cell', 'telephone', 'tel', 'phone_number'],
-  company: ['company', 'company name', 'organization', 'organisation', 'business', 'business name', 'company_name'],
-};
-
-export function mapColumns(headers) {
-  const lower = headers.map((h) => String(h).trim().toLowerCase());
-  const map = {};
-  for (const [field, aliases] of Object.entries(COLUMN_ALIASES)) {
-    const idx = lower.findIndex((h) => aliases.includes(h));
-    if (idx >= 0) map[field] = headers[idx];
-  }
-  // Exports rarely agree on a header. Anything with "email" in it still counts.
-  if (!map.email) {
-    const idx = lower.findIndex((h) => h.includes('email') || h.includes('e-mail'));
-    if (idx >= 0) map.email = headers[idx];
-  }
-  return map;
-}
-
-function toApiRows(parsed) {
-  const map = mapColumns(parsed.headers);
-  if (!map.email) {
-    return { error: `No email column found. Columns seen: ${parsed.headers.join(', ') || '(none)'}. Tell me which one holds the address.`, rows: [] };
-  }
-  return {
-    rows: parsed.rows.map((r) => ({
-      email: r[map.email],
-      ...(map.name ? { name: r[map.name] } : {}),
-      ...(map.first_name ? { first_name: r[map.first_name] } : {}),
-      ...(map.last_name ? { last_name: r[map.last_name] } : {}),
-      ...(map.phone ? { phone: r[map.phone] } : {}),
-      ...(map.company ? { company: r[map.company] } : {}),
-    })),
-    mapped: map,
-  };
-}
-
-// 'content' is the profile a client installs when their work is publishing and
-// list-building rather than pipeline chasing.
-export const PROFILES = ['content', 'outreach'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'Your KM Hub does not expose the marketing surface to the terminal yet. That is not a fault: the workspace ' +
-  'is fine and every other tool works as normal. SEO and the newsletter are both there in the web app at ' +
-  'https://hub.kivimedia.co, and this connector will start reading them once your KM Hub is on a build that publishes them.';
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_list_seo_sites',
-    'The websites KM Hub is publishing search content to, and whether it is doing it automatically. ' +
-      'Call this when the user asks about SEO, being found on Google, showing up in AI search, their blog, or why ' +
-      'nothing has been published lately. It returns each connected site, its category, whether weekly autopilot is on, ' +
-      'whether autopilot is allowed to publish by itself, when it last published, and the last error if there was one. ' +
-      'An empty list is a real and important answer: no site connected means nothing is being published at all, and the ' +
-      'user almost certainly does not know that. Connecting a site and changing autopilot happen in KM Hub, not here. ' +
-      'Read only, sends nothing, changes nothing.',
-    {},
-    async () => {
-      const r = await call('GET', '/marketing/seo/sites');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_seo_posts',
-    'The SEO content pipeline: what has been written, what is waiting, what is published and what is stuck. ' +
-      'Use it when the user asks what has been published, what is in the works, why a post has not gone out, or how ' +
-      'their content is doing. Returns the title, target keyword, silo, status, whether it is blocked and why, and the ' +
-      'published URL where there is one, plus a count by status so you can describe the shape of the pipeline in a sentence. ' +
-      '🚨 The article body is NOT included here, on purpose: post bodies are thousands of words and twenty of them would ' +
-      'drown the answer. Use km_get_seo_post for one specific post. Anything blocked is worth raising unprompted, because ' +
-      'a blocked post is silent work that has stopped. Read only.',
-    {
-      status: z
-        .enum(['draft', 'generating', 'ready', 'approved', 'publishing', 'published', 'failed', 'blocked'])
-        .optional()
-        .describe('Narrow to one stage. Leave it out for the whole pipeline, which is usually what you want first.'),
-      limit: z.number().int().min(1).max(100).optional().describe('How many posts, newest first. Default 25.'),
-    },
-    async ({ status, limit }) => {
-      const r = await call('GET', `/marketing/seo/posts${qs({ status, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_get_seo_post',
-    'One SEO post in detail: its outline, its meta title and description, its quality scores, its target and secondary ' +
-      'keywords, and the first part of the body. Use it when the user asks about a specific post, wants to know whether ' +
-      'something is any good before it goes out, or asks why one is blocked. ' +
-      'The body comes back as a preview with the true character count alongside it, so you can say how long the piece is ' +
-      'without carrying all of it. Editing, approving and publishing all happen in KM Hub at https://hub.kivimedia.co: ' +
-      'say so rather than offering to do it. Read only.',
-    {
-      id: z.string().describe('The post id, as km_list_seo_posts returned it.'),
-    },
-    async ({ id }) => {
-      const r = await call('GET', `/marketing/seo/posts/${encodeURIComponent(String(id || '').trim())}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_newsletters',
-    'The newsletter: every issue, with the numbers that actually matter. Use it when the user asks about their ' +
-      'newsletter, their list, their email marketing, whether anyone reads what they send, or what went out last month. ' +
-      'Each issue returns recipients, sent, delivered, opened, clicked, bounced and complained, plus open, click and ' +
-      'bounce rates already worked out against delivered rather than against sent, which is the comparison that is not ' +
-      'misleading. ' +
-      '🚨 A bounce rate creeping up matters more than an open rate going down and almost nobody looks at it: rising ' +
-      'bounces or complaints put the sending domain at risk, which quietly costs every future send. Raise it if you see it. ' +
-      'Nothing here can write, schedule or send an issue. Read only.',
-    {
-      status: z
-        .enum(['draft', 'scheduled', 'sending', 'sent', 'failed'])
-        .optional()
-        .describe('Narrow to one state. "scheduled" answers "what is going out next", "sent" answers "how did it do".'),
-      limit: z.number().int().min(1).max(100).optional().describe('How many issues, newest first. Default 20.'),
-    },
-    async ({ status, limit }) => {
-      const r = await call('GET', `/marketing/newsletters${qs({ status, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_get_newsletter',
-    'One newsletter issue in full: subject, preheader, sender name, send timezone, its A/B test if it ran one, and the ' +
-      'complete delivery numbers. Use it when the user asks about a specific issue or wants to know why one performed ' +
-      'differently from another. The rendered HTML is not returned, because a built email is enormous and unreadable as ' +
-      'text; the subject and preheader are what actually decided the open rate. Read only.',
-    {
-      id: z.string().describe('The newsletter id, as km_list_newsletters returned it.'),
-    },
-    async ({ id }) => {
-      const r = await call('GET', `/marketing/newsletters/${encodeURIComponent(String(id || '').trim())}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_newsletter_audience',
-    'How big the newsletter list is and what state it is in: subscribed, unsubscribed, unconfirmed and so on. ' +
-      'Use it when the user asks how many people they can reach, whether the list is growing, or before advising ' +
-      'anything about sending. ' +
-      '🚨 It returns COUNTS, never the people. Individual subscribers are deliberately not available to the terminal: a ' +
-      'mailing list is the most sensitive asset in the workspace and there is no reason a command line needs to pull it ' +
-      'down. Do not look for another route to the addresses. ' +
-      'A large unconfirmed count is worth raising: those are people who signed up and never completed it, so they are ' +
-      'not being reached at all. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/marketing/audience');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_broadcasts',
-    'One-off sends to the list, as distinct from the regular newsletter: an announcement, a date release, a last-minute ' +
-      'offer. Returns the subject, the audience it went to, its status and how many were sent or failed. ' +
-      'Use it when the user asks what they have sent recently, or when you are about to suggest emailing the list and ' +
-      'need to know whether they already have. Sending one happens in KM Hub at https://hub.kivimedia.co. Read only.',
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many broadcasts, newest first. Default 20.'),
-    },
-    async ({ limit }) => {
-      const r = await call('GET', `/marketing/broadcasts${qs({ limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_lists',
-    'The saved lists: every segment in the workspace with its name, the tag it is built on and a live member count. ' +
-      'Use it when the user asks what lists they have, how big one is, or before importing so you can tell whether ' +
-      'the list already exists (an import into an existing name GROWS it rather than making a second one). ' +
-      'Returns list names and sizes, never the people on them. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/marketing/lists');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_import_list',
-    'Build a list in KM Hub from a CSV or from rows: YES, this is the tool for "here is a CSV, make me a list". ' +
-      'Each person is filed as a client (found by email if they already exist, created if not), tagged with the list ' +
-      'name, and a saved segment with that name is created so the list is ready to pick in Compose & Send, broadcasts ' +
-      'and re-engagement. Re-running with the same list name adds to it and never duplicates a contact. ' +
-      'Give it EITHER csv_text (the file contents, header row included - email / name / first name / last name / ' +
-      'phone / company are picked up by their usual column names) OR rows (already structured) OR csv_path (a file on ' +
-      'the machine this connector runs on - local installs only, not the hosted connector). Files over 500 rows are ' +
-      'sent in chunks automatically. ' +
-      'Report back what it returns: created, tagged_existing, already_on_list and the skipped counts - a row with no ' +
-      'usable email is skipped and listed, not silently lost. Nothing is SENT to anyone: this builds the list only.',
-    {
-      list_name: z.string().min(1).max(120).describe('The list name. Becomes the segment name and the tag on every contact. Reuse a name to grow that list.'),
-      csv_text: z.string().optional().describe('The raw CSV contents including the header row. Preferred when the user pasted or attached the file.'),
-      csv_path: z.string().optional().describe('Absolute path to a CSV on the machine running this connector. Local installs only.'),
-      rows: z
-        .array(
-          z.object({
-            email: z.string(),
-            name: z.string().optional(),
-            first_name: z.string().optional(),
-            last_name: z.string().optional(),
-            phone: z.string().optional(),
-            company: z.string().optional(),
-          }),
-        )
-        .optional()
-        .describe('Structured rows, if you already have them. email is required per row.'),
-      description: z.string().max(500).optional().describe('Shown on the segment card in KM Hub. Defaults to "Imported list (date)".'),
-      source: z.string().max(60).optional().describe('Stamped on created contacts as their source. Defaults to api_import; use e.g. "brevo_export" when you know where the file came from.'),
-    },
-    async ({ list_name, csv_text, csv_path, rows, description, source }) => {
-      let apiRows = Array.isArray(rows) && rows.length ? rows : null;
-      let mapped = null;
-      if (!apiRows) {
-        let raw = csv_text;
-        if (!raw && csv_path) {
-          try {
-            raw = readFileSync(csv_path, 'utf8');
-          } catch (e) {
-            return text(
-              `I could not read ${csv_path} from here (${e.code || e.message}). On the hosted connector the file is on your machine, not mine: paste the file contents as csv_text instead.`,
-              true,
-            );
-          }
-        }
-        if (!raw) return text('Give me the list as csv_text (the file contents), rows, or a csv_path on a local install.', true);
-        const converted = toApiRows(parseCsv(raw));
-        if (converted.error) return text(converted.error, true);
-        apiRows = converted.rows;
-        mapped = converted.mapped;
-      }
-      if (!apiRows.length) return text('The file parsed but had no data rows under the header, so there is nothing to import.', true);
-
-      const totals = { received: 0, created: 0, tagged_existing: 0, already_on_list: 0, invalid_email: 0, duplicate_in_file: 0, tag_failed: 0 };
-      const invalidExamples = [];
-      const problems = [];
-      let list = null;
-      for (let i = 0; i < apiRows.length; i += IMPORT_CHUNK) {
-        const chunk = apiRows.slice(i, i + IMPORT_CHUNK);
-        const chunkNo = i / IMPORT_CHUNK + 1;
-        const r = await call('POST', '/marketing/lists/import', { list_name, rows: chunk, description, source });
-        if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-        if (r.status === 402) return out(r);
-        const d = r.data && typeof r.data === 'object' ? r.data : {};
-        if (!r.ok && r.status !== 207) {
-          problems.push(`chunk ${chunkNo} (rows ${i + 1}-${i + chunk.length}): ${d.message || JSON.stringify(d).slice(0, 300)}`);
-          continue;
-        }
-        totals.received += Number(d.received) || 0;
-        totals.created += Number(d.created) || 0;
-        totals.tagged_existing += Number(d.tagged_existing) || 0;
-        totals.already_on_list += Number(d.already_on_list) || 0;
-        for (const k of ['invalid_email', 'duplicate_in_file', 'tag_failed']) totals[k] += Number(d.skipped?.[k]) || 0;
-        for (const ex of d.invalid_examples || []) if (invalidExamples.length < 10) invalidExamples.push(ex);
-        if (d.insert_error) problems.push(`chunk ${chunkNo}: ${d.note_on_error || d.insert_error}`);
-        if (d.segment_error) problems.push(d.segment_error);
-        if (d.list) list = d.list;
-      }
-      const ok = problems.length === 0 && Boolean(list && list.id);
-      const summary = {
-        ok,
-        list,
-        chunks: Math.ceil(apiRows.length / IMPORT_CHUNK),
-        ...(mapped ? { columns_used: mapped } : {}),
-        ...totals,
-        invalid_examples: invalidExamples,
-        ...(problems.length ? { problems } : {}),
-        where: 'https://hub.kivimedia.co/?page=email-segments',
-        note: ok
-          ? `"${list.name}" now has ${list.members ?? '?'} members and is ready to pick as an audience in KM Hub. Nothing was sent.`
-          : 'The import did not fully land - see problems. Re-sending the same file is safe: existing contacts are tagged, not duplicated.',
-      };
-      return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }], isError: !ok };
-    },
-  );
-}
+/**
+ * Tool family: marketing - being found, and the list you already own.
+ *
+ * Workstream B1. Before this family a client's Claude could see their pipeline,
+ * their diary and their money, and had no idea KM Hub also ran their search
+ * visibility and their newsletter. Asked "does it do my newsletter" it answered
+ * from its tool list and understated the product by a whole department.
+ *
+ *   km_list_seo_sites    -> GET /marketing/seo/sites
+ *   km_list_seo_posts    -> GET /marketing/seo/posts
+ *   km_get_seo_post      -> GET /marketing/seo/posts/:id
+ *   km_list_newsletters  -> GET /marketing/newsletters
+ *   km_get_newsletter    -> GET /marketing/newsletters/:id
+ *   km_newsletter_audience -> GET /marketing/audience
+ *   km_list_broadcasts   -> GET /marketing/broadcasts
+ *   km_lists             -> GET /marketing/lists
+ *   km_import_list       -> POST /marketing/lists/import   (free)
+ *
+ * 🚨 NOTHING HERE SENDS. No tool in this family sends a newsletter, publishes a
+ * post, or changes a schedule: a send is irreversible against a list somebody
+ * spent years building. When a user asks to send, say plainly that it happens
+ * in KM Hub and do not look for another route to it.
+ *
+ * BUILDING a list is allowed (16-Sep-2026). "If I give you a CSV can you create
+ * lists for me inside kmhub" was being answered "no" from the tool list, and the
+ * answer is yes: km_import_list takes the file's rows, files each person as a
+ * client tagged with the list name, and saves the segment. It is 'free' class -
+ * internal, reversible, nobody outside sees it.
+ *
+ * These routes ship on the API side separately from this connector, so each tool
+ * degrades in plain words when the route is not there yet: an older KM Hub is not
+ * a broken KM Hub.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+
+export const FAMILY = 'marketing';
+
+export const TOOLS = [
+  'km_list_seo_sites',
+  'km_list_seo_posts',
+  'km_get_seo_post',
+  'km_list_newsletters',
+  'km_get_newsletter',
+  'km_newsletter_audience',
+  'km_list_broadcasts',
+  'km_lists',
+  'km_import_list',
+];
+
+/** Rows per import call, matching the API's IMPORT_MAX_ROWS. Bigger files are chunked. */
+const IMPORT_CHUNK = 500;
+
+/**
+ * RFC 4180 CSV -> array of objects keyed by the header row. Quoted fields, doubled
+ * quotes, embedded newlines and a BOM are handled; the delimiter (',' ';' or tab)
+ * is sniffed from the header line. No dependency: the connector ships with none
+ * it does not need.
+ */
+export function parseCsv(input) {
+  const src = String(input || '').replace(/^/, '');
+  const firstLine = src.split(/\r?\n/, 1)[0] || '';
+  const delim = [',', ';', '\t']
+    .map((d) => [d, firstLine.split(d).length - 1])
+    .sort((a, b) => b[1] - a[1])[0][0];
+  const rows = [];
+  let row = [];
+  let field = '';
+  let quoted = false;
+  for (let i = 0; i < src.length; i += 1) {
+    const c = src[i];
+    if (quoted) {
+      if (c === '"') {
+        if (src[i + 1] === '"') { field += '"'; i += 1; } else quoted = false;
+      } else field += c;
+      continue;
+    }
+    if (c === '"') { quoted = true; continue; }
+    if (c === delim) { row.push(field); field = ''; continue; }
+    if (c === '\r') continue;
+    if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; continue; }
+    field += c;
+  }
+  if (field !== '' || row.length) { row.push(field); rows.push(row); }
+  const nonEmpty = rows.filter((r) => r.some((v) => String(v).trim() !== ''));
+  if (nonEmpty.length < 2) return { headers: nonEmpty[0] || [], rows: [] };
+  const headers = nonEmpty[0].map((h) => String(h).trim());
+  return {
+    headers,
+    rows: nonEmpty.slice(1).map((r) => Object.fromEntries(headers.map((h, i) => [h, String(r[i] ?? '').trim()]))),
+  };
+}
+
+/** Map whatever the file calls its columns onto the fields the API takes. */
+const COLUMN_ALIASES = {
+  email: ['email', 'e-mail', 'email address', 'emailaddress', 'mail', 'primary email', 'email_address'],
+  name: ['name', 'full name', 'fullname', 'contact', 'contact name', 'client', 'client name', 'customer', 'customer name'],
+  first_name: ['first name', 'first', 'firstname', 'first_name', 'given name'],
+  last_name: ['last name', 'last', 'lastname', 'last_name', 'surname', 'family name'],
+  phone: ['phone', 'phone number', 'mobile', 'cell', 'telephone', 'tel', 'phone_number'],
+  company: ['company', 'company name', 'organization', 'organisation', 'business', 'business name', 'company_name'],
+};
+
+export function mapColumns(headers) {
+  const lower = headers.map((h) => String(h).trim().toLowerCase());
+  const map = {};
+  for (const [field, aliases] of Object.entries(COLUMN_ALIASES)) {
+    const idx = lower.findIndex((h) => aliases.includes(h));
+    if (idx >= 0) map[field] = headers[idx];
+  }
+  // Exports rarely agree on a header. Anything with "email" in it still counts.
+  if (!map.email) {
+    const idx = lower.findIndex((h) => h.includes('email') || h.includes('e-mail'));
+    if (idx >= 0) map.email = headers[idx];
+  }
+  return map;
+}
+
+function toApiRows(parsed) {
+  const map = mapColumns(parsed.headers);
+  if (!map.email) {
+    return { error: `No email column found. Columns seen: ${parsed.headers.join(', ') || '(none)'}. Tell me which one holds the address.`, rows: [] };
+  }
+  return {
+    rows: parsed.rows.map((r) => ({
+      email: r[map.email],
+      ...(map.name ? { name: r[map.name] } : {}),
+      ...(map.first_name ? { first_name: r[map.first_name] } : {}),
+      ...(map.last_name ? { last_name: r[map.last_name] } : {}),
+      ...(map.phone ? { phone: r[map.phone] } : {}),
+      ...(map.company ? { company: r[map.company] } : {}),
+    })),
+    mapped: map,
+  };
+}
+
+// 'content' is the profile a client installs when their work is publishing and
+// list-building rather than pipeline chasing.
+export const PROFILES = ['content', 'outreach'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose the marketing surface to the terminal yet. That is not a fault: the workspace ' +
+  'is fine and every other tool works as normal. SEO and the newsletter are both there in the web app at ' +
+  'https://hub.kivimedia.co, and this connector will start reading them once your KM Hub is on a build that publishes them.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_list_seo_sites',
+    'The websites KM Hub is publishing search content to, and whether it is doing it automatically. ' +
+      'Call this when the user asks about SEO, being found on Google, showing up in AI search, their blog, or why ' +
+      'nothing has been published lately. It returns each connected site, its category, whether weekly autopilot is on, ' +
+      'whether autopilot is allowed to publish by itself, when it last published, and the last error if there was one. ' +
+      'An empty list is a real and important answer: no site connected means nothing is being published at all, and the ' +
+      'user almost certainly does not know that. Connecting a site and changing autopilot happen in KM Hub, not here. ' +
+      'Read only, sends nothing, changes nothing.',
+    {},
+    async () => {
+      const r = await call('GET', '/marketing/seo/sites');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_seo_posts',
+    'The SEO content pipeline: what has been written, what is waiting, what is published and what is stuck. ' +
+      'Use it when the user asks what has been published, what is in the works, why a post has not gone out, or how ' +
+      'their content is doing. Returns the title, target keyword, silo, status, whether it is blocked and why, and the ' +
+      'published URL where there is one, plus a count by status so you can describe the shape of the pipeline in a sentence. ' +
+      '🚨 The article body is NOT included here, on purpose: post bodies are thousands of words and twenty of them would ' +
+      'drown the answer. Use km_get_seo_post for one specific post. Anything blocked is worth raising unprompted, because ' +
+      'a blocked post is silent work that has stopped. Read only.',
+    {
+      status: z
+        .enum(['draft', 'generating', 'ready', 'approved', 'publishing', 'published', 'failed', 'blocked'])
+        .optional()
+        .describe('Narrow to one stage. Leave it out for the whole pipeline, which is usually what you want first.'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many posts, newest first. Default 25.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/marketing/seo/posts${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_get_seo_post',
+    'One SEO post in detail: its outline, its meta title and description, its quality scores, its target and secondary ' +
+      'keywords, and the first part of the body. Use it when the user asks about a specific post, wants to know whether ' +
+      'something is any good before it goes out, or asks why one is blocked. ' +
+      'The body comes back as a preview with the true character count alongside it, so you can say how long the piece is ' +
+      'without carrying all of it. Editing, approving and publishing all happen in KM Hub at https://hub.kivimedia.co: ' +
+      'say so rather than offering to do it. Read only.',
+    {
+      id: z.string().describe('The post id, as km_list_seo_posts returned it.'),
+    },
+    async ({ id }) => {
+      const r = await call('GET', `/marketing/seo/posts/${encodeURIComponent(String(id || '').trim())}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_newsletters',
+    'The newsletter: every issue, with the numbers that actually matter. Use it when the user asks about their ' +
+      'newsletter, their list, their email marketing, whether anyone reads what they send, or what went out last month. ' +
+      'Each issue returns recipients, sent, delivered, opened, clicked, bounced and complained, plus open, click and ' +
+      'bounce rates already worked out against delivered rather than against sent, which is the comparison that is not ' +
+      'misleading. ' +
+      '🚨 A bounce rate creeping up matters more than an open rate going down and almost nobody looks at it: rising ' +
+      'bounces or complaints put the sending domain at risk, which quietly costs every future send. Raise it if you see it. ' +
+      'Nothing here can write, schedule or send an issue. Read only.',
+    {
+      status: z
+        .enum(['draft', 'scheduled', 'sending', 'sent', 'failed'])
+        .optional()
+        .describe('Narrow to one state. "scheduled" answers "what is going out next", "sent" answers "how did it do".'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many issues, newest first. Default 20.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/marketing/newsletters${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_get_newsletter',
+    'One newsletter issue in full: subject, preheader, sender name, send timezone, its A/B test if it ran one, and the ' +
+      'complete delivery numbers. Use it when the user asks about a specific issue or wants to know why one performed ' +
+      'differently from another. The rendered HTML is not returned, because a built email is enormous and unreadable as ' +
+      'text; the subject and preheader are what actually decided the open rate. Read only.',
+    {
+      id: z.string().describe('The newsletter id, as km_list_newsletters returned it.'),
+    },
+    async ({ id }) => {
+      const r = await call('GET', `/marketing/newsletters/${encodeURIComponent(String(id || '').trim())}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_newsletter_audience',
+    'How big the newsletter list is and what state it is in: subscribed, unsubscribed, unconfirmed and so on. ' +
+      'Use it when the user asks how many people they can reach, whether the list is growing, or before advising ' +
+      'anything about sending. ' +
+      '🚨 It returns COUNTS, never the people. Individual subscribers are deliberately not available to the terminal: a ' +
+      'mailing list is the most sensitive asset in the workspace and there is no reason a command line needs to pull it ' +
+      'down. Do not look for another route to the addresses. ' +
+      'A large unconfirmed count is worth raising: those are people who signed up and never completed it, so they are ' +
+      'not being reached at all. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/marketing/audience');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_broadcasts',
+    'One-off sends to the list, as distinct from the regular newsletter: an announcement, a date release, a last-minute ' +
+      'offer. Returns the subject, the audience it went to, its status and how many were sent or failed. ' +
+      'Use it when the user asks what they have sent recently, or when you are about to suggest emailing the list and ' +
+      'need to know whether they already have. Sending one happens in KM Hub at https://hub.kivimedia.co. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many broadcasts, newest first. Default 20.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/marketing/broadcasts${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_lists',
+    'The saved lists: every segment in the workspace with its name, the tag it is built on and a live member count. ' +
+      'Use it when the user asks what lists they have, how big one is, or before importing so you can tell whether ' +
+      'the list already exists (an import into an existing name GROWS it rather than making a second one). ' +
+      'Returns list names and sizes, never the people on them. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/marketing/lists');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_import_list',
+    'Build a list in KM Hub from a CSV or from rows: YES, this is the tool for "here is a CSV, make me a list". ' +
+      'Each person is filed as a client (found by email if they already exist, created if not), tagged with the list ' +
+      'name, and a saved segment with that name is created so the list is ready to pick in Compose & Send, broadcasts ' +
+      'and re-engagement. Re-running with the same list name adds to it and never duplicates a contact. ' +
+      'Give it EITHER csv_text (the file contents, header row included - email / name / first name / last name / ' +
+      'phone / company are picked up by their usual column names) OR rows (already structured) OR csv_path (a file on ' +
+      'the machine this connector runs on - local installs only, not the hosted connector). Files over 500 rows are ' +
+      'sent in chunks automatically. ' +
+      'Report back what it returns: created, tagged_existing, already_on_list and the skipped counts - a row with no ' +
+      'usable email is skipped and listed, not silently lost. Nothing is SENT to anyone: this builds the list only.',
+    {
+      list_name: z.string().min(1).max(120).describe('The list name. Becomes the segment name and the tag on every contact. Reuse a name to grow that list.'),
+      csv_text: z.string().optional().describe('The raw CSV contents including the header row. Preferred when the user pasted or attached the file.'),
+      csv_path: z.string().optional().describe('Absolute path to a CSV on the machine running this connector. Local installs only.'),
+      rows: z
+        .array(
+          z.object({
+            email: z.string(),
+            name: z.string().optional(),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+            phone: z.string().optional(),
+            company: z.string().optional(),
+          }),
+        )
+        .optional()
+        .describe('Structured rows, if you already have them. email is required per row.'),
+      description: z.string().max(500).optional().describe('Shown on the segment card in KM Hub. Defaults to "Imported list (date)".'),
+      source: z.string().max(60).optional().describe('Stamped on created contacts as their source. Defaults to api_import; use e.g. "brevo_export" when you know where the file came from.'),
+    },
+    async ({ list_name, csv_text, csv_path, rows, description, source }) => {
+      let apiRows = Array.isArray(rows) && rows.length ? rows : null;
+      let mapped = null;
+      if (!apiRows) {
+        let raw = csv_text;
+        if (!raw && csv_path) {
+          try {
+            raw = readFileSync(csv_path, 'utf8');
+          } catch (e) {
+            return text(
+              `I could not read ${csv_path} from here (${e.code || e.message}). On the hosted connector the file is on your machine, not mine: paste the file contents as csv_text instead.`,
+              true,
+            );
+          }
+        }
+        if (!raw) return text('Give me the list as csv_text (the file contents), rows, or a csv_path on a local install.', true);
+        const converted = toApiRows(parseCsv(raw));
+        if (converted.error) return text(converted.error, true);
+        apiRows = converted.rows;
+        mapped = converted.mapped;
+      }
+      if (!apiRows.length) return text('The file parsed but had no data rows under the header, so there is nothing to import.', true);
+
+      const totals = { received: 0, created: 0, tagged_existing: 0, already_on_list: 0, invalid_email: 0, duplicate_in_file: 0, tag_failed: 0 };
+      const invalidExamples = [];
+      const problems = [];
+      let list = null;
+      for (let i = 0; i < apiRows.length; i += IMPORT_CHUNK) {
+        const chunk = apiRows.slice(i, i + IMPORT_CHUNK);
+        const chunkNo = i / IMPORT_CHUNK + 1;
+        const r = await call('POST', '/marketing/lists/import', { list_name, rows: chunk, description, source });
+        if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+        if (r.status === 402) return out(r);
+        const d = r.data && typeof r.data === 'object' ? r.data : {};
+        if (!r.ok && r.status !== 207) {
+          problems.push(`chunk ${chunkNo} (rows ${i + 1}-${i + chunk.length}): ${d.message || JSON.stringify(d).slice(0, 300)}`);
+          continue;
+        }
+        totals.received += Number(d.received) || 0;
+        totals.created += Number(d.created) || 0;
+        totals.tagged_existing += Number(d.tagged_existing) || 0;
+        totals.already_on_list += Number(d.already_on_list) || 0;
+        for (const k of ['invalid_email', 'duplicate_in_file', 'tag_failed']) totals[k] += Number(d.skipped?.[k]) || 0;
+        for (const ex of d.invalid_examples || []) if (invalidExamples.length < 10) invalidExamples.push(ex);
+        if (d.insert_error) problems.push(`chunk ${chunkNo}: ${d.note_on_error || d.insert_error}`);
+        if (d.segment_error) problems.push(d.segment_error);
+        if (d.list) list = d.list;
+      }
+      const ok = problems.length === 0 && Boolean(list && list.id);
+      const summary = {
+        ok,
+        list,
+        chunks: Math.ceil(apiRows.length / IMPORT_CHUNK),
+        ...(mapped ? { columns_used: mapped } : {}),
+        ...totals,
+        invalid_examples: invalidExamples,
+        ...(problems.length ? { problems } : {}),
+        where: 'https://hub.kivimedia.co/?page=email-segments',
+        note: ok
+          ? `"${list.name}" now has ${list.members ?? '?'} members and is ready to pick as an audience in KM Hub. Nothing was sent.`
+          : 'The import did not fully land - see problems. Re-sending the same file is safe: existing contacts are tagged, not duplicated.',
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }], isError: !ok };
+    },
+  );
+}