@signaliz/sdk 1.0.11 → 1.0.13

package/README.md

@@ -93,19 +93,30 @@ const plan = await signaliz.campaignBuilderAgent.createPlan({
 });
 
 const dryRun = await signaliz.campaignBuilderAgent.dryRunPlan(plan);
+const readiness = await signaliz.campaignBuilderAgent.readiness({
+  goal: 'Build a strategy-template campaign for mature local operators',
+  strategyTemplate: 'non-medical-home-care',
+  targetCount: 500,
+  builtIns: ['lead_generation', 'local_leads', 'email_finding', 'email_verification', 'signals'],
+});
 
 console.log(plan.strategyMemoryStatus?.ready);
+console.log(readiness.summary.ready);
 console.log(plan.mcpFlow.filter((step) =>
   ['gtm_provider_recipe_prepare', 'gtm_provider_route_activate'].includes(step.tool)
 ));
 
 // After an approved launch, keep review and delivery in the agent surface.
+const review = await signaliz.campaignBuilderAgent.reviewBuild('campaign_build_id', {
+  limit: 100,
+});
 const finalStatus = await signaliz.campaignBuilderAgent.getBuildStatus('campaign_build_id');
 const reviewRows = await signaliz.campaignBuilderAgent.getBuildRows('campaign_build_id', {
   limit: 100,
   qualified: true,
 });
 const artifacts = await signaliz.campaignBuilderAgent.listBuildArtifacts('campaign_build_id');
+console.log(review.summary.readyForDeliveryApproval);
 ```
 
 The CLI can run the same request shape from a reusable JSON file, with flags
@@ -124,7 +135,12 @@ npx @signaliz/sdk campaign-agent plan \
   --target-count 250 \
   --json
 
+npx @signaliz/sdk campaign-agent doctor \
+  --request-file campaign-request.json \
+  --json
+
 npx @signaliz/sdk campaign-agent status campaign_build_id --json
+npx @signaliz/sdk campaign-agent review campaign_build_id --limit 100 --json
 npx @signaliz/sdk campaign-agent rows campaign_build_id --limit 100 --json
 ```
 

package/dist/{chunk-QQW6DZQ4.mjs → chunk-DJVOGXVD.mjs}

@@ -1191,6 +1191,13 @@ var DEFAULT_CAMPAIGN_BUILDER_BUILT_INS = [
   "email_verification",
   "signals"
 ];
+var CAMPAIGN_BUILDER_BUILT_IN_ROUTE_IDS = {
+  lead_generation: "signaliz-lead-generation",
+  local_leads: "signaliz-local-leads",
+  email_finding: "signaliz-email-finding",
+  email_verification: "signaliz-email-verification",
+  signals: "signaliz-signals"
+};
 var DEFAULT_CAMPAIGN_BUILDER_APPROVAL_TYPES = [
   "memory_retrieval",
   "spend",
@@ -1687,6 +1694,10 @@ var CampaignBuilderAgent = class {
     }
     return plan;
   }
