@flowapt/flowiq-cli 0.3.3 → 0.3.4

package/README.md

@@ -194,6 +194,15 @@ flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
   `/api/send-template` as `headerMedia`, the same field the dashboard uses. A
   media-header template with no resolvable image is refused (pass
   `--header-media`).
+- **`--python` engine (v0.3.4, `send --tag` only)**: hand the whole send to the
+  **python `/meta-broadcast` endpoint** — the *same* sender the dashboard's "Python
+  endpoint" toggle uses — via a staff-gated proxy (the master key stays server-side
+  in `VITE_PYTHON_RENDER_API_KEY`; the CLI never holds it). Python resolves the tag
+  + eligibility (`allow_broadcast=true`, not blocked; **no 2000-cap, paginated**) and
+  sends **fire-and-forget**, returning a `broadcastId`. Dry-run (no `--commit`) asks
+  python for the eligible count + a sample. Trade-off vs the default per-row engine:
+  no CLI write-ahead-log / `resume` (python owns the broadcast record), and archived
+  contacts aren't separately filtered. Media headers work on both engines.
 - **v1 scope**: Meta orgs, POSITIONAL templates, text / no header / media header.
   NAMED and carousel templates and WATI orgs are refused with a clear message.
 - **Validation before anything sends**: APPROVED-only, every slot mapped,

package/TEAM-GUIDE.md

@@ -92,6 +92,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Split a big id-list cohort into send-safe batch tags | `flowiq seg plan <org_id> --tag-prefix … --ids-file …` → `flowiq seg apply … --commit` |
 | Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` |
 | Send a broadcast whose template has an IMAGE header | Same as above — the image is automatic (the template's own header image). Override with `--header-media <public-image-url>` if needed. |
+| Send via the SAME engine as the dashboard's "Python" toggle | add `--python` to a `bc send --tag …` (fire-and-forget; python resolves the tag + sends + tracks; no CLI resume for this engine) |
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |
 | Export an org's full chat history | `flowiq export chats <org_id>` |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/broadcast.js

@@ -731,6 +731,54 @@ export function collectKV(pair, mapAcc) {
   return mapAcc;
 }
 
+/** --python engine: hand the send to the python /meta-broadcast endpoint via the
+ *  staff-gated proxy. Fire-and-forget — python resolves the tag + eligibility
+ *  (allow_broadcast=true, not blocked) and sends in the background, returning a
+ *  broadcastId. No CLI write-ahead log / resume for this engine (python owns the
+ *  broadcast record). Dry-run (no --commit) asks python for the eligible count. */
+async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage }) {
+  const reqBody = (dryRun) => ({
+    action: "send-python", organization_id: orgId, tag, template_name: templateName,
+    body_parameters: bodyLiterals,
+    ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
+    ...(headerMedia ? { header_media: headerMedia } : {}),
+    dry_run: dryRun,
+  });
+
+  // Dry-run: python fetches the eligible contacts (no send) → count + sample.
+  let dry;
+  try { dry = await http.post("broadcast", reqBody(true)); }
+  catch (e) { console.error(`Python dry-run failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  const total = dry.total_contacts_found ?? 0;
+
+  console.log("");
+  console.log(`Engine: PYTHON (yapi.store/meta-broadcast) — fire-and-forget, python-tracked.`);
+  console.log(`Tag "${tag}": ${total} eligible contact(s) (allow_broadcast + not blocked, resolved server-side).`);
+  const sampleNum = dry.sample_contacts?.[0]?.whatsapp_id || dry.sample_contacts?.[0]?.phone_number || "<first eligible>";
+  renderPreview(template, { rownum: 1, number: sampleNum, values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
+    console.log("  ({{first_name}}-style tokens are resolved PER CONTACT by python)");
+  }
+  console.log("");
+
+  if (!commitStage) {
+    console.log("DRY RUN — nothing sent. Add --commit to fire the python broadcast.");
+    return;
+  }
+  if (!total) { console.log("Nothing eligible under this tag."); return; }
+  if (!opts.yes) {
+    const answer = await ask(`Type the tag ("${tag}") to fire the python broadcast to ${total} contact(s): `);
+    if (answer !== tag) { console.log("Mismatch — aborted, nothing sent."); process.exit(0); }
+  }
+
+  let out;
+  try { out = await http.post("broadcast", reqBody(false)); }
+  catch (e) { console.error(`Python broadcast failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log("");
+  console.log(`✅ ${out.message || "Broadcast started"}${out.broadcastId ? `  ·  broadcastId ${out.broadcastId}` : ""}`);
+  console.log(`   Python is sending in the background${out.mode ? ` (${out.mode})` : ""} and tracking it under that broadcast id — no CLI resume for this engine.`);
+}
+
 async function runTagPipeline(orgId, opts, { commitStage }) {
   if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
   const campaign = opts.campaign || slugify(opts.tag, "tag-campaign");
@@ -764,6 +812,13 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   if (template.url_button?.present && !buttonLiteral) aborts.push("template has a dynamic URL button — pass --button param1=<code>");
   if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
 
+  // --python: hand the whole send to the python /meta-broadcast engine (the same
+  // sender the dashboard's "Python endpoint" toggle uses) via the staff-gated
+  // proxy. Python resolves the tag + eligibility + sends fire-and-forget.
+  if (opts.python) {
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+  }
+
   // resolve the tag server-side (broadcast-safe recipients only)
   let resolved;
   try { resolved = await http.post("broadcast", { action: "resolve-tag", organization_id: orgId, tag }); }
@@ -877,6 +932,7 @@ export async function preview(orgId, opts = {}) {
 
 export async function send(orgId, opts = {}) {
   if (opts.tag && opts.csv) { console.error("Error: --tag and --csv are mutually exclusive."); process.exit(1); }
+  if (opts.python && !opts.tag) { console.error("Error: --python requires --tag (the python engine is tag-based)."); process.exit(1); }
   if (opts.tag) return runTagPipeline(orgId, opts, { commitStage: !!opts.commit });
   await runPipeline(orgId, opts, { commitStage: !!opts.commit, isResume: !!opts.resume });
 }

package/src/index.js

@@ -391,6 +391,7 @@ export function run(argv) {
     .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("--header-media <url>", "header image/video/doc URL for a media-header template (default: the template's own stored image)")
+    .option("--python", "with --tag: send via the python /meta-broadcast engine (same as the dashboard's Python toggle; fire-and-forget, python-tracked)")
     .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")