@signaliz/cli 1.0.56 → 1.0.57

package/README.md

@@ -40,6 +40,9 @@ signaliz signal-to-copy --company-domain example.com --person-name "Jane Doe" \
 # Signals Everything returns distinct companies with a source-backed signal.
 # It is asynchronous by default; add --wait or resume the returned run ID.
 signaliz signals "companies that just got funded" --limit 100 --sources web,news
+signaliz signals "companies showing signals they need account-signal automation" \
+  --icp-context "B2B SaaS with outbound teams and manual account research" \
+  --limit 100 --sources web,news
 signaliz signals --signal-search-run-id run_... --wait --json
 ```
 
@@ -106,6 +109,14 @@ copy row explicitly requests fresh or deep research, the CLI preserves that
 behavior with synchronous chunks of at most 25. Signal to Copy also shares
 company research across recipients.
 
+Every command uses the authenticated workspace. Find Email and Verify Email
+honor that workspace's configured cache window; eligible hits cost 0 credits,
+while fresh discovery or verification is charged on every plan. Team, Agency,
+and Pay-As-You-Go include fresh Company Signals and Signal to Copy. Those plans
+still check eligible workspace signal data first even when Company Signals is
+set to No cache. `--lookback-days` remains a hard evidence-age bound for both
+cached and fresh Company Signals and Signal to Copy results.
+
 Signals Everything is a query-first company discovery command rather than a
 row batch. It returns only dated, source-linked signals that contain both a
 company name and company domain. The default request is 100 companies and the
@@ -113,7 +124,8 @@ maximum is 1,000. It is included on Team and Agency plans, is resumable with
 `signal_search_run_id`, and reports a strict source-cost guardrail: results are
 only returned when source cost is below $0.01 per qualified company. A request
 is a ceiling, not a promise: it can return fewer results when public evidence
-cannot verify both a date and company identity.
+cannot verify both a date and company identity. Use `--icp-context` to qualify
+an open-ended signal request against a target market.
 
 Connection commands are limited to access infrastructure:
 

package/dist/bin.js

@@ -13,14 +13,15 @@ var HELP = `Signaliz CLI
 
 Five product commands:
   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 verify-email [jane@example.com] [--verification-run-id run_...] [--no-wait] [--max-wait-ms 600000]
   signaliz company-signals --domain example.com [--research-prompt "..."] [--search-mode fast|balanced|coverage] [--include-candidate-evidence] [--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 120000]
+    [--lookback-days 90] [--skip-cache] [--deep-search] [--max-wait-ms 120000]
   signaliz signal-to-copy --signal-run-id copy_...  Reuse a completed signal run
-  signaliz signals "companies that just got funded" [--limit 100] [--sources web,news] [--wait]
+  signaliz signals "companies that just got funded" [--icp-context "..."] [--limit 100] [--sources web,news] [--wait]
   signaliz signals --signal-search-run-id run_...  Resume an existing company-attributed signal search
 
 Access and connection:
@@ -42,6 +43,8 @@ Common flags:
   --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 response to recover the same request or job
+  --run-id <run_...>            Resume one existing Find Email run without dispatching new work
+  --icp-context <text>          Optional ICP, product, or pain context that returned signals must support
   --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. Signals Everything is asynchronous by default; use --wait to poll until it completes.
