@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/deals.md

@@ -0,0 +1,2436 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.deals`: Deals
+
+48 operations (21 read, 17 write, 7 destructive, 3 billable).
+
+8 of these also have a hand-written method (`g8.deals`), 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: [deals.d.ts](deals.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`addDealContact`](#op-adddealcontact) | `POST /api/v1/deals/{deal_id}/contacts` | write | `deals:write` | Add Deal Contact |
+| [`archiveDealCloseReason`](#op-archivedealclosereason) | `DELETE /api/v1/deals/close-reasons/{reason_id}` | destructive | `deals:delete` | Archive Deal Close Reason |
+| [`bulkUpdateDeals`](#op-bulkupdatedeals) | `POST /api/v1/deals/bulk` | write | `deals:write` | Bulk Update Deals |
+| [`createAccountDeal`](#op-createaccountdeal) | `POST /api/v1/accounts/{account_id}/deals` | write | `deals:write` | Create Account Deal |
+| [`createDeal`](#op-createdeal) ★ | `POST /api/v1/deals` | write | `deals:write` | Create Deal |
+| [`createDealCloseReason`](#op-createdealclosereason) | `POST /api/v1/deals/close-reasons` | write | `deals:write` | Create Deal Close Reason |
+| [`createDealColumn`](#op-createdealcolumn) | `POST /api/v1/deals/columns/create` | write | `deals:write` | Create Deal Column |
+| [`deleteDeal`](#op-deletedeal) ★ | `DELETE /api/v1/deals/{deal_id}` | destructive | `deals:delete` | Delete Deal |
+| [`deleteDealColumn`](#op-deletedealcolumn) | `DELETE /api/v1/deals/columns/{column_id}` | destructive | `deals:delete` | Delete Deal Column |
+| [`deleteDealDocument`](#op-deletedealdocument) | `DELETE /api/v1/deals/{deal_id}/documents/{document_id}` | destructive | `deals:delete` | Delete Deal Document |
+| [`deleteDealNote`](#op-deletedealnote) | `DELETE /api/v1/deals/{deal_id}/notes/{note_id}` | destructive | `deals:delete` | Delete Deal Note |
+| [`generateAllDealDocuments`](#op-generatealldealdocuments) | `POST /api/v1/deals/{deal_id}/documents/generate-all` | billable | `deals:run` | Generate All Deal Documents |
+| [`generateDealDocument`](#op-generatedealdocument) | `POST /api/v1/deals/{deal_id}/documents/types/{doc_type}/generate` | billable | `deals:run` | Generate Deal Document |
+| [`getCompanyDeals`](#op-getcompanydeals) ★ | `GET /api/v1/companies/{company_id}/deals` | read | `deals:read` | Get Company Deals |
+| [`getContactDeals`](#op-getcontactdeals) ★ | `GET /api/v1/contacts/{contact_id}/deals` | read | `deals:read` | Get Contact Deals |
+| [`getDeal`](#op-getdeal) ★ | `GET /api/v1/deals/{deal_id}` | read | `deals:read` | Get Deal |
+| [`getDealAnalytics`](#op-getdealanalytics) | `GET /api/v1/deals/analytics` | read | `deals:read` | Get Deal Analytics |
+| [`getDealCrossfire`](#op-getdealcrossfire) | `GET /api/v1/deals/{deal_id}/crossfire` | read | `deals:read` | Get Deal Crossfire |
+| [`getDealDetail`](#op-getdealdetail) | `GET /api/v1/deals/{deal_id}/detail` | read | `deals:read` | Get Deal Detail |
+| [`getDealDocument`](#op-getdealdocument) | `GET /api/v1/deals/{deal_id}/documents/types/{doc_type}` | read | `deals:read` | Get Deal Document |
+| [`getDealDocumentGenerationStatus`](#op-getdealdocumentgenerationstatus) | `GET /api/v1/deals/{deal_id}/documents/generation-status` | read | `deals:read` | Get Deal Document Generation Status |
+| [`getDealSignals`](#op-getdealsignals) | `GET /api/v1/deals/{deal_id}/signals` | read | `deals:read` | Get Deal Signals |
+| [`getDealStageVelocity`](#op-getdealstagevelocity) | `GET /api/v1/deals/stage-velocity` | read | `deals:read` | Get Deal Stage Velocity |
+| [`listAccountDeals`](#op-listaccountdeals) | `GET /api/v1/accounts/{account_id}/deals` | read | `deals:read` | List Account Deals |
+| [`listDealCloseReasons`](#op-listdealclosereasons) | `GET /api/v1/deals/close-reasons` | read | `deals:read` | List Deal Close Reasons |
+| [`listDealColumns`](#op-listdealcolumns) | `GET /api/v1/deals/columns` | read | `deals:read` | List Deal Columns |
+| [`listDealContacts`](#op-listdealcontacts) | `GET /api/v1/deals/{deal_id}/contacts` | read | `deals:read` | List Deal Contacts |
+| [`listDealCustomFieldDiConfig`](#op-listdealcustomfielddiconfig) | `GET /api/v1/deals/custom-fields/di-config` | read | `deals:read` | List Deal Custom Field Di Config |
+| [`listDealDocuments`](#op-listdealdocuments) | `GET /api/v1/deals/{deal_id}/documents` | read | `deals:read` | List Deal Documents |
+| [`listDealHistory`](#op-listdealhistory) | `GET /api/v1/deals/{deal_id}/history` | read | `deals:read` | List Deal History |
+| [`listDealLineItems`](#op-listdeallineitems) | `GET /api/v1/deals/{deal_id}/line-items` | read | `deals:read` | List Deal Line Items |
+| [`listDeals`](#op-listdeals) ★ | `GET /api/v1/deals` | read | `deals:read` | List Deals |
+| [`listPipelines`](#op-listpipelines) ★ | `GET /api/v1/deals/pipelines` | read | `deals:read` | List Pipelines |
+| [`mergeDeal`](#op-mergedeal) | `POST /api/v1/deals/{deal_id}/merge` | destructive | `deals:delete` | Merge Deal |
+| [`moveDealToPipeline`](#op-movedealtopipeline) | `PUT /api/v1/deals/{deal_id}/pipeline` | write | `deals:write` | Move Deal To Pipeline |
+| [`previewDealMerge`](#op-previewdealmerge) | `GET /api/v1/deals/{deal_id}/merge/preview` | read | `deals:read` | Preview Deal Merge |
+| [`regenerateDealDocument`](#op-regeneratedealdocument) | `POST /api/v1/deals/{deal_id}/documents/types/{doc_type}/regenerate` | billable | `deals:run` | Regenerate Deal Document |
+| [`removeDealContact`](#op-removedealcontact) | `DELETE /api/v1/deals/{deal_id}/contacts/{person_id}` | destructive | `deals:delete` | Remove Deal Contact |
+| [`replaceDealLineItems`](#op-replacedeallineitems) | `PUT /api/v1/deals/{deal_id}/line-items` | write | `deals:write` | Replace Deal Line Items |
+| [`setDealColumnValues`](#op-setdealcolumnvalues) | `PUT /api/v1/deals/{deal_id}/columns/values` | write | `deals:write` | Set Deal Column Values |
+| [`setDealCompany`](#op-setdealcompany) | `PUT /api/v1/deals/{deal_id}/company` | write | `deals:write` | Set Deal Company |
+| [`setDealContactRole`](#op-setdealcontactrole) | `PUT /api/v1/deals/{deal_id}/contacts/{contact_id}` | write | `deals:write` | Set Deal Contact Role |
+| [`setPrimaryDealContact`](#op-setprimarydealcontact) | `PUT /api/v1/deals/{deal_id}/contacts/{person_id}/primary` | write | `deals:write` | Set Primary Deal Contact |
+| [`setRivalAttach`](#op-setrivalattach) | `POST /api/v1/deals/{deal_id}/rival-attach` | write | `deals:write` | Set Rival Attach |
+| [`updateDeal`](#op-updatedeal) ★ | `PATCH /api/v1/deals/{deal_id}` | write | `deals:write` | Update Deal |
+| [`updateDealDocument`](#op-updatedealdocument) | `PUT /api/v1/deals/{deal_id}/documents/{document_id}` | write | `deals:write` | Update Deal Document |
+| [`updateDealNote`](#op-updatedealnote) | `PUT /api/v1/deals/{deal_id}/notes/{note_id}` | write | `deals:write` | Update Deal Note |
+| [`upsertDealCustomFieldDiConfig`](#op-upsertdealcustomfielddiconfig) | `POST /api/v1/deals/custom-fields/di-config` | write | `deals:write` | Upsert Deal Custom Field Di Config |
+
+---
+
+<a id="op-adddealcontact"></a>
+
+### `g8.api.deals.addDealContact(input)`
+
+**Add Deal Contact**
+
+- HTTP: `POST /api/v1/deals/{deal_id}/contacts`
+- operationId: `add_deal_contact_deals__deal_id__contacts_post` (also callable as `g8.api.call("add_deal_contact_deals__deal_id__contacts_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Link a contact to this deal.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `body` | `DealContactCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`DealContactCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.person_id` | `string` | yes | Contact to link to the deal. |
+| `body.role` | `string \| null` | no | Role on this deal: champion, decision_maker, influencer, blocker, coach or end_user. The app does not constrain the value, so it is left open here rather than declaring an enum this surface would then have to keep in lock-step. |
+
+**Returns** `ApiResponse_DealContact_`: the envelope `{ data: DealContact, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealContact` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `buying_role` | `string \| null` | no | General buying role from the contact record. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `email` | `string \| null` | no |  |
+| `id` | `string \| null` | no | Link id, not the person id. |
+| `is_primary` | `boolean \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `person_id` | `string \| null` | no |  |
+| `role` | `string \| null` | no | Role on THIS deal. |
+| `title` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.addDealContact({ path: { deal_id: "id" }, body: { person_id: "id" } });
+```
+
+---
+
+<a id="op-archivedealclosereason"></a>
+
+### `g8.api.deals.archiveDealCloseReason(input)`
+
+**Archive Deal Close Reason**
+
+- HTTP: `DELETE /api/v1/deals/close-reasons/{reason_id}`
+- operationId: `archive_deal_close_reason_deals_close_reasons__reason_id__delete` (also callable as `g8.api.call("archive_deal_close_reason_deals_close_reasons__reason_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Archive a close reason.
+
+ENTRY GATE: `_REASON_MUTATE_PERMISSIONS`, the SAME route dependency the app
+declares. Beyond the gate the decision is CREATOR OR MANAGER, not
+manager-only - the app's own note: manager-only removal "would make every
+rep's typo permanent and org-wide, in a list" a rep is expected to extend
+inline. `can_manage` (forwarded to the app handler) enforces that in-body
+creator-or-manager check, and tells a caller in advance which rows they may
+remove.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reason_id` | `string` | yes | Close reason id. |
+
+**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
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.deals.archiveDealCloseReason({ path: { reason_id: "id" } });
+```
+
+---
+
+<a id="op-bulkupdatedeals"></a>
+
+### `g8.api.deals.bulkUpdateDeals(input)`
+
+**Bulk Update Deals**
+
+- HTTP: `POST /api/v1/deals/bulk`
+- operationId: `bulk_update_deals_deals_bulk_post` (also callable as `g8.api.call("bulk_update_deals_deals_bulk_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Apply ONE change to up to 100 deals.
+
+PUT semantics on every field of `change`: null leaves a value alone, an
+EMPTY STRING clears it. Omitting a field and sending `""` are therefore
+different instructions and the second one is destructive.
+
+Read the per-deal result rather than the HTTP status: a deal the caller
+cannot write is reported, not fatal.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BulkDealUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`BulkDealUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.change` | `BulkDealChange` | yes |  |
+| `body.deal_ids` | `Array<string>` | yes | min items 1, max items 100 |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.bulkUpdateDeals({ body: { change: {}, deal_ids: ["id"] } });
+```
+
+---
+
+<a id="op-createaccountdeal"></a>
+
+### `g8.api.deals.createAccountDeal(input)`
+
+**Create Account Deal**
+
+- HTTP: `POST /api/v1/accounts/{account_id}/deals`
+- operationId: `create_account_deal_accounts__account_id__deals_post` (also callable as `g8.api.call("create_account_deal_accounts__account_id__deals_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Create a deal already attached to an account.
+
+`POST /deals` creates one standalone; this attaches it in the same call,
+closing the window where a deal exists with no account.
+
+No per-record gate, matching the app: there is no existing deal to check
+against, and the account is validated by the handler.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `string` | yes | Account the deal belongs to. |
+| `body` | `AccountDealCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`AccountDealCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes |  |
+| `body.amount` | `number \| null` | no |  |
+| `body.close_date` | `string (date-time) \| null` | no |  |
+| `body.contact_ids` | `Array<string>` | no | max items 100 |
+| `body.currency` | `string` | no | default `"USD"` |
+| `body.description` | `string \| null` | no |  |
+| `body.owner_id` | `string \| null` | no | Who owns the deal. Omit to take the app's default - an API key is an ORGANISATION credential, so there is no 'me' to fall back to. |
+| `body.pipeline_id` | `string \| null` | no |  |
+| `body.products` | `Array<string>` | no |  |
+| `body.stage` | `string` | no | Stage NAME, not id. default `"discovery"` |
+| `body.stage_id` | `string \| null` | no | Stage id. Takes precedence over `stage`. |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.createAccountDeal({ path: { account_id: "id" }, body: { name: "Example" } });
+```
+
+---
+
+<a id="op-createdeal"></a>
+
+### `g8.api.deals.createDeal(input)`
+
+**Create Deal**
+
+- HTTP: `POST /api/v1/deals`
+- operationId: `create_deal_deals_post` (also callable as `g8.api.call("create_deal_deals_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+- ★ Hand-written: [`g8.deals.create()`](../sdk-clients.md#g8-deals-create)
+
+Create a new deal. Defaults to the org's default pipeline and first stage if not specified.
+
+``background_tasks`` carries the ``deal.created`` event only (#16242). Like
+the PATCH endpoint's stage fan-out it is injected, not a body field, so it
+does not appear in the OpenAPI schema and the request contract is unchanged.
+Queuing it there rather than publishing inline keeps the Redis round trip
+off the caller's latency budget and makes "strictly after the commit"
+structural: the task is queued only once the session context has exited,
+and FastAPI attaches background tasks to the SUCCESS response, so a raise
+anywhere above publishes nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DealCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`DealCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<integer>` | yes | mashup_contact_ids to associate with the deal (>=1 required; all must share one company) min items 1 |
+| `body.name` | `string` | yes | Deal name |
+| `body.owner_id` | `string` | yes | Deal owner (user id or email). Required. |
+| `body.allow_duplicate` | `boolean` | no | Set true to create a deal even if one already exists for the company default `false` |
+| `body.amount` | `number \| null` | no | Deal monetary value |
+| `body.close_date` | `string \| null` | no | Expected close date (ISO 8601) |
+| `body.company_id` | `integer \| null` | no | Deprecated: the company is derived from the contacts. If sent, it must match; otherwise omit it. |
+| `body.currency` | `string \| null` | no | Currency code (default: USD) default `"USD"` |
+| `body.description` | `string \| null` | no | Deal description |
+| `body.pipeline_id` | `string \| null` | no | Pipeline ID (defaults to org default) |
+| `body.stage_id` | `string \| null` | no | Stage ID (from /deals/pipelines) |
+
+**Returns** `ApiResponse_DealResponse_`: the envelope `{ data: DealResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number \| null` | no |  |
+| `close_date` | `string \| null` | no |  |
+| `closed_lost_reason` | `string \| null` | no |  |
+| `company_id` | `unknown \| null` | no |  |
+| `contact_count` | `integer` | no | default `0` |
+| `contacts` | `Array<ContactBrief> \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `last_activity_at` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_email` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `owner_name` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `pipeline_name` | `string \| null` | no |  |
+| `primary_contact` | `ContactBrief \| null` | no |  |
+| `revision` | `integer \| null` | no | CRM revision after a conditional update |
+| `stage_id` | `string \| null` | no |  |
+| `stage_name` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.createDeal({ body: { contact_ids: [123], name: "Example", owner_id: "id" } });
+```
+
+---
+
+<a id="op-createdealclosereason"></a>
+
+### `g8.api.deals.createDealCloseReason(input)`
+
+**Create Deal Close Reason**
+
+- HTTP: `POST /api/v1/deals/close-reasons`
+- operationId: `create_deal_close_reason_deals_close_reasons_post` (also callable as `g8.api.call("create_deal_close_reason_deals_close_reasons_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Add a close reason.
+
+ENTRY GATE: `_REASON_MUTATE_PERMISSIONS`, the SAME route dependency the app
+declares - wider than the manager tier (a rep may extend the list inline
+while closing their own deal) but NOT open to org members with no deal
+access. `can_manage` is still resolved for the handler; `may_seed` is now
+enforced by the route gate rather than discarded.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CloseReasonCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`CloseReasonCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.kind` | `string` | yes | Which list this reason belongs to, e.g. won or lost. |
+| `body.label` | `string` | yes | min length 1, max length 255 |
+
+**Returns** `ApiResponse_DealOpResponse_`: the envelope `{ data: DealOpResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.createDealCloseReason({ body: { kind: "example", label: "example" } });
+```
+
+---
+
+<a id="op-createdealcolumn"></a>
+
+### `g8.api.deals.createDealColumn(input)`
+
+**Create Deal Column**
+
+- HTTP: `POST /api/v1/deals/columns/create`
+- operationId: `create_deal_column_deals_columns_create_post` (also callable as `g8.api.call("create_deal_column_deals_columns_create_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Add a custom column.
+
+`list_id` null creates a GLOBAL column, visible on every deals grid in the
+org. That is the wider blast radius of the two, so it is what you get by
+omission only because it is the app's own default.
+
+The path is `/columns/create` rather than a POST to `/columns`, matching
+the app exactly - a different spelling here would be a second way to say
+the same thing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateDealColumnRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateDealColumnRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | Display name. min length 1, max length 100 |
+| `body.data_type` | `"text" \| "int" \| "numeric" \| "number" \| "boolean" \| "date"` | no | Closed to what the app accepts. It validates this inside the handler, so a free string would raise there and escape as a 500 instead of a 422 naming the valid types. default `"text"` |
+| `body.list_id` | `integer \| null` | no | Scope the column to one list. Null creates a GLOBAL column. |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.createDealColumn({ body: { title: "Example" } });
+```
+
+---
+
+<a id="op-deletedeal"></a>
+
+### `g8.api.deals.deleteDeal(input)`
+
+**Delete Deal**
+
+- HTTP: `DELETE /api/v1/deals/{deal_id}`
+- operationId: `delete_deal_deals__deal_id__delete` (also callable as `g8.api.call("delete_deal_deals__deal_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+- ★ Hand-written: [`g8.deals.delete()`](../sdk-clients.md#g8-deals-delete)
+
+Delete a deal.
+
+THE TOMBSTONE RULE (#16242): ``deal.deleted`` has to be self-contained,
+because by the time a consumer reads it the row is gone and ``deal_id``
+resolves to nothing. The payload therefore comes from ``RETURNING`` on the
+DELETE itself — one round trip, and no window in which a concurrent write
+could change what a preceding SELECT had read. ``background_tasks`` is
+injected (not a body field, so the OpenAPI schema is unchanged) for the
+same reason as on PATCH.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal ID (UUID) |
+
+**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
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.deals.deleteDeal({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-deletedealcolumn"></a>
+
+### `g8.api.deals.deleteDealColumn(input)`
+
+**Delete Deal Column**
+
+- HTTP: `DELETE /api/v1/deals/columns/{column_id}`
+- operationId: `delete_deal_column_deals_columns__column_id__delete` (also callable as `g8.api.call("delete_deal_column_deals_columns__column_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Remove a custom column, and the values every deal held in it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.column_id` | `integer` | yes | Column id. |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.deals.deleteDealColumn({ path: { column_id: 123 } });
+```
+
+---
+
+<a id="op-deletedealdocument"></a>
+
+### `g8.api.deals.deleteDealDocument(input)`
+
+**Delete Deal Document**
+
+- HTTP: `DELETE /api/v1/deals/{deal_id}/documents/{document_id}`
+- operationId: `delete_deal_document_deals__deal_id__documents__document_id__delete` (also callable as `g8.api.call("delete_deal_document_deals__deal_id__documents__document_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Remove a generated document.
+
+Not destructive in the way a deleted record is: the document can be
+generated again from the same sources - at the cost of the credits that
+takes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `path.document_id` | `string` | yes | Document id, from the list read. |
+
+**Returns** `ApiResponse_DocumentPayload_`: the envelope `{ data: DocumentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.deals.deleteDealDocument({ path: { deal_id: "id", document_id: "id" } });
+```
+
+---
+
+<a id="op-deletedealnote"></a>
+
+### `g8.api.deals.deleteDealNote(input)`
+
+**Delete Deal Note**
+
+- HTTP: `DELETE /api/v1/deals/{deal_id}/notes/{note_id}`
+- operationId: `delete_deal_note_deals__deal_id__notes__note_id__delete` (also callable as `g8.api.call("delete_deal_note_deals__deal_id__notes__note_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Delete a note. The deal and its other notes are untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `path.note_id` | `string` | yes | Note id. |
+
+**Returns** `ApiResponse_DealOpResponse_`: the envelope `{ data: DealOpResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.deals.deleteDealNote({ path: { deal_id: "id", note_id: "id" } });
+```
+
+---
+
+<a id="op-generatealldealdocuments"></a>
+
+### `g8.api.deals.generateAllDealDocuments(input)`
+
+**Generate All Deal Documents**
+
+- HTTP: `POST /api/v1/deals/{deal_id}/documents/generate-all`
+- operationId: `generate_all_deal_documents_deals__deal_id__documents_generate_all_post` (also callable as `g8.api.call("generate_all_deal_documents_deals__deal_id__documents_generate_all_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+Generate all six documents for this deal. SPENDS CREDITS.
+
+ASYNCHRONOUS: the work is queued and this returns straight away. Poll
+`/documents/generation-status`.
+
+The app REFUSES this when the deal's company has no completed synthesis
+documents of its own - the deal documents are written from them, so
+without them there is nothing to write from. Generate the company
+documents first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+
+**Returns** `ApiResponse_DocumentPayload_`: the envelope `{ data: DocumentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.deals.generateAllDealDocuments({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-generatedealdocument"></a>
+
+### `g8.api.deals.generateDealDocument(input)`
+
+**Generate Deal Document**
+
+- HTTP: `POST /api/v1/deals/{deal_id}/documents/types/{doc_type}/generate`
+- operationId: `generate_deal_document_deals__deal_id__documents_types__doc_type__generate_post` (also callable as `g8.api.call("generate_deal_document_deals__deal_id__documents_types__doc_type__generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+Generate ONE document. SPENDS CREDITS.
+
+IDEMPOTENT ONLY IN THE SENSE THAT IT WILL NOT DUPLICATE: if the document
+already exists this OVERWRITES it, and the response says so with
+`is_regeneration`. It does not skip, so a retried call is a second spend.
+
+Queued, not synchronous - poll `/documents/generation-status`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `path.doc_type` | `"deal_risks" \| "next_steps" \| "close_plan" \| "scope_of_work" \| "roi_analysis" \| "competitive_analysis"` | yes | Which generated document. One of the six the deal synthesis produces; anything else is a 422 naming them. |
+
+**Returns** `ApiResponse_DocumentPayload_`: the envelope `{ data: DocumentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.deals.generateDealDocument({ path: { deal_id: "id", doc_type: "deal_risks" } });
+```
+
+---
+
+<a id="op-getcompanydeals"></a>
+
+### `g8.api.deals.getCompanyDeals(input)`
+
+**Get Company Deals**
+
+- HTTP: `GET /api/v1/companies/{company_id}/deals`
+- operationId: `get_company_deals_companies__company_id__deals_get` (also callable as `g8.api.call("get_company_deals_companies__company_id__deals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+- ★ Hand-written: [`g8.deals.forCompany()`](../sdk-clients.md#g8-deals-forcompany)
+
+Get all deals associated with a company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company ID |
+
+**Returns** `ApiResponse_list_ContactDealResponse__`: the envelope `{ data: Array<ContactDealResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactDealResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `close_date` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `deal_id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `role` | `string \| null` | no |  |
+| `stage` | `string \| null` | no |  |
+| `value` | `number \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getCompanyDeals({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactdeals"></a>
+
+### `g8.api.deals.getContactDeals(input)`
+
+**Get Contact Deals**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/deals`
+- operationId: `get_contact_deals_contacts__contact_id__deals_get` (also callable as `g8.api.call("get_contact_deals_contacts__contact_id__deals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+- ★ Hand-written: [`g8.deals.forContact()`](../sdk-clients.md#g8-deals-forcontact)
+
+Get all deals associated with a contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact ID |
+
+**Returns** `ApiResponse_list_ContactDealResponse__`: the envelope `{ data: Array<ContactDealResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactDealResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `close_date` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `deal_id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `role` | `string \| null` | no |  |
+| `stage` | `string \| null` | no |  |
+| `value` | `number \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getContactDeals({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getdeal"></a>
+
+### `g8.api.deals.getDeal(input)`
+
+**Get Deal**
+
+- HTTP: `GET /api/v1/deals/{deal_id}`
+- operationId: `get_deal_deals__deal_id__get` (also callable as `g8.api.call("get_deal_deals__deal_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+- ★ Hand-written: [`g8.deals.get()`](../sdk-clients.md#g8-deals-get)
+
+Get a single deal by ID.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal ID (UUID) |
+
+**Returns** `ApiResponse_DealResponse_`: the envelope `{ data: DealResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number \| null` | no |  |
+| `close_date` | `string \| null` | no |  |
+| `closed_lost_reason` | `string \| null` | no |  |
+| `company_id` | `unknown \| null` | no |  |
+| `contact_count` | `integer` | no | default `0` |
+| `contacts` | `Array<ContactBrief> \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `last_activity_at` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_email` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `owner_name` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `pipeline_name` | `string \| null` | no |  |
+| `primary_contact` | `ContactBrief \| null` | no |  |
+| `revision` | `integer \| null` | no | CRM revision after a conditional update |
+| `stage_id` | `string \| null` | no |  |
+| `stage_name` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getDeal({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-getdealanalytics"></a>
+
+### `g8.api.deals.getDealAnalytics(input?)`
+
+**Get Deal Analytics**
+
+- HTTP: `GET /api/v1/deals/analytics`
+- operationId: `get_deal_analytics_deals_analytics_get` (also callable as `g8.api.call("get_deal_analytics_deals_analytics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Pipeline totals, stage breakdown, win rate and velocity over the deals the key can see.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.pipeline_id` | `string \| null` | no | Only this pipeline. |
+| `query.owner_ids` | `Array<string> \| null` | no | Only these owners. Repeatable. |
+| `query.stage_ids` | `Array<string> \| null` | no | Only these stages. Repeatable. |
+| `query.close_date_from` | `string \| null` | no | Close date lower bound, YYYY-MM-DD. |
+| `query.close_date_to` | `string \| null` | no | Close date upper bound, YYYY-MM-DD. |
+| `query.search` | `string \| null` | no | Match on deal or account name. |
+| `query.segmentFilter` | `string \| null` | no | Advanced filter tree as JSON, the same one `GET /deals` accepts. 400 if unparseable. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getDealAnalytics();
+```
+
+---
+
+<a id="op-getdealcrossfire"></a>
+
+### `g8.api.deals.getDealCrossfire(input)`
+
+**Get Deal Crossfire**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/crossfire`
+- operationId: `get_deal_crossfire_deals__deal_id__crossfire_get` (also callable as `g8.api.call("get_deal_crossfire_deals__deal_id__crossfire_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Competitive pressure on this deal.
+
+Open-shaped: this is an ADVISORY read whose contents grow with the
+product, and a dropped field reads as "nothing to worry about" rather than
+"we did not tell you".
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getDealCrossfire({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-getdealdetail"></a>
+
+### `g8.api.deals.getDealDetail(input)`
+
+**Get Deal Detail**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/detail`
+- operationId: `get_deal_detail_deals__deal_id__detail_get` (also callable as `g8.api.call("get_deal_detail_deals__deal_id__detail_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The full deal record the detail page reads.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `query.include_revision` | `boolean` | no | Include the optimistic-concurrency revision. Null in the response means this org has no revision tracking, so a save is unconditional - it does NOT mean revision 1. default `false` |
+
+**Returns** `ApiResponse_DealDetail_`: the envelope `{ data: DealDetail, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealDetail` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number \| null` | no |  |
+| `close_date` | `string (date-time) \| null` | no |  |
+| `company_id` | `string \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `revision` | `integer \| null` | no | Optimistic-concurrency token. None means this org has no revision tracking, so a save is unconditional - it does NOT mean 1. |
+| `stage` | `string \| null` | no |  |
+| `stage_id` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getDealDetail({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-getdealdocument"></a>
+
+### `g8.api.deals.getDealDocument(input)`
+
+**Get Deal Document**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/documents/types/{doc_type}`
+- operationId: `get_deal_document_deals__deal_id__documents_types__doc_type__get` (also callable as `g8.api.call("get_deal_document_deals__deal_id__documents_types__doc_type__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+One generated document, in full.
+
+There is at most ONE document per type per deal, which is why the type
+identifies it. 404 when it has not been generated yet.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `path.doc_type` | `"deal_risks" \| "next_steps" \| "close_plan" \| "scope_of_work" \| "roi_analysis" \| "competitive_analysis"` | yes | Which generated document. One of the six the deal synthesis produces; anything else is a 422 naming them. |
+
+**Returns** `ApiResponse_DocumentPayload_`: the envelope `{ data: DocumentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getDealDocument({ path: { deal_id: "id", doc_type: "deal_risks" } });
+```
+
+---
+
+<a id="op-getdealdocumentgenerationstatus"></a>
+
+### `g8.api.deals.getDealDocumentGenerationStatus(input)`
+
+**Get Deal Document Generation Status**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/documents/generation-status`
+- operationId: `get_deal_document_generation_status_deals__deal_id__documents_generation_status_get` (also callable as `g8.api.call("get_deal_document_generation_status_deals__deal_id__documents_generation_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+How the generation is going - the cheap read to POLL.
+
+Counts rather than content: total, ready, generating, failed. Listing the
+documents transfers every body, which is the wrong call in a poll loop.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+
+**Returns** `ApiResponse_DocumentPayload_`: the envelope `{ data: DocumentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getDealDocumentGenerationStatus({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-getdealsignals"></a>
+
+### `g8.api.deals.getDealSignals(input)`
+
+**Get Deal Signals**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/signals`
+- operationId: `get_deal_signals_deals__deal_id__signals_get` (also callable as `g8.api.call("get_deal_signals_deals__deal_id__signals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Intent and activity signals attached to this deal.
+
+Returned as an open object rather than a pinned shape: the signals payload
+is assembled from several upstreams and declaring a schema here would
+silently DROP a signal type the moment one is added.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+
+**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.deals.getDealSignals({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-getdealstagevelocity"></a>
+
+### `g8.api.deals.getDealStageVelocity(input?)`
+
+**Get Deal Stage Velocity**
+
+- HTTP: `GET /api/v1/deals/stage-velocity`
+- operationId: `get_deal_stage_velocity_deals_stage_velocity_get` (also callable as `g8.api.call("get_deal_stage_velocity_deals_stage_velocity_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Time in stage, stage conversion and stuck deals over the deals the key can see.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.pipeline_id` | `string \| null` | no | Only this pipeline (UUID). |
+| `query.owner_ids` | `Array<string> \| null` | no | Only these owners. Repeatable, at most 100. |
+| `query.stuck_threshold_days` | `integer` | no | A deal with no stage change in this many days is 'stuck'. default `30` |
+
+**Returns** `ApiResponse_DealStageVelocityPayload_`: the envelope `{ data: DealStageVelocityPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealStageVelocityPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `stuck_deals` | `DealStageVelocityStuckSummary` | yes |  |
+| `by_stage` | `Array<DealStageVelocityBucket>` | no |  |
+| `disclosures` | `Array<string>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.getDealStageVelocity();
+```
+
+---
+
+<a id="op-listaccountdeals"></a>
+
+### `g8.api.deals.listAccountDeals(input)`
+
+**List Account Deals**
+
+- HTTP: `GET /api/v1/accounts/{account_id}/deals`
+- operationId: `list_account_deals_accounts__account_id__deals_get` (also callable as `g8.api.call("list_account_deals_accounts__account_id__deals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Deals on one account.
+
+No per-record gate: a LIST is filtered by `deal_scope`, which the app
+handler takes as a parameter and applies itself. Gating row by row here
+would be both redundant and wrong - there is no single deal id to check.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `string` | yes | Account id. |
+
+**Returns** `ApiResponse_DealListResponse_`: the envelope `{ data: DealListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `deals` | `Array<DealSummary>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listAccountDeals({ path: { account_id: "id" } });
+```
+
+---
+
+<a id="op-listdealclosereasons"></a>
+
+### `g8.api.deals.listDealCloseReasons(input?)`
+
+**List Deal Close Reasons**
+
+- HTTP: `GET /api/v1/deals/close-reasons`
+- operationId: `list_deal_close_reasons_deals_close_reasons_get` (also callable as `g8.api.call("list_deal_close_reasons_deals_close_reasons_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The org's close reasons, and what this caller may do with them.
+
+`can_manage` comes back WITH the list, resolved by the same rule the
+archive endpoint enforces - the app does that deliberately so the control a
+UI renders and the permission the endpoint applies cannot drift. A
+rebuilder without it has to guess which rows are removable.
+
+LITERAL PATH: registered before `deals_router` so `/deals/{deal_id}` cannot
+read "close-reasons" as a deal id.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.kind` | `string \| null` | no | Filter to one list, e.g. won or lost. |
+
+**Returns** `ApiResponse_CloseReasonListResponse_`: the envelope `{ data: CloseReasonListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CloseReasonListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `can_manage` | `boolean \| null` | no | Whether this caller may archive reasons they did not create. |
+| `reasons` | `Array<Record<string, unknown>>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listDealCloseReasons();
+```
+
+---
+
+<a id="op-listdealcolumns"></a>
+
+### `g8.api.deals.listDealColumns(input?)`
+
+**List Deal Columns**
+
+- HTTP: `GET /api/v1/deals/columns`
+- operationId: `list_deal_columns_deals_columns_get` (also callable as `g8.api.call("list_deal_columns_deals_columns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The custom columns the deals grid can show.
+
+The source of the keys `PUT /deals/{id}/columns/values` accepts - writing
+to anything else is refused.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer \| null` | no | Only columns scoped to this list, plus the global ones. Omit for the global set alone. |
+
+**Returns** `ApiResponse_DealCollectionPayload_`: the envelope `{ data: DealCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listDealColumns();
+```
+
+---
+
+<a id="op-listdealcontacts"></a>
+
+### `g8.api.deals.listDealContacts(input)`
+
+**List Deal Contacts**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/contacts`
+- operationId: `list_deal_contacts_deals__deal_id__contacts_get` (also callable as `g8.api.call("list_deal_contacts_deals__deal_id__contacts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Everyone linked to this deal, with their role on it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+
+**Returns** `ApiResponse_DealContactListResponse_`: the envelope `{ data: DealContactListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealContactListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `contacts` | `Array<DealContact>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listDealContacts({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-listdealcustomfielddiconfig"></a>
+
+### `g8.api.deals.listDealCustomFieldDiConfig(input?)`
+
+**List Deal Custom Field Di Config**
+
+- HTTP: `GET /api/v1/deals/custom-fields/di-config`
+- operationId: `list_deal_custom_field_di_config_deals_custom_fields_di_config_get` (also callable as `g8.api.call("list_deal_custom_field_di_config_deals_custom_fields_di_config_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Which deal custom fields exist and how they map outward.
+
+No per-record gate: this is org-level configuration, not a deal.
+
+NOTE ON ROUTING ORDER: this path is LITERAL and would otherwise be
+swallowed by `/deals/{deal_id}` in the existing deals router, which would
+read "custom-fields" as a deal id. That is why this router is registered
+BEFORE it in `app.py` - see the comment there.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.crm_provider` | `string \| null` | no | Filter to one CRM provider's mappings. |
+
+**Returns** `ApiResponse_CustomFieldDiConfigListResponse_`: the envelope `{ data: CustomFieldDiConfigListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CustomFieldDiConfigListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `configs` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listDealCustomFieldDiConfig();
+```
+
+---
+
+<a id="op-listdealdocuments"></a>
+
+### `g8.api.deals.listDealDocuments(input)`
+
+**List Deal Documents**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/documents`
+- operationId: `list_deal_documents_deals__deal_id__documents_get` (also callable as `g8.api.call("list_deal_documents_deals__deal_id__documents_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Every generated document on this deal, newest first.
+
+Carries each document's body, so it is the wrong read for a poll loop -
+use `/documents/generation-status` for that.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `query.folder` | `string \| null` | no | `strategy` or `analysis`. Not validated by the app - an unrecognised folder matches nothing rather than failing. |
+
+**Returns** `ApiResponse_DocumentListPayload_`: the envelope `{ data: DocumentListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DocumentListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listDealDocuments({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-listdealhistory"></a>
+
+### `g8.api.deals.listDealHistory(input)`
+
+**List Deal History**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/history`
+- operationId: `list_deal_history_deals__deal_id__history_get` (also callable as `g8.api.call("list_deal_history_deals__deal_id__history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+What changed on this deal, and who changed it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `query.limit` | `integer` | no | The app's cap, and it is a real ceiling rather than a default to raise: a long history pages through `offset`. default `200` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_DealCollectionPayload_`: the envelope `{ data: DealCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listDealHistory({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-listdeallineitems"></a>
+
+### `g8.api.deals.listDealLineItems(input)`
+
+**List Deal Line Items**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/line-items`
+- operationId: `list_deal_line_items_deals__deal_id__line_items_get` (also callable as `g8.api.call("list_deal_line_items_deals__deal_id__line_items_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+A deal's line items, its derived amount, and whether it disagrees with its linked quote.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+
+**Returns** `ApiResponse_DealLineItemsPayload_`: the envelope `{ data: DealLineItemsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealLineItemsPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `deal_id` | `string` | yes |  |
+| `amount` | `number \| null` | no |  |
+| `amount_mismatch` | `boolean` | no | default `false` |
+| `currency` | `string \| null` | no |  |
+| `line_items` | `Array<DealLineItemRecord>` | no |  |
+| `linked_quote_total` | `number \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listDealLineItems({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-listdeals"></a>
+
+### `g8.api.deals.listDeals(input?)`
+
+**List Deals**
+
+- HTTP: `GET /api/v1/deals`
+- operationId: `list_deals_deals_get` (also callable as `g8.api.call("list_deals_deals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+- ★ Hand-written: [`g8.deals.list()`](../sdk-clients.md#g8-deals-list)
+
+List all deals org-wide with optional filters and pagination.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | Page number default `1` |
+| `query.limit` | `integer` | no | Items per page default `50` |
+| `query.stage_id` | `string \| null` | no | Filter by stage ID |
+| `query.pipeline_id` | `string \| null` | no | Filter by pipeline ID |
+| `query.search` | `string \| null` | no | Search by deal name |
+| `query.owner_id` | `string \| null` | no | Filter by owner ID |
+| `query.owner_email` | `string \| null` | no | Filter by owner email |
+| `query.outcome` | `"won" \| "lost" \| "open" \| null` | no | Filter by deal outcome. A deal is won, lost, or open - exactly one. Prefer this over is_closed_won: the boolean's false branch means 'not won', which returns open AND unclassified deals alongside lost ones, and is the wrong cohort for closed-lost re-engagement. |
+| `query.is_closed_won` | `boolean \| null` | no | LEGACY - prefer outcome=. Retained for backwards compatibility with existing consumers. true means won; false means NOT won (open, lost and unclassified deals), which is rarely what a caller intends. |
+| `query.last_activity_before` | `string (date-time) \| null` | no | Only deals last touched before this timestamp |
+| `query.stale_before` | `string (date-time) \| null` | no | Deals last touched before this timestamp OR never touched at all. Union of last_activity_before and the no-activity cohort - use this for 'my stale deals' (last_activity_before alone excludes deals with no recorded activity, since NULL is never earlier-than). |
+| `query.has_activity` | `boolean \| null` | no | Filter by whether the deal has recorded activity |
+| `query.has_contact` | `boolean \| null` | no | Filter by whether the deal has a route to any contact. false returns the orphaned-deal cohort: no cb_deal_contacts row AND no live primary contact (a primary_contact_id pointing at a soft-deleted or merged-away contact counts as no route). Same definition the Data Quality panel counts, so the two can never disagree. |
+| `query.close_after` | `string (date-time) \| null` | no | Only deals whose close_date is on/after this timestamp (inclusive lower bound). Pair with close_before for a period window, and with outcome=won for 'deals we closed-won in this period'. A period count needs BOTH a lower bound and the outcome join: close_before alone sums the entire deal history into every period. Deals with a NULL close_date are excluded (a deal with no close date is not closing… |
+| `query.close_before` | `string (date-time) \| null` | no | Only deals whose close_date is strictly before this timestamp (exclusive upper bound). The window is half-open [close_after, close_before) so adjacent periods never double-count a deal that closes exactly on a boundary. A naive timestamp is treated as UTC (the close_date column is timestamp without time zone). |
+
+**Returns** `ApiResponse_list_DealResponse__`: the envelope `{ data: Array<DealResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number \| null` | no |  |
+| `close_date` | `string \| null` | no |  |
+| `closed_lost_reason` | `string \| null` | no |  |
+| `company_id` | `unknown \| null` | no |  |
+| `contact_count` | `integer` | no | default `0` |
+| `contacts` | `Array<ContactBrief> \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `last_activity_at` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_email` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `owner_name` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `pipeline_name` | `string \| null` | no |  |
+| `primary_contact` | `ContactBrief \| null` | no |  |
+| `revision` | `integer \| null` | no | CRM revision after a conditional update |
+| `stage_id` | `string \| null` | no |  |
+| `stage_name` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listDeals();
+```
+
+---
+
+<a id="op-listpipelines"></a>
+
+### `g8.api.deals.listPipelines(input?)`
+
+**List Pipelines**
+
+- HTTP: `GET /api/v1/deals/pipelines`
+- operationId: `list_pipelines_deals_pipelines_get` (also callable as `g8.api.call("list_pipelines_deals_pipelines_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+- ★ Hand-written: [`g8.deals.pipelines()`](../sdk-clients.md#g8-deals-pipelines)
+
+List all deal pipelines and their stages.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_PipelineResponse__`: the envelope `{ data: Array<PipelineResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`PipelineResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `is_default` | `boolean` | no | default `false` |
+| `stages` | `Array<PipelineStageResponse>` | no | default `[]` |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.listPipelines();
+```
+
+---
+
+<a id="op-mergedeal"></a>
+
+### `g8.api.deals.mergeDeal(input)`
+
+**Merge Deal**
+
+- HTTP: `POST /api/v1/deals/{deal_id}/merge`
+- operationId: `merge_deal_deals__deal_id__merge_post` (also callable as `g8.api.call("merge_deal_deals__deal_id__merge_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Merge `secondary_id` into this deal. NOT REVERSIBLE.
+
+The secondary deal stops existing; its contacts, notes and activity move
+onto the survivor. `field_overrides` is the only way to keep a value from
+the deal being merged away.
+
+Preview it first. There is no unmerge.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | The deal that SURVIVES. |
+| `body` | `MergeDealRequest` | yes | Request body; fields below. |
+
+Body fields (`MergeDealRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.secondary_id` | `string` | yes | The deal to merge AWAY. Must be a UUID; the path deal survives. |
+| `body.field_overrides` | `Array<DealFieldOverride>` | no | Decide individual fields yourself instead of taking the app's rules. |
+| `body.suggestion_id` | `string \| null` | no | The duplicate-suggestion this merge acts on, if any. |
+| `body.trigger` | `"manual" \| "queue" \| "bulk_criterion"` | no | What prompted the merge. Recorded on the audit row. default `"manual"` |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.deals.mergeDeal({ path: { deal_id: "id" }, body: { secondary_id: "id" } });
+```
+
+---
+
+<a id="op-movedealtopipeline"></a>
+
+### `g8.api.deals.moveDealToPipeline(input)`
+
+**Move Deal To Pipeline**
+
+- HTTP: `PUT /api/v1/deals/{deal_id}/pipeline`
+- operationId: `move_deal_to_pipeline_deals__deal_id__pipeline_put` (also callable as `g8.api.call("move_deal_to_pipeline_deals__deal_id__pipeline_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Move a deal into a different pipeline.
+
+The deal keeps its identity and history. Its STAGE does not carry over -
+the target pipeline has its own stages and the app re-seats the deal within
+them, so a caller should read the deal back rather than assume its stage.
+
+The path is `/pipeline` rather than the app's `/move-pipeline`: the verb is
+already in the PUT.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `body` | `DealMovePipelineRequest` | yes | Request body; fields below. |
+
+Body fields (`DealMovePipelineRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.target_pipeline_id` | `string` | yes | Pipeline to move the deal into. |
+
+**Returns** `ApiResponse_DealOpResponse_`: the envelope `{ data: DealOpResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.moveDealToPipeline({ path: { deal_id: "id" }, body: { target_pipeline_id: "id" } });
+```
+
+---
+
+<a id="op-previewdealmerge"></a>
+
+### `g8.api.deals.previewDealMerge(input)`
+
+**Preview Deal Merge**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/merge/preview`
+- operationId: `preview_deal_merge_deals__deal_id__merge_preview_get` (also callable as `g8.api.call("preview_deal_merge_deals__deal_id__merge_preview_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+What the merge WOULD do. Changes nothing.
+
+Worth calling first for the same reason the app does: merging is not
+reversible, and this is the only place that says which field values change
+and which records move before they do.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | The deal that SURVIVES. |
+| `query.secondary` | `string` | yes | The deal that would be merged AWAY. |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.previewDealMerge({ path: { deal_id: "id" }, query: { secondary: "example" } });
+```
+
+---
+
+<a id="op-regeneratedealdocument"></a>
+
+### `g8.api.deals.regenerateDealDocument(input)`
+
+**Regenerate Deal Document**
+
+- HTTP: `POST /api/v1/deals/{deal_id}/documents/types/{doc_type}/regenerate`
+- operationId: `regenerate_deal_document_deals__deal_id__documents_types__doc_type__regenerate_post` (also callable as `g8.api.call("regenerate_deal_document_deals__deal_id__documents_types__doc_type__regenerate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+Re-write a document that already exists. SPENDS CREDITS.
+
+The difference from `/generate` is what happens when the document is
+MISSING: this 404s, `/generate` creates it. Use this when you want to be
+sure you are replacing rather than creating.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `path.doc_type` | `"deal_risks" \| "next_steps" \| "close_plan" \| "scope_of_work" \| "roi_analysis" \| "competitive_analysis"` | yes | Which generated document. One of the six the deal synthesis produces; anything else is a 422 naming them. |
+
+**Returns** `ApiResponse_DocumentPayload_`: the envelope `{ data: DocumentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.deals.regenerateDealDocument({ path: { deal_id: "id", doc_type: "deal_risks" } });
+```
+
+---
+
+<a id="op-removedealcontact"></a>
+
+### `g8.api.deals.removeDealContact(input)`
+
+**Remove Deal Contact**
+
+- HTTP: `DELETE /api/v1/deals/{deal_id}/contacts/{person_id}`
+- operationId: `remove_deal_contact_deals__deal_id__contacts__person_id__delete` (also callable as `g8.api.call("remove_deal_contact_deals__deal_id__contacts__person_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Unlink a contact from the deal. The contact record itself is untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `path.person_id` | `string` | yes | Contact id. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.deals.removeDealContact({ path: { deal_id: "id", person_id: "id" } });
+```
+
+---
+
+<a id="op-replacedeallineitems"></a>
+
+### `g8.api.deals.replaceDealLineItems(input)`
+
+**Replace Deal Line Items**
+
+- HTTP: `PUT /api/v1/deals/{deal_id}/line-items`
+- operationId: `replace_deal_line_items_deals__deal_id__line_items_put` (also callable as `g8.api.call("replace_deal_line_items_deals__deal_id__line_items_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Replace a deal's line items. The FULL set, not a delta.
+
+A non-empty set makes the deal amount the sum of the lines (audited in the
+deal history). An empty set clears the lines and keeps the typed amount.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `body` | `DealLineItemsReplaceBody` | yes | Request body; fields below. |
+
+Body fields (`DealLineItemsReplaceBody`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.line_items` | `Array<DealLineItemWrite>` | no |  |
+
+**Returns** `ApiResponse_DealLineItemsPayload_`: the envelope `{ data: DealLineItemsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealLineItemsPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `deal_id` | `string` | yes |  |
+| `amount` | `number \| null` | no |  |
+| `amount_mismatch` | `boolean` | no | default `false` |
+| `currency` | `string \| null` | no |  |
+| `line_items` | `Array<DealLineItemRecord>` | no |  |
+| `linked_quote_total` | `number \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.replaceDealLineItems({ path: { deal_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-setdealcolumnvalues"></a>
+
+### `g8.api.deals.setDealColumnValues(input)`
+
+**Set Deal Column Values**
+
+- HTTP: `PUT /api/v1/deals/{deal_id}/columns/values`
+- operationId: `set_deal_column_values_deals__deal_id__columns_values_put` (also callable as `g8.api.call("set_deal_column_values_deals__deal_id__columns_values_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Write custom column values on one deal.
+
+A null CLEARS that column rather than leaving it alone. Keys come from
+`GET /deals/columns`; anything else is refused.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `body` | `SetDealColumnValuesRequest` | yes | Request body; fields below. |
+| `query.list_id` | `integer \| null` | no | Resolve list-scoped columns against this list. |
+
+Body fields (`SetDealColumnValuesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.values` | `Record<string, string \| integer \| number \| boolean \| null>` | yes | Column key -> value. A null clears that column. |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.setDealColumnValues({ path: { deal_id: "id" }, body: { values: {} } });
+```
+
+---
+
+<a id="op-setdealcompany"></a>
+
+### `g8.api.deals.setDealCompany(input)`
+
+**Set Deal Company**
+
+- HTTP: `PUT /api/v1/deals/{deal_id}/company`
+- operationId: `set_deal_company_deals__deal_id__company_put` (also callable as `g8.api.call("set_deal_company_deals__deal_id__company_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Attach or change the company on a deal.
+
+`mashup_company_id` is the CANONICAL company id, not a
+`cb_company_extensions` / ABM overlay id. They are different tables with
+different ids, and the wrong one attaches the deal to nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `body` | `DealCompanyRequest` | yes | Request body; fields below. |
+
+Body fields (`DealCompanyRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mashup_company_id` | `integer` | yes | The CANONICAL company id (`mashup_companies`), not a `cb_company_extensions` / ABM overlay id. The two are different tables with different ids and passing the wrong one attaches the deal to nothing. |
+
+**Returns** `ApiResponse_DealOpResponse_`: the envelope `{ data: DealOpResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.setDealCompany({ path: { deal_id: "id" }, body: { mashup_company_id: 123 } });
+```
+
+---
+
+<a id="op-setdealcontactrole"></a>
+
+### `g8.api.deals.setDealContactRole(input)`
+
+**Set Deal Contact Role**
+
+- HTTP: `PUT /api/v1/deals/{deal_id}/contacts/{contact_id}`
+- operationId: `set_deal_contact_role_deals__deal_id__contacts__contact_id__put` (also callable as `g8.api.call("set_deal_contact_role_deals__deal_id__contacts__contact_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Set (or clear) a contact's buying-committee role on a deal.
+
+The role lives on the deal-contact LINK (`cb_deal_contacts.role`), not on
+the contact: the same person can be a champion on one deal and an end user
+on another. This endpoint only re-roles an EXISTING link — it never
+creates one, so attaching and roling stay separately auditable. Use
+``PATCH /deals/{deal_id}`` with ``add_contact_ids`` (optionally alongside
+``contact_roles``) to link a contact first.
+
+``{contact_id}`` is the ``mashup_contact_id``, the same integer id this API
+uses for a contact everywhere else (``GET /contacts/{id}``, the ``id`` on
+every ``ContactBrief``). The internal app route calls the identical value
+``{person_id}``; that name is a historical misnomer and is not repeated
+here.
+
+Body is ``{"role": "champion"}``; an explicit ``{"role": null}`` clears the
+role. ``role`` is required — an empty body is a 422, because a PUT that
+names no new state for the sub-resource is a caller bug, and reading
+omission as "clear" would destroy data on a typo.
+
+Returns the updated contact. 404 when the deal does not exist in this org
+or the contact is not linked to it; 422 on a role outside the vocabulary.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal ID (UUID) |
+| `path.contact_id` | `integer` | yes | mashup_contact_id (BigInt) of a contact already linked to this deal |
+| `body` | `DealContactRoleUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`DealContactRoleUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.role` | `string \| null` | yes | Buying-committee role for this contact on this deal. One of: champion, decision_maker, influencer, blocker, coach, end_user. Pass null to clear the role. |
+
+**Returns** `ApiResponse_ContactBrief_`: the envelope `{ data: ContactBrief, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactBrief` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `email` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `role` | `string \| null` | no |  |
+| `title` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.setDealContactRole({
+  path: { deal_id: "id", contact_id: 123 },
+  body: { role: "example" },
+});
+```
+
+---
+
+<a id="op-setprimarydealcontact"></a>
+
+### `g8.api.deals.setPrimaryDealContact(input)`
+
+**Set Primary Deal Contact**
+
+- HTTP: `PUT /api/v1/deals/{deal_id}/contacts/{person_id}/primary`
+- operationId: `set_primary_deal_contact_deals__deal_id__contacts__person_id__primary_put` (also callable as `g8.api.call("set_primary_deal_contact_deals__deal_id__contacts__person_id__primary_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Make this person the deal's primary contact.
+
+A deal has ONE primary, so this demotes whoever held it - there is no
+separate call to unset the previous one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `path.person_id` | `string` | yes | Contact id to make primary. |
+
+**Returns** `ApiResponse_DealContact_`: the envelope `{ data: DealContact, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealContact` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `buying_role` | `string \| null` | no | General buying role from the contact record. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `email` | `string \| null` | no |  |
+| `id` | `string \| null` | no | Link id, not the person id. |
+| `is_primary` | `boolean \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `person_id` | `string \| null` | no |  |
+| `role` | `string \| null` | no | Role on THIS deal. |
+| `title` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.setPrimaryDealContact({ path: { deal_id: "id", person_id: "id" } });
+```
+
+---
+
+<a id="op-setrivalattach"></a>
+
+### `g8.api.deals.setRivalAttach(input)`
+
+**Set Rival Attach**
+
+- HTTP: `POST /api/v1/deals/{deal_id}/rival-attach`
+- operationId: `set_rival_attach_deals__deal_id__rival_attach_post` (also callable as `g8.api.call("set_rival_attach_deals__deal_id__rival_attach_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Record which competitor is on this deal, and how it is going.
+
+A null `competitor_id` DETACHES the current one - the same route both
+attaches and clears.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `body` | `RivalAttachRequest` | yes | Request body; fields below. |
+
+Body fields (`RivalAttachRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `string` | yes | Where the deal stands against them. |
+| `body.competitor_id` | `string \| null` | no | The competitor. Null detaches the current one. |
+
+**Returns** `ApiResponse_DealPayload_`: the envelope `{ data: DealPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.setRivalAttach({ path: { deal_id: "id" }, body: { status: "example" } });
+```
+
+---
+
+<a id="op-updatedeal"></a>
+
+### `g8.api.deals.updateDeal(input)`
+
+**Update Deal**
+
+- HTTP: `PATCH /api/v1/deals/{deal_id}`
+- operationId: `update_deal_deals__deal_id__patch` (also callable as `g8.api.call("update_deal_deals__deal_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+- ★ Hand-written: [`g8.deals.update()`](../sdk-clients.md#g8-deals-update)
+
+Update a deal (partial update).
+
+Contact operations run in a fixed order within the single transaction:
+``remove_contact_ids`` -> ``add_contact_ids`` -> ``contact_roles``. That
+order is what makes the useful combinations work:
+
+* a contact linked by ``add_contact_ids`` in THIS request can be given a
+  role by ``contact_roles`` in the same call (roles run last);
+* an id in both ``remove_contact_ids`` and ``add_contact_ids`` ends up
+  linked (add runs after remove), so a role for it still applies;
+* an id in ``remove_contact_ids`` and ``contact_roles`` but NOT in
+  ``add_contact_ids`` is unlinked by the time roles run, so it is a 422
+  naming that id rather than a role written to a row that no longer
+  exists.
+
+A ``contact_roles`` entry for a contact that is neither already linked nor
+being added is a 422; the whole transaction rolls back, so a partially
+applied batch is not a state this endpoint can produce.
+
+``background_tasks`` carries the ``deal.stage_changed`` fan-out only. It is
+injected, not a body field, so it does not appear in the OpenAPI schema and
+the request contract is unchanged (pinned by
+``developer_api/tests/test_deal_stage_events.py``). Publishing there rather
+than inline keeps the Redis round trip off the caller's latency budget and
+makes "strictly after the commit" structural: the task is queued only after
+the session context has exited, and FastAPI attaches background tasks to the
+SUCCESS response, so a raise anywhere above publishes nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal ID (UUID) |
+| `body` | `DealUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`DealUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.add_contact_ids` | `Array<integer>` | no | mashup_contact_ids to add to the deal (must match the deal's company; idempotent) |
+| `body.amount` | `number \| null` | no | Deal monetary value |
+| `body.close_date` | `string \| null` | no | Expected close date (ISO 8601) |
+| `body.contact_roles` | `Record<string, string \| null> \| null` | no | Buying-committee roles keyed by mashup_contact_id, e.g. {"5500429": "champion", "5500914": null}. Valid roles: champion, decision_maker, influencer, blocker, coach, end_user. null clears a role. Each id must already be linked to the deal or be present in add_contact_ids in the same request (422 otherwise). |
+| `body.currency` | `string \| null` | no | Currency code |
+| `body.description` | `string \| null` | no | Deal description |
+| `body.expected_revision` | `integer \| null` | no | Apply only if the canonical CRM revision still matches; otherwise return 409. Omit for existing PATCH behavior. min 1 |
+| `body.name` | `string \| null` | no | Deal name |
+| `body.owner_id` | `string \| null` | no | Reassign deal owner (member id, email, or PropelAuth uid). Cannot be cleared. |
+| `body.remove_contact_ids` | `Array<integer>` | no | mashup_contact_ids to remove from the deal (idempotent — unlinked skipped) |
+| `body.stage_id` | `string \| null` | no | Stage ID |
+
+**Returns** `ApiResponse_DealResponse_`: the envelope `{ data: DealResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DealResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number \| null` | no |  |
+| `close_date` | `string \| null` | no |  |
+| `closed_lost_reason` | `string \| null` | no |  |
+| `company_id` | `unknown \| null` | no |  |
+| `contact_count` | `integer` | no | default `0` |
+| `contacts` | `Array<ContactBrief> \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `last_activity_at` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_email` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `owner_name` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `pipeline_name` | `string \| null` | no |  |
+| `primary_contact` | `ContactBrief \| null` | no |  |
+| `revision` | `integer \| null` | no | CRM revision after a conditional update |
+| `stage_id` | `string \| null` | no |  |
+| `stage_name` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deals.updateDeal({ path: { deal_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updatedealdocument"></a>
+
+### `g8.api.deals.updateDealDocument(input)`
+
+**Update Deal Document**
+
+- HTTP: `PUT /api/v1/deals/{deal_id}/documents/{document_id}`
+- operationId: `update_deal_document_deals__deal_id__documents__document_id__put` (also callable as `g8.api.call("update_deal_document_deals__deal_id__documents__document_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Edit a generated document by hand.
+
+Keyed by document ID, not by type - this is the one place the two
+identifier spaces differ, and it is why the type-keyed routes live under
+`/documents/types/`.
+
+An omitted field is left alone; `structured_data` REPLACES the stored
+object rather than merging into it. A later regeneration OVERWRITES the
+edit, so edit last.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id (UUID). |
+| `path.document_id` | `string` | yes | Document id, from the list read. |
+| `body` | `DealDocumentUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`DealDocumentUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string \| null` | no | The document body. |
+| `body.structured_data` | `Record<string, unknown> \| null` | no | The machine-readable half. Replaces, does not merge. |
+
+**Returns** `ApiResponse_DocumentPayload_`: the envelope `{ data: DocumentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.updateDealDocument({ path: { deal_id: "id", document_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updatedealnote"></a>
+
+### `g8.api.deals.updateDealNote(input)`
+
+**Update Deal Note**
+
+- HTTP: `PUT /api/v1/deals/{deal_id}/notes/{note_id}`
+- operationId: `update_deal_note_deals__deal_id__notes__note_id__put` (also callable as `g8.api.call("update_deal_note_deals__deal_id__notes__note_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Rewrite a note.
+
+`content` is a full REPLACEMENT, not a patch, and `mentioned_users` is who
+is mentioned AFTER the edit - omitting someone removes their mention. Send
+the whole state you want, not the delta.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `path.note_id` | `string` | yes | Note id. |
+| `body` | `DealNoteUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`DealNoteUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string` | yes | Full replacement body - this is not a patch. |
+| `body.mentioned_users` | `Array<DealNoteMention>` | no | Who is mentioned AFTER the edit. Omitting someone removes their mention, because the list replaces rather than adds. |
+
+**Returns** `ApiResponse_DealOpResponse_`: the envelope `{ data: DealOpResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.updateDealNote({
+  path: { deal_id: "id", note_id: "id" },
+  body: { content: "example" },
+});
+```
+
+---
+
+<a id="op-upsertdealcustomfielddiconfig"></a>
+
+### `g8.api.deals.upsertDealCustomFieldDiConfig(input)`
+
+**Upsert Deal Custom Field Di Config**
+
+- HTTP: `POST /api/v1/deals/custom-fields/di-config`
+- operationId: `upsert_deal_custom_field_di_config_deals_custom_fields_di_config_post` (also callable as `g8.api.call("upsert_deal_custom_field_di_config_deals_custom_fields_di_config_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Replace the deal custom-field mappings.
+
+ENTRY GATE: manager tier (DEALS_WRITE_TEAM / DEALS_WRITE_ALL /
+DEALS_MANAGE), the SAME route dependency the app declares - the values here
+are interpolated into the Deal Intelligence LLM prompt, so an own-scope rep
+must not be able to poison org-wide DI. The coarse `deals:write` scope does
+not distinguish own/team/all/manage, so this RBAC gate is what stops a
+rep-minted key reaching a manager-only surface.
+
+`items` is the FULL desired set for the providers it names, not a delta -
+the app upserts exactly what is sent. The READ half of this pair shipped in
+#20744; this completes it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CustomFieldDiConfigUpsertRequest` | yes | Request body; fields below. |
+
+Body fields (`CustomFieldDiConfigUpsertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.items` | `Array<CustomFieldDiConfigItem>` | yes | min items 1, max items 100 |
+
+**Returns** `ApiResponse_DealOpResponse_`: the envelope `{ data: DealOpResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deals.upsertDealCustomFieldDiConfig({ body: { items: [{ crm_provider: "example", field_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-bulkdealchange"></a>
+
+### `BulkDealChange`
+
+The change applied to EVERY deal in the batch. PUT semantics, and the distinction matters: `null` leaves a value alone, an EMPTY STRING clears it. So omitting a field and sending `""` are different instructions, and the second one is destructive.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number \| null` | no |  |
+| `close_date` | `string (date-time) \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `custom_fields` | `Record<string, unknown> \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `next_step` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `stage` | `string \| null` | no |  |
+| `stage_id` | `string \| null` | no |  |
+
+<a id="type-customfielddiconfigitem"></a>
+
+### `CustomFieldDiConfigItem`
+
+One custom-field mapping. Typed rather than left an open dict: `crm_provider` and `field_id` are REQUIRED upstream, and an open list let a missing one reach the app's model as a raw ValidationError from inside the proxy - a 500 for a plain client error. The 255 caps are the underlying VARCHAR widths, and `display_name` additionally feeds the Deal Intelligence LLM prompt, so its bound is a token-budget and prompt-injection concern rather than cosmetic.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `crm_provider` | `string` | yes | salesforce, hubspot or pipedrive. |
+| `field_id` | `string` | yes | The CRM's own field id. max length 255 |
+| `display_name` | `string \| null` | no | max length 255 |
+| `id` | `string \| null` | no |  |
+| `include_in_di_summary` | `boolean` | no | default `false` |
+| `include_in_forecast_probability` | `boolean` | no | default `false` |
+
+<a id="type-dealfieldoverride"></a>
+
+### `DealFieldOverride`
+
+Which side of the merge wins one field. Without an override the app picks per its own rules. Name a field here to decide it yourself - the only way to keep a value from the deal that is being merged AWAY.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `field` | `string` | yes |  |
+| `winner` | `"primary" \| "secondary"` | yes |  |
+
+<a id="type-deallineitemrecord"></a>
+
+### `DealLineItemRecord`
+
+A deal line item. Money fields are in cents.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `discount_pct` | `number` | yes |  |
+| `id` | `string` | yes |  |
+| `line_total` | `integer` | yes |  |
+| `product_name` | `string` | yes |  |
+| `quantity` | `integer` | yes |  |
+| `sort_order` | `integer` | yes |  |
+| `unit_amount` | `integer` | yes |  |
+| `billing_frequency` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `manual_product_id` | `string \| null` | no |  |
+| `stripe_price_id` | `string \| null` | no |  |
+| `stripe_product_id` | `string \| null` | no |  |
+
+<a id="type-deallineitemwrite"></a>
+
+### `DealLineItemWrite`
+
+One line item in a replace request. Money is in CENTS. `line_total` is not accepted: the server recomputes it from `unit_amount`, `quantity` and `discount_pct`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `product_name` | `string` | yes | min length 1, max length 500 |
+| `unit_amount` | `integer` | yes | Unit price in cents. min 0, max 1000000000 |
+| `billing_frequency` | `string \| null` | no | max length 50 |
+| `description` | `string \| null` | no | max length 2000 |
+| `discount_pct` | `number` | no | default `0`, min 0, max 100 |
+| `manual_product_id` | `string \| null` | no | Id of a manually-defined product. |
+| `quantity` | `integer` | no | default `1`, min 1, max 10000 |
+| `sort_order` | `integer` | no | default `0` |
+| `stripe_price_id` | `string \| null` | no | Catalog price id, when catalog-backed. |
+| `stripe_product_id` | `string \| null` | no | Catalog product id, when catalog-backed. |
+
+<a id="type-dealnotemention"></a>
+
+### `DealNoteMention`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `email` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+
+<a id="type-dealstagevelocitybucket"></a>
+
+### `DealStageVelocityBucket`
+
+Movement through one stage. `avg_days_in_stage` and `conversion_rate` are null (not 0) when there is no sample: an average over zero completed dwells is undefined.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `completed_dwells` | `integer` | yes |  |
+| `entered_count` | `integer` | yes |  |
+| `fell_back_count` | `integer` | yes |  |
+| `position` | `integer` | yes |  |
+| `progressed_count` | `integer` | yes |  |
+| `stage_id` | `string` | yes |  |
+| `stage_name` | `string` | yes |  |
+| `still_in_stage_count` | `integer` | yes |  |
+| `avg_days_in_stage` | `number \| null` | no |  |
+| `conversion_rate` | `number \| null` | no |  |
+
+<a id="type-dealstagevelocitystucksummary"></a>
+
+### `DealStageVelocityStuckSummary`
+
+`total_count` is exact; `deals` is capped at 100 (`truncated` says so).
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `threshold_days` | `integer` | yes |  |
+| `total_count` | `integer` | yes |  |
+| `truncated` | `boolean` | yes |  |
+| `deals` | `Array<DealStageVelocityStuckDeal>` | no |  |
+
+<a id="type-dealsummary"></a>
+
+### `DealSummary`
+
+One deal as it appears in a list.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number \| null` | no |  |
+| `close_date` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `pipeline_id` | `string \| null` | no |  |
+| `stage` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+
+<a id="type-pipelinestageresponse"></a>
+
+### `PipelineStageResponse`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `channel_scripts` | `Record<string, string>` | no |  |
+| `color` | `string \| null` | no |  |
+| `position` | `integer \| null` | no |  |
+| `probability` | `integer \| null` | no |  |
+| `recommended_elements` | `Array<string>` | no |  |
+| `required_elements` | `Array<string>` | no |  |
+| `stage_type` | `string \| null` | no |  |