@flowapt/flowiq-cli 0.1.12 → 0.2.1

package/src/commands/segments.js

@@ -0,0 +1,252 @@
+// `flowiq segments` (alias `seg`) — slice a contact cohort into fixed-size
+// batch tags and bulk-apply them (spec 01 / the broadcast-tag-batching
+// runbook). This command TAGS ONLY — it never sends. The send per tag is
+// `flowiq broadcast send --tag <batch-tag>` (or the dashboard broadcaster).
+//
+//   plan  <org> --tag-prefix X (--from-segment file | --ids-file file)  # exclusions → slice → plan file (no DB write)
+//   apply <org> <slug>  [--commit] [--yes]                              # append the batch tags (dry-run default)
+//   list  <org> [--prefix X]                                            # VERIFY: tag → contact count
+//   untag <org> <slug> --commit --confirm                               # ROLLBACK: remove the plan's own tags
+//
+// Golden rules encoded: exclusions (opt-out/archived/blocked) are applied
+// BEFORE slicing; apply is append-only + idempotent (`already_had` reported,
+// never double-added); untag only ever removes the plan's own tags.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { http } from "../http.js";
+
+const SEG_DIR = path.resolve(process.cwd(), ".flowiq", "segments");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const TAG_PREFIX_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+function slugify(name, fallback) {
+  const s = String(name || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+const planPath = (slug) => path.join(SEG_DIR, `${slug}.json`);
+
+async function resolvePlan(identifier) {
+  const candidates = [];
+  if (path.isAbsolute(identifier)) candidates.push(identifier);
+  else if (identifier.includes("/")) candidates.push(path.resolve(identifier));
+  else {
+    const base = identifier.endsWith(".json") ? identifier : `${identifier}.json`;
+    candidates.push(path.join(SEG_DIR, base));
+    candidates.push(path.resolve(base));
+  }
+  for (const c of candidates) if (await fileExists(c)) return c;
+  throw new Error(`Plan file not found. Tried:\n  ${candidates.join("\n  ")}`);
+}
+
+/** Read the cohort ids from a christiaan/segments snapshot or a plain file. */
+async function readCohort(opts, orgId) {
+  if (!!opts.fromSegment === !!opts.idsFile) {
+    throw new Error("provide exactly one of --from-segment / --ids-file");
+  }
+  let ids = [], sourceMeta;
+  if (opts.fromSegment) {
+    const raw = JSON.parse(await fs.readFile(path.resolve(opts.fromSegment), "utf8"));
+    if (raw.organization_id && raw.organization_id !== orgId) {
+      throw new Error(`snapshot organization_id (${raw.organization_id}) ≠ the org you passed (${orgId}) — refusing (V-3)`);
+    }
+    ids = Array.isArray(raw.contact_ids) ? raw.contact_ids : [];
+    sourceMeta = { type: "segment_file", path: opts.fromSegment, input_count: ids.length, generated_at: raw.generated_at ?? null, definition: raw.definition ?? null };
+  } else {
+    const text = await fs.readFile(path.resolve(opts.idsFile), "utf8");
+    ids = text.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
+    sourceMeta = { type: "ids_file", path: opts.idsFile, input_count: ids.length };
+  }
+  const bad = ids.filter((id) => !UUID_RE.test(id));
+  const good = ids.filter((id) => UUID_RE.test(id));
+  return { ids: good, badUuids: bad, sourceMeta };
+}
+
+export async function plan(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  const prefix = String(opts.tagPrefix || "").trim();
+  if (!TAG_PREFIX_RE.test(prefix)) {
+    console.error(`Error: --tag-prefix must be slug-safe lowercase ([a-z0-9-], got "${prefix}").`);
+    process.exit(1);
+  }
+  const batchSize = Number(opts.batchSize ?? 75);
+  if (!Number.isInteger(batchSize) || batchSize < 1) { console.error("Error: --batch-size must be ≥ 1."); process.exit(1); }
+  if (batchSize > 500) console.log(`⚠ batch size ${batchSize} is large — Meta tier risk; the runbook default is 75.`);
+
+  let cohort;
+  try { cohort = await readCohort(opts, orgId); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  if (cohort.badUuids.length) console.log(`⚠ skipped ${cohort.badUuids.length} non-UUID line(s) in the cohort source.`);
+  if (!cohort.ids.length) { console.error("Error: no valid contact ids in the cohort source."); process.exit(1); }
+
+  let resp;
+  try {
+    resp = await http.post("segments", {
+      mode: "plan", organization_id: orgId,
+      contact_ids: cohort.ids, include_unsafe: !!opts.includeUnsafe,
+    });
+  } catch (e) {
+    console.error(`Plan failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+  if (!resp.safe_count) { console.error("Nothing to tag — 0 safe contacts after exclusions (V-13)."); process.exit(1); }
+
+  // Slice safe_ids into contiguous batches (client-side, per the spec split).
+  const batches = [];
+  for (let i = 0; i < resp.safe_ids.length; i += batchSize) {
+    const nn = String(batches.length + 1).padStart(2, "0");
+    batches.push({ tag: `${prefix}-batch-${nn}`, count: Math.min(batchSize, resp.safe_ids.length - i), contact_ids: resp.safe_ids.slice(i, i + batchSize) });
+  }
+
+  const slug = slugify(opts.segment || prefix, prefix);
+  const planDoc = {
+    schema_version: 1,
+    segment: slug,
+    organization_id: resp.organization_id,
+    organization_slug: slugify(resp.organization_name, resp.organization_id.slice(0, 8)),
+    tag_prefix: prefix,
+    batch_size: batchSize,
+    created_at: new Date().toISOString(),
+    source: cohort.sourceMeta,
+    exclusions: {
+      policy: opts.includeUnsafe ? "include_unsafe" : "broadcast_safe",
+      excluded_counts: Object.fromEntries(Object.entries(resp.excluded).map(([k, v]) => [k, v.length])),
+      excluded_ids: resp.excluded,
+    },
+    safe_count: resp.safe_count,
+    batch_count: batches.length,
+    batches,
+    applied: null,
+  };
+  await fs.mkdir(SEG_DIR, { recursive: true });
+  await fs.writeFile(planPath(slug), JSON.stringify(planDoc, null, 2) + "\n", "utf8");
+
+  const ex = planDoc.exclusions.excluded_counts;
+  console.log(`Wrote ${planPath(slug)}`);
+  console.log(`  org:      ${resp.organization_name}`);
+  console.log(`  input:    ${resp.input_count} · safe: ${resp.safe_count} · excluded: ${ex.not_allow_broadcast + ex.archived + ex.blocked} (allow_broadcast ${ex.not_allow_broadcast}, archived ${ex.archived}, blocked ${ex.blocked}) · not_found ${ex.not_found_in_org} · dupes ${ex.duplicate_in_input}`);
+  console.log(`  batches:  ${batches.length} × ≤${batchSize}  (${batches[0].tag} … ${batches[batches.length - 1].tag})`);
+  if (cohort.sourceMeta.generated_at) {
+    console.log(`  ⚠ tagging point-in-time ids from ${cohort.sourceMeta.generated_at} — re-derive the cohort SQL if freshness matters.`);
+  }
+  console.log("");
+  console.log(`Next: flowiq segments apply ${orgId} ${slug} [--commit]`);
+}
+
+export async function apply(orgId, identifier, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  let filePath;
+  try { filePath = await resolvePlan(identifier); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  const planDoc = JSON.parse(await fs.readFile(filePath, "utf8"));
+  if (planDoc.organization_id !== orgId) {
+    console.error(`Plan is for org ${planDoc.organization_id}, you passed ${orgId} — refusing (V-10).`);
+    process.exit(1);
+  }
+  if (!Array.isArray(planDoc.batches) || !planDoc.batches.length) {
+    console.error("Plan has no batches — re-run `segments plan` (V-10).");
+    process.exit(1);
+  }
+
+  const total = planDoc.batches.reduce((a, b) => a + b.contact_ids.length, 0);
+  console.log(`Plan ${planDoc.segment}: ${planDoc.batches.length} batch tag(s), ${total} contact(s) on ${planDoc.organization_slug}.`);
+
+  // V-11: warn when the batch tags already carry members (tag reuse merges counts).
+  try {
+    const before = await http.post("segments", { mode: "list", organization_id: orgId, prefix: planDoc.tag_prefix });
+    const existing = (before.tags || []).filter((t) => Number(t.count) > 0);
+    if (existing.length) {
+      console.log(`⚠ ${existing.length} of these tags already have members (counts will MERGE):`);
+      for (const t of existing.slice(0, 5)) console.log(`    ${t.tag}: ${t.count}`);
+      if (!opts.yes && opts.commit) {
+        const a = await ask("Type y to proceed anyway: ");
+        if (a.toLowerCase() !== "y") { console.log("Aborted — nothing tagged."); process.exit(0); }
+      }
+    }
+  } catch { /* the pre-check is best-effort */ }
+
+  if (!opts.commit) {
+    console.log(`DRY RUN — would tag ${total} contact(s) across ${planDoc.batches.length} batch tag(s). Add --commit to apply.`);
+    return;
+  }
+  if (!opts.yes) {
+    const a = await ask(`Type the segment name ("${planDoc.segment}") to tag ${total} contact(s): `);
+    if (a !== planDoc.segment) { console.log("Mismatch — aborted, nothing tagged."); process.exit(0); }
+  }
+
+  let resp;
+  try {
+    resp = await http.post("segments", {
+      mode: "apply", organization_id: orgId,
+      batches: planDoc.batches.map((b) => ({ tag: b.tag, contact_ids: b.contact_ids })),
+    });
+  } catch (e) {
+    console.error(`Apply failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  for (const r of resp.results || []) {
+    console.log(`  ${r.tag.padEnd(40)} tagged ${r.tagged}${r.already_had ? ` · already_had ${r.already_had}` : ""}${r.not_found ? ` · not_found ${r.not_found}` : ""}`);
+  }
+  console.log(`Totals: tagged ${resp.totals.tagged} · already_had ${resp.totals.already_had} · not_found ${resp.totals.not_found}`);
+
+  planDoc.applied = { at: new Date().toISOString(), tag_counts: Object.fromEntries((resp.results || []).map((r) => [r.tag, r.tagged + r.already_had])) };
+  await fs.writeFile(filePath, JSON.stringify(planDoc, null, 2) + "\n", "utf8");
+  console.log("");
+  console.log(`Send per tag, one batch at a time: flowiq broadcast send ${orgId} --tag ${planDoc.batches[0].tag} --template <name> …`);
+}
+
+export async function list(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  let resp;
+  try { resp = await http.post("segments", { mode: "list", organization_id: orgId, prefix: opts.prefix }); }
+  catch (e) { console.error(`List failed: ${e.message}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.tags?.length) { console.log(`(no tags${opts.prefix ? ` with prefix "${opts.prefix}"` : ""} on ${resp.organization_name})`); return; }
+  for (const t of resp.tags) console.log(`  ${String(t.tag).padEnd(44)} ${t.count}`);
+  console.log(`  ${"TOTAL".padEnd(44)} ${resp.total_tagged}`);
+}
+
+export async function untag(orgId, identifier, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  let filePath;
+  try { filePath = await resolvePlan(identifier); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  const planDoc = JSON.parse(await fs.readFile(filePath, "utf8"));
+  if (planDoc.organization_id !== orgId) {
+    console.error(`Plan is for org ${planDoc.organization_id}, you passed ${orgId} — refusing.`);
+    process.exit(1);
+  }
+  const tags = (planDoc.batches || []).map((b) => b.tag);
+  if (!tags.length) { console.error("Plan has no batch tags."); process.exit(1); }
+
+  if (!opts.commit) {
+    console.log(`DRY RUN — would remove ${tags.length} batch tag(s): ${tags.join(", ")}. Add --commit --confirm to remove.`);
+    return;
+  }
+  if (!opts.confirm) {
+    console.error("untag is destructive — add --confirm alongside --commit (V-12).");
+    process.exit(1);
+  }
+
+  let resp;
+  try { resp = await http.post("segments", { mode: "untag", organization_id: orgId, tags }); }
+  catch (e) { console.error(`Untag failed: ${e.message}`); process.exit(1); }
+  for (const r of resp.results || []) console.log(`  ${r.tag.padEnd(40)} removed ${r.removed}`);
+  console.log(`Totals: removed ${resp.totals.removed}`);
+}

package/src/index.js

@@ -24,6 +24,8 @@ import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
 import * as customToolsCmd from "./commands/custom-tools.js";
+import * as broadcastCmd from "./commands/broadcast.js";
+import * as segmentsCmd from "./commands/segments.js";
 
 // Read version from package.json so it stays in sync with the published npm
 // version automatically (single source of truth — bumping package.json on each
@@ -217,10 +219,10 @@ export function run(argv) {
     .option("--discount [bool]", "agent.discount.enabled (true if bare)")
     .action((orgId, opts) => agentConfigCmd.config(orgId, opts));
 
-  // agent-updates (pending client change-requests + chat context; read-only)
+  // agent-updates (pending client change-requests + chat context; pull + resolve)
   const au = program.command("agent-updates")
     .alias("au")
-    .description("Pull pending agent_updates + the chat context around each (read-only)");
+    .description("Pull pending agent_updates + the chat context around each; resolve a ticket with a client-facing note");
   au.command("pull <organization_id>")
     .description("Fetch updates + linked contact + trigger-message window; downloads attachments locally")
     .option("--status <status>", "pending (default) | resolved | in_progress | all")
@@ -234,6 +236,14 @@ export function run(argv) {
   au.command("list")
     .description("List local agent-updates snapshots")
     .action(() => agentUpdatesCmd.list());
+  au.command("resolve <update_id>")
+    .description("Flip a client-raised ticket to resolved/declined + write the client-facing note (the client reads \"FlowIQ: <note>\")")
+    .option("--note <text>", "client-facing note (required when resolving)")
+    .option("--internal <text>", "staff-only note (never shown to the client)")
+    .option("--image <url>", "client-facing response image URL")
+    .option("--status <status>", "resolved (default) | declined", "resolved")
+    .option("--yes", "skip the interactive confirm gate (the --note requirement still applies)")
+    .action((updateId, opts) => agentUpdatesCmd.resolve(updateId, opts));
 
   // export (full chat history → TXT, byte-identical to the in-app export)
   const exp = program.command("export").description("Export data to local files");
@@ -335,5 +345,83 @@ export function run(argv) {
     .description("List local custom-tools snapshots")
     .action(() => customToolsCmd.list());
 
+  // broadcast (CSV → per-row WhatsApp template broadcast; spec: flowiq-broadcast-send-SPEC)
+  const broadcast = program.command("broadcast")
+    .alias("bc")
+    .description("Send an APPROVED WhatsApp template to every row of a CSV (per-row column→param mapping)");
+  broadcast.command("map <organization_id>")
+    .description("Introspect the template + CSV and build/refresh the saved mapping interactively (no send)")
+    .requiredOption("--template <name>", "approved Meta template name")
+    .requiredOption("--csv <file>", "path to the recipients CSV")
+    .option("--campaign <name>", "campaign id / config file slug (default: CSV filename)")
+    .option("--force-remap", "ignore the saved mapping and rebuild interactively")
+    .action((orgId, opts) => broadcastCmd.map(orgId, opts));
+  broadcast.command("preview <organization_id>")
+    .description("Dry-run render of sample rows (exact message text + resolved button URL); never sends")
+    .option("--template <name>", "template (default: from the saved campaign)")
+    .option("--csv <file>", "CSV (default: from the saved campaign)")
+    .option("--campaign <name>", "campaign id / config file slug")
+    .option("--rows <n>", "how many sample rows to render", "3")
+    .action((orgId, opts) => broadcastCmd.preview(orgId, opts));
+  broadcast.command("send <organization_id>")
+    .description("Run the full pipeline. DRY-RUN by default; --commit sends (type the campaign name to confirm). Recipients from --csv OR --tag.")
+    .requiredOption("--template <name>", "approved Meta template name")
+    .option("--csv <file>", "path to the recipients CSV (per-row values)")
+    .option("--tag <tag>", "send to every broadcast-safe contact carrying this tag (e.g. a segments batch tag)")
+    .option("--body <k=v>", "with --tag: body param (repeatable), e.g. --body param1=\"Hi {{first_name}}\"", broadcastCmd.collectKV, {})
+    .option("--button <k=v>", "with --tag: dynamic URL button param, e.g. --button param1=<short-code>", broadcastCmd.collectKV, {})
+    .option("--campaign <name>", "campaign id / config file slug (default: CSV filename / tag)")
+    .option("--commit", "actually send (omit to dry-run)")
+    .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")
+    .option("--force-remap", "ignore the saved mapping and rebuild interactively")
+    .option("--illegal-chars <mode>", "reject | strip — newlines/tabs/4+ spaces in values (Meta #100)", "reject")
+    .option("--rate <n>", "max messages per second (hard cap 10)", "8")
+    .option("--upsert-batch <n>", "contacts per upsert call (max 4000)", "4000")
+    .option("--skip-upsert", "assume contacts already exist; skip the upsert stage")
+    .option("--limit <n>", "only process the first N valid rows (smoke test)")
+    .option("--resume", "continue from the existing status log instead of starting fresh")
+    .option("--retry-failed", "with --resume: also re-attempt rows previously marked failed")
+    .action((orgId, opts) => broadcastCmd.send(orgId, opts));
+  broadcast.command("resume <organization_id>")
+    .description("Continue an interrupted campaign: only unsent rows from the status log; ambiguous in-flight rows are NEVER auto-resent")
+    .requiredOption("--campaign <name>", "campaign id / config file slug")
+    .option("--commit", "actually send (omit to dry-run the remaining rows)")
+    .option("--yes", "skip the confirm gate")
+    .option("--rate <n>", "max messages per second (hard cap 10)", "8")
+    .option("--retry-failed", "also re-attempt rows previously marked failed (confirmed failures only)")
+    .action((orgId, opts) => broadcastCmd.resume(orgId, opts));
+  broadcast.command("list")
+    .description("List local campaigns + sent counts")
+    .action(() => broadcastCmd.list());
+
+  // segments (cohort → batch tags; tags only — the send is `broadcast send --tag`)
+  const segments = program.command("segments")
+    .alias("seg")
+    .description("Slice a contact cohort into fixed-size batch tags and bulk-apply them (broadcast batching)");
+  segments.command("plan <organization_id>")
+    .description("Ingest a cohort id list, apply broadcast-safety exclusions, slice into N-sized batch tags, write the plan (no DB write)")
+    .requiredOption("--tag-prefix <name>", "campaign tag stem; batches become <prefix>-batch-NN")
+    .option("--from-segment <path>", "a segments snapshot JSON (uses its contact_ids[])")
+    .option("--ids-file <path>", "a plain newline/CSV file of contact UUIDs")
+    .option("--batch-size <n>", "contacts per batch tag", "75")
+    .option("--segment <name>", "plan file slug (default: the tag prefix)")
+    .option("--include-unsafe", "do NOT exclude non-broadcast-safe contacts (rare; default excludes)")
+    .action((orgId, opts) => segmentsCmd.plan(orgId, opts));
+  segments.command("apply <organization_id> <slug-or-path>")
+    .description("Append the plan's batch tags to their contacts. DRY-RUN by default; --commit to write (append-only, idempotent)")
+    .option("--commit", "actually write the tags")
+    .option("--yes", "skip the type-the-segment-name confirm gate")
+    .action((orgId, id, opts) => segmentsCmd.apply(orgId, id, opts));
+  segments.command("list <organization_id>")
+    .description("VERIFY: print tag → contact count (read-only)")
+    .option("--prefix <substr>", "only tags starting with this prefix (recommended)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => segmentsCmd.list(orgId, opts));
+  segments.command("untag <organization_id> <slug-or-path>")
+    .description("ROLLBACK: remove the plan's own batch tags. Destructive — needs --commit AND --confirm")
+    .option("--commit", "actually remove (omit to dry-run)")
+    .option("--confirm", "required alongside --commit")
+    .action((orgId, id, opts) => segmentsCmd.untag(orgId, id, opts));
+
   program.parseAsync(argv);
 }