@@ -126,24 +129,27 @@ function record(value) {
 }
 function customerEmailResult(value) {
   const result = record(value);
-  if (String(result.status || "").toLowerCase() === "processing") return result;
   const raw = record(result.raw);
-  const verifiedForSending = typeof raw.verified_for_sending === "boolean" ? raw.verified_for_sending : typeof raw._verified_for_sending === "boolean" ? raw._verified_for_sending : result.raw === void 0 && typeof result.verifiedForSending === "boolean" ? result.verifiedForSending : result.raw === void 0 && typeof result.isVerifiedForSending === "boolean" ? result.isVerifiedForSending : void 0;
-  const isCatchAll = typeof result.isCatchAll === "boolean" ? result.isCatchAll : void 0;
-  const isMalformed = result.isMalformed === true || raw.is_malformed === true;
-  const verificationStatus = result.verificationStatus || result.verificationVerdict;
+  if (String(result.status || "").toLowerCase() === "processing") {
+    const verificationRunId = result.verificationRunId ?? raw.verification_run_id;
+    const runId = result.runId ?? raw.run_id ?? verificationRunId;
+    return {
+      success: true,
+      status: "processing",
+      email: null,
+      run_id: runId,
+      ...verificationRunId ? { verification_run_id: verificationRunId } : {},
+      next_poll_after_seconds: result.nextPollAfterSeconds ?? raw.next_poll_after_seconds,
+      suggested_action: result.suggestedAction ?? raw.suggested_action ?? (verificationRunId ? "retry_with_verification_run_id" : "retry_with_run_id")
+    };
+  }
+  const creditsUsed = Number(result.creditsUsed ?? raw.credits_used ?? 0);
   return {
-    ...result,
     email: typeof result.email === "string" && result.email.trim() ? result.email.trim() : null,
     status: "completed",
     success: result.success === true,
-    is_valid: verifiedForSending ?? result.isValid ?? result.isVerified ?? false,
-    credits_used: Number(result.creditsUsed || 0),
-    ...verifiedForSending !== void 0 ? { verified_for_sending: verifiedForSending } : {},
-    ...isCatchAll !== void 0 ? { email_is_catch_all: isCatchAll, is_catch_all: isCatchAll } : {},
-    ...typeof result.isMalformed === "boolean" || typeof raw.is_malformed === "boolean" ? { is_malformed: isMalformed } : {},
-    ...verificationStatus ? { verification_status: verificationStatus, verification_verdict: verificationStatus } : {},
-    ...result.billingMetadata ? { billing_metadata: result.billingMetadata } : {}
+    is_valid: typeof raw.is_valid === "boolean" ? raw.is_valid : result.isValid ?? result.isVerified ?? false,
+    credits_used: Number.isFinite(creditsUsed) && creditsUsed >= 0 ? creditsUsed : 0
   };
 }
 function customerEmailBatch(value) {
@@ -151,10 +157,19 @@ function customerEmailBatch(value) {
     ...value,
     results: value.results.map((item) => {
       const row = record(item);
-      return row.data ? { ...row, data: customerEmailResult(row.data) } : row;
+      return promoteBatchRecoveryMetadata(row.data ? { ...row, data: customerEmailResult(row.data) } : row);
     })
   };
 }
+function promoteBatchRecoveryMetadata(row) {
+  return {
+    ...row,
+    ...typeof row.runId === "string" ? { run_id: row.runId } : {},
+    ...typeof row.verificationRunId === "string" ? { verification_run_id: row.verificationRunId } : {},
+    ...typeof row.jobId === "string" ? { job_id: row.jobId } : {},
+    ...typeof row.suggestedAction === "string" ? { suggested_action: row.suggestedAction } : {}
+  };
+}
 function customerSignalResult(value) {
   const result = record(value);
   const raw = record(result.raw);
@@ -176,7 +191,7 @@ function customerSignalBatch(value) {
     ...value,
     results: value.results.map((item) => {
       const row = record(item);
-      return row.data ? { ...row, data: customerSignalResult(row.data) } : row;
+      return promoteBatchRecoveryMetadata(row.data ? { ...row, data: customerSignalResult(row.data) } : row);
     })
   };
 }
@@ -256,6 +271,9 @@ function numberValue(value) {
   const number = Number(value);
   return Number.isFinite(number) ? number : void 0;
 }
+function nullableNumberValue(value) {
+  return value === null ? null : numberValue(value);
+}
 function stringValue(value) {
   return typeof value === "string" ? value.trim() : "";
 }
