@graph8/sdk 0.277.0 → 0.294.0

package/docs/api/enrichment.md

@@ -2,7 +2,7 @@
 
 # `g8.api.enrichment`: Enrichment
 
-114 operations (51 read, 21 write, 10 destructive, 32 billable).
+115 operations (52 read, 21 write, 10 destructive, 32 billable).
 
 3 of these also have a hand-written method (`g8.enrich`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
 
@@ -101,6 +101,7 @@ Exact TypeScript types for every operation on this page, and every schema they u
 | [`lookupPerson`](#op-lookupperson) ★ | `POST /api/v1/enrichment/lookup/person` | billable | `enrichment:run` | Lookup Person |
 | [`lookupPersonAlias`](#op-lookuppersonalias) | `POST /api/v1/enrichment/person` | billable | `enrichment:run` | Lookup Person (alias of /enrichment/lookup/person) |
 | [`pauseEnrichmentJob`](#op-pauseenrichmentjob) | `POST /api/v1/enrichment/jobs/{job_id}/pause` | write | `enrichment:write` | Pause Enrichment Job |
+| [`preflightEnrichment`](#op-preflightenrichment) | `POST /api/v1/enrichment/preflight` | read | `enrichment:read` | Preflight Enrichment |
 | [`previewFindPeople`](#op-previewfindpeople) | `POST /api/v1/enrichment/find-people/{config_id}/preview` | billable | `enrichment:run` | Preview Find People |
 | [`previewFormula`](#op-previewformula) | `POST /api/v1/enrichment/ai-formula/preview` | read | `enrichment:read` | Preview Formula |
 | [`previewRecordSync`](#op-previewrecordsync) | `POST /api/v1/enrichment/record-sync/{entity_type}/preview` | read | `enrichment:read` | Preview Record Sync |
@@ -3255,6 +3256,80 @@ const result = await g8.api.enrichment.pauseEnrichmentJob({ path: { job_id: "id"
 
 ---
 
+<a id="op-preflightenrichment"></a>
+
+### `g8.api.enrichment.preflightEnrichment(input)`
+
+**Preflight Enrichment**
+
+- HTTP: `POST /api/v1/enrichment/preflight`
+- operationId: `preflight_enrichment_enrichment_preflight_post` (also callable as `g8.api.call("preflight_enrichment_enrichment_preflight_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `enrichment:read`
+
+Check an enrichment request before running it. Free: nothing is written,
+queued or charged.
+
+Errors for input a run could never use: an unknown `mode` (400
+`invalid_mode`), zero or negative contact IDs (400 `invalid_record_ids`), a
+list that is not in this organization (404 `list_not_found`), an unknown
+`target_field` (400 `unsupported_field`), an unknown provider (400
+`unsupported_provider` / `unsupported_provider_for_field`) and a missing AI
+config (404 `ai_config_not_found`).
+
+Otherwise returns what the run would do: the unique contact IDs (repeats
+are counted once), contacts that are not on the list, the providers that
+would run, and plain warnings such as "Lusha is not connected: add your
+key" or "No providers chosen: using your saved pipeline".
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `EnrichmentPreflightRequest` | yes | Request body; fields below. |
+
+Body fields (`EnrichmentPreflightRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<integer>` | yes | Contact IDs to enrich (duplicates are counted once) |
+| `body.list_id` | `integer` | yes | List ID the contacts belong to |
+| `body.ai_group_id` | `string \| null` | no | group_id of a saved AI enrichment config (required for 'ai-research') |
+| `body.email_verification` | `boolean` | no | Add ZeroBounce email verification default `false` |
+| `body.mode` | `string` | no | 'auto' (AI when ai_group_id is set, else waterfall), 'waterfall' or 'ai-research' default `"auto"` |
+| `body.providers` | `Array<string> \| null` | no | Ordered provider names for a waterfall run. Omit to use the list's saved pipeline; an empty list also uses the saved pipeline (a warning says so). |
+| `body.target_field` | `string \| null` | no | Column to enrich: a canonical CONTACT_*/COMPANY_* column or a synonym like 'phone' or 'email' |
+
+**Returns** `ApiResponse_EnrichmentPreflightResponse_`: the envelope `{ data: EnrichmentPreflightResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`EnrichmentPreflightResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `contact_count` | `integer` | yes | Number of unique contacts (the count credits are estimated on) |
+| `contact_ids` | `Array<integer>` | yes | Contact IDs that will be enriched: duplicates removed, order kept |
+| `list_id` | `integer` | yes |  |
+| `mode` | `string` | yes | Resolved mode: 'waterfall' or 'ai-research' |
+| `duplicates_removed` | `integer` | no | How many repeated contact IDs were dropped default `0` |
+| `list_name` | `string \| null` | no |  |
+| `missing_credentials` | `Array<string>` | no | Providers whose step would be skipped because the org has no key for them |
+| `not_in_list` | `Array<integer>` | no | Contact IDs that are not on the list; the run skips them and does not charge for them |
+| `providers` | `Array<string>` | no | Providers that would run, in order (empty = the saved pipeline) |
+| `providers_detail` | `Array<ProviderStepDetail>` | no |  |
+| `target_field` | `string \| null` | no | Canonical column for target_field, when given |
+| `uses_saved_pipeline` | `boolean` | no | True when the list's saved pipeline (or the graph8 default) would run default `false` |
+| `warnings` | `Array<string>` | no | Plain-language advisories for the user |
+
+**Example**
+
+```ts
+const result = await g8.api.enrichment.preflightEnrichment({ body: { contact_ids: [123], list_id: 123 } });
+```
+
+---
+
 <a id="op-previewfindpeople"></a>
 
 ### `g8.api.enrichment.previewFindPeople(input)`

package/docs/api/fields.d.ts

@@ -212,7 +212,7 @@ export interface ApiResponse_list_FieldResponse__ {
  * level (a batch targets one entity and, when enrichment is used, one list).
  */
 export interface BatchFieldItem {
-  /** Column data type. Currently only 'text' is supported. */
+  /** Column data type: 'text', 'int' (whole number), 'numeric' (decimal) or 'boolean' (yes/no). Unknown values 400. */
   data_type?: string;
   /** Optional per-column waterfall enrichment block (identical shape to POST /fields). When supplied, a companion enrichment_configs row is created for that column so it's immediately runnable. */
   enrichment?: CreateFieldEnrichmentInput | null;
@@ -222,9 +222,13 @@ export interface BatchFieldItem {
 
 /** Per-column outcome inside a batch response. */
 export interface BatchFieldResult {
+  /** True when this column already existed (same name, same scope), so the existing column was returned instead of a new one. */
+  already_existed?: boolean;
   enrichment?: CreateFieldEnrichmentResponse | null;
   /** Set when the column was created but its companion enrichment config failed. */
   error?: string | null;
+  /** When `already_existed` is true: the existing column's data type. */
+  existing_data_type?: string | null;
   id?: number | null;
   /** True when this column was created org-GLOBAL (no list_id was supplied) and will therefore appear on EVERY list in the org. Pass `list_id` to scope columns to one list. */
   is_global?: boolean;
@@ -233,6 +237,8 @@ export interface BatchFieldResult {
   name?: string | null;
   ok?: boolean;
   title: string;
+  /** Non-blocking notices for this column (e.g. same name exists org-wide). */
+  warnings?: Array<string>;
 }
 
 /**
@@ -279,7 +285,7 @@ export interface CreateFieldEnrichmentResponse {
 
 /** Request body for creating a custom field (column). */
 export interface CreateFieldRequest {
-  /** Column data type. Currently only 'text' is supported; additional types (numeric, date, boolean, select) may be added in future versions. */
+  /** Column data type: 'text', 'int' (whole number), 'numeric' (decimal) or 'boolean' (yes/no). Unknown values 400. If the name already exists with another type, the create is rejected with 409. */
   data_type?: string;
   /** Optional enrichment-pipeline block. When supplied, a companion `enrichment_configs` row is created in the same request so the new column is immediately runnable via /enrichment/waterfall/enrich. */
   enrichment?: CreateFieldEnrichmentInput | null;
@@ -292,14 +298,20 @@ export interface CreateFieldRequest {
 }
 
 export interface CreateFieldResponse {
+  /** True when a column with this name already existed in this scope, so no new column was created and `id` is the existing column. A different `data_type` for an existing name is rejected with 409. */
+  already_existed?: boolean;
   data_type: string;
   /** Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent /enrichment/waterfall/enrich calls. */
   enrichment?: CreateFieldEnrichmentResponse | null;
+  /** When `already_existed` is true: the existing column's data type. */
+  existing_data_type?: string | null;
   id: number;
   is_global: boolean;
   list_id?: number | null;
   name: string;
   title: string;
+  /** Non-blocking notices, e.g. a column with the same name already exists org-wide, so the list now shows two columns with that name. */
+  warnings?: Array<string>;
 }
 
 /**
@@ -321,6 +333,9 @@ export interface CreateFieldsBatchResponse {
   entity: string;
   list_id?: number | null;
   results: Array<BatchFieldResult>;
+  /** How many requested columns already existed and were returned as-is. */
+  total_already_existed?: number;
+  /** Columns returned by this call, INCLUDING ones that already existed (unchanged meaning). `total_already_existed` says how many of them were existing columns. */
   total_created: number;
   total_requested: number;
 }
@@ -355,6 +370,8 @@ export interface FieldResponse {
   data_type?: string;
   id?: number | null;
   is_global?: boolean;
+  /** Human-readable field name for display, e.g. 'First name' for CONTACT_FIRST_NAME. Custom columns use their title. Keep using `name` as the identifier. */
+  label?: string | null;
   name?: string | null;
   title: string;
 }
@@ -370,11 +387,15 @@ export interface FieldValueItem {
 /** Response body for reading a single custom column value from one row. */
 export interface GetFieldValueResponse {
   column_id: number;
+  /** The column's data type, the same value `GET /fields` reports in `data_type`: 'text', 'int', 'numeric' or 'boolean'. */
+  data_type?: string | null;
   entity: string;
   /** The underlying column slug (column_name_db). */
   name: string;
   record_id: number;
-  /** The stored value, or null if the column is unset for this row. */
+  /** The stored value in its native JSON type: a number for 'int' and 'numeric' columns, true/false for 'boolean' columns, a string for text columns. Null when the column is unset for this row. */
+  typed_value?: boolean | number | string | null;
+  /** The stored value as text, or null if the column is unset for this row. Number and yes/no columns are returned in text form ('42', '12.5', 'true'/'false'); read `typed_value` for the native JSON value. */
   value?: string | null;
 }
 

package/docs/api/fields.md

@@ -66,7 +66,7 @@ Body fields (`CreateFieldRequest`):
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `body.title` | `string` | yes | Column title, e.g. 'Job Level' |
-| `body.data_type` | `string` | no | Column data type. Currently only 'text' is supported; additional types (numeric, date, boolean, select) may be added in future versions. default `"text"` |
+| `body.data_type` | `string` | no | Column data type: 'text', 'int' (whole number), 'numeric' (decimal) or 'boolean' (yes/no). Unknown values 400. If the name already exists with another type, the create is rejected with 409. default `"text"` |
 | `body.enrichment` | `CreateFieldEnrichmentInput \| null` | no | Optional enrichment-pipeline block. When supplied, a companion `enrichment_configs` row is created in the same request so the new column is immediately runnable via /enrichment/waterfall/enrich. |
 | `body.entity` | `string` | no | Target entity: 'contacts' or 'companies' default `"contacts"` |
 | `body.list_id` | `integer \| null` | no | If set, field is list-specific; otherwise global across the org |
@@ -84,8 +84,11 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `is_global` | `boolean` | yes |  |
 | `name` | `string` | yes |  |
 | `title` | `string` | yes |  |
+| `already_existed` | `boolean` | no | True when a column with this name already existed in this scope, so no new column was created and `id` is the existing column. A different `data_type` for an existing name is rejected with 409. default `false` |
 | `enrichment` | `CreateFieldEnrichmentResponse \| null` | no | Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent /enrichment/waterfall/enrich calls. |
+| `existing_data_type` | `string \| null` | no | When `already_existed` is true: the existing column's data type. |
 | `list_id` | `integer \| null` | no |  |
+| `warnings` | `Array<string>` | no | Non-blocking notices, e.g. a column with the same name already exists org-wide, so the list now shows two columns with that name. |
 
 **Example**
 
@@ -146,9 +149,10 @@ Other envelope fields: `pagination` (PaginationMeta).
 |---|---|---|---|
 | `entity` | `string` | yes |  |
 | `results` | `Array<BatchFieldResult>` | yes |  |
-| `total_created` | `integer` | yes |  |
+| `total_created` | `integer` | yes | Columns returned by this call, INCLUDING ones that already existed (unchanged meaning). `total_already_existed` says how many of them were existing columns. |
 | `total_requested` | `integer` | yes |  |
 | `list_id` | `integer \| null` | no |  |
+| `total_already_existed` | `integer` | no | How many requested columns already existed and were returned as-is. default `0` |
 
 **Example**
 
@@ -251,7 +255,9 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `entity` | `string` | yes |  |
 | `name` | `string` | yes | The underlying column slug (column_name_db). |
 | `record_id` | `integer` | yes |  |
-| `value` | `string \| null` | no | The stored value, or null if the column is unset for this row. |
+| `data_type` | `string \| null` | no | The column's data type, the same value `GET /fields` reports in `data_type`: 'text', 'int', 'numeric' or 'boolean'. |
+| `typed_value` | `boolean \| integer \| number \| string \| null \| null` | no | The stored value in its native JSON type: a number for 'int' and 'numeric' columns, true/false for 'boolean' columns, a string for text columns. Null when the column is unset for this row. |
+| `value` | `string \| null` | no | The stored value as text, or null if the column is unset for this row. Number and yes/no columns are returned in text form ('42', '12.5', 'true'/'false'); read `typed_value` for the native JSON value. |
 
 **Example**
 
@@ -293,6 +299,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `data_type` | `string` | no | default `"text"` |
 | `id` | `integer \| null` | no |  |
 | `is_global` | `boolean` | no | default `true` |
+| `label` | `string \| null` | no | Human-readable field name for display, e.g. 'First name' for CONTACT_FIRST_NAME. Custom columns use their title. Keep using `name` as the identifier. |
 | `name` | `string \| null` | no |  |
 
 **Example**
@@ -335,6 +342,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `data_type` | `string` | no | default `"text"` |
 | `id` | `integer \| null` | no |  |
 | `is_global` | `boolean` | no | default `true` |
+| `label` | `string \| null` | no | Human-readable field name for display, e.g. 'First name' for CONTACT_FIRST_NAME. Custom columns use their title. Keep using `name` as the identifier. |
 | `name` | `string \| null` | no |  |
 
 **Example**
@@ -489,7 +497,7 @@ One column in a batch-create request. `title`, `data_type` and the optional `enr
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `title` | `string` | yes | Column title, e.g. 'Job Level' |
-| `data_type` | `string` | no | Column data type. Currently only 'text' is supported. default `"text"` |
+| `data_type` | `string` | no | Column data type: 'text', 'int' (whole number), 'numeric' (decimal) or 'boolean' (yes/no). Unknown values 400. default `"text"` |
 | `enrichment` | `CreateFieldEnrichmentInput \| null` | no | Optional per-column waterfall enrichment block (identical shape to POST /fields). When supplied, a companion enrichment_configs row is created for that column so it's immediately runnable. |
 
 <a id="type-batchfieldresult"></a>
@@ -501,13 +509,16 @@ Per-column outcome inside a batch response.
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `title` | `string` | yes |  |
+| `already_existed` | `boolean` | no | True when this column already existed (same name, same scope), so the existing column was returned instead of a new one. default `false` |
 | `enrichment` | `CreateFieldEnrichmentResponse \| null` | no |  |
 | `error` | `string \| null` | no | Set when the column was created but its companion enrichment config failed. |
+| `existing_data_type` | `string \| null` | no | When `already_existed` is true: the existing column's data type. |
 | `id` | `integer \| null` | no |  |
 | `is_global` | `boolean` | no | True when this column was created org-GLOBAL (no list_id was supplied) and will therefore appear on EVERY list in the org. Pass `list_id` to scope columns to one list. default `false` |
 | `list_id` | `integer \| null` | no | The list this column is scoped to, or null when it is org-global. |
 | `name` | `string \| null` | no |  |
 | `ok` | `boolean` | no | default `true` |
+| `warnings` | `Array<string>` | no | Non-blocking notices for this column (e.g. same name exists org-wide). |
 
 <a id="type-createfieldenrichmentinput"></a>
 

package/docs/api/install.d.ts

@@ -106,6 +106,12 @@ export interface InstallOperations {
       /** Repository ID */
       repo_id: string;
     };
+    query?: {
+      /** Page number (1-indexed). Omit page and limit to get every stream. */
+      page?: number | null;
+      /** Streams per page (max 200). Omit page and limit to get every stream. */
+      limit?: number | null;
+    };
     headers?: {
       "X-Target-Org-Id"?: string | null;
     };
@@ -196,6 +202,10 @@ export interface PatchSetResponse {
 }
 
 export interface SnippetResponse {
+  /** True when the organization has several streams and none could be identified as its main website. The write key is the first stream's (unchanged legacy default); pick the right one from available_streams and call again with stream_id. */
+  action_required?: boolean;
+  /** The organization's streams to choose from. Filled only when action_required is true. */
+  available_streams?: Array<StreamInfoResponse>;
   /** Full configuration object for gtm/config.json */
   config?: Record<string, unknown>;
   domains?: Array<string>;
@@ -203,17 +213,33 @@ export interface SnippetResponse {
   react_snippet: string;
   /** Vanilla JS script tag for non-React apps */
   script_tag: string;
+  /** ID of the tracking stream the write key belongs to, when known. */
+  stream_id?: string | null;
+  /** User-friendly name of that stream, when known. */
+  stream_name?: string | null;
+  /** How the stream was chosen: 'explicit' (stream_id given), 'repo_write_key' (the repository's stored key), 'only_stream', 'domain_match' (matches the organization's website), or 'first_stream_fallback' (ambiguous; see action_required). */
+  stream_selection?: string | null;
   tracking_host?: string;
+  /** Human-readable explanation when action_required is true, or a stream setup advisory. */
+  warning?: string | null;
   write_key: string;
 }
 
 export interface StreamInfoResponse {
   /** Domains associated with this stream */
   domains?: Array<string>;
+  /** Whether the stream lists allowed domains. False means its public write key is accepted from any website (see warning). */
+  domains_restricted?: boolean;
   /** Stream ID used to select this stream */
   id: string;
+  /** True for the stream GET /snippet uses when no stream_id is given: the only stream, or the one whose domain matches the organization's website. False on every stream when that choice is ambiguous; pass stream_id explicitly then. */
+  is_default?: boolean;
   /** User-friendly stream name (e.g. 'graph8.com', 'heyreach-graph8') */
   name: string;
+  /** Connected repository whose stored write key belongs to this stream. Null when no connected repository uses it: streams are organization-level, not owned by a repo. */
+  repo_id?: string | null;
+  /** Read-only advisory about this stream's setup, e.g. no allowed domains. Nothing is enforced. */
+  warning?: string | null;
   /** Public write key for this stream */
   write_key?: string | null;
 }

package/docs/api/install.md

@@ -201,9 +201,15 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `react_snippet` | `string` | yes | Ready-to-use React component import for @graph8/nextjs |
 | `script_tag` | `string` | yes | Vanilla JS script tag for non-React apps |
 | `write_key` | `string` | yes |  |
+| `action_required` | `boolean` | no | True when the organization has several streams and none could be identified as its main website. The write key is the first stream's (unchanged legacy default); pick the right one from available_streams and call again with stream_id. default `false` |
+| `available_streams` | `Array<StreamInfoResponse>` | no | The organization's streams to choose from. Filled only when action_required is true. |
 | `config` | `Record<string, unknown>` | no | Full configuration object for gtm/config.json |
 | `domains` | `Array<string>` | no |  |
+| `stream_id` | `string \| null` | no | ID of the tracking stream the write key belongs to, when known. |
+| `stream_name` | `string \| null` | no | User-friendly name of that stream, when known. |
+| `stream_selection` | `string \| null` | no | How the stream was chosen: 'explicit' (stream_id given), 'repo_write_key' (the repository's stored key), 'only_stream', 'domain_match' (matches the organization's website), or 'first_stream_fallback' (ambiguous; see action_required). |
 | `tracking_host` | `string` | no | default `"https://t.graph8.com"` |
+| `warning` | `string \| null` | no | Human-readable explanation when action_required is true, or a stream setup advisory. |
 
 **Example**
 
@@ -230,11 +236,19 @@ Returns each stream's ID, user-friendly name (domain or label),
 associated domains, and write key. The caller should select one
 and pass its `id` to the snippet endpoint.
 
+Streams belong to the organization, not to the repository: every stream
+of the org is listed, and `repo_id` on each one names the connected
+repository already using it (null when none does). The repository must
+exist in the caller's organization (404 otherwise). The org-level
+equivalent that needs no repository is `GET /streams`.
+
 **Input**
 
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `path.repo_id` | `string` | yes | Repository ID |
+| `query.page` | `integer \| null` | no | Page number (1-indexed). Omit page and limit to get every stream. |
+| `query.limit` | `integer \| null` | no | Streams per page (max 200). Omit page and limit to get every stream. |
 
 **Returns** `ApiResponse_list_StreamInfoResponse__`: the envelope `{ data: Array<StreamInfoResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -247,6 +261,10 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `id` | `string` | yes | Stream ID used to select this stream |
 | `name` | `string` | yes | User-friendly stream name (e.g. 'graph8.com', 'heyreach-graph8') |
 | `domains` | `Array<string>` | no | Domains associated with this stream |
+| `domains_restricted` | `boolean` | no | Whether the stream lists allowed domains. False means its public write key is accepted from any website (see warning). default `false` |
+| `is_default` | `boolean` | no | True for the stream GET /snippet uses when no stream_id is given: the only stream, or the one whose domain matches the organization's website. False on every stream when that choice is ambiguous; pass stream_id explicitly then. default `false` |
+| `repo_id` | `string \| null` | no | Connected repository whose stored write key belongs to this stream. Null when no connected repository uses it: streams are organization-level, not owned by a repo. |
+| `warning` | `string \| null` | no | Read-only advisory about this stream's setup, e.g. no allowed domains. Nothing is enforced. |
 | `write_key` | `string \| null` | no | Public write key for this stream |
 
 **Example**

package/docs/api/intent.d.ts

@@ -273,7 +273,7 @@ export interface IntentOperations {
   };
 }
 
-// 27 schemas referenced above (the same as G8Contract.<Name>).
+// 28 schemas referenced above (the same as G8Contract.<Name>).
 
 export interface ApiResponse_KeywordCreateFromDomainResponse_ {
   data: KeywordCreateFromDomainResponse;
@@ -300,6 +300,13 @@ export interface ApiResponse_PagesSearchResponse_ {
   pagination?: PaginationMeta | null;
 }
 
+export interface CreateFromDomainSampleContact {
+  company_domain?: string | null;
+  company_name?: string | null;
+  job_title?: string | null;
+  name?: string | null;
+}
+
 export interface IntentPageItem {
   audience?: string | null;
   commercial_score?: number | null;
@@ -309,6 +316,8 @@ export interface IntentPageItem {
   summary?: string | null;
   title?: string | null;
   url?: string | null;
+  /** Distinct visitors (hashed emails) in the lookback window. Set only by pages/search with include_visitors=true when the count succeeded; null otherwise. */
+  visitors?: number | null;
 }
 
 export interface KeywordAddedItem {
@@ -324,6 +333,8 @@ export interface KeywordCreateFromDomainRequest {
   contact_limit?: number;
   /** Competitor domain to track, e.g. 'cognism.com'. */
   domain: string;
+  /** Preview only: find the on-domain pages and resolve contacts exactly as a real run would, but save nothing. The counts then say what WOULD be seeded, keyword_id stays null, and sample_pages / sample_contacts show a preview. Default false keeps the one-call create. */
+  dry_run?: boolean;
   /** Max pages to seed from the domain. */
   page_limit?: number;
 }
@@ -331,11 +342,17 @@ export interface KeywordCreateFromDomainRequest {
 export interface KeywordCreateFromDomainResponse {
   companies_seeded?: number;
   contacts_seeded?: number;
+  /** True when nothing was saved (preview). */
+  dry_run?: boolean;
   keyword: string;
   keyword_id?: string | null;
   message?: string;
   off_domain_rejected?: number;
   pages_seeded?: number;
+  /** Dry run only: up to 10 of the contacts that would be pre-resolved (no emails). */
+  sample_contacts?: Array<CreateFromDomainSampleContact>;
+  /** Dry run only: up to 10 of the pages that would be seeded. */
+  sample_pages?: Array<IntentPageItem>;
 }
 
 export interface KeywordCreateFromSearchItem {
@@ -441,11 +458,19 @@ export interface PagesSearchRequest {
 }
 
 export interface PagesSearchResponse {
+  /** Hits hidden because they had no visitors in the lookback window (include_visitors=true). total_hits counts them; pages does not. */
+  filtered_no_visitors?: number;
   mode?: string;
   pages?: Array<IntentPageItem>;
   query: string;
+  /** How this search scoped the results, when it differs from a sibling tool (e.g. a bare-domain query matches the apex + www only). */
+  scope_note?: string | null;
   took_ms?: number;
   total_hits?: number;
+  /** Why visitor enrichment was skipped (include_visitors=true only). */
+  visitors_error?: string | null;
+  /** Non-fatal problems: visitor counts timed out or failed (pages are then returned unfiltered, visitors=null), every hit was hidden by the has-visitors filter, or the search backend failed. */
+  warnings?: Array<string>;
 }
 
 export interface PagesVisitorCountsRequest {

package/docs/api/intent.md

@@ -168,6 +168,9 @@ const result = await g8.api.intent.keywordContacts({
 
 Replace a keyword's `search_filters` JSON.
 
+404 when the keyword does not exist for this org or was deleted (IN-07:
+the bare ALTER matched no row and still answered "success").
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -339,6 +342,7 @@ Body fields (`KeywordCreateFromDomainRequest`):
 |---|---|---|---|
 | `body.domain` | `string` | yes | Competitor domain to track, e.g. 'cognism.com'. min length 3, max length 253 |
 | `body.contact_limit` | `integer` | no | Max contacts to pre-resolve. default `200`, min 1, max 500 |
+| `body.dry_run` | `boolean` | no | Preview only: find the on-domain pages and resolve contacts exactly as a real run would, but save nothing. The counts then say what WOULD be seeded, keyword_id stays null, and sample_pages / sample_contacts show a preview. Default false keeps the one-call create. default `false` |
 | `body.page_limit` | `integer` | no | Max pages to seed from the domain. default `200`, min 1, max 500 |
 
 **Returns** `ApiResponse_KeywordCreateFromDomainResponse_`: the envelope `{ data: KeywordCreateFromDomainResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
@@ -352,10 +356,13 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `keyword` | `string` | yes |  |
 | `companies_seeded` | `integer` | no | default `0` |
 | `contacts_seeded` | `integer` | no | default `0` |
+| `dry_run` | `boolean` | no | True when nothing was saved (preview). default `false` |
 | `keyword_id` | `string \| null` | no |  |
 | `message` | `string` | no | default `""` |
 | `off_domain_rejected` | `integer` | no | default `0` |
 | `pages_seeded` | `integer` | no | default `0` |
+| `sample_contacts` | `Array<CreateFromDomainSampleContact>` | no | Dry run only: up to 10 of the contacts that would be pre-resolved (no emails). |
+| `sample_pages` | `Array<IntentPageItem>` | no | Dry run only: up to 10 of the pages that would be seeded. |
 
 **Example**
 
@@ -652,10 +659,14 @@ Other envelope fields: `pagination` (PaginationMeta).
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `query` | `string` | yes |  |
+| `filtered_no_visitors` | `integer` | no | Hits hidden because they had no visitors in the lookback window (include_visitors=true). total_hits counts them; pages does not. default `0` |
 | `mode` | `string` | no | default `"text"` |
 | `pages` | `Array<IntentPageItem>` | no | default `[]` |
+| `scope_note` | `string \| null` | no | How this search scoped the results, when it differs from a sibling tool (e.g. a bare-domain query matches the apex + www only). |
 | `took_ms` | `integer` | no | default `0` |
 | `total_hits` | `integer` | no | default `0` |
+| `visitors_error` | `string \| null` | no | Why visitor enrichment was skipped (include_visitors=true only). |
+| `warnings` | `Array<string>` | no | Non-fatal problems: visitor counts timed out or failed (pages are then returned unfiltered, visitors=null), every hit was hidden by the has-visitors filter, or the search backend failed. |
 
 **Example**
 
@@ -808,6 +819,17 @@ const result = await g8.api.intent.urlCompanies({ body: { url: "https://example.
 
 Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
 
+<a id="type-createfromdomainsamplecontact"></a>
+
+### `CreateFromDomainSampleContact`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `company_domain` | `string \| null` | no |  |
+| `company_name` | `string \| null` | no |  |
+| `job_title` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+
 <a id="type-intentpageitem"></a>
 
 ### `IntentPageItem`
@@ -822,6 +844,7 @@ Named types that appear in the tables above. Full TypeScript definitions: `G8Con
 | `summary` | `string \| null` | no |  |
 | `title` | `string \| null` | no |  |
 | `url` | `string \| null` | no |  |
+| `visitors` | `integer \| null` | no | Distinct visitors (hashed emails) in the lookback window. Set only by pages/search with include_visitors=true when the count succeeded; null otherwise. |
 
 <a id="type-keywordaddeditem"></a>
 

package/docs/api/lists.d.ts

@@ -896,11 +896,15 @@ export interface ListCreateRequest {
 
 export interface ListCreateResponse {
   description?: string | null;
+  /** Ids of existing lists with the same name (case-insensitive), when any. */
+  duplicate_list_ids?: Array<number> | null;
   id: number;
   status?: string | null;
   title: string;
   total?: number;
   type?: string | null;
+  /** Set when another list already has this name. The list was still created. */
+  warning?: string | null;
 }
 
 /**
@@ -999,6 +1003,10 @@ export interface ListPerformanceResponse {
 
 /** Audience/list representation for the public API. */
 export interface ListResponse {
+  /** Number of companies in a company list (null for other list types) */
+  company_count?: number | null;
+  /** Number of contacts in a contact list (null for other list types) */
+  contact_count?: number | null;
   created_at?: string | null;
   created_by?: string | null;
   /** Agent/human-readable note describing the list's purpose (#16641) */
@@ -1013,6 +1021,7 @@ export interface ListResponse {
   total?: number;
   /** List type (contacts, companies, suppressions, deals, leads) */
   type?: string | null;
+  /** Last change to the list. Equals created_at for a list never edited since creation. */
   updated_at?: string | null;
 }
 

package/docs/api/lists.md

@@ -75,6 +75,10 @@ Exact TypeScript types for every operation on this page, and every schema they u
 
 Add contacts to a list by their IDs.
 
+``added`` is the number of membership rows really created. Ids that are not
+live contacts in this org come back in ``not_found``; ids already on the
+list in ``already_member`` (LI-01). A missing or deleted list is a 404.
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -350,9 +354,11 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `id` | `integer` | yes |  |
 | `title` | `string` | yes |  |
 | `description` | `string \| null` | no |  |
+| `duplicate_list_ids` | `Array<integer> \| null` | no | Ids of existing lists with the same name (case-insensitive), when any. |
 | `status` | `string \| null` | no |  |
 | `total` | `integer` | no | default `0` |
 | `type` | `string \| null` | no |  |
+| `warning` | `string \| null` | no | Set when another list already has this name. The list was still created. |
 
 **Example**
 
@@ -1076,6 +1082,8 @@ Other envelope fields: `pagination` (PaginationMeta).
 |---|---|---|---|
 | `id` | `integer` | yes |  |
 | `title` | `string` | yes |  |
+| `company_count` | `integer \| null` | no | Number of companies in a company list (null for other list types) |
+| `contact_count` | `integer \| null` | no | Number of contacts in a contact list (null for other list types) |
 | `created_at` | `string (date-time) \| null` | no |  |
 | `created_by` | `string \| null` | no |  |
 | `description` | `string \| null` | no | Agent/human-readable note describing the list's purpose (#16641) |
@@ -1085,7 +1093,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `tags` | `Array<string>` | no |  |
 | `total` | `integer` | no | default `0` |
 | `type` | `string \| null` | no | List type (contacts, companies, suppressions, deals, leads) |
-| `updated_at` | `string (date-time) \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no | Last change to the list. Equals created_at for a list never edited since creation. |
 
 **Example**
 
@@ -1381,6 +1389,11 @@ const result = await g8.api.lists.refreshMasterListNow({ path: { audience_id: 12
 
 Remove contacts from a list.
 
+``removed`` is the number of membership rows really deleted; requested ids
+that were not on the list come back in ``not_member`` (LI-01). A missing or
+deleted list is a 404 (a deleted list's membership is frozen, so nothing
+could be removed from it anyway).
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -1483,6 +1496,8 @@ Other envelope fields: `pagination` (PaginationMeta).
 |---|---|---|---|
 | `id` | `integer` | yes |  |
 | `title` | `string` | yes |  |
+| `company_count` | `integer \| null` | no | Number of companies in a company list (null for other list types) |
+| `contact_count` | `integer \| null` | no | Number of contacts in a contact list (null for other list types) |
 | `created_at` | `string (date-time) \| null` | no |  |
 | `created_by` | `string \| null` | no |  |
 | `description` | `string \| null` | no | Agent/human-readable note describing the list's purpose (#16641) |
@@ -1492,7 +1507,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `tags` | `Array<string>` | no |  |
 | `total` | `integer` | no | default `0` |
 | `type` | `string \| null` | no | List type (contacts, companies, suppressions, deals, leads) |
-| `updated_at` | `string (date-time) \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no | Last change to the list. Equals created_at for a list never edited since creation. |
 
 **Example**