@signaliz/sdk 1.0.17 → 1.0.19

package/dist/cli.mjs

@@ -62,6 +62,13 @@ async function main() {
       await handleGtmCommand(signaliz, process.argv.slice(3));
       break;
     }
+    case "public-data":
+    case "ground-truth":
+    case "public-ground-truth": {
+      const signaliz = await createSignalizClient();
+      await handlePublicGroundTruthCommand(signaliz, process.argv.slice(3));
+      break;
+    }
     case "campaign-agent":
     case "campaign-builder": {
       await handleCampaignAgentCommand(createSignalizClient, process.argv.slice(3));
@@ -71,6 +78,51 @@ async function main() {
       printHelp();
   }
 }
+async function handlePublicGroundTruthCommand(signaliz, argv) {
+  const subcommand = argv[0] && !argv[0].startsWith("--") ? argv[0] : "search";
+  if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    printPublicGroundTruthHelp();
+    return;
+  }
+  if (subcommand === "sources" || subcommand === "list-sources") {
+    const flags2 = parseFlags(argv.slice(subcommand === argv[0] ? 1 : 0));
+    const result2 = await signaliz.publicGroundTruth.listSources({
+      query: stringFlag(flags2, "query", "q", "search"),
+      status: stringFlag(flags2, "status"),
+      limit: numberFlag(flags2, "limit")
+    });
+    if (booleanFlag(flags2, "json")) {
+      printJson(result2);
+    } else {
+      printPublicGroundTruthSources(result2);
+    }
+    return;
+  }
+  if (subcommand !== "search") {
+    throw new Error(`Unknown public-data command: ${subcommand}`);
+  }
+  const flags = parseFlags(argv.slice(subcommand === argv[0] ? 1 : 0));
+  const query = stringFlag(flags, "query", "q", "search");
+  const sourceId = stringFlag(flags, "source-id", "sourceId");
+  const entityType = stringFlag(flags, "entity-type", "entityType");
+  const filters = publicGroundTruthFiltersFromFlags(flags);
+  if (!query && !sourceId && !entityType && Object.keys(filters).length === 0) {
+    throw new Error("public-data search requires --query or at least one filter");
+  }
+  const result = await signaliz.publicGroundTruth.search({
+    query,
+    sourceId,
+    entityType,
+    ...filters,
+    limit: numberFlag(flags, "limit"),
+    offset: numberFlag(flags, "offset")
+  });
+  if (booleanFlag(flags, "json")) {
+    printJson(result);
+  } else {
+    printPublicGroundTruthSearch(result);
+  }
+}
 async function handleGtmCommand(signaliz, argv) {
   const subcommand = argv[0];
   if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
@@ -1057,6 +1109,69 @@ function jsonObjectFromString(value, label) {
   }
   return parsed;
 }
