@graph8/sdk 0.295.2 → 0.303.0

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.295.2";
+export declare const SDK_VERSION = "0.303.0";
 /** Value of the `X-G8-Client` header every SDK request carries (I-13). */
-export declare const SDK_CLIENT_ID = "js-sdk/0.295.2";
+export declare const SDK_CLIENT_ID = "js-sdk/0.303.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: **3255 Developer API
+inbox, meetings, workflows and more. This SDK reaches all of it: **3264 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 3255 operations |
+| Coverage | 289 methods, reaching 258 operations | all 3264 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` (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).
+`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` (24), `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` (14), `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,9 +196,9 @@ Every operation carries a tier:
 
 | Tier | What it means | Count |
 |---|---|---|
-| `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 |
+| `read` | reads data; safe to call and to retry | 1515 |
+| `write` | creates or changes records; the SDK sends an Idempotency-Key and retries transient failures | 814 |
+| `destructive` | deletes or archives data; confirm with a human before calling | 301 |
 | `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 | 251 |
 

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 3255 operations across 141 namespaces (1510 read, 811 write, 300 destructive, 383 billable, 251 external).
+`g8.api` is generated from the published OpenAPI contract, so it covers all 3264 operations across 141 namespaces (1515 read, 814 write, 301 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).
@@ -104,7 +104,7 @@
 | `g8.api.newsletter` | Newsletter | 61 | 15 | [newsletter.md](newsletter.md) | [newsletter.d.ts](newsletter.d.ts) |
 | `g8.api.notes` | Notes | 19 | 8 | [notes.md](notes.md) | [notes.d.ts](notes.d.ts) |
 | `g8.api.notifications` | Notifications | 2 | none | [notifications.md](notifications.md) | [notifications.d.ts](notifications.d.ts) |
-| `g8.api.objects` | Objects | 18 | 18 | [objects.md](objects.md) | [objects.d.ts](objects.d.ts) |
+| `g8.api.objects` | Objects | 24 | 18 | [objects.md](objects.md) | [objects.d.ts](objects.d.ts) |
 | `g8.api.openSearch` | OpenSearch | 4 | none | [openSearch.md](openSearch.md) | [openSearch.d.ts](openSearch.d.ts) |
 | `g8.api.ops` | Ops (internal, cross-tenant, read-only) | 5 | none | [ops.md](ops.md) | [ops.d.ts](ops.d.ts) |
 | `g8.api.orgGovernance` | Org Governance | 17 | none | [orgGovernance.md](orgGovernance.md) | [orgGovernance.d.ts](orgGovernance.d.ts) |
@@ -137,7 +137,7 @@
 | `g8.api.scraping` | Scraping | 10 | none | [scraping.md](scraping.md) | [scraping.d.ts](scraping.d.ts) |
 | `g8.api.sdrAnalytics` | SDR Analytics | 5 | none | [sdrAnalytics.md](sdrAnalytics.md) | [sdrAnalytics.d.ts](sdrAnalytics.d.ts) |
 | `g8.api.search` | Search | 19 | 4 | [search.md](search.md) | [search.d.ts](search.d.ts) |
-| `g8.api.seo` | SEO | 11 | none | [seo.md](seo.md) | [seo.d.ts](seo.d.ts) |
+| `g8.api.seo` | SEO | 14 | none | [seo.md](seo.md) | [seo.d.ts](seo.d.ts) |
 | `g8.api.sequenceLifecycle` | Sequence Lifecycle | 8 | 6 | [sequenceLifecycle.md](sequenceLifecycle.md) | [sequenceLifecycle.d.ts](sequenceLifecycle.d.ts) |
 | `g8.api.sequences` | Sequences | 71 | 6 | [sequences.md](sequences.md) | [sequences.d.ts](sequences.d.ts) |
 | `g8.api.settings` | Settings | 18 | none | [settings.md](settings.md) | [settings.d.ts](settings.d.ts) |

package/docs/api/by-path.md

