@flowapt/flowiq-cli 0.4.9 → 0.6.0

package/README.md

@@ -199,6 +199,16 @@ template's variables **per row** from the CSV's own columns. The
 highest-stakes command in the CLI — built as a map → preview → commit
 pipeline with several layers of deliberate friction.
 
+**v0.6.0 — the CSV send is a server-side fan-out.** A commit imports every
+sendable row as a contact carrying the campaign tag `bc-<campaign>` plus that
+row's values as campaign-scoped attributes (`bc_<campaign>_param1…` /
+`_button`), then fires **ONE** python `/meta-broadcast` call whose params are
+`{{attributes.bc_<campaign>_paramN}}` tokens — python resolves them **per
+contact** (body AND URL-button) and paces the send server-side. The CLI
+returns in seconds; closing the laptop no longer matters. A 1,846-row CSV
+that took ~77 min on the old per-row loop is now python-paced like any big
+tag send.
+
 ```bash
 # 1) Build the column→param mapping interactively (saved per campaign, no send)
 flowiq bc map <org_id> --template rewards_referral_v1 --csv ./people.csv --campaign july-referrals
@@ -206,11 +216,15 @@ flowiq bc map <org_id> --template rewards_referral_v1 --csv ./people.csv --campa
 # 2) Dry-run: validation + exact rendered messages for sample rows (default)
 flowiq bc send <org_id> --template rewards_referral_v1 --csv ./people.csv --campaign july-referrals
 
-# 3) Commit: upsert contacts, then send per row @ ≤8/s
+# 3) Commit: import+tag the rows, fire ONE python broadcast (returns a broadcastId)
 flowiq bc send <org_id> --template … --csv … --campaign july-referrals --commit
 #   → prompts: type the campaign name to confirm
+#   → then audit with: flowiq bc status <org_id> <broadcastId> [--failures]
+
+# 4) Re-fire ONLY the failed recipients (python campaigns have no per-row resume):
+flowiq bc retry <org_id> <broadcastId> --commit
 
-# 4) Interrupted? Continue only unsent rows:
+# (pre-v0.6.0 campaigns with a per-row status log still finish on the old loop:)
 flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
 
 # SCHEDULE a tag send for later instead of sending now (--at is SAST):
@@ -307,10 +321,31 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
   DRY-RUN by default (shows the failed count + reason breakdown); `--commit` fires.
   Note: permanent failures (e.g. `131026` undeliverable, opt-outs) just fail again —
   retry earns its keep on transient (throttle/throughput) failures. Capped at 500.
+- **CSV fan-out semantics (v0.6.0)** — the things the engine change makes true:
+  - **Per-row values persist on the contact** as `bc_<campaign>_paramN` /
+    `_button` attributes (and the `bc-<campaign>` tag) — deliberate: they're the
+    audit trail of exactly what each person was sent. Re-running a campaign
+    overwrites them with the current CSV's values. Names are safe: a blank/missing
+    CSV name can never null a real contact's name (the upsert RPC preserves it).
+  - **One campaign = one audience.** A campaign that already fanned out refuses
+    a re-run (`--resend` overrides, and resends to EVERY tagged contact — for
+    failures use `bc retry`, which re-fires only the failed ones). Smoke-test
+    with `--limit` under a THROWAWAY `--campaign`: a limited fan-off still
+    records the campaign as fired, and the full run would need `--resend`.
+  - **The audience is the TAG, not the file.** If an earlier run of the same
+    campaign tagged rows since removed from the CSV, python still resolves them —
+    the CLI cross-checks python's count against the CSV after tagging and makes
+    you type `YES` when the tag carries MORE people than the file.
+  - No per-row write-ahead log or `resume` on fresh sends — the campaign log
+    records ONE `handoff` line (broadcastId); delivery/failure detail lives in
+    `bc status <org> <broadcastId> [--failures]` and `bc retry`.
+  - `--rate` / `--skip-upsert` only apply to pre-v0.6.0 `resume`; fresh sends
+    ignore them (python paces itself; the upsert IS the mechanism).
 - **Engine auto-routing (v0.3.6):** any `send --tag` of **more than 10** eligible
   recipients **always uses the python engine** (a `>2000` tag routes there too).
-  Only a ≤10 send stays on the resumable per-row Node engine. `--python` forces
-  python at any size. (CSV per-row sends stay on Node — python takes uniform params.)
+  Only a ≤10 tag send stays on the per-row Node engine. `--python` forces
+  python at any size. **CSV sends are ALWAYS python from v0.6.0** (per-row values
+  ride as contact attributes — see above).
 - **`--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
@@ -350,17 +385,19 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
   blocked contacts are skipped, always.
 - **Dry-run is the default**; `--commit` + typing the campaign name is the
   only way to send (`--yes` for CI skips the typing, never the dry-run).
