@signaliz/cli 1.0.89 → 1.0.91

package/README.md

@@ -216,18 +216,32 @@ signaliz campaign-os audience-draft --client-id <uuid> --name "Launch ICP" \
   --definition-file audience.json --entity-type people \
   --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> --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
 ```
 
 `provider-runtime` explains the safe Clay or Instantly route, adapter source,
 approval boundaries, and receipt semantics without returning credentials or
-calling the provider. `build`, `audience-draft`, `audience-preview`, and
-`compile` do not need CMM-admin approval and keep providers locked. `request`
-creates only an auditable review request for paid sourcing, provider load,
+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; 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,10 +63,14 @@ 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> [--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 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:
@@ -2239,7 +2243,7 @@ async function campaignOs(args) {
       const campaign = record(result.campaign);
       process.stdout.write(`Campaign Brain build: ${String(build.status || "unknown")}
 `);
-      if (campaign.id) process.stdout.write(`Review-held campaign: ${String(campaign.name || "")} (${String(campaign.id)})
+      if (campaign.id) process.stdout.write(`Provider-locked campaign: ${String(campaign.name || "")} (${String(campaign.id)})
 `);
       process.stdout.write("Provider execution remains locked.\n");
     });
@@ -2284,13 +2288,51 @@ async function campaignOs(args) {
     });
     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-locked draft created without admin approval: ${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, Instantly, Smartlead, or Bison mutation was performed.\n");
     });
     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");
@@ -2340,6 +2382,70 @@ async function campaignOs(args) {
     output(result, () => process.stdout.write("No-spend Audience preview recorded \xB7 provider calls 0 \xB7 Clay usage 0\n"));
     return;
   }
+  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) {
+      throw new CliInputError("signaliz campaign-os materialize-cache-audience requires --client-id, --audience-id, --target-count <1-500>, and --idempotency-key");
+    }
+    requireIntegerInRange(targetCount, "--target-count", 1, 500);
+    const result = await client.materializeCampaignOsCacheAudience({
+      clientId,
+      audienceId,
+      campaignId,
+      targetCount,
+      idempotencyKey
+    });
+    output(result, () => {
+      const usage = record(result.usage_receipt);
+      const reconciliation = record(result.terminal_reconciliation_receipt);
+      process.stdout.write(`Cache Audience materialized: target ${targetCount}
+`);
+      process.stdout.write(`Provider calls: ${String(usage.provider_calls)} \xB7 Clay Search allowance: ${String(usage.clay_search_allowance_used)} \xB7 Clay Actions: ${String(usage.clay_actions_used)} \xB7 Clay Data Credits: ${String(usage.clay_data_credits_used)}
+`);
+      process.stdout.write(`Terminal reconciliation receipt: ${JSON.stringify(reconciliation)}
+`);
+      process.stdout.write("No provider approval was requested.\n");
+    });
+    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");
@@ -2354,19 +2460,62 @@ async function campaignOs(args) {
     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);
@@ -2376,6 +2525,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);
@@ -2393,7 +2560,7 @@ async function campaignOs(args) {
     });
     return;
   }
-  throw new CliInputError("Usage: signaliz campaign-os clients|context|knowledge|provider-runtime|build|build-status|draft|audience-draft|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|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.89",
+  "version": "1.0.91",
   "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.93"
+    "@signaliz/sdk": "^1.0.95"
   },
   "devDependencies": {
     "tsup": "^8.0.0",