@signaliz/sdk 1.0.38 → 1.0.39

package/README.md

@@ -32,6 +32,16 @@ const verified = await signaliz.verifyEmail(found.email!, {
   skipCache: true,
 });
 
+// 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', {
+  skipCache: true,
+  waitForResult: false,
+});
+const resumedVerification = await signaliz.verifyEmail('jane@example.com', {
+  verificationRunId: queuedVerification.verificationRunId,
+});
+
 const signals = await signaliz.enrichCompanySignals({
   companyDomain: 'example.com',
   researchPrompt: 'expansion priorities',

package/dist/{chunk-ZIYVY22X.mjs → chunk-UVW5N4LW.mjs}

@@ -376,11 +376,28 @@ var Signaliz = class {
     );
   }
   async verifyEmail(email, options) {
-    const data = await this.client.post("api/v1/verify-email", {
-      email,
+    const request = compact({
+      email: email || void 0,
+      verification_run_id: options?.verificationRunId,
       skip_cache: options?.skipCache
     });
-    return normalizeVerifyEmailResult(email, data);
+    let data = await this.client.post("api/v1/verify-email", request);
+    if (options?.waitForResult !== false && isPendingSignalResponse(data) && data.verification_run_id) {
+      const maxWaitMs = Math.max(1e3, options?.maxWaitMs ?? 10 * 6e4);
+      const startedAt = Date.now();
+      while (Date.now() - startedAt < maxWaitMs) {
+        if (!await waitForNextSignalPoll(data, options?.pollIntervalMs, startedAt, maxWaitMs)) break;
+        data = await this.client.post("api/v1/verify-email", compact({
+          email: email || void 0,
+          verification_run_id: data.verification_run_id
+        }));
+        if (!isPendingSignalResponse(data)) break;
+      }
+      if (isPendingSignalResponse(data)) {
+        throw new Error(`Email verification ${data.verification_run_id} did not complete within ${maxWaitMs}ms`);
+      }
+    }
+    return normalizeVerifyEmailResult(email || "", data);
   }
   async verifyEmails(emails, options) {
     validateBatchSize(emails);
@@ -868,6 +885,10 @@ function normalizeVerifyEmailResult(email, data) {
   const verified = data.email_verified === true || ["valid", "deliverable"].includes(verificationStatus);
   return {
     email: data.email ?? email,
+    status: String(data.status || "").toLowerCase() === "processing" ? "processing" : "completed",
+    verificationRunId: data.verification_run_id ?? data.run_id,
+    retryAfterMs: data.retry_after_ms,
+    nextPollAfterSeconds: data.next_poll_after_seconds,
     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,

package/dist/index.d.mts

@@ -69,6 +69,12 @@ interface FindEmailResult {
 }
 interface VerifyEmailResult {
     email: string;
+    /** Execution state. Processing results are never send-safe. */
+    status: 'processing' | 'completed';
+    /** Durable Trigger run id for resuming a long verification. */
+    verificationRunId?: string;
+    retryAfterMs?: number;
+    nextPollAfterSeconds?: number;
     isValid: boolean;
     isDeliverable: boolean;
     isCatchAll: boolean;
@@ -80,6 +86,14 @@ interface VerifyEmailResult {
 interface VerifyEmailOptions {
     /** Bypass cached verification data for a fresh-provider quality check. */
     skipCache?: boolean;
+    /** Resume an existing long verification without another provider call. */
+    verificationRunId?: string;
+    /** Wait for a processing verification to finish. Defaults to true. */
+    waitForResult?: boolean;
+    /** Maximum time to wait for a processing verification. Defaults to 10 minutes. */
+    maxWaitMs?: number;
+    /** Override the server-provided polling delay. */
+    pollIntervalMs?: number;
 }
 interface VerifyEmailBatchOptions extends BatchOptions, VerifyEmailOptions {
 }
@@ -204,7 +218,7 @@ declare class Signaliz {
     constructor(config: SignalizConfig);
     findEmail(params: FindEmailParams): Promise<FindEmailResult>;
     findEmails(params: FindEmailParams[], options?: BatchOptions): Promise<BatchResult<FindEmailResult>>;
-    verifyEmail(email: string, options?: VerifyEmailOptions): Promise<VerifyEmailResult>;
+    verifyEmail(email: string | undefined, options?: VerifyEmailOptions): Promise<VerifyEmailResult>;
     verifyEmails(emails: string[], options?: VerifyEmailBatchOptions): Promise<BatchResult<VerifyEmailResult>>;
     enrichCompanySignals(params: CompanySignalEnrichmentParams): Promise<CompanySignalEnrichmentResult>;
     enrichCompanies(companies: CompanySignalEnrichmentParams[], options?: BatchOptions): Promise<BatchResult<CompanySignalEnrichmentResult>>;

package/dist/index.d.ts

@@ -69,6 +69,12 @@ interface FindEmailResult {
 }
 interface VerifyEmailResult {
     email: string;
+    /** Execution state. Processing results are never send-safe. */
+    status: 'processing' | 'completed';
+    /** Durable Trigger run id for resuming a long verification. */
+    verificationRunId?: string;
+    retryAfterMs?: number;
+    nextPollAfterSeconds?: number;
     isValid: boolean;
     isDeliverable: boolean;
     isCatchAll: boolean;
@@ -80,6 +86,14 @@ interface VerifyEmailResult {
 interface VerifyEmailOptions {
     /** Bypass cached verification data for a fresh-provider quality check. */
     skipCache?: boolean;
+    /** Resume an existing long verification without another provider call. */
+    verificationRunId?: string;
+    /** Wait for a processing verification to finish. Defaults to true. */
+    waitForResult?: boolean;
+    /** Maximum time to wait for a processing verification. Defaults to 10 minutes. */
+    maxWaitMs?: number;
+    /** Override the server-provided polling delay. */
+    pollIntervalMs?: number;
 }
 interface VerifyEmailBatchOptions extends BatchOptions, VerifyEmailOptions {
 }
@@ -204,7 +218,7 @@ declare class Signaliz {
     constructor(config: SignalizConfig);
     findEmail(params: FindEmailParams): Promise<FindEmailResult>;
     findEmails(params: FindEmailParams[], options?: BatchOptions): Promise<BatchResult<FindEmailResult>>;
-    verifyEmail(email: string, options?: VerifyEmailOptions): Promise<VerifyEmailResult>;
+    verifyEmail(email: string | undefined, options?: VerifyEmailOptions): Promise<VerifyEmailResult>;
     verifyEmails(emails: string[], options?: VerifyEmailBatchOptions): Promise<BatchResult<VerifyEmailResult>>;
     enrichCompanySignals(params: CompanySignalEnrichmentParams): Promise<CompanySignalEnrichmentResult>;
     enrichCompanies(companies: CompanySignalEnrichmentParams[], options?: BatchOptions): Promise<BatchResult<CompanySignalEnrichmentResult>>;

package/dist/index.js

@@ -403,11 +403,28 @@ var Signaliz = class {
     );
   }
   async verifyEmail(email, options) {
-    const data = await this.client.post("api/v1/verify-email", {
-      email,
+    const request = compact({
+      email: email || void 0,
+      verification_run_id: options?.verificationRunId,
       skip_cache: options?.skipCache
     });
-    return normalizeVerifyEmailResult(email, data);
+    let data = await this.client.post("api/v1/verify-email", request);
+    if (options?.waitForResult !== false && isPendingSignalResponse(data) && data.verification_run_id) {
+      const maxWaitMs = Math.max(1e3, options?.maxWaitMs ?? 10 * 6e4);
+      const startedAt = Date.now();
+      while (Date.now() - startedAt < maxWaitMs) {
+        if (!await waitForNextSignalPoll(data, options?.pollIntervalMs, startedAt, maxWaitMs)) break;
+        data = await this.client.post("api/v1/verify-email", compact({
+          email: email || void 0,
+          verification_run_id: data.verification_run_id
+        }));
+        if (!isPendingSignalResponse(data)) break;
+      }
+      if (isPendingSignalResponse(data)) {
+        throw new Error(`Email verification ${data.verification_run_id} did not complete within ${maxWaitMs}ms`);
+      }
+    }
+    return normalizeVerifyEmailResult(email || "", data);
   }
   async verifyEmails(emails, options) {
     validateBatchSize(emails);
@@ -895,6 +912,10 @@ function normalizeVerifyEmailResult(email, data) {
   const verified = data.email_verified === true || ["valid", "deliverable"].includes(verificationStatus);
   return {
     email: data.email ?? email,
+    status: String(data.status || "").toLowerCase() === "processing" ? "processing" : "completed",
+    verificationRunId: data.verification_run_id ?? data.run_id,
+    retryAfterMs: data.retry_after_ms,
+    nextPollAfterSeconds: data.next_poll_after_seconds,
     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,

package/dist/index.mjs

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

package/dist/mcp-config.js

@@ -407,11 +407,28 @@ var Signaliz = class {
     );
   }
   async verifyEmail(email, options) {
-    const data = await this.client.post("api/v1/verify-email", {
-      email,
+    const request = compact({
+      email: email || void 0,
+      verification_run_id: options?.verificationRunId,
       skip_cache: options?.skipCache
     });
-    return normalizeVerifyEmailResult(email, data);
+    let data = await this.client.post("api/v1/verify-email", request);
+    if (options?.waitForResult !== false && isPendingSignalResponse(data) && data.verification_run_id) {
+      const maxWaitMs = Math.max(1e3, options?.maxWaitMs ?? 10 * 6e4);
+      const startedAt = Date.now();
+      while (Date.now() - startedAt < maxWaitMs) {
+        if (!await waitForNextSignalPoll(data, options?.pollIntervalMs, startedAt, maxWaitMs)) break;
+        data = await this.client.post("api/v1/verify-email", compact({
+          email: email || void 0,
+          verification_run_id: data.verification_run_id
+        }));
+        if (!isPendingSignalResponse(data)) break;
+      }
+      if (isPendingSignalResponse(data)) {
+        throw new Error(`Email verification ${data.verification_run_id} did not complete within ${maxWaitMs}ms`);
+      }
+    }
+    return normalizeVerifyEmailResult(email || "", data);
   }
   async verifyEmails(emails, options) {
     validateBatchSize(emails);
@@ -899,6 +916,10 @@ function normalizeVerifyEmailResult(email, data) {
   const verified = data.email_verified === true || ["valid", "deliverable"].includes(verificationStatus);
   return {
     email: data.email ?? email,
+    status: String(data.status || "").toLowerCase() === "processing" ? "processing" : "completed",
+    verificationRunId: data.verification_run_id ?? data.run_id,
+    retryAfterMs: data.retry_after_ms,
+    nextPollAfterSeconds: data.next_poll_after_seconds,
     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,

package/dist/mcp-config.mjs

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

package/package.json

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