@@ -311,6 +329,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 identityCostSource = stringValue(guardrail.identity_cost_source);
   const warnings = Array.isArray(value.warnings) ? value.warnings.filter((warning) => typeof warning === "string") : void 0;
   return {
     success: value.success !== false,
@@ -327,7 +346,15 @@ function normalizeSignalsEverythingResult(request, value) {
     ...maxCost === void 0 ? {} : {
       costGuardrail: {
         maxCostPerQualifiedSignalUsd: maxCost,
-        costPerQualifiedSignalUsd: value.cost_guardrail && typeof value.cost_guardrail === "object" ? numberValue(guardrail.cost_per_qualified_signal_usd) ?? (guardrail.cost_per_qualified_signal_usd === null ? null : void 0) : void 0
+        costPerQualifiedSignalUsd: nullableNumberValue(guardrail.cost_per_qualified_signal_usd),
+        identityResolutionCostUsd: nullableNumberValue(guardrail.identity_resolution_cost_usd),
+        identityCostSource: [
+          "observed_zero_credit_receipts",
+          "contractual_zero_cost",
+          "not_used",
+          "unavailable"
+        ].includes(identityCostSource) ? identityCostSource : void 0,
+        identityProviderRequests: numberValue(guardrail.identity_provider_requests)
       }
     },
     ...warnings?.length ? { warnings } : {},
@@ -342,6 +369,7 @@ async function discoverSignalsEverything(request) {
     ...request.idempotencyKey ? { idempotency_key: request.idempotencyKey } : {}
   } : {
     query: request.query,
+    ...request.icpContext ? { icp_context: request.icpContext } : {},
     limit: request.limit ?? 100,
     ...request.sources ? { sources: request.sources } : {},
     ...request.lookbackDays === void 0 ? {} : { lookback_days: request.lookbackDays },
@@ -469,6 +497,8 @@ async function findEmail() {
   if (rows) {
     const requests = rows.map((value) => {
       const row = record(value);
+      const runId2 = row.runId || row.run_id;
+      if (runId2) return { runId: runId2 };
       return {
         companyDomain: row.companyDomain || row.company_domain || row.domain,
         fullName: row.fullName || row.full_name || row.name,
@@ -489,14 +519,15 @@ async function findEmail() {
     return;
   }
   const companyDomain = flag("company-domain") || flag("domain");
+  const runId = flag("run-id");
   const fullName = flag("full-name");
   const firstName = flag("first-name");
   const lastName = flag("last-name");
   const linkedinUrl = flag("linkedin-url");
-  if (!companyDomain || !fullName && !(firstName && lastName)) {
-    fail('Usage: signaliz find-email --company-domain example.com --full-name "Jane Doe"');
+  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 request = {
+  const request = runId ? { runId } : {
     companyDomain,
     fullName,
     firstName,
@@ -515,21 +546,23 @@ async function findEmail() {
   const publicResult = customerEmailResult(result);
   if (outputFailedCoreProduct(publicResult, "No verified email found")) return;
   output(publicResult, () => {
-    process.stdout.write(`${result.email || "No email found"} (${result.verificationStatus})
+    if (result.status === "processing" && result.runId) {
+      process.stdout.write(`Find Email processing: ${result.runId}
 `);
-    process.stdout.write(`Verified for sending: ${result.isVerifiedForSending}
+      process.stdout.write(`Retry after ${result.nextPollAfterSeconds || 3} seconds with --run-id ${result.runId}
 `);
-    process.stdout.write(`Catch-all: ${result.isCatchAll}
+      return;
+    }
+    process.stdout.write(`Email: ${publicResult.email ?? "Not found"}
 `);
-    process.stdout.write(`Confidence: ${result.confidence}
+    process.stdout.write(`Status: ${publicResult.status}
 `);
-    process.stdout.write(`Provider: ${result.providerUsed}
+    process.stdout.write(`Success: ${publicResult.success}
 `);
-    process.stdout.write(`Credits used: ${result.creditsUsed || 0}
+    process.stdout.write(`Valid: ${publicResult.is_valid}
+`);
+    process.stdout.write(`Credits used: ${publicResult.credits_used}
 `);
-    if (result.needsReverification) {
-      process.stdout.write("Send safety: stale verification; rerun with --skip-cache before sending\n");
-    }
   });
 }
 async function verifyEmail(args) {
@@ -579,15 +612,15 @@ async function verifyEmail(args) {
 `);
       return;
     }
-    process.stdout.write(`${result.email}: ${result.verifiedForSending ? "verified for sending" : "not verified for sending"}
+    process.stdout.write(`Email: ${publicResult.email ?? "Not found"}
+`);
+    process.stdout.write(`Status: ${publicResult.status}
+`);
+    process.stdout.write(`Success: ${publicResult.success}
 `);
-    process.stdout.write(`Valid: ${result.isValid}
-Deliverable: ${result.isDeliverable}
-Catch-all: ${result.isCatchAll}
-Verdict: ${result.verificationVerdict}
+    process.stdout.write(`Valid: ${publicResult.is_valid}
 `);
-    if (result.isMalformed) process.stdout.write("Malformed: true (rejected before provider call)\n");
-    process.stdout.write(`Credits used: ${result.creditsUsed || 0}
+    process.stdout.write(`Credits used: ${publicResult.credits_used}
 `);
   });
 }
@@ -676,6 +709,7 @@ function signalQueryFromArgs(args) {
     "--limit",
     "--sources",
     "--lookback-days",
+    "--icp-context",
     "--signal-search-run-id",
     "--idempotency-key",
     "--max-wait-ms",
@@ -709,8 +743,13 @@ async function signals(args) {
   if (sourceValues?.some((source) => !["web", "news"].includes(source))) {
     fail("--sources must contain only web or news");
   }
+  const icpContext = flag("icp-context");
+  if (hasFlag("icp-context") && (typeof icpContext !== "string" || icpContext.trim().length < 2 || icpContext.trim().length > 4e3)) {
+    fail("--icp-context must contain between 2 and 4000 characters");
+  }
   const request = {
     query,
+    icpContext: icpContext?.trim(),
     signalSearchRunId,
     limit: numberFlag("limit"),
     sources: sourceValues,
@@ -764,6 +803,14 @@ async function signals(args) {
         `Source cost per qualified company: ${guardrail.costPerQualifiedSignalUsd ?? "n/a"} (must be < $${guardrail.maxCostPerQualifiedSignalUsd})
 `
       );
+      if (guardrail.identityResolutionCostUsd !== void 0) {
+        const identityCost = guardrail.identityResolutionCostUsd === null ? "unavailable" : `$${guardrail.identityResolutionCostUsd}`;
+        const identityRequests = guardrail.identityProviderRequests;
+        process.stdout.write(
+          `Identity resolution cost: ${identityCost}${identityRequests === void 0 ? "" : ` across ${identityRequests} fallback provider request${identityRequests === 1 ? "" : "s"}`}${guardrail.identityCostSource ? ` (${guardrail.identityCostSource})` : ""}.
+`
+        );
+      }
     }
     for (const signal of result.signals.slice(0, 20)) {
       process.stdout.write(`- ${signal.company.name} (${signal.company.domain}) \u2014 ${signal.eventDate} \u2014 ${signal.title}
@@ -788,6 +835,7 @@ async function signalToCopy() {
         title: row.title,
         campaignOffer: row.campaignOffer || row.campaign_offer || row.offer,
         researchPrompt: row.researchPrompt || row.research_prompt || flag("research-prompt") || flag("prompt"),
+        lookbackDays: row.lookbackDays || row.lookback_days || numberFlag("lookback-days"),
         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"),
@@ -814,6 +862,7 @@ async function signalToCopy() {
     title,
     campaignOffer,
     researchPrompt: flag("research-prompt") || flag("prompt"),
+    lookbackDays: numberFlag("lookback-days"),
     signalRunId,
     skipCache: hasFlag("skip-cache"),
     enableDeepSearch: hasFlag("deep-search"),
@@ -933,6 +982,13 @@ main().catch((error) => {
         retry_after: signalizError.retryAfter,
         retry_after_seconds: signalizError.retryAfter
       } : {},
+      ...signalizError?.details?.retry_strategy === "new_idempotency_key" ? { retry_strategy: "new_idempotency_key" } : {},
+      ...signalizError?.details?.credits_used === 0 ? { credits_used: 0 } : {},
+      ...signalizError?.details?.credits_charged === 0 ? { credits_charged: 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 } : {},
+      ...typeof signalizError?.details?.suggested_action === "string" ? { suggested_action: signalizError.details.suggested_action } : {},
       ...signalizError?.errorType ? { error_type: signalizError.errorType } : {},
       ...signalizError?.details ? { details: signalizError.details } : {}
     }, hasFlag("json") ? 2 : void 0)}
@@ -946,6 +1002,39 @@ main().catch((error) => {
     fail(`${message}
 Recoverable signal run: ${signalRunId}
 Retry the same signaliz ${command} command with --signal-run-id ${signalRunId}, or use --json for structured recovery metadata.`);
+  }
+  if (error instanceof import_sdk.SignalizError && typeof error.details?.verification_run_id === "string") {
+    const verificationRunId = error.details.verification_run_id;
+    if (error.details.suggested_action === "retry_with_verification_run_id") {
+      fail(`${message}
+Recoverable verification run: ${verificationRunId}
+Retry with: signaliz verify-email --verification-run-id ${verificationRunId}`);
+    }
+    fail(`${message}
+Terminal verification run: ${verificationRunId}
+No automatic retry is recommended; review the provider outcome or contact support.`);
+  }
+  if (error instanceof import_sdk.SignalizError && typeof error.details?.run_id === "string" && process.argv[2] === "find-email") {
+    const runId = error.details.run_id;
+    if (error.details.suggested_action === "retry_with_run_id") {
+      fail(`${message}
+Recoverable Find Email run: ${runId}
+Retry with: signaliz find-email --run-id ${runId}`);
+    }
+    fail(`${message}
+Terminal Find Email run: ${runId}
+No automatic retry is recommended; review the provider outcome or contact support.`);
+  }
+  if (error instanceof import_sdk.SignalizError && typeof error.details?.job_id === "string") {
+    const jobId = error.details.job_id;
+    if (error.details.suggested_action === "check_job_status") {
+      fail(`${message}
+Recoverable job: ${jobId}
+Resume this job through the REST API or SDK using job_id ${jobId}, or use --json for structured recovery metadata.`);
+    }
+    fail(`${message}
+Terminal job: ${jobId}
+No automatic retry is recommended; review the provider outcome or contact support.`);
   }
   fail(message);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaliz/cli",
-  "version": "1.0.56",
+  "version": "1.0.57",
   "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.60"
+    "@signaliz/sdk": "^1.0.61"
   },
   "devDependencies": {
     "tsup": "^8.0.0",