@signaliz/sdk 1.0.6 → 1.0.8

package/README.md

@@ -62,6 +62,93 @@ console.log('Download:', csv?.signedUrl);
 
 > **Downstream routing:** Signaliz outputs JSON, CSV, and webhook. Your agent routes rows to CRMs, outreach tools, or warehouses using their own APIs/MCPs.
 
+## Campaign Builder Agent
+
+Use `campaignBuilderAgent` when application code should compose the same
+strategy-template MCP flow exposed in the CLI: strategy-memory readiness,
+Signaliz-native sourcing, email finding, verification, signals, Brain risk, and
+BYO tool routes.
+
+```typescript
+const plan = await signaliz.campaignBuilderAgent.createPlan({
+  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'],
+  integrations: [{
+    provider: 'workspace_mcp',
+    layer: 'enrichment',
+    gtmLayers: ['company_enrichment'],
+    toolName: 'account_enrich',
+    mcpServerName: 'workspace-mcp',
+    mode: 'required',
+    approvalRequired: true,
+  }],
+  agencyContext: {
+    strategyModel: 'strategy_template',
+    includeStrategyPatterns: true,
+    includeWorkflowPatterns: true,
+    includeNangoCatalog: true,
+  },
+});
+
+const dryRun = await signaliz.campaignBuilderAgent.dryRunPlan(plan);
+
+console.log(plan.strategyMemoryStatus?.ready);
+console.log(plan.mcpFlow.filter((step) =>
+  ['gtm_provider_recipe_prepare', 'gtm_provider_route_activate'].includes(step.tool)
+));
+```
+
+The CLI can run the same request shape from a reusable JSON file, with flags
+overriding file fields:
+
+```bash
+npx @signaliz/sdk campaign-agent init \
+  --strategy-template non-medical-home-care \
+  --target-count 250 \
+  --use-local-leads \
+  --with-byo-placeholder \
+  --output-file campaign-request.json
+
+npx @signaliz/sdk campaign-agent plan \
+  --request-file campaign-request.json \
+  --target-count 250 \
+  --json
+```
+
+Use the hosted MCP campaign-agent planner when you want Signaliz to return the
+same strategy-template runbook exposed through MCP:
+
+```typescript
+const memoryStatus = await signaliz.gtm.campaignStrategyMemoryStatus({
+  strategyTemplate: 'non-medical-home-care',
+  includeSamples: true,
+});
+
+const hostedTemplate = await signaliz.gtm.campaignAgentRequestTemplate({
+  goal: 'Build a reusable strategy-template campaign request',
+  strategyTemplate: 'non-medical-home-care',
+  targetCount: 250,
+  includeLocalLeads: true,
+  includeByoPlaceholder: true,
+  privacyMode: 'workspace_only',
+});
+
+const hostedPlan = await signaliz.gtm.campaignAgentPlan({
+  goal: 'Build a strategy-template campaign for local operators',
+  strategyTemplate: 'non-medical-home-care',
+  targetCount: 500,
+  builtIns: ['lead_generation', 'local_leads', 'email_finding', 'email_verification', 'signals'],
+  customTools: [{
+    provider: 'workspace_mcp',
+    layer: 'enrichment',
+    tool: 'account_enrich',
+    mcp: 'workspace-mcp',
+  }],
+});
+```
+
 ## GTM Kernel + Brain
 
 Use `signaliz.gtm` when an agent needs the substrate directly: workspace context, first-class campaign objects, ranked memory, Brain patterns/defaults, and provider routes.
@@ -177,11 +264,18 @@ connection reference and approval/audit context.
 ### Nango-Managed API Tools
 
 Use Nango when a workspace brings its own provider account and the action should
-run through Nango-managed auth. Start by listing available tools for the saved
-workspace connection, dry-run the action, then confirm the write only after the
-preview is approved.
+run through Nango-managed auth. If the vendor is not connected yet, create a
+Connect session and send the user to the returned auth link. Then list tools for
+the saved workspace connection, dry-run the action, and confirm the write only
+after the preview is approved.
 
 ```typescript
+const session = await signaliz.gtm.createNangoConnectSession({
+  providerId: 'apollo',
+  integrationId: 'apollo',
+});
+console.log(session.connect_link);
+
 const tools = await signaliz.gtm.listNangoTools({
   workspaceConnectionId: 'workspace_conn_nango_hubspot',
   providerConfigKey: 'hubspot',
@@ -217,13 +311,11 @@ if (preview.ready_for_confirmation) {
 
 ### GTM Kernel Smoke Test
 
-After CMM imports or Campaign Builder backfills, run the read-only/dry-run
+After strategy imports or Campaign Builder backfills, run the read-only/dry-run
 smoke harness before launching spendful provider work:
 
-```bash
-SIGNALIZ_API_KEY=sk_... node scripts/cmm-kernel-smoke.mjs \
-  --campaign-build-id <campaign_build_id>
-```
+Run the internal smoke harness with `SIGNALIZ_API_KEY` and
+`--campaign-build-id <campaign_build_id>` or `--campaign-id <campaign_id>`.
 
 The receipt includes campaign/build/workspace IDs, execution stage, feedback and
 memory counts, workspace bootstrap gate readiness, Brain phase readiness,