@signaliz/sdk 1.0.38 → 1.0.40

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-A7B63XMZ.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,
@@ -923,15 +944,16 @@ function companySignalRecoverableBatchOptions(companies, tasks) {
   return { label: "Company Signals", pageSize: 25, maxWaitMs };
 }
 function normalizeCompanySignalResult(params, data) {
+  const rawSignals = data.signals ?? data.signal_feed ?? [];
   return {
     success: data.success ?? true,
     status: data.status,
-    signalRunId: data.signal_run_id ?? data.run_id,
+    signalRunId: data.signal_run_id ?? data.run_id ?? params.signalRunId,
     company: {
       name: data.company?.name ?? params.companyName ?? null,
       domain: data.company?.domain ?? params.companyDomain ?? null
     },
-    signals: (data.signals ?? []).map((signal) => {
+    signals: rawSignals.map((signal) => {
       const metadata = signal.metadata && typeof signal.metadata === "object" && !Array.isArray(signal.metadata) ? signal.metadata : void 0;
       return {
         id: signal.id,
@@ -955,9 +977,20 @@ function normalizeCompanySignalResult(params, data) {
         metadata
       };
     }),
-    signalCount: data.signal_count ?? data.total_signals ?? data.signals?.length ?? 0,
+    signalCount: data.signal_count ?? data.total_signals ?? rawSignals.length,
+    signalSummary: data.signal_summary ?? null,
+    signalSummarySource: data.signal_summary_source,
     intelligence: data.intelligence ?? null,
+    copyFuel: data.copy_fuel ?? null,
+    evidenceValidation: data.evidence_validation,
+    evidenceSources: data.evidence_sources,
     credits: data.credits,
+    creditsUsed: data.credits_used,
+    costUsd: data.cost_usd,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    liveProviderCalled: data.live_provider_called,
     metadata: data.metadata,
     raw: data
   };

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 {
 }
@@ -136,8 +150,19 @@ interface CompanySignalEnrichmentResult {
     };
     signals: CompanySignal[];
     signalCount: number;
+    signalSummary: string | null;
+    signalSummarySource?: string;
     intelligence?: Record<string, unknown> | null;
+    copyFuel?: Record<string, unknown> | null;
+    evidenceValidation?: Record<string, unknown>;
+    evidenceSources?: Record<string, unknown>[];
     credits?: Record<string, unknown>;
+    creditsUsed?: number;
+    costUsd?: number;
+    billingMetadata?: Record<string, unknown>;
+    resultReturnedFrom?: string;
+    cacheHit?: boolean;
+    liveProviderCalled?: boolean;
     metadata?: Record<string, unknown>;
     raw: Record<string, unknown>;
 }
@@ -204,7 +229,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 {
 }
@@ -136,8 +150,19 @@ interface CompanySignalEnrichmentResult {
     };
     signals: CompanySignal[];
     signalCount: number;
+    signalSummary: string | null;
+    signalSummarySource?: string;
     intelligence?: Record<string, unknown> | null;
+    copyFuel?: Record<string, unknown> | null;
+    evidenceValidation?: Record<string, unknown>;
+    evidenceSources?: Record<string, unknown>[];
     credits?: Record<string, unknown>;
+    creditsUsed?: number;
+    costUsd?: number;
+    billingMetadata?: Record<string, unknown>;
+    resultReturnedFrom?: string;
+    cacheHit?: boolean;
+    liveProviderCalled?: boolean;
     metadata?: Record<string, unknown>;
     raw: Record<string, unknown>;
 }
@@ -204,7 +229,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,
@@ -950,15 +971,16 @@ function companySignalRecoverableBatchOptions(companies, tasks) {
   return { label: "Company Signals", pageSize: 25, maxWaitMs };
 }
 function normalizeCompanySignalResult(params, data) {
+  const rawSignals = data.signals ?? data.signal_feed ?? [];
   return {
     success: data.success ?? true,
     status: data.status,
-    signalRunId: data.signal_run_id ?? data.run_id,
+    signalRunId: data.signal_run_id ?? data.run_id ?? params.signalRunId,
     company: {
       name: data.company?.name ?? params.companyName ?? null,
       domain: data.company?.domain ?? params.companyDomain ?? null
     },
-    signals: (data.signals ?? []).map((signal) => {
+    signals: rawSignals.map((signal) => {
       const metadata = signal.metadata && typeof signal.metadata === "object" && !Array.isArray(signal.metadata) ? signal.metadata : void 0;
       return {
         id: signal.id,
@@ -982,9 +1004,20 @@ function normalizeCompanySignalResult(params, data) {
         metadata
       };
     }),
-    signalCount: data.signal_count ?? data.total_signals ?? data.signals?.length ?? 0,
+    signalCount: data.signal_count ?? data.total_signals ?? rawSignals.length,
+    signalSummary: data.signal_summary ?? null,
+    signalSummarySource: data.signal_summary_source,
     intelligence: data.intelligence ?? null,
+    copyFuel: data.copy_fuel ?? null,
+    evidenceValidation: data.evidence_validation,
+    evidenceSources: data.evidence_sources,
     credits: data.credits,
+    creditsUsed: data.credits_used,
+    costUsd: data.cost_usd,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    liveProviderCalled: data.live_provider_called,
     metadata: data.metadata,
     raw: data
   };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   Signaliz,
   SignalizError
-} from "./chunk-ZIYVY22X.mjs";
+} from "./chunk-A7B63XMZ.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,
@@ -954,15 +975,16 @@ function companySignalRecoverableBatchOptions(companies, tasks) {
   return { label: "Company Signals", pageSize: 25, maxWaitMs };
 }
 function normalizeCompanySignalResult(params, data) {
+  const rawSignals = data.signals ?? data.signal_feed ?? [];
   return {
     success: data.success ?? true,
     status: data.status,
-    signalRunId: data.signal_run_id ?? data.run_id,
+    signalRunId: data.signal_run_id ?? data.run_id ?? params.signalRunId,
     company: {
       name: data.company?.name ?? params.companyName ?? null,
       domain: data.company?.domain ?? params.companyDomain ?? null
     },
-    signals: (data.signals ?? []).map((signal) => {
+    signals: rawSignals.map((signal) => {
       const metadata = signal.metadata && typeof signal.metadata === "object" && !Array.isArray(signal.metadata) ? signal.metadata : void 0;
       return {
         id: signal.id,
@@ -986,9 +1008,20 @@ function normalizeCompanySignalResult(params, data) {
         metadata
       };
     }),
-    signalCount: data.signal_count ?? data.total_signals ?? data.signals?.length ?? 0,
+    signalCount: data.signal_count ?? data.total_signals ?? rawSignals.length,
+    signalSummary: data.signal_summary ?? null,
+    signalSummarySource: data.signal_summary_source,
     intelligence: data.intelligence ?? null,
+    copyFuel: data.copy_fuel ?? null,
+    evidenceValidation: data.evidence_validation,
+    evidenceSources: data.evidence_sources,
     credits: data.credits,
+    creditsUsed: data.credits_used,
+    costUsd: data.cost_usd,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    liveProviderCalled: data.live_provider_called,
     metadata: data.metadata,
     raw: data
   };

package/dist/mcp-config.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   Signaliz
-} from "./chunk-ZIYVY22X.mjs";
+} from "./chunk-A7B63XMZ.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.40",
   "description": "Signaliz SDK for Find Email, Verify Email, Company Signal Enrichment, and Signal to Copy AI.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",