@signaliz/cli 1.0.44 → 1.0.46

package/README.md

@@ -18,21 +18,18 @@ signaliz find-email --company-domain example.com --full-name "Jane Doe" --skip-c
 signaliz verify-email jane@example.com
 # Force a fresh-provider verification instead of reusing cached proof
 signaliz verify-email jane@example.com --skip-cache
+# Preview any single or batch product request without provider calls or credits
+signaliz verify-email jane@example.com --dry-run --json
 # Return early when a provider check runs long, then resume the exact run
 signaliz verify-email jane@example.com --skip-cache --no-wait --json
 signaliz verify-email --verification-run-id run_... --json
 signaliz company-signals --domain example.com --research-prompt "expansion priorities"
-# Resume a queued run in a later agent/process without duplicate spend
-signaliz company-signals --signal-run-id run_...
 signaliz signal-to-copy \
   --company-domain example.com \
   --person-name "Jane Doe" \
   --title "VP Sales" \
   --campaign-offer "pipeline intelligence"
 
-# Resume a queued copy request with the returned ID only
-signaliz signal-to-copy --signal-run-id copy_... --json
-
 # Force fresh signals or opt into slower deep research only when needed
 signaliz signal-to-copy --company-domain example.com --person-name "Jane Doe" \
   --title "VP Sales" --campaign-offer "pipeline intelligence" --skip-cache --deep-search
@@ -70,20 +67,21 @@ JSONL writes one `{ "type": "result", ... }` line per input followed by one
 Failed result lines preserve `errorCode`, `retryEligible`, and
 `retryAfterSeconds` when the API supplies recovery guidance.
 
-If a batch submission response is lost, rerun the same command with
-`--idempotency-key <key>` to recover the original job without duplicate work.
+If a single request or batch submission response is lost, rerun the same
+command with `--idempotency-key <key>` to recover the original request or supported email job
+without duplicate work. Add `--dry-run` to any product command, including one
+using `--input`, to receive a conservative credit ceiling without provider
+calls, jobs, writes, or spend.
 
 Batch input is capped at 5,000 records, concurrency is bounded to `1-50`, input
 order is preserved, and a failed item does not abort successful items.
 Exact duplicate tasks are single-flighted across the full input before
 transport. Find Email and Verify Email inputs larger than 25 use one cache-aware
-recoverable REST job with 500-row result pages. Uniform Company Signal
-Enrichment inputs larger than 25 use one cache-aware recoverable REST job with
-25-row result pages; heterogeneous, no-wait, and per-run recovery inputs keep
-the 25-row request path. Signal to Copy inputs larger than 25 use one
-recoverable REST job when they can reuse available signal data; fresh or
-deep-search requests keep the 25-row path. Signal to Copy also shares company
-research across recipients.
+recoverable REST job with 500-row result pages. Company Signal Enrichment and
+Signal to Copy inputs larger than 25 are chunked client-side into synchronous
+requests of at most 25; the CLI waits for every chunk and emits only complete
+results or terminal per-row errors. Signal to Copy also shares company research
+across recipients.
 
 Connection commands are limited to access infrastructure:
 

package/dist/bin.js

@@ -14,12 +14,12 @@ var HELP = `Signaliz CLI
 Four product commands:
   signaliz find-email --company-domain example.com --full-name "Jane Doe" [--skip-cache]
   signaliz verify-email [jane@example.com] [--verification-run-id run_...] [--no-wait] [--max-wait-ms 600000]
-  signaliz company-signals --domain example.com [--research-prompt "..."] [--no-summary] [--max-wait-ms 1200000]
-  signaliz company-signals --signal-run-id run_...  Resume without duplicate spend
+  signaliz company-signals --domain example.com [--research-prompt "..."] [--search-mode fast|balanced|coverage] [--no-summary] [--max-wait-ms 120000]
+  signaliz company-signals --signal-run-id run_...  Read a completed run without duplicate spend
   signaliz signal-to-copy --company-domain example.com --person-name "Jane Doe" \\
     --title "VP Sales" --campaign-offer "pipeline intelligence" [--signal-run-id run_...] \\
-    [--skip-cache] [--deep-search] [--max-wait-ms 1200000]
-  signaliz signal-to-copy --signal-run-id copy_...  Resume with the returned ID only
+    [--skip-cache] [--deep-search] [--max-wait-ms 120000]
+  signaliz signal-to-copy --signal-run-id copy_...  Reuse a completed signal run
 
 Access and connection:
   signaliz auth login
@@ -39,7 +39,10 @@ Common flags:
   --input <json-or-jsonl-file>  Batch up to 5,000 records with any product command
   --input -                     Read a JSON array or JSONL batch from stdin
   --concurrency <1-50>          Simultaneous API requests for batch input (default: 10)
-  --idempotency-key <key>       Reuse after an ambiguous batch submission to recover the same job
+  --idempotency-key <key>       Reuse after an ambiguous response to recover the same request or job
+  --dry-run                     Return a no-spend plan without provider calls, jobs, or writes
+
+Company Signals and Signal to Copy always wait for complete results or terminal errors.
 `;
 function loadConfig() {
   if (!(0, import_node_fs.existsSync)(CONFIG_FILE)) return {};
@@ -84,6 +87,11 @@ function csvFlag(name) {
   const value = flag(name);
   return value?.split(",").map((item) => item.trim()).filter(Boolean);
 }
+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");
+}
 function readBatchInput() {
   const path = flag("input");
   if (!path) return null;
@@ -121,6 +129,11 @@ function batchOptions() {
     compactDuplicates: !hasFlag("expand-duplicates")
   };
 }
