@signaliz/cli 1.0.84 → 1.0.86

package/README.md

@@ -1,6 +1,6 @@
 # @signaliz/cli
 
-The Signaliz CLI exposes the Signaliz core products, Signal Awareness,
+The Signaliz CLI exposes all five core products, Signal Awareness,
 Signaliz Flow, and delivered managed builds through one public contract:
 
 ```bash
@@ -197,3 +197,22 @@ signaliz mcp install
 Configuration is stored in `~/.signaliz/config.json` with file mode `0600`.
 `SIGNALIZ_API_KEY`, `SIGNALIZ_API_URL`, and `SIGNALIZ_BASE_URL` override the
 saved configuration.
+
+## Campaign OS agent harness
+
+Use the same commands from Codex, Claude Code, Cursor, Devin, Grok, or a shell
+automation. All context is bounded and all provider actions remain gated:
+
+```bash
+signaliz campaign-os clients --status active --json
+signaliz campaign-os context --client-id <uuid> --json
+signaliz campaign-os draft --client-id <uuid> --name "Launch intent" \
+  --lane realtime --agent codex --idempotency-key launch-draft-v1 --json
+signaliz campaign-os request --client-id <uuid> --campaign-id <uuid> \
+  --agent devin --action provider_activation --instructions "Prepare for review" --json
+signaliz campaign-os receipts --client-id <uuid> --json
+```
+
+`draft` creates only a locked Signaliz campaign object. `request` creates only
+an auditable review request. Neither command loads leads, activates a provider
+campaign, or sends email.

package/dist/bin.js

@@ -52,8 +52,15 @@ Product commands:
   signaliz flow --run-id run_...  Read a durable Flow checkpoint without dispatching new work
   signaliz builds list
   signaliz builds get --build-id BLD-...
-  signaliz builds run --build-id BLD-... [--input request.json] [--idempotency-key <key>]
+  signaliz builds quote --build-id BLD-... [--input request.json]
+  signaliz builds run --build-id BLD-... [--input request.json] --confirm-spend --max-credits <number> [--idempotency-key <key>]
   signaliz builds status --run-id <uuid> [--limit 100]
+  signaliz builds download --run-id <uuid> --out results.csv
+  signaliz campaign-os clients [--status active] [--query signaliz] [--limit 100]
+  signaliz campaign-os context --client-id <uuid> [--source-limit 50]
+  signaliz campaign-os draft --client-id <uuid> --name "Campaign" [--objective "..."] [--lane one_time|always_on|realtime] [--audience-binding-id <uuid>] [--agent codex]
+  signaliz campaign-os request --client-id <uuid> [--campaign-id <uuid>] --agent codex --action build_campaign --instructions "..." [--idempotency-key <key>]
+  signaliz campaign-os receipts [--client-id <uuid>] [--campaign-id <uuid>] [--limit 50]
 
 Access and connection:
   signaliz auth login
@@ -1986,18 +1993,44 @@ async function managedBuilds(args) {
     output(result, () => {
       process.stdout.write(`${result.build.build_id} \u2014 ${result.build.name}
 `);
-      process.stdout.write(`Fixed price: ${result.build.fixed_credits_per_run} Signaliz credits/run (${result.build.clay_credits_budget_per_run} Clay-credit budget)
+      process.stdout.write(`Base price: ${result.build.fixed_credits_per_run} Signaliz credits for ${result.build.included_records_per_run} included record(s)
+`);
+      process.stdout.write(`Additional records: ${result.build.additional_record_credits} Signaliz credits each \xB7 max ${result.build.max_records_per_run}
+`);
+      process.stdout.write(`Estimated Clay use: ${result.build.clay_credits_budget_per_run} base + ${result.build.additional_clay_credits_per_record} per additional record
 `);
       if (result.build.delivery_notes) process.stdout.write(`${result.build.delivery_notes}
 `);
     });
     return;
   }