+  async readiness(request, options = {}) {
+    const plan = await this.createPlan(request, options);
+    return createCampaignBuilderReadiness(plan);
+  }
   async commitPlan(plan, options = {}) {
     const writeMode = options.confirm === true && options.dryRun === false;
     if (writeMode && !options.approvedBy) {
@@ -1874,6 +1885,15 @@ var CampaignBuilderAgent = class {
   async approveDelivery(campaignBuildId, destinationType, options) {
     return this.approveCampaignDelivery(campaignBuildId, destinationType, options);
   }
+  async reviewBuild(campaignBuildId, options = {}) {
+    const status = await this.getBuildStatus(campaignBuildId);
+    const rows = await this.getBuildRows(campaignBuildId, {
+      ...options,
+      limit: options.limit ?? 100
+    });
+    const artifacts = await this.listBuildArtifacts(campaignBuildId);
+    return createCampaignBuilderBuildReview(status, rows, artifacts);
+  }
   async getCampaignBuildStatus(campaignBuildId) {
     const data = await this.callMcp("get_campaign_build_status", {
       campaign_build_id: campaignBuildId
@@ -2038,6 +2058,91 @@ function createCampaignBuilderAgentPlan(request, context = {}) {
     warnings: context.warnings ?? []
   };
 }
+function createCampaignBuilderReadiness(plan) {
+  const lanes = plan.routes.map((route) => createCampaignBuilderReadinessLane(route, plan));
+  const builtInLanes = lanes.filter((lane) => lane.builtIn);
+  const customRoutes = lanes.filter((lane) => lane.customRoute);
+  const strategyMemory = asRecord(plan.strategyMemoryStatus);
+  const deliveryRisk = asRecord(plan.buildRequest.deliveryRisk);
+  const deliveryRiskBlockers = arrayOfStrings(deliveryRisk.blockers) ?? [];
+  const deliveryRiskValue = asRecord(deliveryRisk.risk);
+  const deliveryRiskLevel = stringValue(deliveryRiskValue.risk_level ?? deliveryRiskValue.riskLevel);
+  const memoryReady = !plan.strategyMemoryStatus || strategyMemory.ready !== false;
+  const kernelPlanReady = Object.keys(asRecord(plan.kernelPlan)).length > 0;
+  const deliveryRiskReady = !plan.buildRequest.deliveryRisk || deliveryRiskBlockers.length === 0 && !["high", "critical", "blocked"].includes(String(deliveryRiskLevel ?? "").toLowerCase());
+  const builtInsReady = builtInLanes.length > 0 && builtInLanes.every((lane) => lane.ready);
+  const customRoutesReady = customRoutes.every((lane) => lane.ready);
+  const approvalGatesReady = plan.approvals.length > 0;
+  const gates = [
+    {
+      id: "campaign_plan_created",
+      label: "Campaign plan created",
+      passed: Boolean(plan.planId && plan.mcpFlow.length > 0),
+      detail: plan.planId ? `Plan ${plan.planId} has ${plan.mcpFlow.length} MCP step(s).` : "No campaign-builder plan was created."
+    },
+    {
+      id: "built_in_lanes_ready",
+      label: "Built-in lanes ready",
+      passed: builtInsReady,
+      detail: `${builtInLanes.filter((lane) => lane.ready).length}/${builtInLanes.length} Signaliz built-in lane(s) are present.`
+    },
+    {
+      id: "strategy_memory_ready",
+      label: "Strategy memory ready",
+      passed: memoryReady,
+      detail: plan.strategyMemoryStatus ? "Strategy memory readiness was checked." : "Strategy memory readiness was not requested."
+    },
+    {
+      id: "kernel_plan_attached",
+      label: "Kernel plan attached",
+      passed: kernelPlanReady,
+      detail: kernelPlanReady ? "Kernel planner evidence is attached." : "Kernel planner evidence is not attached."
+    },
+    {
+      id: "delivery_risk_clear",
+      label: "Delivery risk clear",
+      passed: deliveryRiskReady,
+      detail: plan.buildRequest.deliveryRisk ? `Delivery risk is ${deliveryRiskLevel || "available"} with ${deliveryRiskBlockers.length} blocker(s).` : "Delivery risk preflight was not requested."
+    },
+    {
+      id: "custom_routes_prepared",
+      label: "Custom routes prepared",
+      passed: customRoutesReady,
+      detail: customRoutes.length === 0 ? "No BYO routes were requested." : `${customRoutes.filter((lane) => lane.ready).length}/${customRoutes.length} BYO route(s) have read-only setup steps.`
+    },
+    {
+      id: "approval_gates_present",
+      label: "Approval gates present",
+      passed: approvalGatesReady,
+      detail: approvalGatesReady ? `${plan.approvals.length} approval gate(s) are attached.` : "No approval gates are attached."
+    }
+  ];
+  const blockers = [
+    ...gates.filter((gate) => !gate.passed).map((gate) => gate.detail),
+    ...lanes.flatMap((lane) => lane.blockers)
+  ];
+  const score = gates.length === 0 ? 0 : Math.round(gates.filter((gate) => gate.passed).length / gates.length * 100);
+  const ready = blockers.length === 0;
+  return {
+    plan,
+    lanes,
+    gates,
+    summary: {
+      ready,
+      score,
+      targetCount: plan.targetCount,
+      estimatedCredits: plan.estimatedCredits,
+      builtInLanesReady: builtInLanes.filter((lane) => lane.ready).length,
+      builtInLanesTotal: builtInLanes.length,
+      customRoutesReady: customRoutes.filter((lane) => lane.ready).length,
+      customRoutesTotal: customRoutes.length,
+      approvalGateCount: plan.approvals.length,
+      blockers,
+      warnings: plan.warnings
+    },
+    nextActions: campaignReadinessNextActions(plan, ready, customRoutes.length)
+  };
+}
 function getMissingCampaignBuilderApprovals(plan, approval) {
   if (approval.planId !== plan.planId) {
     return plan.approvals;
@@ -3301,6 +3406,185 @@ function mapAgentCampaignArtifact(data) {
     createdAt: stringValue(data.created_at) ?? ""
   };
 }
+function createCampaignBuilderBuildReview(status, rows, artifacts) {
+  const sampledRows = rows.rows.length;
+  const availableRows = rows.count || sampledRows;
+  const qualifiedRows = rows.rows.filter((row) => row.qualified !== false).length;
+  const rowsWithEmail = rows.rows.filter(campaignReviewRowHasEmail).length;
+  const copyReadyRows = rows.rows.filter(campaignReviewRowHasCopy).length;
+  const artifactCount = artifacts.length || status.artifactCount || 0;
+  const gates = [
+    {
+      id: "build_completed",
+      label: "Build completed",
+      passed: status.status === "completed",
+      detail: status.status === "completed" ? "The campaign build is completed." : `The campaign build is ${status.status}; review again after completion.`
+    },
+    {
+      id: "rows_available",
+      label: "Rows available",
+      passed: sampledRows > 0,
+      detail: sampledRows > 0 ? `${sampledRows} sampled row(s) are available for review.` : "No rows were returned for review."
+    },
+    {
+      id: "qualified_sample",
+      label: "Sample rows qualified",
+      passed: sampledRows > 0 && qualifiedRows === sampledRows,
+      detail: sampledRows > 0 ? `${qualifiedRows}/${sampledRows} sampled row(s) are marked qualified.` : "Qualification could not be checked without sampled rows."
+    },
+    {
+      id: "email_coverage",
+      label: "Email coverage",
+      passed: sampledRows > 0 && rowsWithEmail === sampledRows,
+      detail: sampledRows > 0 ? `${rowsWithEmail}/${sampledRows} sampled row(s) include an email.` : "Email coverage could not be checked without sampled rows."
+    },
+    {
+      id: "artifact_available",
+      label: "Artifact available",
+      passed: artifactCount > 0,
+      detail: artifactCount > 0 ? `${artifactCount} artifact(s) are available.` : "No delivery artifact is available yet."
+    },
+    {
+      id: "no_failed_rows",
+      label: "No failed rows",
+      passed: status.recordsFailed === 0,
+      detail: status.recordsFailed === 0 ? "The build reports zero failed rows." : `${status.recordsFailed} row(s) failed during the build.`
+    }
+  ];
+  const blockedReasons = gates.filter((gate) => !gate.passed).map((gate) => gate.detail);
+  const warnings = [
+    rows.hasMore ? "This review is based on a row sample; page through remaining rows before final approval." : void 0,
+    sampledRows > 0 && copyReadyRows < sampledRows ? `${copyReadyRows}/${sampledRows} sampled row(s) include generated copy.` : void 0,
+    ...status.warnings
+  ].filter((item) => Boolean(item));
+  const readyForDeliveryApproval = blockedReasons.length === 0;
+  return {
+    campaignBuildId: status.campaignBuildId || rows.campaignBuildId,
+    status,
+    rows,
+    artifacts,
+    gates,
+    summary: {
+      status: status.status,
+      phase: status.currentPhase,
+      sampledRows,
+      availableRows,
+      qualifiedRows,
+      rowsWithEmail,
+      copyReadyRows,
+      artifactCount,
+      readyForDeliveryApproval,
+      blockedReasons,
+      warnings
+    },
+    nextActions: campaignReviewNextActions(status, readyForDeliveryApproval)
+  };
+}
+function campaignReviewNextActions(status, readyForDeliveryApproval) {
+  const buildId = status.campaignBuildId;
+  if (!buildId) return [];
+  if (status.status === "completed" && readyForDeliveryApproval) {
+    return [
+      `signaliz campaign-agent approve ${buildId} --destination-type json`,
+      `signaliz campaign-agent artifacts ${buildId}`
+    ];
+  }
+  if (status.status === "completed") {
+    return [
+      `signaliz campaign-agent rows ${buildId} --limit 100`,
+      `signaliz campaign-agent artifacts ${buildId}`
+    ];
+  }
+  if (status.status === "pending_approval") {
+    return [
+      `signaliz campaign-agent rows ${buildId} --limit 100`,
+      `signaliz campaign-agent approve ${buildId} --destination-type json`
+    ];
+  }
+  if ((status.status === "queued" || status.status === "running") && status.triggerRunId) {
+    return [`signaliz ops run-status ${status.triggerRunId} --watch`];
+  }
+  return [`signaliz campaign-agent status ${buildId}`];
+}
+function campaignReviewRowHasEmail(row) {
+  const data = asRecord(row.data);
+  return Boolean(
+    stringValue(data.email) || stringValue(data.work_email) || stringValue(data.workEmail)
+  );
+}
+function campaignReviewRowHasCopy(row) {
+  const data = asRecord(row.data);
+  const copy = asRecord(data.copy);
+  const rawCopy = asRecord(data.raw_copy ?? data.rawCopy);
+  return row.status === "copy_ready" || data.copy_ready === true || Boolean(
+    stringValue(data.subject) || stringValue(data.subject_line) || stringValue(data.subjectLine) || stringValue(data.opener) || stringValue(data.body) || stringValue(data.cta) || stringValue(copy.subject) || stringValue(copy.body) || stringValue(rawCopy.subject) || stringValue(rawCopy.body)
+  );
+}
+function createCampaignBuilderReadinessLane(route, plan) {
+  const builtIn = campaignBuilderBuiltInForRoute(route);
+  const customRoute = route.provider !== "signaliz" && route.provider !== "csv" && builtIn === void 0;
+  const prepareStep = plan.mcpFlow.find(
+    (step) => step.tool === "gtm_provider_recipe_prepare" && step.arguments.provider_id === route.provider
+  );
+  const activateStep = plan.mcpFlow.find(
+    (step) => step.tool === "gtm_provider_route_activate" && step.arguments.provider_id === route.provider
+  );
+  const readOnlySetup = !customRoute || prepareStep?.readOnly === true && activateStep?.readOnly === true && activateStep.arguments.dry_run === true && activateStep.arguments.confirm === false;
+  const blockers = [
+    customRoute && !prepareStep ? `${route.label ?? route.provider} is missing provider recipe setup.` : void 0,
+    customRoute && !activateStep ? `${route.label ?? route.provider} is missing provider route dry-run setup.` : void 0,
+    customRoute && !readOnlySetup ? `${route.label ?? route.provider} route setup must stay read-only before approval.` : void 0,
+    route.mode === "required" && !route.toolName && customRoute ? `${route.label ?? route.provider} is required but has no tool name.` : void 0
+  ].filter((item) => Boolean(item));
+  return {
+    id: route.id ?? `${route.provider}-${route.layer}`,
+    label: route.label ?? readinessLaneLabel(route, builtIn),
+    layer: route.layer,
+    gtmLayers: gtmLayersForRoute(route),
+    provider: route.provider,
+    toolName: route.toolName,
+    mode: route.mode ?? "if_available",
+    builtIn,
+    approvalRequired: route.approvalRequired === true || plan.approvals.some((approval) => approval.routeId === route.id),
+    customRoute,
+    readOnlySetup,
+    ready: blockers.length === 0,
+    blockers,
+    nextAction: customRoute ? `Review ${route.provider} route setup before launch approval.` : void 0
+  };
+}
+function campaignBuilderBuiltInForRoute(route) {
+  return Object.entries(CAMPAIGN_BUILDER_BUILT_IN_ROUTE_IDS).find(([, routeId]) => route.id === routeId)?.[0];
+}
+function readinessLaneLabel(route, builtIn) {
+  if (builtIn) {
+    const labels = {
+      lead_generation: "Signaliz lead generation",
+      local_leads: "Signaliz local leads",
+      email_finding: "Signaliz email finding",
+      email_verification: "Signaliz email verification",
+      signals: "Signaliz signals"
+    };
+    return labels[builtIn];
+  }
+  return `${route.provider} ${route.layer}`;
+}
+function campaignReadinessNextActions(plan, ready, customRouteCount) {
+  const requestHint = "--request-file campaign-request.json";
+  if (ready) {
+    return [
+      `signaliz campaign-agent proof ${requestHint} --json`,
+      `signaliz campaign-agent commit-plan ${requestHint} --json`,
+      `signaliz campaign-agent build-approved ${requestHint} --confirm-launch --approve-all --approved-by operator@example.com --spend-limit ${plan.estimatedCredits}`
+    ];
+  }
+  const actions = [
+    plan.strategyMemoryStatus && asRecord(plan.strategyMemoryStatus).ready === false ? "signaliz gtm strategy-memory --strategy-template <strategy_template> --include-samples --json" : void 0,
+    customRouteCount > 0 ? "Review BYO provider recipe and route dry-run steps in the readiness packet." : void 0,
+    `signaliz campaign-agent plan ${requestHint} --json`
+  ];
+  return actions.filter((item) => Boolean(item));
+}
 function diagnosticMessages2(value) {
   if (!Array.isArray(value)) return [];
   return value.map((item) => {
@@ -6311,6 +6595,7 @@ export {
   CAMPAIGN_BUILDER_STRATEGY_TEMPLATES,
   CampaignBuilderAgent,
   createCampaignBuilderAgentPlan,
+  createCampaignBuilderReadiness,
   getMissingCampaignBuilderApprovals,
   createCampaignBuilderApproval,
   getCampaignBuilderStrategyTemplate,