-- **Write-ahead status log** (`.flowiq/campaigns/<campaign>.status.jsonl`):
-  every row logs `sending` *before* the POST and `sent`/`failed` after. A
-  crash mid-row leaves an *ambiguous* row that is **never auto-resent** —
-  it's surfaced for manual review. `resume` sends only never-attempted rows
-  (`--retry-failed` adds confirmed failures).
-- **Error handling**: `#132000` aborts the run (config bug — every row would
-  fail); rate errors back off exponentially and halve the send rate; a Meta
-  daily-cap soft-stops cleanly with a resume hint.
-- Contacts are **pre-upserted** (`/cli/contacts-upsert`, ≤4000/batch, retries
-  then aborts) so the send payload never needs a `name` key — the classic
-  `#132000` footgun.
+- **Campaign status log** (`.flowiq/campaigns/<campaign>.status.jsonl`): a
+  fresh (v0.6.0) send records a `meta` header + ONE `handoff` line carrying the
+  `broadcastId` — the re-run guard and your local pointer to `bc status`.
+  Pre-v0.6.0 campaigns keep their per-row `sending`/`sent`/`failed` lines and
+  finish on `resume` (ambiguous mid-crash rows are still never auto-resent;
+  `--retry-failed` adds confirmed failures).
+- **Error handling**: all pre-send validation is unchanged and client-side;
+  per-recipient send errors are python-side — audit them with
+  `bc status <org> <broadcastId> --failures`, re-fire with `bc retry`.
+- Contacts are **imported/updated** via `/cli/contacts-upsert` (≤4000/batch,
+  retries then aborts) carrying the campaign tag + attributes; the python
+  params are pure `{{attributes.*}}` tokens, so the payload never needs a
+  `name` key — the classic `#132000` footgun stays structurally impossible.
 
 **Tag mode** — send to everyone carrying a tag (e.g. a `segments` batch tag)
 instead of a CSV. Same guards, same status log, same resume:
@@ -759,6 +796,40 @@ Validation: `platform` ∈ `{whatsapp, web}`, `type` from the per-platform
 allowed enum, valid http(s) URL, no duplicate (platform, type, url)
 tuples.
 
+**Auth fields (19 Aug 2026).** Each row also carries `auth_type`
+(`none` | `bearer` | `basic` | `api_key` | `oauth2_client_credentials`),
+`auth_config`, `headers` and `secret` — how FlowIQ authenticates when it POSTs
+the event, plus an optional HMAC signing key. Pull returns all four; push
+writes all four.
+
+**Because push is FULL-REPLACE, a body that omits these fields STRIPS the
+credentials off every webhook.** Always pull-edit-push the same file; never
+hand-write a push body. The dry-run diff includes an auth fingerprint, so
+changing only a credential correctly shows as `to insert 1 / to delete 1`
+rather than "unchanged".
+
+```jsonc
+{
+  "url": "https://middleware.example.com/notification/log",
+  "type": "sent_message",
+  "platform": "whatsapp",
+  "auth_type": "oauth2_client_credentials",
+  "auth_config": {
+    "token_url": "https://middleware.example.com/oauth2/token",
+    "client_id": "acme_flowapt",
+    "client_secret": "…",
+    "scope": "notify:write",        // optional
+    "client_auth": "basic"          // optional: "basic" (default) | "body"
+  },
+  "headers": { "X-Tenant": "acme" },  // optional static headers
+  "secret": "…"                       // optional → X-Flowiq-Signature: sha256=<hmac>
+}
+```
+
+Push refuses an `auth_type` whose credentials are incomplete (e.g. `bearer`
+with no `auth_config.token`), because that would make every delivery fail
+closed — FlowIQ never falls back to an unauthenticated send.
+
 ### FlowMod prompts — `flowiq flowmod pull|push <slug>` (alias `fm`)
 
 Round-trips a FlowMod org's **master-group** prompts + config. FlowMod groups
@@ -834,6 +905,33 @@ Editable fields: `name`, `description`, `status` (open / in_progress / done),
 null), `organizations[]`, `media[]`, `messages[]`, `created_by`. Array columns
 are full-replace within the row.
 
+### Client hours — `flowiq hours log|list|summary` (v0.5.0)
+
+The client-hours ledger. Every org's package includes **10 hours of Flowapt
+work per calendar month**; every piece of client work gets logged against it —
+manually here, or automatically by Claude sessions via the FlowIQ MCP's
+`log_client_hours` tool. Clients see their own usage on the Client Console;
+the cross-org view lives in the super-admin Changelog dialog → Client hours.
+
+```bash
+flowiq hours log <org_id> --hours 1.5 --desc "Rebuilt the abandoned-cart copy"   # fractions fine
+flowiq hours log <org_id> --minutes 45 --desc "Fixed template header" --date 2026-08-18
+flowiq hours list <org_id>                    # this month's entries + package standing
+flowiq hours list <org_id> --month 2026-07    # a past month
+flowiq hours summary                          # every org with logged work this month
+```
+
+- `log` takes exactly ONE of `--minutes <n>` (whole minutes) or `--hours <h>`
+  (fractions fine — `--hours 1.5` = 90 min). `--desc` is required and should be
+  plain language the client could read (it shows on their Client Console).
+- `--by` overrides who did the work (default: your staff login email);
+  `--date YYYY-MM-DD` backdates an entry (it counts toward THAT month);
+  `--session` tags the session/task name.
+- `list` / `summary` default to the current month and print each org's usage
+  against the 10h package, flagging any org that has gone over.
+- Corrections (delete/edit) live in the Changelog → Client hours page, not the
+  CLI. Every `log` is audited.
+
 ### WhatsApp templates — `flowiq templates pull|list|create|status` (alias `tpl`)
 
 Read an org's live templates straight from Meta (read-only), and submit new

