@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/assertUpsert.d.ts

@@ -0,0 +1,286 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.assertUpsert` (Assert / Upsert): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"assert_companies_batch_companies_assert_batch_put">;
+ *
+ * Reference with examples: assertUpsert.md
+ */
+/* eslint-disable */
+
+/** `g8.api.assertUpsert.<member>` -> the operationId it calls. */
+export interface AssertUpsertMembers {
+  assertCompaniesBatch: "assert_companies_batch_companies_assert_batch_put";
+  assertCompany: "assert_company_companies_assert_put";
+  assertContact: "assert_contact_contacts_assert_put";
+  assertContactsBatch: "assert_contacts_batch_contacts_assert_batch_put";
+  assertDeal: "assert_deal_deals_assert_put";
+  assertDealContact: "assert_deal_contact_contacts__contact_id__deals_assert_put";
+}
+
+/** Input and output of every `g8.api.assertUpsert` operation, keyed by operationId. */
+export interface AssertUpsertOperations {
+  /**
+   * PUT /companies/assert/batch
+   * Assert Companies Batch
+   * tier: write · scope: contacts:write
+   */
+  assert_companies_batch_companies_assert_batch_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BatchCompanyAssertRequest;
+  };
+    output: ApiResponse_BatchAssertResponse_;
+  };
+  /**
+   * PUT /companies/assert
+   * Assert Company
+   * tier: write · scope: contacts:write
+   */
+  assert_company_companies_assert_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CompanyAssertRequest;
+  };
+    output: ApiResponse_CompanyAssertResponse_;
+  };
+  /**
+   * PUT /contacts/assert
+   * Assert Contact
+   * tier: write · scope: contacts:write
+   */
+  assert_contact_contacts_assert_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactAssertRequest;
+  };
+    output: ApiResponse_ContactAssertResponse_;
+  };
+  /**
+   * PUT /contacts/assert/batch
+   * Assert Contacts Batch
+   * tier: write · scope: contacts:write
+   */
+  assert_contacts_batch_contacts_assert_batch_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BatchContactAssertRequest;
+  };
+    output: ApiResponse_BatchAssertResponse_;
+  };
+  /**
+   * PUT /deals/assert
+   * Assert Deal
+   * tier: write · scope: contacts:write
+   */
+  assert_deal_deals_assert_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealAssertRequest;
+  };
+    output: ApiResponse_DealAssertResponse_;
+  };
+  /**
+   * PUT /contacts/{contact_id}/deals/assert
+   * Assert Deal Contact
+   * tier: write · scope: contacts:write
+   */
+  assert_deal_contact_contacts__contact_id__deals_assert_put: {
+    input: {
+    path: {
+      /** Contact ID */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealContactAssertRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+}
+
+// 17 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_BatchAssertResponse_ {
+  data: BatchAssertResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CompanyAssertResponse_ {
+  data: CompanyAssertResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ContactAssertResponse_ {
+  data: ContactAssertResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealAssertResponse_ {
+  data: DealAssertResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface BatchAssertResponse {
+  created?: number;
+  custom_fields?: CustomFieldWriteReport;
+  errors?: Array<Record<string, unknown>>;
+  total: number;
+  updated?: number;
+}
+
+export interface BatchCompanyAssertRequest {
+  /** Up to 100 companies with domain or linkedin_url */
+  companies: Array<Record<string, unknown>>;
+  /** When true, any key in `custom_fields` that matches no existing column is created as a NEW list-scoped custom column (max 100 per request) and then written. Default false preserves the previous behaviour of not creating columns implicitly. */
+  create_missing_fields?: boolean;
+  /** Target list ID */
+  list_id: number;
+}
+
+export interface BatchContactAssertRequest {
+  /** Up to 100 contacts with work_email or linkedin_url */
+  contacts: Array<Record<string, unknown>>;
+  /** When true, any key in `custom_fields` that matches no existing column is created as a NEW list-scoped custom column (max 100 per request) and then written. Default false preserves the previous behaviour of not creating columns implicitly. */
+  create_missing_fields?: boolean;
+  /** Target list ID */
+  list_id: number;
+}
+
+export interface CompanyAssertRequest {
+  annual_revenue?: string | null;
+  city?: string | null;
+  country?: string | null;
+  /** When true, any key in `custom_fields` that matches no existing column is created as a NEW list-scoped custom column (max 100 per request) and then written. Default false preserves the previous behaviour of not creating columns implicitly. */
+  create_missing_fields?: boolean;
+  /** Custom column values to write on this record, keyed by the column's display title (e.g. 'Followup 1'), its slug (e.g. 'udo_followup_1_ab12cd34'), or a case/space variant of the title. Keys that match no existing column are reported back in `ignored_fields` unless `create_missing_fields` is true. */
+  custom_fields?: (Record<string, string | null>) | null;
+  description?: string | null;
+  /** Company domain (primary match key) */
+  domain?: string | null;
+  employee_count?: number | null;
+  industry?: string | null;
+  /** LinkedIn URL (fallback match key) */
+  linkedin_url?: string | null;
+  /** Target list ID */
+  list_id: number;
+  name?: string | null;
+  state?: string | null;
+  website?: string | null;
+}
+
+export interface CompanyAssertResponse {
+  /** 'created' or 'updated' */
+  action: string;
+  count?: number;
+  custom_fields?: CustomFieldWriteReport;
+}
+
+export interface ContactAssertRequest {
+  city?: string | null;
+  company_domain?: string | null;
+  country?: string | null;
+  /** When true, any key in `custom_fields` that matches no existing column is created as a NEW list-scoped custom column (max 100 per request) and then written. Default false preserves the previous behaviour of not creating columns implicitly. */
+  create_missing_fields?: boolean;
+  /** Custom column values to write on this record, keyed by the column's display title (e.g. 'Followup 1'), its slug (e.g. 'udo_followup_1_ab12cd34'), or a case/space variant of the title. Keys that match no existing column are reported back in `ignored_fields` unless `create_missing_fields` is true. */
+  custom_fields?: (Record<string, string | null>) | null;
+  direct_phone?: string | null;
+  first_name?: string | null;
+  job_department?: string | null;
+  job_title?: string | null;
+  last_name?: string | null;
+  /** LinkedIn URL (fallback match key) */
+  linkedin_url?: string | null;
+  /** Target list ID */
+  list_id: number;
+  mobile_phone?: string | null;
+  personal_emails?: string | null;
+  seniority_level?: string | null;
+  state?: string | null;
+  /** Work email (primary match key) */
+  work_email?: string | null;
+}
+
+export interface ContactAssertResponse {
+  /** 'created' or 'updated' */
+  action: string;
+  count?: number;
+  custom_fields?: CustomFieldWriteReport;
+}
+
+/**
+ * How a write path handled the request's custom (dynamic) column keys.
+ *
+ * Shared by every Developer API write surface that accepts custom columns
+ * (``POST /contacts``, ``PUT /contacts/assert[/batch]``,
+ * ``PUT /companies/assert[/batch]``).
+ *
+ * Every field defaults to empty, so a client that ignores this object sees no
+ * behavioural change. It exists because these keys were previously dropped
+ * with NO caller-visible signal — the only trace was a server-side
+ * ``logger.warning`` in ``append_to_audience``.
+ */
+export interface CustomFieldWriteReport {
+  /** Caller keys for which a NEW custom column was created by this request. */
+  created?: Array<string>;
+  /** Caller keys that matched no custom column and were NOT written. Create the column first (POST /fields) or pass create_missing_fields=true. */
+  ignored?: Array<string>;
+  /** Caller keys that resolved to a custom column and were written. */
+  written?: Array<string>;
+}
+
+export interface DealAssertRequest {
+  amount?: number | null;
+  close_date?: string | null;
+  /** Company ID (match key, combined with name) */
+  company_id?: string | null;
+  currency?: string | null;
+  description?: string | null;
+  /** Deal name (match key) */
+  name: string;
+  pipeline_id?: string | null;
+  stage_id?: string | null;
+}
+
+export interface DealAssertResponse {
+  /** 'created' or 'updated' */
+  action: string;
+  deal_id: string;
+}
+
+export interface DealContactAssertRequest {
+  /** Deal ID to associate */
+  deal_id: string;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  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;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}

package/docs/api/assertUpsert.md

@@ -0,0 +1,370 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.assertUpsert`: Assert / Upsert
+
+6 operations (6 write).
+
+1 of these also have a hand-written method (`g8.contacts`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [assertUpsert.d.ts](assertUpsert.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`assertCompaniesBatch`](#op-assertcompaniesbatch) | `PUT /api/v1/companies/assert/batch` | write | `contacts:write` | Assert Companies Batch |
+| [`assertCompany`](#op-assertcompany) | `PUT /api/v1/companies/assert` | write | `contacts:write` | Assert Company |
+| [`assertContact`](#op-assertcontact) ★ | `PUT /api/v1/contacts/assert` | write | `contacts:write` | Assert Contact |
+| [`assertContactsBatch`](#op-assertcontactsbatch) | `PUT /api/v1/contacts/assert/batch` | write | `contacts:write` | Assert Contacts Batch |
+| [`assertDeal`](#op-assertdeal) | `PUT /api/v1/deals/assert` | write | `contacts:write` | Assert Deal |
+| [`assertDealContact`](#op-assertdealcontact) | `PUT /api/v1/contacts/{contact_id}/deals/assert` | write | `contacts:write` | Assert Deal Contact |
+
+---
+
+<a id="op-assertcompaniesbatch"></a>
+
+### `g8.api.assertUpsert.assertCompaniesBatch(input)`
+
+**Assert Companies Batch**
+
+- HTTP: `PUT /api/v1/companies/assert/batch`
+- operationId: `assert_companies_batch_companies_assert_batch_put` (also callable as `g8.api.call("assert_companies_batch_companies_assert_batch_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Batch create or update up to 100 companies. Matches by domain, then linkedin_url.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BatchCompanyAssertRequest` | yes | Request body; fields below. |
+
+Body fields (`BatchCompanyAssertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.companies` | `Array<Record<string, unknown>>` | yes | Up to 100 companies with domain or linkedin_url max items 100 |
+| `body.list_id` | `integer` | yes | Target list ID |
+| `body.create_missing_fields` | `boolean` | no | When true, any key in `custom_fields` that matches no existing column is created as a NEW list-scoped custom column (max 100 per request) and then written. Default false preserves the previous behaviour of not creating columns implicitly. default `false` |
+
+**Returns** `ApiResponse_BatchAssertResponse_`: the envelope `{ data: BatchAssertResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`BatchAssertResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `total` | `integer` | yes |  |
+| `created` | `integer` | no | default `0` |
+| `custom_fields` | `CustomFieldWriteReport` | no |  |
+| `errors` | `Array<Record<string, unknown>>` | no | default `[]` |
+| `updated` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.assertUpsert.assertCompaniesBatch({ body: { companies: [{}], list_id: 123 } });
+```
+
+---
+
+<a id="op-assertcompany"></a>
+
+### `g8.api.assertUpsert.assertCompany(input)`
+
+**Assert Company**
+
+- HTTP: `PUT /api/v1/companies/assert`
+- operationId: `assert_company_companies_assert_put` (also callable as `g8.api.call("assert_company_companies_assert_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Create or update a company. Matches by domain, then linkedin_url.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CompanyAssertRequest` | yes | Request body; fields below. |
+
+Body fields (`CompanyAssertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.list_id` | `integer` | yes | Target list ID |
+| `body.annual_revenue` | `string \| null` | no |  |
+| `body.city` | `string \| null` | no |  |
+| `body.country` | `string \| null` | no |  |
+| `body.create_missing_fields` | `boolean` | no | When true, any key in `custom_fields` that matches no existing column is created as a NEW list-scoped custom column (max 100 per request) and then written. Default false preserves the previous behaviour of not creating columns implicitly. default `false` |
+| `body.custom_fields` | `Record<string, string \| null> \| null` | no | Custom column values to write on this record, keyed by the column's display title (e.g. 'Followup 1'), its slug (e.g. 'udo_followup_1_ab12cd34'), or a case/space variant of the title. Keys that match no existing column are reported back in `ignored_fields` unless `create_missing_fields` is true. |
+| `body.description` | `string \| null` | no |  |
+| `body.domain` | `string \| null` | no | Company domain (primary match key) |
+| `body.employee_count` | `integer \| null` | no |  |
+| `body.industry` | `string \| null` | no |  |
+| `body.linkedin_url` | `string \| null` | no | LinkedIn URL (fallback match key) |
+| `body.name` | `string \| null` | no |  |
+| `body.state` | `string \| null` | no |  |
+| `body.website` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_CompanyAssertResponse_`: the envelope `{ data: CompanyAssertResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CompanyAssertResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes | 'created' or 'updated' |
+| `count` | `integer` | no | default `1` |
+| `custom_fields` | `CustomFieldWriteReport` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.assertUpsert.assertCompany({ body: { list_id: 123 } });
+```
+
+---
+
+<a id="op-assertcontact"></a>
+
+### `g8.api.assertUpsert.assertContact(input)`
+
+**Assert Contact**
+
+- HTTP: `PUT /api/v1/contacts/assert`
+- operationId: `assert_contact_contacts_assert_put` (also callable as `g8.api.call("assert_contact_contacts_assert_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+- ★ Hand-written: [`g8.contacts.upsert()`](../sdk-clients.md#g8-contacts-upsert)
+
+Create or update a contact. Matches by work_email, then linkedin_url.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ContactAssertRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactAssertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.list_id` | `integer` | yes | Target list ID |
+| `body.city` | `string \| null` | no |  |
+| `body.company_domain` | `string \| null` | no |  |
+| `body.country` | `string \| null` | no |  |
+| `body.create_missing_fields` | `boolean` | no | When true, any key in `custom_fields` that matches no existing column is created as a NEW list-scoped custom column (max 100 per request) and then written. Default false preserves the previous behaviour of not creating columns implicitly. default `false` |
+| `body.custom_fields` | `Record<string, string \| null> \| null` | no | Custom column values to write on this record, keyed by the column's display title (e.g. 'Followup 1'), its slug (e.g. 'udo_followup_1_ab12cd34'), or a case/space variant of the title. Keys that match no existing column are reported back in `ignored_fields` unless `create_missing_fields` is true. |
+| `body.direct_phone` | `string \| null` | no |  |
+| `body.first_name` | `string \| null` | no |  |
+| `body.job_department` | `string \| null` | no |  |
+| `body.job_title` | `string \| null` | no |  |
+| `body.last_name` | `string \| null` | no |  |
+| `body.linkedin_url` | `string \| null` | no | LinkedIn URL (fallback match key) |
+| `body.mobile_phone` | `string \| null` | no |  |
+| `body.personal_emails` | `string \| null` | no |  |
+| `body.seniority_level` | `string \| null` | no |  |
+| `body.state` | `string \| null` | no |  |
+| `body.work_email` | `string \| null` | no | Work email (primary match key) |
+
+**Returns** `ApiResponse_ContactAssertResponse_`: the envelope `{ data: ContactAssertResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactAssertResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes | 'created' or 'updated' |
+| `count` | `integer` | no | default `1` |
+| `custom_fields` | `CustomFieldWriteReport` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.assertUpsert.assertContact({ body: { list_id: 123 } });
+```
+
+---
+
+<a id="op-assertcontactsbatch"></a>
+
+### `g8.api.assertUpsert.assertContactsBatch(input)`
+
+**Assert Contacts Batch**
+
+- HTTP: `PUT /api/v1/contacts/assert/batch`
+- operationId: `assert_contacts_batch_contacts_assert_batch_put` (also callable as `g8.api.call("assert_contacts_batch_contacts_assert_batch_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Batch create or update up to 100 contacts. Matches by work_email, then linkedin_url.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BatchContactAssertRequest` | yes | Request body; fields below. |
+
+Body fields (`BatchContactAssertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contacts` | `Array<Record<string, unknown>>` | yes | Up to 100 contacts with work_email or linkedin_url max items 100 |
+| `body.list_id` | `integer` | yes | Target list ID |
+| `body.create_missing_fields` | `boolean` | no | When true, any key in `custom_fields` that matches no existing column is created as a NEW list-scoped custom column (max 100 per request) and then written. Default false preserves the previous behaviour of not creating columns implicitly. default `false` |
+
+**Returns** `ApiResponse_BatchAssertResponse_`: the envelope `{ data: BatchAssertResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`BatchAssertResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `total` | `integer` | yes |  |
+| `created` | `integer` | no | default `0` |
+| `custom_fields` | `CustomFieldWriteReport` | no |  |
+| `errors` | `Array<Record<string, unknown>>` | no | default `[]` |
+| `updated` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.assertUpsert.assertContactsBatch({ body: { contacts: [{}], list_id: 123 } });
+```
+
+---
+
+<a id="op-assertdeal"></a>
+
+### `g8.api.assertUpsert.assertDeal(input)`
+
+**Assert Deal**
+
+- HTTP: `PUT /api/v1/deals/assert`
+- operationId: `assert_deal_deals_assert_put` (also callable as `g8.api.call("assert_deal_deals_assert_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Create or update a deal. Matches by name + company_id.
+
+Deliberately NOT wired into the closed-stage gates or the completeness
+rule: assert is the sync-shaped surface (external systems pushing state,
+no human to answer a 400), the same category the internal router excludes
+for POST /v1/deals/webhook/sync and the CRM pull worker (#15530
+"Out of scope"). Only input hygiene applies here: ids must exist and
+close_date must parse.
+
+#16060: a stage move made here now emits ``deal.stage_changed`` and writes
+``cb_deal_stage_history``, like every other stage writer. ``background_tasks``
+is injected (not a body field, so the request schema is unchanged) and the
+publish is queued only after the session context has exited — a rolled-back
+assert publishes nothing. Because assert is the sync-shaped surface, the
+SAME stage arrives on every tick of the caller's poll loop: the event fires
+only on an actual transition, never on a re-assert of the current stage.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DealAssertRequest` | yes | Request body; fields below. |
+
+Body fields (`DealAssertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | Deal name (match key) |
+| `body.amount` | `number \| null` | no |  |
+| `body.close_date` | `string \| null` | no |  |
+| `body.company_id` | `string \| null` | no | Company ID (match key, combined with name) |
+| `body.currency` | `string \| null` | no |  |
+| `body.description` | `string \| null` | no |  |
+| `body.pipeline_id` | `string \| null` | no |  |
+| `body.stage_id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_DealAssertResponse_`: the envelope `{ data: DealAssertResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealAssertResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes | 'created' or 'updated' |
+| `deal_id` | `string` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.assertUpsert.assertDeal({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-assertdealcontact"></a>
+
+### `g8.api.assertUpsert.assertDealContact(input)`
+
+**Assert Deal Contact**
+
+- HTTP: `PUT /api/v1/contacts/{contact_id}/deals/assert`
+- operationId: `assert_deal_contact_contacts__contact_id__deals_assert_put` (also callable as `g8.api.call("assert_deal_contact_contacts__contact_id__deals_assert_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Assert a deal-contact association. Idempotent — no error if already linked.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact ID |
+| `body` | `DealContactAssertRequest` | yes | Request body; fields below. |
+
+Body fields (`DealContactAssertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.deal_id` | `string` | yes | Deal ID to associate |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.assertUpsert.assertDealContact({ path: { contact_id: 123 }, body: { deal_id: "id" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-customfieldwritereport"></a>
+
+### `CustomFieldWriteReport`
+
+How a write path handled the request's custom (dynamic) column keys. Shared by every Developer API write surface that accepts custom columns (``POST /contacts``, ``PUT /contacts/assert[/batch]``, ``PUT /companies/assert[/batch]``). Every field defaults to empty, so a client that ignores this object sees no behavioural change. It exists because these keys were previously dropped with NO caller-visible signal — the only trace was a server-side ``logger.warning`` in ``append_to_audience``.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created` | `Array<string>` | no | Caller keys for which a NEW custom column was created by this request. |
+| `ignored` | `Array<string>` | no | Caller keys that matched no custom column and were NOT written. Create the column first (POST /fields) or pass create_missing_fields=true. |
+| `written` | `Array<string>` | no | Caller keys that resolved to a custom column and were written. |