@signaliz/sdk 1.0.55 → 1.0.56

package/README.md

@@ -29,6 +29,8 @@ const plan = await signaliz.findEmail({
   dryRun: true,
 });
 console.log(plan.estimatedCredits.max, plan.creditsCharged); // 2, 0
+// Batch plans price only semantic unique work and expose duplicate suppression.
+console.log(plan.inputCount, plan.uniqueFreshInputCount, plan.inputDuplicatesSuppressed);
 
 const found = await signaliz.findEmail({
   companyDomain: 'example.com',
@@ -111,8 +113,11 @@ when the REST API supplies them, including after automatic row retries are
 exhausted.
 
 For an ambiguous single request or batch submission failure, retry with the
-same `idempotencyKey` to recover the original request or durable job without duplicate
-work.
+same `idempotencyKey` to recover the original request, durable job, or provider
+run without duplicate work or spend. The key is portable across REST API, MCP,
+SDK, and CLI calls for the same workspace and logical input. Chunked batches
+derive a stable key from each row's original input index, including after exact
+duplicate compaction and rate-limit retries.
 
 Each batch accepts up to 5,000 items. For the four row-oriented core products, batches larger
 than 25 use one recoverable REST job; the SDK waits for completion and retrieves

package/dist/{chunk-QXMVHZIQ.mjs → chunk-K7RDDRMJ.mjs}

@@ -536,7 +536,11 @@ var Signaliz = class {
       request: signalToCopyRequestBody(params)
     }));
     const uniqueRequests = deduplicated.uniqueItems;
