@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/deals.d.ts

@@ -0,0 +1,1696 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.deals` (Deals): 48 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"add_deal_contact_deals__deal_id__contacts_post">;
+ *
+ * Reference with examples: deals.md
+ */
+/* eslint-disable */
+
+/** `g8.api.deals.<member>` -> the operationId it calls. */
+export interface DealsMembers {
+  addDealContact: "add_deal_contact_deals__deal_id__contacts_post";
+  archiveDealCloseReason: "archive_deal_close_reason_deals_close_reasons__reason_id__delete";
+  bulkUpdateDeals: "bulk_update_deals_deals_bulk_post";
+  createAccountDeal: "create_account_deal_accounts__account_id__deals_post";
+  createDeal: "create_deal_deals_post";
+  createDealCloseReason: "create_deal_close_reason_deals_close_reasons_post";
+  createDealColumn: "create_deal_column_deals_columns_create_post";
+  deleteDeal: "delete_deal_deals__deal_id__delete";
+  deleteDealColumn: "delete_deal_column_deals_columns__column_id__delete";
+  deleteDealDocument: "delete_deal_document_deals__deal_id__documents__document_id__delete";
+  deleteDealNote: "delete_deal_note_deals__deal_id__notes__note_id__delete";
+  generateAllDealDocuments: "generate_all_deal_documents_deals__deal_id__documents_generate_all_post";
+  generateDealDocument: "generate_deal_document_deals__deal_id__documents_types__doc_type__generate_post";
+  getCompanyDeals: "get_company_deals_companies__company_id__deals_get";
+  getContactDeals: "get_contact_deals_contacts__contact_id__deals_get";
+  getDeal: "get_deal_deals__deal_id__get";
+  getDealAnalytics: "get_deal_analytics_deals_analytics_get";
+  getDealCrossfire: "get_deal_crossfire_deals__deal_id__crossfire_get";
+  getDealDetail: "get_deal_detail_deals__deal_id__detail_get";
+  getDealDocument: "get_deal_document_deals__deal_id__documents_types__doc_type__get";
+  getDealDocumentGenerationStatus: "get_deal_document_generation_status_deals__deal_id__documents_generation_status_get";
+  getDealSignals: "get_deal_signals_deals__deal_id__signals_get";
+  getDealStageVelocity: "get_deal_stage_velocity_deals_stage_velocity_get";
+  listAccountDeals: "list_account_deals_accounts__account_id__deals_get";
+  listDealCloseReasons: "list_deal_close_reasons_deals_close_reasons_get";
+  listDealColumns: "list_deal_columns_deals_columns_get";
+  listDealContacts: "list_deal_contacts_deals__deal_id__contacts_get";
+  listDealCustomFieldDiConfig: "list_deal_custom_field_di_config_deals_custom_fields_di_config_get";
+  listDealDocuments: "list_deal_documents_deals__deal_id__documents_get";
+  listDealHistory: "list_deal_history_deals__deal_id__history_get";
+  listDealLineItems: "list_deal_line_items_deals__deal_id__line_items_get";
+  listDeals: "list_deals_deals_get";
+  listPipelines: "list_pipelines_deals_pipelines_get";
+  mergeDeal: "merge_deal_deals__deal_id__merge_post";
+  moveDealToPipeline: "move_deal_to_pipeline_deals__deal_id__pipeline_put";
+  previewDealMerge: "preview_deal_merge_deals__deal_id__merge_preview_get";
+  regenerateDealDocument: "regenerate_deal_document_deals__deal_id__documents_types__doc_type__regenerate_post";
+  removeDealContact: "remove_deal_contact_deals__deal_id__contacts__person_id__delete";
+  replaceDealLineItems: "replace_deal_line_items_deals__deal_id__line_items_put";
+  setDealColumnValues: "set_deal_column_values_deals__deal_id__columns_values_put";
+  setDealCompany: "set_deal_company_deals__deal_id__company_put";
+  setDealContactRole: "set_deal_contact_role_deals__deal_id__contacts__contact_id__put";
+  setPrimaryDealContact: "set_primary_deal_contact_deals__deal_id__contacts__person_id__primary_put";
+  setRivalAttach: "set_rival_attach_deals__deal_id__rival_attach_post";
+  updateDeal: "update_deal_deals__deal_id__patch";
+  updateDealDocument: "update_deal_document_deals__deal_id__documents__document_id__put";
+  updateDealNote: "update_deal_note_deals__deal_id__notes__note_id__put";
+  upsertDealCustomFieldDiConfig: "upsert_deal_custom_field_di_config_deals_custom_fields_di_config_post";
+}
+
+/** Input and output of every `g8.api.deals` operation, keyed by operationId. */
+export interface DealsOperations {
+  /**
+   * POST /deals/{deal_id}/contacts
+   * Add Deal Contact
+   * tier: write · scope: deals:write
+   */
+  add_deal_contact_deals__deal_id__contacts_post: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealContactCreateRequest;
+  };
+    output: ApiResponse_DealContact_;
+  };
+  /**
+   * DELETE /deals/close-reasons/{reason_id}
+   * Archive Deal Close Reason
+   * tier: destructive · scope: deals:delete
+   */
+  archive_deal_close_reason_deals_close_reasons__reason_id__delete: {
+    input: {
+    path: {
+      /** Close reason id. */
+      reason_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /deals/bulk
+   * Bulk Update Deals
+   * tier: write · scope: deals:write
+   */
+  bulk_update_deals_deals_bulk_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BulkDealUpdateRequest;
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * POST /accounts/{account_id}/deals
+   * Create Account Deal
+   * tier: write · scope: deals:write
+   */
+  create_account_deal_accounts__account_id__deals_post: {
+    input: {
+    path: {
+      /** Account the deal belongs to. */
+      account_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AccountDealCreateRequest;
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * POST /deals
+   * Create Deal
+   * tier: write · scope: deals:write
+   */
+  create_deal_deals_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealCreateRequest;
+  };
+    output: ApiResponse_DealResponse_;
+  };
+  /**
+   * POST /deals/close-reasons
+   * Create Deal Close Reason
+   * tier: write · scope: deals:write
+   */
+  create_deal_close_reason_deals_close_reasons_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CloseReasonCreateRequest;
+  };
+    output: ApiResponse_DealOpResponse_;
+  };
+  /**
+   * POST /deals/columns/create
+   * Create Deal Column
+   * tier: write · scope: deals:write
+   */
+  create_deal_column_deals_columns_create_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateDealColumnRequest;
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * DELETE /deals/{deal_id}
+   * Delete Deal
+   * tier: destructive · scope: deals:delete
+   */
+  delete_deal_deals__deal_id__delete: {
+    input: {
+    path: {
+      /** Deal ID (UUID) */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * DELETE /deals/columns/{column_id}
+   * Delete Deal Column
+   * tier: destructive · scope: deals:delete
+   */
+  delete_deal_column_deals_columns__column_id__delete: {
+    input: {
+    path: {
+      /** Column id. */
+      column_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * DELETE /deals/{deal_id}/documents/{document_id}
+   * Delete Deal Document
+   * tier: destructive · scope: deals:delete
+   */
+  delete_deal_document_deals__deal_id__documents__document_id__delete: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+      /** Document id, from the list read. */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DocumentPayload_;
+  };
+  /**
+   * DELETE /deals/{deal_id}/notes/{note_id}
+   * Delete Deal Note
+   * tier: destructive · scope: deals:delete
+   */
+  delete_deal_note_deals__deal_id__notes__note_id__delete: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+      /** Note id. */
+      note_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealOpResponse_;
+  };
+  /**
+   * POST /deals/{deal_id}/documents/generate-all
+   * Generate All Deal Documents
+   * tier: billable · scope: deals:run
+   */
+  generate_all_deal_documents_deals__deal_id__documents_generate_all_post: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DocumentPayload_;
+  };
+  /**
+   * POST /deals/{deal_id}/documents/types/{doc_type}/generate
+   * Generate Deal Document
+   * tier: billable · scope: deals:run
+   */
+  generate_deal_document_deals__deal_id__documents_types__doc_type__generate_post: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+      /** Which generated document. One of the six the deal synthesis produces; anything else is a 422 naming them. */
+      doc_type: "deal_risks" | "next_steps" | "close_plan" | "scope_of_work" | "roi_analysis" | "competitive_analysis";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DocumentPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/deals
+   * Get Company Deals
+   * tier: read · scope: deals:read
+   */
+  get_company_deals_companies__company_id__deals_get: {
+    input: {
+    path: {
+      /** Company ID */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_ContactDealResponse__;
+  };
+  /**
+   * GET /contacts/{contact_id}/deals
+   * Get Contact Deals
+   * tier: read · scope: deals:read
+   */
+  get_contact_deals_contacts__contact_id__deals_get: {
+    input: {
+    path: {
+      /** Contact ID */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_ContactDealResponse__;
+  };
+  /**
+   * GET /deals/{deal_id}
+   * Get Deal
+   * tier: read · scope: deals:read
+   */
+  get_deal_deals__deal_id__get: {
+    input: {
+    path: {
+      /** Deal ID (UUID) */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealResponse_;
+  };
+  /**
+   * GET /deals/analytics
+   * Get Deal Analytics
+   * tier: read · scope: deals:read
+   */
+  get_deal_analytics_deals_analytics_get: {
+    input: {
+    query?: {
+      /** Only this pipeline. */
+      pipeline_id?: string | null;
+      /** Only these owners. Repeatable. */
+      owner_ids?: Array<string> | null;
+      /** Only these stages. Repeatable. */
+      stage_ids?: Array<string> | null;
+      /** Close date lower bound, YYYY-MM-DD. */
+      close_date_from?: string | null;
+      /** Close date upper bound, YYYY-MM-DD. */
+      close_date_to?: string | null;
+      /** Match on deal or account name. */
+      search?: string | null;
+      /** Advanced filter tree as JSON, the same one `GET /deals` accepts. 400 if unparseable. */
+      segmentFilter?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /deals/{deal_id}/crossfire
+   * Get Deal Crossfire
+   * tier: read · scope: deals:read
+   */
+  get_deal_crossfire_deals__deal_id__crossfire_get: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * GET /deals/{deal_id}/detail
+   * Get Deal Detail
+   * tier: read · scope: deals:read
+   */
+  get_deal_detail_deals__deal_id__detail_get: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+    };
+    query?: {
+      /** 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. */
+      include_revision?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealDetail_;
+  };
+  /**
+   * GET /deals/{deal_id}/documents/types/{doc_type}
+   * Get Deal Document
+   * tier: read · scope: deals:read
+   */
+  get_deal_document_deals__deal_id__documents_types__doc_type__get: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+      /** Which generated document. One of the six the deal synthesis produces; anything else is a 422 naming them. */
+      doc_type: "deal_risks" | "next_steps" | "close_plan" | "scope_of_work" | "roi_analysis" | "competitive_analysis";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DocumentPayload_;
+  };
+  /**
+   * GET /deals/{deal_id}/documents/generation-status
+   * Get Deal Document Generation Status
+   * tier: read · scope: deals:read
+   */
+  get_deal_document_generation_status_deals__deal_id__documents_generation_status_get: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DocumentPayload_;
+  };
+  /**
+   * GET /deals/{deal_id}/signals
+   * Get Deal Signals
+   * tier: read · scope: deals:read
+   */
+  get_deal_signals_deals__deal_id__signals_get: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /deals/stage-velocity
+   * Get Deal Stage Velocity
+   * tier: read · scope: deals:read
+   */
+  get_deal_stage_velocity_deals_stage_velocity_get: {
+    input: {
+    query?: {
+      /** Only this pipeline (UUID). */
+      pipeline_id?: string | null;
+      /** Only these owners. Repeatable, at most 100. */
+      owner_ids?: Array<string> | null;
+      /** A deal with no stage change in this many days is 'stuck'. */
+      stuck_threshold_days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealStageVelocityPayload_;
+  };
+  /**
+   * GET /accounts/{account_id}/deals
+   * List Account Deals
+   * tier: read · scope: deals:read
+   */
+  list_account_deals_accounts__account_id__deals_get: {
+    input: {
+    path: {
+      /** Account id. */
+      account_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealListResponse_;
+  };
+  /**
+   * GET /deals/close-reasons
+   * List Deal Close Reasons
+   * tier: read · scope: deals:read
+   */
+  list_deal_close_reasons_deals_close_reasons_get: {
+    input: {
+    query?: {
+      /** Filter to one list, e.g. won or lost. */
+      kind?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CloseReasonListResponse_;
+  };
+  /**
+   * GET /deals/columns
+   * List Deal Columns
+   * tier: read · scope: deals:read
+   */
+  list_deal_columns_deals_columns_get: {
+    input: {
+    query?: {
+      /** Only columns scoped to this list, plus the global ones. Omit for the global set alone. */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealCollectionPayload_;
+  };
+  /**
+   * GET /deals/{deal_id}/contacts
+   * List Deal Contacts
+   * tier: read · scope: deals:read
+   */
+  list_deal_contacts_deals__deal_id__contacts_get: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealContactListResponse_;
+  };
+  /**
+   * GET /deals/custom-fields/di-config
+   * List Deal Custom Field Di Config
+   * tier: read · scope: deals:read
+   */
+  list_deal_custom_field_di_config_deals_custom_fields_di_config_get: {
+    input: {
+    query?: {
+      /** Filter to one CRM provider's mappings. */
+      crm_provider?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CustomFieldDiConfigListResponse_;
+  };
+  /**
+   * GET /deals/{deal_id}/documents
+   * List Deal Documents
+   * tier: read · scope: deals:read
+   */
+  list_deal_documents_deals__deal_id__documents_get: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+    };
+    query?: {
+      /** `strategy` or `analysis`. Not validated by the app - an unrecognised folder matches nothing rather than failing. */
+      folder?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DocumentListPayload_;
+  };
+  /**
+   * GET /deals/{deal_id}/history
+   * List Deal History
+   * tier: read · scope: deals:read
+   */
+  list_deal_history_deals__deal_id__history_get: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+    };
+    query?: {
+      /** The app's cap, and it is a real ceiling rather than a default to raise: a long history pages through `offset`. */
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealCollectionPayload_;
+  };
+  /**
+   * GET /deals/{deal_id}/line-items
+   * List Deal Line Items
+   * tier: read · scope: deals:read
+   */
+  list_deal_line_items_deals__deal_id__line_items_get: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealLineItemsPayload_;
+  };
+  /**
+   * GET /deals
+   * List Deals
+   * tier: read · scope: deals:read
+   */
+  list_deals_deals_get: {
+    input: {
+    query?: {
+      /** Page number */
+      page?: number;
+      /** Items per page */
+      limit?: number;
+      /** Filter by stage ID */
+      stage_id?: string | null;
+      /** Filter by pipeline ID */
+      pipeline_id?: string | null;
+      /** Search by deal name */
+      search?: string | null;
+      /** Filter by owner ID */
+      owner_id?: string | null;
+      /** Filter by owner email */
+      owner_email?: string | null;
+      /** 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. */
+      outcome?: ("won" | "lost" | "open") | null;
+      /** 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. */
+      is_closed_won?: boolean | null;
+      /** Only deals last touched before this timestamp */
+      last_activity_before?: string | null;
+      /** 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). */
+      stale_before?: string | null;
+      /** Filter by whether the deal has recorded activity */
+      has_activity?: boolean | null;
+      /** 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. */
+      has_contact?: boolean | null;
+      /** 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 in any window). A naive timestamp is treated as UTC. */
+      close_after?: string | null;
+      /** 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). */
+      close_before?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_DealResponse__;
+  };
+  /**
+   * GET /deals/pipelines
+   * List Pipelines
+   * tier: read · scope: deals:read
+   */
+  list_pipelines_deals_pipelines_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_PipelineResponse__;
+  };
+  /**
+   * POST /deals/{deal_id}/merge
+   * Merge Deal
+   * tier: destructive · scope: deals:delete
+   */
+  merge_deal_deals__deal_id__merge_post: {
+    input: {
+    path: {
+      /** The deal that SURVIVES. */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: MergeDealRequest;
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * PUT /deals/{deal_id}/pipeline
+   * Move Deal To Pipeline
+   * tier: write · scope: deals:write
+   */
+  move_deal_to_pipeline_deals__deal_id__pipeline_put: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealMovePipelineRequest;
+  };
+    output: ApiResponse_DealOpResponse_;
+  };
+  /**
+   * GET /deals/{deal_id}/merge/preview
+   * Preview Deal Merge
+   * tier: read · scope: deals:read
+   */
+  preview_deal_merge_deals__deal_id__merge_preview_get: {
+    input: {
+    path: {
+      /** The deal that SURVIVES. */
+      deal_id: string;
+    };
+    query: {
+      /** The deal that would be merged AWAY. */
+      secondary: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * POST /deals/{deal_id}/documents/types/{doc_type}/regenerate
+   * Regenerate Deal Document
+   * tier: billable · scope: deals:run
+   */
+  regenerate_deal_document_deals__deal_id__documents_types__doc_type__regenerate_post: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+      /** Which generated document. One of the six the deal synthesis produces; anything else is a 422 naming them. */
+      doc_type: "deal_risks" | "next_steps" | "close_plan" | "scope_of_work" | "roi_analysis" | "competitive_analysis";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DocumentPayload_;
+  };
+  /**
+   * DELETE /deals/{deal_id}/contacts/{person_id}
+   * Remove Deal Contact
+   * tier: destructive · scope: deals:delete
+   */
+  remove_deal_contact_deals__deal_id__contacts__person_id__delete: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+      /** Contact id. */
+      person_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+  /**
+   * PUT /deals/{deal_id}/line-items
+   * Replace Deal Line Items
+   * tier: write · scope: deals:write
+   */
+  replace_deal_line_items_deals__deal_id__line_items_put: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealLineItemsReplaceBody;
+  };
+    output: ApiResponse_DealLineItemsPayload_;
+  };
+  /**
+   * PUT /deals/{deal_id}/columns/values
+   * Set Deal Column Values
+   * tier: write · scope: deals:write
+   */
+  set_deal_column_values_deals__deal_id__columns_values_put: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+    };
+    query?: {
+      /** Resolve list-scoped columns against this list. */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SetDealColumnValuesRequest;
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * PUT /deals/{deal_id}/company
+   * Set Deal Company
+   * tier: write · scope: deals:write
+   */
+  set_deal_company_deals__deal_id__company_put: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealCompanyRequest;
+  };
+    output: ApiResponse_DealOpResponse_;
+  };
+  /**
+   * PUT /deals/{deal_id}/contacts/{contact_id}
+   * Set Deal Contact Role
+   * tier: write · scope: deals:write
+   */
+  set_deal_contact_role_deals__deal_id__contacts__contact_id__put: {
+    input: {
+    path: {
+      /** Deal ID (UUID) */
+      deal_id: string;
+      /** mashup_contact_id (BigInt) of a contact already linked to this deal */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealContactRoleUpdateRequest;
+  };
+    output: ApiResponse_ContactBrief_;
+  };
+  /**
+   * PUT /deals/{deal_id}/contacts/{person_id}/primary
+   * Set Primary Deal Contact
+   * tier: write · scope: deals:write
+   */
+  set_primary_deal_contact_deals__deal_id__contacts__person_id__primary_put: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+      /** Contact id to make primary. */
+      person_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DealContact_;
+  };
+  /**
+   * POST /deals/{deal_id}/rival-attach
+   * Set Rival Attach
+   * tier: write · scope: deals:write
+   */
+  set_rival_attach_deals__deal_id__rival_attach_post: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RivalAttachRequest;
+  };
+    output: ApiResponse_DealPayload_;
+  };
+  /**
+   * PATCH /deals/{deal_id}
+   * Update Deal
+   * tier: write · scope: deals:write
+   */
+  update_deal_deals__deal_id__patch: {
+    input: {
+    path: {
+      /** Deal ID (UUID) */
+      deal_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealUpdateRequest;
+  };
+    output: ApiResponse_DealResponse_;
+  };
+  /**
+   * PUT /deals/{deal_id}/documents/{document_id}
+   * Update Deal Document
+   * tier: write · scope: deals:write
+   */
+  update_deal_document_deals__deal_id__documents__document_id__put: {
+    input: {
+    path: {
+      /** Deal id (UUID). */
+      deal_id: string;
+      /** Document id, from the list read. */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealDocumentUpdateRequest;
+  };
+    output: ApiResponse_DocumentPayload_;
+  };
+  /**
+   * PUT /deals/{deal_id}/notes/{note_id}
+   * Update Deal Note
+   * tier: write · scope: deals:write
+   */
+  update_deal_note_deals__deal_id__notes__note_id__put: {
+    input: {
+    path: {
+      /** Deal id. */
+      deal_id: string;
+      /** Note id. */
+      note_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DealNoteUpdateRequest;
+  };
+    output: ApiResponse_DealOpResponse_;
+  };
+  /**
+   * POST /deals/custom-fields/di-config
+   * Upsert Deal Custom Field Di Config
+   * tier: write · scope: deals:write
+   */
+  upsert_deal_custom_field_di_config_deals_custom_fields_di_config_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CustomFieldDiConfigUpsertRequest;
+  };
+    output: ApiResponse_DealOpResponse_;
+  };
+}
+
+// 67 schemas referenced above (the same as G8Contract.<Name>).
+
+/**
+ * Create a deal already attached to an account.
+ *
+ * `POST /deals` creates one standalone. This attaches it in the same call,
+ * which is the difference worth having: a two-step create leaves a window
+ * where the deal exists with no account.
+ */
+export interface AccountDealCreateRequest {
+  amount?: number | null;
+  close_date?: string | null;
+  contact_ids?: Array<string>;
+  currency?: string;
+  description?: string | null;
+  name: string;
+  /** 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. */
+  owner_id?: string | null;
+  pipeline_id?: string | null;
+  products?: Array<string>;
+  /** Stage NAME, not id. */
+  stage?: string;
+  /** Stage id. Takes precedence over `stage`. */
+  stage_id?: string | null;
+}
+
+export interface ApiResponse_CloseReasonListResponse_ {
+  data: CloseReasonListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ContactBrief_ {
+  data: ContactBrief;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CrmRecordPayload_ {
+  data: CrmRecordPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CustomFieldDiConfigListResponse_ {
+  data: CustomFieldDiConfigListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealCollectionPayload_ {
+  data: DealCollectionPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealContactListResponse_ {
+  data: DealContactListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealContact_ {
+  data: DealContact;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealDetail_ {
+  data: DealDetail;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealLineItemsPayload_ {
+  data: DealLineItemsPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealListResponse_ {
+  data: DealListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealOpResponse_ {
+  data: DealOpResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealPayload_ {
+  data: DealPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealResponse_ {
+  data: DealResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DealStageVelocityPayload_ {
+  data: DealStageVelocityPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DocumentListPayload_ {
+  data: DocumentListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DocumentPayload_ {
+  data: DocumentPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_ContactDealResponse__ {
+  data: Array<ContactDealResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_DealResponse__ {
+  data: Array<DealResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_PipelineResponse__ {
+  data: Array<PipelineResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * 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.
+ */
+export interface BulkDealChange {
+  amount?: number | null;
+  close_date?: string | null;
+  currency?: string | null;
+  custom_fields?: Record<string, unknown> | null;
+  description?: string | null;
+  next_step?: string | null;
+  owner_id?: string | null;
+  pipeline_id?: string | null;
+  stage?: string | null;
+  stage_id?: string | null;
+}
+
+/**
+ * Apply one change to up to 100 deals.
+ *
+ * Each deal is checked against the caller's deal scope individually; one the
+ * caller cannot write is reported rather than aborting the batch.
+ */
+export interface BulkDealUpdateRequest {
+  change: BulkDealChange;
+  deal_ids: Array<string>;
+}
+
+/**
+ * Add a close reason.
+ *
+ * Adding one is gated on `_REASON_MUTATE_PERMISSIONS` (the app's own route
+ * gate): deliberately wider than the manager tier - a rep extends the list
+ * inline while closing their own deal - but NOT open to org members with no
+ * deal access. REMOVING one carries the same entry gate plus a creator-or-
+ * manager check, because manager-only removal would make every rep's typo
+ * permanent and org-wide.
+ */
+export interface CloseReasonCreateRequest {
+  /** Which list this reason belongs to, e.g. won or lost. */
+  kind: string;
+  label: string;
+}
+
+/**
+ * The close reasons, plus what this caller may do with them.
+ *
+ * `can_manage` is returned alongside the list ON PURPOSE: it is resolved by
+ * the same rule the archive endpoint enforces, so a UI cannot render a delete
+ * control the backend would refuse - or hide one it would allow.
+ */
+export interface CloseReasonListResponse {
+  /** Whether this caller may archive reasons they did not create. */
+  can_manage?: boolean | null;
+  reasons?: Array<Record<string, unknown>>;
+  [key: string]: unknown;
+}
+
+/**
+ * Lightweight contact summary embedded in deal responses.
+ *
+ * `id` is the canonical `mashup_contact_id` (BigInt), matching how contacts
+ * are addressed everywhere else in the public API (g8_search_contacts,
+ * g8_lookup_person, etc.). `role` is the contact's role within THIS deal
+ * (champion / decision_maker / influencer / blocker / coach / end_user) and
+ * is null when no role was set.
+ */
+export interface ContactBrief {
+  email?: string | null;
+  id: number;
+  name?: string | null;
+  role?: string | null;
+  title?: string | null;
+}
+
+/** Deal response from contact or company deals handler (dict-based). */
+export interface ContactDealResponse {
+  close_date?: string | null;
+  created_at?: string | null;
+  currency?: string | null;
+  deal_id?: string | null;
+  name?: string | null;
+  owner_id?: string | null;
+  pipeline_id?: string | null;
+  role?: string | null;
+  stage?: string | null;
+  value?: number | null;
+}
+
+/** Add a custom column to the deals grid. */
+export interface CreateDealColumnRequest {
+  /** 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. */
+  data_type?: "text" | "int" | "numeric" | "number" | "boolean" | "date";
+  /** Scope the column to one list. Null creates a GLOBAL column. */
+  list_id?: number | null;
+  /** Display name. */
+  title: string;
+}
+
+/**
+ * An open envelope for one record, one dashboard or one job receipt.
+ *
+ * Open because most of these reads are COMPUTED shapes - an engagement
+ * summary, a next-best-step, an intelligence status - that grow with the
+ * product, and dropping a field from an advisory read makes it say "nothing
+ * to report" rather than "we did not tell you".
+ */
+export type CrmRecordPayload = Record<string, unknown>;
+
+/**
+ * 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.
+ */
+export interface CustomFieldDiConfigItem {
+  /** salesforce, hubspot or pipedrive. */
+  crm_provider: string;
+  display_name?: string | null;
+  /** The CRM's own field id. */
+  field_id: string;
+  id?: string | null;
+  include_in_di_summary?: boolean;
+  include_in_forecast_probability?: boolean;
+}
+
+/**
+ * Deal custom-field mappings for a CRM provider.
+ *
+ * This is what a rebuilt deal form needs to know which custom fields exist
+ * and how they map outward - without it a custom UI can render the built-in
+ * columns and nothing else.
+ */
+export interface CustomFieldDiConfigListResponse {
+  configs?: Array<Record<string, unknown>>;
+  total?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Replace the deal custom-field mappings.
+ *
+ * `items` is the FULL desired set for the providers it names, not a delta -
+ * the app upserts what is sent. Capped at 100 by the app; declared here so an
+ * over-long request is a 422 naming the field rather than a failure deeper
+ * in.
+ */
+export interface CustomFieldDiConfigUpsertRequest {
+  items: Array<CustomFieldDiConfigItem>;
+}
+
+/** An open envelope for a LIST result, so a bare list keeps its shape. */
+export interface DealCollectionPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/** Attach or change the company on a deal. */
+export interface DealCompanyRequest {
+  /** 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. */
+  mashup_company_id: number;
+}
+
+/**
+ * One person linked to a deal.
+ *
+ * `role` is the person's role on THIS deal (champion, decision_maker,
+ * influencer, blocker, coach, end_user). `buying_role` is their general
+ * buying role on the contact record and is NOT deal-specific - the two are
+ * separate fields in the app and conflating them loses the distinction
+ * between "who this is" and "what they are to this deal".
+ */
+export interface DealContact {
+  /** General buying role from the contact record. */
+  buying_role?: string | null;
+  created_at?: string | null;
+  email?: string | null;
+  /** Link id, not the person id. */
+  id?: string | null;
+  is_primary?: boolean | null;
+  name?: string | null;
+  person_id?: string | null;
+  /** Role on THIS deal. */
+  role?: string | null;
+  title?: string | null;
+  [key: string]: unknown;
+}
+
+export interface DealContactCreateRequest {
+  /** Contact to link to the deal. */
+  person_id: string;
+  /** 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. */
+  role?: string | null;
+}
+
+/** Everyone linked to a deal. */
+export interface DealContactListResponse {
+  contacts?: Array<DealContact>;
+  total?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Body for `PUT /deals/{deal_id}/contacts/{contact_id}`.
+ *
+ * `role` is REQUIRED but nullable. That combination is the whole point of a
+ * PUT here: `{"role": "champion"}` sets it, `{"role": null}` clears it, and
+ * an empty body `{}` is a 422 rather than a silent no-op — a PUT that says
+ * nothing about the sub-resource it is replacing is a caller bug, and the
+ * alternative (treating omission as "clear") would delete data on a typo.
+ */
+export interface DealContactRoleUpdateRequest {
+  /** 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. */
+  role: string | null;
+}
+
+export interface DealCreateRequest {
+  /** Set true to create a deal even if one already exists for the company */
+  allow_duplicate?: boolean;
+  /** Deal monetary value */
+  amount?: number | null;
+  /** Expected close date (ISO 8601) */
+  close_date?: string | null;
+  /** Deprecated: the company is derived from the contacts. If sent, it must match; otherwise omit it. */
+  company_id?: number | null;
+  /** mashup_contact_ids to associate with the deal (>=1 required; all must share one company) */
+  contact_ids: Array<number>;
+  /** Currency code (default: USD) */
+  currency?: string | null;
+  /** Deal description */
+  description?: string | null;
+  /** Deal name */
+  name: string;
+  /** Deal owner (user id or email). Required. */
+  owner_id: string;
+  /** Pipeline ID (defaults to org default) */
+  pipeline_id?: string | null;
+  /** Stage ID (from /deals/pipelines) */
+  stage_id?: string | null;
+}
+
+/**
+ * One deal, with the related data the detail page reads.
+ *
+ * `revision` is the optimistic-concurrency token. It is `None` when the org
+ * has no canonical revision tracking provisioned - the app degrades rather
+ * than 503ing a read - and a null there means an unconditional save, NOT
+ * revision 1. Do not default it.
+ */
+export interface DealDetail {
+  amount?: number | null;
+  close_date?: string | null;
+  company_id?: string | null;
+  created_at?: string | null;
+  currency?: string | null;
+  description?: string | null;
+  id?: string | null;
+  name?: string | null;
+  owner_id?: string | null;
+  pipeline_id?: string | null;
+  /** Optimistic-concurrency token. None means this org has no revision tracking, so a save is unconditional - it does NOT mean 1. */
+  revision?: number | null;
+  stage?: string | null;
+  stage_id?: string | null;
+  status?: string | null;
+  updated_at?: string | null;
+  [key: string]: unknown;
+}
+
+/**
+ * Edit a generated deal document in place.
+ *
+ * Mirrors `campaign_builder.models.deal_documents.UpdateDealDocumentRequest`.
+ * An omitted field is left alone; `structured_data` REPLACES the stored
+ * object rather than merging into it.
+ */
+export interface DealDocumentUpdateRequest {
+  /** The document body. */
+  content?: string | null;
+  /** The machine-readable half. Replaces, does not merge. */
+  structured_data?: Record<string, unknown> | null;
+}
+
+/**
+ * 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.
+ */
+export interface DealFieldOverride {
+  field: string;
+  winner: "primary" | "secondary";
+}
+
+/** A deal line item. Money fields are in cents. */
+export interface DealLineItemRecord {
+  billing_frequency?: string | null;
+  description?: string | null;
+  discount_pct: number;
+  id: string;
+  line_total: number;
+  manual_product_id?: string | null;
+  product_name: string;
+  quantity: number;
+  sort_order: number;
+  stripe_price_id?: string | null;
+  stripe_product_id?: string | null;
+  unit_amount: number;
+}
+
+/**
+ * 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`.
+ */
+export interface DealLineItemWrite {
+  billing_frequency?: string | null;
+  description?: string | null;
+  discount_pct?: number;
+  /** Id of a manually-defined product. */
+  manual_product_id?: string | null;
+  product_name: string;
+  quantity?: number;
+  sort_order?: number;
+  /** Catalog price id, when catalog-backed. */
+  stripe_price_id?: string | null;
+  /** Catalog product id, when catalog-backed. */
+  stripe_product_id?: string | null;
+  /** Unit price in cents. */
+  unit_amount: number;
+}
+
+/**
+ * A deal's line items with its derived amount and quote-mismatch flag.
+ *
+ * `amount` and `linked_quote_total` are in DOLLARS (the deal's own unit);
+ * line-item money is in cents. `amount_mismatch` is true when the deal amount
+ * and its most authoritative linked quote disagree by more than half a cent.
+ */
+export interface DealLineItemsPayload {
+  amount?: number | null;
+  amount_mismatch?: boolean;
+  currency?: string | null;
+  deal_id: string;
+  line_items?: Array<DealLineItemRecord>;
+  linked_quote_total?: number | null;
+}
+
+/** The FULL desired set of line items. An empty list clears them. */
+export interface DealLineItemsReplaceBody {
+  line_items?: Array<DealLineItemWrite>;
+}
+
+/** A page of deals on one account. */
+export interface DealListResponse {
+  deals?: Array<DealSummary>;
+  total?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Move a deal to a different pipeline.
+ *
+ * The deal keeps its identity and history; only its pipeline and stage
+ * change. Its current stage does NOT carry over - the target pipeline has
+ * its own stages, and the app re-seats the deal within them.
+ */
+export interface DealMovePipelineRequest {
+  /** Pipeline to move the deal into. */
+  target_pipeline_id: string;
+}
+
+export interface DealNoteMention {
+  email?: string | null;
+  id: string;
+  name?: string | null;
+}
+
+/** Rewrite a note's body and its mentions. */
+export interface DealNoteUpdateRequest {
+  /** Full replacement body - this is not a patch. */
+  content: string;
+  /** Who is mentioned AFTER the edit. Omitting someone removes their mention, because the list replaces rather than adds. */
+  mentioned_users?: Array<DealNoteMention>;
+}
+
+/** Whatever the operation returns, carried through whole. */
+export type DealOpResponse = Record<string, unknown>;
+
+/**
+ * An open envelope for a deal, a merge preview or a column result.
+ *
+ * Open because the crossfire and merge-preview payloads are computed shapes
+ * that grow with the product, and a closed model would drop a field from an
+ * ADVISORY read - where a missing signal reads as "nothing to worry about"
+ * rather than "we did not tell you".
+ */
+export type DealPayload = Record<string, unknown>;
+
+export interface DealResponse {
+  amount?: number | null;
+  close_date?: string | null;
+  closed_lost_reason?: string | null;
+  company_id?: unknown | null;
+  contact_count?: number;
+  contacts?: Array<ContactBrief> | null;
+  created_at?: string | null;
+  currency?: string | null;
+  description?: string | null;
+  id?: string | null;
+  last_activity_at?: string | null;
+  name?: string | null;
+  owner_email?: string | null;
+  owner_id?: string | null;
+  owner_name?: string | null;
+  pipeline_id?: string | null;
+  primary_contact?: ContactBrief | null;
+  /** CRM revision after a conditional update */
+  revision?: number | null;
+  stage_id?: string | null;
+  stage_name?: string | null;
+  updated_at?: string | null;
+}
+
+/**
+ * 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.
+ */
+export interface DealStageVelocityBucket {
+  avg_days_in_stage?: number | null;
+  completed_dwells: number;
+  conversion_rate?: number | null;
+  entered_count: number;
+  fell_back_count: number;
+  position: number;
+  progressed_count: number;
+  stage_id: string;
+  stage_name: string;
+  still_in_stage_count: number;
+}
+
+export interface DealStageVelocityPayload {
+  by_stage?: Array<DealStageVelocityBucket>;
+  disclosures?: Array<string>;
+  stuck_deals: DealStageVelocityStuckSummary;
+}
+
+export interface DealStageVelocityStuckDeal {
+  days_in_current_stage: number;
+  deal_id: string;
+  deal_name?: string | null;
+  last_transitioned_at: string;
+  owner_id?: string | null;
+  owner_name?: string | null;
+  stage_id?: string | null;
+  stage_name?: string | null;
+}
+
+/** `total_count` is exact; `deals` is capped at 100 (`truncated` says so). */
+export interface DealStageVelocityStuckSummary {
+  deals?: Array<DealStageVelocityStuckDeal>;
+  threshold_days: number;
+  total_count: number;
+  truncated: boolean;
+}
+
+/** One deal as it appears in a list. */
+export interface DealSummary {
+  amount?: number | null;
+  close_date?: string | null;
+  created_at?: string | null;
+  currency?: string | null;
+  id?: string | null;
+  name?: string | null;
+  owner_id?: string | null;
+  pipeline_id?: string | null;
+  stage?: string | null;
+  status?: string | null;
+  [key: string]: unknown;
+}
+
+export interface DealUpdateRequest {
+  /** mashup_contact_ids to add to the deal (must match the deal's company; idempotent) */
+  add_contact_ids?: Array<number>;
+  /** Deal monetary value */
+  amount?: number | null;
+  /** Expected close date (ISO 8601) */
+  close_date?: string | null;
+  /** 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). */
+  contact_roles?: (Record<string, string | null>) | null;
+  /** Currency code */
+  currency?: string | null;
+  /** Deal description */
+  description?: string | null;
+  /** Apply only if the canonical CRM revision still matches; otherwise return 409. Omit for existing PATCH behavior. */
+  expected_revision?: number | null;
+  /** Deal name */
+  name?: string | null;
+  /** Reassign deal owner (member id, email, or PropelAuth uid). Cannot be cleared. */
+  owner_id?: string | null;
+  /** mashup_contact_ids to remove from the deal (idempotent — unlinked skipped) */
+  remove_contact_ids?: Array<number>;
+  /** Stage ID */
+  stage_id?: string | null;
+}
+
+/**
+ * An open envelope for a LIST result, so a bare list keeps its shape.
+ *
+ * `items` is always present and always the list, whichever key the app used
+ * for it - so a caller can page one way rather than learning six key names.
+ */
+export interface DocumentListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope for one document, folder or questionnaire.
+ *
+ * Open on purpose: a Library document carries extraction metadata, a
+ * questionnaire carries per-provider processing detail, and a generated deal
+ * document carries `structured_data` and `highlights` whose shape is the
+ * generator's rather than this contract's. Pinning those would silently drop
+ * whatever the app learned to return that this file had not caught up on.
+ */
+export type DocumentPayload = Record<string, unknown>;
+
+/**
+ * Merge one deal into another. THE SECONDARY DEAL STOPS EXISTING.
+ *
+ * `secondary_id` is the deal merged AWAY; the deal in the path survives.
+ * Preview it first with `GET /deals/{deal_id}/merge/preview` - that call
+ * says exactly which field values change and which records move.
+ */
+export interface MergeDealRequest {
+  /** Decide individual fields yourself instead of taking the app's rules. */
+  field_overrides?: Array<DealFieldOverride>;
+  /** The deal to merge AWAY. Must be a UUID; the path deal survives. */
+  secondary_id: string;
+  /** The duplicate-suggestion this merge acts on, if any. */
+  suggestion_id?: string | null;
+  /** What prompted the merge. Recorded on the audit row. */
+  trigger?: "manual" | "queue" | "bulk_criterion";
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+export interface PipelineResponse {
+  id: string;
+  is_default?: boolean;
+  name: string;
+  stages?: Array<PipelineStageResponse>;
+}
+
+export interface PipelineStageResponse {
+  channel_scripts?: Record<string, string>;
+  color?: string | null;
+  id: string;
+  name: string;
+  position?: number | null;
+  probability?: number | null;
+  recommended_elements?: Array<string>;
+  required_elements?: Array<string>;
+  stage_type?: string | null;
+}
+
+/** Record which competitor is on a deal, and how it is going. */
+export interface RivalAttachRequest {
+  /** The competitor. Null detaches the current one. */
+  competitor_id?: string | null;
+  /** Where the deal stands against them. */
+  status: string;
+}
+
+/**
+ * Write custom column values on one deal.
+ *
+ * `null` CLEARS a value rather than leaving it alone - this is a write of
+ * exactly what you send, not a patch that skips nulls.
+ */
+export interface SetDealColumnValuesRequest {
+  /** Column key -> value. A null clears that column. */
+  values: Record<string, string | number | boolean | null>;
+}