mango-lollipop 0.1.0

package/lib/excel.ts

@@ -0,0 +1,433 @@
+// =============================================================================
+// Mango Lollipop — Excel Generation (xlsx-js-style)
+// =============================================================================
+
+import XLSX from "xlsx-js-style";
+import { writeFileSync } from "fs";
+import type {
+  Message,
+  EventTaxonomy,
+  Channel,
+  AARRRStage,
+  Analysis,
+} from "./schema.js";
+
+// -----------------------------------------------------------------------------
+// Stage display names and colors
+// -----------------------------------------------------------------------------
+
+const STAGE_LABELS: Record<AARRRStage | "TX", string> = {
+  TX: "Transactional",
+  AQ: "Acquisition",
+  AC: "Activation",
+  RV: "Revenue",
+  RT: "Retention",
+  RF: "Referral",
+};
+
+const STAGE_COLORS: Record<string, { fill: string }> = {
+  TX: { fill: "F0F0F0" },
+  AQ: { fill: "D4EDDA" },
+  AC: { fill: "CCE5FF" },
+  RV: { fill: "FFF3CD" },
+  RT: { fill: "FFE5CC" },
+  RF: { fill: "E8D5F5" },
+};
+
+const HEADER_STYLE: XLSX.CellStyle = {
+  fill: { fgColor: { rgb: "374151" } },
+  font: { bold: true, color: { rgb: "FFFFFF" }, sz: 11 },
+  alignment: { vertical: "center" },
+};
+
+// -----------------------------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------------------------
+
+function guardsToString(msg: Message): string {
+  if (!msg.guards.length) return "\u2014";
+  return msg.guards.map((g) => g.condition).join("; ");
+}
+
+function suppressionsToString(msg: Message): string {
+  if (!msg.suppressions.length) return "\u2014";
+  return msg.suppressions.map((s) => s.condition).join("; ");
+}
+
+function channelToString(msg: Message): string {
+  if (msg.channel) return msg.channel;
+  if ((msg as any).channels) return (msg as any).channels.join(", ");
+  return "\u2014";
+}
+
+function tagsToString(tags: string[]): string {
+  return tags.join(", ");
+}
+
+// Apply header style to first row of a worksheet
+function applyHeaderStyle(ws: XLSX.WorkSheet): void {
+  const range = XLSX.utils.decode_range(ws["!ref"] ?? "A1");
+  for (let c = range.s.c; c <= range.e.c; c++) {
+    const addr = XLSX.utils.encode_cell({ r: 0, c });
+    if (ws[addr]) {
+      ws[addr].s = HEADER_STYLE;
+    }
+  }
+}
+
+// Apply stage-based row fills to data rows
+function applyStageColors(
+  ws: XLSX.WorkSheet,
+  stageColIndex: number
+): void {
+  const range = XLSX.utils.decode_range(ws["!ref"] ?? "A1");
+  for (let r = 1; r <= range.e.r; r++) {
+    const stageCell =
+      ws[XLSX.utils.encode_cell({ r, c: stageColIndex })];
+    if (!stageCell) continue;
+
+    // Resolve stage code from label or raw value
+    const val = String(stageCell.v ?? "");
+    let stageCode = val;
+    for (const [code, label] of Object.entries(STAGE_LABELS)) {
+      if (label === val) {
+        stageCode = code;
+        break;
+      }
+    }
+
+    const color = STAGE_COLORS[stageCode];
+    if (!color) continue;
+
+    const fillStyle: XLSX.CellStyle = {
+      fill: { fgColor: { rgb: color.fill } },
+    };
+
+    for (let c = range.s.c; c <= range.e.c; c++) {
+      const addr = XLSX.utils.encode_cell({ r, c });
+      if (ws[addr]) {
+        ws[addr].s = fillStyle;
+      }
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Sheet builders
+// -----------------------------------------------------------------------------
+
+function buildWelcomeSheet(
+  analysis: Analysis,
+  messageCount: number
+): XLSX.WorkSheet {
+  const pathLabel = analysis.path === "fresh" ? "Fresh" : "Improving Existing";
+  const channels = analysis.channels.join(", ");
+  const generated = new Date().toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+  });
+
+  const data: (string | number)[][] = [
+    ["Mango Lollipop \u2014 Lifecycle Messaging Matrix"],
+    [],
+    ["Company", analysis.company.name],
+    ["Product", analysis.company.product_type],
+    ["Channels", channels],
+    ["Generated", generated],
+    ["Total Messages", messageCount],
+    ["Path", pathLabel],
+    [],
+    ["How to Use This Spreadsheet"],
+    [
+      "Transactional Messages",
+      "Mandatory system messages (email verification, password reset, receipts)",
+    ],
+    [
+      "Lifecycle Matrix",
+      "Your AARRR messaging strategy with triggers, guards, and suppressions",
+    ],
+    [
+      "Event Taxonomy",
+      "All product events and which messages they trigger",
+    ],
+    ["Tags", "Tag inventory with message counts"],
+    [
+      "Channel Strategy",
+      "Message distribution by channel and stage",
+    ],
+    [],
+    [],
+    [
+      "Generated by Mango Lollipop \u2014 https://github.com/sr-kai/mango-lollipop",
+    ],
+    ["Made by Sasha Kai with probably too much coffee."],
+  ];
+
+  const ws = XLSX.utils.aoa_to_sheet(data);
+
+  // Style the title row
+  if (ws["A1"]) {
+    ws["A1"].s = {
+      font: { bold: true, sz: 16, color: { rgb: "1F2937" } },
+    };
+  }
+
+  // Style "How to Use" header
+  if (ws["A10"]) {
+    ws["A10"].s = {
+      font: { bold: true, sz: 13, color: { rgb: "1F2937" } },
+    };
+  }
+
+  // Style info labels (rows 3-8, column A)
+  for (let r = 2; r <= 7; r++) {
+    const addr = XLSX.utils.encode_cell({ r, c: 0 });
+    if (ws[addr]) {
+      ws[addr].s = { font: { bold: true, color: { rgb: "6B7280" } } };
+    }
+  }
+
+  // Style sheet tab names (rows 11-15, column A)
+  for (let r = 10; r <= 14; r++) {
+    const addr = XLSX.utils.encode_cell({ r, c: 0 });
+    if (ws[addr]) {
+      ws[addr].s = { font: { bold: true, color: { rgb: "374151" } } };
+    }
+  }
+
+  // Style footer
+  if (ws["A18"]) {
+    ws["A18"].s = { font: { color: { rgb: "9CA3AF" }, sz: 10 } };
+  }
+  if (ws["A19"]) {
+    ws["A19"].s = { font: { color: { rgb: "9CA3AF" }, sz: 10 } };
+  }
+
+  // Column widths
+  ws["!cols"] = [{ wch: 30 }, { wch: 70 }];
+
+  return ws;
+}
+
+function buildTransactionalSheet(messages: Message[]): XLSX.WorkSheet {
+  const tx = messages.filter((m) => m.classification === "transactional");
+  const rows = tx.map((m) => ({
+    ID: m.id,
+    Name: m.name,
+    "Trigger Event": m.trigger.event,
+    "Trigger Type": m.trigger.type,
+    Wait: m.wait,
+    Channel: channelToString(m),
+    CTA: m.cta.text,
+    From: m.from,
+    Tags: tagsToString(m.tags),
+  }));
+  const ws = XLSX.utils.json_to_sheet(rows);
+  autoFitColumns(ws, rows);
+  applyHeaderStyle(ws);
+  // TX rows all get the TX color
+  applyStageColors(ws, -1); // special handling below
+  // For TX sheet, all rows are TX — apply fill to all data rows
+  const range = XLSX.utils.decode_range(ws["!ref"] ?? "A1");
+  const txFill: XLSX.CellStyle = {
+    fill: { fgColor: { rgb: STAGE_COLORS.TX.fill } },
+  };
+  for (let r = 1; r <= range.e.r; r++) {
+    for (let c = range.s.c; c <= range.e.c; c++) {
+      const addr = XLSX.utils.encode_cell({ r, c });
+      if (ws[addr]) ws[addr].s = txFill;
+    }
+  }
+  return ws;
+}
+
+function buildLifecycleSheet(messages: Message[]): XLSX.WorkSheet {
+  const lc = messages.filter((m) => m.classification === "lifecycle");
+  const rows = lc.map((m) => ({
+    ID: m.id,
+    Stage: STAGE_LABELS[m.stage] ?? m.stage,
+    Name: m.name,
+    "Trigger Event": m.trigger.event,
+    "Trigger Type": m.trigger.type,
+    Wait: m.wait,
+    Guards: guardsToString(m),
+    Suppressions: suppressionsToString(m),
+    Channel: channelToString(m),
+    CTA: m.cta.text,
+    Goal: m.goal,
+    Segment: m.segment,
+    Tags: tagsToString(m.tags),
+    Format: m.format,
+    From: m.from,
+  }));
+  const ws = XLSX.utils.json_to_sheet(rows);
+  autoFitColumns(ws, rows);
+  applyHeaderStyle(ws);
+  applyStageColors(ws, 1); // Stage is column B (index 1)
+  return ws;
+}
+
+function buildEventTaxonomySheet(
+  events: EventTaxonomy,
+  messages: Message[]
+): XLSX.WorkSheet {
+  const rows: { Category: string; Event: string; "Used By": string }[] = [];
+
+  const categories: (keyof EventTaxonomy)[] = [
+    "identity",
+    "activation",
+    "engagement",
+    "conversion",
+    "retention",
+  ];
+
+  for (const category of categories) {
+    const eventList = events[category] ?? [];
+    for (const event of eventList) {
+      const usedBy = messages
+        .filter((m) => m.trigger.event === event)
+        .map((m) => m.id)
+        .join(", ");
+      rows.push({
+        Category: category.charAt(0).toUpperCase() + category.slice(1),
+        Event: event,
+        "Used By": usedBy || "\u2014",
+      });
+    }
+  }
+
+  const ws = XLSX.utils.json_to_sheet(rows);
+  autoFitColumns(ws, rows);
+  applyHeaderStyle(ws);
+  return ws;
+}
+
+function buildTagsSheet(
+  messages: Message[],
+  tagDefinitions: string[]
+): XLSX.WorkSheet {
+  const allTags = new Set<string>([
+    ...tagDefinitions,
+    ...messages.flatMap((m) => m.tags),
+  ]);
+
+  const rows = Array.from(allTags)
+    .sort()
+    .map((tag) => {
+      const msgIds = messages
+        .filter((m) => m.tags.includes(tag))
+        .map((m) => m.id);
+      return {
+        Tag: tag,
+        "Message Count": msgIds.length,
+        "Used By": msgIds.join(", ") || "\u2014",
+      };
+    });
+
+  const ws = XLSX.utils.json_to_sheet(rows);
+  autoFitColumns(ws, rows);
+  applyHeaderStyle(ws);
+  return ws;
+}
+
+function buildChannelStrategySheet(messages: Message[]): XLSX.WorkSheet {
+  const channels: Channel[] = ["email", "sms", "in-app", "push"];
+  const stages: (AARRRStage | "TX")[] = ["TX", "AQ", "AC", "RV", "RT", "RF"];
+
+  const rows: Record<string, string | number>[] = [];
+
+  for (const ch of channels) {
+    const msgsWithChannel = messages.filter(
+      (m) =>
+        m.channel === ch ||
+        ((m as any).channels && (m as any).channels.includes(ch))
+    );
+    if (msgsWithChannel.length === 0) continue;
+
+    const row: Record<string, string | number> = {
+      Channel: ch,
+      "Total Messages": msgsWithChannel.length,
+    };
+
+    for (const stage of stages) {
+      const count = msgsWithChannel.filter((m) => m.stage === stage).length;
+      row[STAGE_LABELS[stage]] = count;
+    }
+
+    rows.push(row);
+  }
+
+  const ws = XLSX.utils.json_to_sheet(rows);
+  autoFitColumns(ws, rows);
+  applyHeaderStyle(ws);
+  return ws;
+}
+
+// Auto-fit column widths based on content
+function autoFitColumns(
+  ws: XLSX.WorkSheet,
+  rows: Record<string, unknown>[]
+): void {
+  if (!rows.length) return;
+  const headers = Object.keys(rows[0]);
+  ws["!cols"] = headers.map((h) => {
+    let maxWidth = h.length;
+    for (const row of rows) {
+      const val = String(row[h] ?? "");
+      if (val.length > maxWidth) maxWidth = val.length;
+    }
+    return { wch: Math.min(maxWidth + 2, 60) };
+  });
+}
+
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+
+export function generateMatrixWorkbook(
+  messages: Message[],
+  events: EventTaxonomy,
+  tags: string[],
+  analysis?: Analysis
+): XLSX.WorkBook {
+  const wb = XLSX.utils.book_new();
+
+  // Welcome sheet first (if analysis data available)
+  if (analysis) {
+    XLSX.utils.book_append_sheet(
+      wb,
+      buildWelcomeSheet(analysis, messages.length),
+      "Welcome"
+    );
+  }
+
+  XLSX.utils.book_append_sheet(
+    wb,
+    buildTransactionalSheet(messages),
+    "Transactional Messages"
+  );
+  XLSX.utils.book_append_sheet(
+    wb,
+    buildLifecycleSheet(messages),
+    "Lifecycle Matrix"
+  );
+  XLSX.utils.book_append_sheet(
+    wb,
+    buildEventTaxonomySheet(events, messages),
+    "Event Taxonomy"
+  );
+  XLSX.utils.book_append_sheet(wb, buildTagsSheet(messages, tags), "Tags");
+  XLSX.utils.book_append_sheet(
+    wb,
+    buildChannelStrategySheet(messages),
+    "Channel Strategy"
+  );
+
+  return wb;
+}
+
+export function writeWorkbook(workbook: XLSX.WorkBook, filePath: string): void {
+  const buf = XLSX.write(workbook, { type: "buffer", bookType: "xlsx" });
+  writeFileSync(filePath, buf);
+}