flashrev-ai-enrich 1.0.0

package/src/cli.js

@@ -0,0 +1,435 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { parseArgv, readFlag, readFlagList, requireFlag } from "./args.js";
+import { CAPABILITIES, applyRemoteConfigs } from "./capabilities.js";
+import { loadConfig, writeInitialConfig } from "./config.js";
+import { estimateJob } from "./estimate.js";
+import { FlashRevEnrichClient } from "./flashrev-client.js";
+import { mappingsFromFlags, resolveJob, validateJobForHeaders } from "./job.js";
+import { runEnrichment, TerminateError } from "./runner.js";
+import { readCsvSource, writeCsvFile } from "./tabular.js";
+import { parseKeyValueList } from "./utils.js";
+
+/**
+ * Fetch remote capability registry and merge it on top of the local fallback.
+ * Network failure is non-blocking — local CAPABILITIES still works.
+ */
+async function syncRemoteConfigs(client) {
+  try {
+    const remote = await client.listConfigs();
+    if (Array.isArray(remote) && remote.length) applyRemoteConfigs(remote);
+    return remote;
+  } catch (e) {
+    console.warn(`Warning: failed to fetch capability configs (${e.message}). Using local fallback.`);
+    return null;
+  }
+}
+
+export async function main(argv) {
+  const { positionals, flags } = parseArgv(argv);
+  // ai-mode: --ai-mode flag OR FLASHREV_ENRICH_AI_MODE=1 env var.
+  // When on, list commands auto-emit JSON and bin/ wraps errors in a structured envelope.
+  const aiMode = flags.aiMode === true || process.env.FLASHREV_ENRICH_AI_MODE === "1";
+  process.env.__FLASHREV_AI_MODE = aiMode ? "1" : "";
+  if (aiMode) flags.json = true;
+  if (flags.version || flags.v) return commandVersion();
+  const command = positionals[0] || (flags.help || flags.h ? "help" : "");
+
+  switch (command) {
+    case "init":
+      return commandInit(flags);
+    case "doctor":
+      return commandDoctor(flags);
+    case "tokens":
+      return commandTokens(flags);
+    case "token-history":
+    case "tokens-history":
+      return commandTokenHistory(flags);
+    case "schema":
+      return commandSchema(flags);
+    case "dry-run":
+      return commandRun({ ...flags, dryRun: true });
+    case "run":
+      return commandRun(flags);
+    case "help":
+    case "":
+    case undefined:
+      console.log(helpText());
+      return;
+    default:
+      throw new Error(`Unknown command: ${command}. Run flashrev-ai-enrich --help.`);
+  }
+}
+
+async function commandInit(flags) {
+  const path = await writeInitialConfig(readFlag(flags, "config"), {
+    force: Boolean(flags.force),
+    baseUrl: readFlag(flags, "baseUrl"),
+    apiKeyEnv: readFlag(flags, "apiKeyEnv"),
+    apiKey: readFlag(flags, "apiKey"),
+    saveApiKey: Boolean(flags.saveApiKey),
+    mePath: readFlag(flags, "mePath"),
+    tokensPath: readFlag(flags, "tokensPath"),
+    quotePath: readFlag(flags, "quotePath")
+  });
+  console.log(`Created config: ${path}`);
+  console.log("Set FLASHREV_API_KEY before calling FlashRev Enrichment APIs.");
+  if (flags.apiKey && !flags.saveApiKey) {
+    console.log("API key was not saved. Prefer environment variables for external users.");
+  }
+}
+
+async function commandDoctor(flags) {
+  const config = await loadConfig(readFlag(flags, "config"));
+  const checks = [];
+  checks.push(["Node >=20", Number(process.versions.node.split(".")[0]) >= 20]);
+  checks.push(["Config path resolved", Boolean(config.__path)]);
+  checks.push([`API key env ${config.flashrev.apiKeyEnv}`, Boolean(config.__apiKey)]);
+  checks.push(["Tokens endpoint path", Boolean(config.flashrev.endpoints.tokens.path)]);
+  checks.push(["Configs endpoint path", Boolean(config.flashrev.endpoints.configs?.path)]);
+  checks.push(["Enrich endpoint path", Boolean(config.flashrev.endpoints.enrich.path)]);
+  checks.push(["Capability registry loaded", CAPABILITIES.length > 0]);
+
+  for (const [label, ok] of checks) console.log(`${ok ? "OK " : "NO "} ${label}`);
+
+  if (flags.api === false || flags.noApi) {
+    console.log("Skipped live API checks because --no-api was provided.");
+    return;
+  }
+
+  const client = new FlashRevEnrichClient(config);
+  const remote = await syncRemoteConfigs(client);
+  console.log(`OK Remote capability configs: ${remote ? remote.length : 0}`);
+  const tokens = await client.tokens();
+  console.log(`OK FlashRev tokens remaining: ${tokens.remaining}`);
+}
+
+async function commandTokens(flags) {
+  const config = await loadConfig(readFlag(flags, "config"));
+  const client = new FlashRevEnrichClient(config);
+  const tokens = await client.tokens();
+  if (flags.json) {
+    console.log(JSON.stringify(tokens, null, 2));
+    return;
+  }
+  console.log(`FlashRev tokens remaining: ${tokens.remaining}`);
+  if (tokens.remaining <= 0) {
+    console.log("Balance is 0. Please recharge tokens in FlashRev before running enrichment.");
+  }
+  if (tokens.total) console.log(`Total: ${tokens.total}`);
+  if (tokens.used) console.log(`Used: ${tokens.used}`);
+  if (tokens.plan) console.log(`Plan: ${tokens.plan}`);
+}
+
+async function commandTokenHistory(flags) {
+  const config = await loadConfig(readFlag(flags, "config"));
+  const client = new FlashRevEnrichClient(config);
+  const history = await client.tokenHistory({
+    from: readFlag(flags, "from"),
+    to: readFlag(flags, "to"),
+    limit: readFlag(flags, "limit")
+  });
+  if (flags.json) {
+    console.log(JSON.stringify(history, null, 2));
+    return;
+  }
+  if (!history.length) {
+    console.log("No token usage history found for the selected range.");
+    return;
+  }
+  for (const item of history) {
+    console.log(`${item.date || "-"}  ${String(item.tokens).padStart(4)}  ${item.action || "-"}${item.status ? `  ${item.status}` : ""}`);
+  }
+}
+
+async function commandSchema(flags) {
+  // Prefer remote /configs; fall back to local capabilities.js if it fails.
+  const config = await loadConfig(readFlag(flags, "config")).catch(() => null);
+  if (config && config.__apiKey) {
+    await syncRemoteConfigs(new FlashRevEnrichClient(config));
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ capabilities: CAPABILITIES.map(publicCapability) }, null, 2));
+    return;
+  }
+  const groups = new Map();
+  for (const capability of CAPABILITIES) {
+    const group = capability.group || "Other";
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group).push(capability);
+  }
+  for (const [group, capabilities] of groups.entries()) {
+    console.log(group);
+    for (const capability of capabilities) {
+      const outputs = capability.dynamicOutput
+        ? "dynamic outputs"
+        : (capability.outputFields || []).map((f) => f.key).join(", ");
+      const price = capability.unitPriceToken != null ? ` (${capability.unitPriceToken}t)` : "";
+      console.log(`  ${capability.id}${price} - ${capability.name || capability.displayName} -> ${outputs}`);
+    }
+    console.log("");
+  }
+}
+
+async function commandRun(flags) {
+  const config = await loadConfig(readFlag(flags, "config"));
+  const source = readFlag(flags, "source");
+  const out = readFlag(flags, "out");
+  if (!flags.dryRun && !out) throw new Error("Missing required flag: --out");
+  if (!flags.dryRun && source && resolve(source) === resolve(out)) {
+    throw new Error("Refusing to overwrite source CSV. Choose a different --out path.");
+  }
+
+  const imported = source ? await readCsvSource(source) : importedFromInlineInput(flags);
+  if (!imported.records.length) throw new Error("No rows found in source CSV.");
+
+  const client = new FlashRevEnrichClient(config);
+
+  // Sync remote capability registry on startup (unitPriceToken / concurrency / rules).
+  await syncRemoteConfigs(client);
+
+  const { inputMapping, outputMapping } = mappingsFromFlags(readFlagList(flags, "map"), readFlagList(flags, "output"));
+  // Inline input mode: auto-map each --input key to the capability field of the same name,
+  // so users don't need to also write `--map email=email`.
+  if (!source) {
+    for (const key of imported.headers) {
+      if (inputMapping[key] == null) inputMapping[key] = key;
+    }
+  }
+  const job = await resolveJob(flags, inputMapping, outputMapping, imported.headers, {
+    client,
+    capabilities: CAPABILITIES
+  });
+  if (job.routedFromPrompt) printRoutingDecision(job);
+  validateJobForHeaders(job, imported.headers);
+
+  const estimate = estimateJob(config, job, imported.records);
+  printEstimate(estimate);
+
+  if (flags.dryRun) {
+    console.log("Dry run only. No FlashRev enrichment request was sent.");
+    return;
+  }
+
+  if (!flags.yes && !flags.y) {
+    await confirmCostBeforeRun(estimate);
+  }
+
+  if (!flags.skipBalanceCheck) {
+    const tokens = await client.tokens();
+    if (tokens.remaining <= 0) {
+      const error = new Error("FlashRev token balance is 0. Please recharge tokens before running enrichment.");
+      error.hint = "Run flashrev-ai-enrich tokens to check balance after recharging.";
+      throw error;
+    }
+    if (estimate.estimatedTokens > tokens.remaining) {
+      console.log(`Warning: estimated tokens (${estimate.estimatedTokens}) exceed current balance (${tokens.remaining}).`);
+    }
+  }
+
+  // Query balance once before the batch so we can reconcile precisely afterwards.
+  // (response.cost.tokens can be slightly inflated under concurrency because the
+  //  server-side remainBefore/After windows interleave; the before/after balance
+  //  delta is the only fully accurate figure.)
+  let balanceBeforeRun = null;
+  try {
+    balanceBeforeRun = (await client.tokens()).remaining;
+  } catch {
+    // Best-effort; ignore if balance query fails.
+  }
+
+  let result;
+  let terminateError = null;
+  try {
+    result = await runEnrichment({ client, config, job, imported, flags });
+  } catch (e) {
+    if (!(e instanceof TerminateError)) throw e;
+    terminateError = e;
+    // runEnrichment fills the results array (with skipped markers) before throwing; pick it from e.partial.
+    result = e.partial || { records: [], completed: 0, stoppedAfterSample: false, summary: null };
+  }
+
+  // Query balance after the batch to compute true deduction = before - after.
+  let balanceAfterRun = null;
+  try {
+    balanceAfterRun = (await client.tokens()).remaining;
+  } catch {
+    // Fall back to summary's accumulated cost.tokens.
+  }
+  if (result.summary && balanceBeforeRun != null && balanceAfterRun != null) {
+    result.summary.tokensUsedActual = balanceBeforeRun - balanceAfterRun;
+    result.summary.balanceBefore = balanceBeforeRun;
+    result.summary.balanceAfter = balanceAfterRun;
+  }
+
+  if (result.records.length) {
+    const path = await writeCsvFile(out, result.records);
+    console.log("");
+    console.log(`Wrote ${result.records.length} row(s) to ${path}`);
+  }
+
+  printRunSummary(result, estimate);
+
+  if (result.stoppedAfterSample) {
+    console.log("Stopped after sample preview. Re-run with --yes to continue after the preview.");
+  }
+
+  if (terminateError) {
+    console.error("");
+    console.error(`Run terminated: ${terminateError.message}`);
+    process.exitCode = 1;
+  }
+}
+
+function printRunSummary(result, estimate) {
+  const s = result.summary || {};
+  console.log("");
+  console.log("Summary:");
+  console.log(`  Completed:   ${result.completed}`);
+  console.log(`  Failed:      ${s.failedCount || 0}`);
+  console.log(`  Cached:      ${s.cachedCount || 0}`);
+  // Prefer the before-after balance delta (real deduction); fall back to summed cost.tokens
+  // when balance is unavailable. cost.tokens can be inflated under concurrency, treat as approximate.
+  if (s.tokensUsedActual != null) {
+    console.log(`  Tokens used: ${s.tokensUsedActual}${estimate ? ` (estimated ${estimate.estimatedTokens})` : ""}`);
+    if (s.balanceBefore != null && s.balanceAfter != null) {
+      console.log(`               (balance ${s.balanceBefore} → ${s.balanceAfter})`);
+    }
+  } else {
+    console.log(`  Tokens used: ~${s.tokensUsed || 0}${estimate ? ` (estimated ${estimate.estimatedTokens})` : ""}`);
+    console.log(`               (approximate; query 'tokens' or 'token-history' for exact)`);
+  }
+}
+
+async function confirmCostBeforeRun(estimate) {
+  if (!process.stdin.isTTY) {
+    const error = new Error("Refusing to run enrichment without cost confirmation in non-interactive mode.");
+    error.hint = "Run dry-run first, then pass --yes when the estimated token cost is approved.";
+    throw error;
+  }
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(
+      `Estimated cost is ${estimate.estimatedTokens} token(s) for ${estimate.rowCount} row(s). Continue? [y/N] `
+    );
+    if (!/^y(es)?$/i.test(answer.trim())) {
+      throw new Error("Stopped before enrichment because the estimated token cost was not approved.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function importedFromInlineInput(flags) {
+  const inputValues = readFlagList(flags, "input");
+  if (!flags.prompt && !inputValues.length) {
+    throw new Error("Missing required flag: --source. For inline mode, provide --input key=value pairs (with --capability) or --prompt.");
+  }
+  const record = parseKeyValueList(inputValues, "--input");
+  const headers = Object.keys(record);
+  return {
+    headers,
+    records: [record],
+    source: "inline-input",
+    format: "inline"
+  };
+}
+
+async function commandVersion() {
+  const pkgUrl = new URL("../package.json", import.meta.url);
+  const pkg = JSON.parse(await readFile(pkgUrl, "utf8"));
+  console.log(pkg.version);
+}
+
+function printRoutingDecision(job) {
+  const fmtMap = (m) =>
+    Object.entries(m || {})
+      .map(([k, v]) => `${k}=${v}`)
+      .join(", ") || "(none)";
+  console.log("");
+  console.log("Routing decision:");
+  console.log(`  capability:     ${job.capability.funcName || job.capability.id}`);
+  console.log(`  inputMapping:   ${fmtMap(job.inputMapping)}`);
+  console.log(`  outputMapping:  ${fmtMap(job.outputMapping)}`);
+  if (job.routerReasoning) console.log(`  reasoning:      ${job.routerReasoning}`);
+  console.log(`  routing cost:   ${job.routerTokensCharged || 0} token(s)`);
+  console.log("");
+}
+
+function printEstimate(estimate) {
+  console.log(`Capability:           ${estimate.displayName || estimate.capability}`);
+  console.log(`Rows:                 ${estimate.rowCount}`);
+  console.log(`Unit cost:            ${estimate.unitCost} token(s) / ${estimate.unit}`);
+  console.log(`Concurrency:          ${estimate.effectiveConcurrency}`);
+  console.log(`Estimated API calls:  ${estimate.estimatedApiCalls}`);
+  console.log(`Estimated tokens:     ${estimate.estimatedTokens}`);
+  console.log(`Estimated duration:   ~${formatDuration(estimate.estimatedSeconds)}`);
+  console.log(`Estimate source:      ${estimate.estimateMethod}`);
+  if (estimate.note) console.log(`Note:                 ${estimate.note}`);
+}
+
+function formatDuration(seconds) {
+  if (!seconds || seconds < 60) return `${seconds || 0}s`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+  const h = Math.floor(seconds / 3600);
+  const m = Math.round((seconds % 3600) / 60);
+  return `${h}h ${m}m`;
+}
+
+function publicCapability(capability) {
+  return {
+    id: capability.id,
+    displayName: capability.displayName,
+    name: capability.name,
+    group: capability.group,
+    inputFields: capability.inputFields,
+    rules: capability.rules,
+    outputFields: capability.outputFields,
+    dynamicOutput: capability.dynamicOutput
+  };
+}
+
+export function helpText() {
+  return `FlashRev AI Enrich
+
+Usage:
+  flashrev-ai-enrich init [--config .flashrev/enrich-config.json]
+  flashrev-ai-enrich doctor [--no-api]
+  flashrev-ai-enrich tokens [--json]
+  flashrev-ai-enrich token-history [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--json]
+  flashrev-ai-enrich schema [--json]
+  flashrev-ai-enrich dry-run --source leads.csv --capability match_company_id --map company_linkedin=linkedin
+  flashrev-ai-enrich run --source leads.csv --out enriched.csv --capability enrich_email --map first_name=first_name --map last_name=last_name --map company_name=company --yes
+  flashrev-ai-enrich run --source leads.csv --out enriched.csv --prompt "fill missing business emails" --yes
+
+Core flags:
+  --config PATH             Config file path. Defaults to .flashrev/enrich-config.json
+  --source PATH             Source CSV file
+  --input key=value         Inline condition for prompt-only enrichment. Repeatable
+  --out PATH                Output CSV file for run
+  --capability ID           Enrichment capability ID from schema
+  --prompt TEXT             Natural-language request (routed via run_llm, costs 1 token). Agents should prefer --capability
+  --job PATH                JSON job file with capability, inputMapping, and outputs
+  --map input=csv_column    Map enrichment input field to CSV column. Repeatable
+  --output column=response  Map output CSV column to response field. Repeatable
+  --output-fields a,b       Dynamic output fields for LLM/search/extract capabilities
+  --sample-size N           Preview N enriched rows before the remaining batch. Default 10
+  --concurrency N           Number of row requests to run at a time after validation. Default 3
+  --skip-balance-check      Skip pre-run tokens balance check
+  --yes                     Continue automatically after sample preview
+  --ai-mode                 JSON output for list commands and JSON error envelope. Also enabled by FLASHREV_ENRICH_AI_MODE=1
+
+Examples:
+  # Generate a private app key at https://info.flashlabs.ai/settings/privateApps
+  export FLASHREV_API_KEY="your_flashrev_api_key"
+  flashrev-ai-enrich tokens
+  flashrev-ai-enrich token-history --from 2026-05-01 --to 2026-05-27
+  flashrev-ai-enrich schema
+  flashrev-ai-enrich dry-run --source leads.csv --capability get_person_location --map email=email
+  flashrev-ai-enrich run --source leads.csv --out leads.enriched.csv --capability enrich_email --map email=email --yes
+  flashrev-ai-enrich run --source leads.csv --out enriched.csv --prompt "fill missing business emails" --yes
+`;
+}

package/src/config.js

@@ -0,0 +1,114 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { deepMerge, ensureDir, readJson, writeJson } from "./utils.js";
+
+export const DEFAULT_CONFIG = {
+  flashrev: {
+    baseUrl: "https://open-ai-api.flashlabs.ai",
+    apiKeyEnv: "FLASHREV_API_KEY",
+    auth: {
+      // FlashRev open API expects the X-API-Key header with no prefix; same as cli-npm-cli-flashrev-api-ai.
+      type: "header",
+      header: "X-API-Key"
+    },
+    endpoints: {
+      // Balance query: returns limit.tokenTotal / tokenCost / tokenCategoryRemain.
+      tokens: {
+        method: "GET",
+        path: "/flashrev/api/v2/oauth/me"
+      },
+      // Token consumption history.
+      tokenHistory: {
+        method: "POST",
+        path: "/flashrev/api/v2/commodity/token/transaction/list"
+      },
+      // Capability registry.
+      configs: {
+        method: "GET",
+        path: "/flashrev/api/v1/enrich/configs"
+      },
+      // Row-level enrichment.
+      enrich: {
+        method: "POST",
+        path: "/flashrev/api/v1/enrich/run"
+      }
+    }
+  },
+  defaults: {
+    sampleSize: 10,
+    concurrency: 3,
+    retryCount: 1,
+    retryDelayMs: 500,
+    statusColumn: "flashrev_enrich_status",
+    errorColumn: "flashrev_enrich_error",
+    tokensPerRow: {
+      company: 1,
+      person: 1,
+      flashagent: 1,
+      unlock_email: 2,
+      unlock_phone: 8,
+      verify_email: 1,
+      verify_phone: 1,
+      generic: 1
+    }
+  },
+  paths: {
+    dataDir: ".flashrev/enrich"
+  }
+};
+
+export function resolveConfigPath(value) {
+  return resolve(process.cwd(), value || process.env.FLASHREV_ENRICH_CONFIG || ".flashrev/enrich-config.json");
+}
+
+export async function loadConfig(path) {
+  const configPath = resolveConfigPath(path);
+  const userConfig = existsSync(configPath) ? await readJson(configPath) : {};
+  const config = deepMerge(DEFAULT_CONFIG, userConfig);
+  config.__path = configPath;
+  config.__apiKey = readApiKey(config);
+  return config;
+}
+
+export async function writeInitialConfig(path, options = {}) {
+  const configPath = resolveConfigPath(path);
+  if (existsSync(configPath) && !options.force) {
+    throw new Error(`Config already exists at ${configPath}. Use --force to overwrite.`);
+  }
+
+  const config = deepMerge(DEFAULT_CONFIG, {
+    flashrev: {
+      baseUrl: options.baseUrl || DEFAULT_CONFIG.flashrev.baseUrl,
+      apiKeyEnv: options.apiKeyEnv || DEFAULT_CONFIG.flashrev.apiKeyEnv,
+      endpoints: {
+        tokens: {
+          method: DEFAULT_CONFIG.flashrev.endpoints.tokens.method,
+          path: options.tokensPath || DEFAULT_CONFIG.flashrev.endpoints.tokens.path
+        },
+        tokenHistory: {
+          method: DEFAULT_CONFIG.flashrev.endpoints.tokenHistory.method,
+          path: options.tokenHistoryPath || DEFAULT_CONFIG.flashrev.endpoints.tokenHistory.path
+        },
+        configs: {
+          method: DEFAULT_CONFIG.flashrev.endpoints.configs.method,
+          path: options.configsPath || DEFAULT_CONFIG.flashrev.endpoints.configs.path
+        },
+        enrich: {
+          method: DEFAULT_CONFIG.flashrev.endpoints.enrich.method,
+          path: options.enrichPath || DEFAULT_CONFIG.flashrev.endpoints.enrich.path
+        }
+      }
+    }
+  });
+
+  if (options.saveApiKey && options.apiKey) config.flashrev.apiKey = options.apiKey;
+
+  await ensureDir(resolve(process.cwd(), config.paths.dataDir));
+  await writeJson(configPath, config);
+  return configPath;
+}
+
+export function readApiKey(config) {
+  const envName = config.flashrev.apiKeyEnv || "FLASHREV_API_KEY";
+  return process.env[envName] || config.flashrev.apiKey || "";
+}

package/src/csv.js

@@ -0,0 +1,81 @@
+import { normalizeHeader } from "./utils.js";
+
+export function parseDelimitedText(text, delimiter = detectDelimiter(text)) {
+  const rows = parseDelimited(text, delimiter).filter((row) => row.some((cell) => cell.trim() !== ""));
+  if (rows.length === 0) return { headers: [], records: [] };
+
+  const headers = rows[0].map((header, index) => normalizeHeader(header) || `column_${index + 1}`);
+  const records = rows.slice(1).map((row) => {
+    const record = {};
+    headers.forEach((header, index) => {
+      record[header] = row[index] === undefined ? "" : row[index];
+    });
+    return record;
+  });
+  return { headers, records };
+}
+
+export function toDelimitedText(records, delimiter = ",") {
+  if (!records.length) return "";
+  const headers = [...new Set(records.flatMap((record) => Object.keys(record)))];
+  const lines = [headers.map((header) => escapeCell(header, delimiter)).join(delimiter)];
+  for (const record of records) {
+    lines.push(headers.map((header) => escapeCell(record[header] ?? "", delimiter)).join(delimiter));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function detectDelimiter(text) {
+  const sample = text.split(/\r?\n/, 1)[0] || "";
+  const commaCount = (sample.match(/,/g) || []).length;
+  const tabCount = (sample.match(/\t/g) || []).length;
+  const semicolonCount = (sample.match(/;/g) || []).length;
+  if (tabCount > commaCount && tabCount >= semicolonCount) return "\t";
+  if (semicolonCount > commaCount) return ";";
+  return ",";
+}
+
+function parseDelimited(text, delimiter) {
+  const rows = [];
+  let row = [];
+  let cell = "";
+  let inQuotes = false;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    const next = text[index + 1];
+    if (char === '"') {
+      if (inQuotes && next === '"') {
+        cell += '"';
+        index += 1;
+      } else {
+        inQuotes = !inQuotes;
+      }
+      continue;
+    }
+    if (!inQuotes && char === delimiter) {
+      row.push(cell);
+      cell = "";
+      continue;
+    }
+    if (!inQuotes && (char === "\n" || char === "\r")) {
+      if (char === "\r" && next === "\n") index += 1;
+      row.push(cell);
+      rows.push(row);
+      row = [];
+      cell = "";
+      continue;
+    }
+    cell += char;
+  }
+
+  row.push(cell);
+  rows.push(row);
+  return rows;
+}
+
+function escapeCell(value, delimiter) {
+  const text = String(value);
+  const escaped = text.replace(/"/g, '""');
+  return text.includes(delimiter) || /["\n\r]/.test(text) ? `"${escaped}"` : text;
+}