@signaliz/sdk 1.0.3 → 1.0.5

package/README.md

@@ -7,6 +7,20 @@ Nango-managed customer API connections, MCP/Ops control-plane methods, and
 enrichment primitives. Available data is returned before fresh enrichment;
 live email verification is 0.02 fresh enrichment credits when a new verification is needed.
 
+## Which Surface Should I Use?
+
+Signaliz is the GTM brain over any stack. The SDK is for application code,
+scripts, and agent runtimes that need typed access to the same GTM Kernel, Ops,
+integration, and approval primitives exposed through MCP and CLI.
+
+- Use MCP or Codex when an agent should reason, choose tools, and build or audit
+  a campaign from a plain-English goal.
+- Use the CLI when a human operator or local agent needs a repeatable command,
+  JSON receipt, readiness check, or debug trail. Start with `signaliz start`.
+- Use the SDK when product code or automation needs typed methods.
+- Use the UI as the human cockpit to inspect state, connect tools, approve gated
+  actions, and monitor results.
+
 ## Installation
 
 ```bash
@@ -74,6 +88,12 @@ const seed = await signaliz.gtm.seedBrainDefaults({
   layers: ['icp', 'lead_generation', 'copy_enrichment'],
   includeGlobal: true,
 });
+console.log({
+  workspacePatterns: seed.seed?.evidence?.workspace_pattern_count,
+  networkPatterns: seed.seed?.evidence?.global_pattern_count,
+  activeRoutes: seed.seed?.recommended_defaults?.provider_strategy?.active_layer_routes?.length ?? 0,
+  privacyPolicy: seed.privacy_policy,
+});
 
 const failures = await signaliz.gtm.failurePatterns({
   campaignId: campaign.campaign?.id,
@@ -111,6 +131,21 @@ const campaignLearning = await signaliz.gtm.campaignLearningStatus({
 const readyLanes = campaignLearning.learning_lanes?.filter((lane) => lane.state === 'ready') ?? [];
 const networkLane = campaignLearning.learning_lanes?.find((lane) => lane.id === 'network_patterns');
 
+const memory = await signaliz.gtm.searchMemory({
+  query: 'subject lines that worked for SaaS engineering leaders',
+  outcomeType: 'meeting_booked',
+  targetIcp: { persona: 'Head of Engineering', segment: 'Series B SaaS' },
+  layers: ['copy_enrichment', 'sender'],
+  limit: 5,
+});
+const topMemory = memory.memories?.[0];
+console.log({
+  title: topMemory?.title,
+  outcomeClass: Array.isArray(topMemory?.match_reasons) ? undefined : topMemory?.match_reasons?.outcome_class,
+  requestedOutcomeMatch: Array.isArray(topMemory?.match_reasons) ? false : topMemory?.match_reasons?.requested_outcome_match,
+  outcomeScore: Array.isArray(topMemory?.match_reasons) ? undefined : topMemory?.match_reasons?.outcome_score,
+});
+
 await signaliz.gtm.createIntegrationRecipe({
   providerId: 'clay_webhook',
   providerName: 'Clay Webhook',
@@ -139,6 +174,47 @@ Smartlead, custom APIs, custom MCP servers, or manual review gates. Nango routes
 keep customer credentials in Nango while Signaliz stores only the workspace
 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.
+
+```typescript
+const tools = await signaliz.gtm.listNangoTools({
+  workspaceConnectionId: 'workspace_conn_nango_hubspot',
+  providerConfigKey: 'hubspot',
+  includeRaw: false,
+});
+
+const preview = await signaliz.gtm.callNangoTool({
+  workspaceConnectionId: 'workspace_conn_nango_hubspot',
+  actionName: 'upsert-contact',
+  input: { email: 'buyer@example.com', company: 'Acme' },
+  dryRun: true,
+  confirm: false,
+});
+
+if (preview.ready_for_confirmation) {
+  const confirmed = await signaliz.gtm.callNangoTool({
+    workspaceConnectionId: 'workspace_conn_nango_hubspot',
+    actionName: 'upsert-contact',
+    input: { email: 'buyer@example.com', company: 'Acme' },
+    dryRun: false,
+    confirm: true,
+    async: true,
+  });
+
+  if (confirmed.action_id || confirmed.status_url) {
+    await signaliz.gtm.getNangoActionResult({
+      actionId: confirmed.action_id,
+      statusUrl: confirmed.status_url,
+    });
+  }
+}
+```
+
 ### GTM Kernel Smoke Test
 
 After CMM imports or Campaign Builder backfills, run the read-only/dry-run
@@ -150,8 +226,9 @@ SIGNALIZ_API_KEY=sk_... node scripts/cmm-kernel-smoke.mjs \
 ```
 
 The receipt includes campaign/build/workspace IDs, execution stage, feedback and
-memory counts, Brain phase readiness, blockers/warnings, the next safe MCP
-action, and explicit no-spend/no-write/no-sender/no-delivery confirmation.
+memory counts, workspace bootstrap gate readiness, Brain phase readiness,
+blockers/warnings, the next safe MCP action, and explicit
+no-spend/no-write/no-sender/no-delivery confirmation.
 
 ## MCP/Ops Control Plane