@graph8/sdk 0.265.0 → 0.293.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/events.d.ts

@@ -108,8 +108,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }

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;
 }
 
@@ -385,10 +406,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /** One row (contact or company) plus the columns to set on it. */

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/forms.d.ts

@@ -1005,8 +1005,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }

package/docs/api/gtmCampaigns.d.ts

@@ -585,10 +585,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 export interface SequenceStepRef {

package/docs/api/gtmContext.d.ts

@@ -1040,10 +1040,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /** Mirrors `company_profile.SaveProfileRequest`. */

package/docs/api/gtmDeliverability.d.ts

@@ -53,8 +53,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }

package/docs/api/gtmKnowledgeBase.d.ts

@@ -69,8 +69,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }

package/docs/api/gtmLibrary.d.ts

@@ -415,10 +415,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 export interface PersonaFillFromDocRequest {

package/docs/api/imageLibrary.d.ts

@@ -317,10 +317,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /**

package/docs/api/imports.d.ts

@@ -150,8 +150,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }

package/docs/api/inbox.d.ts

@@ -633,10 +633,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /** A named queue + filter combination. */

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;
     };
@@ -165,10 +171,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 export interface PatchResponse {
@@ -190,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>;
@@ -197,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/installedApps.d.ts

@@ -124,8 +124,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }

package/docs/api/integrationStatus.d.ts

@@ -135,8 +135,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }