@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/events.d.ts

@@ -0,0 +1,115 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.events` (Events): 1 operation.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"list_org_events_events_get">;
+ *
+ * Reference with examples: events.md
+ */
+/* eslint-disable */
+
+/** `g8.api.events.<member>` -> the operationId it calls. */
+export interface EventsMembers {
+  listOrgEvents: "list_org_events_events_get";
+}
+
+/** Input and output of every `g8.api.events` operation, keyed by operationId. */
+export interface EventsOperations {
+  /**
+   * GET /events
+   * List Org Events
+   * tier: read · scope: analytics:read
+   */
+  list_org_events_events_get: {
+    input: {
+    query?: {
+      /** Filter by event type (repeatable), e.g. sequencer, inbox, voiceai. */
+      type?: Array<string> | null;
+      /** Filter by event name (repeatable), e.g. sequence_email_replied. */
+      name?: Array<string> | null;
+      /** Filter by producing service. */
+      source?: string | null;
+      /** Only events whose message.contact_id matches. */
+      contact_id?: string | null;
+      /** Only events whose message.sequence_id matches. */
+      sequence_id?: string | null;
+      /** Only events whose message.campaign_id matches. */
+      campaign_id?: string | null;
+      /** Window start (ISO 8601). Defaults to 7 days before `until`. */
+      since?: string | null;
+      /** Window end, exclusive (ISO 8601). Defaults to now. */
+      until?: string | null;
+      /** `next_cursor` from the previous page. */
+      cursor?: string | null;
+      /** Page size. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgEventFeedPage_;
+  };
+}
+
+// 4 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_OrgEventFeedPage_ {
+  data: OrgEventFeedPage;
+  pagination?: PaginationMeta | null;
+}
+
+/** A page of events, newest first. */
+export interface OrgEventFeedPage {
+  events?: Array<OrgEventItem>;
+  /** Whether another page exists within the requested window. */
+  has_more?: boolean;
+  /** Pass back as `cursor` to fetch the next (older) page. Null when there are no more. */
+  next_cursor?: string | null;
+  /** Lower bound of the window that was searched (ISO 8601, UTC). */
+  since: string;
+  /** Upper bound of the window that was searched (ISO 8601, UTC). */
+  until: string;
+}
+
+/** One event from the org's event store. */
+export interface OrgEventItem {
+  /** The event's context email: the acting user, recipient or a system actor address. */
+  actor_email?: string | null;
+  /** message.campaign_id, when the event carries one. */
+  campaign_id?: string | null;
+  /** message.contact_id, when the event carries one. */
+  contact_id?: string | null;
+  /** Event uid. Stable across reads; use it to de-duplicate. */
+  id?: string | null;
+  /** The event payload exactly as produced. */
+  message?: Record<string, unknown>;
+  /** Event name, e.g. sequence_email_sent, inbox.email_received, sdr.call_ended, booking_created. */
+  name?: string | null;
+  /** When the event happened (ISO 8601, UTC). */
+  occurred_at?: string | null;
+  /** message.sequence_id, when the event carries one. */
+  sequence_id?: string | null;
+  /** Producing service, e.g. sequencer, voiceai-service. */
+  source?: string | null;
+  /** Event family, e.g. sequencer, inbox, voiceai, appointments, crm, deals, quotes, newsletter, uui, mcp, internal. Web-tracking rows carry the tracker's type (e.g. page). */
+  type?: string | null;
+  /** Page URL, for web-tracking rows. */
+  url?: string | null;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}

package/docs/api/events.md

@@ -0,0 +1,105 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.events`: Events
+
+1 operation (1 read).
+
+No hand-written client covers this area. Call it through `g8.api.events.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+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: [events.d.ts](events.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`listOrgEvents`](#op-listorgevents) | `GET /api/v1/events` | read | `analytics:read` | List Org Events |
+
+---
+
+<a id="op-listorgevents"></a>
+
+### `g8.api.events.listOrgEvents(input?)`
+
+**List Org Events**
+
+- HTTP: `GET /api/v1/events`
+- operationId: `list_org_events_events_get` (also callable as `g8.api.call("list_org_events_events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+List the organisation's events, newest first, with cursor pagination.
+
+Covers every event the EDA pipeline stores for the org plus website tracking
+rows. Filters combine with AND. Pages are stable under concurrent writes:
+the cursor encodes the last (timestamp, uid) seen.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.type` | `Array<string> \| null` | no | Filter by event type (repeatable), e.g. sequencer, inbox, voiceai. |
+| `query.name` | `Array<string> \| null` | no | Filter by event name (repeatable), e.g. sequence_email_replied. |
+| `query.source` | `string \| null` | no | Filter by producing service. |
+| `query.contact_id` | `string \| null` | no | Only events whose message.contact_id matches. |
+| `query.sequence_id` | `string \| null` | no | Only events whose message.sequence_id matches. |
+| `query.campaign_id` | `string \| null` | no | Only events whose message.campaign_id matches. |
+| `query.since` | `string (date-time) \| null` | no | Window start (ISO 8601). Defaults to 7 days before `until`. |
+| `query.until` | `string (date-time) \| null` | no | Window end, exclusive (ISO 8601). Defaults to now. |
+| `query.cursor` | `string \| null` | no | `next_cursor` from the previous page. |
+| `query.limit` | `integer` | no | Page size. default `50` |
+
+**Returns** `ApiResponse_OrgEventFeedPage_`: the envelope `{ data: OrgEventFeedPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgEventFeedPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `since` | `string` | yes | Lower bound of the window that was searched (ISO 8601, UTC). |
+| `until` | `string` | yes | Upper bound of the window that was searched (ISO 8601, UTC). |
+| `events` | `Array<OrgEventItem>` | no |  |
+| `has_more` | `boolean` | no | Whether another page exists within the requested window. default `false` |
+| `next_cursor` | `string \| null` | no | Pass back as `cursor` to fetch the next (older) page. Null when there are no more. |
+
+**Example**
+
+```ts
+const result = await g8.api.events.listOrgEvents();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-orgeventitem"></a>
+
+### `OrgEventItem`
+
+One event from the org's event store.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `actor_email` | `string \| null` | no | The event's context email: the acting user, recipient or a system actor address. |
+| `campaign_id` | `string \| null` | no | message.campaign_id, when the event carries one. |
+| `contact_id` | `string \| null` | no | message.contact_id, when the event carries one. |
+| `id` | `string \| null` | no | Event uid. Stable across reads; use it to de-duplicate. |
+| `message` | `Record<string, unknown>` | no | The event payload exactly as produced. |
+| `name` | `string \| null` | no | Event name, e.g. sequence_email_sent, inbox.email_received, sdr.call_ended, booking_created. |
+| `occurred_at` | `string \| null` | no | When the event happened (ISO 8601, UTC). |
+| `sequence_id` | `string \| null` | no | message.sequence_id, when the event carries one. |
+| `source` | `string \| null` | no | Producing service, e.g. sequencer, voiceai-service. |
+| `type` | `string \| null` | no | Event family, e.g. sequencer, inbox, voiceai, appointments, crm, deals, quotes, newsletter, uui, mcp, internal. Web-tracking rows carry the tracker's type (e.g. page). |
+| `url` | `string \| null` | no | Page URL, for web-tracking rows. |

package/docs/api/fields.d.ts

@@ -0,0 +1,482 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.fields` (Fields): 8 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_field_fields_post">;
+ *
+ * Reference with examples: fields.md
+ */
+/* eslint-disable */
+
+/** `g8.api.fields.<member>` -> the operationId it calls. */
+export interface FieldsMembers {
+  createField: "create_field_fields_post";
+  createFieldsBatch: "create_fields_batch_fields_batch_post";
+  deleteField: "delete_field_fields__column_id__delete";
+  getFieldValue: "get_field_value_fields__column_id__values_get";
+  listCompanyFields: "list_company_fields_fields_companies_get";
+  listContactFields: "list_contact_fields_fields_get";
+  setFieldValue: "set_field_value_fields__column_id__values_patch";
+  setFieldValuesBatch: "set_field_values_batch_fields_values_batch_patch";
+}
+
+/** Input and output of every `g8.api.fields` operation, keyed by operationId. */
+export interface FieldsOperations {
+  /**
+   * POST /fields
+   * Create Field
+   * tier: write · scope: fields:write
+   */
+  create_field_fields_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateFieldRequest;
+  };
+    output: ApiResponse_CreateFieldResponse_;
+  };
+  /**
+   * POST /fields/batch
+   * Create Fields Batch
+   * tier: write · scope: fields:write
+   */
+  create_fields_batch_fields_batch_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateFieldsBatchRequest;
+  };
+    output: ApiResponse_CreateFieldsBatchResponse_;
+  };
+  /**
+   * DELETE /fields/{column_id}
+   * Delete Field
+   * tier: destructive · scope: fields:delete
+   */
+  delete_field_fields__column_id__delete: {
+    input: {
+    path: {
+      /** Column ID to delete */
+      column_id: number;
+    };
+    query?: {
+      /** Target entity: 'contacts' or 'companies' */
+      entity?: string;
+      /** Optional list scope guard. If provided, the column must belong to this list or the request returns 404. Use this to prevent an agent with narrow intent from accidentally deleting a column on a different list in the same org. */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DeleteFieldResponse_;
+  };
+  /**
+   * GET /fields/{column_id}/values
+   * Get Field Value
+   * tier: read · scope: fields:read
+   */
+  get_field_value_fields__column_id__values_get: {
+    input: {
+    path: {
+      /** Column ID from g8_list_fields or g8_create_field */
+      column_id: number;
+    };
+    query: {
+      /** Contact ID (entity='contacts') or company ID (entity='companies') */
+      record_id: number;
+      /** Target entity: 'contacts' or 'companies' */
+      entity?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_GetFieldValueResponse_;
+  };
+  /**
+   * GET /fields/companies
+   * List Company Fields
+   * tier: read · scope: fields:read
+   */
+  list_company_fields_fields_companies_get: {
+    input: {
+    query?: {
+      /** List ID to include list-specific custom fields */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_FieldResponse__;
+  };
+  /**
+   * GET /fields
+   * List Contact Fields
+   * tier: read · scope: fields:read
+   */
+  list_contact_fields_fields_get: {
+    input: {
+    query?: {
+      /** List ID to include list-specific custom fields */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_FieldResponse__;
+  };
+  /**
+   * PATCH /fields/{column_id}/values
+   * Set Field Value
+   * tier: write · scope: fields:write
+   */
+  set_field_value_fields__column_id__values_patch: {
+    input: {
+    path: {
+      /** Column ID from g8_list_fields or g8_create_field */
+      column_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SetFieldValueRequest;
+  };
+    output: ApiResponse_SetFieldValueResponse_;
+  };
+  /**
+   * PATCH /fields/values/batch
+   * Set Field Values Batch
+   * tier: write · scope: fields:write
+   */
+  set_field_values_batch_fields_values_batch_patch: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SetFieldValuesBatchRequest;
+  };
+    output: ApiResponse_SetFieldValuesBatchResponse_;
+  };
+}
+
+// 28 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_CreateFieldResponse_ {
+  data: CreateFieldResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CreateFieldsBatchResponse_ {
+  data: CreateFieldsBatchResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DeleteFieldResponse_ {
+  data: DeleteFieldResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_GetFieldValueResponse_ {
+  data: GetFieldValueResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SetFieldValueResponse_ {
+  data: SetFieldValueResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SetFieldValuesBatchResponse_ {
+  data: SetFieldValuesBatchResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_FieldResponse__ {
+  data: Array<FieldResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * One column in a batch-create request.
+ *
+ * `title`, `data_type` and the optional `enrichment` block are per-column;
+ * `list_id` and `entity` are shared at the parent `CreateFieldsBatchRequest`
+ * level (a batch targets one entity and, when enrichment is used, one list).
+ */
+export interface BatchFieldItem {
+  /** Column data type. Currently only 'text' is supported. */
+  data_type?: string;
+  /** Optional per-column waterfall enrichment block (identical shape to POST /fields). When supplied, a companion enrichment_configs row is created for that column so it's immediately runnable. */
+  enrichment?: CreateFieldEnrichmentInput | null;
+  /** Column title, e.g. 'Job Level' */
+  title: string;
+}
+
+/** Per-column outcome inside a batch response. */
+export interface BatchFieldResult {
+  enrichment?: CreateFieldEnrichmentResponse | null;
+  /** Set when the column was created but its companion enrichment config failed. */
+  error?: string | null;
+  id?: number | null;
+  /** True when this column was created org-GLOBAL (no list_id was supplied) and will therefore appear on EVERY list in the org. Pass `list_id` to scope columns to one list. */
+  is_global?: boolean;
+  /** The list this column is scoped to, or null when it is org-global. */
+  list_id?: number | null;
+  name?: string | null;
+  ok?: boolean;
+  title: string;
+}
+
+/**
+ * Optional enrichment-pipeline block attached at column-create time.
+ *
+ * When supplied, `POST /fields` creates a companion `enrichment_configs`
+ * row in the same request so the new column is immediately runnable via
+ * `POST /enrichment/waterfall/enrich`. Without this block the column
+ * exists but has no enrichment plan — calling /waterfall/enrich on it
+ * returns 422 (`waterfall_config_missing`).
+ *
+ * Currently only `type='waterfall'` is supported; AI / formula
+ * enrichment will follow once the rest of the agent surface lands.
+ */
+export interface CreateFieldEnrichmentInput {
+  /** Optional post-enrichment email verification config. */
+  email_verification?: EmailVerificationInput | null;
+  /** Target field identifier. Defaults to the new column's slug. */
+  field_to_enrich?: string | null;
+  /** Pipeline name. Defaults to `<column title> Enrichment` if omitted. */
+  name?: string | null;
+  /** Ordered list of provider names. Without `target_field`, server maps each to its default email-finder action (legacy). With `target_field`, filters the column template to these providers (correct per-field action preserved). Mutually exclusive with `steps`. */
+  providers?: Array<string> | null;
+  /** If true, skip rows where the target field is already populated. */
+  skip_existing_values?: boolean;
+  /** Full caller-supplied step list. Persisted verbatim. Mutually exclusive with `providers`. */
+  steps?: Array<WaterfallStepInput> | null;
+  /** Kind of data this column holds — CONTACT_DIRECT_PHONE, CONTACT_MOBILE_PHONE, CONTACT_WORK_EMAIL, CONTACT_LINKEDIN_URL, COMPANY_PHONE, ... or a friendly synonym ('phone', 'mobile', 'email', 'linkedin'). When set, the pipeline is built from the server's per-column TEMPLATE so each provider runs its CORRECT action for that data kind (e.g. leadmagic `mobile_finder` for a phone, NOT `email_finder`) — the same actions the web UI's 'Add column -> Waterfall' picks. Combine with `providers[]` to keep only those providers from the template. Mutually exclusive with `steps`. When omitted, the legacy `providers[]` email-finder shortcut is unchanged. */
+  target_field?: string | null;
+  /** Pipeline kind. Only 'waterfall' is supported today. */
+  type?: string;
+}
+
+/** Echo of the companion enrichment config created by `enrichment` block. */
+export interface CreateFieldEnrichmentResponse {
+  /** column_id slug to pass to /enrichment/waterfall/enrich */
+  column_id: string;
+  config_id: string;
+  email_verification?: Record<string, unknown> | null;
+  name: string;
+  providers?: Array<string>;
+  type: string;
+}
+
+/** Request body for creating a custom field (column). */
+export interface CreateFieldRequest {
+  /** Column data type. Currently only 'text' is supported; additional types (numeric, date, boolean, select) may be added in future versions. */
+  data_type?: string;
+  /** Optional enrichment-pipeline block. When supplied, a companion `enrichment_configs` row is created in the same request so the new column is immediately runnable via /enrichment/waterfall/enrich. */
+  enrichment?: CreateFieldEnrichmentInput | null;
+  /** Target entity: 'contacts' or 'companies' */
+  entity?: string;
+  /** If set, field is list-specific; otherwise global across the org */
+  list_id?: number | null;
+  /** Column title, e.g. 'Job Level' */
+  title: string;
+}
+
+export interface CreateFieldResponse {
+  data_type: string;
+  /** Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent /enrichment/waterfall/enrich calls. */
+  enrichment?: CreateFieldEnrichmentResponse | null;
+  id: number;
+  is_global: boolean;
+  list_id?: number | null;
+  name: string;
+  title: string;
+}
+
+/**
+ * Create MANY custom columns in one request.
+ *
+ * All columns are created in a single DB transaction with a SINGLE view
+ * rebuild — at 40-50 columns this replaces 40-50 view recreations with one.
+ */
+export interface CreateFieldsBatchRequest {
+  /** Target entity for ALL columns: 'contacts' or 'companies' */
+  entity?: string;
+  /** Columns to create (1-100). */
+  fields: Array<BatchFieldItem>;
+  /** Shared list scope for all columns. REQUIRED if ANY field carries an `enrichment` block — waterfall pipelines are list-scoped. */
+  list_id?: number | null;
+}
+
+export interface CreateFieldsBatchResponse {
+  entity: string;
+  list_id?: number | null;
+  results: Array<BatchFieldResult>;
+  total_created: number;
+  total_requested: number;
+}
+
+export interface DeleteFieldResponse {
+  column_id: number;
+  deleted?: boolean;
+}
+
+/**
+ * Email verification config attached to a waterfall pipeline.
+ *
+ * Mirrors the canonical `EmailVerificationConfigDto` in
+ * `enrichment/interfaces/fastapi/waterfall_dtos.py` so the dev-API and the
+ * UI persist an identical settings shape (the CF worker reads `settings.
+ * email_verification.*` regardless of which surface saved the pipeline).
+ */
+export interface EmailVerificationInput {
+  /** Treat catch-all responses as valid (domains that accept any address). */
+  accept_catchall?: boolean;
+  /** Enable post-enrichment email verification */
+  enabled?: boolean;
+  /** Verification provider. Charges credits when use_system_credentials=True. */
+  provider?: "zerobounce" | "hunter" | "icypeas" | "leadmagic";
+  /** Use graph8-managed API keys (charges credits). False = use org's BYOK keys. */
+  use_system_credentials?: boolean;
+  /** Verification statuses to accept as valid. Typical: ['valid'] or ['valid','catch-all']. */
+  valid_statuses?: Array<string>;
+}
+
+export interface FieldResponse {
+  data_type?: string;
+  id?: number | null;
+  is_global?: boolean;
+  name?: string | null;
+  title: string;
+}
+
+/** One (column, value) pair to write on a row. */
+export interface FieldValueItem {
+  /** Column ID from g8_list_fields or g8_create_field. */
+  column_id: number;
+  /** Value to write into the custom column. Pass null (or omit) to clear the field. */
+  value?: string | null;
+}
+
+/** Response body for reading a single custom column value from one row. */
+export interface GetFieldValueResponse {
+  column_id: number;
+  entity: string;
+  /** The underlying column slug (column_name_db). */
+  name: string;
+  record_id: number;
+  /** The stored value, or null if the column is unset for this row. */
+  value?: string | null;
+}
+
+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;
+}
+
+/** One row (contact or company) plus the columns to set on it. */
+export interface RowFieldValues {
+  /** Column/value pairs to write on this row. Empty = no-op (counts as ok with 0 writes). */
+  fields?: Array<FieldValueItem>;
+  /** Contact ID (entity='contacts') or company ID (entity='companies'). */
+  record_id: number;
+}
+
+/** Request body for writing a custom column value to a single contact or company row. */
+export interface SetFieldValueRequest {
+  /** Target entity: 'contacts' or 'companies' */
+  entity?: string;
+  /** Contact ID (entity='contacts') or company ID (entity='companies') */
+  record_id: number;
+  /** Value to write into the custom column. Pass null (or omit) to clear the field. */
+  value?: string | null;
+}
+
+export interface SetFieldValueResponse {
+  column_id: number;
+  record_id: number;
+  updated?: boolean;
+}
+
+/** Write custom column values to one OR many contact/company rows at once. */
+export interface SetFieldValuesBatchRequest {
+  /** Target entity, SHARED across every row: 'contacts' or 'companies'. */
+  entity?: string;
+  /** Rows to update (1-500). Each carries its own record_id + fields[]. */
+  rows: Array<RowFieldValues>;
+  /** Opt-in status-code semantics. Default false keeps the historical behaviour: always HTTP 200, per-row outcomes in `results[]`. When true, a batch where EVERY row failed returns 422 and a partially-failed batch returns 207 Multi-Status, so a client that only checks the status code cannot mistake a total failure for success. The response body is identical either way. */
+  strict?: boolean;
+}
+
+export interface SetFieldValuesBatchResponse {
+  /** True when rows were requested and NONE were written. */
+  all_failed?: boolean;
+  entity: string;
+  results: Array<SetFieldValuesRowResult>;
+  /** Rows that could not be written (see results[].error). */
+  total_rows_failed?: number;
+  total_rows_requested: number;
+  total_rows_updated: number;
+  total_values_written: number;
+}
+
+/** Per-row outcome inside a batch value-write response. */
+export interface SetFieldValuesRowResult {
+  /** Set when this row failed (record not found, unknown column, etc.). Other rows still commit. */
+  error?: string | null;
+  ok?: boolean;
+  record_id: number;
+  updated_columns?: Array<number>;
+}
+
+/**
+ * Single step in a caller-supplied waterfall sequence.
+ *
+ * Mirrors `WaterfallStepDto` in `enrichment/interfaces/fastapi/waterfall_dtos.py`.
+ * Persisted verbatim into `enrichment_configs.config.steps[]` so the CF
+ * worker can resolve provider, action and credentials the same way
+ * UI-saved pipelines do.
+ */
+export interface WaterfallStepInput {
+  /** Provider action: lookup_person, find_email, enrich_person, ... */
+  action: string;
+  /** Human-readable label shown in UI. Auto-titled from `action` if omitted. */
+  action_display_name?: string | null;
+  confidence_threshold?: number;
+  /** Provider-specific options (e.g. apollo `reveal_phone_numbers=true`). */
+  config?: Record<string, unknown>;
+  enabled?: boolean;
+  /** Step identifier. Auto-generated (`step_<provider>_<uuid8>`) if omitted. */
+  id?: string | null;
+  /** Maps provider input names to graph8 column identifiers (CONTACT_*). */
+  input_mapping?: Record<string, string>;
+  /** True = use graph8-managed credentials + charge credits. False = use org BYOK. */
+  is_system_provider?: boolean;
+  max_retries?: number;
+  /** 0-indexed execution order. */
+  order?: number;
+  /** Dotted path the worker writes into (e.g. 'contact.work_email'). */
+  output_field?: string | null;
+  /** Optional output field remap (deprecated — prefer `output_field`). */
+  output_mapping?: Record<string, string>;
+  /** Provider name: graph8, hunter, prospeo, dropcontact, apollo, ... */
+  provider: string;
+  stop_on_success?: boolean;
+}