@signaliz/cli 1.0.90 → 1.0.92

package/README.md

@@ -217,14 +217,18 @@ signaliz campaign-os audience-draft --client-id <uuid> --name "Launch ICP" \
   --audience-role campaign_segment --source-mode signaliz_owned \
   --idempotency-key launch-audience-v1 --json
 signaliz campaign-os materialize-cache-audience --client-id <uuid> \
-  --audience-id <uuid> --target-count 500 \
+  --audience-id <uuid> --campaign-id <uuid> --target-count 500 \
   --idempotency-key launch-cache-materialization-v1 --json
 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 request --client-id <uuid> --campaign-id <uuid> \
-  --agent devin --action provider_activation --instructions "Prepare for review" --json
+  --agent devin --action provider_activation --instructions "Prepare for review" \
+  --preflight-inputs-file action-preflight.json \
+  --idempotency-key launch-activation-request-v1 --json
+signaliz campaign-os prepare-preflight --client-id <uuid> \
+  --request-id <approved-request-uuid> --json
 signaliz campaign-os receipts --client-id <uuid> --json
 ```
 
@@ -233,6 +237,11 @@ approval boundaries, and receipt semantics without returning credentials or
 calling the provider. `build`, `audience-draft`, `materialize-cache-audience`,
 `audience-preview`, and `compile` do not need CMM-admin approval and keep
 providers locked. Cache materialization is capped at 500 members and returns
-exact zero-provider/Clay usage plus a terminal reconciliation receipt. `request`
-creates only an auditable review request for paid sourcing, provider load,
+exact zero-provider/Clay usage plus a terminal reconciliation receipt; optional
+`--campaign-id` links that run to its campaign lifecycle. `request` requires a
+nonblank `--idempotency-key` and creates only an auditable review request for paid sourcing, provider load,
 activation, real-time arming, queueing, or sending; it does not execute them.
+`--preflight-inputs-file` accepts one JSON object containing only exact,
+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.

package/dist/bin.js

@@ -63,11 +63,23 @@ Product commands:
   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 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> --target-count <1-500> --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>
+  signaliz campaign-os audience-schedule --client-id <uuid> --audience-id <uuid> [--campaign-id <uuid>] [--cadence-minutes 1440] [--per-run-cap 100] [--source-policy cache_only|cache_then_review] [--enabled yes|no] [--run-now]
   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 request --client-id <uuid> [--campaign-id <uuid>] --agent codex --action provider_load --instructions "..." [--idempotency-key <key>]
+  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-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 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]
+  signaliz campaign-os request --client-id <uuid> [--campaign-id <uuid>] --agent codex --action provider_load --instructions "..." [--preflight-inputs-file inputs.json] --idempotency-key <key>
+  signaliz campaign-os prepare-preflight --client-id <uuid> --request-id <uuid>
   signaliz campaign-os receipts [--client-id <uuid>] [--campaign-id <uuid>] [--limit 50]
 
 Access and connection:
@@ -2292,6 +2304,44 @@ async function campaignOs(args) {
     });
     return;
   }
+  if (action === "refine") {
+    const clientId = flag("client-id");
+    const campaignId = flag("campaign-id");
+    const expectedCampaignSpecVersionId = flag("expected-spec-version-id");
+    const campaignSpecFile = flag("campaign-spec-file");
+    const changeReason = flag("change-reason");
+    const idempotencyKey = flag("idempotency-key");
+    if (!clientId || !campaignId || !expectedCampaignSpecVersionId || !campaignSpecFile || !changeReason || !idempotencyKey) {
+      throw new CliInputError("signaliz campaign-os refine requires --client-id, --campaign-id, --expected-spec-version-id, --campaign-spec-file, --change-reason, and --idempotency-key");
+    }
+    let campaignSpec;
+    try {
+      const parsed = JSON.parse((0, import_node_fs.readFileSync)(campaignSpecFile, "utf8"));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("file must contain one JSON object");
+      }
+      campaignSpec = parsed;
+    } catch (error) {
+      throw new CliInputError(`Unable to read --campaign-spec-file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = await client.refineCampaignOsCampaign({
+      clientId,
+      campaignId,
+      expectedCampaignSpecVersionId,
+      knowledgeSnapshotId: flag("knowledge-snapshot-id"),
+      campaignSpec,
+      changeReason,
+      agentVendor: campaignOsAgentFlag(),
+      idempotencyKey
+    });
+    output(result, () => {
+      const campaign = record(result.campaign);
+      process.stdout.write(`CampaignSpec v${String(campaign.campaign_spec_version || "")} appended to ${String(campaign.name || campaignId)}.
+`);
+      process.stdout.write("Prior provider approvals were invalidated. Provider load, activation, and send remain locked.\n");
+    });
+    return;
+  }
   if (action === "audience-draft") {
     const clientId = flag("client-id");
     const name = flag("name");
@@ -2344,6 +2394,7 @@ async function campaignOs(args) {
   if (action === "materialize-cache-audience") {
     const clientId = flag("client-id");
     const audienceId = flag("audience-id");
+    const campaignId = flag("campaign-id");
     const targetCount = numberFlag("target-count");
     const idempotencyKey = flag("idempotency-key");
     if (!clientId || !audienceId || targetCount === void 0 || !idempotencyKey) {
@@ -2353,6 +2404,7 @@ async function campaignOs(args) {
     const result = await client.materializeCampaignOsCacheAudience({
       clientId,
       audienceId,
+      campaignId,
       targetCount,
       idempotencyKey
     });
@@ -2369,6 +2421,40 @@ async function campaignOs(args) {
     });
     return;
   }
+  if (action === "audience-schedule") {
+    const clientId = flag("client-id");
+    const audienceId = flag("audience-id");
+    if (!clientId || !audienceId) {
+      throw new CliInputError("signaliz campaign-os audience-schedule requires --client-id and --audience-id");
+    }
+    const cadenceMinutes = numberFlag("cadence-minutes") ?? 1440;
+    const perRunCap = numberFlag("per-run-cap") ?? 100;
+    requireIntegerInRange(cadenceMinutes, "--cadence-minutes", 15, 10080);
+    requireIntegerInRange(perRunCap, "--per-run-cap", 1, 500);
+    const sourcePolicy = flag("source-policy") || "cache_only";
+    if (!["cache_only", "cache_then_review"].includes(sourcePolicy)) {
+      throw new CliInputError("--source-policy must be cache_only or cache_then_review");
+    }
+    const result = await client.upsertCampaignOsAudienceSchedule({
+      clientId,
+      audienceId,
+      campaignId: flag("campaign-id"),
+      enabled: yesNoFlag("enabled") ?? true,
+      sourcePolicy,
+      cadenceMinutes,
+      perRunCap,
+      timezone: flag("timezone") || "UTC",
+      startAt: flag("start-at"),
+      runNow: hasFlag("run-now")
+    });
+    output(result, () => {
+      const schedule = record(result.schedule);
+      process.stdout.write(`Audience schedule: ${String(schedule.status || "unknown")} \xB7 next ${String(schedule.next_run_at || "not scheduled")}
+`);
+      process.stdout.write("Cache deltas need no CMM-admin approval. Standing Clay approval: false.\n");
+    });
+    return;
+  }
   if (action === "compile") {
     const clientId = flag("client-id");
     const campaignId = flag("campaign-id");
@@ -2379,23 +2465,247 @@ async function campaignOs(args) {
     output(result, () => process.stdout.write("Compile preview recorded \xB7 provider calls 0 \xB7 no campaign created or sent\n"));
     return;
   }
+  if (action === "alpha-plan" || action === "alpha-discover") {
+    const clientId = flag("client-id");
+    const clientName = flag("client-name");
+    const offerSummary = flag("offer-summary");
+    const icpSummary = flag("icp-summary");
+    const idempotencyKey = flag("idempotency-key")?.trim();
+    if (!clientId || !clientName || !offerSummary || !icpSummary || !idempotencyKey) {
+      throw new CliInputError(`signaliz campaign-os ${action} requires --client-id, --client-name, --offer-summary, --icp-summary, and --idempotency-key`);
+    }
+    const params = {
+      clientId,
+      campaignId: flag("campaign-id"),
+      clientName,
+      offerSummary,
+      icpSummary,
+      buyerPersonas: csvFlag("buyer-personas"),
+      knownEvidence: csvFlag("known-evidence"),
+      preferredSources: csvFlag("preferred-sources"),
+      idempotencyKey
+    };
+    if (action === "alpha-plan") {
+      const result2 = await client.planCampaignOsAlpha(params);
+      output(result2, () => {
+        process.stdout.write("Signaliz Alpha plan ready \xB7 model calls 0 \xB7 web searches 0 \xB7 spend $0.00\n");
+        process.stdout.write("Candidates will remain unvalidated until a measured sample proves them.\n");
+      });
+      return;
+    }
+    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);
+    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
+`);
+      process.stdout.write("Output is candidate-only. Clay, audience creation, provider load, activation, queue, and send remain locked.\n");
+    });
+    return;
+  }
+  if (action === "alpha-status") {
+    const alphaRunId = flag("alpha-run-id");
+    if (!alphaRunId) {
+      throw new CliInputError("signaliz campaign-os alpha-status requires --alpha-run-id <uuid>");
+    }
+    const result = await client.getCampaignOsAlphaRun(alphaRunId);
+    output(result, () => {
+      const run = record(result.run);
+      process.stdout.write(`Signaliz Alpha run: ${String(run.status || "unknown")} \xB7 ${String(run.id || alphaRunId)}
+`);
+      process.stdout.write("Completed output remains a source-cited candidate until a measured validation receipt exists.\n");
+    });
+    return;
+  }
+  if (action === "alpha-validate") {
+    const clientId = flag("client-id");
+    const campaignId = flag("campaign-id");
+    const alphaRunId = flag("alpha-run-id");
+    const candidateIndex = numberFlag("candidate-index");
+    const sampleFile = flag("sample-file");
+    const idempotencyKey = flag("idempotency-key")?.trim();
+    if (!clientId || !campaignId || !alphaRunId || candidateIndex === void 0 || !sampleFile || !idempotencyKey) {
+      throw new CliInputError("signaliz campaign-os alpha-validate requires --client-id, --campaign-id, --alpha-run-id, --candidate-index, --sample-file, and --idempotency-key");
+    }
+    requireIntegerInRange(candidateIndex, "--candidate-index", 0, 4);
+    if (!hasFlag("confirm-spend")) {
+      throw new CliInputError("signaliz campaign-os alpha-validate requires --confirm-spend for the fixed $0.25 maximum");
+    }
+    let sampleEntities;
+    try {
+      const parsed = JSON.parse((0, import_node_fs.readFileSync)(sampleFile, "utf8"));
+      if (!Array.isArray(parsed) || parsed.length < 3 || parsed.length > 20) {
+        throw new Error("file must contain a JSON array of 3-20 sample entities");
+      }
+      sampleEntities = parsed;
+    } catch (error) {
+      throw new CliInputError(`Unable to read --sample-file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = await client.startCampaignOsAlphaValidation({
+      clientId,
+      campaignId,
+      alphaRunId,
+      candidateIndex,
+      sampleEntities,
+      idempotencyKey
+    });
+    output(result, () => {
+      const run = record(result.run);
+      process.stdout.write(`Signaliz Alpha validation started: ${String(run.id || "")} \xB7 ${String(run.status || "queued")} \xB7 maximum $0.25
+`);
+      process.stdout.write("Passing status is receipt-derived. Clay and delivery providers remain locked.\n");
+    });
+    return;
+  }
+  if (action === "alpha-validation-status" || action === "alpha-apply") {
+    const validationRunId = flag("validation-run-id");
+    if (!validationRunId) {
+      throw new CliInputError(`signaliz campaign-os ${action} requires --validation-run-id <uuid>`);
+    }
+    const result = action === "alpha-apply" ? await client.applyCampaignOsValidatedAlpha(validationRunId) : await client.getCampaignOsAlphaValidationRun(validationRunId);
+    output(result, () => {
+      const run = record(result.run);
+      if (action === "alpha-apply") {
+        process.stdout.write(`Validated Alpha applied to immutable CampaignSpec: ${String(run.applied_spec_version_id || "complete")}
+`);
+        process.stdout.write("Provider load, activation, queue, and send remain locked.\n");
+      } else {
+        process.stdout.write(`Signaliz Alpha validation: ${String(run.status || "unknown")} \xB7 ${String(run.matched_count || 0)}/${String(run.sample_size || 0)} matched
+`);
+        process.stdout.write(`Validation passed: ${run.validation_passed === true ? "yes" : "no"}
+`);
+      }
+    });
+    return;
+  }
+  if (action === "connections") {
+    const clientId = flag("client-id");
+    if (!clientId) throw new CliInputError("signaliz campaign-os connections requires --client-id <uuid>");
+    const result = await client.listCampaignOsConnections(clientId);
+    output(result, () => {
+      process.stdout.write(`${result.bindings.length} client binding(s) \xB7 ${result.source_bindings.length} exact source binding(s)
+`);
+      process.stdout.write("OAuth tokens and raw provider values were not returned; no provider call occurred.\n");
+    });
+    return;
+  }
+  if (action === "source-binding" || action === "source-policy") {
+    const clientId = flag("client-id");
+    const bindingId = flag("binding-id");
+    const name = flag("name");
+    const sourceKind = flag("source-kind");
+    const selectorFile = flag("selector-file");
+    const idempotencyKey = flag("idempotency-key")?.trim();
+    if (!clientId || !bindingId || !name || !sourceKind || !selectorFile || !idempotencyKey) {
+      throw new CliInputError("signaliz campaign-os source-binding requires --client-id, --binding-id, --name, --source-kind, --selector-file, and --idempotency-key");
+    }
+    if (!["memory", "data", "audience", "trigger"].includes(sourceKind)) {
+      throw new CliInputError("--source-kind must be memory, data, audience, or trigger");
+    }
+    let selector;
+    try {
+      const parsed = JSON.parse((0, import_node_fs.readFileSync)(selectorFile, "utf8"));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("file must contain one JSON object");
+      selector = parsed;
+    } catch (error) {
+      throw new CliInputError(`Unable to read --selector-file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = await client.createCampaignOsSourceBinding({
+      clientId,
+      bindingId,
+      name,
+      sourceKind,
+      remoteObjectType: flag("remote-object-type"),
+      remoteRef: flag("remote-ref"),
+      selector,
+      audienceId: flag("audience-id"),
+      idempotencyKey
+    });
+    output(result, () => {
+      const sourceBinding = record(result.source_binding);
+      process.stdout.write(`Draft source binding: ${String(sourceBinding.name || name)} (${String(sourceBinding.id || "")})
+`);
+      process.stdout.write("Provider calls: 0 \xB7 hydration: locked \xB7 realtime armed: false \xB7 send authorized: false\n");
+    });
+    return;
+  }
+  if (action === "source-preflight") {
+    const clientId = flag("client-id");
+    const sourceBindingId = flag("source-binding-id") || flag("source-policy-id");
+    const idempotencyKey = flag("idempotency-key")?.trim();
+    const maxRecords = numberFlag("max-records") ?? 25;
+    if (!clientId || !sourceBindingId || !idempotencyKey) {
+      throw new CliInputError("signaliz campaign-os source-preflight requires --client-id, --source-binding-id, and --idempotency-key");
+    }
+    requireIntegerInRange(maxRecords, "--max-records", 1, 25);
+    const result = await client.preflightCampaignOsSourceBinding(clientId, sourceBindingId, idempotencyKey, maxRecords);
+    output(result, () => {
+      process.stdout.write("Source binding preflight recorded \xB7 provider calls 0 \xB7 source approval unchanged\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 "..."');
+    const idempotencyKey = flag("idempotency-key")?.trim();
+    if (!clientId || !actionType || !instructions || !idempotencyKey) {
+      throw new CliInputError('signaliz campaign-os request requires --client-id <uuid> --action <type> --instructions "..." --idempotency-key <key>');
     }
     if (!CAMPAIGN_OS_ACTIONS.has(actionType)) {
       throw new CliInputError(`--action must be one of: ${Array.from(CAMPAIGN_OS_ACTIONS).join(", ")}`);
     }
+    let preflightInputs;
+    const preflightInputsFile = flag("preflight-inputs-file");
+    if (preflightInputsFile) {
+      try {
+        const parsed = JSON.parse((0, import_node_fs.readFileSync)(preflightInputsFile, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+          throw new Error("expected one JSON object");
+        }
+        const input = parsed;
+        const allowed = /* @__PURE__ */ new Set([
+          "provider",
+          "provider_connection_id",
+          "audience_id",
+          "audience_run_id",
+          "provider_artifact_id",
+          "policy_id",
+          "delivery_id",
+          "provider_campaign_id",
+          "target_count",
+          "verification_max_age_days"
+        ]);
+        const unsupported = Object.keys(input).filter((key) => !allowed.has(key));
+        if (unsupported.length) {
+          throw new Error(`unsupported fields: ${unsupported.join(", ")}`);
+        }
+        preflightInputs = {
+          provider: input.provider,
+          providerConnectionId: input.provider_connection_id,
+          audienceId: input.audience_id,
+          audienceRunId: input.audience_run_id,
+          providerArtifactId: input.provider_artifact_id,
+          policyId: input.policy_id,
+          deliveryId: input.delivery_id,
+          providerCampaignId: input.provider_campaign_id,
+          targetCount: input.target_count,
+          verificationMaxAgeDays: input.verification_max_age_days
+        };
+      } catch (error) {
+        throw new CliInputError(`Unable to read --preflight-inputs-file: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
     const result = await client.submitCampaignOsActionRequest({
       clientId,
       campaignId: flag("campaign-id"),
       agentVendor: campaignOsAgentFlag(),
       actionType,
       instructions,
-      idempotencyKey: flag("idempotency-key")
+      preflightInputs,
+      idempotencyKey
     });
     output(result, () => {
       const request = record(result.request);
@@ -2405,6 +2715,24 @@ async function campaignOs(args) {
     });
     return;
   }
+  if (action === "prepare-preflight") {
+    const clientId = flag("client-id");
+    const requestId = flag("request-id");
+    if (!clientId || !requestId) {
+      throw new CliInputError("signaliz campaign-os prepare-preflight requires --client-id <uuid> --request-id <uuid>");
+    }
+    const result = await client.prepareCampaignOsActionPreflight(clientId, requestId);
+    output(result, () => {
+      const receipt = record(result.continuation_receipt);
+      const missing = Array.isArray(receipt.missing_inputs) ? receipt.missing_inputs : [];
+      const blockers = Array.isArray(receipt.system_blockers) ? receipt.system_blockers : [];
+      process.stdout.write(`Action preflight continuation: ${String(receipt.implementation_status || "blocked")}
+`);
+      process.stdout.write(`${missing.length} missing input(s) \xB7 ${blockers.length} system blocker(s) \xB7 provider calls 0
+`);
+    });
+    return;
+  }
   if (action === "receipts") {
     const limit = numberFlag("limit") ?? 50;
     requireIntegerInRange(limit, "--limit", 1, 200);
@@ -2422,7 +2750,7 @@ async function campaignOs(args) {
     });
     return;
   }
-  throw new CliInputError("Usage: signaliz campaign-os clients|context|knowledge|provider-runtime|build|build-status|draft|audience-draft|materialize-cache-audience|audience-preview|compile|request|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|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.90",
+  "version": "1.0.92",
   "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.94"
+    "@signaliz/sdk": "^1.0.96"
   },
   "devDependencies": {
     "tsup": "^8.0.0",