package/TEAM-GUIDE.md

@@ -60,7 +60,11 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
    would change before anything writes.
 3. **Pushes are full-replace.** What's in your file becomes the whole surface
    (all prompt sections, all tools, all webhooks). Deleting an entry from the
-   file deletes it from the platform.
+   file deletes it from the platform. This is also why you must never
+   hand-write a push body: messaging webhooks carry their own credentials
+   (`auth_type` / `auth_config` / `headers` / `secret`), and a body that leaves
+   those fields out strips the auth off every webhook for that org. Pull, edit
+   that same file, push it.
 4. **`--agent <id>` targets a specific agent**; without it you get the org's
    *active* agent. Files remember which agent they came from, so a push always
    goes back to the agent you pulled — never "whatever is active now".
@@ -101,7 +105,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign X --content X --commit` |
 | Check which links a campaign has, and their clicks | `flowiq links list <org_id> --campaign 13Aug_Seeds` |
 | A link already looks short (`linklnk.io/abc123`) — can I re-tag it? | No: paste the DESTINATION url instead. Re-shortening keeps the old campaign tag and splits the click count, so the CLI refuses it |
-| Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit` |
+| Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit`. **v0.6.0: the commit imports every row as a contact (tag `bc-<campaign>` + the row's values as attributes) and fires ONE python broadcast** — it returns in seconds with a `broadcastId`; python sends in the background. Check delivery with `bc status`, re-fire failures with `bc retry`. A campaign that already fired refuses a re-run (`--resend` deliberately resends to everyone tagged). |
 | Tag every repeat buyer (e.g. 2+ orders in the last 60 days) | `flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d` → `flowiq seg apply <org_id> repeat-60d` (dry run) → `… --commit` |
 | Tag everyone who bought a product (accurate, windowable) | `flowiq seg plan <org_id> --tag-prefix whey --bought "Whey" --window 90d` → `flowiq seg apply … --commit` |
 | Advanced Tagging in the terminal (one named tag on a matched set) | `flowiq tag field\|cohort\|segment\|attributes\|messages <org_id> …` (dry-run) → add `--tag <name> --commit` |
@@ -128,12 +132,14 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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` |
 | Manage Shopify/Woo platform webhooks | `flowiq wh pull <org_id>` → edit → `flowiq wh push <slug>` |
-| Manage outbound messaging webhooks | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
+| Manage outbound messaging webhooks (incl. their auth) | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
 | Create a brand-new client org | `flowiq org create --name "Client Name"` → then `agent create` on the printed id |
 | See a client's pending change requests | `flowiq au pull <org_id>` |
 | Close a client's change request (after verifying the fix!) | `flowiq au resolve <update_id> --note "what changed"` — the client reads the note |
 | Check an org's platform + active agent | `flowiq org info <org_id>` |
 | Work a Pin Board task | `flowiq pin list-remote open` → `pull` → edit → `push` |
+| Log hours you worked for a client (every package = 10h Flowapt work/month) | `flowiq hours log <org_id> --hours 1.5 --desc "what you did"` — plain language, the client sees it on their Client Console |
+| Check a client's package hours / the month across all clients | `flowiq hours list <org_id>` / `flowiq hours summary` |
 | Re-read this guide / the full command reference | `flowiq guide` / `flowiq guide --reference` |
 
 The flow is the same everywhere: **pull → edit the JSON → push**. Slugs are the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.4.9",
+  "version": "0.6.0",
   "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

@@ -6,17 +6,23 @@
 //   send    <org>  --template T --csv F [--commit]       full pipeline; DRY-RUN by default
 //   resume  <org>  --campaign C [--commit]               continue from the status log
 //
-// Pipeline: introspect template (live Meta + DB labels, via /cli/broadcast) →
-// parse CSV → build/load column→param MAPPING (each row fills the template
-// with its OWN values) → validate (V-1..V-13) → broadcast-safety classify
-// (opted-out/archived/blocked are skipped) → preview → [--commit] upsert
-// contacts (/cli/contacts-upsert, ≤4000/batch, 3× retry then ABORT) → send
-// per row via /api/send-template (org-UUID branch, NO auth header), paced
-// ≤10 msg/s, with a WRITE-AHEAD per-row status log:
-//   {status:"sending"} appended BEFORE the POST, the terminal sent/failed
-//   line after — so a crash mid-row leaves an ambiguous row that is NEVER
-//   auto-resent (surfaced for manual review). Resume dedups on
-//   normalized-number-within-campaign, never on CSV fingerprint.
+// Pipeline (v0.6.0 — python server-side fan-out): introspect template (live
+// Meta + DB labels, via /cli/broadcast) → parse CSV → build/load column→param
+// MAPPING (each row fills the template with its OWN values) → validate
+// (V-1..V-13) → broadcast-safety classify (opted-out/archived/blocked are
+// skipped) → preview → [--commit] upsert contacts (/cli/contacts-upsert,
+// ≤4000/batch, 3× retry then ABORT) carrying the campaign TAG bc-<campaign>
+// plus each row's values as campaign-scoped ATTRIBUTES
+// (bc_<campaign>_paramN / _button) → ONE python /meta-broadcast call with
+// {{attributes.bc_<campaign>_paramN}} tokens, which python resolves PER
+// CONTACT (broadcast.py substitute_contact_fields — body AND URL-button
+// params). The send is fire-and-forget: python owns pacing + the broadcast
+// record; audit via `bc status <org> <broadcastId>` / `bc retry`.
+//
+// The OLD per-row Node loop (write-ahead status log, `resume`) survives ONLY
+// to finish campaigns started before v0.6.0 — a fresh CSV send never uses it.
+// A python campaign records ONE {type:"handoff"} line instead; re-running it
+// needs --resend (the tag fan-out cannot skip already-reached rows).
 //
 // #132000 structural guard: the payload builder whitelists /^param\d+$/ keys
 // only — a stray "name" key (which would add a body param on a POSITIONAL
