@signaliz/sdk 1.0.46 → 1.0.47

package/README.md

@@ -20,6 +20,15 @@ const signaliz = new Signaliz({
   apiKey: process.env.SIGNALIZ_API_KEY,
 });
 
+// Every product supports a strict no-spend preflight. Batch methods accept the
+// same option and return one plan for the full input.
+const plan = await signaliz.findEmail({
+  companyDomain: 'example.com',
+  fullName: 'Jane Doe',
+  dryRun: true,
+});
+console.log(plan.estimatedCredits.max, plan.creditsCharged); // 2, 0
+
 const found = await signaliz.findEmail({
   companyDomain: 'example.com',
   fullName: 'Jane Doe',
@@ -104,8 +113,9 @@ Failed rows preserve `errorCode`, `retryEligible`, and `retryAfterSeconds`
 when the REST API supplies them, including after automatic row retries are
 exhausted.
 
-For an ambiguous submission failure, retry with the same
-`idempotencyKey` to recover the original job without duplicate work.
+For an ambiguous single request or batch submission failure, retry with the
+same `idempotencyKey` to recover the original request or 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;

package/dist/{chunk-4LXMT3S5.mjs → chunk-KTWDTUCI.mjs}

@@ -378,10 +378,17 @@ var Signaliz = class {
   }
   async findEmail(params) {
     const data = await this.client.post("api/v1/find-email", findEmailRequestBody(params));
-    return normalizeFindEmailResult(data);
+    return isCoreProductDryRun(data) ? normalizeCoreProductDryRunResult(data) : normalizeFindEmailResult(data);
   }
   async findEmails(params, options) {
     validateBatchSize(params);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/find-email",
+        params.map(findEmailRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const round = await this.runCoreBatchRound(
       "api/v1/find-email",
@@ -400,9 +407,12 @@ var Signaliz = class {
     const request = compact({
       email: email || void 0,
       verification_run_id: options?.verificationRunId,
-      skip_cache: options?.skipCache
+      skip_cache: options?.skipCache,
+      dry_run: options?.dryRun,
+      idempotency_key: options?.idempotencyKey
     });
     let data = await this.client.post("api/v1/verify-email", request);
+    if (isCoreProductDryRun(data)) return normalizeCoreProductDryRunResult(data);
     if (options?.waitForResult !== false && isPendingSignalResponse(data) && data.verification_run_id) {
       const maxWaitMs = Math.max(1e3, options?.maxWaitMs ?? 10 * 6e4);
       const startedAt = Date.now();
@@ -422,6 +432,13 @@ var Signaliz = class {
   }
   async verifyEmails(emails, options) {
     validateBatchSize(emails);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/verify-email",
+        emails.map((email) => ({ email, skip_cache: options.skipCache })),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const round = await this.runCoreBatchRound(
       "api/v1/verify-email",
@@ -442,6 +459,7 @@ var Signaliz = class {
   async enrichCompanySignals(params) {
     const request = companySignalRequestBody(params);
     let 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();
@@ -472,6 +490,13 @@ var Signaliz = class {
   }
   async enrichCompanies(companies, options) {
     validateBatchSize(companies);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/company-signals",
+        companies.map(companySignalRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const results = new Array(companies.length);
     const initialTasks = companies.map((params, index) => ({
@@ -549,6 +574,7 @@ var Signaliz = class {
     validateSignalToCopyParams(params);
     const request = signalToCopyRequestBody(params);
     let 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();
@@ -567,6 +593,13 @@ var Signaliz = class {
   async createSignalCopyBatch(requests, options) {
     validateBatchSize(requests);
     requests.forEach(validateSignalToCopyParams);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/signal-to-copy",
+        requests.map(signalToCopyRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const deduplicated = dedupeExactBatchItems(requests, (params) => JSON.stringify({
       request: signalToCopyRequestBody(params),
@@ -593,6 +626,17 @@ var Signaliz = class {
       results: compactedResults
     };
   }
+  async runCoreProductDryRun(path, requests, idempotencyKey) {
+    const data = await this.client.post(path, compact({
+      requests,
+      dry_run: true,
+      idempotency_key: idempotencyKey
+    }));
+    if (!isCoreProductDryRun(data)) {
+      throw new Error(`${path} dry run returned a live-result contract`);
+    }
+    return normalizeCoreProductDryRunResult(data);
+  }
   async runSignalCopyBatchChunks(uniqueRequests, options) {
     const chunks = [];
     for (let offset = 0; offset < uniqueRequests.length; offset += 25) {
@@ -951,9 +995,34 @@ function findEmailRequestBody(params) {
     last_name: params.lastName,
     linkedin_url: params.linkedinUrl,
     company_name: params.companyName,
-    skip_cache: params.skipCache
+    skip_cache: params.skipCache,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
+function isCoreProductDryRun(data) {
+  return data.dry_run === true && data.status === "planned";
+}
+function normalizeCoreProductDryRunResult(data) {
+  const estimatedCredits = data.estimated_credits && typeof data.estimated_credits === "object" ? data.estimated_credits : { min: 0, max: 0 };
+  return {
+    success: true,
+    dryRun: true,
+    status: "planned",
+    capability: String(data.capability || ""),
+    inputCount: Number(data.input_count || 0),
+    recoveryReadCount: Number(data.recovery_read_count || 0),
+    plan: data.plan && typeof data.plan === "object" ? data.plan : {},
+    estimate: data.estimate && typeof data.estimate === "object" ? data.estimate : {},
+    estimatedCredits: {
+      min: Number(estimatedCredits.min || 0),
+      max: Number(estimatedCredits.max || 0)
+    },
+    creditsCharged: 0,
+    sideEffects: Array.isArray(data.side_effects) ? data.side_effects : [],
+    raw: data
+  };
+}
 function normalizeFindEmailResult(data) {
   const email = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const found = Boolean(email) && data.found !== false;
@@ -1022,7 +1091,9 @@ function companySignalRequestBody(params) {
     // REST always returns a resumable run instead of holding the connection;
     // waitForResult controls the SDK polling loop.
     wait_for_result: false,
-    max_wait_ms: params.maxWaitMs
+    max_wait_ms: params.maxWaitMs,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
 function companySignalRecoverableBatchOptions(companies, tasks) {
@@ -1194,7 +1265,9 @@ function signalToCopyRequestBody(params) {
     research_prompt: params.researchPrompt,
     signal_run_id: params.signalRunId,
     skip_cache: params.skipCache,
-    enable_deep_search: params.enableDeepSearch
+    enable_deep_search: params.enableDeepSearch,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
 function validateSignalToCopyParams(params) {

package/dist/index.d.mts

@@ -13,6 +13,8 @@ interface BatchOptions {
     idempotencyKey?: string;
     /** Return exact repeated successes as duplicateOf references. Defaults to false. */
     compactDuplicates?: boolean;
+    /** Return one no-spend plan for the full batch without provider calls or jobs. */
+    dryRun?: boolean;
 }
 interface BatchItemResult<T> {
     index: number;
@@ -43,6 +45,23 @@ interface SignalizErrorData {
     retryAfter?: number;
     details?: Record<string, unknown>;
 }
+interface CoreProductDryRunResult {
+    success: true;
+    dryRun: true;
+    status: 'planned';
+    capability: string;
+    inputCount: number;
+    recoveryReadCount: number;
+    plan: Record<string, unknown>;
+    estimate: Record<string, unknown>;
+    estimatedCredits: {
+        min: number;
+        max: number;
+    };
+    creditsCharged: 0;
+    sideEffects: unknown[];
+    raw: Record<string, unknown>;
+}
 interface FindEmailParams {
     companyDomain: string;
     fullName?: string;
@@ -52,6 +71,10 @@ interface FindEmailParams {
     companyName?: string;
     /** Bypass cached email and verification data for a fresh-provider run. */
     skipCache?: boolean;
+    /** Return a no-spend plan without provider calls or jobs. */
+    dryRun?: boolean;
+    /** Stable retry key for recovering the same request after an ambiguous response. */
+    idempotencyKey?: string;
 }
 interface FindEmailResult {
     success: boolean;
@@ -100,6 +123,10 @@ interface VerifyEmailOptions {
     maxWaitMs?: number;
     /** Override the server-provided polling delay. */
     pollIntervalMs?: number;
+    /** Return a no-spend plan without provider calls or jobs. */
+    dryRun?: boolean;
+    /** Stable retry key for recovering the same request after an ambiguous response. */
+    idempotencyKey?: string;
 }
 interface VerifyEmailBatchOptions extends BatchOptions, VerifyEmailOptions {
 }
@@ -124,6 +151,10 @@ interface CompanySignalEnrichmentParams {
     maxWaitMs?: number;
     /** Delay between queued-enrichment status checks. Defaults to 2 seconds. */
     pollIntervalMs?: number;
+    /** Return a no-spend plan without provider calls or jobs. */
+    dryRun?: boolean;
+    /** Stable retry key for recovering the same request after an ambiguous response. */
+    idempotencyKey?: string;
 }
 interface CompanySignal {
     id?: string;
@@ -186,6 +217,10 @@ interface SignalToCopyParams {
     waitForResult?: boolean;
     maxWaitMs?: number;
     pollIntervalMs?: number;
+    /** Return a no-spend plan without provider calls or jobs. */
+    dryRun?: boolean;
+    /** Stable retry key for recovering the same request after an ambiguous response. */
+    idempotencyKey?: string;
 }
 interface SignalToCopyVariation {
     style: 'signal_led' | 'business_case' | 'predictive';
@@ -237,14 +272,39 @@ declare class SignalizError extends Error {
 declare class Signaliz {
     private readonly client;
     constructor(config: SignalizConfig);
+    findEmail(params: FindEmailParams & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     findEmail(params: FindEmailParams): Promise<FindEmailResult>;
+    findEmails(params: FindEmailParams[], options: BatchOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     findEmails(params: FindEmailParams[], options?: BatchOptions): Promise<BatchResult<FindEmailResult>>;
+    verifyEmail(email: string | undefined, options: VerifyEmailOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     verifyEmail(email: string | undefined, options?: VerifyEmailOptions): Promise<VerifyEmailResult>;
+    verifyEmails(emails: string[], options: VerifyEmailBatchOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     verifyEmails(emails: string[], options?: VerifyEmailBatchOptions): Promise<BatchResult<VerifyEmailResult>>;
+    enrichCompanySignals(params: CompanySignalEnrichmentParams & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     enrichCompanySignals(params: CompanySignalEnrichmentParams): Promise<CompanySignalEnrichmentResult>;
+    enrichCompanies(companies: CompanySignalEnrichmentParams[], options: BatchOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     enrichCompanies(companies: CompanySignalEnrichmentParams[], options?: BatchOptions): Promise<BatchResult<CompanySignalEnrichmentResult>>;
+    signalToCopy(params: SignalToCopyParams & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     signalToCopy(params: SignalToCopyParams): Promise<SignalToCopyResult>;
+    createSignalCopyBatch(requests: SignalToCopyParams[], options: BatchOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     createSignalCopyBatch(requests: SignalToCopyParams[], options?: BatchOptions): Promise<BatchResult<SignalToCopyResult>>;
+    private runCoreProductDryRun;
     private runSignalCopyBatchChunks;
     private runAvailableSignalCopyBatchJob;
     private runRecoverableCoreBatchJob;

package/dist/index.d.ts

@@ -13,6 +13,8 @@ interface BatchOptions {
     idempotencyKey?: string;
     /** Return exact repeated successes as duplicateOf references. Defaults to false. */
     compactDuplicates?: boolean;
+    /** Return one no-spend plan for the full batch without provider calls or jobs. */
+    dryRun?: boolean;
 }
 interface BatchItemResult<T> {
     index: number;
@@ -43,6 +45,23 @@ interface SignalizErrorData {
     retryAfter?: number;
     details?: Record<string, unknown>;
 }
+interface CoreProductDryRunResult {
+    success: true;
+    dryRun: true;
+    status: 'planned';
+    capability: string;
+    inputCount: number;
+    recoveryReadCount: number;
+    plan: Record<string, unknown>;
+    estimate: Record<string, unknown>;
+    estimatedCredits: {
+        min: number;
+        max: number;
+    };
+    creditsCharged: 0;
+    sideEffects: unknown[];
+    raw: Record<string, unknown>;
+}
 interface FindEmailParams {
     companyDomain: string;
     fullName?: string;
@@ -52,6 +71,10 @@ interface FindEmailParams {
     companyName?: string;
     /** Bypass cached email and verification data for a fresh-provider run. */
     skipCache?: boolean;
+    /** Return a no-spend plan without provider calls or jobs. */
+    dryRun?: boolean;
+    /** Stable retry key for recovering the same request after an ambiguous response. */
+    idempotencyKey?: string;
 }
 interface FindEmailResult {
     success: boolean;
@@ -100,6 +123,10 @@ interface VerifyEmailOptions {
     maxWaitMs?: number;
     /** Override the server-provided polling delay. */
     pollIntervalMs?: number;
+    /** Return a no-spend plan without provider calls or jobs. */
+    dryRun?: boolean;
+    /** Stable retry key for recovering the same request after an ambiguous response. */
+    idempotencyKey?: string;
 }
 interface VerifyEmailBatchOptions extends BatchOptions, VerifyEmailOptions {
 }
@@ -124,6 +151,10 @@ interface CompanySignalEnrichmentParams {
     maxWaitMs?: number;
     /** Delay between queued-enrichment status checks. Defaults to 2 seconds. */
     pollIntervalMs?: number;
+    /** Return a no-spend plan without provider calls or jobs. */
+    dryRun?: boolean;
+    /** Stable retry key for recovering the same request after an ambiguous response. */
+    idempotencyKey?: string;
 }
 interface CompanySignal {
     id?: string;
@@ -186,6 +217,10 @@ interface SignalToCopyParams {
     waitForResult?: boolean;
     maxWaitMs?: number;
     pollIntervalMs?: number;
+    /** Return a no-spend plan without provider calls or jobs. */
+    dryRun?: boolean;
+    /** Stable retry key for recovering the same request after an ambiguous response. */
+    idempotencyKey?: string;
 }
 interface SignalToCopyVariation {
     style: 'signal_led' | 'business_case' | 'predictive';
@@ -237,14 +272,39 @@ declare class SignalizError extends Error {
 declare class Signaliz {
     private readonly client;
     constructor(config: SignalizConfig);
+    findEmail(params: FindEmailParams & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     findEmail(params: FindEmailParams): Promise<FindEmailResult>;
+    findEmails(params: FindEmailParams[], options: BatchOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     findEmails(params: FindEmailParams[], options?: BatchOptions): Promise<BatchResult<FindEmailResult>>;
+    verifyEmail(email: string | undefined, options: VerifyEmailOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     verifyEmail(email: string | undefined, options?: VerifyEmailOptions): Promise<VerifyEmailResult>;
+    verifyEmails(emails: string[], options: VerifyEmailBatchOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     verifyEmails(emails: string[], options?: VerifyEmailBatchOptions): Promise<BatchResult<VerifyEmailResult>>;
+    enrichCompanySignals(params: CompanySignalEnrichmentParams & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     enrichCompanySignals(params: CompanySignalEnrichmentParams): Promise<CompanySignalEnrichmentResult>;
+    enrichCompanies(companies: CompanySignalEnrichmentParams[], options: BatchOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     enrichCompanies(companies: CompanySignalEnrichmentParams[], options?: BatchOptions): Promise<BatchResult<CompanySignalEnrichmentResult>>;
+    signalToCopy(params: SignalToCopyParams & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     signalToCopy(params: SignalToCopyParams): Promise<SignalToCopyResult>;
+    createSignalCopyBatch(requests: SignalToCopyParams[], options: BatchOptions & {
+        dryRun: true;
+    }): Promise<CoreProductDryRunResult>;
     createSignalCopyBatch(requests: SignalToCopyParams[], options?: BatchOptions): Promise<BatchResult<SignalToCopyResult>>;
+    private runCoreProductDryRun;
     private runSignalCopyBatchChunks;
     private runAvailableSignalCopyBatchJob;
     private runRecoverableCoreBatchJob;

package/dist/index.js

@@ -405,10 +405,17 @@ var Signaliz = class {
   }
   async findEmail(params) {
     const data = await this.client.post("api/v1/find-email", findEmailRequestBody(params));
-    return normalizeFindEmailResult(data);
+    return isCoreProductDryRun(data) ? normalizeCoreProductDryRunResult(data) : normalizeFindEmailResult(data);
   }
   async findEmails(params, options) {
     validateBatchSize(params);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/find-email",
+        params.map(findEmailRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const round = await this.runCoreBatchRound(
       "api/v1/find-email",
@@ -427,9 +434,12 @@ var Signaliz = class {
     const request = compact({
       email: email || void 0,
       verification_run_id: options?.verificationRunId,
-      skip_cache: options?.skipCache
+      skip_cache: options?.skipCache,
+      dry_run: options?.dryRun,
+      idempotency_key: options?.idempotencyKey
     });
     let data = await this.client.post("api/v1/verify-email", request);
+    if (isCoreProductDryRun(data)) return normalizeCoreProductDryRunResult(data);
     if (options?.waitForResult !== false && isPendingSignalResponse(data) && data.verification_run_id) {
       const maxWaitMs = Math.max(1e3, options?.maxWaitMs ?? 10 * 6e4);
       const startedAt = Date.now();
@@ -449,6 +459,13 @@ var Signaliz = class {
   }
   async verifyEmails(emails, options) {
     validateBatchSize(emails);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/verify-email",
+        emails.map((email) => ({ email, skip_cache: options.skipCache })),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const round = await this.runCoreBatchRound(
       "api/v1/verify-email",
@@ -469,6 +486,7 @@ var Signaliz = class {
   async enrichCompanySignals(params) {
     const request = companySignalRequestBody(params);
     let 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();
@@ -499,6 +517,13 @@ var Signaliz = class {
   }
   async enrichCompanies(companies, options) {
     validateBatchSize(companies);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/company-signals",
+        companies.map(companySignalRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const results = new Array(companies.length);
     const initialTasks = companies.map((params, index) => ({
@@ -576,6 +601,7 @@ var Signaliz = class {
     validateSignalToCopyParams(params);
     const request = signalToCopyRequestBody(params);
     let 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();
@@ -594,6 +620,13 @@ var Signaliz = class {
   async createSignalCopyBatch(requests, options) {
     validateBatchSize(requests);
     requests.forEach(validateSignalToCopyParams);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/signal-to-copy",
+        requests.map(signalToCopyRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const deduplicated = dedupeExactBatchItems(requests, (params) => JSON.stringify({
       request: signalToCopyRequestBody(params),
@@ -620,6 +653,17 @@ var Signaliz = class {
       results: compactedResults
     };
   }
+  async runCoreProductDryRun(path, requests, idempotencyKey) {
+    const data = await this.client.post(path, compact({
+      requests,
+      dry_run: true,
+      idempotency_key: idempotencyKey
+    }));
+    if (!isCoreProductDryRun(data)) {
+      throw new Error(`${path} dry run returned a live-result contract`);
+    }
+    return normalizeCoreProductDryRunResult(data);
+  }
   async runSignalCopyBatchChunks(uniqueRequests, options) {
     const chunks = [];
     for (let offset = 0; offset < uniqueRequests.length; offset += 25) {
@@ -978,9 +1022,34 @@ function findEmailRequestBody(params) {
     last_name: params.lastName,
     linkedin_url: params.linkedinUrl,
     company_name: params.companyName,
-    skip_cache: params.skipCache
+    skip_cache: params.skipCache,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
+function isCoreProductDryRun(data) {
+  return data.dry_run === true && data.status === "planned";
+}
+function normalizeCoreProductDryRunResult(data) {
+  const estimatedCredits = data.estimated_credits && typeof data.estimated_credits === "object" ? data.estimated_credits : { min: 0, max: 0 };
+  return {
+    success: true,
+    dryRun: true,
+    status: "planned",
+    capability: String(data.capability || ""),
+    inputCount: Number(data.input_count || 0),
+    recoveryReadCount: Number(data.recovery_read_count || 0),
+    plan: data.plan && typeof data.plan === "object" ? data.plan : {},
+    estimate: data.estimate && typeof data.estimate === "object" ? data.estimate : {},
+    estimatedCredits: {
+      min: Number(estimatedCredits.min || 0),
+      max: Number(estimatedCredits.max || 0)
+    },
+    creditsCharged: 0,
+    sideEffects: Array.isArray(data.side_effects) ? data.side_effects : [],
+    raw: data
+  };
+}
 function normalizeFindEmailResult(data) {
   const email = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const found = Boolean(email) && data.found !== false;
@@ -1049,7 +1118,9 @@ function companySignalRequestBody(params) {
     // REST always returns a resumable run instead of holding the connection;
     // waitForResult controls the SDK polling loop.
     wait_for_result: false,
-    max_wait_ms: params.maxWaitMs
+    max_wait_ms: params.maxWaitMs,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
 function companySignalRecoverableBatchOptions(companies, tasks) {
@@ -1221,7 +1292,9 @@ function signalToCopyRequestBody(params) {
     research_prompt: params.researchPrompt,
     signal_run_id: params.signalRunId,
     skip_cache: params.skipCache,
-    enable_deep_search: params.enableDeepSearch
+    enable_deep_search: params.enableDeepSearch,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
 function validateSignalToCopyParams(params) {

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   Signaliz,
   SignalizError
-} from "./chunk-4LXMT3S5.mjs";
+} from "./chunk-KTWDTUCI.mjs";
 export {
   Signaliz,
   SignalizError

package/dist/mcp-config.js

@@ -409,10 +409,17 @@ var Signaliz = class {
   }
   async findEmail(params) {
     const data = await this.client.post("api/v1/find-email", findEmailRequestBody(params));
-    return normalizeFindEmailResult(data);
+    return isCoreProductDryRun(data) ? normalizeCoreProductDryRunResult(data) : normalizeFindEmailResult(data);
   }
   async findEmails(params, options) {
     validateBatchSize(params);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/find-email",
+        params.map(findEmailRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const round = await this.runCoreBatchRound(
       "api/v1/find-email",
@@ -431,9 +438,12 @@ var Signaliz = class {
     const request = compact({
       email: email || void 0,
       verification_run_id: options?.verificationRunId,
-      skip_cache: options?.skipCache
+      skip_cache: options?.skipCache,
+      dry_run: options?.dryRun,
+      idempotency_key: options?.idempotencyKey
     });
     let data = await this.client.post("api/v1/verify-email", request);
+    if (isCoreProductDryRun(data)) return normalizeCoreProductDryRunResult(data);
     if (options?.waitForResult !== false && isPendingSignalResponse(data) && data.verification_run_id) {
       const maxWaitMs = Math.max(1e3, options?.maxWaitMs ?? 10 * 6e4);
       const startedAt = Date.now();
@@ -453,6 +463,13 @@ var Signaliz = class {
   }
   async verifyEmails(emails, options) {
     validateBatchSize(emails);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/verify-email",
+        emails.map((email) => ({ email, skip_cache: options.skipCache })),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const round = await this.runCoreBatchRound(
       "api/v1/verify-email",
@@ -473,6 +490,7 @@ var Signaliz = class {
   async enrichCompanySignals(params) {
     const request = companySignalRequestBody(params);
     let 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();
@@ -503,6 +521,13 @@ var Signaliz = class {
   }
   async enrichCompanies(companies, options) {
     validateBatchSize(companies);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/company-signals",
+        companies.map(companySignalRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const results = new Array(companies.length);
     const initialTasks = companies.map((params, index) => ({
@@ -580,6 +605,7 @@ var Signaliz = class {
     validateSignalToCopyParams(params);
     const request = signalToCopyRequestBody(params);
     let 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();
@@ -598,6 +624,13 @@ var Signaliz = class {
   async createSignalCopyBatch(requests, options) {
     validateBatchSize(requests);
     requests.forEach(validateSignalToCopyParams);
+    if (options?.dryRun === true) {
+      return this.runCoreProductDryRun(
+        "api/v1/signal-to-copy",
+        requests.map(signalToCopyRequestBody),
+        options.idempotencyKey
+      );
+    }
     const startedAt = Date.now();
     const deduplicated = dedupeExactBatchItems(requests, (params) => JSON.stringify({
       request: signalToCopyRequestBody(params),
@@ -624,6 +657,17 @@ var Signaliz = class {
       results: compactedResults
     };
   }
+  async runCoreProductDryRun(path2, requests, idempotencyKey) {
+    const data = await this.client.post(path2, compact({
+      requests,
+      dry_run: true,
+      idempotency_key: idempotencyKey
+    }));
+    if (!isCoreProductDryRun(data)) {
+      throw new Error(`${path2} dry run returned a live-result contract`);
+    }
+    return normalizeCoreProductDryRunResult(data);
+  }
   async runSignalCopyBatchChunks(uniqueRequests, options) {
     const chunks = [];
     for (let offset = 0; offset < uniqueRequests.length; offset += 25) {
@@ -982,9 +1026,34 @@ function findEmailRequestBody(params) {
     last_name: params.lastName,
     linkedin_url: params.linkedinUrl,
     company_name: params.companyName,
-    skip_cache: params.skipCache
+    skip_cache: params.skipCache,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
+function isCoreProductDryRun(data) {
+  return data.dry_run === true && data.status === "planned";
+}
+function normalizeCoreProductDryRunResult(data) {
+  const estimatedCredits = data.estimated_credits && typeof data.estimated_credits === "object" ? data.estimated_credits : { min: 0, max: 0 };
+  return {
+    success: true,
+    dryRun: true,
+    status: "planned",
+    capability: String(data.capability || ""),
+    inputCount: Number(data.input_count || 0),
+    recoveryReadCount: Number(data.recovery_read_count || 0),
+    plan: data.plan && typeof data.plan === "object" ? data.plan : {},
+    estimate: data.estimate && typeof data.estimate === "object" ? data.estimate : {},
+    estimatedCredits: {
+      min: Number(estimatedCredits.min || 0),
+      max: Number(estimatedCredits.max || 0)
+    },
+    creditsCharged: 0,
+    sideEffects: Array.isArray(data.side_effects) ? data.side_effects : [],
+    raw: data
+  };
+}
 function normalizeFindEmailResult(data) {
   const email = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const found = Boolean(email) && data.found !== false;
@@ -1053,7 +1122,9 @@ function companySignalRequestBody(params) {
     // REST always returns a resumable run instead of holding the connection;
     // waitForResult controls the SDK polling loop.
     wait_for_result: false,
-    max_wait_ms: params.maxWaitMs
+    max_wait_ms: params.maxWaitMs,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
 function companySignalRecoverableBatchOptions(companies, tasks) {
@@ -1225,7 +1296,9 @@ function signalToCopyRequestBody(params) {
     research_prompt: params.researchPrompt,
     signal_run_id: params.signalRunId,
     skip_cache: params.skipCache,
-    enable_deep_search: params.enableDeepSearch
+    enable_deep_search: params.enableDeepSearch,
+    dry_run: params.dryRun,
+    idempotency_key: params.idempotencyKey
   });
 }
 function validateSignalToCopyParams(params) {

package/dist/mcp-config.mjs

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

package/package.json

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