+var PUBLIC_GROUND_TRUTH_CLI_FILTERS = [
+  ["industry", "industry"],
+  ["location", "location"],
+  ["nativeId", "native-id", "nativeId"],
+  ["entityName", "entity-name", "entityName"],
+  ["domain", "domain"],
+  ["websiteUrl", "website-url", "websiteUrl"],
+  ["phone", "phone"],
+  ["email", "email"],
+  ["city", "city"],
+  ["state", "state"],
+  ["postalCode", "postal-code", "postalCode"],
+  ["country", "country"],
+  ["sourceUrl", "source-url", "sourceUrl"],
+  ["naics", "naics"],
+  ["industryCode", "industry-code", "industryCode"],
+  ["industryType", "industry-type", "industryType"],
+  ["year", "year"],
+  ["quarter", "quarter"],
+  ["areaFips", "area-fips", "areaFips"],
+  ["geoId", "geo-id", "geoId"],
+  ["ownCode", "own-code", "ownCode"],
+  ["sourceUpdatedAfter", "source-updated-after", "sourceUpdatedAfter"],
+  ["sourceUpdatedBefore", "source-updated-before", "sourceUpdatedBefore"],
+  ["observedAfter", "observed-after", "observedAfter"],
+  ["observedBefore", "observed-before", "observedBefore"]
+];
+function objectFromKeyValueFlags(flags, keyValueNames, jsonNames) {
+  const object = {};
+  for (const jsonName of jsonNames) {
+    const parsed = jsonObjectFlag(flags, jsonName);
+    if (parsed) Object.assign(object, parsed);
+  }
+  for (const pair of repeatedStringFlag(flags, ...keyValueNames)) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) throw new Error(`Expected key=value for --${keyValueNames[0]}`);
+    const key = pair.slice(0, eq).trim();
+    const value = pair.slice(eq + 1).trim();
+    if (!key) throw new Error(`Expected non-empty key for --${keyValueNames[0]}`);
+    object[key] = value;
+  }
+  return Object.keys(object).length > 0 ? object : void 0;
+}
+function publicGroundTruthFiltersFromFlags(flags) {
+  const filters = {};
+  for (const [paramName, ...flagNames] of PUBLIC_GROUND_TRUTH_CLI_FILTERS) {
+    const value = stringFlag(flags, ...flagNames);
+    if (value) filters[paramName] = value;
+  }
+  const joinKeys = objectFromKeyValueFlags(
+    flags,
+    ["join-key", "joinKey"],
+    ["join-keys-json", "joinKeysJson"]
+  );
+  const rowData = objectFromKeyValueFlags(
+    flags,
+    ["row-data", "rowData"],
+    ["row-data-json", "rowDataJson"]
+  );
+  if (joinKeys) filters.joinKeys = joinKeys;
+  if (rowData) filters.rowData = rowData;
+  return filters;
+}
 function printResult(result, flags) {
   if (booleanFlag(flags, "json")) {
     printJson(result);
@@ -1133,10 +1248,59 @@ function printCampaignAgentExecution(payload, flags) {
     printJson(payload);
     return;
   }
+  printCampaignAgentOperatorVerdict(payload);
   printCampaignAgentPlan(payload.plan);
   console.log("\nResult:");
   printJson(payload.result);
 }
+function printCampaignAgentOperatorVerdict(payload) {
+  const result = asRecord(payload.result);
+  const build = hasRecordKeys(asRecord(result.build)) ? asRecord(result.build) : result;
+  const finalStatus = asRecord(result.finalStatus);
+  const deliveryApproval = asRecord(result.deliveryApproval);
+  const status = textFromRecord(finalStatus, "status") ?? textFromRecord(build, "status") ?? "unknown";
+  const dryRun = build.dryRun === true || build.dry_run === true || status === "dry_run";
+  const campaignBuildId = textFromRecord(build, "campaignBuildId", "campaign_build_id") ?? textFromRecord(finalStatus, "campaignBuildId", "campaign_build_id");
+  const campaignId = textFromRecord(build, "campaignId", "campaign_id") ?? textFromRecord(finalStatus, "campaignId", "campaign_id");
+  if (dryRun) {
+    console.log("Operator verdict: dry run complete; nothing launched.");
+    console.log("Safety: Dry-run only. No spend, provider write, sender load, delivery, or launch ran.");
+  } else if (textFromRecord(finalStatus, "status") === "completed") {
+    console.log("Operator verdict: approved campaign build completed.");
+    console.log("Safety: Approved build path. Review rows and artifacts before any delivery expansion.");
+  } else {
+    console.log(`Operator verdict: approved campaign build ${status}.`);
+    console.log("Safety: Approved build path. Spend and provider writes require the supplied approval packet; delivery remains separately gated.");
+  }
+  console.log(`Approval state: ${campaignAgentApprovalState(payload)}`);
+  if (campaignId) console.log(`Campaign ID: ${campaignId}`);
+  if (campaignBuildId) console.log(`Campaign build ID: ${campaignBuildId}`);
+  if (hasRecordKeys(finalStatus)) console.log(`Final status: ${textFromRecord(finalStatus, "status") ?? "unknown"}`);
+  if (hasRecordKeys(deliveryApproval)) console.log(`Delivery approval: ${textFromRecord(deliveryApproval, "status") ?? "unknown"}`);
+  console.log(`Next safe command: ${campaignAgentNextSafeCommand(payload.plan, dryRun, campaignBuildId)}`);
+  console.log("");
+}
+function campaignAgentApprovalState(payload) {
+  if (payload.approval) return "approval packet supplied";
+  const required = payload.plan.approvals.map((item) => item.type);
+  return required.length ? `missing ${required.join(", ")}` : "no explicit approvals required";
+}
+function campaignAgentNextSafeCommand(plan, dryRun, campaignBuildId) {
+  if (campaignBuildId) return `signaliz campaign-agent review ${campaignBuildId} --limit 100`;
+  if (!dryRun) return "signaliz campaign-agent status <campaign-build-id>";
+  return [
+    "signaliz campaign-agent build-approved",
+    "--goal",
+    shellQuote(plan.campaignName),
+    "--target-count",
+    String(plan.targetCount),
+    "--confirm-launch",
+    "--approve-all",
+    "--approved-by <operator-email>",
+    "--spend-limit",
+    String(plan.estimatedCredits)
+  ].join(" ");
+}
 function printCampaignAgentReadiness(readiness) {
   const summary = asRecord(readiness.summary);
   const plan = readiness.plan;
@@ -1175,6 +1339,13 @@ function printCampaignAgentBuildStatus(status) {
   if (status.campaignId) console.log(`Campaign ID: ${status.campaignId}`);
   console.log(`Status: ${status.status}`);
   console.log(`Phase: ${status.currentPhase || "N/A"}`);
+  const terminalState = asRecord(status.terminalState);
+  if (terminalState.kind) {
+    console.log(`Terminal state: ${terminalState.kind} (${terminalState.label || "no label"})`);
+    if (terminalState.heartbeatAgeSeconds !== void 0 && terminalState.heartbeatAgeSeconds !== null) {
+      console.log(`Heartbeat age: ${terminalState.heartbeatAgeSeconds}s`);
+    }
+  }
   console.log(`Rows: ${status.recordsSucceeded}/${status.recordsTotal} succeeded, ${status.recordsFailed} failed`);
   printCampaignCustomerRowCounts(status);
   console.log(`Artifacts: ${status.artifactCount}`);
@@ -1196,6 +1367,8 @@ function printCampaignAgentBuildStatus(status) {
     console.log(`Next: ${status.nextAction}`);
   } else if (status.status === "pending_approval") {
     console.log(`Next: signaliz campaign-agent approve ${status.campaignBuildId} --destination-type webhook`);
+  } else if (terminalState.safeNextAction) {
+    console.log(`Next: ${terminalState.safeNextAction}`);
   }
 }
 function printCampaignCustomerRowCounts(status) {
@@ -1203,7 +1376,10 @@ function printCampaignCustomerRowCounts(status) {
   if (!counts || typeof counts !== "object") return;
   const value = (camel, snake) => counts[camel] ?? counts[snake] ?? "n/a";
   const requested = value("requestedTarget", "requested_target");
-  console.log(`Customer rows: accepted ${value("acceptedRows", "accepted_rows")}/${requested}, copied ${value("copiedRows", "copied_rows")}, approval-ready ${value("approvalReadyRows", "approval_ready_rows")}, QA-ready ${value("qaReadyRows", "qa_ready_rows")}, delivered ${value("deliveredRows", "delivered_rows")}`);
+  const copied = value("copiedRows", "copied_rows");
+  const copySkipped = value("copySkippedRows", "copy_skipped_rows");
+  const copyLabel = typeof copySkipped === "number" && copySkipped > 0 && (!copied || copied === "n/a") ? `copy-skipped ${copySkipped}` : `copied ${copied}`;
+  console.log(`Customer rows: accepted ${value("acceptedRows", "accepted_rows")}/${requested}, ${copyLabel}, approval-ready ${value("approvalReadyRows", "approval_ready_rows")}, QA-ready ${value("qaReadyRows", "qa_ready_rows")}, delivered ${value("deliveredRows", "delivered_rows")}`);
   const shortfalls = [
     ["accepted", value("acceptedShortfall", "accepted_shortfall")],
     ["usable", value("usableShortfall", "usable_shortfall")],
@@ -1219,17 +1395,20 @@ function printCampaignAgentBuildReview(review) {
   console.log(`Campaign: ${review.status?.name || review.campaignBuildId}`);
   console.log(`Status: ${summary.status || review.status?.status}`);
   console.log(`Phase: ${summary.phase || review.status?.currentPhase || "N/A"}`);
+  console.log(`Terminal state: ${summary.terminalState || review.status?.terminalState?.kind || "unknown"}`);
   console.log(`Rows: ${summary.sampledRows || 0} sampled, ${summary.availableRows || 0} available`);
   console.log(`Qualified: ${summary.qualifiedRows || 0}`);
   console.log(`Emails: ${summary.rowsWithEmail || 0}`);
   console.log(`Copy ready: ${summary.copyReadyRows || 0}`);
   console.log(`Artifacts: ${summary.artifactCount || 0}`);
+  printCampaignAgentNorthStarScorecard(review.northStarScorecard);
   if (review.campaignBuildId) printCampaignArtifactDownload(review.status, review.campaignBuildId);
   console.log(`Delivery approval ready: ${summary.readyForDeliveryApproval === true ? "yes" : "no"}`);
   if (Array.isArray(review.gates) && review.gates.length > 0) {
     console.log("\nGates:");
     for (const gate of review.gates) {
-      console.log(`- ${gate.passed ? "PASS" : "BLOCKED"} ${gate.label}: ${gate.detail}`);
+      const status = String(gate.status || (gate.passed ? "pass" : "blocked")).toUpperCase();
+      console.log(`- ${status} ${gate.label}: ${gate.detail}`);
     }
   }
   const warnings = Array.isArray(summary.warnings) ? summary.warnings : [];
@@ -1243,6 +1422,21 @@ function printCampaignAgentBuildReview(review) {
     for (const action of nextActions) console.log(`- ${action}`);
   }
 }
+function printCampaignAgentNorthStarScorecard(scorecard) {
+  const card = asRecord(scorecard);
+  if (!card.version) return;
+  const score = card.score === null || card.score === void 0 ? "pending" : `${card.score}%`;
+  console.log(`North Star: ${String(card.status || "unknown")} (${score})`);
+  if (card.moatState) console.log(`Moat state: ${card.moatState}`);
+  const metrics = Array.isArray(card.metrics) ? card.metrics : [];
+  if (metrics.length > 0) {
+    console.log("\nNorth Star gates:");
+    for (const metric of metrics.slice(0, 12)) {
+      const item = asRecord(metric);
+      console.log(`- ${String(item.status || "review").toUpperCase()} ${item.label || item.id}: ${item.detail || ""}`);
+    }
+  }
+}
 function formatCampaignAgentRows(rows) {
   return rows.map((row) => {
     const data = asRecord(row.data);
@@ -1320,6 +1514,20 @@ function printCampaignAgentCopySnippets(rows, limit = 5) {
 function asRecord(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
+function hasRecordKeys(value) {
+  return Object.keys(value).length > 0;
+}
+function textFromRecord(record, ...keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+    if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  }
+  return void 0;
+}
+function shellQuote(value) {
+  return `'${String(value || "").replace(/'/g, `'\\''`)}'`;
+}
 function printCampaignAgentProof(proof) {
   console.log(`Campaign-agent proof: ${proof.success ? "passed" : "failed"}`);
   const campaign = asRecord(proof.campaign);
@@ -1337,6 +1545,51 @@ function printCampaignAgentProof(proof) {
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
+function truncateCell(value, width) {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  return text.length > width ? `${text.slice(0, Math.max(width - 3, 0))}...` : text;
+}
+function printPublicGroundTruthSearch(result) {
+  const records = Array.isArray(result.records) ? result.records : [];
+  console.log(`Public data search: ${result.total_count ?? 0} matches (${records.length} returned)`);
+  if (result.query) console.log(`Query: ${result.query}`);
+  if (result.source_id) console.log(`Source: ${result.source_id}`);
+  if (result.entity_type) console.log(`Entity type: ${result.entity_type}`);
+  if (!records.length) {
+    console.log("No records matched.");
+    return;
+  }
+  console.log("");
+  console.log("Source".padEnd(22) + "Native ID".padEnd(22) + "Name".padEnd(42) + "Industry".padEnd(28) + "Domain".padEnd(24) + "Loc".padEnd(12) + "Match");
+  console.log("-".repeat(160));
+  for (const record of records) {
+    const loc = [record.city, record.state].filter(Boolean).join(", ");
+    const industry = [record.industry_code, record.industry_name].filter(Boolean).join(" ");
+    console.log(
+      truncateCell(record.source_id, 21).padEnd(22) + truncateCell(record.native_id, 21).padEnd(22) + truncateCell(record.entity_name, 41).padEnd(42) + truncateCell(industry, 27).padEnd(28) + truncateCell(record.domain, 23).padEnd(24) + truncateCell(loc, 11).padEnd(12) + truncateCell(record.match_type, 16)
+    );
+  }
+  if (result.next_offset !== null && result.next_offset !== void 0) {
+    console.log(`
+Next page: --offset ${result.next_offset}`);
+  }
+}
+function printPublicGroundTruthSources(result) {
+  const sources = Array.isArray(result.sources) ? result.sources : [];
+  console.log(`Public data sources: ${sources.length}/${result.total ?? sources.length}`);
+  if (!sources.length) {
+    console.log("No sources matched.");
+    return;
+  }
+  console.log("");
+  console.log("Source ID".padEnd(30) + "Status".padEnd(12) + "Rung".padEnd(7) + "Join key".padEnd(20) + "Cadence".padEnd(16) + "Name");
+  console.log("-".repeat(120));
+  for (const source of sources) {
+    console.log(
+      truncateCell(source.id, 29).padEnd(30) + truncateCell(source.ingestion_status, 11).padEnd(12) + String(source.ground_truth_rung ?? "").padEnd(7) + truncateCell(source.primary_join_key || source.join_key_quality, 19).padEnd(20) + truncateCell(source.update_cadence, 15).padEnd(16) + truncateCell(source.name, 40)
+    );
+  }
+}
 function printHelp() {
   console.log(`
 Signaliz CLI v1.0.0
@@ -1344,6 +1597,8 @@ Signaliz CLI v1.0.0
 Usage:
   signaliz test                       Verify API connectivity
   signaliz tools                      List all available MCP tools
+  signaliz public-data search --query "swift transportation" --limit 10
+  signaliz public-data sources --status ready
   signaliz gtm context --json         Load GTM Kernel workspace context
   signaliz gtm bootstrap --json       Inspect GTM Kernel readiness
   signaliz gtm templates --json       List private-safe campaign strategy templates
@@ -1374,6 +1629,25 @@ Environment:
   SIGNALIZ_BASE_URL  Optional API base URL override
 `);
 }
+function printPublicGroundTruthHelp() {
+  console.log(`
+Signaliz public-data commands:
+
+  signaliz public-data search [--query TEXT] [--industry TEXT] [--location TEXT] [--source-id ID] [--domain DOMAIN] [--naics CODE] [--state ST] [--year YYYY] [--join-key k=v] [--row-data k=v] [--limit N] [--offset N] [--json]
+  signaliz public-data sources [--query TEXT] [--status ready|partial|blocked|planned] [--limit N] [--json]
+
+Aliases:
+  signaliz ground-truth search ...
+
+Examples:
+  signaliz public-data search --query "swift transportation" --source-id fmcsa_company_census --limit 10
+  signaliz public-data search --industry "software publishers" --location CA --limit 25 --json
+  signaliz public-data search --source-id bls_qcew --naics 541511 --state CA --year 2025 --json
+  signaliz public-data search --domain swifttrans.com --json
+  signaliz public-data search --join-key ein=123456789 --json
+  signaliz public-data sources --status ready --json
+`);
+}
 function printGtmHelp() {
   console.log(`
 Signaliz GTM commands: