@signaliz/cli 1.0.60 → 1.0.62

package/README.md

@@ -14,6 +14,8 @@ signaliz auth login
 # https://api.signaliz.com/functions/v1/api/v1/signals
 
 signaliz find-email --company-domain example.com --full-name "Jane Doe"
+# An HTTPS LinkedIn person profile URL (/in/<slug>) is sufficient without a name or company domain
+signaliz find-email --linkedin-url "https://www.linkedin.com/in/jane-doe"
 # Force a fresh-provider quality check instead of reusing cached email or verification data
 signaliz find-email --company-domain example.com --full-name "Jane Doe" --skip-cache
 signaliz verify-email jane@example.com

package/dist/bin.js

@@ -7,11 +7,18 @@ var import_node_os = require("os");
 var import_node_path = require("path");
 var import_node_readline = require("readline");
 var import_sdk = require("@signaliz/sdk");
+var CliInputError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliInputError";
+  }
+};
 var CONFIG_DIR = (0, import_node_path.join)((0, import_node_os.homedir)(), ".signaliz");
 var CONFIG_FILE = (0, import_node_path.join)(CONFIG_DIR, "config.json");
 var HELP = `Signaliz CLI
 
 Five product commands:
+  signaliz find-email --linkedin-url https://www.linkedin.com/in/jane-doe [--skip-cache]
   signaliz find-email --company-domain example.com --full-name "Jane Doe" [--skip-cache]
   signaliz find-email --run-id run_...  Resume an existing Find Email run without duplicate spend
   signaliz find-email --job-id job_...  Resume an existing Find Email batch without redispatch
@@ -92,13 +99,25 @@ function numberFlag(name) {
   const value = flag(name);
   if (value === void 0) return void 0;
   const parsed = Number(value);
-  if (!Number.isFinite(parsed)) fail(`--${name} must be a number`);
+  if (!Number.isFinite(parsed)) throw new CliInputError(`--${name} must be a number`);
   return parsed;
 }
 function requireIntegerInRange(value, name, minimum, maximum) {
   if (value === void 0) return;
   if (!Number.isInteger(value) || value < minimum || value > maximum) {
-    throw new RangeError(`${name} must be an integer between ${minimum} and ${maximum}`);
+    throw new CliInputError(`${name} must be an integer between ${minimum} and ${maximum}`);
+  }
+}
+function requireSignalToCopyIdentity(request) {
+  if (stringValue(request.signalRunId)) return;
+  const missing = [
+    ["companyDomain", request.companyDomain],
+    ["personName", request.personName],
+    ["title", request.title],
+    ["campaignOffer", request.campaignOffer]
+  ].filter(([, value]) => !stringValue(value)).map(([name]) => name);
+  if (missing.length > 0) {
+    throw new CliInputError(`Signal to Copy requires signalRunId or: ${missing.join(", ")}`);
   }
 }
 function csvFlag(name) {
@@ -108,7 +127,7 @@ function csvFlag(name) {
 function companySignalSearchMode(value) {
   if (value === void 0 || value === null || value === "") return void 0;
   if (value === "fast" || value === "balanced" || value === "coverage") return value;
-  fail("--search-mode must be fast, balanced, or coverage");
+  throw new CliInputError("--search-mode must be fast, balanced, or coverage");
 }
 function readBatchInput() {
   const path = flag("input");
@@ -118,23 +137,28 @@ function readBatchInput() {
   try {
     raw = (0, import_node_fs.readFileSync)(path === "-" ? 0 : path, "utf8").trim();
   } catch (error) {
-    fail(`Unable to read --input ${source}: ${error instanceof Error ? error.message : String(error)}`);
+    throw new CliInputError(`Unable to read --input ${source}: ${error instanceof Error ? error.message : String(error)}`);
   }
-  if (!raw) fail(`--input ${source} must contain at least one record`);
+  if (!raw) throw new CliInputError(`--input ${source} must contain at least one record`);
   let rows;
   try {
     rows = raw.startsWith("[") ? JSON.parse(raw) : raw.split(/\r?\n/).filter(Boolean).map((line, index) => {
       try {
         return JSON.parse(line);
       } catch {
-        fail(`Invalid JSON on line ${index + 1} of ${source}`);
+        throw new CliInputError(`Invalid JSON on line ${index + 1} of ${source}`);
       }
     });
   } catch (error) {
-    fail(`Invalid JSON in --input ${source}: ${error instanceof Error ? error.message : String(error)}`);
+    if (error instanceof CliInputError) throw error;
+    throw new CliInputError(`Invalid JSON in --input ${source}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!Array.isArray(rows) || rows.length === 0) {
+    throw new CliInputError("--input must be a non-empty JSON array or JSONL file");
+  }
+  if (rows.length > 5e3) {
+    throw new CliInputError(`--input supports at most 5,000 records; received ${rows.length}`);
   }
