@graph8/sdk 0.277.0 → 0.294.0

package/dist/types/enrich.d.ts

@@ -34,7 +34,7 @@ export interface SearchResults {
 export declare const createEnrichClient: (apiKey: string, apiUrl?: string) => {
     /**
      * Look up a person by email, LinkedIn, or name + company. Costs 2 credits per
-     * lookup, charged even when no match is found (`found: false`).
+     * lookup, charged only when a match is found (`found: false` costs nothing).
      */
     person(params: {
         email?: string;
@@ -45,7 +45,7 @@ export declare const createEnrichClient: (apiKey: string, apiUrl?: string) => {
     }): Promise<PersonEnrichment>;
     /**
      * Look up a company by domain or name. Costs 2 credits per lookup, charged
-     * even when no match is found (`found: false`).
+     * only when a match is found (`found: false` costs nothing).
      */
     company(params: {
         domain?: string;

package/dist/types/react.d.ts

@@ -128,9 +128,7 @@ export declare const useG8: () => {
                 company_domain?: string;
             }): Promise<import("./enrich").PersonEnrichment>;
             company(params: {
-                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;
+                domain?: string;
                 name?: string;
             }): Promise<import("./enrich").CompanyEnrichment>;
             verifyEmail(email: string): Promise<import("./enrich").EmailVerification>;

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.277.0";
+export declare const SDK_VERSION = "0.294.0";
 /** Value of the `X-G8-Client` header every SDK request carries (I-13). */
-export declare const SDK_CLIENT_ID = "js-sdk/0.277.0";
+export declare const SDK_CLIENT_ID = "js-sdk/0.294.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: **3253 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 3253 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` (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` (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,7 +196,7 @@ 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 |
@@ -220,7 +220,7 @@ 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 (a person or company lookup is 2 credits,
-  charged even when no match is found).
+  charged only when a match is found).
 
 ## 8. Errors
 
@@ -376,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 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.
+You have an email, LinkedIn URL, name + company, or a domain and need the full profile. Each lookup costs 2 credits, charged only when a 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 3253 operations across 141 namespaces (1508 read, 811 write, 300 destructive, 383 billable, 251 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) |
@@ -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/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 */

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

@@ -193,6 +193,8 @@ export interface CompanyAssertRequest {
 export interface CompanyAssertResponse {
   /** 'created' or 'updated' */
   action: string;
+  /** ID of the company that was created or updated (use it with GET/PATCH /companies/{company_id}). Null when the saved record cannot be identified unambiguously, e.g. when the domain already matched several companies in the list. */
+  company_id?: number | null;
   count?: number;
   custom_fields?: CustomFieldWriteReport;
   /** Advisory notes about values saved as sent that look wrong (e.g. an unrecognised country). Empty when the input is clean. */

package/docs/api/assertUpsert.md

@@ -128,6 +128,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `action` | `string` | yes | 'created' or 'updated' |
+| `company_id` | `integer \| null` | no | ID of the company that was created or updated (use it with GET/PATCH /companies/{company_id}). Null when the saved record cannot be identified unambiguously, e.g. when the domain already matched several companies in the list. |
 | `count` | `integer` | no | default `1` |
 | `custom_fields` | `CustomFieldWriteReport` | no |  |
 | `warnings` | `Array<string>` | no | Advisory notes about values saved as sent that look wrong (e.g. an unrecognised country). Empty when the input is clean. |

package/docs/api/audienceSyncs.d.ts

@@ -198,11 +198,19 @@ export interface AudienceSyncConfigResponse {
   id: number;
   is_active?: boolean;
   last_sync_at?: string | null;
+  /** Error of the last failed run, if any. */
+  last_sync_error?: string | null;
   mode?: string;
+  /** When the worker will next try this sync. */
+  next_sync_at?: string | null;
   platform: string;
   platform_audience_name?: string | null;
   refresh_cadence_hours?: number;
   status?: string | null;
+  /** Human-readable explanation of status_reason. */
+  status_detail?: string | null;
+  /** Why the sync is not delivering, or null when healthy: keyword_only (no list, keyword-only Google Search; never scheduled), list_missing (every list it uploads from was deleted), lists_partially_missing, paused, failing (last run failed), failing_never_synced (has never succeeded). */
+  status_reason?: string | null;
 }
 
 export interface AudienceSyncCreateRequest {

package/docs/api/audienceSyncs.md

@@ -79,10 +79,14 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `created_at` | `string \| null` | no |  |
 | `is_active` | `boolean` | no | default `true` |
 | `last_sync_at` | `string \| null` | no |  |
+| `last_sync_error` | `string \| null` | no | Error of the last failed run, if any. |
 | `mode` | `string` | no | default `"mirror"` |
+| `next_sync_at` | `string \| null` | no | When the worker will next try this sync. |
 | `platform_audience_name` | `string \| null` | no |  |
 | `refresh_cadence_hours` | `integer` | no | default `24` |
 | `status` | `string \| null` | no |  |
+| `status_detail` | `string \| null` | no | Human-readable explanation of status_reason. |
+| `status_reason` | `string \| null` | no | Why the sync is not delivering, or null when healthy: keyword_only (no list, keyword-only Google Search; never scheduled), list_missing (every list it uploads from was deleted), lists_partially_missing, paused, failing (last run failed), failing_never_synced (has never succeeded). |
 
 **Example**
 
@@ -160,10 +164,14 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `created_at` | `string \| null` | no |  |
 | `is_active` | `boolean` | no | default `true` |
 | `last_sync_at` | `string \| null` | no |  |
+| `last_sync_error` | `string \| null` | no | Error of the last failed run, if any. |
 | `mode` | `string` | no | default `"mirror"` |
+| `next_sync_at` | `string \| null` | no | When the worker will next try this sync. |
 | `platform_audience_name` | `string \| null` | no |  |
 | `refresh_cadence_hours` | `integer` | no | default `24` |
 | `status` | `string \| null` | no |  |
+| `status_detail` | `string \| null` | no | Human-readable explanation of status_reason. |
+| `status_reason` | `string \| null` | no | Why the sync is not delivering, or null when healthy: keyword_only (no list, keyword-only Google Search; never scheduled), list_missing (every list it uploads from was deleted), lists_partially_missing, paused, failing (last run failed), failing_never_synced (has never succeeded). |
 
 **Example**
 
@@ -203,10 +211,14 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `created_at` | `string \| null` | no |  |
 | `is_active` | `boolean` | no | default `true` |
 | `last_sync_at` | `string \| null` | no |  |
+| `last_sync_error` | `string \| null` | no | Error of the last failed run, if any. |
 | `mode` | `string` | no | default `"mirror"` |
+| `next_sync_at` | `string \| null` | no | When the worker will next try this sync. |
 | `platform_audience_name` | `string \| null` | no |  |
 | `refresh_cadence_hours` | `integer` | no | default `24` |
 | `status` | `string \| null` | no |  |
+| `status_detail` | `string \| null` | no | Human-readable explanation of status_reason. |
+| `status_reason` | `string \| null` | no | Why the sync is not delivering, or null when healthy: keyword_only (no list, keyword-only Google Search; never scheduled), list_missing (every list it uploads from was deleted), lists_partially_missing, paused, failing (last run failed), failing_never_synced (has never succeeded). |
 
 **Example**
 
@@ -382,10 +394,14 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `created_at` | `string \| null` | no |  |
 | `is_active` | `boolean` | no | default `true` |
 | `last_sync_at` | `string \| null` | no |  |
+| `last_sync_error` | `string \| null` | no | Error of the last failed run, if any. |
 | `mode` | `string` | no | default `"mirror"` |
+| `next_sync_at` | `string \| null` | no | When the worker will next try this sync. |
 | `platform_audience_name` | `string \| null` | no |  |
 | `refresh_cadence_hours` | `integer` | no | default `24` |
 | `status` | `string \| null` | no |  |
+| `status_detail` | `string \| null` | no | Human-readable explanation of status_reason. |
+| `status_reason` | `string \| null` | no | Why the sync is not delivering, or null when healthy: keyword_only (no list, keyword-only Google Search; never scheduled), list_missing (every list it uploads from was deleted), lists_partially_missing, paused, failing (last run failed), failing_never_synced (has never succeeded). |
 
 **Example**
 

package/docs/api/by-path.md

@@ -1183,6 +1183,7 @@ Every Developer API route, sorted by path, with the SDK call that reaches it. Th
 | POST | `/api/v1/enrichment/lookup/company` | [`g8.api.enrichment.lookupCompany`](enrichment.md#op-lookupcompany) or `g8.enrich.company()` | billable |
 | POST | `/api/v1/enrichment/lookup/person` | [`g8.api.enrichment.lookupPerson`](enrichment.md#op-lookupperson) or `g8.enrich.person()` | billable |
 | POST | `/api/v1/enrichment/person` | [`g8.api.enrichment.lookupPersonAlias`](enrichment.md#op-lookuppersonalias) | billable |
+| POST | `/api/v1/enrichment/preflight` | [`g8.api.enrichment.preflightEnrichment`](enrichment.md#op-preflightenrichment) | read |
 | GET | `/api/v1/enrichment/providers` | [`g8.api.enrichment.listEnrichmentProviders`](enrichment.md#op-listenrichmentproviders) | read |
 | GET | `/api/v1/enrichment/record-sync/{entity_type}/fields` | [`g8.api.enrichment.listRecordSyncFields`](enrichment.md#op-listrecordsyncfields) | read |
 | GET | `/api/v1/enrichment/record-sync/{entity_type}/history` | [`g8.api.enrichment.listRecordSyncHistory`](enrichment.md#op-listrecordsynchistory) | read |
@@ -2653,6 +2654,7 @@ Every Developer API route, sorted by path, with the SDK call that reaches it. Th
 | POST | `/api/v1/social/posts/{post_id}/publish` | [`g8.api.socialPublishing.publishSocialPost`](socialPublishing.md#op-publishsocialpost) | external |
 | POST | `/api/v1/social/posts/{post_id}/schedule` | [`g8.api.socialPublishing.scheduleSocialPost`](socialPublishing.md#op-schedulesocialpost) | external |
 | GET | `/api/v1/social/providers` | [`g8.api.socialPublishing.listSocialProviders`](socialPublishing.md#op-listsocialproviders) | read |
+| GET | `/api/v1/streams` | [`g8.api.snippet.listOrgStreams`](snippet.md#op-listorgstreams) | read |
 | POST | `/api/v1/stripe/api-key` | [`g8.api.quotes.connectStripeApiKey`](quotes.md#op-connectstripeapikey) | external |
 | GET | `/api/v1/stripe/companies/{company_id}/invoices` | [`g8.api.quotes.getCompanyStripeInvoices`](quotes.md#op-getcompanystripeinvoices) | read |
 | GET | `/api/v1/stripe/companies/{company_id}/revenue-summary` | [`g8.api.quotes.getCompanyRevenueSummary`](quotes.md#op-getcompanyrevenuesummary) | read |

package/docs/api/companies.d.ts

@@ -1320,7 +1320,7 @@ export type CompanyWorkflowType = "company_intelligence" | "stakeholder_mapping"
 export interface CreateCompanyColumnRequest {
   /** 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;
@@ -1339,15 +1339,21 @@ export interface CreateCompanyColumnRequest {
  * that is populated when the request included an `enrichment` block.
  */
 export interface CreateCompanyColumnResponse {
+  /** 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>;
 }
 
 /**

package/docs/api/companies.md

@@ -339,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. |
 
@@ -352,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**
 

package/docs/api/contacts.d.ts

@@ -852,7 +852,7 @@ export interface ContactsOperations {
       name?: string | null;
       /** Filter by job title (partial match) */
       job_title?: string | null;
-      /** 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`. */
+      /** 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. `VP` (or `Vice President`) means VP and above, so it also returns the SVP/EVP band; `SVP/EVP` alone returns only that band. Pass several levels comma-separated to match any of them, e.g. `Director,VP`. */
       seniority_level?: string | null;
       /** Filter by company name (partial match) */
       company_name?: string | null;
@@ -1716,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;
@@ -1735,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>;
 }
 
 /**

package/docs/api/contacts.md

@@ -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**
 
@@ -1884,7 +1887,7 @@ List contacts with optional filtering and pagination.
 | `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, 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.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. `VP` (or `Vice President`) means VP and above, so it also returns the SVP/EVP band; `SVP/EVP` alone returns only that band. Pass several levels comma-separated to match any of them, e.g. `Direc… |
 | `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, case-insensitive; surrounding spaces ignored). Common aliases match each other: United States = US = USA; United Kingdom = UK. |

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;