@signaliz/sdk 1.0.59 → 1.0.61

package/README.md

@@ -44,6 +44,10 @@ const verified = await signaliz.verifyEmail(found.email!, {
   skipCache: true,
 });
 
+// Syntax failures are terminal local results, with no HTTP or provider call.
+const malformed = await signaliz.verifyEmail('badformat@@gmail..com');
+console.log(malformed.success, malformed.isMalformed, malformed.verificationVerdict);
+
 // The SDK waits for long checks by default. For an agent handoff, return early
 // and resume the exact provider run later without duplicate spend.
 const queuedVerification = await signaliz.verifyEmail('jane@example.com', {
@@ -69,6 +73,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;
@@ -150,12 +160,15 @@ 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.
+`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
@@ -166,6 +179,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. 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

package/dist/{chunk-VKBUQTDS.mjs → chunk-ENA7AVFB.mjs}

@@ -9,17 +9,21 @@ var SignalizError = class extends Error {
     this.details = data.details;
   }
   get isRetryable() {
+    if (typeof this.details?.retry_eligible === "boolean") {
+      return this.details.retry_eligible;
+    }
     return this.errorType === "rate_limited" || this.errorType === "timeout" || this.errorType === "provider_error";
   }
 };
 function parseError(status, body) {
   if (body?.error && typeof body.error === "object") {
+    const nestedDetails = body.error.details && typeof body.error.details === "object" ? body.error.details : {};
     return new SignalizError({
       code: body.error.code || `HTTP_${status}`,
       message: body.error.message || `Request failed with status ${status}`,
       errorType: mapErrorType(body.error.code, status),
       retryAfter: retryAfterSeconds(body.error),
-      details: body.error.details
+      details: mergePublicErrorDetails({ ...body, ...body.error }, nestedDetails)
     });
   }
   const code = typeof body?.error_code === "string" && body.error_code.trim() ? body.error_code.trim() : `HTTP_${status}`;
@@ -28,7 +32,7 @@ function parseError(status, body) {
     message: body?.message || body?.error || `Request failed with status ${status}`,
     errorType: mapErrorType(code, status),
     retryAfter: retryAfterSeconds(body),
-    details: body?.details || publicRetryDetails(body)
+    details: mergePublicErrorDetails(body, body?.details)
   });
 }
 function retryAfterSeconds(body) {
@@ -40,13 +44,26 @@ function publicRetryDetails(body) {
     ...body?.retry_eligible !== void 0 ? { retry_eligible: body.retry_eligible } : {},
     ...body?.retry_after !== void 0 ? { retry_after: body.retry_after } : {},
     ...body?.retry_after_seconds !== void 0 ? { retry_after_seconds: body.retry_after_seconds } : {},
+    ...body?.retry_strategy !== void 0 ? { retry_strategy: body.retry_strategy } : {},
+    ...body?.credits_used !== void 0 ? { credits_used: body.credits_used } : {},
+    ...body?.credits_charged !== void 0 ? { credits_charged: body.credits_charged } : {},
+    ...body?.job_id !== void 0 ? { job_id: body.job_id } : {},
+    ...body?.verification_run_id !== void 0 ? { verification_run_id: body.verification_run_id } : {},
     ...body?.run_id !== void 0 ? { run_id: body.run_id } : {},
+    ...body?.suggested_action !== void 0 ? { suggested_action: body.suggested_action } : {},
     ...body?.signal_run_id !== void 0 ? { signal_run_id: body.signal_run_id } : {},
     ...body?.company_signal_run_id !== void 0 ? { company_signal_run_id: body.company_signal_run_id } : {},
     ...body?.resume_context_persisted !== void 0 ? { resume_context_persisted: body.resume_context_persisted } : {}
   };
   return Object.keys(details).length > 0 ? details : void 0;
 }
+function mergePublicErrorDetails(body, explicitDetails) {
+  const merged = { ...publicRetryDetails(body) || {} };
+  if (explicitDetails && typeof explicitDetails === "object" && !Array.isArray(explicitDetails)) {
+    Object.assign(merged, explicitDetails);
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
 function mapErrorType(code, status) {
   if (code === "RATE_LIMITED" || status === 429) return "rate_limited";
   if (code === "VALIDATION_ERROR" || code === "SIGNAL_RUN_COMPANY_MISMATCH" || status === 400) return "validation";
@@ -108,7 +125,9 @@ var HttpClient = class {
           const errBody = await res.json().catch(() => ({}));
           const err = parseError(res.status, errBody);
           if (err.isRetryable && attempt < this.maxRetries) {
-            const wait = err.retryAfter ? err.retryAfter * 1e3 : Math.min(1e3 * Math.pow(2, attempt), 1e4);
+            const retryWithNewKey = err.details?.retry_strategy === "new_idempotency_key" && err.details?.credits_used === 0 && err.details?.credits_charged === 0;
+            if (retryWithNewKey) throw err;
+            const wait = err.retryAfter !== void 0 ? err.retryAfter * 1e3 : Math.min(1e3 * Math.pow(2, attempt), 1e4);
             await sleep(wait);
             lastError = err;
             continue;
@@ -408,6 +427,29 @@ var Signaliz = class {
     );
   }
   async verifyEmail(email, options) {
+    const normalizedEmail = typeof email === "string" ? email.trim() : "";
+    if (options?.dryRun !== true && !options?.verificationRunId && normalizedEmail && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalizedEmail)) {
+      const error = `Invalid email format: "${normalizedEmail}"`;
+      return normalizeVerifyEmailResult(normalizedEmail, {
+        success: false,
+        email: normalizedEmail,
+        status: "completed",
+        is_valid: false,
+        is_deliverable: false,
+        email_verified: false,
+        verified_for_sending: false,
+        is_malformed: true,
+        verification_status: "malformed",
+        verification_verdict: "malformed",
+        verification_source: "input_validation",
+        provider_status: "rejected_before_provider",
+        error,
+        error_code: "INPUT_001",
+        retry_eligible: false,
+        credits_used: 0,
+        live_provider_called: false
+      });
+    }
     const request = compact({
       email: email || void 0,
       verification_run_id: options?.verificationRunId,
@@ -742,7 +784,10 @@ var Signaliz = class {
     );
     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 } : void 0;
-    if (path !== "api/v1/company-signals" && recoverableBatch && uniqueTasks.length > 25) {
+    const containsFindRecoveryReads = path === "api/v1/find-email" && uniqueTasks.some(
+      (task) => typeof task.request.run_id === "string" && task.request.run_id.trim()
+    );
+    if (path !== "api/v1/company-signals" && recoverableBatch && uniqueTasks.length > 25 && !containsFindRecoveryReads) {
       const rows = await this.runRecoverableCoreBatchJob(
         path,
         uniqueTasks.map((task) => task.request),
@@ -868,13 +913,27 @@ function batchItemFailure(index, error, raw) {
     raw?.retry_after_seconds ?? raw?.retry_after ?? raw?.retryAfterSeconds ?? (Number.isFinite(Number(raw?.retry_after_ms)) ? Number(raw?.retry_after_ms) / 1e3 : void 0)
   );
   const retryEligible = raw?.retry_eligible ?? raw?.retryEligible;
+  const retryStrategy = raw?.retry_strategy ?? raw?.retryStrategy;
+  const creditsUsed = raw?.credits_used ?? raw?.creditsUsed;
+  const creditsCharged = raw?.credits_charged ?? raw?.creditsCharged;
+  const runId = raw?.run_id ?? raw?.runId;
+  const verificationRunId = raw?.verification_run_id ?? raw?.verificationRunId;
+  const jobId = raw?.job_id ?? raw?.jobId;
+  const suggestedAction = raw?.suggested_action ?? raw?.suggestedAction;
   return {
     index,
     success: false,
     error,
     ...errorCode ? { errorCode } : {},
     ...typeof retryEligible === "boolean" ? { retryEligible } : {},
-    ...Number.isFinite(retryAfterSeconds2) && retryAfterSeconds2 >= 0 ? { retryAfterSeconds: retryAfterSeconds2 } : {}
+    ...Number.isFinite(retryAfterSeconds2) && retryAfterSeconds2 >= 0 ? { retryAfterSeconds: retryAfterSeconds2 } : {},
+    ...retryStrategy === "new_idempotency_key" ? { retryStrategy } : {},
+    ...creditsUsed === 0 ? { creditsUsed: 0 } : {},
+    ...creditsCharged === 0 ? { creditsCharged: 0 } : {},
+    ...typeof runId === "string" && runId.trim() ? { runId: runId.trim() } : {},
+    ...typeof verificationRunId === "string" && verificationRunId.trim() ? { verificationRunId: verificationRunId.trim() } : {},
+    ...typeof jobId === "string" && jobId.trim() ? { jobId: jobId.trim() } : {},
+    ...typeof suggestedAction === "string" && suggestedAction.trim() ? { suggestedAction: suggestedAction.trim() } : {}
   };
 }
 function recoverableJobRowFailed(row) {
@@ -889,6 +948,7 @@ function compact(input) {
 }
 function findEmailRequestBody(params) {
   return compact({
+    run_id: params.runId,
     company_domain: params.companyDomain,
     full_name: params.fullName,
     first_name: params.firstName,
@@ -928,6 +988,7 @@ function normalizeCoreProductDryRunResult(data) {
   };
 }
 function normalizeFindEmailResult(data) {
+  const processing = String(data.status || "").toLowerCase() === "processing";
   const failed = coreProductResponseFailed(data);
   const rawEmail = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const email = failed ? null : rawEmail;
@@ -940,7 +1001,7 @@ function normalizeFindEmailResult(data) {
   const verified = !explicitlyNotSendSafe && (data.is_valid === true || data.isValid === true || data.email_verified === true || data.verified_for_sending === true || ["valid", "deliverable"].includes(String(verificationStatus).toLowerCase()));
   const verificationAgeDays = typeof data.verification_age_days === "number" && Number.isFinite(data.verification_age_days) ? data.verification_age_days : null;
   return {
-    success: !failed && found,
+    success: processing || !failed && found,
     found,
     email,
     firstName: data.first_name,
@@ -967,8 +1028,12 @@ function normalizeFindEmailResult(data) {
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
     byoOpenrouterUsed: data.byo_openrouter_used,
-    error: found ? void 0 : coreProductErrorMessage(data) ?? "No verified email found",
-    errorCode: found ? void 0 : coreProductErrorCode(data) ?? "EMAIL_NOT_FOUND",
+    error: processing || found ? void 0 : coreProductErrorMessage(data) ?? "No verified email found",
+    errorCode: processing || found ? void 0 : coreProductErrorCode(data) ?? "EMAIL_NOT_FOUND",
+    status: processing ? "processing" : "completed",
+    runId: data.run_id,
+    nextPollAfterSeconds: data.next_poll_after_seconds,
+    suggestedAction: data.suggested_action,
     raw: data
   };
 }
@@ -1104,6 +1169,12 @@ function validateSignalDiscoveryParams(params) {
   if (query && (query.length < 2 || query.length > 2e3)) {
     throw new RangeError("query must contain between 2 and 2000 characters");
   }
+  if (params.icpContext !== void 0) {
+    const icpContext = typeof params.icpContext === "string" ? params.icpContext.trim() : "";
+    if (icpContext.length < 2 || icpContext.length > 4e3) {
+      throw new RangeError("icpContext must contain between 2 and 4000 characters");
+    }
+  }
   if (params.limit !== void 0 && (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 1e3)) {
     throw new RangeError("limit must be an integer between 1 and 1000");
   }
@@ -1128,6 +1199,7 @@ function signalDiscoveryRequestBody(params) {
   }
   return compact({
     query: params.query?.trim(),
+    icp_context: params.icpContext?.trim(),
     limit: params.limit ?? 100,
     sources: params.sources,
     lookback_days: params.lookbackDays,
@@ -1153,6 +1225,8 @@ function normalizeSignalDiscoveryResult(params, data) {
     availableCompanySignalCount: Number.isFinite(Number(data.available_company_signal_count)) ? Number(data.available_company_signal_count) : void 0,
     sourceLanes: Array.isArray(data.source_lanes) ? data.source_lanes.filter((lane) => typeof lane === "string") : void 0,
     evidenceValidation: data.evidence_validation && typeof data.evidence_validation === "object" ? data.evidence_validation : void 0,
+    discoveryDiagnostics: data.discovery_diagnostics && typeof data.discovery_diagnostics === "object" ? data.discovery_diagnostics : void 0,
+    identityResolution: data.identity_resolution && typeof data.identity_resolution === "object" ? data.identity_resolution : void 0,
     costGuardrail: normalizeSignalDiscoveryCostGuardrail(data.cost_guardrail),
     warnings: Array.isArray(data.warnings) ? data.warnings.filter((warning) => typeof warning === "string") : void 0,
     raw: data
@@ -1181,7 +1255,15 @@ function normalizeSignalDiscoveryCostGuardrail(value) {
       guardrail.projected_cost_per_requested_company_signal_usd
     ),
     sourceCostUsd: numberOrNullable(guardrail.source_cost_usd),
-    costSource: ["observed", "catalog_bounded", "mixed", "unavailable"].includes(String(guardrail.cost_source)) ? String(guardrail.cost_source) : void 0,
+    costSource: ["observed", "catalog_preflight", "catalog_bounded", "mixed", "unavailable"].includes(String(guardrail.cost_source)) ? String(guardrail.cost_source) : void 0,
+    identityResolutionCostUsd: numberOrNullable(guardrail.identity_resolution_cost_usd),
+    identityCostSource: [
+      "observed_zero_credit_receipts",
+      "contractual_zero_cost",
+      "not_used",
+      "unavailable"
+    ].includes(String(guardrail.identity_cost_source)) ? String(guardrail.identity_cost_source) : void 0,
+    identityProviderRequests: numberOrUndefined(guardrail.identity_provider_requests),
     qualifiedCompanySignalCount: numberOrUndefined(guardrail.qualified_company_signal_count),
     returnedCompanySignalCount: numberOrUndefined(guardrail.returned_company_signal_count),
     availableCompanySignalCount: numberOrUndefined(guardrail.available_company_signal_count),
@@ -1285,6 +1367,7 @@ function normalizedFindEmailBatchName(request) {
 function coreProductBatchRequestKey(path, request) {
   if (path === "api/v1/find-email") {
     return JSON.stringify([
+      normalizedBatchText(request.run_id),
       normalizedFindEmailBatchName(request),
       normalizedBatchDomain(request.company_domain),
       normalizedBatchLinkedIn(request.linkedin_url),
@@ -1390,6 +1473,7 @@ function signalToCopyRequestBody(params) {
     title: params.title,
     campaign_offer: params.campaignOffer,
     research_prompt: params.researchPrompt,
+    lookback_days: params.lookbackDays,
     signal_run_id: params.signalRunId,
     skip_cache: params.skipCache,
     enable_deep_search: params.enableDeepSearch,
@@ -1400,6 +1484,9 @@ function signalToCopyRequestBody(params) {
 }
 function validateSignalToCopyParams(params) {
   validateCoreProductMaxWaitMs(params.maxWaitMs);
+  if (params.lookbackDays !== void 0 && (!Number.isInteger(params.lookbackDays) || params.lookbackDays < 1 || params.lookbackDays > 365)) {
+    throw new RangeError("lookbackDays must be an integer between 1 and 365");
+  }
   if (typeof params.signalRunId === "string" && params.signalRunId.trim()) return;
   const missing = [
     ["companyDomain", params.companyDomain],

package/dist/index.d.mts

@@ -27,6 +27,20 @@ interface BatchItemResult<T> {
     retryEligible?: boolean;
     /** Server-provided delay before retrying the failed row. */
     retryAfterSeconds?: number;
+    /** Explicit recovery strategy. A fresh key can repeat provider work and is never automatic. */
+    retryStrategy?: 'new_idempotency_key';
+    /** Present only when the server proves the failed row consumed zero Signaliz credits. */
+    creditsUsed?: 0;
+    /** Present only when the server proves the failed row charged zero Signaliz credits. */
+    creditsCharged?: 0;
+    /** Existing provider run that can be resumed without dispatching new work. */
+    runId?: string;
+    /** Existing Verify Email run that can be resumed without dispatching new work. */
+    verificationRunId?: string;
+    /** Existing recoverable batch job. */
+    jobId?: string;
+    /** Machine-readable recovery action returned by Signaliz. */
+    suggestedAction?: string;
     /** Zero-based input index containing the full result for this exact duplicate. */
     duplicateOf?: number;
 }
@@ -66,8 +80,7 @@ interface CoreProductDryRunResult {
     sideEffects: unknown[];
     raw: Record<string, unknown>;
 }
-interface FindEmailParams {
-    companyDomain: string;
+interface FindEmailCommonParams {
     fullName?: string;
     firstName?: string;
     lastName?: string;
@@ -80,6 +93,15 @@ interface FindEmailParams {
     /** Stable retry key for recovering the same request after an ambiguous response. */
     idempotencyKey?: string;
 }
+type FindEmailParams = FindEmailCommonParams & ({
+    companyDomain: string;
+    /** Omit for a new lookup. */
+    runId?: undefined;
+} | {
+    /** Resume one existing Find Email run without dispatching a new finder. */
+    runId: string;
+    companyDomain?: string;
+});
 interface FindEmailResult {
     success: boolean;
     found: boolean;
@@ -112,6 +134,12 @@ interface FindEmailResult {
     byoOpenrouterUsed?: boolean;
     error?: string;
     errorCode?: string;
+    /** Processing while an existing provider run is still active; otherwise completed. */
+    status?: 'processing' | 'completed';
+    /** Durable Find Email run ID for polling without duplicate spend. */
+    runId?: string;
+    nextPollAfterSeconds?: number;
+    suggestedAction?: string;
     raw: Record<string, unknown>;
 }
 interface VerifyEmailResult {
@@ -250,8 +278,10 @@ interface CompanySignalEnrichmentResult {
 type SignalDiscoverySource = 'web' | 'news';
 type SignalDiscoveryStatus = 'planned' | 'queued' | 'processing' | 'completed' | 'completed_with_warnings' | 'failed';
 interface SignalDiscoveryParams {
-    /** Natural-language description of the signals to find. Required for a new search. */
+    /** Any natural-language signal question. Required for a new search. */
     query?: string;
+    /** Optional natural-language ICP, product, or pain context that returned signals must support. */
+    icpContext?: string;
     /** Number of qualified company signals requested. Defaults to 100; allowed range is 1-1,000. */
     limit?: number;
     /** Restrict discovery to selected source families. */
@@ -300,7 +330,13 @@ interface SignalDiscoveryCostGuardrail {
     maxSourceCostUsd?: number | null;
     projectedCostPerRequestedCompanySignalUsd?: number | null;
     sourceCostUsd?: number | null;
-    costSource?: 'observed' | 'catalog_bounded' | 'mixed' | 'unavailable';
+    costSource?: 'observed' | 'catalog_preflight' | 'catalog_bounded' | 'mixed' | 'unavailable';
+    /** Separately reported company identity-resolution cost; null when receipts are incomplete. */
+    identityResolutionCostUsd?: number | null;
+    /** Evidence used to account for company identity-resolution cost. */
+    identityCostSource?: 'observed_zero_credit_receipts' | 'contractual_zero_cost' | 'not_used' | 'unavailable';
+    /** Zero-cost fallback identity-provider requests covered by identityResolutionCostUsd. */
+    identityProviderRequests?: number;
     qualifiedCompanySignalCount?: number;
     returnedCompanySignalCount?: number;
     /** Qualified signals retained on the same search run for later expansion. */
@@ -326,6 +362,10 @@ interface SignalDiscoveryResult {
     availableCompanySignalCount?: number;
     sourceLanes?: string[];
     evidenceValidation?: Record<string, unknown>;
+    /** Search, reachability, date, classifier, and rejection counts for diagnosis. */
+    discoveryDiagnostics?: Record<string, unknown>;
+    /** Company-domain verification counts for the retained cohort. */
+    identityResolution?: Record<string, unknown>;
     costGuardrail?: SignalDiscoveryCostGuardrail;
     warnings?: string[];
     raw: Record<string, unknown>;
@@ -336,6 +376,8 @@ interface SignalToCopyParams {
     title?: string;
     campaignOffer?: string;
     researchPrompt?: string;
+    /** Maximum signal age used for cache reuse and fresh research. Defaults to 90 days. */
+    lookbackDays?: number;
     signalRunId?: string;
     /** Bypass cached company signals and start fresh research. */
     skipCache?: boolean;

package/dist/index.d.ts

@@ -27,6 +27,20 @@ interface BatchItemResult<T> {
     retryEligible?: boolean;
     /** Server-provided delay before retrying the failed row. */
     retryAfterSeconds?: number;
+    /** Explicit recovery strategy. A fresh key can repeat provider work and is never automatic. */
+    retryStrategy?: 'new_idempotency_key';
+    /** Present only when the server proves the failed row consumed zero Signaliz credits. */
+    creditsUsed?: 0;
+    /** Present only when the server proves the failed row charged zero Signaliz credits. */
+    creditsCharged?: 0;
+    /** Existing provider run that can be resumed without dispatching new work. */
+    runId?: string;
+    /** Existing Verify Email run that can be resumed without dispatching new work. */
+    verificationRunId?: string;
+    /** Existing recoverable batch job. */
+    jobId?: string;
+    /** Machine-readable recovery action returned by Signaliz. */
+    suggestedAction?: string;
     /** Zero-based input index containing the full result for this exact duplicate. */
     duplicateOf?: number;
 }
@@ -66,8 +80,7 @@ interface CoreProductDryRunResult {
     sideEffects: unknown[];
     raw: Record<string, unknown>;
 }
-interface FindEmailParams {
-    companyDomain: string;
+interface FindEmailCommonParams {
     fullName?: string;
     firstName?: string;
     lastName?: string;
@@ -80,6 +93,15 @@ interface FindEmailParams {
     /** Stable retry key for recovering the same request after an ambiguous response. */
     idempotencyKey?: string;
 }
+type FindEmailParams = FindEmailCommonParams & ({
+    companyDomain: string;
+    /** Omit for a new lookup. */
+    runId?: undefined;
+} | {
+    /** Resume one existing Find Email run without dispatching a new finder. */
+    runId: string;
+    companyDomain?: string;
+});
 interface FindEmailResult {
     success: boolean;
     found: boolean;
@@ -112,6 +134,12 @@ interface FindEmailResult {
     byoOpenrouterUsed?: boolean;
     error?: string;
     errorCode?: string;
+    /** Processing while an existing provider run is still active; otherwise completed. */
+    status?: 'processing' | 'completed';
+    /** Durable Find Email run ID for polling without duplicate spend. */
+    runId?: string;
+    nextPollAfterSeconds?: number;
+    suggestedAction?: string;
     raw: Record<string, unknown>;
 }
 interface VerifyEmailResult {
@@ -250,8 +278,10 @@ interface CompanySignalEnrichmentResult {
 type SignalDiscoverySource = 'web' | 'news';
 type SignalDiscoveryStatus = 'planned' | 'queued' | 'processing' | 'completed' | 'completed_with_warnings' | 'failed';
 interface SignalDiscoveryParams {
-    /** Natural-language description of the signals to find. Required for a new search. */
+    /** Any natural-language signal question. Required for a new search. */
     query?: string;
+    /** Optional natural-language ICP, product, or pain context that returned signals must support. */
+    icpContext?: string;
     /** Number of qualified company signals requested. Defaults to 100; allowed range is 1-1,000. */
     limit?: number;
     /** Restrict discovery to selected source families. */
@@ -300,7 +330,13 @@ interface SignalDiscoveryCostGuardrail {
     maxSourceCostUsd?: number | null;
     projectedCostPerRequestedCompanySignalUsd?: number | null;
     sourceCostUsd?: number | null;
-    costSource?: 'observed' | 'catalog_bounded' | 'mixed' | 'unavailable';
+    costSource?: 'observed' | 'catalog_preflight' | 'catalog_bounded' | 'mixed' | 'unavailable';
+    /** Separately reported company identity-resolution cost; null when receipts are incomplete. */
+    identityResolutionCostUsd?: number | null;
+    /** Evidence used to account for company identity-resolution cost. */
+    identityCostSource?: 'observed_zero_credit_receipts' | 'contractual_zero_cost' | 'not_used' | 'unavailable';
+    /** Zero-cost fallback identity-provider requests covered by identityResolutionCostUsd. */
+    identityProviderRequests?: number;
     qualifiedCompanySignalCount?: number;
     returnedCompanySignalCount?: number;
     /** Qualified signals retained on the same search run for later expansion. */
@@ -326,6 +362,10 @@ interface SignalDiscoveryResult {
     availableCompanySignalCount?: number;
     sourceLanes?: string[];
     evidenceValidation?: Record<string, unknown>;
+    /** Search, reachability, date, classifier, and rejection counts for diagnosis. */
+    discoveryDiagnostics?: Record<string, unknown>;
+    /** Company-domain verification counts for the retained cohort. */
+    identityResolution?: Record<string, unknown>;
     costGuardrail?: SignalDiscoveryCostGuardrail;
     warnings?: string[];
     raw: Record<string, unknown>;
@@ -336,6 +376,8 @@ interface SignalToCopyParams {
     title?: string;
     campaignOffer?: string;
     researchPrompt?: string;
+    /** Maximum signal age used for cache reuse and fresh research. Defaults to 90 days. */
+    lookbackDays?: number;
     signalRunId?: string;
     /** Bypass cached company signals and start fresh research. */
     skipCache?: boolean;

package/dist/index.js

@@ -36,17 +36,21 @@ var SignalizError = class extends Error {
     this.details = data.details;
   }
   get isRetryable() {
+    if (typeof this.details?.retry_eligible === "boolean") {
+      return this.details.retry_eligible;
+    }
     return this.errorType === "rate_limited" || this.errorType === "timeout" || this.errorType === "provider_error";
   }
 };
 function parseError(status, body) {
   if (body?.error && typeof body.error === "object") {
+    const nestedDetails = body.error.details && typeof body.error.details === "object" ? body.error.details : {};
     return new SignalizError({
       code: body.error.code || `HTTP_${status}`,
       message: body.error.message || `Request failed with status ${status}`,
       errorType: mapErrorType(body.error.code, status),
       retryAfter: retryAfterSeconds(body.error),
-      details: body.error.details
+      details: mergePublicErrorDetails({ ...body, ...body.error }, nestedDetails)
     });
   }
   const code = typeof body?.error_code === "string" && body.error_code.trim() ? body.error_code.trim() : `HTTP_${status}`;
@@ -55,7 +59,7 @@ function parseError(status, body) {
     message: body?.message || body?.error || `Request failed with status ${status}`,
     errorType: mapErrorType(code, status),
     retryAfter: retryAfterSeconds(body),
-    details: body?.details || publicRetryDetails(body)
+    details: mergePublicErrorDetails(body, body?.details)
   });
 }
 function retryAfterSeconds(body) {
@@ -67,13 +71,26 @@ function publicRetryDetails(body) {
     ...body?.retry_eligible !== void 0 ? { retry_eligible: body.retry_eligible } : {},
     ...body?.retry_after !== void 0 ? { retry_after: body.retry_after } : {},
     ...body?.retry_after_seconds !== void 0 ? { retry_after_seconds: body.retry_after_seconds } : {},
+    ...body?.retry_strategy !== void 0 ? { retry_strategy: body.retry_strategy } : {},
+    ...body?.credits_used !== void 0 ? { credits_used: body.credits_used } : {},
+    ...body?.credits_charged !== void 0 ? { credits_charged: body.credits_charged } : {},
+    ...body?.job_id !== void 0 ? { job_id: body.job_id } : {},
+    ...body?.verification_run_id !== void 0 ? { verification_run_id: body.verification_run_id } : {},
     ...body?.run_id !== void 0 ? { run_id: body.run_id } : {},
+    ...body?.suggested_action !== void 0 ? { suggested_action: body.suggested_action } : {},
     ...body?.signal_run_id !== void 0 ? { signal_run_id: body.signal_run_id } : {},
     ...body?.company_signal_run_id !== void 0 ? { company_signal_run_id: body.company_signal_run_id } : {},
     ...body?.resume_context_persisted !== void 0 ? { resume_context_persisted: body.resume_context_persisted } : {}
   };
   return Object.keys(details).length > 0 ? details : void 0;
 }
+function mergePublicErrorDetails(body, explicitDetails) {
+  const merged = { ...publicRetryDetails(body) || {} };
+  if (explicitDetails && typeof explicitDetails === "object" && !Array.isArray(explicitDetails)) {
+    Object.assign(merged, explicitDetails);
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
 function mapErrorType(code, status) {
   if (code === "RATE_LIMITED" || status === 429) return "rate_limited";
   if (code === "VALIDATION_ERROR" || code === "SIGNAL_RUN_COMPANY_MISMATCH" || status === 400) return "validation";
@@ -135,7 +152,9 @@ var HttpClient = class {
           const errBody = await res.json().catch(() => ({}));
           const err = parseError(res.status, errBody);
           if (err.isRetryable && attempt < this.maxRetries) {
-            const wait = err.retryAfter ? err.retryAfter * 1e3 : Math.min(1e3 * Math.pow(2, attempt), 1e4);
+            const retryWithNewKey = err.details?.retry_strategy === "new_idempotency_key" && err.details?.credits_used === 0 && err.details?.credits_charged === 0;
+            if (retryWithNewKey) throw err;
+            const wait = err.retryAfter !== void 0 ? err.retryAfter * 1e3 : Math.min(1e3 * Math.pow(2, attempt), 1e4);
             await sleep(wait);
             lastError = err;
             continue;
@@ -435,6 +454,29 @@ var Signaliz = class {
     );
   }
   async verifyEmail(email, options) {
+    const normalizedEmail = typeof email === "string" ? email.trim() : "";
+    if (options?.dryRun !== true && !options?.verificationRunId && normalizedEmail && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalizedEmail)) {
+      const error = `Invalid email format: "${normalizedEmail}"`;
+      return normalizeVerifyEmailResult(normalizedEmail, {
+        success: false,
+        email: normalizedEmail,
+        status: "completed",
+        is_valid: false,
+        is_deliverable: false,
+        email_verified: false,
+        verified_for_sending: false,
+        is_malformed: true,
+        verification_status: "malformed",
+        verification_verdict: "malformed",
+        verification_source: "input_validation",
+        provider_status: "rejected_before_provider",
+        error,
+        error_code: "INPUT_001",
+        retry_eligible: false,
+        credits_used: 0,
+        live_provider_called: false
+      });
+    }
     const request = compact({
       email: email || void 0,
       verification_run_id: options?.verificationRunId,
@@ -769,7 +811,10 @@ var Signaliz = class {
     );
     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 } : void 0;
-    if (path !== "api/v1/company-signals" && recoverableBatch && uniqueTasks.length > 25) {
+    const containsFindRecoveryReads = path === "api/v1/find-email" && uniqueTasks.some(
+      (task) => typeof task.request.run_id === "string" && task.request.run_id.trim()
+    );
+    if (path !== "api/v1/company-signals" && recoverableBatch && uniqueTasks.length > 25 && !containsFindRecoveryReads) {
       const rows = await this.runRecoverableCoreBatchJob(
         path,
         uniqueTasks.map((task) => task.request),
@@ -895,13 +940,27 @@ function batchItemFailure(index, error, raw) {
     raw?.retry_after_seconds ?? raw?.retry_after ?? raw?.retryAfterSeconds ?? (Number.isFinite(Number(raw?.retry_after_ms)) ? Number(raw?.retry_after_ms) / 1e3 : void 0)
   );
   const retryEligible = raw?.retry_eligible ?? raw?.retryEligible;
+  const retryStrategy = raw?.retry_strategy ?? raw?.retryStrategy;
+  const creditsUsed = raw?.credits_used ?? raw?.creditsUsed;
+  const creditsCharged = raw?.credits_charged ?? raw?.creditsCharged;
+  const runId = raw?.run_id ?? raw?.runId;
+  const verificationRunId = raw?.verification_run_id ?? raw?.verificationRunId;
+  const jobId = raw?.job_id ?? raw?.jobId;
+  const suggestedAction = raw?.suggested_action ?? raw?.suggestedAction;
   return {
     index,
     success: false,
     error,
     ...errorCode ? { errorCode } : {},
     ...typeof retryEligible === "boolean" ? { retryEligible } : {},
-    ...Number.isFinite(retryAfterSeconds2) && retryAfterSeconds2 >= 0 ? { retryAfterSeconds: retryAfterSeconds2 } : {}
+    ...Number.isFinite(retryAfterSeconds2) && retryAfterSeconds2 >= 0 ? { retryAfterSeconds: retryAfterSeconds2 } : {},
+    ...retryStrategy === "new_idempotency_key" ? { retryStrategy } : {},
+    ...creditsUsed === 0 ? { creditsUsed: 0 } : {},
+    ...creditsCharged === 0 ? { creditsCharged: 0 } : {},
+    ...typeof runId === "string" && runId.trim() ? { runId: runId.trim() } : {},
+    ...typeof verificationRunId === "string" && verificationRunId.trim() ? { verificationRunId: verificationRunId.trim() } : {},
+    ...typeof jobId === "string" && jobId.trim() ? { jobId: jobId.trim() } : {},
+    ...typeof suggestedAction === "string" && suggestedAction.trim() ? { suggestedAction: suggestedAction.trim() } : {}
   };
 }
 function recoverableJobRowFailed(row) {
@@ -916,6 +975,7 @@ function compact(input) {
 }
 function findEmailRequestBody(params) {
   return compact({
+    run_id: params.runId,
     company_domain: params.companyDomain,
     full_name: params.fullName,
     first_name: params.firstName,
@@ -955,6 +1015,7 @@ function normalizeCoreProductDryRunResult(data) {
   };
 }
 function normalizeFindEmailResult(data) {
+  const processing = String(data.status || "").toLowerCase() === "processing";
   const failed = coreProductResponseFailed(data);
   const rawEmail = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const email = failed ? null : rawEmail;
@@ -967,7 +1028,7 @@ function normalizeFindEmailResult(data) {
   const verified = !explicitlyNotSendSafe && (data.is_valid === true || data.isValid === true || data.email_verified === true || data.verified_for_sending === true || ["valid", "deliverable"].includes(String(verificationStatus).toLowerCase()));
   const verificationAgeDays = typeof data.verification_age_days === "number" && Number.isFinite(data.verification_age_days) ? data.verification_age_days : null;
   return {
-    success: !failed && found,
+    success: processing || !failed && found,
     found,
     email,
     firstName: data.first_name,
@@ -994,8 +1055,12 @@ function normalizeFindEmailResult(data) {
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
     byoOpenrouterUsed: data.byo_openrouter_used,
-    error: found ? void 0 : coreProductErrorMessage(data) ?? "No verified email found",
-    errorCode: found ? void 0 : coreProductErrorCode(data) ?? "EMAIL_NOT_FOUND",
+    error: processing || found ? void 0 : coreProductErrorMessage(data) ?? "No verified email found",
+    errorCode: processing || found ? void 0 : coreProductErrorCode(data) ?? "EMAIL_NOT_FOUND",
+    status: processing ? "processing" : "completed",
+    runId: data.run_id,
+    nextPollAfterSeconds: data.next_poll_after_seconds,
+    suggestedAction: data.suggested_action,
     raw: data
   };
 }
@@ -1131,6 +1196,12 @@ function validateSignalDiscoveryParams(params) {
   if (query && (query.length < 2 || query.length > 2e3)) {
     throw new RangeError("query must contain between 2 and 2000 characters");
   }
+  if (params.icpContext !== void 0) {
+    const icpContext = typeof params.icpContext === "string" ? params.icpContext.trim() : "";
+    if (icpContext.length < 2 || icpContext.length > 4e3) {
+      throw new RangeError("icpContext must contain between 2 and 4000 characters");
+    }
+  }
   if (params.limit !== void 0 && (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 1e3)) {
     throw new RangeError("limit must be an integer between 1 and 1000");
   }
@@ -1155,6 +1226,7 @@ function signalDiscoveryRequestBody(params) {
   }
   return compact({
     query: params.query?.trim(),
+    icp_context: params.icpContext?.trim(),
     limit: params.limit ?? 100,
     sources: params.sources,
     lookback_days: params.lookbackDays,
@@ -1180,6 +1252,8 @@ function normalizeSignalDiscoveryResult(params, data) {
     availableCompanySignalCount: Number.isFinite(Number(data.available_company_signal_count)) ? Number(data.available_company_signal_count) : void 0,
     sourceLanes: Array.isArray(data.source_lanes) ? data.source_lanes.filter((lane) => typeof lane === "string") : void 0,
     evidenceValidation: data.evidence_validation && typeof data.evidence_validation === "object" ? data.evidence_validation : void 0,
+    discoveryDiagnostics: data.discovery_diagnostics && typeof data.discovery_diagnostics === "object" ? data.discovery_diagnostics : void 0,
+    identityResolution: data.identity_resolution && typeof data.identity_resolution === "object" ? data.identity_resolution : void 0,
     costGuardrail: normalizeSignalDiscoveryCostGuardrail(data.cost_guardrail),
     warnings: Array.isArray(data.warnings) ? data.warnings.filter((warning) => typeof warning === "string") : void 0,
     raw: data
@@ -1208,7 +1282,15 @@ function normalizeSignalDiscoveryCostGuardrail(value) {
       guardrail.projected_cost_per_requested_company_signal_usd
     ),
     sourceCostUsd: numberOrNullable(guardrail.source_cost_usd),
-    costSource: ["observed", "catalog_bounded", "mixed", "unavailable"].includes(String(guardrail.cost_source)) ? String(guardrail.cost_source) : void 0,
+    costSource: ["observed", "catalog_preflight", "catalog_bounded", "mixed", "unavailable"].includes(String(guardrail.cost_source)) ? String(guardrail.cost_source) : void 0,
+    identityResolutionCostUsd: numberOrNullable(guardrail.identity_resolution_cost_usd),
+    identityCostSource: [
+      "observed_zero_credit_receipts",
+      "contractual_zero_cost",
+      "not_used",
+      "unavailable"
+    ].includes(String(guardrail.identity_cost_source)) ? String(guardrail.identity_cost_source) : void 0,
+    identityProviderRequests: numberOrUndefined(guardrail.identity_provider_requests),
     qualifiedCompanySignalCount: numberOrUndefined(guardrail.qualified_company_signal_count),
     returnedCompanySignalCount: numberOrUndefined(guardrail.returned_company_signal_count),
     availableCompanySignalCount: numberOrUndefined(guardrail.available_company_signal_count),
@@ -1312,6 +1394,7 @@ function normalizedFindEmailBatchName(request) {
 function coreProductBatchRequestKey(path, request) {
   if (path === "api/v1/find-email") {
     return JSON.stringify([
+      normalizedBatchText(request.run_id),
       normalizedFindEmailBatchName(request),
       normalizedBatchDomain(request.company_domain),
       normalizedBatchLinkedIn(request.linkedin_url),
@@ -1417,6 +1500,7 @@ function signalToCopyRequestBody(params) {
     title: params.title,
     campaign_offer: params.campaignOffer,
     research_prompt: params.researchPrompt,
+    lookback_days: params.lookbackDays,
     signal_run_id: params.signalRunId,
     skip_cache: params.skipCache,
     enable_deep_search: params.enableDeepSearch,
@@ -1427,6 +1511,9 @@ function signalToCopyRequestBody(params) {
 }
 function validateSignalToCopyParams(params) {
   validateCoreProductMaxWaitMs(params.maxWaitMs);
+  if (params.lookbackDays !== void 0 && (!Number.isInteger(params.lookbackDays) || params.lookbackDays < 1 || params.lookbackDays > 365)) {
+    throw new RangeError("lookbackDays must be an integer between 1 and 365");
+  }
   if (typeof params.signalRunId === "string" && params.signalRunId.trim()) return;
   const missing = [
     ["companyDomain", params.companyDomain],

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   Signaliz,
   SignalizError
-} from "./chunk-VKBUQTDS.mjs";
+} from "./chunk-ENA7AVFB.mjs";
 export {
   Signaliz,
   SignalizError

package/dist/mcp-config.js

@@ -40,17 +40,21 @@ var SignalizError = class extends Error {
     this.details = data.details;
   }
   get isRetryable() {
+    if (typeof this.details?.retry_eligible === "boolean") {
+      return this.details.retry_eligible;
+    }
     return this.errorType === "rate_limited" || this.errorType === "timeout" || this.errorType === "provider_error";
   }
 };
 function parseError(status, body) {
   if (body?.error && typeof body.error === "object") {
+    const nestedDetails = body.error.details && typeof body.error.details === "object" ? body.error.details : {};
     return new SignalizError({
       code: body.error.code || `HTTP_${status}`,
       message: body.error.message || `Request failed with status ${status}`,
       errorType: mapErrorType(body.error.code, status),
       retryAfter: retryAfterSeconds(body.error),
-      details: body.error.details
+      details: mergePublicErrorDetails({ ...body, ...body.error }, nestedDetails)
     });
   }
   const code = typeof body?.error_code === "string" && body.error_code.trim() ? body.error_code.trim() : `HTTP_${status}`;
@@ -59,7 +63,7 @@ function parseError(status, body) {
     message: body?.message || body?.error || `Request failed with status ${status}`,
     errorType: mapErrorType(code, status),
     retryAfter: retryAfterSeconds(body),
-    details: body?.details || publicRetryDetails(body)
+    details: mergePublicErrorDetails(body, body?.details)
   });
 }
 function retryAfterSeconds(body) {
@@ -71,13 +75,26 @@ function publicRetryDetails(body) {
     ...body?.retry_eligible !== void 0 ? { retry_eligible: body.retry_eligible } : {},
     ...body?.retry_after !== void 0 ? { retry_after: body.retry_after } : {},
     ...body?.retry_after_seconds !== void 0 ? { retry_after_seconds: body.retry_after_seconds } : {},
+    ...body?.retry_strategy !== void 0 ? { retry_strategy: body.retry_strategy } : {},
+    ...body?.credits_used !== void 0 ? { credits_used: body.credits_used } : {},
+    ...body?.credits_charged !== void 0 ? { credits_charged: body.credits_charged } : {},
+    ...body?.job_id !== void 0 ? { job_id: body.job_id } : {},
+    ...body?.verification_run_id !== void 0 ? { verification_run_id: body.verification_run_id } : {},
     ...body?.run_id !== void 0 ? { run_id: body.run_id } : {},
+    ...body?.suggested_action !== void 0 ? { suggested_action: body.suggested_action } : {},
     ...body?.signal_run_id !== void 0 ? { signal_run_id: body.signal_run_id } : {},
     ...body?.company_signal_run_id !== void 0 ? { company_signal_run_id: body.company_signal_run_id } : {},
     ...body?.resume_context_persisted !== void 0 ? { resume_context_persisted: body.resume_context_persisted } : {}
   };
   return Object.keys(details).length > 0 ? details : void 0;
 }
+function mergePublicErrorDetails(body, explicitDetails) {
+  const merged = { ...publicRetryDetails(body) || {} };
+  if (explicitDetails && typeof explicitDetails === "object" && !Array.isArray(explicitDetails)) {
+    Object.assign(merged, explicitDetails);
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
 function mapErrorType(code, status) {
   if (code === "RATE_LIMITED" || status === 429) return "rate_limited";
   if (code === "VALIDATION_ERROR" || code === "SIGNAL_RUN_COMPANY_MISMATCH" || status === 400) return "validation";
@@ -139,7 +156,9 @@ var HttpClient = class {
           const errBody = await res.json().catch(() => ({}));
           const err = parseError(res.status, errBody);
           if (err.isRetryable && attempt < this.maxRetries) {
-            const wait = err.retryAfter ? err.retryAfter * 1e3 : Math.min(1e3 * Math.pow(2, attempt), 1e4);
+            const retryWithNewKey = err.details?.retry_strategy === "new_idempotency_key" && err.details?.credits_used === 0 && err.details?.credits_charged === 0;
+            if (retryWithNewKey) throw err;
+            const wait = err.retryAfter !== void 0 ? err.retryAfter * 1e3 : Math.min(1e3 * Math.pow(2, attempt), 1e4);
             await sleep(wait);
             lastError = err;
             continue;
@@ -439,6 +458,29 @@ var Signaliz = class {
     );
   }
   async verifyEmail(email, options) {
+    const normalizedEmail = typeof email === "string" ? email.trim() : "";
+    if (options?.dryRun !== true && !options?.verificationRunId && normalizedEmail && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalizedEmail)) {
+      const error = `Invalid email format: "${normalizedEmail}"`;
+      return normalizeVerifyEmailResult(normalizedEmail, {
+        success: false,
+        email: normalizedEmail,
+        status: "completed",
+        is_valid: false,
+        is_deliverable: false,
+        email_verified: false,
+        verified_for_sending: false,
+        is_malformed: true,
+        verification_status: "malformed",
+        verification_verdict: "malformed",
+        verification_source: "input_validation",
+        provider_status: "rejected_before_provider",
+        error,
+        error_code: "INPUT_001",
+        retry_eligible: false,
+        credits_used: 0,
+        live_provider_called: false
+      });
+    }
     const request = compact({
       email: email || void 0,
       verification_run_id: options?.verificationRunId,
@@ -773,7 +815,10 @@ var Signaliz = class {
     );
     const uniqueTasks = deduplicated.uniqueItems;
     const recoverableBatch = path2 === "api/v1/find-email" ? { label: "Find Email", pageSize: 500, maxWaitMs: 20 * 6e4 } : path2 === "api/v1/verify-email" ? { label: "Verify Email", pageSize: 500, maxWaitMs: 20 * 6e4 } : void 0;
-    if (path2 !== "api/v1/company-signals" && recoverableBatch && uniqueTasks.length > 25) {
+    const containsFindRecoveryReads = path2 === "api/v1/find-email" && uniqueTasks.some(
+      (task) => typeof task.request.run_id === "string" && task.request.run_id.trim()
+    );
+    if (path2 !== "api/v1/company-signals" && recoverableBatch && uniqueTasks.length > 25 && !containsFindRecoveryReads) {
       const rows = await this.runRecoverableCoreBatchJob(
         path2,
         uniqueTasks.map((task) => task.request),
@@ -899,13 +944,27 @@ function batchItemFailure(index, error, raw) {
     raw?.retry_after_seconds ?? raw?.retry_after ?? raw?.retryAfterSeconds ?? (Number.isFinite(Number(raw?.retry_after_ms)) ? Number(raw?.retry_after_ms) / 1e3 : void 0)
   );
   const retryEligible = raw?.retry_eligible ?? raw?.retryEligible;
+  const retryStrategy = raw?.retry_strategy ?? raw?.retryStrategy;
+  const creditsUsed = raw?.credits_used ?? raw?.creditsUsed;
+  const creditsCharged = raw?.credits_charged ?? raw?.creditsCharged;
+  const runId = raw?.run_id ?? raw?.runId;
+  const verificationRunId = raw?.verification_run_id ?? raw?.verificationRunId;
+  const jobId = raw?.job_id ?? raw?.jobId;
+  const suggestedAction = raw?.suggested_action ?? raw?.suggestedAction;
   return {
     index,
     success: false,
     error,
     ...errorCode ? { errorCode } : {},
     ...typeof retryEligible === "boolean" ? { retryEligible } : {},
-    ...Number.isFinite(retryAfterSeconds2) && retryAfterSeconds2 >= 0 ? { retryAfterSeconds: retryAfterSeconds2 } : {}
+    ...Number.isFinite(retryAfterSeconds2) && retryAfterSeconds2 >= 0 ? { retryAfterSeconds: retryAfterSeconds2 } : {},
+    ...retryStrategy === "new_idempotency_key" ? { retryStrategy } : {},
+    ...creditsUsed === 0 ? { creditsUsed: 0 } : {},
+    ...creditsCharged === 0 ? { creditsCharged: 0 } : {},
+    ...typeof runId === "string" && runId.trim() ? { runId: runId.trim() } : {},
+    ...typeof verificationRunId === "string" && verificationRunId.trim() ? { verificationRunId: verificationRunId.trim() } : {},
+    ...typeof jobId === "string" && jobId.trim() ? { jobId: jobId.trim() } : {},
+    ...typeof suggestedAction === "string" && suggestedAction.trim() ? { suggestedAction: suggestedAction.trim() } : {}
   };
 }
 function recoverableJobRowFailed(row) {
@@ -920,6 +979,7 @@ function compact(input) {
 }
 function findEmailRequestBody(params) {
   return compact({
+    run_id: params.runId,
     company_domain: params.companyDomain,
     full_name: params.fullName,
     first_name: params.firstName,
@@ -959,6 +1019,7 @@ function normalizeCoreProductDryRunResult(data) {
   };
 }
 function normalizeFindEmailResult(data) {
+  const processing = String(data.status || "").toLowerCase() === "processing";
   const failed = coreProductResponseFailed(data);
   const rawEmail = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const email = failed ? null : rawEmail;
@@ -971,7 +1032,7 @@ function normalizeFindEmailResult(data) {
   const verified = !explicitlyNotSendSafe && (data.is_valid === true || data.isValid === true || data.email_verified === true || data.verified_for_sending === true || ["valid", "deliverable"].includes(String(verificationStatus).toLowerCase()));
   const verificationAgeDays = typeof data.verification_age_days === "number" && Number.isFinite(data.verification_age_days) ? data.verification_age_days : null;
   return {
-    success: !failed && found,
+    success: processing || !failed && found,
     found,
     email,
     firstName: data.first_name,
@@ -998,8 +1059,12 @@ function normalizeFindEmailResult(data) {
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
     byoOpenrouterUsed: data.byo_openrouter_used,
-    error: found ? void 0 : coreProductErrorMessage(data) ?? "No verified email found",
-    errorCode: found ? void 0 : coreProductErrorCode(data) ?? "EMAIL_NOT_FOUND",
+    error: processing || found ? void 0 : coreProductErrorMessage(data) ?? "No verified email found",
+    errorCode: processing || found ? void 0 : coreProductErrorCode(data) ?? "EMAIL_NOT_FOUND",
+    status: processing ? "processing" : "completed",
+    runId: data.run_id,
+    nextPollAfterSeconds: data.next_poll_after_seconds,
+    suggestedAction: data.suggested_action,
     raw: data
   };
 }
@@ -1135,6 +1200,12 @@ function validateSignalDiscoveryParams(params) {
   if (query && (query.length < 2 || query.length > 2e3)) {
     throw new RangeError("query must contain between 2 and 2000 characters");
   }
+  if (params.icpContext !== void 0) {
+    const icpContext = typeof params.icpContext === "string" ? params.icpContext.trim() : "";
+    if (icpContext.length < 2 || icpContext.length > 4e3) {
+      throw new RangeError("icpContext must contain between 2 and 4000 characters");
+    }
+  }
   if (params.limit !== void 0 && (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 1e3)) {
     throw new RangeError("limit must be an integer between 1 and 1000");
   }
@@ -1159,6 +1230,7 @@ function signalDiscoveryRequestBody(params) {
   }
   return compact({
     query: params.query?.trim(),
+    icp_context: params.icpContext?.trim(),
     limit: params.limit ?? 100,
     sources: params.sources,
     lookback_days: params.lookbackDays,
@@ -1184,6 +1256,8 @@ function normalizeSignalDiscoveryResult(params, data) {
     availableCompanySignalCount: Number.isFinite(Number(data.available_company_signal_count)) ? Number(data.available_company_signal_count) : void 0,
     sourceLanes: Array.isArray(data.source_lanes) ? data.source_lanes.filter((lane) => typeof lane === "string") : void 0,
     evidenceValidation: data.evidence_validation && typeof data.evidence_validation === "object" ? data.evidence_validation : void 0,
+    discoveryDiagnostics: data.discovery_diagnostics && typeof data.discovery_diagnostics === "object" ? data.discovery_diagnostics : void 0,
+    identityResolution: data.identity_resolution && typeof data.identity_resolution === "object" ? data.identity_resolution : void 0,
     costGuardrail: normalizeSignalDiscoveryCostGuardrail(data.cost_guardrail),
     warnings: Array.isArray(data.warnings) ? data.warnings.filter((warning) => typeof warning === "string") : void 0,
     raw: data
@@ -1212,7 +1286,15 @@ function normalizeSignalDiscoveryCostGuardrail(value) {
       guardrail.projected_cost_per_requested_company_signal_usd
     ),
     sourceCostUsd: numberOrNullable(guardrail.source_cost_usd),
-    costSource: ["observed", "catalog_bounded", "mixed", "unavailable"].includes(String(guardrail.cost_source)) ? String(guardrail.cost_source) : void 0,
+    costSource: ["observed", "catalog_preflight", "catalog_bounded", "mixed", "unavailable"].includes(String(guardrail.cost_source)) ? String(guardrail.cost_source) : void 0,
+    identityResolutionCostUsd: numberOrNullable(guardrail.identity_resolution_cost_usd),
+    identityCostSource: [
+      "observed_zero_credit_receipts",
+      "contractual_zero_cost",
+      "not_used",
+      "unavailable"
+    ].includes(String(guardrail.identity_cost_source)) ? String(guardrail.identity_cost_source) : void 0,
+    identityProviderRequests: numberOrUndefined(guardrail.identity_provider_requests),
     qualifiedCompanySignalCount: numberOrUndefined(guardrail.qualified_company_signal_count),
     returnedCompanySignalCount: numberOrUndefined(guardrail.returned_company_signal_count),
     availableCompanySignalCount: numberOrUndefined(guardrail.available_company_signal_count),
@@ -1316,6 +1398,7 @@ function normalizedFindEmailBatchName(request) {
 function coreProductBatchRequestKey(path2, request) {
   if (path2 === "api/v1/find-email") {
     return JSON.stringify([
+      normalizedBatchText(request.run_id),
       normalizedFindEmailBatchName(request),
       normalizedBatchDomain(request.company_domain),
       normalizedBatchLinkedIn(request.linkedin_url),
@@ -1421,6 +1504,7 @@ function signalToCopyRequestBody(params) {
     title: params.title,
     campaign_offer: params.campaignOffer,
     research_prompt: params.researchPrompt,
+    lookback_days: params.lookbackDays,
     signal_run_id: params.signalRunId,
     skip_cache: params.skipCache,
     enable_deep_search: params.enableDeepSearch,
@@ -1431,6 +1515,9 @@ function signalToCopyRequestBody(params) {
 }
 function validateSignalToCopyParams(params) {
   validateCoreProductMaxWaitMs(params.maxWaitMs);
+  if (params.lookbackDays !== void 0 && (!Number.isInteger(params.lookbackDays) || params.lookbackDays < 1 || params.lookbackDays > 365)) {
+    throw new RangeError("lookbackDays must be an integer between 1 and 365");
+  }
   if (typeof params.signalRunId === "string" && params.signalRunId.trim()) return;
   const missing = [
     ["companyDomain", params.companyDomain],

package/dist/mcp-config.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   Signaliz
-} from "./chunk-VKBUQTDS.mjs";
+} from "./chunk-ENA7AVFB.mjs";
 
 // src/mcp-config.ts
 import * as fs from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaliz/sdk",
-  "version": "1.0.59",
+  "version": "1.0.61",
   "description": "Signaliz SDK for Signals Everything, Find Email, Verify Email, Company Signal Enrichment, and Signal to Copy AI.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",