@graph8/sdk 0.265.0 → 0.293.0

package/docs/api/companies.md

@@ -297,6 +297,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `status` | `string` | yes |  |
 | `company_id` | `integer \| null` | no |  |
 | `merged` | `boolean` | no | default `false` |
+| `warnings` | `Array<string>` | no | Advisory notes about values that look wrong (e.g. an employee_count with no number, an unrecognised country, or a linkedin_url that is not a web address and was not saved). Empty when the input is clean. |
 
 **Example**
 
@@ -338,7 +339,7 @@ Body fields (`CreateCompanyColumnRequest`):
 |---|---|---|---|
 | `body.created_by` | `string (email)` | yes | Email of the user creating the column (for audit). |
 | `body.title` | `string` | yes | Column title shown in the UI (e.g. 'Tier') |
-| `body.data_type` | `ColumnType` | no | Column data type. Currently only 'text' is supported. default `"text"` |
+| `body.data_type` | `ColumnType` | no | Column data type: 'text', 'int' (whole number), 'numeric' (decimal) or 'boolean' (yes/no). Other values 422. default `"text"` |
 | `body.enrichment` | `CreateFieldEnrichmentInput \| null` | no | STRONGLY RECOMMENDED. Optional waterfall enrichment block. When supplied, a companion `enrichment_configs` row is created alongside the column so the UI 'Enrich' button works immediately. Without it the column exists but isn't enrichable until a pipeline is configured via POST /enrichment/waterfall/configs. |
 | `body.list_id` | `integer \| null` | no | If set, the column is list-scoped (only visible on that list). Required when `enrichment` is supplied — waterfall pipelines are list-scoped. |
 
@@ -351,12 +352,15 @@ Other envelope fields: `pagination` (PaginationMeta).
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `title` | `string` | yes |  |
+| `already_existed` | `boolean` | no | True when a column with this name already existed in this scope, so the existing column was returned. A different `data_type` is rejected with 409. default `false` |
 | `data_type` | `ColumnType` | no | default `"text"` |
 | `enrichment` | `CreateFieldEnrichmentResponse \| null` | no | Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent POST /enrichment/waterfall/enrich calls. |
