@signaliz/cli 1.0.92 → 1.0.94

package/README.md

@@ -223,6 +223,13 @@ signaliz campaign-os audience-preview --client-id <uuid> \
   --audience-id <uuid> --idempotency-key launch-preview-v1 --json
 signaliz campaign-os compile --client-id <uuid> --campaign-id <uuid> \
   --providers all --json
+signaliz campaign-os alpha-materialize-preflight --client-id <uuid> \
+  --campaign-id <uuid> --audience-run-id <uuid> --validation-run-id <uuid> \
+  --idempotency-key launch-alpha-materialization-v1 --json
+signaliz campaign-os alpha-materialize --materialization-run-id <uuid> \
+  --approval-hash sha256:<64-hex> --confirm-spend --json
+signaliz campaign-os alpha-materialization-status \
+  --materialization-run-id <uuid> --json
 signaliz campaign-os request --client-id <uuid> --campaign-id <uuid> \
   --agent devin --action provider_activation --instructions "Prepare for review" \
   --preflight-inputs-file action-preflight.json \
@@ -245,3 +252,9 @@ activation, real-time arming, queueing, or sending; it does not execute them.
 non-secret provider and artifact identifiers. After a Signaliz superadmin
 approves that proposal, `prepare-preflight` appends or reads the immutable
 no-call continuation and reports missing inputs or unavailable adapters.
+
+`alpha-materialize-preflight` records the exact campaign, Audience run,
+validation receipt, coverage target, batches, and research ceiling without
+spend. `alpha-materialize` requires the returned approval hash and
+`--confirm-spend`; it authorizes only that bounded research. It never calls
+Clay, creates an Audience, loads or activates a provider, queues, or sends.

package/dist/bin.js

@@ -57,12 +57,12 @@ Product commands:
   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 knowledge --query "cache first" [--client-id <uuid>] [--record-kind campaign_playbook] [--limit 15]
+  signaliz campaign-os context --client-id <uuid> [--knowledge-snapshot-id <uuid>] [--source-limit 50]
+  signaliz campaign-os knowledge --query "cache first" [--client-id <uuid>] [--knowledge-snapshot-id <uuid>] [--record-kind campaign_playbook] [--limit 15]
   signaliz campaign-os provider-runtime --client-id <uuid> --provider clay|instantly|smartlead|bison
   signaliz campaign-os build --client-id <uuid> --name "Campaign" --objective "Goal" --target-count 500 --idempotency-key <key>
   signaliz campaign-os build-status --build-run-id <uuid>
-  signaliz campaign-os draft --client-id <uuid> --name "Campaign" --campaign-spec-file campaign-spec.json --idempotency-key <key> [--agent codex]
+  signaliz campaign-os draft --client-id <uuid> --name "Campaign" --campaign-spec-file campaign-spec.json --idempotency-key <key> [--knowledge-snapshot-id <uuid>] [--agent codex]
   signaliz campaign-os refine --client-id <uuid> --campaign-id <uuid> --expected-spec-version-id <uuid> --campaign-spec-file campaign-spec.json --change-reason "What changed" --idempotency-key <key> [--agent codex]
   signaliz campaign-os audience-draft --client-id <uuid> --name "Audience" --definition-file audience.json --entity-type people --audience-role campaign_segment --source-mode signaliz_owned --idempotency-key <key>
   signaliz campaign-os materialize-cache-audience --client-id <uuid> --audience-id <uuid> [--campaign-id <uuid>] --target-count <1-500> --idempotency-key <key>
@@ -70,11 +70,14 @@ Product commands:
   signaliz campaign-os audience-preview --client-id <uuid> --audience-id <uuid> --idempotency-key <key>
   signaliz campaign-os compile --client-id <uuid> --campaign-id <uuid> [--providers all]
   signaliz campaign-os alpha-plan --client-id <uuid> --client-name "Velox" --offer-summary "..." --icp-summary "..." --idempotency-key <key>
-  signaliz campaign-os alpha-discover --client-id <uuid> --client-name "Velox" --offer-summary "..." --icp-summary "..." --idempotency-key <key> --confirm-spend
+  signaliz campaign-os alpha-discover --client-id <uuid> --campaign-id <uuid> --client-name "Velox" --offer-summary "..." --icp-summary "..." --idempotency-key <key> --confirm-spend
   signaliz campaign-os alpha-status --alpha-run-id <uuid>
   signaliz campaign-os alpha-validate --client-id <uuid> --campaign-id <uuid> --alpha-run-id <uuid> --candidate-index 0 --sample-file sample.json --idempotency-key <key> --confirm-spend
   signaliz campaign-os alpha-validation-status --validation-run-id <uuid>
   signaliz campaign-os alpha-apply --validation-run-id <uuid>