@@ -2024,13 +2024,19 @@ Every Developer API route, sorted by path, with the SDK call that reaches it. Th
 | PATCH | `/api/v1/objects/{object_slug}/attributes/{attr_slug}` | [`g8.api.objects.updateAttribute`](objects.md#op-updateattribute) or `g8.objects.updateAttribute()` | write |
 | GET | `/api/v1/objects/{object_slug}/records` | [`g8.api.objects.listObjectRecords`](objects.md#op-listobjectrecords) or `g8.objects.listRecords()` | read |
 | POST | `/api/v1/objects/{object_slug}/records` | [`g8.api.objects.createObjectRecord`](objects.md#op-createobjectrecord) or `g8.objects.createRecord()` | write |
+| PATCH | `/api/v1/objects/{object_slug}/records/bulk` | [`g8.api.objects.bulkUpdateObjectRecords`](objects.md#op-bulkupdateobjectrecords) | write |
+| POST | `/api/v1/objects/{object_slug}/records/merge` | [`g8.api.objects.mergeObjectRecords`](objects.md#op-mergeobjectrecords) | write |
 | POST | `/api/v1/objects/{object_slug}/records/upsert` | [`g8.api.objects.upsertObjectRecord`](objects.md#op-upsertobjectrecord) or `g8.objects.upsertRecord()` | write |
 | DELETE | `/api/v1/objects/{object_slug}/records/{record_id}` | [`g8.api.objects.archiveObjectRecord`](objects.md#op-archiveobjectrecord) or `g8.objects.archiveRecord()` | destructive |
 | GET | `/api/v1/objects/{object_slug}/records/{record_id}` | [`g8.api.objects.getObjectRecord`](objects.md#op-getobjectrecord) or `g8.objects.getRecord()` | read |
 | PATCH | `/api/v1/objects/{object_slug}/records/{record_id}` | [`g8.api.objects.updateObjectRecord`](objects.md#op-updateobjectrecord) or `g8.objects.updateRecord()` | write |
 | GET | `/api/v1/objects/{object_slug}/records/{record_id}/changes` | [`g8.api.objects.getObjectRecordChanges`](objects.md#op-getobjectrecordchanges) or `g8.objects.changes()` | read |
 | GET | `/api/v1/objects/{object_slug}/records/{record_id}/history` | [`g8.api.objects.getObjectRecordHistory`](objects.md#op-getobjectrecordhistory) or `g8.objects.history()` | read |
+| GET | `/api/v1/objects/{object_slug}/records/{record_id}/relationships` | [`g8.api.objects.getObjectRelationships`](objects.md#op-getobjectrelationships) | read |
+| POST | `/api/v1/objects/{object_slug}/records/{record_id}/relationships` | [`g8.api.objects.createObjectRelationship`](objects.md#op-createobjectrelationship) | write |
+| DELETE | `/api/v1/objects/{object_slug}/records/{record_id}/relationships/{relationship_id}` | [`g8.api.objects.deleteObjectRelationship`](objects.md#op-deleteobjectrelationship) | destructive |
 | POST | `/api/v1/objects/{object_slug}/records/{record_id}/restore` | [`g8.api.objects.restoreObjectRecord`](objects.md#op-restoreobjectrecord) or `g8.objects.restoreRecord()` | write |
+| GET | `/api/v1/objects/{object_slug}/relationships` | [`g8.api.objects.getObjectRelationshipDefinitions`](objects.md#op-getobjectrelationshipdefinitions) | read |
 | POST | `/api/v1/opensearch/aggregate` | [`g8.api.openSearch.opensearchAggregate`](openSearch.md#op-opensearchaggregate) | write |
 | POST | `/api/v1/opensearch/count` | [`g8.api.openSearch.opensearchCount`](openSearch.md#op-opensearchcount) | write |
 | POST | `/api/v1/opensearch/resolve` | [`g8.api.openSearch.opensearchResolve`](openSearch.md#op-opensearchresolve) | write |
@@ -2466,6 +2472,9 @@ Every Developer API route, sorted by path, with the SDK call that reaches it. Th
 | POST | `/api/v1/seo/audits` | [`g8.api.seo.startSeoAudit`](seo.md#op-startseoaudit) | billable |
 | GET | `/api/v1/seo/audits/{audit_id}` | [`g8.api.seo.getSeoAudit`](seo.md#op-getseoaudit) | read |
 | GET | `/api/v1/seo/audits/{audit_id}/issues` | [`g8.api.seo.getSeoAuditIssues`](seo.md#op-getseoauditissues) | read |
+| GET | `/api/v1/seo/domains/tracked` | [`g8.api.seo.listSeoTrackedDomains`](seo.md#op-listseotrackeddomains) | read |
+| GET | `/api/v1/seo/domains/tracked/{domain}` | [`g8.api.seo.getSeoTrackedDomain`](seo.md#op-getseotrackeddomain) | read |
+| GET | `/api/v1/seo/domains/tracked/{domain}/pages` | [`g8.api.seo.listSeoDomainPages`](seo.md#op-listseodomainpages) | read |
 | GET | `/api/v1/seo/domains/{domain}/backlinks` | [`g8.api.seo.getSeoDomainBacklinks`](seo.md#op-getseodomainbacklinks) | billable |
 | GET | `/api/v1/seo/domains/{domain}/overview` | [`g8.api.seo.getSeoDomainOverview`](seo.md#op-getseodomainoverview) | billable |
 | POST | `/api/v1/seo/keywords/research` | [`g8.api.seo.researchSeoKeywords`](seo.md#op-researchseokeywords) | billable |

package/docs/api/companies.d.ts

@@ -1074,6 +1074,13 @@ export interface Column {
   id?: number | null;
   /** Automatically computed: True if object_id is None/empty, False otherwise. */
   is_global: boolean;
+  /**
+   * Human-readable display name (CF-09), e.g. ``CONTACT_FIRST_NAME`` ->
+   * "First name", ``COMPANY_NAICS`` -> "Company NAICS". Custom columns keep
+   * their own title. Additive and read-only: ``name`` / ``title`` stay the
+   * storage key, because callers send them back as identifiers.
+   */
+  label: string | null;
   name?: string | null;
   object_id?: string | null;
   source?: ColumnSource;

package/docs/api/companies.md

@@ -1479,6 +1479,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `is_global` | `boolean` | yes | Automatically computed: True if object_id is None/empty, False otherwise. |
+| `label` | `string \| null` | yes | Human-readable display name (CF-09), e.g. ``CONTACT_FIRST_NAME`` -> "First name", ``COMPANY_NAICS`` -> "Company NAICS". Custom columns keep their own title. Additive and read-only: ``name`` / ``title`` stay the storage key, because callers send them back as identifiers. |
 | `title` | `string` | yes |  |
 | `data_type` | `ColumnType` | no | default `"text"` |
 | `id` | `integer \| null` | no |  |

package/docs/api/contacts.d.ts

@@ -1422,6 +1422,13 @@ export interface Column {
   id?: number | null;
   /** Automatically computed: True if object_id is None/empty, False otherwise. */
   is_global: boolean;
+  /**
+   * Human-readable display name (CF-09), e.g. ``CONTACT_FIRST_NAME`` ->
+   * "First name", ``COMPANY_NAICS`` -> "Company NAICS". Custom columns keep
+   * their own title. Additive and read-only: ``name`` / ``title`` stay the
+   * storage key, because callers send them back as identifiers.
+   */
+  label: string | null;
   name?: string | null;
   object_id?: string | null;
   source?: ColumnSource;

package/docs/api/contacts.md

@@ -1772,6 +1772,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `is_global` | `boolean` | yes | Automatically computed: True if object_id is None/empty, False otherwise. |
+| `label` | `string \| null` | yes | Human-readable display name (CF-09), e.g. ``CONTACT_FIRST_NAME`` -> "First name", ``COMPANY_NAICS`` -> "Company NAICS". Custom columns keep their own title. Additive and read-only: ``name`` / ``title`` stay the storage key, because callers send them back as identifiers. |
 | `title` | `string` | yes |  |
 | `data_type` | `ColumnType` | no | default `"text"` |
 | `id` | `integer \| null` | no |  |

package/docs/api/enrichment.d.ts

@@ -2618,16 +2618,24 @@ export interface EnrichmentPreflightResponse {
   contact_count: number;
   /** Contact IDs that will be enriched: duplicates removed, order kept */
   contact_ids: Array<number>;
+  /** Waterfall only: the most one contact can cost, in graph8 credits. A record is charged its dearest graph8-funded step that finds a value (steps are not added together); steps on your own key cost 0. Null when the pipeline could not be priced. */
+  credits_per_record?: number | null;
   /** How many repeated contact IDs were dropped */
   duplicates_removed?: number;
   list_id: number;
   list_name?: string | null;
+  /** Waterfall only: priced_records x credits_per_record, the most this run can charge. Records the pipeline skips (values already present, run conditions) cost less. Null when not priced. */
+  max_total_credits?: number | 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>;
+  /** column_id of the saved waterfall pipeline the run would reuse. Null when the run would create a new pipeline (it is created on confirm) or in 'ai-research' mode. Pass it to POST /enrichment/waterfall/validate-credits for the record-exact quote. */
+  pipeline_column_id?: string | null;
+  /** Waterfall only: contacts the price covers (unique contacts that are on the list). */
+  priced_records?: number | null;
   /** Providers that would run, in order (empty = the saved pipeline) */
   providers?: Array<string>;
   providers_detail?: Array<ProviderStepDetail>;

package/docs/api/enrichment.md

@@ -3312,10 +3312,14 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `contact_ids` | `Array<integer>` | yes | Contact IDs that will be enriched: duplicates removed, order kept |
 | `list_id` | `integer` | yes |  |
 | `mode` | `string` | yes | Resolved mode: 'waterfall' or 'ai-research' |
+| `credits_per_record` | `integer \| null` | no | Waterfall only: the most one contact can cost, in graph8 credits. A record is charged its dearest graph8-funded step that finds a value (steps are not added together); steps on your own key cost 0. Null when the pipeline could not be priced. |
 | `duplicates_removed` | `integer` | no | How many repeated contact IDs were dropped default `0` |
 | `list_name` | `string \| null` | no |  |
+| `max_total_credits` | `integer \| null` | no | Waterfall only: priced_records x credits_per_record, the most this run can charge. Records the pipeline skips (values already present, run conditions) cost less. Null when not priced. |
 | `missing_credentials` | `Array<string>` | no | Providers whose step would be skipped because the org has no key for them |
 | `not_in_list` | `Array<integer>` | no | Contact IDs that are not on the list; the run skips them and does not charge for them |
+| `pipeline_column_id` | `string \| null` | no | column_id of the saved waterfall pipeline the run would reuse. Null when the run would create a new pipeline (it is created on confirm) or in 'ai-research' mode. Pass it to POST /enrichment/waterfall/validate-credits for the record-exact quote. |
+| `priced_records` | `integer \| null` | no | Waterfall only: contacts the price covers (unique contacts that are on the list). |
 | `providers` | `Array<string>` | no | Providers that would run, in order (empty = the saved pipeline) |
 | `providers_detail` | `Array<ProviderStepDetail>` | no |  |
 | `target_field` | `string \| null` | no | Canonical column for target_field, when given |

package/docs/api/lists.d.ts

@@ -469,6 +469,8 @@ export interface ListsOperations {
       page?: number;
       /** Items per page (max 200) */
       limit?: number;
+      /** Case-insensitive substring match on the list title. Omit for every list. */
+      search?: string | null;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -1016,6 +1018,10 @@ export interface ListResponse {
   /** Source of the list */
   source?: string | null;
   status?: string | null;
+  /** Human-readable explanation of status_reason. */
+  status_detail?: string | null;
+  /** Why the list is not usable, or null when it is fine: 'import_failed' (a file import raised; status_detail carries the reason when known), 'import_not_finished' (an uploaded list still processing with no records an hour after it was created: the import never ran) or 'build_failed' (a list built another way, e.g. from Search, failed; re-run it from its source). */
+  status_reason?: string | null;
   tags?: Array<string>;
   title: string;
   total?: number;

package/docs/api/lists.md

@@ -1063,7 +1063,7 @@ const result = await g8.api.lists.listListFolders();
 - API-key scope: `lists:read`
 - ★ Hand-written: [`g8.lists.list()`](../sdk-clients.md#g8-lists-list)
 
-List all lists (audiences) in the organization.
+List all lists (audiences) in the organization, optionally filtered by title.
 
 **Input**
 
@@ -1071,6 +1071,7 @@ List all lists (audiences) in the organization.
 |---|---|---|---|
 | `query.page` | `integer` | no | Page number (1-indexed) default `1` |
 | `query.limit` | `integer` | no | Items per page (max 200) default `50` |
+| `query.search` | `string \| null` | no | Case-insensitive substring match on the list title. Omit for every list. |
 
 **Returns** `ApiResponse_list_ListResponse__`: the envelope `{ data: Array<ListResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -1090,6 +1091,8 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `is_dynamic` | `boolean` | no | default `false` |
 | `source` | `string \| null` | no | Source of the list |
 | `status` | `string \| null` | no |  |
+| `status_detail` | `string \| null` | no | Human-readable explanation of status_reason. |
+| `status_reason` | `string \| null` | no | Why the list is not usable, or null when it is fine: 'import_failed' (a file import raised; status_detail carries the reason when known), 'import_not_finished' (an uploaded list still processing with no records an hour after it was created: the import never ran) or 'build_failed' (a list built another way, e.g. from Search, failed; re-run it from its source). |
 | `tags` | `Array<string>` | no |  |
 | `total` | `integer` | no | default `0` |
 | `type` | `string \| null` | no | List type (contacts, companies, suppressions, deals, leads) |
@@ -1504,6 +1507,8 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `is_dynamic` | `boolean` | no | default `false` |
 | `source` | `string \| null` | no | Source of the list |
 | `status` | `string \| null` | no |  |
+| `status_detail` | `string \| null` | no | Human-readable explanation of status_reason. |
+| `status_reason` | `string \| null` | no | Why the list is not usable, or null when it is fine: 'import_failed' (a file import raised; status_detail carries the reason when known), 'import_not_finished' (an uploaded list still processing with no records an hour after it was created: the import never ran) or 'build_failed' (a list built another way, e.g. from Search, failed; re-run it from its source). |
 | `tags` | `Array<string>` | no |  |
 | `total` | `integer` | no | default `0` |
 | `type` | `string \| null` | no | List type (contacts, companies, suppressions, deals, leads) |

package/docs/api/objects.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.objects` (Objects): 18 operations.
+ * Types for `g8.api.objects` (Objects): 24 operations.
  *
  * For reading. In code, import from the package instead:
  *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
@@ -16,16 +16,22 @@ export interface ObjectsMembers {
   archiveAttribute: "archive_attribute_objects__object_slug__attributes__attr_slug__delete";
   archiveObject: "archive_object_objects__object_slug__delete";
   archiveObjectRecord: "archive_object_record_objects__object_slug__records__record_id__delete";
+  bulkUpdateObjectRecords: "bulk_update_object_records_objects__object_slug__records_bulk_patch";
   createAttribute: "create_attribute_objects__object_slug__attributes_post";
   createObject: "create_object_objects_post";
   createObjectRecord: "create_object_record_objects__object_slug__records_post";
+  createObjectRelationship: "create_object_relationship_objects__object_slug__records__record_id__relationships_post";
+  deleteObjectRelationship: "delete_object_relationship_objects__object_slug__records__record_id__relationships__relationship_id__delete";
   getObject: "get_object_objects__object_slug__get";
   getObjectRecord: "get_object_record_objects__object_slug__records__record_id__get";
   getObjectRecordChanges: "get_object_record_changes_objects__object_slug__records__record_id__changes_get";
   getObjectRecordHistory: "get_object_record_history_objects__object_slug__records__record_id__history_get";
+  getObjectRelationshipDefinitions: "get_object_relationship_definitions_objects__object_slug__relationships_get";
+  getObjectRelationships: "get_object_relationships_objects__object_slug__records__record_id__relationships_get";
   listObjectAttributes: "list_object_attributes_objects__object_slug__attributes_get";
   listObjectRecords: "list_object_records_objects__object_slug__records_get";
   listObjects: "list_objects_objects_get";
+  mergeObjectRecords: "merge_object_records_objects__object_slug__records_merge_post";
   restoreObjectRecord: "restore_object_record_objects__object_slug__records__record_id__restore_post";
   updateAttribute: "update_attribute_objects__object_slug__attributes__attr_slug__patch";
   updateObject: "update_object_objects__object_slug__patch";
@@ -85,6 +91,23 @@ export interface ObjectsOperations {
   };
     output: ApiResponse_ObjectRecordResponse_;
   };
+  /**
+   * PATCH /objects/{object_slug}/records/bulk
+   * Bulk Update Object Records
+   * tier: write · scope: objects:write
+   */
+  bulk_update_object_records_objects__object_slug__records_bulk_patch: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordBulkUpdate;
+  };
+    output: ApiResponse_RecordBulkUpdateResponse_;
+  };
   /**
    * POST /objects/{object_slug}/attributes
    * Create Attribute
@@ -133,6 +156,43 @@ export interface ObjectsOperations {
   };
     output: ApiResponse_ObjectRecordResponse_;
   };
+  /**
+   * POST /objects/{object_slug}/records/{record_id}/relationships
+   * Create Object Relationship
+   * tier: write · scope: objects:write
+   */
+  create_object_relationship_objects__object_slug__records__record_id__relationships_post: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RelationshipCreate;
+  };
+    output: ApiResponse_RelationshipResponse_;
+  };
+  /**
+   * DELETE /objects/{object_slug}/records/{record_id}/relationships/{relationship_id}
+   * Delete Object Relationship
+   * tier: destructive · scope: objects:write
+   */
+  delete_object_relationship_objects__object_slug__records__record_id__relationships__relationship_id__delete: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+      relationship_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RelationshipCreate;
+  };
+    output: ApiResponse_RelationshipResponse_;
+  };
   /**
    * GET /objects/{object_slug}
    * Get Object
@@ -208,6 +268,47 @@ export interface ObjectsOperations {
   };
     output: ApiResponse_RecordHistoryResponse_;
   };
+  /**
+   * GET /objects/{object_slug}/relationships
+   * Get Object Relationship Definitions
+   * tier: read · scope: objects:read
+   */
+  get_object_relationship_definitions_objects__object_slug__relationships_get: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    query?: {
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RelationshipDefinitionListResponse_;
+  };
+  /**
+   * GET /objects/{object_slug}/records/{record_id}/relationships
+   * Get Object Relationships
+   * tier: read · scope: objects:read
+   */
+  get_object_relationships_objects__object_slug__records__record_id__relationships_get: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    query?: {
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RecordRelationshipsResponse_;
+  };
   /**
    * GET /objects/{object_slug}/attributes
    * List Object Attributes
@@ -267,6 +368,23 @@ export interface ObjectsOperations {
   };
     output: ApiResponse_list_ObjectDefinitionResponse__;
   };
+  /**
+   * POST /objects/{object_slug}/records/merge
+   * Merge Object Records
+   * tier: write · scope: objects:write
+   */
+  merge_object_records_objects__object_slug__records_merge_post: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordMergeRequest;
+  };
+    output: ApiResponse_RecordMergeResponse_;
+  };
   /**
    * POST /objects/{object_slug}/records/{record_id}/restore
    * Restore Object Record
@@ -356,7 +474,7 @@ export interface ObjectsOperations {
   };
 }
 
-// 26 schemas referenced above (the same as G8Contract.<Name>).
+// 46 schemas referenced above (the same as G8Contract.<Name>).
 
 export interface ApiResponse_AttributeDefinitionResponse_ {
   data: AttributeDefinitionResponse;
@@ -373,16 +491,41 @@ export interface ApiResponse_ObjectRecordResponse_ {
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_RecordBulkUpdateResponse_ {
+  data: RecordBulkUpdateResponse;
+  pagination?: PaginationMeta | null;
+}
+
 export interface ApiResponse_RecordHistoryResponse_ {
   data: RecordHistoryResponse;
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_RecordMergeResponse_ {
+  data: RecordMergeResponse;
+  pagination?: PaginationMeta | null;
+}
+
 export interface ApiResponse_RecordMutationsResponse_ {
   data: RecordMutationsResponse;
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_RecordRelationshipsResponse_ {
+  data: RecordRelationshipsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_RelationshipDefinitionListResponse_ {
+  data: RelationshipDefinitionListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_RelationshipResponse_ {
+  data: RelationshipResponse;
+  pagination?: PaginationMeta | null;
+}
+
 export interface ApiResponse_list_AttributeDefinitionResponse__ {
   data: Array<AttributeDefinitionResponse>;
   pagination?: PaginationMeta | null;
@@ -539,6 +682,42 @@ export interface PaginationMeta {
   total_is_lower_bound?: boolean | null;
 }
 
+/**
+ * Bulk-update body: exactly one scope (explicit ids or a filtered set),
+ * plus the values to apply to every record in that scope.
+ *
+ * ``record_ids`` is capped at 500 to bound the transaction. ``filters`` reuses
+ * this router's own ``RecordFilter`` shape; a filtered scope is resolved
+ * entirely server-side (ordered by record id, at most 500 per call) and the
+ * ids it resolves are never trusted from the client. ``after_record_id``
+ * continues a filtered scope that the previous call reported as truncated.
+ */
+export interface RecordBulkUpdate {
+  after_record_id?: string | null;
+  filters?: Array<RecordFilter> | null;
+  record_ids?: Array<string> | null;
+  values?: Record<string, unknown>;
+}
+
+export interface RecordBulkUpdateFailure {
+  error: string;
+  id: string;
+}
+
+export interface RecordBulkUpdateResponse {
+  failed: Array<RecordBulkUpdateFailure>;
+  next_after_record_id?: string | null;
+  succeeded: Array<string>;
+  truncated?: boolean;
+}
+
+/** Filter parameters for listing records. */
+export interface RecordFilter {
+  attribute_slug: string;
+  operator: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "contains" | "starts_with" | "is_null" | "is_not_null";
+  value?: unknown | null;
+}
+
 /**
  * One generation of one attribute's value.
  *
@@ -566,6 +745,37 @@ export interface RecordHistoryResponse {
   record_id: string;
 }
 
+export interface RecordMergeCascade {
+  associations_deleted: number;
+  associations_repointed: number;
+  relationships_deleted: number;
+  relationships_repointed: number;
+}
+
+export interface RecordMergeFieldOverride {
+  attribute_slug: string;
+  winner: "primary" | "secondary";
+}
+
+/**
+ * Merge ``secondary_record_id`` into ``primary_record_id``. The primary's
+ * graph8 identity (id, legacy_id/legacy_type) is preserved; the secondary is
+ * archived, never hard-deleted.
+ */
+export interface RecordMergeRequest {
+  expected_primary_revision?: number | null;
+  expected_secondary_revision?: number | null;
+  field_overrides?: Array<RecordMergeFieldOverride>;
+  primary_record_id: string;
+  secondary_record_id: string;
+}
+
+export interface RecordMergeResponse {
+  cascade: RecordMergeCascade;
+  merge_history_id: string;
+  record: RecordResponse;
+}
+
 export interface RecordMutationEntry {
   action: "created" | "updated" | "archived" | "restored";
   actor_id: string | null;
@@ -594,6 +804,24 @@ export interface RecordMutationsResponse {
   record_id: string;
 }
 
+export interface RecordRelationshipsResponse {
+  /** Next visible page offset; null at the end */
+  next_offset: number | null;
+  relationships: Array<RelatedRecordEdge>;
+}
+
+/** Response for a record with its current attribute values. */
+export interface RecordResponse {
+  created_at: string;
+  id: string;
+  is_archived: boolean;
+  object_definition_id: string;
+  organization_id: string;
+  revision?: number;
+  updated_at: string;
+  values: Record<string, unknown>;
+}
+
 export interface RecordUpdateRequest {
   /** Append canonical non-duplicate values to multivalue fields. Fields must not overlap values or remove_values. */
   append_values?: Record<string, Array<unknown>>;
@@ -625,3 +853,61 @@ export interface RecordWriteRequest {
   /** Attribute values keyed by slug. Call `GET /objects/{object_slug}/attributes` for active fields. Canonical contacts and companies retain CONTACT_*, COMPANY_* and udo_* field names. Unknown keys are rejected with 422. PATCH preserves omitted fields; required fields cannot be cleared with null or an empty multivalue list. Record references must resolve to active records of their configured target object in the same organization and app. */
   values?: Record<string, unknown>;
 }
+
+export interface RelatedRecordEdge {
+  can_unlink: boolean;
+  definition_id: string;
+  definition_revision: number;
+  id: string;
+  relationship_label: string;
+  source_kind: "custom" | "contacts" | "companies" | "deals";
+  source_label: string | null;
+  source_object_slug: string;
+  source_record_id: string;
+  source_revision: number;
+  target_kind: "custom" | "contacts" | "companies" | "deals";
+  target_label: string | null;
+  target_object_slug: string;
+  target_record_id: string;
+  target_revision: number;
+}
+
+export interface RelationshipCreate {
+  definition_id: string;
+  expected_definition_revision: number;
+  expected_source_revision: number;
+  expected_target_revision: number;
+  target_record_id: string;
+}
+
+export interface RelationshipDefinitionListResponse {
+  relationships: Array<RelationshipDefinitionResponse>;
+  total: number;
+}
+
+export interface RelationshipDefinitionResponse {
+  api_slug: string;
+  created_at: string;
+  id: string;
+  is_archived: boolean;
+  revision: number;
+  source_kind: string;
+  source_label: string;
+  source_many: boolean;
+  source_object_definition_id: string | null;
+  target_kind: string;
+  target_label: string;
+  target_many: boolean;
+  target_object_definition_id: string | null;
+}
+
+export interface RelationshipResponse {
+  definition_id: string;
+  id: string;
+  source_kind: string;
+  source_record_id: string;
+  source_revision: number;
+  target_kind: string;
+  target_record_id: string;
+  target_revision: number;
+}