@signaliz/sdk 1.0.21 → 1.0.23

package/README.md

@@ -1,732 +1,67 @@
 # @signaliz/sdk
 
-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.
-Builder includes unlimited cache search, Campaign Builder, API, MCP, CLI, Ops,
-and integrations. Team is the $499/month public plan and adds unlimited live
-Find People and Find Companies in Signaliz; Agency stays $999/month with higher
-credits and throughput.
-
-## 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
+Typed JavaScript/TypeScript access to the four Signaliz products.
 
 ```bash
 npm install @signaliz/sdk
 ```
 
-## Production REST Endpoints
-
-- Find Email: `https://api.signaliz.com/functions/v1/find-verified-email-v2`
-- Email Verification: `https://api.signaliz.com/functions/v1/email-verification-2`
-- Company Signal Enrichment: `https://api.signaliz.com/functions/v1/company-signal-enrichment-v2`
-- Signal to Copy: `https://api.signaliz.com/functions/v1/api/v1/signal-to-copy`
-
-## Quick Start - Ops
-
-Use Ops when a script or agent needs to turn a plain-English GTM outcome into
-durable work, wait for completion, and retrieve rows in one flow.
-
-```typescript
-import { Signaliz } from '@signaliz/sdk';
-
-const signaliz = new Signaliz({ apiKey: process.env.SIGNALIZ_API_KEY });
-
-const result = await signaliz.ops.executeAndWait({
-  prompt: 'Build 50 approved ICP leads and return reviewed rows',
-  targetCount: 50,
-  confirmSpend: true,
-  limit: 50,
-});
-
-console.log(result.status.status);
-console.log(result.results?.results);
-```
-
-If the Op already exists, queue it and wait for results with `runAndWait()`:
-
-```typescript
-const run = await signaliz.ops.runAndWait({
-  opId: 'op_123',
-  limit: 100,
-});
-```
-
-For manual polling or partial-output recovery, use `waitForResults()` directly:
-
-```typescript
-const waited = await signaliz.ops.waitForResults({
-  opId: 'op_123',
-  maxPolls: 60,
-  intervalMs: 5000,
-  includeFailedRuns: true,
-});
-```
-
-## Quick Start — Campaign Builder
+Production REST endpoints:
 
-Build a targeted lead list, wait for completion, then retrieve rows and CSV:
+- `https://api.signaliz.com/functions/v1/api/v1/find-email`
+- `https://api.signaliz.com/functions/v1/api/v1/verify-email`
+- `https://api.signaliz.com/functions/v1/api/v1/company-signals`
+- `https://api.signaliz.com/functions/v1/api/v1/signal-to-copy`
 
-```typescript
+```ts
 import { Signaliz } from '@signaliz/sdk';
 
-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.
-
-## 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);
-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'],
-});
-const proof = await signaliz.campaignBuilderAgent.proof({
-  goal: 'Build a strategy-template campaign for mature local operators',
-  strategyTemplate: 'non-medical-home-care',
-  targetCount: 25,
-  builtIns: ['lead_generation', 'local_leads', 'email_finding', 'email_verification', 'signals'],
-});
-const kit = signaliz.campaignBuilderAgent.buildKit({
-  goal: 'Build a strategy-template campaign for mature local operators',
-  strategyTemplate: 'non-medical-home-care',
-  targetCount: 250,
-  includeLocalLeads: true,
-  includeCustomToolPlaceholder: true,
-});
-const memoryKit = signaliz.campaignBuilderAgent.memoryKit({
-  goal: 'Build a strategy-template campaign for mature local operators',
-  strategyTemplate: 'non-medical-home-care',
-  targetCount: 250,
-  includeLocalLeads: true,
-  source: 'agency',
-});
-
-console.log(plan.strategyMemoryStatus?.ready);
-console.log(readiness.summary.ready);
-console.log(proof.success);
-console.log(kit.mcp_calls.find((call) => call.tool === 'gtm_campaign_agent_proof'));
-console.log(memoryKit.mcp_calls.find((call) => call.tool === 'gtm_campaign_strategy_memory_status'));
-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
-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 kit \
-  --strategy-template non-medical-home-care \
-  --target-count 250 \
-  --use-local-leads \
-  --with-byo-placeholder \
-  --json
-
-npx @signaliz/sdk campaign-agent memory-kit \
-  --strategy-template non-medical-home-care \
-  --target-count 250 \
-  --use-local-leads \
-  --source agency \
-  --json
-
-npx @signaliz/sdk campaign-agent plan \
-  --request-file campaign-request.json \
-  --target-count 250 \
-  --json
-
-npx @signaliz/sdk campaign-agent doctor \
-  --request-file campaign-request.json \
-  --json
-
-npx @signaliz/cli build "Build a strategy-template campaign for local operators" \
-  --strategy-template non-medical-home-care \
-  --target-count 25 \
-  --use-local-leads
-
-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
-```
-
-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.
-
-```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. 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',
-  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,
-    });
-  }
-}
-```
-
-The Ops namespace exposes the same Nango bridge, plus a one-call helper backed
-by `nango_mcp_tool_call_and_wait` when an agent needs the result packet
-immediately:
-
-```typescript
-const nangoResult = await signaliz.ops.callNangoToolAndWait({
-  workspaceConnectionId: 'workspace_conn_nango_hubspot',
-  actionName: 'upsert-contact',
-  input: { email: 'buyer@example.com', company: 'Acme' },
-  dryRun: false,
-  confirm: true,
-  maxPolls: 6,
-});
-console.log(nangoResult.result);
-```
-
-For recurring Ops, use the schedule-and-wait helper to activate the Op and
-retrieve the first result packet in one call. This maps to native MCP
-`ops_schedule_and_wait`:
-
-```typescript
-const recurring = await signaliz.ops.scheduleAndWait({
-  prompt: 'Monitor strategic accounts daily and send new funding signals to Slack',
-  destinations: [{ type: 'slack' }],
-  wakeOnEvents: ['company_funded'],
-  confirmSpend: true,
-  limit: 100,
-});
-console.log(recurring.results?.results);
-```
-
-For Nango-backed recurrence, the Ops SDK sends the natural Nango fields through
-native `ops_nango_schedule` / `ops_nango_schedule_and_wait`:
-
-```typescript
-const hubspotOp = await signaliz.ops.scheduleNangoActionAndWait({
-  prompt: 'Monitor strategic accounts daily and upsert approved rows to HubSpot',
-  workspaceConnectionId: 'workspace_conn_nango_hubspot',
-  providerConfigKey: 'hubspot',
-  actionName: 'upsert-contact',
-  writeConfirmed: true,
-  confirmSpend: true,
-  maxPolls: 6,
-  limit: 100,
-});
-console.log(hubspotOp.results?.results);
-```
-
-### GTM Kernel Smoke Test
-
-After strategy imports or Campaign Builder backfills, run the read-only/dry-run
-smoke harness before launching spendful provider work:
-
-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,
-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
-cache search 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');
-
-// North-star Ops loop: recommend, dry-run, schedule/run, poll, retrieve
-const autopilot = await signaliz.ops.autopilot();
-console.log(autopilot.primaryMotion?.operatingPacket?.northStar);
-console.log(autopilot.primaryMotion?.operatingPacket?.nangoRoute?.dryRunArguments);
-
-const plan = await signaliz.ops.plan(
-  'Monitor stripe.com and plaid.com every day and Slack me new hiring signals',
-);
-console.log(plan.executionContract?.sequence.map((step) => step.tool).join(' -> '));
-console.log(plan.executionContract?.nangoRoute?.writeGate);
-const nangoPreview = await signaliz.ops.execute({
-  prompt: 'Build 50 approved ICP leads and upsert them to HubSpot',
-  destinations: [{
-    type: 'nango',
-    connectionId: 'workspace_conn_nango_hubspot',
-    providerConfigKey: 'hubspot',
-    nangoConnectionId: 'connection_123',
-    actionName: 'upsert-contact',
-  }],
-  dry_run: true,
-});
-const op = await signaliz.ops.schedule({
-  prompt: plan.goal,
-  blueprint: plan.blueprint,
-  target_count: plan.target_count,
-  cadence: plan.cadence === 'manual' ? 'daily' : plan.cadence,
-  timezone: 'America/Phoenix',
-  wakeOnEvents: ['company_funded', 'crm.updated'],
-  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 the Signaliz-hosted default model and attach images, PDFs, audio, or video when needed. The response includes model readback metadata for auditing.
-
-```typescript
-const result = await signaliz.ai.multiModel({
-  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' },
-  ],
-});
-
-console.log(result.model, 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 with the V3 waterfall
-const email = await signaliz.emails.find({
-  fullName: 'Jane Smith',
-  companyDomain: 'stripe.com',
+const signaliz = new Signaliz({
+  apiKey: process.env.SIGNALIZ_API_KEY,
 });
 
-// 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,
+const found = await signaliz.findEmail({
+  companyDomain: 'example.com',
+  fullName: 'Jane Doe',
+  // Optional: bypass cached email and verification data for a fresh-provider run.
+  skipCache: true,
 });
 
-// Company signals
-const signals = await signaliz.signals.enrich({
-  companyName: 'Stripe',
-  researchPrompt: 'Find recent hiring activities',
-});
+const verified = await signaliz.verifyEmail(found.email!);
 
-// Systems (pipelines)
-const system = await signaliz.systems.create({
-  name: 'Email Pipeline',
-  capabilities: ['mcp_input', 'find_emails_with_verification', 'mcp_output'],
+const signals = await signaliz.enrichCompanySignals({
+  companyDomain: 'example.com',
+  researchPrompt: 'expansion priorities',
 });
 
-// HTTP proxy
-const response = await signaliz.http.request({
-  url: 'https://api.example.com/data',
-  method: 'GET',
+const copy = await signaliz.signalToCopy({
+  companyDomain: 'example.com',
+  personName: 'Jane Doe',
+  title: 'VP Sales',
+  campaignOffer: 'pipeline intelligence',
+  researchPrompt: 'expansion priorities',
 });
-
-// Ops routines and output sinks
-const sinks = await signaliz.ops.listOutputSinks();
-const routines = await signaliz.ops.listRoutines({ status: 'active' });
-```
-
-## MCP Setup
-
-```bash
-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.
+All four products support bounded batch execution over the same REST endpoints.
+Results stay in input order, failures are isolated per item, and concurrency is
+limited to `1-50` (default `10`):
 
-## Authentication
-
-### API Key (simplest)
-```typescript
-const signaliz = new Signaliz({ apiKey: 'sk_...' });
+```ts
+const verifiedBatch = await signaliz.verifyEmails(emails, { concurrency: 20 });
+const foundBatch = await signaliz.findEmails(contacts, { concurrency: 20 });
+const signalBatch = await signaliz.enrichCompanies(companies, { concurrency: 5 });
+const copyBatch = await signaliz.createSignalCopyBatch(copyRequests, { concurrency: 5 });
 ```
 
-### M2M OAuth
-```typescript
-const signaliz = new Signaliz({
-  clientId: process.env.SIGNALIZ_CLIENT_ID,
-  clientSecret: process.env.SIGNALIZ_CLIENT_SECRET,
-});
-```
-
-## Error Handling
-
-```typescript
-import { Signaliz, SignalizError } from '@signaliz/sdk';
-
-try {
-  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 — SDK retries 429 and 5xx automatically
-  }
-}
-```
+Each batch accepts up to 5,000 items. Company Signal Enrichment transparently
+resumes long-running research through the same `/company-signals` endpoint;
+callers never need an internal Trigger.dev status URL.
 
-## License
+Company Signal Enrichment defaults `online` and `enableDeepSearch` to `true`
+unless the caller explicitly disables them. Signal to Copy AI returns three
+complete, evidence-backed email variations when supported signals are available.
+Unclassified evidence is returned by signal enrichment but is not used to
+generate outreach copy.
 
-MIT
+`listTools()` and `health()` are connection helpers, not additional products.