@signaliz/sdk 1.0.47 → 1.0.49

package/README.md

@@ -59,15 +59,6 @@ const signals = await signaliz.enrichCompanySignals({
 console.log(signals.signals[0].evidencePublishedDate);
 console.log(signals.signals[0].signalFeedSource, signals.signals[0].derived);
 
-// Persist a no-wait run ID and resume it later without duplicate spend.
-const queuedSignals = await signaliz.enrichCompanySignals({
-  companyDomain: 'example.com',
-  waitForResult: false,
-});
-const resumedSignals = await signaliz.enrichCompanySignals({
-  signalRunId: queuedSignals.signalRunId,
-});
-
 const copy = await signaliz.signalToCopy({
   companyDomain: 'example.com',
   personName: 'Jane Doe',
@@ -79,16 +70,8 @@ const copy = await signaliz.signalToCopy({
   enableDeepSearch: false,
 });
 
-// Persist a queued copy ID and resume with that ID alone. Signaliz restores
-// the recipient, title, offer, prompt, and underlying research run.
-const queuedCopy = await signaliz.signalToCopy({
-  companyDomain: 'example.com',
-  personName: 'Jane Doe',
-  title: 'VP Sales',
-  campaignOffer: 'pipeline intelligence',
-  waitForResult: false,
-});
-const resumedCopy = await signaliz.signalToCopy({ signalRunId: queuedCopy.runId });
+// Company Signals and Signal to Copy are hard synchronous contracts: these
+// methods return complete data or throw a terminal error in this same call.
 ```
 
 All four products support bounded batch execution over the same REST endpoints.
@@ -114,36 +97,35 @@ when the REST API supplies them, including after automatic row retries are
 exhausted.
 
 For an ambiguous single request or batch submission failure, retry with the
-same `idempotencyKey` to recover the original request or job without duplicate
+same `idempotencyKey` to recover the original request or supported email job without duplicate
 work.
 
-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. The SDK follows the
-server's adaptive polling hints by default and still honors `pollIntervalMs`
-when a caller explicitly overrides the cadence.
+Each batch accepts up to 5,000 items. For Company Signals and Signal to Copy,
+the SDK chunks inputs into synchronous requests of at most 25 and waits for
+every chunk. It never returns queued work, job IDs, or polling instructions.
 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. Find Email and Verify Email
 batches
 larger than 25 use one cache-aware recoverable REST job with 500-row result
-pages. Uniform Company Signal Enrichment batches larger than 25 use one
-cache-aware recoverable REST job with 25-row result pages; heterogeneous,
-no-wait, and per-run recovery inputs keep the 25-row request path. Signal to
-Copy batches larger than 25 use one recoverable REST job when they can reuse
-available signal data; fresh or deep-search requests keep the 25-row path.
-Signal to Copy also shares company research across copy recipients.
+pages. Company Signal Enrichment and Signal to Copy always use client-side
+25-row chunks with terminal per-row results. Signal to Copy also shares company
+research across copy recipients.
 
 Company Signal Enrichment defaults `online` and `enableDeepSearch` to `true`
-unless the caller explicitly disables them. Signal to Copy AI returns three
+unless the caller explicitly disables them. Its `searchMode` defaults to
+`balanced`; use `fast` for the primary low-latency search lane only or
+`coverage` when breadth matters more than the sub-cent average budget target.
+Signal to Copy AI returns three
 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.
 Unclassified evidence is returned by signal enrichment but is not used to
 generate outreach copy.
-Each normalized signal also exposes `datePrecision`, `sourceProvenance`,
+Each normalized signal keeps `date` separate from crawl-time `detectedAt` and
+also exposes `datePrecision`, `hasSpecificDate`, `sourceProvenance`,
 `entityConfidence`, `classification`, `derived`, `evidencePublishedDate`,
 `signalFeedSource`, and the provider `metadata` needed for integrity audits.
 

package/dist/{chunk-KTWDTUCI.mjs → chunk-KA66GBVZ.mjs}

@@ -457,39 +457,16 @@ var Signaliz = class {
     );
   }
   async enrichCompanySignals(params) {
+    validateCoreProductMaxWaitMs(params.maxWaitMs);
     const request = companySignalRequestBody(params);
-    let data = await this.client.post("api/v1/company-signals", request);
+    const data = await this.client.post("api/v1/company-signals", request);
     if (isCoreProductDryRun(data)) return normalizeCoreProductDryRunResult(data);
-    if (params.waitForResult !== false && data.run_id && isPendingSignalResponse(data)) {
-      const maxWaitMs = Math.max(1e3, params.maxWaitMs ?? 20 * 6e4);
-      const startedAt = Date.now();
-      while (Date.now() - startedAt < maxWaitMs) {
-        if (!await waitForNextSignalPoll(data, params.pollIntervalMs, startedAt, maxWaitMs)) break;
-        const status = await this.client.post("api/v1/company-signals", {
-          ...request,
-          signal_run_id: data.run_id
-        });
-        if (isCompletedSignalRun(status)) {
-          data = status.output ?? status.result ?? status.data ?? status;
-          break;
-        }
-        if (isFailedSignalRun(status)) {
-          throw new Error(`Company signal enrichment ${data.run_id} failed with status ${status.status || "unknown"}`);
-        }
-        if (!isPendingSignalResponse(status)) {
-          data = status.output ?? status.result ?? status.data ?? status;
-          break;
-        }
-        data = status;
-      }
-      if (isPendingSignalResponse(data)) {
-        throw new Error(`Company signal enrichment ${data.run_id} did not complete within ${maxWaitMs}ms`);
-      }
-    }
+    assertTerminalSignalResponse(data, "Company Signals");
     return normalizeCompanySignalResult(params, data);
   }
   async enrichCompanies(companies, options) {
     validateBatchSize(companies);
+    companies.forEach((params) => validateCoreProductMaxWaitMs(params.maxWaitMs));
     if (options?.dryRun === true) {
       return this.runCoreProductDryRun(
         "api/v1/company-signals",
@@ -498,68 +475,22 @@ var Signaliz = class {
       );
     }
     const startedAt = Date.now();
-    const results = new Array(companies.length);
     const initialTasks = companies.map((params, index) => ({
       index,
       request: companySignalRequestBody(params)
     }));
-    const recoverableBatch = companySignalRecoverableBatchOptions(companies, initialTasks);
-    let pending = initialTasks;
-    let firstRound = true;
-    while (pending.length > 0) {
-      const round = await this.runCoreBatchRound(
-        "api/v1/company-signals",
-        pending,
-        options,
-        firstRound ? recoverableBatch : void 0
-      );
-      firstRound = false;
-      const taskByIndex = new Map(pending.map((task) => [task.index, task]));
-      const nextPending = [];
-      let nextDelayMs = 6e4;
-      for (const item of round) {
-        const params = companies[item.index];
-        const task = taskByIndex.get(item.index);
-        if (!item.success || !item.raw) {
-          results[item.index] = batchItemFailure(
-            item.index,
-            item.error || "Company Signal batch request failed",
-            item.raw ?? item
-          );
-          continue;
-        }
-        if (!isPendingSignalResponse(item.raw) || params.waitForResult === false) {
-          results[item.index] = { index: item.index, success: true, data: normalizeCompanySignalResult(params, item.raw) };
-          continue;
-        }
-        const maxWaitMs = Math.max(1e3, params.maxWaitMs ?? 20 * 6e4);
-        if (Date.now() - startedAt >= maxWaitMs) {
-          results[item.index] = {
-            index: item.index,
-            success: false,
-            error: `Company signal enrichment ${item.raw.signal_run_id || item.raw.run_id || ""} did not complete within ${maxWaitMs}ms`
-          };
-          continue;
-        }
-        const signalRunId = item.raw.signal_run_id || item.raw.run_id;
-        if (!signalRunId) {
-          results[item.index] = { index: item.index, success: false, error: "Company signal enrichment is processing without a signal_run_id" };
-          continue;
-        }
-        nextDelayMs = Math.min(
-          nextDelayMs,
-          signalPollDelayMs(item.raw, params.pollIntervalMs),
-          maxWaitMs - (Date.now() - startedAt)
-        );
-        nextPending.push({
-          ...task,
-          request: { ...task.request, signal_run_id: signalRunId }
-        });
+    const round = await this.runCoreBatchRound("api/v1/company-signals", initialTasks, options);
+    const results = round.map((item) => {
+      if (!item.success || !item.raw) {
+        return batchItemFailure(item.index, item.error || "Company Signal batch request failed", item.raw ?? item);
       }
-      if (nextPending.length === 0) break;
-      await sleep2(Math.max(1, nextDelayMs));
-      pending = nextPending;
-    }
+      try {
+        assertTerminalSignalResponse(item.raw, "Company Signals");
+        return { index: item.index, success: true, data: normalizeCompanySignalResult(companies[item.index], item.raw) };
+      } catch (error) {
+        return batchItemFailure(item.index, error instanceof Error ? error.message : String(error), item.raw);
+      }
+    });
     const compactedResults = compactExactDuplicateResults(results, options?.compactDuplicates === true);
     const succeeded = compactedResults.filter((item) => item.success).length;
     return {
@@ -573,21 +504,9 @@ var Signaliz = class {
   async signalToCopy(params) {
     validateSignalToCopyParams(params);
     const request = signalToCopyRequestBody(params);
-    let data = await this.client.post("api/v1/signal-to-copy", request);
+    const data = await this.client.post("api/v1/signal-to-copy", request);
     if (isCoreProductDryRun(data)) return normalizeCoreProductDryRunResult(data);
-    if (params.waitForResult !== false && (data.signal_run_id || data.run_id) && isPendingSignalResponse(data)) {
-      const maxWaitMs = Math.max(1e3, params.maxWaitMs ?? 20 * 6e4);
-      const startedAt = Date.now();
-      while (Date.now() - startedAt < maxWaitMs) {
-        if (!await waitForNextSignalPoll(data, params.pollIntervalMs, startedAt, maxWaitMs)) break;
-        const signalRunId = data.signal_run_id || data.run_id;
-        data = await this.client.post("api/v1/signal-to-copy", data.resume_context_persisted === true ? { signal_run_id: signalRunId } : { ...request, signal_run_id: signalRunId });
-        if (!isPendingSignalResponse(data)) break;
-      }
-      if (isPendingSignalResponse(data)) {
-        throw new Error(`Signal Copy ${data.run_id} did not complete within ${maxWaitMs}ms`);
-      }
-    }
+    assertTerminalSignalResponse(data, "Signal to Copy");
     return normalizeSignalToCopyResult(data);
   }
   async createSignalCopyBatch(requests, options) {
@@ -602,16 +521,10 @@ var Signaliz = class {
     }
     const startedAt = Date.now();
     const deduplicated = dedupeExactBatchItems(requests, (params) => JSON.stringify({
-      request: signalToCopyRequestBody(params),
-      wait_for_result: params.waitForResult,
-      max_wait_ms: params.maxWaitMs,
-      poll_interval_ms: params.pollIntervalMs
+      request: signalToCopyRequestBody(params)
     }));
     const uniqueRequests = deduplicated.uniqueItems;
-    const canUseRecoverableAvailableDataJob = uniqueRequests.length > 25 && uniqueRequests.every(
-      (params) => (!params.signalRunId || !params.signalRunId.startsWith("copy_") && [params.companyDomain, params.personName, params.title, params.campaignOffer].every((value) => typeof value === "string" && Boolean(value.trim()))) && params.waitForResult !== false && params.skipCache !== true && params.enableDeepSearch !== true && params.maxWaitMs === void 0 && params.pollIntervalMs === void 0
-    );
-    const uniqueResults = canUseRecoverableAvailableDataJob ? await this.runAvailableSignalCopyBatchJob(uniqueRequests, options) : await this.runSignalCopyBatchChunks(uniqueRequests, options);
+    const uniqueResults = await this.runSignalCopyBatchChunks(uniqueRequests, options);
     const results = requests.map((_, index) => ({
       ...uniqueResults[deduplicated.sourceIndexByInput[index]],
       index
@@ -667,22 +580,6 @@ var Signaliz = class {
     }
     return uniqueResults;
   }
-  async runAvailableSignalCopyBatchJob(requests, options) {
-    const rows = await this.runRecoverableCoreBatchJob(
-      "api/v1/signal-to-copy",
-      requests.map(signalToCopyRequestBody),
-      "Signal to Copy",
-      500,
-      20 * 6e4,
-      options?.idempotencyKey
-    );
-    const results = new Array(requests.length);
-    for (const row of rows) {
-      const index = Number(row.index);
-      results[index] = recoverableJobRowFailed(row) ? batchItemFailure(index, row.error || row.message || "Signal to Copy failed", row) : { index, success: true, data: normalizeSignalToCopyResult(row) };
-    }
-    return results;
-  }
   async runRecoverableCoreBatchJob(path, requests, label, pageSize = 500, maxWaitMs = 20 * 6e4, idempotencyKey) {
     const startedAt = Date.now();
     const submissionIdempotencyKey = idempotencyKey?.trim() || newBatchIdempotencyKey(label);
@@ -754,77 +651,35 @@ var Signaliz = class {
     return rows;
   }
   async runSignalCopyBatchChunk(requests, concurrency, rowRateLimitAttempt = 0) {
-    const startedAt = Date.now();
     const results = new Array(requests.length);
     const rateLimited = [];
-    let pending = requests.map((params, index) => ({
-      index,
-      params,
-      request: signalToCopyRequestBody(params)
-    }));
-    while (pending.length > 0) {
-      const data = await this.client.post("api/v1/signal-to-copy", {
-        requests: pending.map((item) => item.request),
-        concurrency
-      });
-      if (!Array.isArray(data.results) || data.results.length !== pending.length) {
-        throw new Error("Signal to Copy batch returned an invalid result count");
-      }
-      const nextPending = [];
-      let nextDelayMs = 6e4;
-      for (let index = 0; index < pending.length; index += 1) {
-        const task = pending[index];
-        const item = data.results[index];
-        if (item.success === false) {
-          if (rowRateLimitAttempt < MAX_ROW_RATE_LIMIT_RETRIES && isRetryableRowRateLimit({
-            index: task.index,
-            success: false,
-            raw: item
-          })) {
-            rateLimited.push({ index: task.index, params: task.params, raw: item });
-            continue;
-          }
-          results[task.index] = batchItemFailure(
-            task.index,
-            item.error || item.message || "Signal to Copy failed",
-            item
-          );
-          continue;
-        }
-        if (!isPendingSignalResponse(item)) {
-          results[task.index] = { index: task.index, success: true, data: normalizeSignalToCopyResult(item) };
-          continue;
-        }
-        if (task.params.waitForResult === false) {
-          results[task.index] = { index: task.index, success: true, data: normalizeSignalToCopyResult(item) };
-          continue;
-        }
-        const maxWaitMs = Math.max(1e3, task.params.maxWaitMs ?? 20 * 6e4);
-        if (Date.now() - startedAt >= maxWaitMs) {
-          results[task.index] = {
-            index: task.index,
-            success: false,
-            error: `Signal Copy ${item.signal_run_id || item.run_id || ""} did not complete within ${maxWaitMs}ms`
-          };
-          continue;
-        }
-        const signalRunId = item.signal_run_id || item.run_id;
-        if (!signalRunId) {
-          results[task.index] = { index: task.index, success: false, error: "Signal Copy is processing without a signal_run_id" };
+    const data = await this.client.post("api/v1/signal-to-copy", {
+      requests: requests.map(signalToCopyRequestBody),
+      concurrency
+    });
+    if (!Array.isArray(data.results) || data.results.length !== requests.length) {
+      throw new Error("Signal to Copy batch returned an invalid result count");
+    }
+    for (let index = 0; index < requests.length; index += 1) {
+      const item = data.results[index];
+      if (item.success === false) {
+        if (rowRateLimitAttempt < MAX_ROW_RATE_LIMIT_RETRIES && isRetryableRowRateLimit({
+          index,
+          success: false,
+          raw: item
+        })) {
+          rateLimited.push({ index, params: requests[index], raw: item });
           continue;
         }
-        nextDelayMs = Math.min(
-          nextDelayMs,
-          signalPollDelayMs(item, task.params.pollIntervalMs),
-          maxWaitMs - (Date.now() - startedAt)
-        );
-        nextPending.push({
-          ...task,
-          request: item.resume_context_persisted === true ? { signal_run_id: signalRunId } : { ...task.request, signal_run_id: signalRunId }
-        });
+        results[index] = batchItemFailure(index, item.error || item.message || "Signal to Copy failed", item);
+        continue;
+      }
+      try {
+        assertTerminalSignalResponse(item, "Signal to Copy");
+        results[index] = { index, success: true, data: normalizeSignalToCopyResult(item) };
+      } catch (error) {
+        results[index] = batchItemFailure(index, error instanceof Error ? error.message : String(error), item);
       }
-      pending = nextPending;
-      if (pending.length > 0) await sleep2(nextDelayMs);
     }
     if (rateLimited.length > 0) {
       await sleep2(rowRateLimitDelayMs(rateLimited.map((item) => ({
@@ -843,12 +698,12 @@ var Signaliz = class {
     }
     return results;
   }
-  async runCoreBatchRound(path, tasks, options, companyRecoverableBatch, rowRateLimitAttempt = 0) {
+  async runCoreBatchRound(path, tasks, options, rowRateLimitAttempt = 0) {
     const { serverConcurrency, chunkConcurrency } = batchConcurrencyPlan(options);
     const deduplicated = dedupeExactBatchItems(tasks, (task) => JSON.stringify(task.request));
     const uniqueTasks = deduplicated.uniqueItems;
-    const recoverableBatch = path === "api/v1/find-email" ? { label: "Find Email", pageSize: 500, maxWaitMs: 20 * 6e4 } : path === "api/v1/verify-email" ? { label: "Verify Email", pageSize: 500, maxWaitMs: 20 * 6e4 } : companyRecoverableBatch;
-    if (recoverableBatch && uniqueTasks.length > 25) {
+    const recoverableBatch = path === "api/v1/find-email" ? { label: "Find Email", pageSize: 500, maxWaitMs: 20 * 6e4 } : path === "api/v1/verify-email" ? { label: "Verify Email", pageSize: 500, maxWaitMs: 20 * 6e4 } : void 0;
+    if (path !== "api/v1/company-signals" && recoverableBatch && uniqueTasks.length > 25) {
       const rows = await this.runRecoverableCoreBatchJob(
         path,
         uniqueTasks.map((task) => task.request),
@@ -920,7 +775,6 @@ var Signaliz = class {
           path,
           retryTasks,
           options,
-          void 0,
           rowRateLimitAttempt + 1
         );
         const retriedByIndex = new Map(retried.map((item) => [item.index, item]));
@@ -1049,6 +903,15 @@ function normalizeFindEmailResult(data) {
     verifiedAt: typeof data.verified_at === "string" ? data.verified_at : null,
     needsReverification,
     providerUsed: data.provider_used ?? data.provider ?? data.email_source ?? data.source ?? "unknown",
+    creditsUsed: data.credits_used,
+    estimatedExternalCostUsd: data.estimated_external_cost_usd,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
+    liveProviderCalled: data.live_provider_called,
+    openrouterCalled: data.openrouter_called,
+    byoOpenrouterUsed: data.byo_openrouter_used,
     error: found ? void 0 : data.error ?? "No verified email found",
     errorCode: found ? void 0 : data.error_code ?? "EMAIL_NOT_FOUND",
     raw: data
@@ -1058,6 +921,7 @@ function normalizeVerifyEmailResult(email, data) {
   const verificationStatus = String(data.verification_status ?? "").toLowerCase();
   const verified = data.email_verified === true || ["valid", "deliverable"].includes(verificationStatus);
   return {
+    success: data.success !== false,
     email: data.email ?? email,
     status: String(data.status || "").toLowerCase() === "processing" ? "processing" : "completed",
     verificationRunId: data.verification_run_id ?? data.run_id,
@@ -1066,9 +930,20 @@ function normalizeVerifyEmailResult(email, data) {
     isValid: data.is_valid ?? data.valid ?? verified,
     isDeliverable: data.is_deliverable ?? data.deliverable ?? verified,
     isCatchAll: data.email_is_catch_all ?? data.is_catch_all ?? data.catch_all ?? data.diagnostics?.is_catch_all ?? false,
+    verifiedForSending: data.verified_for_sending === true,
+    verificationVerdict: data.verification_verdict ?? data.verification_status ?? "unknown",
     confidenceScore: data.confidence_score ?? data.confidence ?? data.diagnostics?.confidence_score ?? (verified ? 1 : 0),
     provider: data.provider,
     verificationSource: data.verification_source,
+    billingReplayed: data.billing_replayed,
+    creditsUsed: data.credits_used,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
+    liveProviderCalled: data.live_provider_called,
+    openrouterCalled: data.openrouter_called,
+    byoOpenrouterUsed: data.byo_openrouter_used,
     raw: data
   };
 }
@@ -1084,41 +959,17 @@ function companySignalRequestBody(params) {
     lookback_days: params.lookbackDays,
     online,
     enable_deep_search: params.enableDeepSearch ?? online,
+    search_mode: params.searchMode ?? "balanced",
     include_summary: params.includeSummary,
     enable_outreach_intelligence: params.enableOutreachIntelligence,
     enable_predictive_intelligence: params.enablePredictiveIntelligence,
     skip_cache: params.skipCache,
-    // REST always returns a resumable run instead of holding the connection;
-    // waitForResult controls the SDK polling loop.
-    wait_for_result: false,
+    wait_for_result: true,
     max_wait_ms: params.maxWaitMs,
     dry_run: params.dryRun,
     idempotency_key: params.idempotencyKey
   });
 }
-function companySignalRecoverableBatchOptions(companies, tasks) {
-  if (companies.length <= 25 || companies.some((params) => params.waitForResult === false || Boolean(params.signalRunId))) {
-    return void 0;
-  }
-  const maxWaitMs = Math.max(1e3, companies[0].maxWaitMs ?? 20 * 6e4);
-  if (companies.some((params) => Math.max(1e3, params.maxWaitMs ?? 20 * 6e4) !== maxWaitMs)) {
-    return void 0;
-  }
-  const configKey = (request) => {
-    const {
-      company_domain: _companyDomain,
-      company_name: _companyName,
-      signal_run_id: _signalRunId,
-      wait_for_result: _waitForResult,
-      max_wait_ms: _maxWaitMs,
-      ...config
-    } = request;
-    return JSON.stringify(config);
-  };
-  const sharedConfig = configKey(tasks[0].request);
-  if (tasks.some((task) => configKey(task.request) !== sharedConfig)) return void 0;
-  return { label: "Company Signals", pageSize: 25, maxWaitMs };
-}
 function normalizeCompanySignalResult(params, data) {
   const rawSignals = data.signals ?? data.signal_feed ?? [];
   return {
@@ -1136,8 +987,10 @@ function normalizeCompanySignalResult(params, data) {
         title: signal.title ?? "",
         type: signal.type ?? signal.signal_type ?? "unknown",
         content: signal.content ?? signal.description ?? "",
-        date: signal.date ?? signal.detected_at ?? null,
+        date: signal.date ?? null,
+        detectedAt: signal.detected_at ?? null,
         datePrecision: signal.date_precision,
+        hasSpecificDate: signal.has_specific_date ?? metadata?.has_specific_date,
         sourceUrl: signal.source_url ?? signal.url ?? null,
         sourceType: signal.source_type,
         sourceProvenance: signal.source_provenance,
@@ -1166,7 +1019,10 @@ function normalizeCompanySignalResult(params, data) {
     billingMetadata: data.billing_metadata,
     resultReturnedFrom: data.result_returned_from,
     cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
     liveProviderCalled: data.live_provider_called,
+    aiProviderCalled: data.ai_provider_called,
+    byoAiUsed: data.byo_ai_used,
     metadata: data.metadata,
     raw: data
   };
@@ -1266,11 +1122,13 @@ function signalToCopyRequestBody(params) {
     signal_run_id: params.signalRunId,
     skip_cache: params.skipCache,
     enable_deep_search: params.enableDeepSearch,
+    max_wait_ms: params.maxWaitMs,
     dry_run: params.dryRun,
     idempotency_key: params.idempotencyKey
   });
 }
 function validateSignalToCopyParams(params) {
+  validateCoreProductMaxWaitMs(params.maxWaitMs);
   if (typeof params.signalRunId === "string" && params.signalRunId.trim()) return;
   const missing = [
     ["companyDomain", params.companyDomain],
@@ -1282,6 +1140,12 @@ function validateSignalToCopyParams(params) {
     throw new TypeError(`Signal to Copy requires signalRunId or: ${missing.join(", ")}`);
   }
 }
+function validateCoreProductMaxWaitMs(value) {
+  if (value === void 0) return;
+  if (!Number.isInteger(value) || value < 1e4 || value > 12e4) {
+    throw new RangeError("maxWaitMs must be an integer between 10000 and 120000");
+  }
+}
 function normalizeSignalToCopyResult(data) {
   return {
     success: data.success ?? true,
@@ -1312,11 +1176,10 @@ function normalizeSignalToCopyResult(data) {
 function isPendingSignalResponse(data) {
   return ["triggered", "queued", "processing", "pending", "pending_version", "waiting_for_deploy"].includes(String(data.status || "").toLowerCase());
 }
-function isCompletedSignalRun(data) {
-  return ["completed", "success", "succeeded"].includes(String(data.status || "").toLowerCase());
-}
-function isFailedSignalRun(data) {
-  return ["failed", "error", "cancelled", "canceled", "crashed", "timed_out"].includes(String(data.status || "").toLowerCase());
+function assertTerminalSignalResponse(data, capability) {
+  if (isPendingSignalResponse(data) || data.job_id) {
+    throw new Error(`${capability} violated the synchronous response contract.`);
+  }
 }
 function signalPollDelayMs(data, override) {
   if (override !== void 0) return Math.max(250, override);

package/dist/index.d.mts

@@ -92,11 +92,21 @@ interface FindEmailResult {
     verifiedAt: string | null;
     needsReverification: boolean;
     providerUsed: string;
+    creditsUsed?: number;
+    estimatedExternalCostUsd?: number;
+    billingMetadata?: Record<string, unknown>;
+    resultReturnedFrom?: string;
+    cacheHit?: boolean;
+    freshEnrichmentUsed?: boolean;
+    liveProviderCalled?: boolean;
+    openrouterCalled?: boolean;
+    byoOpenrouterUsed?: boolean;
     error?: string;
     errorCode?: string;
     raw: Record<string, unknown>;
 }
 interface VerifyEmailResult {
+    success: boolean;
     email: string;
     /** Execution state. Processing results are never send-safe. */
     status: 'processing' | 'completed';
@@ -107,9 +117,21 @@ interface VerifyEmailResult {
     isValid: boolean;
     isDeliverable: boolean;
     isCatchAll: boolean;
+    /** Explicit send-safety verdict. Missing or false never becomes true by inference. */
+    verifiedForSending: boolean;
+    verificationVerdict: string;
     confidenceScore: number;
     provider?: string;
     verificationSource?: string;
+    billingReplayed?: boolean;
+    creditsUsed?: number;
+    billingMetadata?: Record<string, unknown>;
+    resultReturnedFrom?: string;
+    cacheHit?: boolean;
+    freshEnrichmentUsed?: boolean;
+    liveProviderCalled?: boolean;
+    openrouterCalled?: boolean;
+    byoOpenrouterUsed?: boolean;
     raw: Record<string, unknown>;
 }
 interface VerifyEmailOptions {
@@ -141,15 +163,17 @@ interface CompanySignalEnrichmentParams {
     lookbackDays?: number;
     online?: boolean;
     enableDeepSearch?: boolean;
+    /** Web coverage policy. Balanced targets an average all-in search budget below one cent. */
+    searchMode?: 'fast' | 'balanced' | 'coverage';
     includeSummary?: boolean;
     enableOutreachIntelligence?: boolean;
     enablePredictiveIntelligence?: boolean;
     skipCache?: boolean;
-    /** Wait for a queued Trigger.dev enrichment to finish. Defaults to true. */
+    /** @deprecated Company Signals is always synchronous; this option is ignored. */
     waitForResult?: boolean;
-    /** Maximum time to wait for a queued enrichment. Defaults to 20 minutes. */
+    /** Maximum server-side synchronous execution window. */
     maxWaitMs?: number;
-    /** Delay between queued-enrichment status checks. Defaults to 2 seconds. */
+    /** @deprecated Company Signals never returns a polling contract. */
     pollIntervalMs?: number;
     /** Return a no-spend plan without provider calls or jobs. */
     dryRun?: boolean;
@@ -162,7 +186,9 @@ interface CompanySignal {
     type: string;
     content: string;
     date?: string | null;
+    detectedAt?: string | null;
     datePrecision?: string;
+    hasSpecificDate?: boolean;
     sourceUrl?: string | null;
     sourceType?: string;
     sourceProvenance?: string;
@@ -199,7 +225,10 @@ interface CompanySignalEnrichmentResult {
     billingMetadata?: Record<string, unknown>;
     resultReturnedFrom?: string;
     cacheHit?: boolean;
+    freshEnrichmentUsed?: boolean;
     liveProviderCalled?: boolean;
+    aiProviderCalled?: boolean;
+    byoAiUsed?: boolean;
     metadata?: Record<string, unknown>;
     raw: Record<string, unknown>;
 }
@@ -214,8 +243,10 @@ interface SignalToCopyParams {
     skipCache?: boolean;
     /** Opt into slower deep research. Defaults to false. */
     enableDeepSearch?: boolean;
+    /** @deprecated Signal to Copy is always synchronous; this option is ignored. */
     waitForResult?: boolean;
     maxWaitMs?: number;
+    /** @deprecated Signal to Copy never returns a polling contract. */
     pollIntervalMs?: number;
     /** Return a no-spend plan without provider calls or jobs. */
     dryRun?: boolean;
@@ -306,7 +337,6 @@ declare class Signaliz {
     createSignalCopyBatch(requests: SignalToCopyParams[], options?: BatchOptions): Promise<BatchResult<SignalToCopyResult>>;
     private runCoreProductDryRun;
     private runSignalCopyBatchChunks;
-    private runAvailableSignalCopyBatchJob;
     private runRecoverableCoreBatchJob;
     private runSignalCopyBatchChunk;
     private runCoreBatchRound;