+| `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 | Computed: True when object_id is null/empty (global column). default `false` |
 | `name` | `string \| null` | no |  |
 | `object_id` | `string \| null` | no |  |
+| `warnings` | `Array<string>` | no | Non-blocking notices (e.g. a same-named org-wide column also shows on this list). |
 
 **Example**
 
@@ -1354,8 +1358,8 @@ List companies with optional filtering and pagination.
 | `query.name` | `string \| null` | no | Filter by company name (partial match) |
 | `query.employee_count_min` | `integer \| null` | no | Minimum employee count |
 | `query.employee_count_max` | `integer \| null` | no | Maximum employee count |
-| `query.country` | `string \| null` | no | Filter by country (exact match) |
-| `query.state` | `string \| null` | no | Filter by state (exact match) |
+| `query.country` | `string \| null` | no | Filter by country (exact match, case-insensitive; surrounding spaces ignored). Common aliases match each other: United States = US = USA; United Kingdom = UK. |
+| `query.state` | `string \| null` | no | Filter by state (exact match, case-insensitive; surrounding spaces ignored) |
 | `query.city` | `string \| null` | no | Filter by city (partial match) |
 | `query.description` | `string \| null` | no | Filter by company description (partial match) |
 | `query.revenue_min` | `integer \| null` | no | Minimum annual revenue |
@@ -2068,6 +2072,12 @@ const result = await g8.api.companies.startCompanyWorkflow({ path: { company_id:
 
 Update a company's fields (partial update).
 
+A ``name`` over 512 characters or a ``linkedin_url`` that is not a web
+address is refused with a 400 and nothing is written. An employee_count
+with no number, an unrecognised country, or a linkedin_url that is not on
+linkedin.com is saved as sent and flagged in ``warnings`` (present only
+when there is something to flag).
+
 **Input**
 
 | Field | Type | Required | Description |

package/docs/api/companyIntelligence.d.ts

@@ -292,8 +292,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/contacts.d.ts

@@ -844,7 +844,7 @@ export interface ContactsOperations {
       page?: number;
       /** Items per page (max 200) */
       limit?: number;
-      /** Filter by work email (exact match) */
+      /** Filter by work email (exact match, case-insensitive; surrounding spaces ignored) */
       email?: string | null;
       /** Filter by list ID */
       list_id?: number | null;
@@ -852,15 +852,15 @@ export interface ContactsOperations {
       name?: string | null;
       /** Filter by job title (partial match) */
       job_title?: string | null;
-      /** Filter by seniority level (exact match) */
+      /** Filter by seniority level (exact match, case-insensitive). Spellings of the same level match each other: VP = Vice President; SVP/EVP = SVP = EVP = Senior/Executive Vice President; C-Suite = C-Level = CXO. Pass several levels comma-separated to match any of them, e.g. `VP,SVP/EVP`. */
       seniority_level?: string | null;
       /** Filter by company name (partial match) */
       company_name?: string | null;
       /** Filter by company ID */
       company_id?: number | null;
-      /** Filter by country (exact match) */
+      /** Filter by country (exact match, case-insensitive; surrounding spaces ignored). Common aliases match each other: United States = US = USA; United Kingdom = UK. */
       country?: string | null;
-      /** Filter by state (exact match) */
+      /** Filter by state (exact match, case-insensitive; surrounding spaces ignored) */
       state?: string | null;
       /** Filter by city (partial match) */
       city?: string | null;
@@ -1540,6 +1540,8 @@ export interface ContactCreateResponse {
   merged?: boolean;
   status: string;
   validation_errors?: Array<string>;
+  /** Advisory notes about values saved as sent that look wrong (e.g. an unrecognised seniority or country). Empty when the input is clean. */
+  warnings?: Array<string>;
 }
 
 /** Mirrors `campaign_builder.models.contact_documents.UpdateContactDocumentRequest`. */
@@ -1553,8 +1555,14 @@ export interface ContactDocumentUpdateRequest {
 /** Lighter contact representation for list endpoints. */
 export interface ContactListItem {
   city?: string | null;
+  company_domain?: string | null;
+  company_employee_count?: string | null;
   company_id?: number | null;
+  company_industry?: string | null;
+  company_name?: string | null;
+  company_website?: string | null;
   country?: string | null;
+  created_at?: string | null;
   custom_fields?: (Record<string, string | null>) | null;
   direct_phone?: string | null;
   first_name?: string | null;
@@ -1568,6 +1576,7 @@ export interface ContactListItem {
   owner_name?: string | null;
   seniority_level?: string | null;
   state?: string | null;
+  updated_at?: string | null;
   work_email?: string | null;
 }
 
@@ -1707,7 +1716,7 @@ export interface ContactUpdateRequest {
 export interface CreateContactColumnRequest {
   /** Email of the user creating the column (for audit). */
   created_by: string;
-  /** Column data type. Currently only 'text' is supported. */
+  /** Column data type: 'text', 'int' (whole number), 'numeric' (decimal) or 'boolean' (yes/no). Other values 422. */
   data_type?: ColumnType;
   /** STRONGLY RECOMMENDED. Optional waterfall enrichment block. When supplied, a companion `enrichment_configs` row is created alongside the column so the UI 'Enrich' button works immediately. Without it the column exists but isn't enrichable until a pipeline is configured via POST /enrichment/waterfall/configs. */
   enrichment?: CreateFieldEnrichmentInput | null;
@@ -1726,15 +1735,21 @@ export interface CreateContactColumnRequest {
  * that is populated when the request included an `enrichment` block.
  */
 export interface CreateContactColumnResponse {
+  /** True when a column with this name already existed in this scope, so the existing column was returned. A different `data_type` is rejected with 409. */
+  already_existed?: boolean;
   data_type?: ColumnType;
   /** Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent POST /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 | null;
   /** Computed: True when object_id is null/empty (global column). */
   is_global?: boolean;
   name?: string | null;
   object_id?: string | null;
   title: string;
+  /** Non-blocking notices (e.g. a same-named org-wide column also shows on this list). */
+  warnings?: Array<string>;
 }
 
 /**
@@ -1930,10 +1945,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/contacts.md

@@ -245,7 +245,7 @@ const result = await g8.api.contacts.batchContactRelated({ body: { contact_ids:
 Full records for up to 100 contacts in ONE request. Writes nothing.
 
 Use this instead of looping `GET /contacts/{contact_id}`: `GET /contacts`
-returns 17 fields per contact, and the loop spends one rate-limit slot per
+returns a lean summary per contact, and the loop spends one rate-limit slot per
 contact to get the other fields. Each item is exactly what the per-contact
 route returns, through the same access check. A contact that does not exist
 or is outside the key's scope comes back `found: false`, rather than failing
@@ -385,7 +385,7 @@ Body fields (`CreateContactColumnRequest`):
 |---|---|---|---|
 | `body.created_by` | `string (email)` | yes | Email of the user creating the column (for audit). |
 | `body.title` | `string` | yes | Column title shown in the UI (e.g. 'Lead Score') |
-| `body.data_type` | `ColumnType` | no | Column data type. Currently only 'text' is supported. default `"text"` |
+| `body.data_type` | `ColumnType` | no | Column data type: 'text', 'int' (whole number), 'numeric' (decimal) or 'boolean' (yes/no). Other values 422. default `"text"` |
 | `body.enrichment` | `CreateFieldEnrichmentInput \| null` | no | STRONGLY RECOMMENDED. Optional waterfall enrichment block. When supplied, a companion `enrichment_configs` row is created alongside the column so the UI 'Enrich' button works immediately. Without it the column exists but isn't enrichable until a pipeline is configured via POST /enrichment/waterfall/configs. |
 | `body.list_id` | `integer \| null` | no | If set, the column is list-scoped (only visible on that list). Required when `enrichment` is supplied — waterfall pipelines are list-scoped. |
 
@@ -398,12 +398,15 @@ Other envelope fields: `pagination` (PaginationMeta).
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `title` | `string` | yes |  |
+| `already_existed` | `boolean` | no | True when a column with this name already existed in this scope, so the existing column was returned. A different `data_type` is rejected with 409. default `false` |
 | `data_type` | `ColumnType` | no | default `"text"` |
 | `enrichment` | `CreateFieldEnrichmentResponse \| null` | no | Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent POST /enrichment/waterfall/enrich calls. |
+| `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 | Computed: True when object_id is null/empty (global column). default `false` |
 | `name` | `string \| null` | no |  |
 | `object_id` | `string \| null` | no |  |