@@ -308,16 +314,18 @@ async function saveCampaign(cfg) {
 async function loadStatusLog(campaign) {
   const map = new Map();
   let header = null;
+  let handoff = null; // last {type:"handoff"} line — a completed python fan-off
   try {
     const text = await fs.readFile(logPath(campaign), "utf8");
     for (const line of text.split("\n")) {
       if (!line.trim()) continue;
       let obj; try { obj = JSON.parse(line); } catch { continue; }
       if (obj.type === "meta") { header = obj; continue; }
+      if (obj.type === "handoff") { handoff = obj; continue; }
       if (obj.type === "row" && obj.number) map.set(obj.number, obj);
     }
   } catch { /* no log yet */ }
-  return { header, map };
+  return { header, map, handoff };
 }
 
 async function appendLog(campaign, obj) {
@@ -602,11 +610,54 @@ function renderPreview(template, sample, headerMedia) {
   }
 }
 
-async function upsertContacts(orgId, rows, batchCap) {
+// ---------------------------------------------------------------------------
+// CSV → python fan-out builders (v0.6.0). Exported for the test harness.
+// ---------------------------------------------------------------------------
+
+/** The campaign's contact tag — what python resolves the audience from. */
+export const csvCampaignTag = (campaign) => `bc-${campaign}`;
+
+/** Campaign-scoped attribute key for one template slot ("param1".."paramN" | "button"). */
+export const csvAttrKey = (campaign, slot) => `bc_${campaign}_${slot}`;
+
+/** workSet rows → /cli/contacts-upsert contact rows: tag + per-row values as
+ *  attributes. full_name only when the CSV actually carries a non-empty name
+ *  (the RPC COALESCEs, so an omitted name can never null a real one). */
+export function buildCsvContactRows(workSet, campaign) {
+  const tag = csvCampaignTag(campaign);
+  return workSet.map((r) => {
+    const attributes = {};
+    for (const [k, v] of Object.entries(r.values)) {
+      // Same structural guard as the old per-row payload builder (V-12).
+      if (!/^param\d+$/.test(k)) throw new Error(`internal: stray value key "${k}" — refusing (V-12)`);
+      attributes[csvAttrKey(campaign, k)] = v;
+    }
+    if (r.buttonValue != null) attributes[csvAttrKey(campaign, "button")] = r.buttonValue;
+    return {
+      whatsapp_id: r.number,
+      ...(typeof r.contactName === "string" && r.contactName.trim() ? { full_name: r.contactName.trim() } : {}),
+      tags: [tag],
+      attributes,
+    };
+  });
+}
+
+/** The ONE shared param set handed to python — every value is an
+ *  {{attributes.bc_<campaign>_slot}} token python resolves per contact. */
+export function buildCsvTokenParams(template, campaign) {
+  const body = {};
+  for (const pos of template.body_positions) {
+    body[`param${pos}`] = `{{attributes.${csvAttrKey(campaign, `param${pos}`)}}}`;
+  }
+  const button = template.url_button?.present ? `{{attributes.${csvAttrKey(campaign, "button")}}}` : null;
+  return { body, button };
+}
+
+async function upsertContacts(orgId, contactRows, batchCap) {
   let created = 0, updated = 0, skippedN = 0, dropped = 0;
-  const uniq = rows;
+  const uniq = contactRows;
   for (let i = 0; i < uniq.length; i += batchCap) {
-    const chunk = uniq.slice(i, i + batchCap).map((r) => ({ whatsapp_id: r.number, full_name: r.contactName }));
+    const chunk = uniq.slice(i, i + batchCap);
     let resp = null, lastErr = null;
     for (let attempt = 1; attempt <= 3; attempt++) {
       try { resp = await http.post("contacts-upsert", { organization_id: orgId, contacts: chunk }); break; }
@@ -749,9 +800,16 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   let sendable = await applySafetyExclusions(orgId, valid, skipped);
   if (opts.limit) sendable = sendable.slice(0, Number(opts.limit));
 
-  // resume folding
-  const { header: logHeader, map: statusMap } = await loadStatusLog(campaign);
+  // resume folding (pre-v0.6.0 per-row campaigns only — python campaigns have no per-row log)
+  const { header: logHeader, map: statusMap, handoff } = await loadStatusLog(campaign);
   if (isResume) {
+    if (handoff) {
+      console.error(`Campaign "${campaign}" already fanned out via python on ${handoff.at}${handoff.broadcast_id ? ` (broadcastId ${handoff.broadcast_id})` : ""}.`);
+      console.error("There is no per-row resume on the python engine — python owns the send. Audit / re-fire failures with:");
+      console.error(`  flowiq bc status ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} [--failures]`);
+      console.error(`  flowiq bc retry  ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} --commit`);
+      process.exit(1);
+    }
     if (!logHeader) { console.error(`No status log for campaign "${campaign}" — nothing to resume.`); process.exit(1); }
     if (logHeader.csv_fingerprint && logHeader.csv_fingerprint !== csv.header_fingerprint) {
       console.error("CSV headers changed since this campaign started — start a NEW campaign instead of resuming.");
@@ -778,37 +836,142 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   console.log(`Summary: ${sendable.length} sendable · skipped ${skipped.length} (${Object.entries(skippedByReason).map(([k, v]) => `${k}: ${v}`).join(", ") || "none"})`);
   if (statusMap.size) console.log(`Status log: ${[...statusMap.values()].filter((s) => s.status === "sent").length} already sent · work set ${workSet.length}`);
   if (ambiguous.length) console.log(`⚠ ${ambiguous.length} number(s) have an AMBIGUOUS in-flight status (crash mid-send?) — never auto-resent: ${ambiguous.slice(0, 5).join(", ")}${ambiguous.length > 5 ? "…" : ""}. Check the chat, then edit the status log if they must be retried.`);
-  console.log(`Upsert plan: ${workSet.length} contacts in ${Math.ceil(workSet.length / CONTACT_BATCH_CAP)} batch(es)`);
-  const rate = Math.min(Number(opts.rate ?? 8) || 8, HARD_RATE_CAP);
-  console.log(`Send plan:   ${workSet.length} messages @ ≤${rate}/s ≈ ${Math.ceil(workSet.length / rate)}s`);
+  // ── OLD-STYLE RESUME (pre-v0.6.0 per-row campaign): finish it on the Node loop ──
+  if (isResume) {
+    const rate = Math.min(Number(opts.rate ?? 8) || 8, HARD_RATE_CAP);
+    console.log(`Send plan:   ${workSet.length} messages @ ≤${rate}/s (per-row Node loop — pre-v0.6.0 campaign)`);
+    if (!commitStage) {
+      console.log("");
+      console.log("DRY RUN — nothing was sent, no contacts written. Add --commit to send.");
+      return;
+    }
+    if (!workSet.length) { console.log("Nothing to send — all rows are already sent/skipped."); return; }
+    if (!opts.yes) {
+      console.log("");
+      const answer = await ask(`Type the campaign name ("${campaign}") to send ${workSet.length} message(s): `);
+      if (answer !== campaign) { console.log("Mismatch — aborted, nothing sent."); process.exit(0); }
+    }
+    await executeSendLoop({
+      orgId, campaign, templateName, workSet, statusMap, rate, headerMedia,
+      skippedCount: skipped.length,
+      writeMetaHeader: !logHeader,
+      metaExtras: { csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length },
+    });
+    return;
+  }
+
+  // ── FRESH SEND: python server-side fan-out (v0.6.0) ────────────────────────
+  // Per-row values ride as campaign-scoped contact attributes; ONE python
+  // /meta-broadcast call resolves {{attributes.bc_<campaign>_paramN}} per
+  // contact and paces the send server-side. No laptop in the loop.
+  const tag = csvCampaignTag(campaign);
+  const tokens = buildCsvTokenParams(template, campaign);
+  const batchCap = Math.min(Number(opts.upsertBatch ?? CONTACT_BATCH_CAP) || CONTACT_BATCH_CAP, CONTACT_BATCH_CAP);
+  if (opts.skipUpsert) console.log("⚠ --skip-upsert is ignored on the python CSV path — the upsert IS how per-row values reach python.");
+  console.log(`Engine:      PYTHON server-side fan-out (yapi.store/meta-broadcast) — fire-and-forget, python-paced`);
+  console.log(`Tag:         "${tag}"  ·  per-row values → attributes bc_${campaign}_param1..${template.body_var_count}${tokens.button ? " + _button" : ""}`);
+  console.log(`Plan:        upsert+tag ${workSet.length} contact(s) in ${Math.ceil(Math.max(1, workSet.length) / batchCap)} batch(es) → one python broadcast`);
+
+  // A prior fan-off means the tag already reached its audience — re-running
+  // resends to EVERY tagged contact (python cannot skip per row).
+  if (handoff && !opts.resend) {
+    console.log("");
+    console.log(`⚠ Campaign "${campaign}" ALREADY fanned out via python on ${handoff.at}${handoff.broadcast_id ? ` (broadcastId ${handoff.broadcast_id})` : ""}.`);
+    if (!commitStage) {
+      console.log("  A --commit re-run would resend to EVERY tagged contact (no per-row skip). Audit with bc status; re-fire failures with bc retry; pass --resend to deliberately resend to all.");
+    } else {
+      console.error("  Refusing to resend to the whole tag. Audit / re-fire failures with:");
+      console.error(`    flowiq bc status ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} [--failures]`);
+      console.error(`    flowiq bc retry  ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} --commit`);
+      console.error("  To deliberately resend to EVERYONE tagged, pass --resend.");
+      process.exit(1);
+    }
+  }
+  // A pre-v0.6.0 per-row log means part of the audience was already reached
+  // row-by-row — the tag fan-out cannot skip them, so this campaign must be
+  // finished on the old engine (bc resume) or restarted under a fresh slug.
+  if (statusMap.size > 0) {
+    const sentAlready = [...statusMap.values()].filter((s) => s.status === "sent").length;
+    if (!commitStage) {
+      console.log("");
+      console.log(`⚠ This campaign has a pre-v0.6.0 per-row status log (${sentAlready} already sent). A --commit here would be refused — finish it with \`flowiq bc resume\`, or start a fresh --campaign.`);
+    } else {
+      console.error("");
+      console.error(`Refusing: campaign "${campaign}" has a pre-v0.6.0 per-row status log (${sentAlready} row(s) already sent).`);
+      console.error("The python fan-out sends to the WHOLE tag and cannot skip already-sent rows. Either:");
+      console.error(`  flowiq bc resume ${orgId} --campaign ${campaign} --commit     # finish on the old per-row engine`);
+      console.error("  …or re-run under a NEW --campaign slug (fresh tag, everyone in the CSV gets it).");
+      process.exit(1);
+    }
+  }
 
   if (!commitStage) {
     console.log("");
-    console.log("DRY RUN — nothing was sent, no contacts written. Add --commit to send.");
+    console.log("DRY RUN — nothing was sent, no contacts written or tagged. Add --commit to send.");
     return;
   }
-  if (!workSet.length) { console.log("Nothing to send — all rows are already sent/skipped."); return; }
+  if (!workSet.length) { console.log("Nothing to send — all rows were skipped."); return; }
 
-  // 8. gate
+  // 8. gate (BEFORE any write — the upsert itself tags real contacts)
   if (!opts.yes) {
     console.log("");
-    const answer = await ask(`Type the campaign name ("${campaign}") to send ${workSet.length} message(s): `);
-    if (answer !== campaign) { console.log("Mismatch — aborted, nothing sent."); process.exit(0); }
+    const answer = await ask(`Type the campaign name ("${campaign}") to tag ${workSet.length} contact(s) and fire ONE python broadcast: `);
+    if (answer !== campaign) { console.log("Mismatch — aborted, nothing written, nothing sent."); process.exit(0); }
   }
 
-  // 9. upsert
-  if (!opts.skipUpsert && !(isResume && logHeader)) {
-    try { await upsertContacts(orgId, workSet, Math.min(Number(opts.upsertBatch ?? CONTACT_BATCH_CAP) || CONTACT_BATCH_CAP, CONTACT_BATCH_CAP)); }
-    catch (e) { console.error(e.message); process.exit(1); }
+  // 9. upsert: tag + per-row attributes (the fan-out's data plane)
+  try { await upsertContacts(orgId, buildCsvContactRows(workSet, campaign), batchCap); }
+  catch (e) { console.error(e.message); process.exit(1); }
+
+  // 10. python dry-run cross-check: what does the tag ACTUALLY resolve to?
+  const reqBody = (dryRun) => ({
+    action: "send-python", organization_id: orgId, tag, template_name: templateName,
+    body_parameters: tokens.body,
+    ...(tokens.button ? { button_parameters: { param1: tokens.button } } : {}),
+    ...(headerMedia ? { header_media: headerMedia } : {}),
+    dry_run: dryRun,
+  });
+  let pyTotal = null;
+  try {
+    const dry = await http.post("broadcast", reqBody(true));
+    pyTotal = dry.total_contacts_found ?? null;
+  } catch (e) {
+    console.error(`Python dry-run failed after tagging: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`);
+    console.error(`Nothing sent. The ${workSet.length} contact(s) ARE tagged "${tag}" — re-run to retry the fan-off.`);
+    process.exit(1);
+  }
+  if (pyTotal != null && pyTotal !== workSet.length) {
+    if (pyTotal > workSet.length) {
+      console.log(`⚠ Tag "${tag}" resolves to ${pyTotal} contact(s) — ${pyTotal - workSet.length} MORE than this CSV (tagged by an earlier run of this campaign?). They will ALSO receive the send.`);
+      if (!opts.yes) {
+        const extra = await ask(`Type YES to send to all ${pyTotal}: `);
+        if (extra !== "YES") { console.log(`Aborted — nothing sent. The tag still carries ${pyTotal} contact(s); use a fresh --campaign for a clean audience.`); process.exit(0); }
+      }
+    } else {
+      console.log(`Note: python resolves ${pyTotal} of ${workSet.length} tagged (the rest are opted-out/blocked server-side).`);
+    }
   }
 
-  // 10-11. send loop + report (shared with the --tag pipeline)
-  await executeSendLoop({
-    orgId, campaign, templateName, workSet, statusMap, rate, headerMedia,
-    skippedCount: skipped.length,
-    writeMetaHeader: !logHeader,
-    metaExtras: { csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length },
+  // 11. fire — ONE call; python paces + tracks the rest
+  let out;
+  try { out = await http.post("broadcast", reqBody(false)); }
+  catch (e) { console.error(`Python broadcast failed: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`); process.exit(1); }
+  if (!logHeader) {
+    await appendLog(campaign, {
+      type: "meta", campaign, organization_id: orgId, template_name: templateName, engine: "python",
+      csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length,
+      started_at: new Date().toISOString(),
+    });
+  }
+  await appendLog(campaign, {
+    type: "handoff", engine: "python", tag, broadcast_id: out.broadcastId ?? out.broadcast_id ?? null,
+    tagged: workSet.length, python_total: pyTotal, at: new Date().toISOString(),
   });
+  console.log("");
+  console.log(`✅ ${out.message || "Broadcast started"}${out.broadcastId ? `  ·  broadcastId ${out.broadcastId}` : ""}`);
+  console.log(`   Python is sending in the background to tag "${tag}" (${pyTotal ?? workSet.length} contact(s)) and tracking it under that broadcast id.`);
+  console.log(`   Delivery:  flowiq bc status ${orgId} ${out.broadcastId || "<broadcast_id>"} [--failures]`);
+  console.log(`   Failures:  flowiq bc retry  ${orgId} ${out.broadcastId || "<broadcast_id>"} --commit`);
 }
 
 /** The paced, write-ahead-logged per-row send loop + final report. */

package/src/commands/hours.js

@@ -0,0 +1,150 @@
+// `flowiq hours log <org> --minutes N|--hours H --desc "…"` / `list <org>` /
+// `summary`. The client-hours ledger: every org's package includes 10 hours of
+// Flowapt work per calendar month, and every piece of client work gets logged
+// against it (manually here, or automatically by Claude via the FlowIQ MCP).
+// All writes happen server-side (/cli/hours) with the staff token.
+
+import { http } from "../http.js";
+
+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 MONTH_RE = /^\d{4}-(0[1-9]|1[0-2])$/;
+
+function fmtHours(minutes) {
+  const h = minutes / 60;
+  return `${Number.isInteger(h) ? h : h.toFixed(1)}h`;
+}
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId || "")) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID (find it with \`flowiq org list <search>\`).`);
+    process.exit(1);
+  }
+}
+
+function requireMonth(month) {
+  if (month && !MONTH_RE.test(month)) {
+    console.error(`Error: --month must be YYYY-MM (got "${month}").`);
+    process.exit(1);
+  }
+}
+
+/** --minutes and --hours are alternatives; exactly one must yield an integer minute count. */
+function resolveMinutes(opts) {
+  const hasMinutes = opts.minutes !== undefined;
+  const hasHours = opts.hours !== undefined;
+  if (hasMinutes === hasHours) {
+    console.error("Error: pass exactly one of --minutes <n> or --hours <h> (e.g. --hours 1.5).");
+    process.exit(1);
+  }
+  let minutes;
+  if (hasMinutes) {
+    minutes = Number(opts.minutes);
+    if (!Number.isInteger(minutes)) {
+      console.error(`Error: --minutes must be a whole number (got "${opts.minutes}"). Use --hours for fractions.`);
+      process.exit(1);
+    }
+  } else {
+    const h = Number(opts.hours);
+    if (!Number.isFinite(h)) {
+      console.error(`Error: --hours must be a number (got "${opts.hours}").`);
+      process.exit(1);
+    }
+    minutes = Math.round(h * 60);
+  }
+  if (minutes < 1 || minutes > 6000) {
+    console.error(`Error: the entry must be between 1 minute and 100 hours (got ${minutes} min).`);
+    process.exit(1);
+  }
+  return minutes;
+}
+
+export async function log(orgId, opts) {
+  requireOrg(orgId);
+  const minutes = resolveMinutes(opts);
+  const description = (opts.desc || "").trim();
+  if (!description) {
+    console.error('Error: --desc "what was done" is required.');
+    process.exit(1);
+  }
+  if (opts.date && !/^\d{4}-\d{2}-\d{2}$/.test(opts.date)) {
+    console.error(`Error: --date must be YYYY-MM-DD (got "${opts.date}").`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("hours", {
+      organization_id: orgId,
+      description,
+      minutes,
+      performed_by: opts.by || undefined,
+      session: opts.session || undefined,
+      // A bare date logs at noon UTC so it can never slip into a neighbouring
+      // day (or month) in any sane timezone rendering.
+      performed_at: opts.date ? `${opts.date}T12:00:00Z` : undefined,
+    });
+  } catch (e) {
+    console.error(`Log failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  const used = resp.month_total_minutes;
+  const allowance = resp.allowance_hours * 60;
+  console.log(`Logged ${fmtHours(minutes)} for ${resp.organization.name}`);
+  console.log(`  entry:  ${resp.id}`);
+  console.log(`  month:  ${resp.month} — ${fmtHours(used)} of ${resp.allowance_hours}h package used${used > allowance ? `  ⚠ ${fmtHours(used - allowance)} OVER` : ` (${fmtHours(allowance - used)} left)`}`);
+}
+
+export async function list(orgId, opts) {
+  requireOrg(orgId);
+  requireMonth(opts.month);
+  let resp;
+  try {
+    resp = await http.get("hours", { organization_id: orgId, month: opts.month });
+  } catch (e) {
+    console.error(`List failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  const over = resp.remaining_minutes < 0;
+  console.log(`${resp.organization.name} — ${resp.month}`);
+  console.log(`  package: ${resp.allowance_hours}h/month · used ${fmtHours(resp.total_minutes)} · ${over ? `⚠ ${fmtHours(-resp.remaining_minutes)} OVER` : `${fmtHours(resp.remaining_minutes)} left`}`);
+  if (!resp.entries.length) {
+    console.log("  (no entries this month)");
+    return;
+  }
+  console.log("");
+  for (const e of resp.entries) {
+    const when = String(e.performed_at).slice(0, 10);
+    const src = e.source === "manual" ? "ui" : e.source;
+    console.log(`  ${when}  ${fmtHours(e.minutes).padStart(6)}  [${src}]  ${e.performed_by} — ${e.description}`);
+  }
+}
+
+export async function summary(opts) {
+  requireMonth(opts.month);
+  let resp;
+  try {
+    resp = await http.get("hours", { summary: "1", month: opts.month });
+  } catch (e) {
+    console.error(`Summary failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  if (!resp.organizations.length) {
+    console.log(`(no hours logged for any org in ${resp.month})`);
+    return;
+  }
+  const allowance = resp.allowance_hours * 60;
+  console.log(`Client hours — ${resp.month} (package: ${resp.allowance_hours}h/month per org)\n`);
+  for (const o of resp.organizations) {
+    const flag = o.total_minutes > allowance ? `  ⚠ ${fmtHours(o.total_minutes - allowance)} OVER` : "";
+    console.log(`  ${fmtHours(o.total_minutes).padStart(6)}  (${String(o.entries).padStart(2)} entr${o.entries === 1 ? "y" : "ies"})  ${o.name || o.id}${flag}`);
+  }
+}

package/src/commands/messaging-webhooks.js

@@ -97,8 +97,15 @@ export async function push(identifier, opts = {}) {
   try {
     resp = await http.post("messaging-webhooks", {
       organization_id: data.organization_id,
+      // auth_type / auth_config / headers / secret ride along deliberately:
+      // push is FULL-REPLACE (delete-all then insert), so dropping them here
+      // would silently strip every webhook's credentials on the next push.
       messaging_webhooks: data.messaging_webhooks.map((w) => ({
         url: w.url, type: w.type, platform: w.platform,
+        auth_type: w.auth_type ?? "none",
+        auth_config: w.auth_config ?? null,
+        headers: w.headers ?? null,
+        secret: w.secret ?? null,
       })),
       dry_run: !!opts.dryRun,
     });

package/src/index.js

@@ -15,6 +15,7 @@ import * as webhooksCmd from "./commands/webhooks.js";
 import * as flowmodCmd from "./commands/flowmod.js";
 import * as groupsCmd from "./commands/groups.js";
 import * as pinboardCmd from "./commands/pinboard.js";
+import * as hoursCmd from "./commands/hours.js";
 import * as templatesCmd from "./commands/templates.js";
 import * as orgCmd from "./commands/org.js";
 import * as agentConfigCmd from "./commands/agent-config.js";
@@ -191,6 +192,29 @@ export function run(argv) {
     .description("List every task in the DB (optionally filter: open | in_progress | done) to find an id")
     .action((status) => pinboardCmd.listRemote(status));
 
+  // hours (client-hours ledger — every org's package = 10h Flowapt work/month)
+  const hours = program.command("hours")
+    .description("Client-hours ledger: log + report Flowapt work against each org's 10h/month package");
+  hours.command("log <organization_id>")
+    .description("Log work done for a client org (exactly one of --minutes / --hours)")
+    .option("--minutes <n>", "duration in whole minutes")
+    .option("--hours <h>", "duration in hours (fractions fine, e.g. 1.5)")
+    .option("--desc <text>", "what was done, in plain language the client could read")
+    .option("--by <name>", "who did the work (default: your staff login email)")
+    .option("--session <name>", "session/task name the work happened in")
+    .option("--date <YYYY-MM-DD>", "when the work was done (default: now)")
+    .action((orgId, opts) => hoursCmd.log(orgId, opts));
+  hours.command("list <organization_id>")
+    .description("One org's entries + package standing for a month (default: current)")
+    .option("--month <YYYY-MM>", "which month to report")
+    .option("--json", "raw JSON output")
+    .action((orgId, opts) => hoursCmd.list(orgId, opts));
+  hours.command("summary")
+    .description("Cross-org month totals — every org with logged work, vs the 10h package")
+    .option("--month <YYYY-MM>", "which month to report")
+    .option("--json", "raw JSON output")
+    .action((opts) => hoursCmd.summary(opts));
+
   // templates (read WhatsApp templates from Meta; create via /cli/meta-templates)
   const templates = program.command("templates")
     .alias("tpl")
@@ -441,11 +465,12 @@ export function run(argv) {
     .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("--rate <n>", "max messages per second — ONLY the pre-v0.6.0 per-row resume path; python paces fresh sends itself", "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("--skip-upsert", "pre-v0.6.0 resume only — ignored on fresh CSV sends (the upsert IS how per-row values reach python)")
+    .option("--limit <n>", "only process the first N valid rows (smoke-test under a THROWAWAY --campaign — a limited python fan-off still records the campaign as fired)")
+    .option("--resend", "re-fire a CSV campaign that already fanned out via python — resends to EVERY tagged contact, incl. those already reached (bc retry re-fires failures only)")
+    .option("--resume", "continue a pre-v0.6.0 per-row campaign from its status log (python campaigns have no per-row resume — use bc status / bc retry)")
     .option("--retry-failed", "with --resume: also re-attempt rows previously marked failed")
     .action((orgId, opts) => broadcastCmd.send(orgId, opts));
   broadcast.command("resume <organization_id>")