@signaliz/sdk 1.0.61 → 1.0.63

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',
@@ -111,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, {
@@ -140,21 +159,36 @@ 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 and Verify Email polling defaults to 20 minutes; large email batches
+honor `maxWaitMs` and `pollIntervalMs` and retain the same 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
@@ -165,7 +199,7 @@ 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
+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.
@@ -181,10 +215,12 @@ 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. 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
+while fresh discovery or verification is charged on every plan. Builder, Team,
+Agency, and Pay-As-You-Go include fresh Company Signals. Team and Agency also
+include Unlimited Signal to Copy AI; Signal to Copy remains callable on other
+plans under the standard product contract. These 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.