+| `warnings` | `Array<string>` | no | Non-blocking notices (e.g. a same-named org-wide column also shows on this list). |
 
 **Example**
 
@@ -544,6 +547,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `custom_fields` | `CustomFieldWriteReport` | no |  |
 | `merged` | `boolean` | no | default `false` |
 | `validation_errors` | `Array<string>` | no |  |
+| `warnings` | `Array<string>` | no | Advisory notes about values saved as sent that look wrong (e.g. an unrecognised seniority or country). Empty when the input is clean. |
 
 **Example**
 
@@ -1879,15 +1883,15 @@ List contacts with optional filtering and pagination.
 |---|---|---|---|
 | `query.page` | `integer` | no | Page number (1-indexed) default `1` |
 | `query.limit` | `integer` | no | Items per page (max 200) default `50` |
-| `query.email` | `string \| null` | no | Filter by work email (exact match) |
+| `query.email` | `string \| null` | no | Filter by work email (exact match, case-insensitive; surrounding spaces ignored) |
 | `query.list_id` | `integer \| null` | no | Filter by list ID |
 | `query.name` | `string \| null` | no | Filter by first or last name (partial match) |
 | `query.job_title` | `string \| null` | no | Filter by job title (partial match) |
-| `query.seniority_level` | `string \| null` | no | Filter by seniority level (exact match) |
+| `query.seniority_level` | `string \| null` | no | Filter by seniority level (exact match, case-insensitive). Spellings of the same level match each other: VP = Vice President; SVP/EVP = SVP = EVP = Senior/Executive Vice President; C-Suite = C-Level = CXO. Pass several levels comma-separated to match any of them, e.g. `VP,SVP/EVP`. |
 | `query.company_name` | `string \| null` | no | Filter by company name (partial match) |
 | `query.company_id` | `integer \| null` | no | Filter by company ID |
