@signaliz/sdk 1.0.66 → 1.0.68

package/README.md

@@ -1,6 +1,7 @@
 # @signaliz/sdk
 
-Typed JavaScript/TypeScript access to all five core products in Signaliz.
+Typed JavaScript/TypeScript access to all five core products in Signaliz, plus
+Signal Awareness and Signaliz Flow through the same public contract.
 
 ```bash
 npm install @signaliz/sdk
@@ -13,6 +14,10 @@ Production REST endpoints:
 - `https://api.signaliz.com/functions/v1/api/v1/company-signals`
 - `https://api.signaliz.com/functions/v1/api/v1/signal-to-copy`
 - `https://api.signaliz.com/functions/v1/api/v1/signals`
+- `https://api.signaliz.com/functions/v1/api/v1/signal-awareness`
+- `https://api.signaliz.com/functions/v1/api/v1/flow`
+
+The same request and response schemas are available under `/api/v2/`.
 
 ```ts
 import { Signaliz } from '@signaliz/sdk';
@@ -35,8 +40,6 @@ console.log(plan.inputCount, plan.uniqueFreshInputCount, plan.inputDuplicatesSup
 const found = await signaliz.findEmail({
   companyDomain: 'example.com',
   fullName: 'Jane Doe',
-  // Optional: bypass cached email and verification data for a fresh-provider run.
-  skipCache: true,
 });
 
 // An HTTPS LinkedIn person profile URL (/in/<slug>) is also sufficient on its own.
@@ -45,8 +48,6 @@ const foundFromLinkedIn = await signaliz.findEmail({
 });
 
 const verified = await signaliz.verifyEmail(found.email!, {
-  // Optional: bypass cached verification proof for a fresh-provider check.
-  skipCache: true,
 });
 
 // Syntax failures are terminal local results, with no HTTP or provider call.
@@ -56,25 +57,27 @@ console.log(malformed.success, malformed.isMalformed, malformed.verificationVerd
 // The SDK waits for long checks by default. For an agent handoff, return early
 // and resume the exact provider run later without duplicate spend.
 const queuedVerification = await signaliz.verifyEmail('jane@example.com', {
-  skipCache: true,
   waitForResult: false,
 });
 const resumedVerification = await signaliz.verifyEmail('jane@example.com', {
   verificationRunId: queuedVerification.verificationRunId,
 });
 
-// Recovery is zero-current-spend. When the original provider call had a
-// receipt, Find Email and Verify Email retain it separately for audit.
-console.log(resumedVerification.billingMetadata?.result_returned_from); // run_recovery
-console.log(resumedVerification.historicalBillingMetadata?.result_returned_from);
+// Recovery reuses the original request and its public credit receipt.
+console.log(resumedVerification.creditsUsed, resumedVerification.billingReplayed);
 
 const signals = await signaliz.enrichCompanySignals({
   companyDomain: 'example.com',
   researchPrompt: 'expansion priorities',
 });
-// Audit normalized evidence provenance without reaching into `raw`.
-console.log(signals.signals[0].evidencePublishedDate);
-console.log(signals.signals[0].signalFeedSource, signals.signals[0].derived);
+// Signal rows expose only the customer-facing signal fields.
+console.log(
+  signals.signals[0].signal_type,
+  signals.signals[0].source,
+  signals.signals[0].date,
+  signals.signals[0].company_name,
+  signals.signals[0].domain,
+);
 
 // Query-first discovery returns distinct companies with dated source evidence.
 // The first response is usually queued; resume only the returned run ID.
@@ -92,8 +95,7 @@ const painSignalDiscovery = await signaliz.discoverSignals({
 const completedDiscovery = signalDiscovery.signalSearchRunId
   ? await signaliz.discoverSignals({ signalSearchRunId: signalDiscovery.signalSearchRunId })
   : signalDiscovery;
-console.log(completedDiscovery.signals[0]?.company.domain);
-console.log(completedDiscovery.costGuardrail?.costPerQualifiedSignalUsd);
+console.log(completedDiscovery.signals[0]?.domain);
 
 const copy = await signaliz.signalToCopy({
   companyDomain: 'example.com',
@@ -101,11 +103,38 @@ const copy = await signaliz.signalToCopy({
   title: 'VP Sales',
   campaignOffer: 'pipeline intelligence',
   researchPrompt: 'expansion priorities',
-  // Cache-first and shallow by default; opt into either behavior explicitly.
-  skipCache: false,
   enableDeepSearch: false,
 });
 
+// Reuse the completed Signals First snapshot instead of rediscovering it.
+const copyFromSignalRun = await signaliz.signalToCopy({
+  companyDomain: 'example.com',
+  personName: 'Jane Doe',
+  title: 'VP Sales',
+  campaignOffer: 'pipeline intelligence',
+  signalSearchRunId: completedDiscovery.signalSearchRunId,
+});
+// The copy result reuses the completed snapshot without rediscovery.
+
+const awareness = await signaliz.signalAwareness({
+  action: 'list_signals',
+  monitorId: 'monitor-uuid',
+});
+console.log(
+  awareness.signals?.[0].signal_type,
+  awareness.signals?.[0].source,
+  awareness.signals?.[0].date,
+  awareness.signals?.[0].company_name,
+  awareness.signals?.[0].domain,
+);
+
+// Flow uses the same versioned REST gateway as every other SDK capability.
+const flow = await signaliz.startFlow({
+  signalQuery: 'companies with recent hiring',
+  campaignOffer: 'pipeline intelligence',
+});
+const flowStatus = await signaliz.getFlow(flow.runId);
+
 // Company Signals and Signal to Copy are hard synchronous contracts: these
 // methods return complete data, an explicit success:false result, or throw a
 // non-2xx terminal error in this same call.
@@ -189,49 +218,47 @@ Company/Copy submissions preserve every input row and its index so the server's
 idempotency identity remains stable across REST, MCP, SDK, and CLI recovery.
 Set `compactDuplicates: true` to return repeated successful rows as
 `duplicateOf` references; the default remains expanded for compatibility.
-Signal to Copy durable jobs use persisted, eligible company-signal data only
-and never start live providers or deep research. Rows without qualifying
-evidence return the terminal row error `SIGNAL_DATA_REQUIRED`. Batches larger
-than 25 reject fresh/deep/synchronous row controls before HTTP; callers must
-split explicitly fresh requests into batches of at most 25.
+Signal to Copy durable jobs complete missing company-signal research before
+generating copy. They accept uniform `enableDeepSearch`
+controls for the full job. Rows still return `SIGNAL_DATA_REQUIRED` when
+research completes without qualifying evidence.
 Signal to Copy also shares company research across copy recipients.
+Single calls and synchronous batches of at most 25 may instead pass
+`signalSearchRunId`, `factId`, or `eventId` to reuse canonical signal evidence.
+Durable batches of 26-5,000 reject these references rather than silently
+starting new research.
 
 Signals Everything is query-first rather than a row batch. It defaults to 100
-distinct companies and supports up to 1,000. Every returned signal contains a
-company name, company domain, dated evidence, and a source URL. The typed
-`costGuardrail` reports projected and observed source acquisition cost plus
-identity-resolution cost, receipt source, and fallback-provider request count;
-Signaliz returns signals only when cost stays strictly below $0.01 per qualified
-company. A request is a ceiling, not a promise: it can return fewer results
+distinct companies and supports up to 1,000. Every returned signal row contains
+only a signal type, verified source URL, event date, company name, and domain.
+A request is a ceiling, not a promise: it can return fewer results
 when public evidence cannot verify both a date and company identity. It is
 included on Builder, Team, and Agency plans and can be resumed with
-`signalSearchRunId` without duplicate source acquisition. Pass `icpContext` to
+`signalSearchRunId`. Pass `icpContext` to
 ground an open-ended request such as “companies showing signals they need our
 product” in the user's target market.
 
-Company Signal Enrichment defaults `online` and `enableDeepSearch` to `true`
-unless the caller explicitly disables them. Its `searchMode` defaults to
-`balanced`; use `fast` for the primary low-latency search lane only or
-`coverage` when breadth matters more than the sub-cent average budget target.
+Company Signal Enrichment uses one fixed provider policy: cache first, one
+type-agnostic Parallel Advanced search, and at most one Extract of a
+first-party multi-event hub. Deterministic code enforces company identity,
+retrieved URLs, source quality, content-proven dates, copied evidence,
+lookback, and event deduplication before returning the newest ten events. It
+does not expose provider, model, prompt, lookback, signal-type, cache, or
+target-count controls.
 Signal to Copy AI returns three
 complete, evidence-backed email variations when supported signals are available.
-Signal to Copy is cache-first and defaults `enableDeepSearch` to `false` so it
-normally finishes within an agent turn; set `skipCache` or `enableDeepSearch`
-only when fresh or deeper research is required.
-Every core request 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. Builder, Team,
-Agency, and Pay-As-You-Go include fresh Company Signals. Team and Agency also
-include Unlimited Signal to Copy AI; Signal to Copy remains callable on other
-plans under the standard product contract. These plans still check eligible
-workspace signal data first even when Company Signals is set to No cache.
-`lookbackDays` remains a hard evidence-age bound for both
-cached and fresh Company Signals and Signal to Copy results.
+Signal to Copy defaults `enableDeepSearch` to `false` so it normally finishes
+within an agent turn; enable it only when deeper research is required.
+Every core request uses the authenticated workspace. Find Email costs 1 credit
+per returned result and Verify Email costs 0.02 credits per returned terminal
+result on every plan. Signaliz automatically reuses eligible evidence and
+prevents duplicate provider work. Builder, Team, Agency, and Pay-As-You-Go
+include Company Signals.
+Signal to Copy costs 1 credit per successful result on Free and Builder, and is
+unlimited on Team and Agency. `lookbackDays` remains a hard evidence-age bound.
 Unclassified evidence is returned by signal enrichment but is not used to
 generate outreach copy.
-Each normalized signal keeps `date` separate from crawl-time `detectedAt` and
-also exposes customer-facing classification fields such as `datePrecision`,
-`signalFamily`, `eventType`, `eventLabel`, and `classification`. Provider,
-billing, cache, routing, and validation internals are intentionally omitted.
+Provider, billing provenance, routing, and validation internals are intentionally
+omitted from public signal rows.
 
 `listTools()` and `health()` are connection helpers, not additional products.