@signaliz/sdk 1.0.1 → 1.0.4

package/README.md

@@ -2,32 +2,390 @@
 
 The official Signaliz SDK for JavaScript/TypeScript — GTM intelligence for AI agents.
 
+Current surfaces include the GTM Kernel, Campaign Builder, provider routing,
+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
 npm install @signaliz/sdk
 ```
 
-## Quick Start
+## Quick Start — Campaign Builder
+
+Build a targeted lead list, wait for completion, then retrieve rows and CSV:
 
 ```typescript
 import { Signaliz } from '@signaliz/sdk';
 
-const signaliz = new Signaliz({
-  apiKey: process.env.SIGNALIZ_API_KEY,
+const signaliz = new Signaliz({ apiKey: process.env.SIGNALIZ_API_KEY });
+
+// 1. Start a campaign build
+const { campaignBuildId } = await signaliz.campaigns.build({
+  name: 'Q3 SaaS Outbound',
+  prompt: 'Series A-C SaaS companies in fintech hiring SDRs',
+  targetCount: 500,
+  confirmSpend: true,
+  delivery: { destinationType: 'csv' },
+});
+
+// 2. Wait for completion with progress updates
+const final = await signaliz.campaigns.wait(campaignBuildId, {
+  onProgress: (s) => console.log(`${s.recordsProcessed}/${s.recordsTotal} rows`),
+});
+
+// 3. Retrieve structured rows
+const { rows } = await signaliz.campaigns.rows(campaignBuildId, { limit: 100 });
+rows.forEach((r) => console.log(r.data.email, r.data.company_name));
+
+// 4. Download CSV artifact
+const artifacts = await signaliz.campaigns.artifacts(campaignBuildId);
+const csv = artifacts.find((a) => a.artifactType === 'csv');
+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.
+
+## 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.
+
+```typescript
+const context = await signaliz.gtm.context({
+  includeCampaigns: true,
+  includeMemory: true,
+  includeBrain: true,
+  includeConnections: true,
+});
+
+const campaign = await signaliz.gtm.createCampaign({
+  name: 'Series B Engineering Leaders',
+  targetIcp: { personas: ['VP Engineering'], segment: 'Series B SaaS' },
+  leadListRefs: [{ source: 'signaliz_cache' }],
+  sendConfig: { daily_cap: 50 },
+  providerLinks: [{ provider: 'instantly', providerCampaignId: 'instantly_123' }],
+});
+
+const seed = await signaliz.gtm.seedBrainDefaults({
+  campaignId: campaign.campaign?.id,
+  campaignBrief: 'Heads of engineering at Series B SaaS',
+  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,
+  dimensions: ['provider_chain', 'icp_shape', 'copy_pattern'],
+  days: 90,
+});
+
+const aggregate = await signaliz.gtm.aggregateBrainPatterns({
+  patternTypes: ['icp', 'provider_chain', 'failure'],
+  minWorkspaceCount: 3,
+  minPrivacyK: 20,
+  dryRun: true,
+});
+
+const calibrationAggregate = await signaliz.gtm.aggregateBrainCalibrations({
+  dimensionTypes: ['email_domain', 'verification_source', 'provider_chain'],
+  minWorkspaceCount: 3,
+  minPrivacyK: 20,
+  dryRun: true,
+});
+
+const learningCycle = await signaliz.gtm.learningCyclePlan({
+  campaignId: campaign.campaign?.id,
+  campaignBrief: 'Heads of engineering at Series B SaaS',
+  includeNetwork: true,
+  writeMode: 'dry_run',
+});
+
+const campaignLearning = await signaliz.gtm.campaignLearningStatus({
+  campaignId: campaign.campaign?.id,
+  campaignBuildId: campaign.campaign?.campaign_build_id,
+  writeMode: 'dry_run',
+});
+
+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',
+  layerCapabilities: ['find_company', 'find_people', 'lead_generation'],
+  invocationType: 'webhook',
+  authStrategy: 'webhook_secret',
+  endpointUrl: 'https://hooks.example.com/clay',
+  status: 'active',
+});
+
+const routeProof = await signaliz.gtm.previewLayerRoute({
+  layer: 'lead_generation',
+  campaignId: campaign.campaign?.id,
+  sampleRecords: [{ email: 'buyer@example.com' }],
+  context: { source: 'sdk_quickstart' },
+});
+
+console.log(routeProof.next_action);
+console.log(failures.failure_patterns?.[0]?.recommendation?.next_step);
+console.log({ readyLanes: readyLanes.length, networkPolicy: networkLane?.raw_data_policy });
+```
+
+Provider routes can point to Signaliz native tools, Clay webhooks, Airbyte,
+Nango-managed customer APIs, Apollo, AI Ark, Octave, Instantly, HeyReach,
+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
+smoke harness before launching spendful provider work:
+
+```bash
+SIGNALIZ_API_KEY=sk_... node scripts/cmm-kernel-smoke.mjs \
+  --campaign-build-id <campaign_build_id>
+```
+
+The receipt includes campaign/build/workspace IDs, execution stage, feedback and
+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
+
+Fresh-enrichment throughput is now higher across every plan: Free 60/min,
+Builder 300/min, Team 600/min, Agency 1,000/min, and Pay-As-You-Go 1,000/min,
+with a 5,000/hour per-workspace safety cap. Cache hits, API/MCP reads, and
+included standard data do not count against those fresh-enrichment ceilings.
+
+```typescript
+// Workspace and platform health
+const workspace = await signaliz.getWorkspace();
+const health = await signaliz.getPlatformHealth();
+
+// Tool/capability discovery
+const tools = await signaliz.listTools();
+const opsMatches = await signaliz.discover('campaign build with webhook delivery', 'ops');
+
+// Prompt-first Ops loop
+const plan = await signaliz.ops.plan(
+  'Monitor stripe.com and plaid.com every day and Slack me new hiring signals',
+);
+const op = await signaliz.ops.create({
+  prompt: plan.goal,
+  blueprint: plan.blueprint,
+  target_count: plan.target_count,
+  cadence: plan.cadence,
+  confirm_spend: true,
+});
+await signaliz.ops.run(op.op_id);
+const status = await signaliz.ops.status(op.op_id);
+const results = await signaliz.ops.results({ op_id: op.op_id, limit: 100 });
+
+// Spendful lead generation requires explicit approval
+try {
+  await signaliz.leads.generate({
+    prompt: 'VP Sales at B2B SaaS companies, 50-500 employees',
+    maxLeads: 100,
+  });
+} catch (error) {
+  // APPROVAL_REQUIRED includes estimated_credits and retry_arguments in details.
+}
+
+const leadJob = await signaliz.leads.generate({
+  prompt: 'VP Sales at B2B SaaS companies, 50-500 employees',
+  maxLeads: 100,
+  confirmSpend: true,
 });
+const leadStatus = await signaliz.leads.checkStatus(leadJob.jobId);
+```
+
+## Custom AI Enrichment - Multi Model
+
+Use OpenRouter model IDs directly and attach images, PDFs, audio, or video when the selected model supports them. OpenRouter Fusion handles web search/fetch inside the deliberation step, so there is no separate search toggle.
+
+```typescript
+const result = await signaliz.ai.multiModel({
+  model: 'google/gemini-2.5-flash',
+  prompt: 'Research {{company_name}} and score whether they match our ICP.',
+  records: [{ company_name: 'Stripe', company_domain: 'stripe.com' }],
+  outputFields: [
+    { name: 'fit_score', type: 'number', description: 'ICP fit from 1-10' },
+    { name: 'reasoning', type: 'text', description: 'Short evidence-backed rationale' },
+  ],
+  fusion: {
+    analysis_models: ['~google/gemini-flash-latest', '~openai/gpt-latest'],
+    judge_model: '~anthropic/claude-opus-latest',
+  },
+});
+
+console.log(result.results);
+```
+
+## Campaigns API
+
+### `campaigns.build(request, options?)`
+
+Start an async campaign build. Returns immediately with a `campaignBuildId`.
+
+```typescript
+const result = await signaliz.campaigns.build(
+  {
+    name: 'Test',
+    prompt: 'Find CFOs at mid-market healthcare companies',
+    dryRun: true,
+    allowDownscale: true,
+    confirmSpend: true,
+  },
+  { idempotencyKey: 'my-unique-key-123' }  // prevent duplicate builds
+);
+```
+
+When `dryRun: true` is passed, the result is a plan (`status: 'dry_run'`) with
+`campaignBuildId: null`, planned target count, estimated credits, and duration.
 
+### `campaigns.status(id)`
+
+Get a concise status snapshot — ideal for polling.
+
+### `campaigns.get(id)`
+
+Get the full campaign build record including delivery details.
+
+### `campaigns.rows(id, options?)`
+
+Retrieve paginated rows from a completed build.
+
+```typescript
+const page = await signaliz.campaigns.rows(buildId, {
+  limit: 50,
+  segment: 'signal',
+  qualified: true,
+});
+// page.rows, page.nextCursor, page.hasMore
+```
+
+### `campaigns.artifacts(id)`
+
+List all artifacts (CSV exports, signed URLs).
+
+### `campaigns.cancel(id, reason?)`
+
+Cancel a queued or running build.
+
+### `campaigns.wait(id, options?)`
+
+Poll until completed, failed, or canceled.
+
+```typescript
+const final = await signaliz.campaigns.wait(buildId, {
+  intervalMs: 3000,
+  timeoutMs: 300_000,
+  onProgress: (s) => console.log(s.status, s.recordsProcessed),
+});
+```
+
+## Other Resources
+
+```typescript
 // Find and verify an email
 const email = await signaliz.emails.find({
   fullName: 'Jane Smith',
   companyDomain: 'stripe.com',
 });
-console.log(email);
-// → { email: 'jane.smith@stripe.com', verificationStatus: 'valid', confidence: 0.95 }
 
-// Verify an email
-const result = await signaliz.emails.verify('jane@stripe.com');
-// → { isValid: true, isDeliverable: true, isCatchAll: false, confidenceScore: 0.98 }
+// Submit batch email jobs at scale, then poll status
+const job = await signaliz.emails.verifyBatch([
+  'jane@example.com',
+  { email: 'sam@example.com' },
+]);
+const status = await signaliz.emails.checkStatus(job.jobId);
+
+// Local-business lead generation
+const localJob = await signaliz.leads.generateLocal({
+  prompt: 'dentists in Phoenix, AZ',
+  targetVerified: 50,
+  confirmSpend: true,
+});
 
 // Company signals
 const signals = await signaliz.signals.enrich({
@@ -40,28 +398,28 @@ const system = await signaliz.systems.create({
   name: 'Email Pipeline',
   capabilities: ['mcp_input', 'find_emails_with_verification', 'mcp_output'],
 });
-const run = await signaliz.systems.run(system.id, { data: [...] });
-
-// Stream progress
-for await (const event of signaliz.runs.stream(run.runId)) {
-  console.log(`${event.completedRows}/${event.totalRows} — ${event.status}`);
-}
 
 // HTTP proxy
 const response = await signaliz.http.request({
   url: 'https://api.example.com/data',
   method: 'GET',
 });
+
+// Ops routines and output sinks
+const sinks = await signaliz.ops.listOutputSinks();
+const routines = await signaliz.ops.listRoutines({ status: 'active' });
 ```
 
 ## MCP Setup
 
-Connect Signaliz to your AI agent in one command:
-
 ```bash
-npx @signaliz/mcp
+npx -p @signaliz/sdk signaliz-mcp
 ```
 
+The setup helper writes a local stdio MCP config that runs `@signaliz/mcp-server`
+with `SIGNALIZ_API_KEY` in the environment. It does not put API keys in a
+query-string URL.
+
 ## Authentication
 
 ### API Key (simplest)
@@ -83,12 +441,12 @@ const signaliz = new Signaliz({
 import { Signaliz, SignalizError } from '@signaliz/sdk';
 
 try {
-  await signaliz.emails.find({ fullName: 'Test', companyDomain: 'example.com' });
+  await signaliz.campaigns.build({ name: 'Test', prompt: '...' });
 } catch (e) {
   if (e instanceof SignalizError) {
-    console.log(e.errorType);  // 'rate_limited' | 'validation' | 'timeout' | ...
-    console.log(e.retryAfter); // seconds to wait (for 429s)
-    console.log(e.isRetryable); // boolean
+    console.log(e.errorType);   // 'rate_limited' | 'validation' | 'timeout' | ...
+    console.log(e.retryAfter);  // seconds to wait (for 429s)
+    console.log(e.isRetryable); // boolean — SDK retries 429 and 5xx automatically
   }
 }
 ```