+function rejectAsyncSignalFlags() {
+  if (hasFlag("no-wait") || hasFlag("poll-interval-ms")) {
+    fail("Company Signals and Signal to Copy are always synchronous; --no-wait and --poll-interval-ms are not supported.");
+  }
+}
 function batchOutput(value) {
   if (hasFlag("jsonl")) {
     for (const result of value.results) {
@@ -143,6 +156,15 @@ function batchOutput(value) {
     if (value.failed > 0) process.stdout.write("Use --json to inspect per-record errors.\n");
   });
 }
+function dryRunOutput(value) {
+  output(value, () => {
+    process.stdout.write(`Planned ${value.inputCount} ${value.capability} request(s).
+`);
+    process.stdout.write(`Maximum estimated credits: ${value.estimatedCredits.max}
+`);
+    process.stdout.write("No provider calls, jobs, writes, or credits were used.\n");
+  });
+}
 function resolveApiKey() {
   const key = process.env.SIGNALIZ_API_KEY || loadConfig().apiKey;
   if (!key) fail("No API key configured. Run: signaliz auth login");
@@ -238,7 +260,7 @@ async function auth(args) {
 async function findEmail() {
   const rows = readBatchInput();
   if (rows) {
-    const result2 = await createClient().findEmails(rows.map((value) => {
+    const requests = rows.map((value) => {
       const row = record(value);
       return {
         companyDomain: row.companyDomain || row.company_domain || row.domain,
@@ -249,7 +271,13 @@ async function findEmail() {
         companyName: row.companyName || row.company_name,
         skipCache: row.skipCache ?? row.skip_cache ?? hasFlag("skip-cache")
       };
-    }), batchOptions());
+    });
+    if (hasFlag("dry-run")) {
+      const result3 = await createClient().findEmails(requests, { ...batchOptions(), dryRun: true });
+      dryRunOutput(result3);
+      return;
+    }
+    const result2 = await createClient().findEmails(requests, batchOptions());
     batchOutput(result2);
     return;
   }
@@ -261,15 +289,22 @@ async function findEmail() {
   if (!companyDomain || !fullName && !(firstName && lastName)) {
     fail('Usage: signaliz find-email --company-domain example.com --full-name "Jane Doe"');
   }
-  const result = await createClient().findEmail({
+  const request = {
     companyDomain,
     fullName,
     firstName,
     lastName,
     linkedinUrl,
     companyName: flag("company-name"),
-    skipCache: hasFlag("skip-cache")
-  });
+    skipCache: hasFlag("skip-cache"),
+    idempotencyKey: flag("idempotency-key")
+  };
+  if (hasFlag("dry-run")) {
+    const result2 = await createClient().findEmail({ ...request, dryRun: true });
+    dryRunOutput(result2);
+    return;
+  }
+  const result = await createClient().findEmail(request);
   output(result, () => {
     process.stdout.write(`${result.email || "No email found"} (${result.verificationStatus})
 `);
@@ -286,6 +321,15 @@ async function verifyEmail(args) {
   const rows = readBatchInput();
   if (rows) {
     const emails = rows.map((value) => typeof value === "string" ? value : String(record(value).email || ""));
+    if (hasFlag("dry-run")) {
+      const result3 = await createClient().verifyEmails(emails, {
+        ...batchOptions(),
+        skipCache: hasFlag("skip-cache"),
+        dryRun: true
+      });
+      dryRunOutput(result3);
+      return;
+    }
     const result2 = await createClient().verifyEmails(emails, {
       ...batchOptions(),
       skipCache: hasFlag("skip-cache")
@@ -296,13 +340,20 @@ 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_...]");
-  const result = await createClient().verifyEmail(email, {
+  const options = {
     skipCache: hasFlag("skip-cache"),
     verificationRunId,
     waitForResult: !hasFlag("no-wait"),
     maxWaitMs: numberFlag("max-wait-ms"),
-    pollIntervalMs: numberFlag("poll-interval-ms")
-  });
+    pollIntervalMs: numberFlag("poll-interval-ms"),
+    idempotencyKey: flag("idempotency-key")
+  };
+  if (hasFlag("dry-run")) {
+    const result2 = await createClient().verifyEmail(email, { ...options, dryRun: true });
+    dryRunOutput(result2);
+    return;
+  }
+  const result = await createClient().verifyEmail(email, options);
   output(result, () => {
     if (result.status === "processing") {
       process.stdout.write(`Verification processing: ${result.verificationRunId}
@@ -319,9 +370,10 @@ Catch-all: ${result.isCatchAll}
   });
 }
 async function companySignals() {
+  rejectAsyncSignalFlags();
   const rows = readBatchInput();
   if (rows) {
-    const result2 = await createClient().enrichCompanies(rows.map((value) => {
+    const requests = rows.map((value) => {
       const row = record(value);
       const online = row.online ?? !hasFlag("offline");
       return {
@@ -334,15 +386,20 @@ async function companySignals() {
         lookbackDays: row.lookbackDays || row.lookback_days || numberFlag("lookback-days"),
         online,
         enableDeepSearch: row.enableDeepSearch ?? row.enable_deep_search ?? (online && !hasFlag("shallow")),
+        searchMode: companySignalSearchMode(row.searchMode ?? row.search_mode ?? flag("search-mode")),
         includeSummary: row.includeSummary ?? row.include_summary ?? !hasFlag("no-summary"),
         enableOutreachIntelligence: row.enableOutreachIntelligence ?? row.enable_outreach_intelligence,
         enablePredictiveIntelligence: row.enablePredictiveIntelligence ?? row.enable_predictive_intelligence,
         skipCache: row.skipCache ?? row.skip_cache ?? hasFlag("skip-cache"),
-        waitForResult: row.waitForResult ?? row.wait_for_result ?? !hasFlag("no-wait"),
-        maxWaitMs: row.maxWaitMs || row.max_wait_ms || numberFlag("max-wait-ms"),
-        pollIntervalMs: row.pollIntervalMs || row.poll_interval_ms || numberFlag("poll-interval-ms")
+        maxWaitMs: row.maxWaitMs || row.max_wait_ms || numberFlag("max-wait-ms")
       };
-    }), batchOptions());
+    });
+    if (hasFlag("dry-run")) {
+      const result3 = await createClient().enrichCompanies(requests, { ...batchOptions(), dryRun: true });
+      dryRunOutput(result3);
+      return;
+    }
+    const result2 = await createClient().enrichCompanies(requests, batchOptions());
     batchOutput(result2);
     return;
   }
@@ -350,7 +407,7 @@ async function companySignals() {
   const companyName = flag("company-name");
   const signalRunId = flag("signal-run-id");
   if (!companyDomain && !companyName && !signalRunId) fail("Usage: signaliz company-signals --domain example.com");
-  const result = await createClient().enrichCompanySignals({
+  const request = {
     signalRunId,
     companyDomain,
     companyName,
@@ -360,14 +417,20 @@ async function companySignals() {
     lookbackDays: numberFlag("lookback-days"),
     online: !hasFlag("offline"),
     enableDeepSearch: !hasFlag("offline") && !hasFlag("shallow"),
+    searchMode: companySignalSearchMode(flag("search-mode")),
     includeSummary: !hasFlag("no-summary"),
     enableOutreachIntelligence: hasFlag("outreach-intelligence") || void 0,
     enablePredictiveIntelligence: hasFlag("predictive-intelligence") || void 0,
     skipCache: hasFlag("skip-cache"),
-    waitForResult: !hasFlag("no-wait"),
     maxWaitMs: numberFlag("max-wait-ms"),
-    pollIntervalMs: numberFlag("poll-interval-ms")
-  });
+    idempotencyKey: flag("idempotency-key")
+  };
+  if (hasFlag("dry-run")) {
+    const result2 = await createClient().enrichCompanySignals({ ...request, dryRun: true });
+    dryRunOutput(result2);
+    return;
+  }
+  const result = await createClient().enrichCompanySignals(request);
   output(result, () => {
     process.stdout.write(`Company: ${result.company.name || result.company.domain}
 Signals: ${result.signalCount}
@@ -379,9 +442,10 @@ Signals: ${result.signalCount}
   });
 }
 async function signalToCopy() {
+  rejectAsyncSignalFlags();
   const rows = readBatchInput();
   if (rows) {
-    const result2 = await createClient().createSignalCopyBatch(rows.map((value) => {
+    const requests = rows.map((value) => {
       const row = record(value);
       return {
         companyDomain: row.companyDomain || row.company_domain || row.domain,
@@ -392,11 +456,15 @@ async function signalToCopy() {
         signalRunId: row.signalRunId || row.signal_run_id,
         skipCache: row.skipCache ?? row.skip_cache ?? hasFlag("skip-cache"),
         enableDeepSearch: row.enableDeepSearch ?? row.enable_deep_search ?? hasFlag("deep-search"),
-        waitForResult: row.waitForResult ?? row.wait_for_result ?? !hasFlag("no-wait"),
-        maxWaitMs: row.maxWaitMs || row.max_wait_ms || numberFlag("max-wait-ms"),
-        pollIntervalMs: row.pollIntervalMs || row.poll_interval_ms || numberFlag("poll-interval-ms")
+        maxWaitMs: row.maxWaitMs || row.max_wait_ms || numberFlag("max-wait-ms")
       };
-    }), batchOptions());
+    });
+    if (hasFlag("dry-run")) {
+      const result3 = await createClient().createSignalCopyBatch(requests, { ...batchOptions(), dryRun: true });
+      dryRunOutput(result3);
+      return;
+    }
+    const result2 = await createClient().createSignalCopyBatch(requests, batchOptions());
     batchOutput(result2);
     return;
   }
@@ -408,7 +476,7 @@ async function signalToCopy() {
   if (!signalRunId && (!companyDomain || !personName || !title || !campaignOffer)) {
     fail('Usage: signaliz signal-to-copy --company-domain example.com --person-name "Jane Doe" --title "VP Sales" --campaign-offer "pipeline intelligence" OR signaliz signal-to-copy --signal-run-id copy_...');
   }
-  const result = await createClient().signalToCopy({
+  const request = {
     companyDomain,
     personName,
     title,
@@ -418,8 +486,14 @@ async function signalToCopy() {
     skipCache: hasFlag("skip-cache"),
     enableDeepSearch: hasFlag("deep-search"),
     maxWaitMs: numberFlag("max-wait-ms"),
-    pollIntervalMs: numberFlag("poll-interval-ms")
-  });
+    idempotencyKey: flag("idempotency-key")
+  };
+  if (hasFlag("dry-run")) {
+    const result2 = await createClient().signalToCopy({ ...request, dryRun: true });
+    dryRunOutput(result2);
+    return;
+  }
+  const result = await createClient().signalToCopy(request);
   output(result, () => {
     if (result.variations.length === 0) {
       process.stdout.write(`${String(result.raw.message || "Signal research completed without supported evidence.")}

package/package.json

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