-    const uniqueResults = await this.runSignalCopyBatchChunks(uniqueRequests, options);
+    const uniqueInputIndices = new Array(uniqueRequests.length);
+    deduplicated.sourceIndexByInput.forEach((uniqueIndex, inputIndex) => {
+      if (uniqueInputIndices[uniqueIndex] === void 0) uniqueInputIndices[uniqueIndex] = inputIndex;
+    });
+    const uniqueResults = await this.runSignalCopyBatchChunks(uniqueRequests, options, uniqueInputIndices);
     const results = requests.map((_, index) => ({
       ...uniqueResults[deduplicated.sourceIndexByInput[index]],
       index
@@ -562,15 +566,25 @@ var Signaliz = class {
     }
     return normalizeCoreProductDryRunResult(data);
   }
-  async runSignalCopyBatchChunks(uniqueRequests, options) {
+  async runSignalCopyBatchChunks(uniqueRequests, options, idempotencyItemIndices = uniqueRequests.map((_, index) => index)) {
     const chunks = [];
     for (let offset = 0; offset < uniqueRequests.length; offset += 25) {
-      chunks.push({ offset, requests: uniqueRequests.slice(offset, offset + 25) });
+      chunks.push({
+        offset,
+        requests: uniqueRequests.slice(offset, offset + 25),
+        idempotencyItemIndices: idempotencyItemIndices.slice(offset, offset + 25)
+      });
     }
     const { serverConcurrency, chunkConcurrency } = batchConcurrencyPlan(options, 25, 25);
     const chunkBatch = await runBatch(
       chunks,
-      (chunk) => this.runSignalCopyBatchChunk(chunk.requests, serverConcurrency),
+      (chunk) => this.runSignalCopyBatchChunk(
+        chunk.requests,
+        serverConcurrency,
+        0,
+        options?.idempotencyKey,
+        chunk.idempotencyItemIndices
+      ),
       { concurrency: chunkConcurrency }
     );
     const uniqueResults = new Array(uniqueRequests.length);
@@ -592,14 +606,15 @@ var Signaliz = class {
     }
     return uniqueResults;
   }
-  async runRecoverableCoreBatchJob(path, requests, label, pageSize = 500, maxWaitMs = 20 * 6e4, idempotencyKey) {
+  async runRecoverableCoreBatchJob(path, requests, label, pageSize = 500, maxWaitMs = 20 * 6e4, idempotencyKey, idempotencyItemIndices) {
     const startedAt = Date.now();
     const submissionIdempotencyKey = idempotencyKey?.trim() || newBatchIdempotencyKey(label);
     let submission;
     try {
       submission = await this.client.post(path, {
         requests,
-        idempotency_key: submissionIdempotencyKey
+        idempotency_key: submissionIdempotencyKey,
+        batch_item_indices: idempotencyItemIndices
       });
     } catch (error) {
       if (error instanceof SignalizError && !error.isRetryable) throw error;
@@ -662,12 +677,14 @@ var Signaliz = class {
     if (seen.size !== requests.length) throw new Error(`${label} batch returned incomplete indexed results`);
     return rows;
   }
-  async runSignalCopyBatchChunk(requests, concurrency, rowRateLimitAttempt = 0) {
+  async runSignalCopyBatchChunk(requests, concurrency, rowRateLimitAttempt = 0, idempotencyKey, idempotencyItemIndices = requests.map((_, index) => index)) {
     const results = new Array(requests.length);
     const rateLimited = [];
     const data = await this.client.post("api/v1/signal-to-copy", {
       requests: requests.map(signalToCopyRequestBody),
-      concurrency
+      concurrency,
+      idempotency_key: idempotencyKey,
+      batch_item_indices: idempotencyItemIndices
     });
     if (!Array.isArray(data.results) || data.results.length !== requests.length) {
       throw new Error("Signal to Copy batch returned an invalid result count");
@@ -702,7 +719,9 @@ var Signaliz = class {
       const retried = await this.runSignalCopyBatchChunk(
         rateLimited.map((item) => item.params),
         concurrency,
-        rowRateLimitAttempt + 1
+        rowRateLimitAttempt + 1,
+        idempotencyKey,
+        rateLimited.map((item) => idempotencyItemIndices[item.index])
       );
       for (let index = 0; index < rateLimited.length; index += 1) {
         results[rateLimited[index].index] = { ...retried[index], index: rateLimited[index].index };
@@ -722,7 +741,8 @@ var Signaliz = class {
         recoverableBatch.label,
         recoverableBatch.pageSize,
         recoverableBatch.maxWaitMs,
-        options?.idempotencyKey
+        options?.idempotencyKey,
+        uniqueTasks.map((task) => task.index)
       );
       const uniqueResults2 = new Array(uniqueTasks.length);
       for (const raw of rows) {
@@ -746,7 +766,9 @@ var Signaliz = class {
     const chunkBatch = await runBatch(chunks, async (chunk) => {
       const data = await this.client.post(path, {
         requests: chunk.tasks.map((task) => task.request),
-        concurrency: serverConcurrency
+        concurrency: serverConcurrency,
+        idempotency_key: options?.idempotencyKey,
+        batch_item_indices: chunk.tasks.map((task) => task.index)
       });
       if (!Array.isArray(data.results) || data.results.length !== chunk.tasks.length) {
         throw new Error(`${path} batch returned an invalid result count`);
@@ -881,7 +903,11 @@ function normalizeCoreProductDryRunResult(data) {
     status: "planned",
     capability: String(data.capability || ""),
     inputCount: Number(data.input_count || 0),
+    freshInputCount: Number(data.fresh_input_count ?? data.input_count ?? 0),
+    uniqueFreshInputCount: Number(data.unique_fresh_input_count ?? data.fresh_input_count ?? data.input_count ?? 0),
+    inputDuplicatesSuppressed: Number(data.input_duplicates_suppressed || 0),
     recoveryReadCount: Number(data.recovery_read_count || 0),
+    uniqueRecoveryReadCount: Number(data.unique_recovery_read_count ?? data.recovery_read_count ?? 0),
     plan: data.plan && typeof data.plan === "object" ? data.plan : {},
     estimate: data.estimate && typeof data.estimate === "object" ? data.estimate : {},
     estimatedCredits: {
@@ -896,12 +922,12 @@ function normalizeCoreProductDryRunResult(data) {
 function normalizeFindEmailResult(data) {
   const email = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const found = Boolean(email) && data.found !== false;
-  const verificationStatus = data.verification_status ?? data.status ?? "unknown";
+  const verificationStatus = data.verification_status ?? (data.is_valid === true ? "valid" : data.status ?? "unknown");
   const rawFreshness = String(data.verification_freshness ?? "").toLowerCase();
   const verificationFreshness = rawFreshness === "fresh" || rawFreshness === "stale" ? rawFreshness : "unknown";
   const needsReverification = data.needs_reverification === true || verificationFreshness === "stale";
   const explicitlyNotSendSafe = data.verified_for_sending === false || needsReverification;
-  const verified = !explicitlyNotSendSafe && (data.email_verified === true || data.verified_for_sending === true || ["valid", "deliverable"].includes(String(verificationStatus).toLowerCase()));
+  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: data.success !== false && found,
@@ -924,6 +950,9 @@ function normalizeFindEmailResult(data) {
     billingMetadata: data.billing_metadata,
     resultReturnedFrom: data.result_returned_from,
     cacheHit: data.cache_hit,
+    negativeCacheHit: data.negative_cache_hit,
+    negativeCacheTtlSeconds: data.negative_cache_ttl_seconds,
+    cacheTier: data.cache_tier,
     freshEnrichmentUsed: data.fresh_enrichment_used,
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
@@ -945,6 +974,7 @@ function normalizeVerifyEmailResult(email, data) {
     nextPollAfterSeconds: data.next_poll_after_seconds,
     isValid: data.is_valid ?? data.valid ?? verified,
     isDeliverable: data.is_deliverable ?? data.deliverable ?? verified,
+    isMalformed: data.is_malformed === true || data.verification_verdict === "malformed" || data.verification_status === "malformed" || data.deliverability_status === "malformed",
     isCatchAll: data.email_is_catch_all ?? data.is_catch_all ?? data.catch_all ?? data.diagnostics?.is_catch_all ?? false,
     verifiedForSending: data.verified_for_sending === true,
     verificationVerdict: data.verification_verdict ?? data.verification_status ?? "unknown",
@@ -956,6 +986,9 @@ function normalizeVerifyEmailResult(email, data) {
     billingMetadata: data.billing_metadata,
     resultReturnedFrom: data.result_returned_from,
     cacheHit: data.cache_hit,
+    negativeCacheHit: data.negative_cache_hit,
+    negativeCacheTtlSeconds: data.negative_cache_ttl_seconds,
+    cacheTier: data.cache_tier,
     freshEnrichmentUsed: data.fresh_enrichment_used,
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
@@ -1025,6 +1058,14 @@ function normalizeCompanySignalResult(params, data) {
     evidenceCountTotal: data.evidence_count_total,
     evidenceSourcesOmitted: data.evidence_sources_omitted,
     evidenceScope: data.evidence_scope,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
+    creditsUsed: data.credits_used,
+    liveProviderCalled: data.live_provider_called,
+    aiProviderCalled: data.ai_provider_called,
+    byoAiUsed: data.byo_ai_used,
     raw: data
   };
 }
@@ -1302,6 +1343,14 @@ function normalizeSignalToCopyResult(data) {
     empty: data.empty,
     emptyReason: data.empty_reason,
     researchMetadata: data.research_metadata,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
+    creditsUsed: data.credits_used,
+    liveProviderCalled: data.live_provider_called,
+    aiProviderCalled: data.ai_provider_called,
+    byoAiUsed: data.byo_ai_used,
     variations: (data.variations ?? []).map((variation) => ({
       style: variation.style,
       subjectLine: variation.subject_line ?? "",

package/dist/index.d.mts

@@ -9,7 +9,7 @@ interface SignalizConfig {
 interface BatchOptions {
     /** Maximum simultaneous API requests. Defaults to 10; allowed range is 1-50. */
     concurrency?: number;
-    /** Stable key for safely retrying an ambiguous recoverable batch submission. */
+    /** Stable cross-surface key. Retries reuse the same provider work; chunked batches derive one collision-free key per original row. */
     idempotencyKey?: string;
     /** Return exact repeated successes as duplicateOf references. Defaults to false. */
     compactDuplicates?: boolean;
@@ -51,7 +51,11 @@ interface CoreProductDryRunResult {
     status: 'planned';
     capability: string;
     inputCount: number;
+    freshInputCount: number;
+    uniqueFreshInputCount: number;
+    inputDuplicatesSuppressed: number;
     recoveryReadCount: number;
+    uniqueRecoveryReadCount: number;
     plan: Record<string, unknown>;
     estimate: Record<string, unknown>;
     estimatedCredits: {
@@ -97,6 +101,11 @@ interface FindEmailResult {
     billingMetadata?: Record<string, unknown>;
     resultReturnedFrom?: string;
     cacheHit?: boolean;
+    /** True when a definitive no-email result came from the short-lived negative cache. */
+    negativeCacheHit?: boolean;
+    /** Remaining lifetime of the negative cache entry. */
+    negativeCacheTtlSeconds?: number;
+    cacheTier?: string;
     freshEnrichmentUsed?: boolean;
     liveProviderCalled?: boolean;
     openrouterCalled?: boolean;
@@ -116,6 +125,8 @@ interface VerifyEmailResult {
     nextPollAfterSeconds?: number;
     isValid: boolean;
     isDeliverable: boolean;
+    /** True when the address failed syntax validation before any provider call. */
+    isMalformed: boolean;
     isCatchAll: boolean;
     /** Explicit send-safety verdict. Missing or false never becomes true by inference. */
     verifiedForSending: boolean;
@@ -128,6 +139,11 @@ interface VerifyEmailResult {
     billingMetadata?: Record<string, unknown>;
     resultReturnedFrom?: string;
     cacheHit?: boolean;
+    /** True when a conclusive send-blocking verdict came from the short-lived rejection cache. */
+    negativeCacheHit?: boolean;
+    /** Remaining lifetime of the rejection cache entry. */
+    negativeCacheTtlSeconds?: number;
+    cacheTier?: string;
     freshEnrichmentUsed?: boolean;
     liveProviderCalled?: boolean;
     openrouterCalled?: boolean;
@@ -217,6 +233,14 @@ interface CompanySignalEnrichmentResult {
     evidenceCountTotal?: number;
     evidenceSourcesOmitted?: number;
     evidenceScope?: 'selected_signals' | 'all_candidates';
+    billingMetadata?: Record<string, unknown>;
+    resultReturnedFrom?: string;
+    cacheHit?: boolean;
+    freshEnrichmentUsed?: boolean;
+    creditsUsed?: number;
+    liveProviderCalled?: boolean;
+    aiProviderCalled?: boolean;
+    byoAiUsed?: boolean;
     raw: Record<string, unknown>;
 }
 type SignalDiscoverySource = 'web' | 'news';
@@ -311,7 +335,7 @@ interface SignalToCopyParams {
     signalRunId?: string;
     /** Bypass cached company signals and start fresh research. */
     skipCache?: boolean;
-    /** Opt into slower deep research. Defaults to false. */
+    /** Use the full deep-research provider portfolio. The default uses bounded credit-free first-party and Bing grounding. */
     enableDeepSearch?: boolean;
     /** @deprecated Signal to Copy is always synchronous; this option is ignored. */
     waitForResult?: boolean;
@@ -346,6 +370,14 @@ interface SignalToCopyResult {
     empty?: boolean;
     emptyReason?: string;
     researchMetadata?: Record<string, unknown>;
+    billingMetadata?: Record<string, unknown>;
+    resultReturnedFrom?: string;
+    cacheHit?: boolean;
+    freshEnrichmentUsed?: boolean;
+    creditsUsed?: number;
+    liveProviderCalled?: boolean;
+    aiProviderCalled?: boolean;
+    byoAiUsed?: boolean;
     variations: SignalToCopyVariation[];
     raw: Record<string, unknown>;
 }

package/dist/index.d.ts

@@ -9,7 +9,7 @@ interface SignalizConfig {
 interface BatchOptions {
     /** Maximum simultaneous API requests. Defaults to 10; allowed range is 1-50. */
     concurrency?: number;
-    /** Stable key for safely retrying an ambiguous recoverable batch submission. */
+    /** Stable cross-surface key. Retries reuse the same provider work; chunked batches derive one collision-free key per original row. */
     idempotencyKey?: string;
     /** Return exact repeated successes as duplicateOf references. Defaults to false. */
     compactDuplicates?: boolean;
@@ -51,7 +51,11 @@ interface CoreProductDryRunResult {
     status: 'planned';
     capability: string;
     inputCount: number;
+    freshInputCount: number;
+    uniqueFreshInputCount: number;
+    inputDuplicatesSuppressed: number;
     recoveryReadCount: number;
+    uniqueRecoveryReadCount: number;
     plan: Record<string, unknown>;
     estimate: Record<string, unknown>;
     estimatedCredits: {
@@ -97,6 +101,11 @@ interface FindEmailResult {
     billingMetadata?: Record<string, unknown>;
     resultReturnedFrom?: string;
     cacheHit?: boolean;
+    /** True when a definitive no-email result came from the short-lived negative cache. */
+    negativeCacheHit?: boolean;
+    /** Remaining lifetime of the negative cache entry. */
+    negativeCacheTtlSeconds?: number;
+    cacheTier?: string;
     freshEnrichmentUsed?: boolean;
     liveProviderCalled?: boolean;
     openrouterCalled?: boolean;
@@ -116,6 +125,8 @@ interface VerifyEmailResult {
     nextPollAfterSeconds?: number;
     isValid: boolean;
     isDeliverable: boolean;
+    /** True when the address failed syntax validation before any provider call. */
+    isMalformed: boolean;
     isCatchAll: boolean;
     /** Explicit send-safety verdict. Missing or false never becomes true by inference. */
     verifiedForSending: boolean;
@@ -128,6 +139,11 @@ interface VerifyEmailResult {
     billingMetadata?: Record<string, unknown>;
     resultReturnedFrom?: string;
     cacheHit?: boolean;
+    /** True when a conclusive send-blocking verdict came from the short-lived rejection cache. */
+    negativeCacheHit?: boolean;
+    /** Remaining lifetime of the rejection cache entry. */
+    negativeCacheTtlSeconds?: number;
+    cacheTier?: string;
     freshEnrichmentUsed?: boolean;
     liveProviderCalled?: boolean;
     openrouterCalled?: boolean;
@@ -217,6 +233,14 @@ interface CompanySignalEnrichmentResult {
     evidenceCountTotal?: number;
     evidenceSourcesOmitted?: number;
     evidenceScope?: 'selected_signals' | 'all_candidates';
+    billingMetadata?: Record<string, unknown>;
+    resultReturnedFrom?: string;
+    cacheHit?: boolean;
+    freshEnrichmentUsed?: boolean;
+    creditsUsed?: number;
+    liveProviderCalled?: boolean;
+    aiProviderCalled?: boolean;
+    byoAiUsed?: boolean;
     raw: Record<string, unknown>;
 }
 type SignalDiscoverySource = 'web' | 'news';
@@ -311,7 +335,7 @@ interface SignalToCopyParams {
     signalRunId?: string;
     /** Bypass cached company signals and start fresh research. */
     skipCache?: boolean;
-    /** Opt into slower deep research. Defaults to false. */
+    /** Use the full deep-research provider portfolio. The default uses bounded credit-free first-party and Bing grounding. */
     enableDeepSearch?: boolean;
     /** @deprecated Signal to Copy is always synchronous; this option is ignored. */
     waitForResult?: boolean;
@@ -346,6 +370,14 @@ interface SignalToCopyResult {
     empty?: boolean;
     emptyReason?: string;
     researchMetadata?: Record<string, unknown>;
+    billingMetadata?: Record<string, unknown>;
+    resultReturnedFrom?: string;
+    cacheHit?: boolean;
+    freshEnrichmentUsed?: boolean;
+    creditsUsed?: number;
+    liveProviderCalled?: boolean;
+    aiProviderCalled?: boolean;
+    byoAiUsed?: boolean;
     variations: SignalToCopyVariation[];
     raw: Record<string, unknown>;
 }

package/dist/index.js

@@ -563,7 +563,11 @@ var Signaliz = class {
       request: signalToCopyRequestBody(params)
     }));
     const uniqueRequests = deduplicated.uniqueItems;
-    const uniqueResults = await this.runSignalCopyBatchChunks(uniqueRequests, options);
+    const uniqueInputIndices = new Array(uniqueRequests.length);
+    deduplicated.sourceIndexByInput.forEach((uniqueIndex, inputIndex) => {
+      if (uniqueInputIndices[uniqueIndex] === void 0) uniqueInputIndices[uniqueIndex] = inputIndex;
+    });
+    const uniqueResults = await this.runSignalCopyBatchChunks(uniqueRequests, options, uniqueInputIndices);
     const results = requests.map((_, index) => ({
       ...uniqueResults[deduplicated.sourceIndexByInput[index]],
       index
@@ -589,15 +593,25 @@ var Signaliz = class {
     }
     return normalizeCoreProductDryRunResult(data);
   }
-  async runSignalCopyBatchChunks(uniqueRequests, options) {
+  async runSignalCopyBatchChunks(uniqueRequests, options, idempotencyItemIndices = uniqueRequests.map((_, index) => index)) {
     const chunks = [];
     for (let offset = 0; offset < uniqueRequests.length; offset += 25) {
-      chunks.push({ offset, requests: uniqueRequests.slice(offset, offset + 25) });
+      chunks.push({
+        offset,
+        requests: uniqueRequests.slice(offset, offset + 25),
+        idempotencyItemIndices: idempotencyItemIndices.slice(offset, offset + 25)
+      });
     }
     const { serverConcurrency, chunkConcurrency } = batchConcurrencyPlan(options, 25, 25);
     const chunkBatch = await runBatch(
       chunks,
-      (chunk) => this.runSignalCopyBatchChunk(chunk.requests, serverConcurrency),
+      (chunk) => this.runSignalCopyBatchChunk(
+        chunk.requests,
+        serverConcurrency,
+        0,
+        options?.idempotencyKey,
+        chunk.idempotencyItemIndices
+      ),
       { concurrency: chunkConcurrency }
     );
     const uniqueResults = new Array(uniqueRequests.length);
@@ -619,14 +633,15 @@ var Signaliz = class {
     }
     return uniqueResults;
   }
-  async runRecoverableCoreBatchJob(path, requests, label, pageSize = 500, maxWaitMs = 20 * 6e4, idempotencyKey) {
+  async runRecoverableCoreBatchJob(path, requests, label, pageSize = 500, maxWaitMs = 20 * 6e4, idempotencyKey, idempotencyItemIndices) {
     const startedAt = Date.now();
     const submissionIdempotencyKey = idempotencyKey?.trim() || newBatchIdempotencyKey(label);
     let submission;
     try {
       submission = await this.client.post(path, {
         requests,
-        idempotency_key: submissionIdempotencyKey
+        idempotency_key: submissionIdempotencyKey,
+        batch_item_indices: idempotencyItemIndices
       });
     } catch (error) {
       if (error instanceof SignalizError && !error.isRetryable) throw error;
@@ -689,12 +704,14 @@ var Signaliz = class {
     if (seen.size !== requests.length) throw new Error(`${label} batch returned incomplete indexed results`);
     return rows;
   }
-  async runSignalCopyBatchChunk(requests, concurrency, rowRateLimitAttempt = 0) {
+  async runSignalCopyBatchChunk(requests, concurrency, rowRateLimitAttempt = 0, idempotencyKey, idempotencyItemIndices = requests.map((_, index) => index)) {
     const results = new Array(requests.length);
     const rateLimited = [];
     const data = await this.client.post("api/v1/signal-to-copy", {
       requests: requests.map(signalToCopyRequestBody),
-      concurrency
+      concurrency,
+      idempotency_key: idempotencyKey,
+      batch_item_indices: idempotencyItemIndices
     });
     if (!Array.isArray(data.results) || data.results.length !== requests.length) {
       throw new Error("Signal to Copy batch returned an invalid result count");
@@ -729,7 +746,9 @@ var Signaliz = class {
       const retried = await this.runSignalCopyBatchChunk(
         rateLimited.map((item) => item.params),
         concurrency,
-        rowRateLimitAttempt + 1
+        rowRateLimitAttempt + 1,
+        idempotencyKey,
+        rateLimited.map((item) => idempotencyItemIndices[item.index])
       );
       for (let index = 0; index < rateLimited.length; index += 1) {
         results[rateLimited[index].index] = { ...retried[index], index: rateLimited[index].index };
@@ -749,7 +768,8 @@ var Signaliz = class {
         recoverableBatch.label,
         recoverableBatch.pageSize,
         recoverableBatch.maxWaitMs,
-        options?.idempotencyKey
+        options?.idempotencyKey,
+        uniqueTasks.map((task) => task.index)
       );
       const uniqueResults2 = new Array(uniqueTasks.length);
       for (const raw of rows) {
@@ -773,7 +793,9 @@ var Signaliz = class {
     const chunkBatch = await runBatch(chunks, async (chunk) => {
       const data = await this.client.post(path, {
         requests: chunk.tasks.map((task) => task.request),
-        concurrency: serverConcurrency
+        concurrency: serverConcurrency,
+        idempotency_key: options?.idempotencyKey,
+        batch_item_indices: chunk.tasks.map((task) => task.index)
       });
       if (!Array.isArray(data.results) || data.results.length !== chunk.tasks.length) {
         throw new Error(`${path} batch returned an invalid result count`);
@@ -908,7 +930,11 @@ function normalizeCoreProductDryRunResult(data) {
     status: "planned",
     capability: String(data.capability || ""),
     inputCount: Number(data.input_count || 0),
+    freshInputCount: Number(data.fresh_input_count ?? data.input_count ?? 0),
+    uniqueFreshInputCount: Number(data.unique_fresh_input_count ?? data.fresh_input_count ?? data.input_count ?? 0),
+    inputDuplicatesSuppressed: Number(data.input_duplicates_suppressed || 0),
     recoveryReadCount: Number(data.recovery_read_count || 0),
+    uniqueRecoveryReadCount: Number(data.unique_recovery_read_count ?? data.recovery_read_count ?? 0),
     plan: data.plan && typeof data.plan === "object" ? data.plan : {},
     estimate: data.estimate && typeof data.estimate === "object" ? data.estimate : {},
     estimatedCredits: {
@@ -923,12 +949,12 @@ function normalizeCoreProductDryRunResult(data) {
 function normalizeFindEmailResult(data) {
   const email = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const found = Boolean(email) && data.found !== false;
-  const verificationStatus = data.verification_status ?? data.status ?? "unknown";
+  const verificationStatus = data.verification_status ?? (data.is_valid === true ? "valid" : data.status ?? "unknown");
   const rawFreshness = String(data.verification_freshness ?? "").toLowerCase();
   const verificationFreshness = rawFreshness === "fresh" || rawFreshness === "stale" ? rawFreshness : "unknown";
   const needsReverification = data.needs_reverification === true || verificationFreshness === "stale";
   const explicitlyNotSendSafe = data.verified_for_sending === false || needsReverification;
-  const verified = !explicitlyNotSendSafe && (data.email_verified === true || data.verified_for_sending === true || ["valid", "deliverable"].includes(String(verificationStatus).toLowerCase()));
+  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: data.success !== false && found,
@@ -951,6 +977,9 @@ function normalizeFindEmailResult(data) {
     billingMetadata: data.billing_metadata,
     resultReturnedFrom: data.result_returned_from,
     cacheHit: data.cache_hit,
+    negativeCacheHit: data.negative_cache_hit,
+    negativeCacheTtlSeconds: data.negative_cache_ttl_seconds,
+    cacheTier: data.cache_tier,
     freshEnrichmentUsed: data.fresh_enrichment_used,
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
@@ -972,6 +1001,7 @@ function normalizeVerifyEmailResult(email, data) {
     nextPollAfterSeconds: data.next_poll_after_seconds,
     isValid: data.is_valid ?? data.valid ?? verified,
     isDeliverable: data.is_deliverable ?? data.deliverable ?? verified,
+    isMalformed: data.is_malformed === true || data.verification_verdict === "malformed" || data.verification_status === "malformed" || data.deliverability_status === "malformed",
     isCatchAll: data.email_is_catch_all ?? data.is_catch_all ?? data.catch_all ?? data.diagnostics?.is_catch_all ?? false,
     verifiedForSending: data.verified_for_sending === true,
     verificationVerdict: data.verification_verdict ?? data.verification_status ?? "unknown",
@@ -983,6 +1013,9 @@ function normalizeVerifyEmailResult(email, data) {
     billingMetadata: data.billing_metadata,
     resultReturnedFrom: data.result_returned_from,
     cacheHit: data.cache_hit,
+    negativeCacheHit: data.negative_cache_hit,
+    negativeCacheTtlSeconds: data.negative_cache_ttl_seconds,
+    cacheTier: data.cache_tier,
     freshEnrichmentUsed: data.fresh_enrichment_used,
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
@@ -1052,6 +1085,14 @@ function normalizeCompanySignalResult(params, data) {
     evidenceCountTotal: data.evidence_count_total,
     evidenceSourcesOmitted: data.evidence_sources_omitted,
     evidenceScope: data.evidence_scope,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
+    creditsUsed: data.credits_used,
+    liveProviderCalled: data.live_provider_called,
+    aiProviderCalled: data.ai_provider_called,
+    byoAiUsed: data.byo_ai_used,
     raw: data
   };
 }
@@ -1329,6 +1370,14 @@ function normalizeSignalToCopyResult(data) {
     empty: data.empty,
     emptyReason: data.empty_reason,
     researchMetadata: data.research_metadata,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
+    creditsUsed: data.credits_used,
+    liveProviderCalled: data.live_provider_called,
+    aiProviderCalled: data.ai_provider_called,
+    byoAiUsed: data.byo_ai_used,
     variations: (data.variations ?? []).map((variation) => ({
       style: variation.style,
       subjectLine: variation.subject_line ?? "",

package/dist/index.mjs

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

package/dist/mcp-config.js

@@ -567,7 +567,11 @@ var Signaliz = class {
       request: signalToCopyRequestBody(params)
     }));
     const uniqueRequests = deduplicated.uniqueItems;
-    const uniqueResults = await this.runSignalCopyBatchChunks(uniqueRequests, options);
+    const uniqueInputIndices = new Array(uniqueRequests.length);
+    deduplicated.sourceIndexByInput.forEach((uniqueIndex, inputIndex) => {
+      if (uniqueInputIndices[uniqueIndex] === void 0) uniqueInputIndices[uniqueIndex] = inputIndex;
+    });
+    const uniqueResults = await this.runSignalCopyBatchChunks(uniqueRequests, options, uniqueInputIndices);
     const results = requests.map((_, index) => ({
       ...uniqueResults[deduplicated.sourceIndexByInput[index]],
       index
@@ -593,15 +597,25 @@ var Signaliz = class {
     }
     return normalizeCoreProductDryRunResult(data);
   }
-  async runSignalCopyBatchChunks(uniqueRequests, options) {
+  async runSignalCopyBatchChunks(uniqueRequests, options, idempotencyItemIndices = uniqueRequests.map((_, index) => index)) {
     const chunks = [];
     for (let offset = 0; offset < uniqueRequests.length; offset += 25) {
-      chunks.push({ offset, requests: uniqueRequests.slice(offset, offset + 25) });
+      chunks.push({
+        offset,
+        requests: uniqueRequests.slice(offset, offset + 25),
+        idempotencyItemIndices: idempotencyItemIndices.slice(offset, offset + 25)
+      });
     }
     const { serverConcurrency, chunkConcurrency } = batchConcurrencyPlan(options, 25, 25);
     const chunkBatch = await runBatch(
       chunks,
-      (chunk) => this.runSignalCopyBatchChunk(chunk.requests, serverConcurrency),
+      (chunk) => this.runSignalCopyBatchChunk(
+        chunk.requests,
+        serverConcurrency,
+        0,
+        options?.idempotencyKey,
+        chunk.idempotencyItemIndices
+      ),
       { concurrency: chunkConcurrency }
     );
     const uniqueResults = new Array(uniqueRequests.length);
@@ -623,14 +637,15 @@ var Signaliz = class {
     }
     return uniqueResults;
   }
-  async runRecoverableCoreBatchJob(path2, requests, label, pageSize = 500, maxWaitMs = 20 * 6e4, idempotencyKey) {
+  async runRecoverableCoreBatchJob(path2, requests, label, pageSize = 500, maxWaitMs = 20 * 6e4, idempotencyKey, idempotencyItemIndices) {
     const startedAt = Date.now();
     const submissionIdempotencyKey = idempotencyKey?.trim() || newBatchIdempotencyKey(label);
     let submission;
     try {
       submission = await this.client.post(path2, {
         requests,
-        idempotency_key: submissionIdempotencyKey
+        idempotency_key: submissionIdempotencyKey,
+        batch_item_indices: idempotencyItemIndices
       });
     } catch (error) {
       if (error instanceof SignalizError && !error.isRetryable) throw error;
@@ -693,12 +708,14 @@ var Signaliz = class {
     if (seen.size !== requests.length) throw new Error(`${label} batch returned incomplete indexed results`);
     return rows;
   }
-  async runSignalCopyBatchChunk(requests, concurrency, rowRateLimitAttempt = 0) {
+  async runSignalCopyBatchChunk(requests, concurrency, rowRateLimitAttempt = 0, idempotencyKey, idempotencyItemIndices = requests.map((_, index) => index)) {
     const results = new Array(requests.length);
     const rateLimited = [];
     const data = await this.client.post("api/v1/signal-to-copy", {
       requests: requests.map(signalToCopyRequestBody),
-      concurrency
+      concurrency,
+      idempotency_key: idempotencyKey,
+      batch_item_indices: idempotencyItemIndices
     });
     if (!Array.isArray(data.results) || data.results.length !== requests.length) {
       throw new Error("Signal to Copy batch returned an invalid result count");
@@ -733,7 +750,9 @@ var Signaliz = class {
       const retried = await this.runSignalCopyBatchChunk(
         rateLimited.map((item) => item.params),
         concurrency,
-        rowRateLimitAttempt + 1
+        rowRateLimitAttempt + 1,
+        idempotencyKey,
+        rateLimited.map((item) => idempotencyItemIndices[item.index])
       );
       for (let index = 0; index < rateLimited.length; index += 1) {
         results[rateLimited[index].index] = { ...retried[index], index: rateLimited[index].index };
@@ -753,7 +772,8 @@ var Signaliz = class {
         recoverableBatch.label,
         recoverableBatch.pageSize,
         recoverableBatch.maxWaitMs,
-        options?.idempotencyKey
+        options?.idempotencyKey,
+        uniqueTasks.map((task) => task.index)
       );
       const uniqueResults2 = new Array(uniqueTasks.length);
       for (const raw of rows) {
@@ -777,7 +797,9 @@ var Signaliz = class {
     const chunkBatch = await runBatch(chunks, async (chunk) => {
       const data = await this.client.post(path2, {
         requests: chunk.tasks.map((task) => task.request),
-        concurrency: serverConcurrency
+        concurrency: serverConcurrency,
+        idempotency_key: options?.idempotencyKey,
+        batch_item_indices: chunk.tasks.map((task) => task.index)
       });
       if (!Array.isArray(data.results) || data.results.length !== chunk.tasks.length) {
         throw new Error(`${path2} batch returned an invalid result count`);
@@ -912,7 +934,11 @@ function normalizeCoreProductDryRunResult(data) {
     status: "planned",
     capability: String(data.capability || ""),
     inputCount: Number(data.input_count || 0),
+    freshInputCount: Number(data.fresh_input_count ?? data.input_count ?? 0),
+    uniqueFreshInputCount: Number(data.unique_fresh_input_count ?? data.fresh_input_count ?? data.input_count ?? 0),
+    inputDuplicatesSuppressed: Number(data.input_duplicates_suppressed || 0),
     recoveryReadCount: Number(data.recovery_read_count || 0),
+    uniqueRecoveryReadCount: Number(data.unique_recovery_read_count ?? data.recovery_read_count ?? 0),
     plan: data.plan && typeof data.plan === "object" ? data.plan : {},
     estimate: data.estimate && typeof data.estimate === "object" ? data.estimate : {},
     estimatedCredits: {
@@ -927,12 +953,12 @@ function normalizeCoreProductDryRunResult(data) {
 function normalizeFindEmailResult(data) {
   const email = typeof data.email === "string" && data.email.trim() ? data.email.trim() : null;
   const found = Boolean(email) && data.found !== false;
-  const verificationStatus = data.verification_status ?? data.status ?? "unknown";
+  const verificationStatus = data.verification_status ?? (data.is_valid === true ? "valid" : data.status ?? "unknown");
   const rawFreshness = String(data.verification_freshness ?? "").toLowerCase();
   const verificationFreshness = rawFreshness === "fresh" || rawFreshness === "stale" ? rawFreshness : "unknown";
   const needsReverification = data.needs_reverification === true || verificationFreshness === "stale";
   const explicitlyNotSendSafe = data.verified_for_sending === false || needsReverification;
-  const verified = !explicitlyNotSendSafe && (data.email_verified === true || data.verified_for_sending === true || ["valid", "deliverable"].includes(String(verificationStatus).toLowerCase()));
+  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: data.success !== false && found,
@@ -955,6 +981,9 @@ function normalizeFindEmailResult(data) {
     billingMetadata: data.billing_metadata,
     resultReturnedFrom: data.result_returned_from,
     cacheHit: data.cache_hit,
+    negativeCacheHit: data.negative_cache_hit,
+    negativeCacheTtlSeconds: data.negative_cache_ttl_seconds,
+    cacheTier: data.cache_tier,
     freshEnrichmentUsed: data.fresh_enrichment_used,
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
@@ -976,6 +1005,7 @@ function normalizeVerifyEmailResult(email, data) {
     nextPollAfterSeconds: data.next_poll_after_seconds,
     isValid: data.is_valid ?? data.valid ?? verified,
     isDeliverable: data.is_deliverable ?? data.deliverable ?? verified,
+    isMalformed: data.is_malformed === true || data.verification_verdict === "malformed" || data.verification_status === "malformed" || data.deliverability_status === "malformed",
     isCatchAll: data.email_is_catch_all ?? data.is_catch_all ?? data.catch_all ?? data.diagnostics?.is_catch_all ?? false,
     verifiedForSending: data.verified_for_sending === true,
     verificationVerdict: data.verification_verdict ?? data.verification_status ?? "unknown",
@@ -987,6 +1017,9 @@ function normalizeVerifyEmailResult(email, data) {
     billingMetadata: data.billing_metadata,
     resultReturnedFrom: data.result_returned_from,
     cacheHit: data.cache_hit,
+    negativeCacheHit: data.negative_cache_hit,
+    negativeCacheTtlSeconds: data.negative_cache_ttl_seconds,
+    cacheTier: data.cache_tier,
     freshEnrichmentUsed: data.fresh_enrichment_used,
     liveProviderCalled: data.live_provider_called,
     openrouterCalled: data.openrouter_called,
@@ -1056,6 +1089,14 @@ function normalizeCompanySignalResult(params, data) {
     evidenceCountTotal: data.evidence_count_total,
     evidenceSourcesOmitted: data.evidence_sources_omitted,
     evidenceScope: data.evidence_scope,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
+    creditsUsed: data.credits_used,
+    liveProviderCalled: data.live_provider_called,
+    aiProviderCalled: data.ai_provider_called,
+    byoAiUsed: data.byo_ai_used,
     raw: data
   };
 }
@@ -1333,6 +1374,14 @@ function normalizeSignalToCopyResult(data) {
     empty: data.empty,
     emptyReason: data.empty_reason,
     researchMetadata: data.research_metadata,
+    billingMetadata: data.billing_metadata,
+    resultReturnedFrom: data.result_returned_from,
+    cacheHit: data.cache_hit,
+    freshEnrichmentUsed: data.fresh_enrichment_used,
+    creditsUsed: data.credits_used,
+    liveProviderCalled: data.live_provider_called,
+    aiProviderCalled: data.ai_provider_called,
+    byoAiUsed: data.byo_ai_used,
     variations: (data.variations ?? []).map((variation) => ({
       style: variation.style,
       subjectLine: variation.subject_line ?? "",

package/dist/mcp-config.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaliz/sdk",
-  "version": "1.0.55",
+  "version": "1.0.56",
   "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",