+  if (action === "quote") {
+    const buildId = flag("build-id");
+    if (!buildId) throw new CliInputError("signaliz builds quote requires --build-id BLD-...");
+    const result = await client.quoteManagedBuildRun(buildId, readManagedBuildInput());
+    output(result, () => {
+      process.stdout.write(`${result.quote.item_count} record(s): ${result.quote.total_signaliz_credits} Signaliz credits
+`);
+      process.stdout.write(`Estimated Clay consumption: ${result.quote.estimated_clay_credits} credits
+`);
+      process.stdout.write("No run created and no credits charged.\n");
+    });
+    return;
+  }
   if (action === "run") {
     const buildId = flag("build-id");
     if (!buildId) throw new CliInputError("signaliz builds run requires --build-id BLD-...");
-    const result = await client.runManagedBuild(buildId, readManagedBuildInput(), flag("idempotency-key"));
+    const maxCredits = numberFlag("max-credits");
+    if (!hasFlag("confirm-spend") || maxCredits === void 0) {
+      throw new CliInputError("Live managed-build runs require --confirm-spend and --max-credits <number>. Use builds quote first.");
+    }
+    const result = await client.runManagedBuild(buildId, readManagedBuildInput(), {
+      idempotencyKey: flag("idempotency-key"),
+      confirmSpend: true,
+      maxCredits
+    });
     output(result, () => {
+      if (!result.run) throw new CliInputError(result.message || "Managed build was not queued.");
       process.stdout.write(`Managed build queued: ${result.run.run_id}
 `);
       process.stdout.write(`Charged: ${result.run.fixed_credits_charged} Signaliz credits (${result.run.billing_status})
@@ -2017,13 +2050,166 @@ async function managedBuilds(args) {
       process.stdout.write(`${result.run.build_id} run ${result.run.run_id}: ${result.run.status}
 `);
       process.stdout.write(`Results returned: ${result.returned || 0}
+`);
+      const csv = result.artifacts?.csv?.download_url;
+      if (csv) process.stdout.write(`CSV: ${csv}
 `);
       if (result.run.error) process.stdout.write(`Error: ${result.run.error}
 `);
     });
     return;
   }
-  throw new CliInputError("Usage: signaliz builds list|get|run|status");
+  if (action === "download") {
+    const runId = flag("run-id");
+    const out = flag("out");
+    if (!runId || !out) throw new CliInputError("signaliz builds download requires --run-id <uuid> --out results.csv");
+    const result = await client.getManagedBuildRun(runId, 1);
+    const url = result.artifacts?.csv?.download_url;
+    if (!url) throw new CliInputError("This run does not have a CSV artifact yet. Check builds status first.");
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`CSV download failed (HTTP ${response.status}).`);
+    (0, import_node_fs.writeFileSync)(out, Buffer.from(await response.arrayBuffer()));
+    output({ success: true, run_id: runId, path: out }, () => process.stdout.write(`Saved ${out}
+`));
+    return;
+  }
+  throw new CliInputError("Usage: signaliz builds list|get|quote|run|status|download");
+}
+var CAMPAIGN_OS_AGENTS = /* @__PURE__ */ new Set([
+  "codex",
+  "claude_code",
+  "cursor",
+  "devin",
+  "grok",
+  "other"
+]);
+var CAMPAIGN_OS_ACTIONS = /* @__PURE__ */ new Set([
+  "build_campaign",
+  "refresh_brain",
+  "sync_audience",
+  "prepare_realtime_policy",
+  "provider_load",
+  "provider_activation",
+  "provider_send"
+]);
+function campaignOsAgentFlag() {
+  const value = flag("agent")?.trim().toLowerCase().replace(/[\s-]+/g, "_");
+  if (!value) return void 0;
+  if (!CAMPAIGN_OS_AGENTS.has(value)) {
+    throw new CliInputError("--agent must be codex, claude_code, cursor, devin, grok, or other");
+  }
+  return value;
+}
+async function campaignOs(args) {
+  const action = args[0];
+  const client = createClient();
+  if (action === "clients") {
+    const limit = numberFlag("limit") ?? 100;
+    requireIntegerInRange(limit, "--limit", 1, 200);
+    const status = flag("status");
+    if (status && !["onboarding", "active", "paused", "archived"].includes(status)) {
+      throw new CliInputError("--status must be onboarding, active, paused, or archived");
+    }
+    const result = await client.listCampaignOsClients({ query: flag("query"), status, limit });
+    output(result, () => {
+      process.stdout.write(`Campaign OS clients: ${result.total_returned}
+`);
+      for (const item of result.clients) {
+        process.stdout.write(`- ${item.name} (${item.status}) \xB7 Brain v${item.brain_version} \xB7 ${item.counts.sources} sources \xB7 ${item.counts.audiences} audiences \xB7 ${item.counts.campaigns} campaigns
+`);
+      }
+    });
+    return;
+  }
+  if (action === "context") {
+    const clientId = flag("client-id");
+    if (!clientId) throw new CliInputError("signaliz campaign-os context requires --client-id <uuid>");
+    const sourceLimit = numberFlag("source-limit") ?? 50;
+    requireIntegerInRange(sourceLimit, "--source-limit", 1, 100);
+    const result = await client.getCampaignOsClientContext(clientId, sourceLimit);
+    output(result, () => {
+      const selected = result.client;
+      process.stdout.write(`${String(selected.name || clientId)} \xB7 Brain v${String(selected.brain_version || "?")}
+`);
+      process.stdout.write(`${result.brain_sources.length} bounded sources \xB7 ${result.audiences.length} audiences \xB7 ${result.campaigns.length} campaigns \xB7 ${result.realtime_policies.length} realtime policies
+`);
+      process.stdout.write("Raw source bodies and provider secrets were not returned.\n");
+    });
+    return;
+  }
+  if (action === "draft") {
+    const clientId = flag("client-id");
+    const name = flag("name");
+    if (!clientId || !name) throw new CliInputError('signaliz campaign-os draft requires --client-id <uuid> --name "Campaign"');
+    const lane = flag("lane") || "one_time";
+    if (!["one_time", "always_on", "realtime"].includes(lane)) {
+      throw new CliInputError("--lane must be one_time, always_on, or realtime");
+    }
+    const targetCount = numberFlag("target-count");
+    requireIntegerInRange(targetCount, "--target-count", 0, 1e7);
+    const result = await client.createCampaignOsDraft({
+      clientId,
+      name,
+      objective: flag("objective"),
+      lane,
+      targetCount,
+      audienceBindingId: flag("audience-binding-id"),
+      agentVendor: campaignOsAgentFlag(),
+      idempotencyKey: flag("idempotency-key")
+    });
+    output(result, () => {
+      const campaign = record(result.campaign);
+      process.stdout.write(`Review-held draft created: ${String(campaign.name || name)} (${String(campaign.id || "")})
+`);
+      process.stdout.write("Provider load: locked \xB7 activation: locked \xB7 send: locked\n");
+      process.stdout.write("No Clay or Instantly mutation was performed.\n");
+    });
+    return;
+  }
+  if (action === "request") {
+    const clientId = flag("client-id");
+    const actionType = flag("action");
+    const instructions = flag("instructions");
+    if (!clientId || !actionType || !instructions) {
+      throw new CliInputError('signaliz campaign-os request requires --client-id <uuid> --action <type> --instructions "..."');
+    }
+    if (!CAMPAIGN_OS_ACTIONS.has(actionType)) {
+      throw new CliInputError(`--action must be one of: ${Array.from(CAMPAIGN_OS_ACTIONS).join(", ")}`);
+    }
+    const result = await client.submitCampaignOsActionRequest({
+      clientId,
+      campaignId: flag("campaign-id"),
+      agentVendor: campaignOsAgentFlag(),
+      actionType,
+      instructions,
+      idempotencyKey: flag("idempotency-key")
+    });
+    output(result, () => {
+      const request = record(result.request);
+      process.stdout.write(`Action request recorded: ${String(request.id || "")} \xB7 ${String(request.status || "review_required")}
+`);
+      process.stdout.write("Execution did not start. Provider mutations require a separate Signaliz admin approval.\n");
+    });
+    return;
+  }
+  if (action === "receipts") {
+    const limit = numberFlag("limit") ?? 50;
+    requireIntegerInRange(limit, "--limit", 1, 200);
+    const result = await client.listCampaignOsReceipts({
+      clientId: flag("client-id"),
+      campaignId: flag("campaign-id"),
+      limit
+    });
+    output(result, () => {
+      const requests = Array.isArray(result.action_requests) ? result.action_requests : [];
+      const deliveries = Array.isArray(result.delivery_receipts) ? result.delivery_receipts : [];
+      process.stdout.write(`${requests.length} agent request receipt(s) \xB7 ${deliveries.length} provider delivery receipt(s)
+`);
+      process.stdout.write("Provider accepted and mailbox sent remain distinct states.\n");
+    });
+    return;
+  }
+  throw new CliInputError("Usage: signaliz campaign-os clients|context|draft|request|receipts");
 }
 async function main() {
   const [, , command, ...args] = process.argv;
@@ -2050,6 +2236,8 @@ async function main() {
       return flow();
     case "builds":
       return managedBuilds(args);
+    case "campaign-os":
+      return campaignOs(args);
     case "signal-to-copy":
       return signalToCopy();
     case "health":

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signaliz/cli",
-  "version": "1.0.84",
-  "description": "Signaliz CLI for core products, Signal Awareness, Signaliz Flow, and reusable managed builds.",
+  "version": "1.0.86",
+  "description": "Signaliz CLI for Campaign OS, core products, Signal Awareness, Signaliz Flow, and reusable managed builds.",
   "bin": {
     "signaliz": "dist/bin.js"
   },
@@ -21,6 +21,7 @@
     "company-signals",
     "signal-to-copy",
     "signals-first",
+    "campaign-os",
     "signal-awareness",
     "signaliz-flow"
   ],
@@ -29,7 +30,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@signaliz/sdk": "^1.0.88"
+    "@signaliz/sdk": "^1.0.90"
   },
   "devDependencies": {
     "tsup": "^8.0.0",