-| `query.country` | `string \| null` | no | Filter by country (exact match) |
-| `query.state` | `string \| null` | no | Filter by state (exact match) |
+| `query.country` | `string \| null` | no | Filter by country (exact match, case-insensitive; surrounding spaces ignored). Common aliases match each other: United States = US = USA; United Kingdom = UK. |
+| `query.state` | `string \| null` | no | Filter by state (exact match, case-insensitive; surrounding spaces ignored) |
 | `query.city` | `string \| null` | no | Filter by city (partial match) |
 | `query.job_department` | `string \| null` | no | Filter by job department (partial match) |
 | `query.industry` | `string \| null` | no | Filter by company industry (partial match) |
@@ -1902,8 +1906,14 @@ Other envelope fields: `pagination` (PaginationMeta).
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `city` | `string \| null` | no |  |
+| `company_domain` | `string \| null` | no |  |
+| `company_employee_count` | `string \| null` | no |  |
 | `company_id` | `integer \| null` | no |  |
+| `company_industry` | `string \| null` | no |  |
+| `company_name` | `string \| null` | no |  |
+| `company_website` | `string \| null` | no |  |
 | `country` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
 | `custom_fields` | `Record<string, string \| null> \| null` | no |  |
 | `direct_phone` | `string \| null` | no |  |
 | `first_name` | `string \| null` | no |  |
@@ -1917,6 +1927,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `owner_name` | `string \| null` | no |  |
 | `seniority_level` | `string \| null` | no |  |
 | `state` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
 | `work_email` | `string \| null` | no |  |
 
 **Example**

package/docs/api/content.d.ts

@@ -893,10 +893,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/contentGridSkills.d.ts

@@ -170,8 +170,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/copilot.d.ts

@@ -819,10 +819,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;
 }
 
 /** Mirror of `PersonalContactChoiceRequest`. */

package/docs/api/crmSyncs.d.ts

@@ -208,8 +208,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/customerSuccess.d.ts

@@ -484,8 +484,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/deals.d.ts