+  signaliz campaign-os alpha-materialize-preflight --client-id <uuid> --campaign-id <uuid> --audience-run-id <uuid> --validation-run-id <uuid> --idempotency-key <key>
+  signaliz campaign-os alpha-materialize --materialization-run-id <uuid> --approval-hash sha256:<64-hex> --confirm-spend
+  signaliz campaign-os alpha-materialization-status --materialization-run-id <uuid>
   signaliz campaign-os connections --client-id <uuid>
   signaliz campaign-os source-binding --client-id <uuid> --binding-id <uuid> --name "CRM list" --source-kind audience --selector-file selector.json --idempotency-key <key>
   signaliz campaign-os source-preflight --client-id <uuid> --source-binding-id <uuid> --idempotency-key <key> [--max-records 25]
@@ -2145,7 +2148,11 @@ async function campaignOs(args) {
     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);
+    const result = await client.getCampaignOsClientContext(
+      clientId,
+      sourceLimit,
+      flag("knowledge-snapshot-id")
+    );
     output(result, () => {
       const selected = result.client;
       process.stdout.write(`${String(selected.name || clientId)} \xB7 Brain v${String(selected.brain_version || "?")}
@@ -2163,15 +2170,7 @@ async function campaignOs(args) {
     }
     const limit = numberFlag("limit") ?? 15;
     requireIntegerInRange(limit, "--limit", 1, 50);
-    const allowedKinds = [
-      "client_brain",
-      "campaign_register",
-      "campaign_learning",
-      "campaign_methodology",
-      "campaign_genome",
-      "campaign_playbook",
-      "knowledge_inventory"
-    ];
+    const allowedKinds = import_sdk.CAMPAIGN_OS_KNOWLEDGE_RECORD_KINDS;
     const recordKind = flag("record-kind");
     if (recordKind && !allowedKinds.includes(recordKind)) {
       throw new CliInputError(`--record-kind must be one of: ${allowedKinds.join(", ")}`);
@@ -2179,6 +2178,7 @@ async function campaignOs(args) {
     const result = await client.searchCampaignOsKnowledge({
       query,
       clientId: flag("client-id"),
+      knowledgeSnapshotId: flag("knowledge-snapshot-id"),
       recordKind,
       limit
     });
@@ -2291,6 +2291,7 @@ async function campaignOs(args) {
       targetCount,
       audienceBindingId: flag("audience-binding-id"),
       audienceDefinitionId: flag("audience-definition-id"),
+      knowledgeSnapshotId: flag("knowledge-snapshot-id"),
       campaignSpec,
       agentVendor: campaignOsAgentFlag(),
       idempotencyKey
@@ -2467,6 +2468,7 @@ async function campaignOs(args) {
   }
   if (action === "alpha-plan" || action === "alpha-discover") {
     const clientId = flag("client-id");
+    const campaignId = flag("campaign-id");
     const clientName = flag("client-name");
     const offerSummary = flag("offer-summary");
     const icpSummary = flag("icp-summary");
@@ -2476,7 +2478,7 @@ async function campaignOs(args) {
     }
     const params = {
       clientId,
-      campaignId: flag("campaign-id"),
+      campaignId,
       clientName,
       offerSummary,
       icpSummary,
@@ -2496,7 +2498,13 @@ async function campaignOs(args) {
     if (!hasFlag("confirm-spend")) {
       throw new CliInputError("signaliz campaign-os alpha-discover requires --confirm-spend for the $0.10 authorization ceiling");
     }
-    const result = await client.startCampaignOsAlphaDiscovery(params);
+    if (!campaignId) {
+      throw new CliInputError("signaliz campaign-os alpha-discover requires --campaign-id for one saved immutable CampaignSpec");
+    }
+    const result = await client.startCampaignOsAlphaDiscovery({
+      ...params,
+      campaignId
+    });
     output(result, () => {
       const run = record(result.run);
       process.stdout.write(`Signaliz Alpha discovery started: ${String(run.id || "")} \xB7 ${String(run.status || "queued")} \xB7 authorized ceiling $0.10
@@ -2580,6 +2588,70 @@ async function campaignOs(args) {
     });
     return;
   }
+  if (action === "alpha-materialize-preflight") {
+    const clientId = flag("client-id");
+    const campaignId = flag("campaign-id");
+    const audienceRunId = flag("audience-run-id");
+    const validationRunId = flag("validation-run-id");
+    const idempotencyKey = flag("idempotency-key")?.trim();
+    if (!clientId || !campaignId || !audienceRunId || !validationRunId || !idempotencyKey) {
+      throw new CliInputError("signaliz campaign-os alpha-materialize-preflight requires --client-id, --campaign-id, --audience-run-id, --validation-run-id, and --idempotency-key");
+    }
+    const result = await client.preflightCampaignOsAlphaMaterialization({
+      clientId,
+      campaignId,
+      audienceRunId,
+      validationRunId,
+      idempotencyKey
+    });
+    output(result, () => {
+      const run = record(result.run);
+      process.stdout.write(`Signaliz Alpha materialization preflight: ${String(run.id || "")} \xB7 ${String(run.selected_count || 0)} membership(s) \xB7 ${String(run.batch_count || 0)} batch(es)
+`);
+      process.stdout.write(`Research ceiling: $${String(run.max_cost_usd || "0.00")} \xB7 no research, Clay, audience creation, provider load, activation, queue, or send occurred.
+`);
+    });
+    return;
+  }
+  if (action === "alpha-materialize") {
+    const materializationRunId = flag("materialization-run-id");
+    const approvalHash = flag("approval-hash");
+    if (!materializationRunId || !approvalHash) {
+      throw new CliInputError("signaliz campaign-os alpha-materialize requires --materialization-run-id and --approval-hash");
+    }
+    if (!/^sha256:[0-9a-f]{64}$/.test(approvalHash)) {
+      throw new CliInputError("--approval-hash must be the exact sha256:<64-hex> preflight hash");
+    }
+    if (!hasFlag("confirm-spend")) {
+      throw new CliInputError("signaliz campaign-os alpha-materialize requires --confirm-spend for the approval-bound research ceiling");
+    }
+    const result = await client.startCampaignOsAlphaMaterialization({
+      materializationRunId,
+      approvalHash,
+      confirmSpend: true
+    });
+    output(result, () => {
+      const run = record(result.run);
+      process.stdout.write(`Signaliz Alpha materialization started: ${String(run.id || materializationRunId)} \xB7 ${String(run.status || "queued")}
+`);
+      process.stdout.write("Only preflight-bounded research spend is authorized. Clay, audience creation, provider load, activation, queue, and send remain locked.\n");
+    });
+    return;
+  }
+  if (action === "alpha-materialization-status") {
+    const materializationRunId = flag("materialization-run-id");
+    if (!materializationRunId) {
+      throw new CliInputError("signaliz campaign-os alpha-materialization-status requires --materialization-run-id <uuid>");
+    }
+    const result = await client.getCampaignOsAlphaMaterialization(materializationRunId);
+    output(result, () => {
+      const run = record(result.run);
+      process.stdout.write(`Signaliz Alpha materialization: ${String(run.status || "unknown")} \xB7 ${String(run.processed_entity_count || 0)}/${String(run.entity_count || 0)} entities \xB7 ${String(run.covered_membership_count || 0)}/${String(run.selected_count || 0)} memberships
+`);
+      process.stdout.write("Status read only \xB7 no new research, spend, Clay, provider load, activation, queue, or send.\n");
+    });
+    return;
+  }
   if (action === "connections") {
     const clientId = flag("client-id");
     if (!clientId) throw new CliInputError("signaliz campaign-os connections requires --client-id <uuid>");
@@ -2750,7 +2822,7 @@ async function campaignOs(args) {
     });
     return;
   }
-  throw new CliInputError("Usage: signaliz campaign-os clients|context|knowledge|provider-runtime|build|build-status|draft|refine|audience-draft|materialize-cache-audience|audience-schedule|audience-preview|compile|alpha-plan|alpha-discover|alpha-status|alpha-validate|alpha-validation-status|alpha-apply|connections|source-binding|source-preflight|request|prepare-preflight|receipts");
+  throw new CliInputError("Usage: signaliz campaign-os clients|context|knowledge|provider-runtime|build|build-status|draft|refine|audience-draft|materialize-cache-audience|audience-schedule|audience-preview|compile|alpha-plan|alpha-discover|alpha-status|alpha-validate|alpha-validation-status|alpha-apply|alpha-materialize-preflight|alpha-materialize|alpha-materialization-status|connections|source-binding|source-preflight|request|prepare-preflight|receipts");
 }
 async function main() {
   const [, , command, ...args] = process.argv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaliz/cli",
-  "version": "1.0.92",
+  "version": "1.0.94",
   "description": "Signaliz CLI for Campaign OS, core products, Signal Awareness, Signaliz Flow, and reusable managed builds.",
   "bin": {
     "signaliz": "dist/bin.js"
@@ -30,7 +30,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@signaliz/sdk": "^1.0.96"
+    "@signaliz/sdk": "^1.0.98"
   },
   "devDependencies": {
     "tsup": "^8.0.0",