@graph8/sdk 0.265.0 → 0.293.0

package/dist/types/core.d.ts

@@ -1009,9 +1009,11 @@ declare class G8 {
     get search(): {
         contacts(params?: import("./search").SearchParams): Promise<{
             data: import("./search").SearchContactItem[];
+            pagination?: import("./search").SearchPagination;
         }>;
         companies(params?: import("./search").SearchParams): Promise<{
             data: import("./search").SearchCompanyItem[];
+            pagination?: import("./search").SearchPagination;
         }>;
         saveContacts(params: import("./search").SearchSaveParams): Promise<import("./search").SearchSaveResult>;
         saveCompanies(params: import("./search").SearchSaveParams): Promise<import("./search").SearchSaveResult>;

package/dist/types/enrich.d.ts

@@ -27,11 +27,15 @@ export interface SearchResults {
 /**
  * Enrichment API - person/company lookup, email verification, prospecting search.
  *
- * Requires API key (server-side only). Credits charged per call. On the hardened
+ * Requires API key (server-side only). Lookups and email verification charge
+ * credits per call; search is free. On the hardened
  * HTTP core: throws a typed `G8Error` on failure and retries transient errors.
  */
 export declare const createEnrichClient: (apiKey: string, apiUrl?: string) => {
-    /** Look up a person by email, LinkedIn, or name + company. Costs 1 credit. */
+    /**
+     * Look up a person by email, LinkedIn, or name + company. Costs 2 credits per
+     * lookup, charged even when no match is found (`found: false`).
+     */
     person(params: {
         email?: string;
         linkedin_url?: string;
@@ -39,13 +43,16 @@ export declare const createEnrichClient: (apiKey: string, apiUrl?: string) => {
         last_name?: string;
         company_domain?: string;
     }): Promise<PersonEnrichment>;
-    /** Look up a company by domain or name. Costs 1 credit. */
+    /**
+     * Look up a company by domain or name. Costs 2 credits per lookup, charged
+     * even when no match is found (`found: false`).
+     */
     company(params: {
         domain?: string;
         name?: string;
     }): Promise<CompanyEnrichment>;
     /** Verify an email address. Costs 1 credit. */
     verifyEmail(email: string): Promise<EmailVerification>;
-    /** Search 700M+ contacts with filters. Credits charged per result. */
+    /** Search 700M+ contacts with filters. Does not consume credits. */
     search(filters: SearchFilter[], page?: number, limit?: number): Promise<SearchResults>;
 };

package/dist/types/index.d.ts

@@ -35,7 +35,7 @@ export type { IntentKeyword, IntentPage, IntentVisitor, IntentCompany, IntentCon
 export type { GlobalContextDocument, Persona, ICP, IntelligenceData, ResearchReport, } from "./studio";
 export type { MeetingSummary, MeetingDetail, MeetingAttendee, MeetingTranscriptLine, MeetingAnalysis, MeetingListParams, } from "./meetings";
 export type { AudienceSync, AudienceSyncPlatform, AudienceSyncMode, AudienceSyncCreateParams, AudienceSyncUpdateParams, AudienceSyncRun, AudienceSyncError, } from "./audiences";
-export type { SearchOperator, SearchCondition, SearchParams, SearchSaveParams, SearchContactItem, SearchCompanyItem, SearchSaveResult, } from "./search";
+export type { SearchOperator, SearchCondition, SearchParams, SearchSaveParams, SearchContactItem, SearchCompanyItem, SearchSaveResult, SearchPagination, } from "./search";
 export type { AgencyInfo, AgencyClient } from "./agency";
 export type { MarketplaceProfile, MarketplaceOffer, MarketplaceHiring } from "./marketplace";
 export type { Snippet } from "./snippet";

package/dist/types/react.d.ts

@@ -128,8 +128,10 @@ export declare const useG8: () => {
                 company_domain?: string;
             }): Promise<import("./enrich").PersonEnrichment>;
             company(params: {
-                domain?: string;
-                name? /** Identify a user */: string;
+                domain
+                /** Progressive form helpers (read lazily, so useG8() never throws on its own) */
+                ? /** Progressive form helpers (read lazily, so useG8() never throws on its own) */: string;
+                name?: string;
             }): Promise<import("./enrich").CompanyEnrichment>;
             verifyEmail(email: string): Promise<import("./enrich").EmailVerification>;
             search(filters: import("./enrich").SearchFilter[], page?: number, limit?: number): Promise<import("./enrich").SearchResults>;
@@ -941,9 +943,11 @@ export declare const useG8: () => {
         get search(): {
             contacts(params?: import("./search").SearchParams): Promise<{
                 data: import("./search").SearchContactItem[];
+                pagination?: import("./search").SearchPagination;
             }>;
             companies(params?: import("./search").SearchParams): Promise<{
                 data: import("./search").SearchCompanyItem[];
+                pagination?: import("./search").SearchPagination;
             }>;
             saveContacts(params: import("./search").SearchSaveParams): Promise<import("./search").SearchSaveResult>;
             saveCompanies(params: import("./search").SearchSaveParams): Promise<import("./search").SearchSaveResult>;

package/dist/types/search.d.ts

@@ -11,7 +11,10 @@ export interface SearchCondition {
 export interface SearchParams {
     /** Filter conditions, combined with AND. */
     filters?: SearchCondition[];
-    /** Page number, 1-indexed (1-100). */
+    /**
+     * Page number, 1-indexed. page * limit may not exceed 10,000 (the paging
+     * window); narrow the filters to reach records beyond it.
+     */
     page?: number;
     /** Results per page (1-100, default 25). */
     limit?: number;
@@ -45,6 +48,25 @@ export interface SearchContactItem {
     company_employee_count?: string | null;
     company_country?: string | null;
     confidence_score?: number | null;
+    /**
+     * Fields whose value exists but is locked (shown as "***") until the contact
+     * is added to a list. A null field has no value.
+     */
+    locked_fields?: string[];
+}
+/** Pagination block of a search response. */
+export interface SearchPagination {
+    page: number;
+    limit: number;
+    /** Results that can be paged (at most 10,000). */
+    total: number;
+    has_next: boolean;
+    /** How many records really match, when known (can exceed `total`). */
+    total_available?: number | null;
+    /** True when more records match than `total` shows. */
+    total_is_lower_bound?: boolean | null;
+    /** Plain-language notes, e.g. a reversed `between` range was put in order. */
+    notes?: string[] | null;
 }
 export interface SearchCompanyItem {
     name?: string | null;
@@ -87,10 +109,12 @@ export declare const createSearchClient: (apiKey: string, apiUrl?: string) => {
     /** Search open-data contacts by filter. */
     contacts(params?: SearchParams): Promise<{
         data: SearchContactItem[];
+        pagination?: SearchPagination;
     }>;
     /** Search open-data companies by filter. */
     companies(params?: SearchParams): Promise<{
         data: SearchCompanyItem[];
+        pagination?: SearchPagination;
     }>;
     /** Search contacts and save the matches into a new list. */
     saveContacts(params: SearchSaveParams): Promise<SearchSaveResult>;

package/dist/types/version.d.ts

@@ -5,6 +5,6 @@
  * both together (the version-parity gate already pins package.json, the
  * lockfile and the CHANGELOG to each other).
  */
-export declare const SDK_VERSION = "0.265.0";
+export declare const SDK_VERSION = "0.293.0";
 /** Value of the `X-G8-Client` header every SDK request carries (I-13). */
-export declare const SDK_CLIENT_ID = "js-sdk/0.265.0";
+export declare const SDK_CLIENT_ID = "js-sdk/0.293.0";

package/docs/agents.md

@@ -9,7 +9,7 @@ grows every week and your training data is older than this file.
 
 graph8 is a B2B go-to-market platform: CRM (contacts, companies, deals, custom objects), a 700M-person
 data index with enrichment, intent signals, sequences and campaigns across email/SMS/LinkedIn/voice, a unified
-inbox, meetings, workflows and more. This SDK reaches all of it: **3252 Developer API
+inbox, meetings, workflows and more. This SDK reaches all of it: **3255 Developer API
 operations** in 141 areas.
 
 ## 1. The short version
@@ -92,7 +92,7 @@ g8.init({ apiKey: process.env.G8_API_KEY! });
 | | Hand-written clients | `g8.api` (generated) |
 |---|---|---|
 | Example | `g8.contacts.upsert({ list_id, work_email })` | `g8.api.assertUpsert.assertContact({ body: { list_id, work_email } })` |
-| Coverage | 289 methods, reaching 258 operations | all 3252 operations |
+| Coverage | 289 methods, reaching 258 operations | all 3255 operations |
 | Returns | the unwrapped value (usually `data`) | the full envelope; read `result.data` |
 | Arguments | positional / friendly names | `{ path?, query?, headers?, body? }`, exactly as the contract names them |
 | Reference | [sdk-clients.md](sdk-clients.md) | [api/README.md](api/README.md) |
@@ -141,7 +141,7 @@ Hand-written modules:
 | [`g8.webhooks`](sdk-clients.md#g8-webhooks) | 1 | API key |
 | [`g8.workflows`](sdk-clients.md#g8-workflows) | 21 | API key |
 
-`g8.api` namespaces (operation counts): `accounts` (16), `adCampaigns` (19), `adCreatives` (40), `agency` (24), `agent` (8), `agents` (65), `aiInbox` (79), `analytics` (51), `apiKeys` (6), `appDeployments` (7), `appDomains` (5), `appLogs` (2), `appObjects` (10), `appPages` (16), `appPlatformTokens` (3), `appointments` (92), `apps` (22), `assertUpsert` (6), `audienceSyncs` (8), `brandKit` (30), `bugReports` (7), `calendarInvites` (3), `campaignWorkflows` (5), `campaigns` (29), `channels` (5), `cliCampaigns` (6), `cliPipelines` (12), `clickHouse` (2), `companies` (50), `companyIntelligence` (14), `contacts` (70), `content` (41), `contentGridSkills` (6), `copilot` (39), `crmSyncs` (6), `customerSuccess` (19), `deals` (48), `deliverability` (17), `desk` (71), `dialer` (46), `dialerAnalytics` (6), `documents` (35), `duplicates` (7), `eSign` (1), `eSignature` (7), `enrichment` (114), `events` (1), `fields` (8), `forms` (35), `gtmCampaigns` (22), `gtmContext` (51), `gtmDeliverability` (1), `gtmKnowledgeBase` (2), `gtmLaunchHelpers` (2), `gtmLibrary` (20), `health` (1), `imageLibrary` (14), `imports` (3), `inbox` (22), `install` (6), `installedApps` (4), `integrationStatus` (6), `integrations` (83), `intent` (16), `knowledge` (21), `knowledgeBase` (2), `landingPages` (59), `leads` (4), `library` (9), `linkedIn` (5), `linkedInOutreach` (20), `lists` (36), `logs` (1), `mailboxes` (38), `marketingIntelligence` (10), `marketplace` (142), `mcp` (1), `me` (1), `meetings` (17), `newsletter` (61), `notes` (19), `notifications` (2), `objects` (18), `openSearch` (4), `ops` (5), `orgGovernance` (17), `orgVideos` (6), `organizationSettings` (22), `phoneNumbers` (16), `profile` (14), `programmaticPages` (15), `providerDomains` (34), `providerUsage` (5), `public` (1), `publicCopilot` (1), `publicSignals` (1), `publicVisitors` (2), `quotes` (56), `radar` (42), `radarReports` (8), `recordRoles` (4), `repos` (4), `research` (13), `revenue` (14), `revenueAnalytics` (6), `revenueLifecycle` (5), `revenueRecords` (15), `roles` (20), `salesCoach` (37), `sandbox` (9), `scans` (2), `scheduleBuy` (9), `scraping` (10), `sdrAnalytics` (5), `search` (19), `seo` (11), `sequenceLifecycle` (8), `sequences` (71), `settings` (18), `signals` (56), `signatures` (24), `skills` (12), `snippet` (2), `socialPublishing` (22), `studioDocuments` (9), `support` (1), `suppressions` (6), `surveys` (21), `tasks` (25), `teamMembers` (21), `teams` (35), `usage` (9), `visitors` (26), `voice` (187), `webAnalytics` (38), `webChat` (46), `webhooks` (8), `websiteEditor` (12), `work` (59), `workbench` (107), `workflows` (59).
+`g8.api` namespaces (operation counts): `accounts` (16), `adCampaigns` (19), `adCreatives` (40), `agency` (24), `agent` (8), `agents` (65), `aiInbox` (79), `analytics` (51), `apiKeys` (6), `appDeployments` (7), `appDomains` (5), `appLogs` (2), `appObjects` (10), `appPages` (16), `appPlatformTokens` (3), `appointments` (92), `apps` (22), `assertUpsert` (6), `audienceSyncs` (8), `brandKit` (30), `bugReports` (7), `calendarInvites` (3), `campaignWorkflows` (5), `campaigns` (29), `channels` (5), `cliCampaigns` (6), `cliPipelines` (12), `clickHouse` (2), `companies` (50), `companyIntelligence` (14), `contacts` (70), `content` (41), `contentGridSkills` (6), `copilot` (39), `crmSyncs` (6), `customerSuccess` (19), `deals` (48), `deliverability` (17), `desk` (71), `dialer` (46), `dialerAnalytics` (6), `documents` (35), `duplicates` (7), `eSign` (1), `eSignature` (7), `enrichment` (115), `events` (1), `fields` (8), `forms` (35), `gtmCampaigns` (22), `gtmContext` (51), `gtmDeliverability` (1), `gtmKnowledgeBase` (2), `gtmLaunchHelpers` (2), `gtmLibrary` (20), `health` (1), `imageLibrary` (14), `imports` (3), `inbox` (22), `install` (6), `installedApps` (4), `integrationStatus` (6), `integrations` (83), `intent` (16), `knowledge` (21), `knowledgeBase` (2), `landingPages` (59), `leads` (4), `library` (9), `linkedIn` (5), `linkedInOutreach` (20), `lists` (36), `logs` (1), `mailboxes` (38), `marketingIntelligence` (10), `marketplace` (142), `mcp` (1), `me` (1), `meetings` (17), `newsletter` (61), `notes` (19), `notifications` (2), `objects` (18), `openSearch` (4), `ops` (5), `orgGovernance` (17), `orgVideos` (6), `organizationSettings` (22), `phoneNumbers` (16), `profile` (14), `programmaticPages` (15), `providerDomains` (34), `providerUsage` (5), `public` (1), `publicCopilot` (1), `publicSignals` (1), `publicVisitors` (2), `quotes` (56), `radar` (42), `radarReports` (8), `recordRoles` (4), `repos` (4), `research` (13), `revenue` (14), `revenueAnalytics` (6), `revenueLifecycle` (5), `revenueRecords` (15), `roles` (21), `salesCoach` (37), `sandbox` (9), `scans` (2), `scheduleBuy` (9), `scraping` (10), `sdrAnalytics` (5), `search` (19), `seo` (11), `sequenceLifecycle` (8), `sequences` (71), `settings` (18), `signals` (56), `signatures` (24), `skills` (12), `snippet` (3), `socialPublishing` (22), `studioDocuments` (9), `support` (1), `suppressions` (6), `surveys` (21), `tasks` (25), `teamMembers` (21), `teams` (35), `usage` (9), `visitors` (26), `voice` (187), `webAnalytics` (38), `webChat` (46), `webhooks` (8), `websiteEditor` (12), `work` (59), `workbench` (107), `workflows` (59).
 
 ## 5. How to find the right call
 
@@ -196,11 +196,11 @@ Every operation carries a tier:
 
 | Tier | What it means | Count |
 |---|---|---|
-| `read` | reads data; safe to call and to retry | 1508 |
+| `read` | reads data; safe to call and to retry | 1510 |
 | `write` | creates or changes records; the SDK sends an Idempotency-Key and retries transient failures | 811 |
 | `destructive` | deletes or archives data; confirm with a human before calling | 300 |
 | `billable` | spends credits; the SDK never blindly retries it; confirm cost before bulk use | 383 |
-| `external` | reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first | 250 |
+| `external` | reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first | 251 |
 
 What the SDK does for you:
 
@@ -219,7 +219,8 @@ What you must do:
 
 - Get a human's confirmation before calling an `external`, `billable` or `destructive` operation, and say
   what it will do ("this sends the email to 240 contacts").
-- Keep bulk billable jobs small until the user confirms the cost (enrichment is 1 credit per lookup).
+- Keep bulk billable jobs small until the user confirms the cost (a person or company lookup is 2 credits,
+  charged even when no match is found).
 
 ## 8. Errors
 
@@ -375,7 +376,7 @@ for (const person of results.contacts) {
 
 ### Enrich one person or company
 
-You have an email, LinkedIn URL, name + company, or a domain and need the full profile. Each call costs 1 credit (tier `billable`), so the SDK will not blindly retry it on a 5xx.
+You have an email, LinkedIn URL, name + company, or a domain and need the full profile. Each lookup costs 2 credits, charged even when no match is found, and an email verify costs 1 (tier `billable`), so the SDK will not blindly retry them on a 5xx.
 
 ```ts
 import { g8 } from "@graph8/sdk";

package/docs/api/README.md

@@ -2,7 +2,7 @@
 
 # `g8.api`: every Developer API operation
 
-`g8.api` is generated from the published OpenAPI contract, so it covers all 3252 operations across 141 namespaces (1508 read, 811 write, 300 destructive, 383 billable, 250 external).
+`g8.api` is generated from the published OpenAPI contract, so it covers all 3255 operations across 141 namespaces (1510 read, 811 write, 300 destructive, 383 billable, 251 external).
 
 - Found a REST path in a curl example or the web docs? Look it up in [by-path.md](by-path.md).
 - Prefer a hand-written method where one exists: [../sdk-clients.md](../sdk-clients.md).
@@ -67,7 +67,7 @@
 | `g8.api.duplicates` | Duplicates | 7 | none | [duplicates.md](duplicates.md) | [duplicates.d.ts](duplicates.d.ts) |
 | `g8.api.eSign` | E-Sign | 1 | none | [eSign.md](eSign.md) | [eSign.d.ts](eSign.d.ts) |
 | `g8.api.eSignature` | E-Signature | 7 | none | [eSignature.md](eSignature.md) | [eSignature.d.ts](eSignature.d.ts) |
-| `g8.api.enrichment` | Enrichment | 114 | 3 | [enrichment.md](enrichment.md) | [enrichment.d.ts](enrichment.d.ts) |
+| `g8.api.enrichment` | Enrichment | 115 | 3 | [enrichment.md](enrichment.md) | [enrichment.d.ts](enrichment.d.ts) |
 | `g8.api.events` | Events | 1 | none | [events.md](events.md) | [events.d.ts](events.d.ts) |
 | `g8.api.fields` | Fields | 8 | 5 | [fields.md](fields.md) | [fields.d.ts](fields.d.ts) |
 | `g8.api.forms` | Forms | 35 | none | [forms.md](forms.md) | [forms.d.ts](forms.d.ts) |
@@ -129,7 +129,7 @@
 | `g8.api.revenueAnalytics` | Revenue Analytics | 6 | none | [revenueAnalytics.md](revenueAnalytics.md) | [revenueAnalytics.d.ts](revenueAnalytics.d.ts) |
 | `g8.api.revenueLifecycle` | Revenue Lifecycle | 5 | none | [revenueLifecycle.md](revenueLifecycle.md) | [revenueLifecycle.d.ts](revenueLifecycle.d.ts) |
 | `g8.api.revenueRecords` | Revenue Records | 15 | none | [revenueRecords.md](revenueRecords.md) | [revenueRecords.d.ts](revenueRecords.d.ts) |
-| `g8.api.roles` | Roles | 20 | none | [roles.md](roles.md) | [roles.d.ts](roles.d.ts) |
+| `g8.api.roles` | Roles | 21 | none | [roles.md](roles.md) | [roles.d.ts](roles.d.ts) |
 | `g8.api.salesCoach` | Sales Coach | 37 | none | [salesCoach.md](salesCoach.md) | [salesCoach.d.ts](salesCoach.d.ts) |
 | `g8.api.sandbox` | sandbox | 9 | none | [sandbox.md](sandbox.md) | [sandbox.d.ts](sandbox.d.ts) |
 | `g8.api.scans` | Scans | 2 | none | [scans.md](scans.md) | [scans.d.ts](scans.d.ts) |
@@ -144,7 +144,7 @@
 | `g8.api.signals` | Signals | 56 | none | [signals.md](signals.md) | [signals.d.ts](signals.d.ts) |
 | `g8.api.signatures` | Signatures | 24 | none | [signatures.md](signatures.md) | [signatures.d.ts](signatures.d.ts) |
 | `g8.api.skills` | Skills | 12 | 12 | [skills.md](skills.md) | [skills.d.ts](skills.d.ts) |
-| `g8.api.snippet` | Snippet | 2 | 1 | [snippet.md](snippet.md) | [snippet.d.ts](snippet.d.ts) |
+| `g8.api.snippet` | Snippet | 3 | 1 | [snippet.md](snippet.md) | [snippet.d.ts](snippet.d.ts) |
 | `g8.api.socialPublishing` | Social Publishing | 22 | none | [socialPublishing.md](socialPublishing.md) | [socialPublishing.d.ts](socialPublishing.d.ts) |
 | `g8.api.studioDocuments` | Studio Documents | 9 | none | [studioDocuments.md](studioDocuments.md) | [studioDocuments.d.ts](studioDocuments.d.ts) |
 | `g8.api.support` | Support | 1 | none | [support.md](support.md) | [support.d.ts](support.d.ts) |

package/docs/api/accounts.d.ts

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

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

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

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

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

@@ -1559,10 +1559,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 `SessionReadRequest`. */

package/docs/api/aiInbox.d.ts

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

@@ -949,7 +949,7 @@ export interface AnalyticsOperations {
   };
 }
 
-// 19 schemas referenced above (the same as G8Contract.<Name>).
+// 20 schemas referenced above (the same as G8Contract.<Name>).
 
 export interface ApiResponse_CampaignVisitorsReport_ {
   data: CampaignVisitorsReport;
@@ -990,6 +990,8 @@ export interface CampaignVisitorContact {
 export interface CampaignVisitorLink {
   /** events ÷ emails_with_link × 100, clamped [0,100]; null when no denominator */
   ctr_percent?: number | null;
+  /** Why `ctr_percent` is null: 'no_matching_send' = no email sent in the window contained this exact link (e.g. the click came from an email sent before the window, or from a link shared outside a sequence); 'send_lookup_unavailable' = the send counts could not be loaded this time. Null whenever `ctr_percent` has a value. */
+  ctr_unavailable_reason?: string | null;
   /** Sends whose template embedded this URL (CTR denominator) */
   emails_with_link?: number | null;
   /** Human click events on this URL (scanner-filtered) */
@@ -1028,6 +1030,27 @@ export interface CampaignVisitorStep {
   unique_contacts: number;
 }
 
+/**
+ * One summary counter with a human label and a plain-language definition.
+ *
+ * Added for VI-04: the raw ``summary`` keys are internal names
+ * (``jitsu_wired``, ``encrypted_pageviews``) and mix whole-site volume with
+ * campaign clicks. ``summary.metrics`` lists the SAME values under friendly
+ * labels; the original keys are unchanged.
+ */
+export interface CampaignVisitorsMetric {
+  /** What is counted, in plain language */
+  definition: string;
+  /** The `summary` field this entry describes (same value) */
+  key: string;
+  /** Human-readable metric name */
+  label: string;
+  /** 'site' = all tracked page views (context only), 'campaign' = email-link clicks, 'diagnostic' = tracking-health detail, 'table' = row counts behind the tables */
+  scope: string;
+  /** Same value as `summary.<key>` */
+  value: number | boolean;
+}
+
 /** Composite Campaign Visitors report for a single org (analytics report a23). */
 export interface CampaignVisitorsReport {
   link_engagement: Array<CampaignVisitorLink>;
@@ -1055,6 +1078,8 @@ export interface CampaignVisitorsSummary {
   jitsu_wired: boolean;
   /** Total distinct clicked (host, path) before the ceiling */
   link_rows: number;
+  /** The counters above with friendly labels, plain-language definitions and a scope, in display order. Same values as the individual keys; use this to present the summary. */
+  metrics?: Array<CampaignVisitorsMetric>;
   /** Parseable campaign-attributed click events */
   pageview_events: number;
   /** Diagnostic: campaign clicks with a plaintext hash */
@@ -1241,10 +1266,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/analytics.md

@@ -1963,6 +1963,7 @@ One row of the Email Link Engagement table (a clicked destination URL).
 | `path` | `string` | yes | Clicked destination path |
 | `unique_contacts` | `integer` | yes | Distinct contacts who clicked this URL |
 | `ctr_percent` | `number \| null` | no | events ÷ emails_with_link × 100, clamped [0,100]; null when no denominator |
+| `ctr_unavailable_reason` | `string \| null` | no | Why `ctr_percent` is null: 'no_matching_send' = no email sent in the window contained this exact link (e.g. the click came from an email sent before the window, or from a link shared outside a sequence); 'send_lookup_unavailable' = the send counts could not be loaded this time. Null whenever `ctr_percent` has a value. |
 | `emails_with_link` | `integer \| null` | no | Sends whose template embedded this URL (CTR denominator) |
 | `last_seen` | `string \| null` | no | Latest click timestamp (ISO) |
 | `step_ids` | `Array<string>` | no | Sequencer steps whose links drove these clicks |
@@ -2005,6 +2006,7 @@ KPI tiles for the org's campaign-click activity in the window. All click-derived
 | `unique_campaign_steps` | `integer` | yes | Distinct sequencer steps that drew clicks |
 | `unique_contacts` | `integer` | yes | Distinct contacts who clicked a campaign link |
 | `unparseable_pageviews` | `integer` | yes | Campaign clicks whose tracking hash could not be decoded |
+| `metrics` | `Array<CampaignVisitorsMetric>` | no | The counters above with friendly labels, plain-language definitions and a scope, in display order. Same values as the individual keys; use this to present the summary. |
 
 <a id="type-campaignvisitorswindow"></a>
 

package/docs/api/apiKeys.d.ts

@@ -223,10 +223,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 ScopeCatalogEntry {

package/docs/api/appDeployments.d.ts

@@ -224,10 +224,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 PromoteDeploymentRequest {

package/docs/api/appDomains.d.ts

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

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

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

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

@@ -88,10 +88,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;
 }
 
 /** Client-credentials exchange for a service (server-to-server) app token. */