-  if (!Array.isArray(rows) || rows.length === 0) fail("--input must be a non-empty JSON array or JSONL file");
-  if (rows.length > 5e3) fail(`--input supports at most 5,000 records; received ${rows.length}`);
   return rows;
 }
 function record(value) {
@@ -164,6 +188,11 @@ function customerEmailResult(value, kind) {
   if (String(result.status || "").toLowerCase() === "processing") {
     const verificationRunId2 = result.verificationRunId ?? raw.verification_run_id;
     const runId2 = result.runId ?? raw.run_id ?? verificationRunId2;
+    const creditsUsed2 = safeNonNegativeNumber(result.creditsUsed ?? raw.credits_used);
+    const creditsCharged2 = safeNonNegativeNumber(result.creditsCharged ?? raw.credits_charged);
+    const estimatedExternalCostUsd2 = safeNonNegativeNumber(
+      result.estimatedExternalCostUsd ?? raw.estimated_external_cost_usd
+    );
     return {
       success: true,
       status: "processing",
@@ -171,16 +200,28 @@ function customerEmailResult(value, kind) {
       run_id: runId2,
       ...verificationRunId2 ? { verification_run_id: verificationRunId2 } : {},
       next_poll_after_seconds: result.nextPollAfterSeconds ?? raw.next_poll_after_seconds,
-      suggested_action: result.suggestedAction ?? raw.suggested_action ?? (verificationRunId2 ? "retry_with_verification_run_id" : "retry_with_run_id")
+      suggested_action: result.suggestedAction ?? raw.suggested_action ?? (verificationRunId2 ? "retry_with_verification_run_id" : "retry_with_run_id"),
+      retry_eligible: raw.retry_eligible ?? true,
+      retry_strategy: raw.retry_strategy ?? "same_run_recovery",
+      do_not_auto_resubmit: raw.do_not_auto_resubmit ?? true,
+      recovery_mode: raw.recovery_mode ?? "same_run",
+      recovery_status: raw.recovery_status ?? "pending",
+      ...creditsUsed2 !== null ? { credits_used: creditsUsed2 } : {},
+      ...creditsCharged2 !== null ? { credits_charged: creditsCharged2 } : {},
+      ...typeof raw.live_provider_called === "boolean" ? { live_provider_called: raw.live_provider_called } : {},
+      ...estimatedExternalCostUsd2 !== null ? { estimated_external_cost_usd: estimatedExternalCostUsd2 } : {},
+      ...Object.keys(customerEmailBillingMetadata(raw.billing_metadata)).length > 0 ? { billing_metadata: customerEmailBillingMetadata(raw.billing_metadata) } : {}
     };
   }
   const creditsUsed = Number(result.creditsUsed ?? raw.credits_used ?? 0);
+  const creditsCharged = Number(result.creditsCharged ?? raw.credits_charged ?? creditsUsed);
   const base = {
     email: typeof result.email === "string" && result.email.trim() ? result.email.trim() : null,
     status: "completed",
     success: result.success === true,
     is_valid: typeof result.isValid === "boolean" ? result.isValid : typeof raw.is_valid === "boolean" ? raw.is_valid : result.isVerified ?? false,
-    credits_used: Number.isFinite(creditsUsed) && creditsUsed >= 0 ? creditsUsed : 0
+    credits_used: Number.isFinite(creditsUsed) && creditsUsed >= 0 ? creditsUsed : 0,
+    credits_charged: Number.isFinite(creditsCharged) && creditsCharged >= 0 ? creditsCharged : 0
   };
   if (kind === "find") {
     const verifiedForSending2 = typeof result.isVerifiedForSending === "boolean" ? result.isVerifiedForSending : raw.verified_for_sending === true;
@@ -211,11 +252,29 @@ function customerEmailResult(value, kind) {
       cache_hit: cacheHit2,
       fresh_enrichment_used: freshEnrichmentUsed,
       credits_used: base.credits_used,
+      credits_charged: base.credits_charged,
       live_provider_called: liveProviderCalled
     };
     const estimatedExternalCostUsd2 = safeNonNegativeNumber(
       result.estimatedExternalCostUsd ?? raw.estimated_external_cost_usd
     );
+    const rawErrorCode = String(result.errorCode ?? raw.error_code ?? "").trim().toUpperCase();
+    const terminalErrorCode = ["EMAIL_NOT_FOUND", "PROVIDER_001", "PROVIDER_002"].includes(rawErrorCode) ? rawErrorCode : null;
+    const directRunId = stringValue(result.runId ?? raw.run_id);
+    const verificationRunId2 = stringValue(raw.verification_run_id);
+    const jobId = stringValue(raw.job_id);
+    const rawRetryStrategy = result.retryStrategy ?? raw.retry_strategy;
+    const retryStrategy = ["new_idempotency_key", "same_run_recovery"].includes(String(rawRetryStrategy)) ? String(rawRetryStrategy) : null;
+    const recoveryStatus = String(raw.recovery_status ?? "").trim().toLowerCase();
+    const nestedRunActive = Boolean(verificationRunId2 || jobId) && !["completed", "failed"].includes(recoveryStatus);
+    const manualReviewRequested = (result.suggestedAction ?? raw.suggested_action) === "manual_review";
+    const sameRunRetryProven = retryStrategy === "same_run_recovery" && !manualReviewRequested && nestedRunActive;
+    const newRequestRetryProven = retryStrategy === "new_idempotency_key" && raw.credits_used === 0 && raw.credits_charged === 0;
+    const retryEligible = terminalErrorCode === "PROVIDER_002" && !manualReviewRequested && (result.retryEligible ?? raw.retry_eligible) === true && (sameRunRetryProven || newRequestRetryProven);
+    const suggestedAction = retryEligible && retryStrategy === "same_run_recovery" ? verificationRunId2 ? "retry_with_verification_run_id" : jobId ? "check_job_status" : null : terminalErrorCode === "PROVIDER_002" && !retryEligible ? "manual_review" : null;
+    const terminalError = terminalErrorCode ? String(
+      result.error ?? raw.error ?? raw.message ?? (terminalErrorCode === "EMAIL_NOT_FOUND" ? "No verified email found" : "")
+    ).trim().slice(0, 300) || null : null;
     return {
       ...base,
       is_valid: verifiedForSending2,
@@ -241,11 +300,31 @@ function customerEmailResult(value, kind) {
       billing_metadata: normalizedBillingMetadata,
       ...Object.keys(historicalBillingMetadata2).length > 0 ? { historical_billing_metadata: historicalBillingMetadata2 } : {},
       ...estimatedExternalCostUsd2 !== null ? { estimated_external_cost_usd: estimatedExternalCostUsd2 } : {},
-      ...result.runId ?? raw.run_id ? { run_id: result.runId ?? raw.run_id } : {},
+      ...directRunId ? { run_id: directRunId } : {},
+      ...raw.recovery_mode ? {
+        recovery_mode: raw.recovery_mode,
+        recovery_status: raw.recovery_status ?? "completed"
+      } : {},
       ...raw.cache_publication_status ? {
         cache_publication_status: raw.cache_publication_status,
         cache_publication_retry_eligible: raw.cache_publication_retry_eligible === true,
         ...raw.suggested_action ? { suggested_action: raw.suggested_action } : {}
+      } : {},
+      ...terminalErrorCode ? {
+        email: null,
+        success: false,
+        found: false,
+        is_valid: false,
+        verified_for_sending: false,
+        is_deliverable: false,
+        error_code: terminalErrorCode,
+        retry_eligible: retryEligible,
+        ...terminalError ? { error: terminalError } : {},
+        ...retryEligible && retryStrategy ? { retry_strategy: retryStrategy } : {},
+        ...suggestedAction ? { suggested_action: suggestedAction } : {},
+        ...result.doNotAutoResubmit === true || raw.do_not_auto_resubmit === true ? { do_not_auto_resubmit: true } : {},
+        ...verificationRunId2 ? { verification_run_id: verificationRunId2 } : {},
+        ...jobId ? { job_id: jobId } : {}
       } : {}
     };
   }
@@ -375,7 +454,9 @@ function rejectDurableNoWaitPollingFlags(label) {
   if (!hasFlag("no-wait")) return;
   const conflicts = ["max-wait-ms", "poll-interval-ms", "concurrency"].filter(hasFlag);
   if (conflicts.length > 0) {
-    fail(`${label} --no-wait cannot be combined with ${conflicts.map((name) => `--${name}`).join(", ")}.`);
+    throw new CliInputError(
+      `${label} --no-wait cannot be combined with ${conflicts.map((name) => `--${name}`).join(", ")}.`
+    );
   }
 }
 function recoverableJobOutput(value, command) {
@@ -454,10 +535,11 @@ function resolveBaseUrl() {
   const config = loadConfig();
   return (flag("base-url") || process.env.SIGNALIZ_BASE_URL || process.env.SIGNALIZ_API_URL || config.baseUrl || "https://api.signaliz.com/functions/v1").replace(/\/$/, "");
 }
-function createClient() {
+function createClient(maxRetries) {
   return new import_sdk.Signaliz({
     apiKey: resolveApiKey(),
-    baseUrl: resolveBaseUrl()
+    baseUrl: resolveBaseUrl(),
+    ...maxRetries !== void 0 ? { maxRetries } : {}
   });
 }
 function numberValue(value) {
@@ -470,6 +552,18 @@ function nullableNumberValue(value) {
 function stringValue(value) {
   return typeof value === "string" ? value.trim() : "";
 }
+function hasFindEmailLinkedInIdentity(value) {
+  const linkedinUrl = stringValue(value);
+  if (!linkedinUrl) return false;
+  if (!/^[hH][tT][tT][pP][sS]:\/\/(?:[A-Za-z0-9-]+\.)*[lL][iI][nN][kK][eE][dD][iI][nN]\.[cC][oO][mM]\/[iI][nN]\/[^/?#]+\/?(?:[?#].*)?$/.test(linkedinUrl)) return false;
+  try {
+    const url = new URL(linkedinUrl);
+    const hostname = url.hostname.toLowerCase();
+    return url.protocol === "https:" && !url.username && !url.password && !url.port && (hostname === "linkedin.com" || hostname.endsWith(".linkedin.com")) && /^\/in\/[^/]+\/?$/i.test(url.pathname);
+  } catch {
+    return false;
+  }
+}
 function signalsEverythingErrorType(status) {
   if (status === 400 || status === 422) return "validation";
   if (status === 401) return "auth_expired";
@@ -497,9 +591,9 @@ function normalizeSignalsEverythingResult(request, value) {
         source: stringValue(item.source)
       };
     }).filter((item) => Boolean(item.url)) : [];
-    const eventDate = stringValue(signal.event_date || signal.date) || evidence[0]?.publishedAt || "";
-    const sourceUrl = stringValue(signal.source_url || signal.url) || evidence[0]?.url || null;
-    if (!eventDate || !sourceUrl || !evidence.some((item) => Boolean(item.publishedAt))) {
+    const eventDate = stringValue(signal.event_date || signal.date);
+    const sourceUrl = stringValue(signal.source_url || signal.url);
+    if (!eventDate || !sourceUrl || !evidence.some((item) => item.url === sourceUrl && item.publishedAt === eventDate)) {
       throw new Error("Signals Everything response violated the dated-evidence and source-URL contract.");
     }
     return {
@@ -522,6 +616,7 @@ function normalizeSignalsEverythingResult(request, value) {
   const status = statuses.has(statusValue) ? statusValue : signals2.length > 0 ? "completed" : "failed";
   const guardrail = record(value.cost_guardrail);
   const maxCost = numberValue(guardrail.max_cost_per_qualified_signal_usd);
+  const costSource = stringValue(guardrail.cost_source);
   const identityCostSource = stringValue(guardrail.identity_cost_source);
   const warnings = Array.isArray(value.warnings) ? value.warnings.filter((warning) => typeof warning === "string") : void 0;
   return {
@@ -539,6 +634,13 @@ function normalizeSignalsEverythingResult(request, value) {
     ...maxCost === void 0 ? {} : {
       costGuardrail: {
         maxCostPerQualifiedSignalUsd: maxCost,
+        projectedSourceCostUsd: nullableNumberValue(guardrail.projected_source_cost_usd),
+        maxSourceCostUsd: nullableNumberValue(guardrail.max_source_cost_usd),
+        projectedCostPerRequestedCompanySignalUsd: nullableNumberValue(
+          guardrail.projected_cost_per_requested_company_signal_usd
+        ),
+        sourceCostUsd: nullableNumberValue(guardrail.source_cost_usd),
+        costSource: ["observed", "catalog_preflight", "catalog_bounded", "mixed", "unavailable"].includes(costSource) ? costSource : void 0,
         costPerQualifiedSignalUsd: nullableNumberValue(guardrail.cost_per_qualified_signal_usd),
         identityResolutionCostUsd: nullableNumberValue(guardrail.identity_resolution_cost_usd),
         identityCostSource: [
@@ -547,7 +649,13 @@ function normalizeSignalsEverythingResult(request, value) {
           "not_used",
           "unavailable"
         ].includes(identityCostSource) ? identityCostSource : void 0,
-        identityProviderRequests: numberValue(guardrail.identity_provider_requests)
+        identityProviderRequests: numberValue(guardrail.identity_provider_requests),
+        qualifiedCompanySignalCount: numberValue(guardrail.qualified_company_signal_count),
+        returnedCompanySignalCount: numberValue(guardrail.returned_company_signal_count),
+        availableCompanySignalCount: numberValue(guardrail.available_company_signal_count),
+        acquisitionCandidateLimit: numberValue(guardrail.acquisition_candidate_limit),
+        minimumQualifiedCompanySignals: numberValue(guardrail.minimum_qualified_company_signals),
+        withinLimit: guardrail.within_limit === true
       }
     },
     ...warnings?.length ? { warnings } : {},
@@ -702,7 +810,9 @@ async function findEmail() {
       "skip-cache"
     ].filter(hasFlag);
     if (conflicts.length > 0) {
-      fail(`Find Email --job-id cannot be combined with ${conflicts.map((name) => `--${name}`).join(", ")}.`);
+      throw new CliInputError(
+        `Find Email --job-id cannot be combined with ${conflicts.map((name) => `--${name}`).join(", ")}.`
+      );
     }
     const result2 = await createClient().resumeFindEmailBatch(jobId, {
       pageSize: numberFlag("page-size"),
@@ -732,6 +842,15 @@ async function findEmail() {
         idempotencyKey
       };
     });
+    const invalidIndexes = requests.flatMap((request2, index) => {
+      if (stringValue(request2.runId)) return [];
+      if (hasFindEmailLinkedInIdentity(request2.linkedinUrl)) return [];
+      const hasName = stringValue(request2.fullName) || stringValue(request2.firstName) && stringValue(request2.lastName);
+      return !stringValue(request2.companyDomain) || !hasName ? [index] : [];
+    });
+    if (invalidIndexes.length === requests.length) {
+      throw new CliInputError("Every Find Email row must provide an HTTPS LinkedIn person profile URL (/in/<slug>), or company_domain with full_name or first_name and last_name.");
+    }
     if (hasFlag("dry-run")) {
       const result3 = await createClient().findEmails(requests, { ...batchOptions(), dryRun: true });
       dryRunOutput(result3);
@@ -747,8 +866,9 @@ async function findEmail() {
   const firstName = flag("first-name");
   const lastName = flag("last-name");
   const linkedinUrl = flag("linkedin-url");
-  if (!runId && (!companyDomain || !fullName && !(firstName && lastName))) {
-    fail('Usage: signaliz find-email --company-domain example.com --full-name "Jane Doe", or signaliz find-email --run-id run_...');
+  const hasNameAndDomain = Boolean(companyDomain && (fullName || firstName && lastName));
+  if (!runId && !hasFindEmailLinkedInIdentity(linkedinUrl) && !hasNameAndDomain) {
+    throw new CliInputError("Find Email must provide an HTTPS --linkedin-url person profile (/in/<slug>), or --company-domain with --full-name or --first-name and --last-name, or --run-id.");
   }
   const request = runId ? { runId } : {
     companyDomain,
@@ -761,11 +881,11 @@ async function findEmail() {
     idempotencyKey: flag("idempotency-key")
   };
   if (hasFlag("dry-run")) {
-    const result2 = await createClient().findEmail({ ...request, dryRun: true });
+    const result2 = await createClient(runId ? 0 : void 0).findEmail({ ...request, dryRun: true });
     dryRunOutput(result2);
     return;
   }
-  const result = await createClient().findEmail(request);
+  const result = await createClient(runId ? 0 : void 0).findEmail(request);
   const publicResult = customerEmailResult(result, "find");
   if (outputFailedCoreProduct(publicResult, "No verified email found")) return;
   output(publicResult, () => {
@@ -805,7 +925,7 @@ async function verifyEmail(args) {
         ...positionalEmail ? ["email argument"] : [],
         ...conflicts.map((name) => `--${name}`)
       ];
-      fail(`Verify Email --job-id cannot be combined with ${conflictList.join(", ")}.`);
+      throw new CliInputError(`Verify Email --job-id cannot be combined with ${conflictList.join(", ")}.`);
     }
     const result2 = await createClient().resumeVerifyEmailBatch(jobId, {
       pageSize: numberFlag("page-size"),
@@ -846,7 +966,9 @@ async function verifyEmail(args) {
   }
   const email = args[0] && !args[0].startsWith("--") ? args[0] : flag("email");
   const verificationRunId = flag("verification-run-id");
-  if (!email && !verificationRunId) fail("Usage: signaliz verify-email [jane@example.com] [--verification-run-id run_...]");
+  if (!email && !verificationRunId) {
+    throw new CliInputError("Usage: signaliz verify-email [jane@example.com] [--verification-run-id run_...]");
+  }
   const options = {
     skipCache: hasFlag("skip-cache"),
     verificationRunId,
@@ -856,11 +978,11 @@ async function verifyEmail(args) {
     idempotencyKey: flag("idempotency-key")
   };
   if (hasFlag("dry-run")) {
-    const result2 = await createClient().verifyEmail(email, { ...options, dryRun: true });
+    const result2 = await createClient(verificationRunId ? 0 : void 0).verifyEmail(email, { ...options, dryRun: true });
     dryRunOutput(result2);
     return;
   }
-  const result = await createClient().verifyEmail(email, options);
+  const result = await createClient(verificationRunId ? 0 : void 0).verifyEmail(email, options);
   const publicResult = customerEmailResult(result, "verify");
   if (outputFailedCoreProduct(publicResult, "Email verification failed")) return;
   output(publicResult, () => {
@@ -918,7 +1040,9 @@ async function companySignals() {
       "concurrency"
     ].filter(hasFlag);
     if (conflicts.length > 0) {
-      fail(`Company Signals --job-id cannot be combined with ${conflicts.map((name) => `--${name}`).join(", ")}.`);
+      throw new CliInputError(
+        `Company Signals --job-id cannot be combined with ${conflicts.map((name) => `--${name}`).join(", ")}.`
+      );
     }
     const result2 = await createClient().resumeCompanySignalBatch(jobId, {
       pageSize: numberFlag("page-size"),
@@ -960,9 +1084,46 @@ async function companySignals() {
     for (const request2 of requests) {
       requireIntegerInRange(request2.targetSignalCount, "targetSignalCount", 1, 15);
       requireIntegerInRange(request2.lookbackDays, "lookbackDays", 1, 365);
+      requireIntegerInRange(request2.maxWaitMs, "maxWaitMs", 1e4, 12e4);
+    }
+    if (durableBatch && requests.some((request2) => request2.includeCandidateEvidence === true)) {
+      throw new CliInputError(
+        "includeCandidateEvidence is not supported in Company Signals batches larger than 25 because rejected evidence diagnostics are intentionally excluded from durable scale storage; split diagnostic requests into batches of at most 25."
+      );
+    }
+    if (durableBatch) {
+      const controlKey = (request2) => JSON.stringify({
+        researchPrompt: request2.researchPrompt,
+        signalTypes: request2.signalTypes,
+        targetSignalCount: request2.targetSignalCount,
+        lookbackDays: request2.lookbackDays,
+        online: request2.online,
+        enableDeepSearch: request2.enableDeepSearch,
+        searchMode: request2.searchMode ?? "balanced",
+        includeSummary: request2.includeSummary,
+        enableOutreachIntelligence: request2.enableOutreachIntelligence,
+        enablePredictiveIntelligence: request2.enablePredictiveIntelligence,
+        skipCache: request2.skipCache,
+        includeCandidateEvidence: request2.includeCandidateEvidence
+      });
+      const firstControlKey = controlKey(requests[0]);
+      const incompatible = requests.some(
+        (request2) => Boolean(stringValue(request2.signalRunId)) || Boolean(stringValue(request2.idempotencyKey)) || !stringValue(request2.companyDomain) && !stringValue(request2.companyName) || controlKey(request2) !== firstControlKey
+      );
+      if (incompatible) {
+        throw new CliInputError(
+          "Company Signals batches larger than 25 require homogeneous new-enrichment rows with company identity only and uniform controls; split recovery or mixed-control rows into batches of at most 25."
+        );
+      }
+    } else if (hasFlag("no-wait") && !hasFlag("dry-run")) {
+      throw new CliInputError(
+        "Company Signals --no-wait requires more than 25 homogeneous new-enrichment rows; recovery reads and mixed controls must use batches of at most 25."
+      );
     }
     if (hasFlag("dry-run")) {
-      if (hasFlag("no-wait")) fail("Company Signals --no-wait cannot be combined with --dry-run.");
+      if (hasFlag("no-wait")) {
+        throw new CliInputError("Company Signals --no-wait cannot be combined with --dry-run.");
+      }
       const result3 = await createClient().enrichCompanies(requests, { ...batchOptions(), dryRun: true });
       dryRunOutput(result3);
       return;
@@ -979,12 +1140,18 @@ async function companySignals() {
     batchOutput(customerSignalBatch(result2));
     return;
   }
-  if (hasFlag("no-wait")) fail("Company Signals --no-wait requires --input with more than 25 homogeneous rows.");
-  if (hasFlag("poll-interval-ms")) fail("Company Signals --poll-interval-ms requires --input or --job-id.");
+  if (hasFlag("no-wait")) {
+    throw new CliInputError("Company Signals --no-wait requires --input with more than 25 homogeneous rows.");
+  }
+  if (hasFlag("poll-interval-ms")) {
+    throw new CliInputError("Company Signals --poll-interval-ms requires --input or --job-id.");
+  }
   const companyDomain = flag("domain") || flag("company-domain");
   const companyName = flag("company-name");
   const signalRunId = flag("signal-run-id");
-  if (!companyDomain && !companyName && !signalRunId) fail("Usage: signaliz company-signals --domain example.com");
+  if (!companyDomain && !companyName && !signalRunId) {
+    throw new CliInputError("Usage: signaliz company-signals --domain example.com");
+  }
   const request = {
     signalRunId,
     companyDomain,
@@ -1004,6 +1171,9 @@ async function companySignals() {
     maxWaitMs: numberFlag("max-wait-ms"),
     idempotencyKey: flag("idempotency-key")
   };
+  requireIntegerInRange(request.targetSignalCount, "targetSignalCount", 1, 15);
+  requireIntegerInRange(request.lookbackDays, "lookbackDays", 1, 365);
+  requireIntegerInRange(request.maxWaitMs, "maxWaitMs", 1e4, 12e4);
   if (hasFlag("dry-run")) {
     const result2 = await createClient().enrichCompanySignals({ ...request, dryRun: true });
     dryRunOutput(result2);
@@ -1167,7 +1337,9 @@ async function signalToCopy() {
       "concurrency"
     ].filter(hasFlag);
     if (conflicts.length > 0) {
-      fail(`Signal to Copy --job-id cannot be combined with ${conflicts.map((name) => `--${name}`).join(", ")}.`);
+      throw new CliInputError(
+        `Signal to Copy --job-id cannot be combined with ${conflicts.map((name) => `--${name}`).join(", ")}.`
+      );
     }
     const result2 = await createClient().resumeSignalCopyBatch(jobId, {
       pageSize: numberFlag("page-size"),
@@ -1199,8 +1371,27 @@ async function signalToCopy() {
         idempotencyKey: row.idempotencyKey || row.idempotency_key
       };
     });
+    for (const request2 of requests) {
+      requireIntegerInRange(request2.lookbackDays, "lookbackDays", 1, 365);
+      requireIntegerInRange(request2.maxWaitMs, "maxWaitMs", 1e4, 12e4);
+      requireSignalToCopyIdentity(request2);
+    }
+    if (durableBatch) {
+      const invalidIndex = requests.findIndex(
+        (request2) => request2.skipCache === true || request2.enableDeepSearch === true || Boolean(stringValue(request2.idempotencyKey)) || request2.maxWaitMs !== void 0 || !stringValue(request2.companyDomain) || !stringValue(request2.personName) || !stringValue(request2.title) || !stringValue(request2.campaignOffer)
+      );
+      if (invalidIndex >= 0) {
+        throw new CliInputError(
+          `Signal to Copy batches larger than 25 are available-data-only; row ${invalidIndex} requests fresh/deep/synchronous controls or lacks required recipient fields. Split fresh requests into batches of at most 25.`
+        );
+      }
+    } else if (hasFlag("no-wait") && !hasFlag("dry-run")) {
+      throw new CliInputError("Signal to Copy --no-wait requires a durable batch of more than 25 rows.");
+    }
     if (hasFlag("dry-run")) {
-      if (hasFlag("no-wait")) fail("Signal to Copy --no-wait cannot be combined with --dry-run.");
+      if (hasFlag("no-wait")) {
+        throw new CliInputError("Signal to Copy --no-wait cannot be combined with --dry-run.");
+      }
       const result3 = await createClient().createSignalCopyBatch(requests, { ...batchOptions(), dryRun: true });
       dryRunOutput(result3);
       return;
@@ -1217,8 +1408,12 @@ async function signalToCopy() {
     batchOutput(customerSignalBatch(result2));
     return;
   }
-  if (hasFlag("no-wait")) fail("Signal to Copy --no-wait requires --input with more than 25 available-data-only rows.");
-  if (hasFlag("poll-interval-ms")) fail("Signal to Copy --poll-interval-ms requires --input or --job-id.");
+  if (hasFlag("no-wait")) {
+    throw new CliInputError("Signal to Copy --no-wait requires --input with more than 25 available-data-only rows.");
+  }
+  if (hasFlag("poll-interval-ms")) {
+    throw new CliInputError("Signal to Copy --poll-interval-ms requires --input or --job-id.");
+  }
   const companyDomain = flag("company-domain") || flag("domain");
   const personName = flag("person-name");
   const title = flag("title");
@@ -1237,6 +1432,9 @@ async function signalToCopy() {
     maxWaitMs: numberFlag("max-wait-ms"),
     idempotencyKey: flag("idempotency-key")
   };
+  requireIntegerInRange(request.lookbackDays, "lookbackDays", 1, 365);
+  requireIntegerInRange(request.maxWaitMs, "maxWaitMs", 1e4, 12e4);
+  requireSignalToCopyIdentity(request);
   if (hasFlag("dry-run")) {
     const result2 = await createClient().signalToCopy({ ...request, dryRun: true });
     dryRunOutput(result2);
@@ -1340,19 +1538,30 @@ main().catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   if (hasFlag("json") || hasFlag("jsonl")) {
     const signalizError = error instanceof import_sdk.SignalizError ? error : null;
+    const cliInputError = error instanceof CliInputError;
+    const recoveryReadZeroSpend = signalizError?.details?.retry_strategy === "same_run_recovery" && signalizError.details.credits_used === 0 && signalizError.details.credits_charged === 0 && (process.argv[2] === "find-email" && hasFlag("run-id") || process.argv[2] === "verify-email" && hasFlag("verification-run-id"));
     process.stdout.write(`${stringifyMachineJson({
       success: false,
       error: "product_request_failed",
-      error_code: signalizError?.code || (error instanceof RangeError || error instanceof TypeError ? "INPUT_001" : "CLI_ERROR"),
+      error_code: signalizError?.code || (cliInputError ? "INPUT_001" : "CLI_ERROR"),
       message,
       retry_eligible: signalizError?.isRetryable ?? false,
       ...signalizError?.retryAfter !== void 0 ? {
         retry_after: signalizError.retryAfter,
         retry_after_seconds: signalizError.retryAfter
       } : {},
-      ...signalizError?.details?.retry_strategy === "new_idempotency_key" ? { retry_strategy: "new_idempotency_key" } : {},
+      ...["new_idempotency_key", "same_run_recovery"].includes(String(signalizError?.details?.retry_strategy || "")) ? { retry_strategy: signalizError?.details?.retry_strategy } : {},
       ...signalizError?.details?.credits_used === 0 ? { credits_used: 0 } : {},
       ...signalizError?.details?.credits_charged === 0 ? { credits_charged: 0 } : {},
+      ...signalizError?.details?.live_provider_called === false || recoveryReadZeroSpend ? { live_provider_called: false } : {},
+      ...signalizError?.details?.estimated_external_cost_usd === 0 || recoveryReadZeroSpend ? { estimated_external_cost_usd: 0 } : {},
+      ...signalizError?.details?.do_not_auto_resubmit === true ? { do_not_auto_resubmit: true } : {},
+      ...cliInputError ? {
+        credits_used: 0,
+        credits_charged: 0,
+        live_provider_called: false,
+        estimated_external_cost_usd: 0
+      } : {},
       ...typeof signalizError?.details?.run_id === "string" ? { run_id: signalizError.details.run_id } : {},
       ...typeof signalizError?.details?.verification_run_id === "string" ? { verification_run_id: signalizError.details.verification_run_id } : {},
       ...typeof signalizError?.details?.job_id === "string" ? { job_id: signalizError.details.job_id } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaliz/cli",
-  "version": "1.0.60",
+  "version": "1.0.62",
   "description": "Signaliz CLI for Signals Everything, Find Email, Verify Email, Company Signal Enrichment, and Signal to Copy AI.",
   "bin": {
     "signaliz": "dist/bin.js"
@@ -29,7 +29,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@signaliz/sdk": "^1.0.63"
+    "@signaliz/sdk": "^1.0.66"
   },
   "devDependencies": {
     "tsup": "^8.0.0",