@signaliz/sdk 1.0.60 → 1.0.62

package/README.md

@@ -58,6 +58,11 @@ const resumedVerification = await signaliz.verifyEmail('jane@example.com', {
   verificationRunId: queuedVerification.verificationRunId,
 });
 
+// Recovery is zero-current-spend. When the original provider call had a
+// receipt, Find Email and Verify Email retain it separately for audit.
+console.log(resumedVerification.billingMetadata?.result_returned_from); // run_recovery
+console.log(resumedVerification.historicalBillingMetadata?.result_returned_from);
+
 const signals = await signaliz.enrichCompanySignals({
   companyDomain: 'example.com',
   researchPrompt: 'expansion priorities',
@@ -73,6 +78,12 @@ const signalDiscovery = await signaliz.discoverSignals({
   limit: 100,
   sources: ['web', 'news'],
 });
+const painSignalDiscovery = await signaliz.discoverSignals({
+  query: 'companies showing signals they need account-signal automation',
+  icpContext: 'B2B SaaS companies with outbound sales teams and manual account research',
+  limit: 100,
+  sources: ['web', 'news'],
+});
 const completedDiscovery = signalDiscovery.signalSearchRunId
   ? await signaliz.discoverSignals({ signalSearchRunId: signalDiscovery.signalSearchRunId })
   : signalDiscovery;
@@ -105,6 +116,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 });
 
+// If a timeout or interrupted client returns a durable job ID, resume only
+// that job. These methods never submit `requests` or repeat provider work.
+const resumedFoundBatch = await signaliz.resumeFindEmailBatch('job_...');
+const resumedVerifiedBatch = await signaliz.resumeVerifyEmailBatch('job_...');
+const resumedSignalBatch = await signaliz.resumeCompanySignalBatch('job_...');
+const resumedCopyBatch = await signaliz.resumeSignalCopyBatch('job_...');
+
+// Long Company/Copy batches can return immediately with the actual durable
+// job ID and idempotency key. Persist both before yielding the agent turn.
+const signalJob = await signaliz.enrichCompanies(companies, {
+  waitForResult: false,
+});
+// { jobId, idempotencyKey, status, total, ... }
+
 // Keep one full result for exact repeats and return duplicateOf references for
 // the rest. This is lossless and avoids multiplying evidence-rich payloads.
 const compactSignals = await signaliz.enrichCompanies(companies, {
@@ -134,32 +159,48 @@ SDK, and CLI calls for the same workspace and logical input. Chunked batches
 derive a stable key from each row's original input index, including after exact
 duplicate compaction and rate-limit retries.
 
-Each batch accepts up to 5,000 items. For the four row-oriented core products, batches larger
-than 25 use one recoverable REST job; the SDK waits for completion and retrieves
-every result page before returning, so callers never receive queued work or
-polling instructions. Find Email, Verify Email, and Signal to Copy use 500-row
-result pages, while Company Signals uses 25-row result pages.
+Each batch accepts up to 5,000 items. For the four row-oriented core products,
+batches larger than 25 use one recoverable REST job. The SDK waits by default
+and retrieves every result page. Large Company Signals and Signal to Copy calls
+can instead set `waitForResult: false` to receive `jobId` plus the actual
+`idempotencyKey`, then resume with `resumeCompanySignalBatch` or
+`resumeSignalCopyBatch`. Company/Copy polling has no fixed SDK deadline unless
+`maxWaitMs` is explicitly supplied; timeout errors retain both recovery fields.
+Find Email, Verify Email, and Company Signals use bounded 25-row result pages;
+Signal to Copy uses 100-row durable pages.
+Retrieve completed Company/Copy pages within seven days. After cleanup, recovery
+fails with non-retryable `BATCH_RESULTS_EXPIRED`; do not automatically resubmit
+provider work, and require an explicit review before starting a new job.
 Company Signal `signal_run_id` recovery rows remain direct batches of at most
 25, matching the recovery-read API contract instead of starting a new durable
 research job.
-Exact duplicate tasks are single-flighted across each full batch without
-changing input order or result cardinality. Set `compactDuplicates: true` to
-return repeated successful rows as `duplicateOf` references to the zero-based
-canonical input index; the default remains expanded for compatibility. Signal
-to Copy durable jobs use available company-signal data only. If any copy row
-explicitly requests `skipCache` or `enableDeepSearch`, the SDK preserves that
-fresh-research behavior by using synchronous client-side chunks of at most 25.
+Large Company Signal jobs persist bounded result pages and intentionally omit
+rejected candidate-evidence diagnostics. Requests with
+`includeCandidateEvidence: true` must be split into batches of at most 25.
+Exact duplicate tasks are single-flighted for synchronous batches. Durable
+Company/Copy submissions preserve every input row and its index so the server's
+idempotency identity remains stable across REST, MCP, SDK, and CLI recovery.
+Set `compactDuplicates: true` to return repeated successful rows as
+`duplicateOf` references; the default remains expanded for compatibility.
+Signal to Copy durable jobs use persisted, eligible company-signal data only
+and never start live providers or deep research. Rows without qualifying
+evidence return the terminal row error `SIGNAL_DATA_REQUIRED`. Batches larger
+than 25 reject fresh/deep/synchronous row controls before HTTP; callers must
+split explicitly fresh requests into batches of at most 25.
 Signal to Copy also shares company research across copy recipients.
 
 Signals Everything is query-first rather than a row batch. It defaults to 100
 distinct companies and supports up to 1,000. Every returned signal contains a
 company name, company domain, dated evidence, and a source URL. The typed
-`costGuardrail` reports both projected and observed source acquisition cost;
+`costGuardrail` reports projected and observed source acquisition cost plus
+identity-resolution cost, receipt source, and fallback-provider request count;
 Signaliz returns signals only when cost stays strictly below $0.01 per qualified
 company. A request is a ceiling, not a promise: it can return fewer results
 when public evidence cannot verify both a date and company identity. It is
-included on Team and Agency plans and can be resumed with
-`signalSearchRunId` without duplicate source acquisition.
+included on Builder, Team, and Agency plans and can be resumed with
+`signalSearchRunId` without duplicate source acquisition. Pass `icpContext` to
+ground an open-ended request such as “companies showing signals they need our
+product” in the user's target market.
 
 Company Signal Enrichment defaults `online` and `enableDeepSearch` to `true`
 unless the caller explicitly disables them. Its `searchMode` defaults to
@@ -170,6 +211,13 @@ complete, evidence-backed email variations when supported signals are available.
 Signal to Copy is cache-first and defaults `enableDeepSearch` to `false` so it
 normally finishes within an agent turn; set `skipCache` or `enableDeepSearch`
 only when fresh or deeper research is required.
+Every core request uses the authenticated workspace. Find Email and Verify Email
+honor that workspace's configured cache window; eligible hits cost 0 credits,
+while fresh discovery or verification is charged on every plan. Builder, Team,
+Agency, and Pay-As-You-Go include fresh Company Signals and Signal to Copy. Those plans
+still check eligible workspace signal data first even when Company Signals is
+set to No cache. `lookbackDays` remains a hard evidence-age bound for both
+cached and fresh Company Signals and Signal to Copy results.
 Unclassified evidence is returned by signal enrichment but is not used to
 generate outreach copy.
 Each normalized signal keeps `date` separate from crawl-time `detectedAt` and