@@ -1652,10 +1652,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 PipelineResponse {

package/docs/api/deliverability.d.ts

@@ -400,10 +400,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 RetirementDecisionRequest {

package/docs/api/desk.d.ts

@@ -1758,8 +1758,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/dialer.d.ts

@@ -1072,10 +1072,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/documents.d.ts

@@ -854,10 +854,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/duplicates.d.ts

@@ -184,10 +184,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 RejectDuplicateRequest {

package/docs/api/eSignature.d.ts

@@ -229,10 +229,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;
 }
 
 /** Send a draft for signature. This EMAILS A REAL PERSON. */

package/docs/api/enrichment.d.ts

@@ -1,7 +1,7 @@
 /* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
 
 /**
- * Types for `g8.api.enrichment` (Enrichment): 114 operations.
+ * Types for `g8.api.enrichment` (Enrichment): 115 operations.
  *
  * For reading. In code, import from the package instead:
  *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
@@ -92,6 +92,7 @@ export interface EnrichmentMembers {
   lookupPerson: "lookup_person_enrichment_lookup_person_post";
   lookupPersonAlias: "lookup_person_alias_enrichment_person_post";
   pauseEnrichmentJob: "pause_enrichment_job_enrichment_jobs__job_id__pause_post";
+  preflightEnrichment: "preflight_enrichment_enrichment_preflight_post";
   previewFindPeople: "preview_find_people_enrichment_find_people__config_id__preview_post";
   previewFormula: "preview_formula_enrichment_ai_formula_preview_post";
   previewRecordSync: "preview_record_sync_enrichment_record_sync__entity_type__preview_post";
@@ -1473,6 +1474,20 @@ export interface EnrichmentOperations {
   };
     output: ApiResponse_EnrichmentPayload_;
   };
+  /**
+   * POST /enrichment/preflight
+   * Preflight Enrichment
+   * tier: read · scope: enrichment:read
+   */
+  preflight_enrichment_enrichment_preflight_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: EnrichmentPreflightRequest;
+  };
+    output: ApiResponse_EnrichmentPreflightResponse_;
+  };
   /**
    * POST /enrichment/find-people/{config_id}/preview
    * Preview Find People
@@ -2066,7 +2081,7 @@ export interface EnrichmentOperations {
   };
 }
 
-// 102 schemas referenced above (the same as G8Contract.<Name>).
+// 105 schemas referenced above (the same as G8Contract.<Name>).
 
 /**
  * Run a saved AI group over a list. CHARGES per record.
@@ -2256,6 +2271,11 @@ export interface ApiResponse_EnrichmentPayload_ {
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_EnrichmentPreflightResponse_ {
+  data: EnrichmentPreflightResponse;
+  pagination?: PaginationMeta | null;
+}
+
 export interface ApiResponse_LookupResponse_ {
   data: LookupResponse;
   pagination?: PaginationMeta | null;
@@ -2565,6 +2585,60 @@ export interface EnrichmentListPayload {
  */
 export type EnrichmentPayload = Record<string, unknown>;
 
+/**
+ * Check an enrichment request before running it. Free: nothing is written,
+ * queued or charged.
+ *
+ * Takes the same inputs as the MCP `g8_enrich_contacts` tool so a preview can
+ * say up front whether the run would work.
+ */
+export interface EnrichmentPreflightRequest {
+  /** group_id of a saved AI enrichment config (required for 'ai-research') */
+  ai_group_id?: string | null;
+  /** Contact IDs to enrich (duplicates are counted once) */
+  contact_ids: Array<number>;
+  /** Add ZeroBounce email verification */
+  email_verification?: boolean;
+  /** List ID the contacts belong to */
+  list_id: number;
+  /** 'auto' (AI when ai_group_id is set, else waterfall), 'waterfall' or 'ai-research' */
+  mode?: string;
+  /** 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). */
+  providers?: Array<string> | null;
+  /** Column to enrich: a canonical CONTACT_*\/COMPANY_* column or a synonym like 'phone' or 'email' */
+  target_field?: string | null;
+}
+
+/**
+ * What a run with these inputs would do. Errors (unknown list, mode, field or
+ * provider, impossible contact IDs) come back as 400/404 instead.
+ */
+export interface EnrichmentPreflightResponse {
+  /** Number of unique contacts (the count credits are estimated on) */
+  contact_count: number;
+  /** Contact IDs that will be enriched: duplicates removed, order kept */
+  contact_ids: Array<number>;
+  /** How many repeated contact IDs were dropped */
+  duplicates_removed?: number;
+  list_id: number;
+  list_name?: string | null;
+  /** Providers whose step would be skipped because the org has no key for them */
+  missing_credentials?: Array<string>;
+  /** Resolved mode: 'waterfall' or 'ai-research' */
+  mode: string;
+  /** Contact IDs that are not on the list; the run skips them and does not charge for them */
+  not_in_list?: Array<number>;
+  /** Providers that would run, in order (empty = the saved pipeline) */
+  providers?: Array<string>;
+  providers_detail?: Array<ProviderStepDetail>;
+  /** Canonical column for target_field, when given */
+  target_field?: string | null;
+  /** True when the list's saved pipeline (or the graph8 default) would run */
+  uses_saved_pipeline?: boolean;
+  /** Plain-language advisories for the user */
+  warnings?: Array<string>;
+}
+
 /** Price every visible qualification template against one list. Charges nothing. */
 export interface EstimateAllRequest {
   list_id: number;
@@ -2694,10 +2768,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 PersonLookupRequest {