@signaliz/sdk 1.0.16 → 1.0.17

package/README.md

@@ -27,6 +27,47 @@ integration, and approval primitives exposed through MCP and CLI.
 npm install @signaliz/sdk
 ```
 
+## 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
 
 Build a targeted lead list, wait for completion, then retrieve rows and CSV:
@@ -378,6 +419,54 @@ if (preview.ready_for_confirmation) {
 }
 ```
 
+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
@@ -407,15 +496,34 @@ const health = await signaliz.getPlatformHealth();
 const tools = await signaliz.listTools();
 const opsMatches = await signaliz.discover('campaign build with webhook delivery', 'ops');
 
-// Prompt-first Ops loop
+// 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',
 );
-const op = await signaliz.ops.create({
+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,
+  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);
@@ -442,24 +550,19 @@ 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.
+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({
-  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);
+console.log(result.model, result.results);
 ```
 
 ## Campaigns API