@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/lists.d.ts

@@ -0,0 +1,1106 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.lists` (Lists): 36 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"add_contacts_to_list_lists__list_id__contacts_post">;
+ *
+ * Reference with examples: lists.md
+ */
+/* eslint-disable */
+
+/** `g8.api.lists.<member>` -> the operationId it calls. */
+export interface ListsMembers {
+  addContactsToList: "add_contacts_to_list_lists__list_id__contacts_post";
+  addDealsToList: "add_deals_to_list_lists__audience_id__deals_post";
+  assignListToFolder: "assign_list_to_folder_lists_folders_assignments__audience_id__put";
+  assignListsToFolder: "assign_lists_to_folder_lists_folders_assignments_put";
+  checkListIntegrity: "check_list_integrity_lists__list_id__integrity_check_post";
+  createEmptyList: "create_empty_list_lists_create_empty_post";
+  createList: "create_list_lists_post";
+  createListFolder: "create_list_folder_lists_folders_post";
+  createMasterList: "create_master_list_lists_masters_post";
+  deleteCompaniesFromList: "delete_companies_from_list_lists__audience_id__companies_delete";
+  deleteLeadsFromList: "delete_leads_from_list_lists__audience_id__leads_delete";
+  deleteList: "delete_list_lists__list_id__delete";
+  deleteListFolder: "delete_list_folder_lists_folders__folder_id__delete";
+  deleteSuppressionsFromList: "delete_suppressions_from_list_lists__audience_id__suppressions_delete";
+  downloadList: "download_list_lists__audience_id__download_get";
+  generateTrackedLinks: "generate_tracked_links_lists__audience_id__generate_tracked_links_post";
+  getListColumnCapabilities: "get_list_column_capabilities_lists__audience_id__column_capabilities_get";
+  getListContacts: "get_list_contacts_lists__list_id__contacts_get";
+  getListKeywordLinks: "get_list_keyword_links_lists__audience_id__keyword_links_get";
+  getListPerformance: "get_list_performance_lists_performance_get";
+  getTrackedLinkColumns: "get_tracked_link_columns_lists__audience_id__tracked_links_columns_get";
+  listDataColumns: "list_data_columns_lists__list_id__data_columns_get";
+  listListFolders: "list_list_folders_lists_folders_get";
+  listLists: "list_lists_lists_get";
+  listMasterLists: "list_master_lists_lists_masters_get";
+  patchDynamicValue: "patch_dynamic_value_lists__audience_id__dynamic_value_patch";
+  previewListOwnerTransfer: "preview_list_owner_transfer_lists__audience_id__owner_preview_get";
+  reassignListOwner: "reassign_list_owner_lists__audience_id__owner_patch";
+  recordListOpened: "record_list_opened_lists_folders_activity__audience_id__post";
+  refreshDynamicList: "refresh_dynamic_list_lists__audience_id__refresh_post";
+  refreshMasterListNow: "refresh_master_list_now_lists__audience_id__master_refresh_post";
+  removeContactsFromList: "remove_contacts_from_list_lists__list_id__contacts_delete";
+  starList: "star_list_lists_folders_stars__audience_id__put";
+  updateList: "update_list_lists__list_id__patch";
+  updateListFolder: "update_list_folder_lists_folders__folder_id__patch";
+  updateMasterListConfig: "update_master_list_config_lists__audience_id__master_config_patch";
+}
+
+/** Input and output of every `g8.api.lists` operation, keyed by operationId. */
+export interface ListsOperations {
+  /**
+   * POST /lists/{list_id}/contacts
+   * Add Contacts To List
+   * tier: write · scope: lists:write
+   */
+  add_contacts_to_list_lists__list_id__contacts_post: {
+    input: {
+    path: {
+      /** List ID */
+      list_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AddContactsToListRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /lists/{audience_id}/deals
+   * Add Deals To List
+   * tier: write · scope: lists:write
+   */
+  add_deals_to_list_lists__audience_id__deals_post: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AddDealsToListRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * PUT /lists/folders/assignments/{audience_id}
+   * Assign List To Folder
+   * tier: write · scope: lists:write
+   */
+  assign_list_to_folder_lists_folders_assignments__audience_id__put: {
+    input: {
+    path: {
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ListFolderAssignRequest;
+  };
+    output: void;
+  };
+  /**
+   * PUT /lists/folders/assignments
+   * Assign Lists To Folder
+   * tier: write · scope: lists:write
+   */
+  assign_lists_to_folder_lists_folders_assignments_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ListFolderBulkAssignRequest;
+  };
+    output: void;
+  };
+  /**
+   * POST /lists/{list_id}/integrity-check
+   * Check List Integrity
+   * tier: read · scope: lists:read
+   */
+  check_list_integrity_lists__list_id__integrity_check_post: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      list_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: IntegrityCheckRequest;
+  };
+    output: ApiResponse_SequencerPayload_;
+  };
+  /**
+   * POST /lists/create-empty
+   * Create Empty List
+   * tier: write · scope: lists:write
+   */
+  create_empty_list_lists_create_empty_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateEmptyListRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * POST /lists
+   * Create List
+   * tier: write · scope: lists:write
+   */
+  create_list_lists_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ListCreateRequest;
+  };
+    output: ApiResponse_ListCreateResponse_;
+  };
+  /**
+   * POST /lists/folders
+   * Create List Folder
+   * tier: write · scope: lists:write
+   */
+  create_list_folder_lists_folders_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ListFolderCreateRequest;
+  };
+    output: ApiResponse_ListFolderResponse_;
+  };
+  /**
+   * POST /lists/masters
+   * Create Master List
+   * tier: write · scope: lists:write
+   */
+  create_master_list_lists_masters_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateMasterListRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * DELETE /lists/{audience_id}/companies
+   * Delete Companies From List
+   * tier: destructive · scope: lists:delete
+   */
+  delete_companies_from_list_lists__audience_id__companies_delete: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    query?: {
+      /** AgGrid filter JSON. Every company in the list matching it is removed, IN ADDITION to `company_ids` - the two combine rather than the filter narrowing the ids. */
+      agFilterModel?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DeleteCompaniesFromListRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * DELETE /lists/{audience_id}/leads
+   * Delete Leads From List
+   * tier: destructive · scope: lists:delete
+   */
+  delete_leads_from_list_lists__audience_id__leads_delete: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DeleteLeadsFromListRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * DELETE /lists/{list_id}
+   * Delete List
+   * tier: destructive · scope: lists:delete
+   */
+  delete_list_lists__list_id__delete: {
+    input: {
+    path: {
+      /** List ID */
+      list_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * DELETE /lists/folders/{folder_id}
+   * Delete List Folder
+   * tier: destructive · scope: lists:delete
+   */
+  delete_list_folder_lists_folders__folder_id__delete: {
+    input: {
+    path: {
+      /** Folder id. */
+      folder_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+  /**
+   * DELETE /lists/{audience_id}/suppressions
+   * Delete Suppressions From List
+   * tier: destructive · scope: lists:delete
+   */
+  delete_suppressions_from_list_lists__audience_id__suppressions_delete: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DeleteSuppressionsFromListRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * GET /lists/{audience_id}/download
+   * Download List
+   * tier: read · scope: lists:read
+   */
+  download_list_lists__audience_id__download_get: {
+    input: {
+    path: {
+      audience_id: number;
+    };
+    query?: {
+      /** `csv` or `xlsx`. */
+      format?: "csv" | "xlsx";
+      /** Only these columns. Omit for every column. LinkedIn profile URLs are always kept, as in the app. */
+      columns?: Array<string> | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListDownloadPayload_;
+  };
+  /**
+   * POST /lists/{audience_id}/generate-tracked-links
+   * Generate Tracked Links
+   * tier: write · scope: lists:write
+   */
+  generate_tracked_links_lists__audience_id__generate_tracked_links_post: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: GenerateTrackedLinksRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * GET /lists/{audience_id}/column-capabilities
+   * Get List Column Capabilities
+   * tier: read · scope: lists:read
+   */
+  get_list_column_capabilities_lists__audience_id__column_capabilities_get: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    query: {
+      /** Which grid's columns: contacts or companies. */
+      object_type: "mashup_contacts" | "mashup_companies";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * GET /lists/{list_id}/contacts
+   * Get List Contacts
+   * tier: read · scope: lists:read
+   */
+  get_list_contacts_lists__list_id__contacts_get: {
+    input: {
+    path: {
+      /** List ID */
+      list_id: number;
+    };
+    query?: {
+      /** Page number (1-indexed) */
+      page?: number;
+      /** Items per page (max 200) */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_ContactListItem__;
+  };
+  /**
+   * GET /lists/{audience_id}/keyword-links
+   * Get List Keyword Links
+   * tier: read · scope: lists:read
+   */
+  get_list_keyword_links_lists__audience_id__keyword_links_get: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListCollectionPayload_;
+  };
+  /**
+   * GET /lists/performance
+   * Get List Performance
+   * tier: read · scope: lists:read
+   */
+  get_list_performance_lists_performance_get: {
+    input: {
+    query?: {
+      /** Filter to a single list. Omit for all lists. */
+      list_id?: number | null;
+      /** Restrict sends/events to the last N days. Omit for all-time. Ignored when start_date and end_date are both supplied. */
+      days?: number | null;
+      /** Inclusive start of an anchored range, `YYYY-MM-DD`. Requires end_date. */
+      start_date?: string | null;
+      /** Inclusive end of an anchored range, `YYYY-MM-DD`. */
+      end_date?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListPerformanceResponse_;
+  };
+  /**
+   * GET /lists/{audience_id}/tracked-links/columns
+   * Get Tracked Link Columns
+   * tier: read · scope: lists:read
+   */
+  get_tracked_link_columns_lists__audience_id__tracked_links_columns_get: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * GET /lists/{list_id}/data-columns
+   * List Data Columns
+   * tier: read · scope: lists:read
+   */
+  list_data_columns_lists__list_id__data_columns_get: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      list_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SequencerListPayload_;
+  };
+  /**
+   * GET /lists/folders
+   * List List Folders
+   * tier: read · scope: lists:read
+   */
+  list_list_folders_lists_folders_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListFolderIndexResponse_;
+  };
+  /**
+   * GET /lists
+   * List Lists
+   * tier: read · scope: lists:read
+   */
+  list_lists_lists_get: {
+    input: {
+    query?: {
+      /** Page number (1-indexed) */
+      page?: number;
+      /** Items per page (max 200) */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_ListResponse__;
+  };
+  /**
+   * GET /lists/masters
+   * List Master Lists
+   * tier: read · scope: lists:read
+   */
+  list_master_lists_lists_masters_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListCollectionPayload_;
+  };
+  /**
+   * PATCH /lists/{audience_id}/dynamic-value
+   * Patch Dynamic Value
+   * tier: write · scope: lists:write
+   */
+  patch_dynamic_value_lists__audience_id__dynamic_value_patch: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PatchDynamicValueRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * GET /lists/{audience_id}/owner/preview
+   * Preview List Owner Transfer
+   * tier: read · scope: lists:read
+   */
+  preview_list_owner_transfer_lists__audience_id__owner_preview_get: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    query: {
+      /** Candidate owner's PropelAuth user id. */
+      new_owner_user_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * PATCH /lists/{audience_id}/owner
+   * Reassign List Owner
+   * tier: write · scope: lists:write
+   */
+  reassign_list_owner_lists__audience_id__owner_patch: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ReassignListOwnerRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * POST /lists/folders/activity/{audience_id}
+   * Record List Opened
+   * tier: write · scope: lists:write
+   */
+  record_list_opened_lists_folders_activity__audience_id__post: {
+    input: {
+    path: {
+      /** The list (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+  /**
+   * POST /lists/{audience_id}/refresh
+   * Refresh Dynamic List
+   * tier: write · scope: lists:write
+   */
+  refresh_dynamic_list_lists__audience_id__refresh_post: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * POST /lists/{audience_id}/master-refresh
+   * Refresh Master List Now
+   * tier: write · scope: lists:write
+   */
+  refresh_master_list_now_lists__audience_id__master_refresh_post: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ListPayload_;
+  };
+  /**
+   * DELETE /lists/{list_id}/contacts
+   * Remove Contacts From List
+   * tier: destructive · scope: lists:delete
+   */
+  remove_contacts_from_list_lists__list_id__contacts_delete: {
+    input: {
+    path: {
+      /** List ID */
+      list_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RemoveContactsFromListRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * PUT /lists/folders/stars/{audience_id}
+   * Star List
+   * tier: write · scope: lists:write
+   */
+  star_list_lists_folders_stars__audience_id__put: {
+    input: {
+    path: {
+      /** The list (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ListStarRequest;
+  };
+    output: void;
+  };
+  /**
+   * PATCH /lists/{list_id}
+   * Update List
+   * tier: write · scope: lists:write
+   */
+  update_list_lists__list_id__patch: {
+    input: {
+    path: {
+      /** List ID */
+      list_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ListUpdateRequest;
+  };
+    output: ApiResponse_ListResponse_;
+  };
+  /**
+   * PATCH /lists/folders/{folder_id}
+   * Update List Folder
+   * tier: write · scope: lists:write
+   */
+  update_list_folder_lists_folders__folder_id__patch: {
+    input: {
+    path: {
+      /** Folder id. */
+      folder_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ListFolderUpdateRequest;
+  };
+    output: ApiResponse_ListFolderResponse_;
+  };
+  /**
+   * PATCH /lists/{audience_id}/master-config
+   * Update Master List Config
+   * tier: write · scope: lists:write
+   */
+  update_master_list_config_lists__audience_id__master_config_patch: {
+    input: {
+    path: {
+      /** List (audience) id. */
+      audience_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: UpdateMasterListConfigRequest;
+  };
+    output: ApiResponse_ListPayload_;
+  };
+}
+
+// 46 schemas referenced above (the same as G8Contract.<Name>).
+
+/** Request body for adding contacts to a list. */
+export interface AddContactsToListRequest {
+  /** Required on retry after a 409 CONFLICT_REVIEW_REQUIRED response: 'add_all' adds ready + every warned contact, 'skip_all' adds only ready contacts, 'custom' adds ready + the ids in include_warned_ids. Blocked contacts are always excluded regardless of this value. */
+  conflict_resolution?: ("add_all" | "skip_all" | "custom") | null;
+  /** List of contact IDs to add */
+  contact_ids: Array<number>;
+  /** With conflict_resolution='custom', the warned contact ids to also add. */
+  include_warned_ids?: Array<string> | null;
+}
+
+/**
+ * Put deals on a deals list.
+ *
+ * Deal ids are STRINGS here while contact, company, suppression and lead ids
+ * are integers. That is the app's own typing and it is mirrored rather than
+ * smoothed over: coercing would make a mistyped id a silent miss.
+ */
+export interface AddDealsToListRequest {
+  /** Deal ids (strings, unlike the others). */
+  deal_ids: Array<string>;
+  /** Where the addition came from, for the audit trail. */
+  source?: string | null;
+}
+
+export interface ApiResponse_ListCollectionPayload_ {
+  data: ListCollectionPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ListCreateResponse_ {
+  data: ListCreateResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ListDownloadPayload_ {
+  data: ListDownloadPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ListFolderIndexResponse_ {
+  data: ListFolderIndexResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ListFolderResponse_ {
+  data: ListFolderResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ListPayload_ {
+  data: ListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ListPerformanceResponse_ {
+  data: ListPerformanceResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ListResponse_ {
+  data: ListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SequencerListPayload_ {
+  data: SequencerListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SequencerPayload_ {
+  data: SequencerPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_ContactListItem__ {
+  data: Array<ContactListItem>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_ListResponse__ {
+  data: Array<ListResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/** Lighter contact representation for list endpoints. */
+export interface ContactListItem {
+  city?: string | null;
+  company_id?: number | null;
+  country?: string | null;
+  custom_fields?: (Record<string, string | null>) | null;
+  direct_phone?: string | null;
+  first_name?: string | null;
+  id?: number | null;
+  job_department?: string | null;
+  job_title?: string | null;
+  last_name?: string | null;
+  linkedin_url?: string | null;
+  mobile_phone?: string | null;
+  owner_id?: string | null;
+  owner_name?: string | null;
+  seniority_level?: string | null;
+  state?: string | null;
+  work_email?: string | null;
+}
+
+/**
+ * Create a list with nothing in it, to fill later.
+ *
+ * `idempotency_key` is worth using: without one, a retried create makes a
+ * SECOND empty list, and a duplicate list is harder to notice than a failed
+ * request.
+ */
+export interface CreateEmptyListRequest {
+  description?: string | null;
+  /** Retry-safe: the same key returns the same list. */
+  idempotency_key?: string | null;
+  /** A dynamic list re-runs its query; a static one keeps what it is given. */
+  is_dynamic?: boolean;
+  request_fingerprint?: string | null;
+  /** Where the list comes from, e.g. `csv`. */
+  source: "csv" | "graph8" | "FormSubmission" | "visitor" | "salesforce" | "hubspot" | "keyword" | "intent" | "workbench";
+  status?: "completed" | "processing" | "failed";
+  title: string;
+  /** What the list holds. The wire name is `type`; the app's field is `type_` because `type` is a Python builtin, and the alias keeps the wire name identical to the app's. */
+  type?: "contacts" | "companies" | "suppressions" | "deals" | "leads";
+}
+
+/** A list that is the UNION of other lists, kept in sync. */
+export interface CreateMasterListRequest {
+  /** Take EVERY list of this type instead of the named ones, including ones created later. `source_list_ids` is then ignored. */
+  include_all_sources?: boolean;
+  /** The lists to union. */
+  source_list_ids?: Array<number>;
+  title: string;
+  /** Wire name is `type`; see `CreateEmptyListRequest`. */
+  type?: "contacts" | "companies" | "suppressions" | "deals" | "leads";
+}
+
+export interface DeleteCompaniesFromListRequest {
+  company_ids?: Array<number>;
+}
+
+export interface DeleteLeadsFromListRequest {
+  /** The leads to remove. */
+  lead_ids: Array<number>;
+}
+
+export interface DeleteSuppressionsFromListRequest {
+  /** The suppressions to remove. */
+  suppression_ids: Array<number>;
+}
+
+/** Mint one tracked URL per row, into a column on the list. */
+export interface GenerateTrackedLinksRequest {
+  /** Column to write the links into. */
+  column_title?: string | null;
+  /** Absolute http(s) URL every link points at. */
+  destination_url: string;
+  /** What this set of links is called. */
+  link_name: string;
+  /** Query parameters to interpolate per row, e.g. {'utm_term': '{company}'}. */
+  params_template?: Record<string, string>;
+  /** Where the token goes on a NON-shortened URL: `fragment` (#t=…) or `query` (?g8t=…). Ignored when `shorten` is on. */
+  placement?: "fragment" | "query";
+  /** Use the short-link domain. */
+  shorten?: boolean;
+  stream_id?: string | null;
+}
+
+/** Which fields to measure. Mirrors the app's `IntegrityCheckRequest`. */
+export interface IntegrityCheckRequest {
+  /** Enrichment / AI / dynamic columns to measure on top of the default fields - the `column_name_db` values from `GET /lists/{list_id}/data-columns`. */
+  extra_fields?: Array<string> | null;
+}
+
+/** An open envelope for a LIST result, so a bare list keeps its shape. */
+export interface ListCollectionPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/** Request body for creating a new list. */
+export interface ListCreateRequest {
+  /** Optional note describing the list's purpose, readable by agents (#16641) */
+  description?: string | null;
+  /** Name of the list */
+  title: string;
+  /** List type: contacts, companies, suppressions, deals, leads */
+  type?: string;
+}
+
+export interface ListCreateResponse {
+  description?: string | null;
+  id: number;
+  status?: string | null;
+  title: string;
+  total?: number;
+  type?: string | null;
+}
+
+/**
+ * A list's rows as a file, inside the JSON envelope.
+ *
+ * CSV comes back as text (`encoding: "utf-8"`). XLSX is binary, so it comes
+ * back base64-encoded (`encoding: "base64"`); decode it to get the workbook.
+ */
+export interface ListDownloadPayload {
+  content: string;
+  encoding: "utf-8" | "base64";
+  filename: string;
+  format: "csv" | "xlsx";
+  media_type: string;
+}
+
+/** File one list into a folder. */
+export interface ListFolderAssignRequest {
+  /** The folder. Null takes the list OUT of every folder. */
+  folder_id?: string | null;
+}
+
+/** File several lists into one folder. */
+export interface ListFolderBulkAssignRequest {
+  /** The lists to move, 1 to 500. */
+  audience_ids: Array<number>;
+  /** The folder. Null takes the list OUT of every folder. */
+  folder_id?: string | null;
+}
+
+export interface ListFolderCreateRequest {
+  /** Folder title. */
+  title: string;
+  /** Defaults to `private` when omitted. */
+  visibility?: ("private" | "org") | null;
+}
+
+/**
+ * Folders the caller owns, plus org-visible folders owned by teammates.
+ *
+ * `folders` keeps its existing meaning - "mine". `shared_folders` is
+ * browse-only, mirroring the app so a rebuilt UI can render the same split.
+ */
+export interface ListFolderIndexResponse {
+  /** Map of list id -> folder id for every filed list. */
+  assignments?: Record<string, string>;
+  folders?: Array<ListFolderResponse>;
+  shared_folders?: Array<ListFolderResponse>;
+  /** List ids the caller has starred. */
+  starred_ids?: Array<number>;
+}
+
+/** A folder a developer can group lists into. */
+export interface ListFolderResponse {
+  created_at?: string | null;
+  /** User id that created the folder. */
+  created_by: string;
+  /** Folder id. */
+  id: string;
+  /** True when the calling key's org owns the folder. */
+  is_owner: boolean;
+  /** Number of lists currently filed in this folder. */
+  list_count: number;
+  /** Display title. */
+  title: string;
+  updated_at?: string | null;
+  /** `private` (owner only) or `org` (browse-only for teammates). */
+  visibility: string;
+}
+
+/** Either field may be changed independently; omit a field to leave it. */
+export interface ListFolderUpdateRequest {
+  title?: string | null;
+  visibility?: ("private" | "org") | null;
+}
+
+/**
+ * An open envelope for a list, a capability map or a job result.
+ *
+ * Open because several of these return the whole `Audience`, whose shape
+ * carries per-source metadata that differs between an uploaded file, a
+ * dynamic query and a master list - and grows with them.
+ */
+export type ListPayload = Record<string, unknown>;
+
+/** Per-list engagement counters. Fields mirror the app's own item. */
+export interface ListPerformanceItem {
+  list_id?: number | null;
+  title?: string | null;
+  [key: string]: unknown;
+}
+
+export interface ListPerformanceResponse {
+  items?: Array<ListPerformanceItem>;
+}
+
+/** Audience/list representation for the public API. */
+export interface ListResponse {
+  created_at?: string | null;
+  created_by?: string | null;
+  /** Agent/human-readable note describing the list's purpose (#16641) */
+  description?: string | null;
+  id: number;
+  is_dynamic?: boolean;
+  /** Source of the list */
+  source?: string | null;
+  status?: string | null;
+  tags?: Array<string>;
+  title: string;
+  total?: number;
+  /** List type (contacts, companies, suppressions, deals, leads) */
+  type?: string | null;
+  updated_at?: string | null;
+}
+
+/** Star or unstar a list. */
+export interface ListStarRequest {
+  /** True to star, false to unstar. */
+  starred: boolean;
+}
+
+/** Request body for updating an existing list's name and/or description. */
+export interface ListUpdateRequest {
+  /** New purpose note for the list (#16641). Omit to leave the current description unchanged; send an empty string to clear it. */
+  description?: string | null;
+  /** New name for the list */
+  title: string;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * Write one cell of a user-owned dynamic column.
+ *
+ * `expected_value` is an optimistic-concurrency check: send what you believe
+ * is there and the write is refused if it has moved. Omit it and the write
+ * wins unconditionally, which on a shared grid means overwriting a
+ * colleague's edit without knowing.
+ */
+export interface PatchDynamicValueRequest {
+  /** Dynamic column key, e.g. `udo_notes`. */
+  column_key: string;
+  /** Refuse the write unless the cell still holds this. Omit to force. */
+  expected_value?: unknown | null;
+  object_type: "mashup_contacts" | "mashup_companies";
+  /** Grid row id. */
+  record_id: number;
+  /** New value. Null CLEARS the cell. */
+  value?: unknown | null;
+}
+
+/**
+ * Hand a list to someone else.
+ *
+ * `mode` decides how far the transfer reaches, and the difference is not
+ * cosmetic: `list_and_records` re-owns every CONTACT in the list as well,
+ * which changes who can see them under record-level scoping. Preview it
+ * first with `GET /lists/{id}/owner/preview`.
+ */
+export interface ReassignListOwnerRequest {
+  /** `list_only` moves just the list. `list_and_records` also re-owns every record in it, which can change who else can see them. */
+  mode?: "list_only" | "list_and_records";
+  /** Must agree with the user id - the app verifies both. Typed as an email at the request layer because the app's model is `EmailStr` and is built inside the handler: a malformed address would otherwise raise there and escape as a 500 rather than a 422. */
+  owner_email: string;
+  owner_user_id: string;
+}
+
+/** Request body for removing contacts from a list. */
+export interface RemoveContactsFromListRequest {
+  /** List of contact IDs to remove */
+  contact_ids: Array<number>;
+}
+
+/** An open envelope around a LIST of sequencer records, as `items`. */
+export interface SequencerListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope around one sequencer record.
+ *
+ * Open because templates, schedules and channels carry nested step data and
+ * configuration that grows as channels are added.
+ */
+export type SequencerPayload = Record<string, unknown>;
+
+/**
+ * Replace a master list's sources.
+ *
+ * A REPLACE, not a merge: a source you omit stops feeding the master list.
+ * Saved synchronously, and the re-sync runs in the background afterwards, so
+ * a 200 here means the config is stored, not that the membership has caught
+ * up.
+ */
+export interface UpdateMasterListConfigRequest {
+  include_all_sources?: boolean;
+  source_list_ids?: Array<number>;
+}