@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/forms.d.ts

@@ -0,0 +1,1012 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.forms` (Forms): 35 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"add_form_group_members_forms_groups__group_id__members_post">;
+ *
+ * Reference with examples: forms.md
+ */
+/* eslint-disable */
+
+/** `g8.api.forms.<member>` -> the operationId it calls. */
+export interface FormsMembers {
+  addFormGroupMembers: "add_form_group_members_forms_groups__group_id__members_post";
+  captureFormPreview: "capture_form_preview_forms__form_key__preview_post";
+  createFormBackfill: "create_form_backfill_forms__form_key__backfills_post";
+  createFormGroup: "create_form_group_forms_groups_post";
+  deleteFormGroup: "delete_form_group_forms_groups__group_id__delete";
+  getFormActivity: "get_form_activity_forms__form_key__activity_get";
+  getFormBackfill: "get_form_backfill_forms__form_key__backfills__job_id__get";
+  getFormFields: "get_form_fields_forms__form_key__fields_get";
+  getFormOverview: "get_form_overview_forms__form_key__overview_get";
+  getFormPlacements: "get_form_placements_forms__form_key__placements_get";
+  getFormPreview: "get_form_preview_forms__form_key__preview__preview_id__get";
+  getFormRouteRecommendations: "get_form_route_recommendations_forms__form_key__route_recommendations_get";
+  getFormSubmissionTrace: "get_form_submission_trace_forms__form_key__submissions__submission_id__trace_get";
+  getSiteAudit: "get_site_audit_forms_site_audit_get";
+  listFormGroups: "list_form_groups_forms_groups_get";
+  listForms: "list_forms_forms_get";
+  listSavedFormViews: "list_saved_form_views_forms_views_saved_get";
+  pauseFormDelivery: "pause_form_delivery_forms__form_key__delivery_pause_post";
+  previewFormMapping: "preview_form_mapping_forms__form_key__mapping_preview_post";
+  previewUnidentifiedGrouping: "preview_unidentified_grouping_forms_unidentified_grouping_get";
+  removeFormGroupMembers: "remove_form_group_members_forms_groups__group_id__members_remove_post";
+  requestSiteAuditScan: "request_site_audit_scan_forms_site_audit_scan_post";
+  resumeFormDelivery: "resume_form_delivery_forms__form_key__delivery_resume_post";
+  retryFormDelivery: "retry_form_delivery_forms_deliveries__receipt_id__retry_post";
+  rollbackFormRoute: "rollback_form_route_forms__form_key__route_delete";
+  saveFormMapping: "save_form_mapping_forms__form_key__mapping_save_post";
+  saveFormRoute: "save_form_route_forms__form_key__route_put";
+  saveFormView: "save_form_view_forms_views_saved__view_id__put";
+  searchFormSubmissions: "search_form_submissions_forms__form_key__submissions_post";
+  setUnidentifiedGrouping: "set_unidentified_grouping_forms_unidentified_grouping_put";
+  syncUnidentifiedGroup: "sync_unidentified_group_forms_unidentified_groups_sync_post";
+  testFormRoute: "test_form_route_forms__form_key__route_test_post";
+  updateFormGroup: "update_form_group_forms_groups__group_id__patch";
+  updateFormRegistry: "update_form_registry_forms__form_key__patch";
+  updateSiteAuditFinding: "update_site_audit_finding_forms_site_audit_findings__finding_id__patch";
+}
+
+/** Input and output of every `g8.api.forms` operation, keyed by operationId. */
+export interface FormsOperations {
+  /**
+   * POST /forms/groups/{group_id}/members
+   * Add Form Group Members
+   * tier: write · scope: forms:write
+   */
+  add_form_group_members_forms_groups__group_id__members_post: {
+    input: {
+    path: {
+      /** The group's id. */
+      group_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormGroupMembersRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/{form_key}/preview
+   * Capture Form Preview
+   * tier: write · scope: forms:write
+   */
+  capture_form_preview_forms__form_key__preview_post: {
+    input: {
+    path: {
+      /** The form's `form_key` (the `id` from `GET /forms`). */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormPlacementPreviewRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/{form_key}/backfills
+   * Create Form Backfill
+   * tier: external · scope: forms:run
+   */
+  create_form_backfill_forms__form_key__backfills_post: {
+    input: {
+    path: {
+      /** The form's `form_key` (the `id` from `GET /forms`). */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormBackfillRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/groups
+   * Create Form Group
+   * tier: write · scope: forms:write
+   */
+  create_form_group_forms_groups_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormGroupCreateRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * DELETE /forms/groups/{group_id}
+   * Delete Form Group
+   * tier: destructive · scope: forms:delete
+   */
+  delete_form_group_forms_groups__group_id__delete: {
+    input: {
+    path: {
+      /** The group's id. */
+      group_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * GET /forms/{form_key}/activity
+   * Get Form Activity
+   * tier: read · scope: forms:read
+   */
+  get_form_activity_forms__form_key__activity_get: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    query: {
+      /** Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. */
+      source_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * GET /forms/{form_key}/backfills/{job_id}
+   * Get Form Backfill
+   * tier: read · scope: forms:read
+   */
+  get_form_backfill_forms__form_key__backfills__job_id__get: {
+    input: {
+    path: {
+      /** The form's `form_key` (the `id` from `GET /forms`). */
+      form_key: string;
+      /** Job id from the backfill that started it. */
+      job_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * GET /forms/{form_key}/fields
+   * Get Form Fields
+   * tier: read · scope: forms:read
+   */
+  get_form_fields_forms__form_key__fields_get: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    query: {
+      /** Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. */
+      source_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * GET /forms/{form_key}/overview
+   * Get Form Overview
+   * tier: read · scope: forms:read
+   */
+  get_form_overview_forms__form_key__overview_get: {
+    input: {
+    path: {
+      /** The form's HTML tag id / group key (from list_forms). */
+      form_key: string;
+    };
+    query: {
+      /** Write key / site the form belongs to (from list_forms). */
+      source_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormOverview_;
+  };
+  /**
+   * GET /forms/{form_key}/placements
+   * Get Form Placements
+   * tier: read · scope: forms:read
+   */
+  get_form_placements_forms__form_key__placements_get: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    query: {
+      /** Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. */
+      source_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * GET /forms/{form_key}/preview/{preview_id}
+   * Get Form Preview
+   * tier: read · scope: forms:read
+   */
+  get_form_preview_forms__form_key__preview__preview_id__get: {
+    input: {
+    path: {
+      /** The form's `form_key` (the `id` from `GET /forms`). */
+      form_key: string;
+      /** Id from the capture that started it. */
+      preview_id: string;
+    };
+    query: {
+      /** The site (write key) the form is installed on. */
+      source_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * GET /forms/{form_key}/route/recommendations
+   * Get Form Route Recommendations
+   * tier: read · scope: forms:read
+   */
+  get_form_route_recommendations_forms__form_key__route_recommendations_get: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    query: {
+      /** Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. */
+      source_id: string;
+      /** Destination list to tailor the mapping suggestions to. OPTIONAL on purpose: a caller asks for recommendations BEFORE choosing a destination, and making it required 422s every such request. */
+      target_list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * GET /forms/{form_key}/submissions/{submission_id}/trace
+   * Get Form Submission Trace
+   * tier: read · scope: forms:read
+   */
+  get_form_submission_trace_forms__form_key__submissions__submission_id__trace_get: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+      /** Submission id from the activity feed. */
+      submission_id: string;
+    };
+    query: {
+      /** Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. */
+      source_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * GET /forms/site-audit
+   * Get Site Audit
+   * tier: read · scope: forms:read
+   */
+  get_site_audit_forms_site_audit_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * GET /forms/groups
+   * List Form Groups
+   * tier: read · scope: forms:read
+   */
+  list_form_groups_forms_groups_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * GET /forms
+   * List Forms
+   * tier: read · scope: forms:read
+   */
+  list_forms_forms_get: {
+    input: {
+    query?: {
+      /** 1-indexed page. */
+      page?: number;
+      /** Rows per page (max 200). */
+      per_page?: number;
+      /** Case-insensitive substring match on form name/id. */
+      search?: string | null;
+      /** Filter to a single write key / site. */
+      source_id?: string | null;
+      /** total_submissions | latest_submitted_at | form_tag_id */
+      sort_field?: ("submissions_30d" | "total_submissions" | "latest_submitted_at" | "form_tag_id") | null;
+      /** asc | desc */
+      sort_order?: ("asc" | "desc") | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsListResponse_;
+  };
+  /**
+   * GET /forms/views/saved
+   * List Saved Form Views
+   * tier: read · scope: forms:read
+   */
+  list_saved_form_views_forms_views_saved_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/{form_key}/delivery/pause
+   * Pause Form Delivery
+   * tier: external · scope: forms:run
+   */
+  pause_form_delivery_forms__form_key__delivery_pause_post: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormSourceScopedRequest;
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * POST /forms/{form_key}/mapping/preview
+   * Preview Form Mapping
+   * tier: read · scope: forms:read
+   */
+  preview_form_mapping_forms__form_key__mapping_preview_post: {
+    input: {
+    path: {
+      /** The form's `form_key` (the `id` from `GET /forms`). */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormMappingRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * GET /forms/unidentified/grouping
+   * Preview Unidentified Grouping
+   * tier: read · scope: forms:read
+   */
+  preview_unidentified_grouping_forms_unidentified_grouping_get: {
+    input: {
+    query?: {
+      /** One site. Omit for every site. */
+      source_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/groups/{group_id}/members/remove
+   * Remove Form Group Members
+   * tier: write · scope: forms:write
+   */
+  remove_form_group_members_forms_groups__group_id__members_remove_post: {
+    input: {
+    path: {
+      /** The group's id. */
+      group_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormGroupMembersRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/site-audit/scan
+   * Request Site Audit Scan
+   * tier: write · scope: forms:write
+   */
+  request_site_audit_scan_forms_site_audit_scan_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/{form_key}/delivery/resume
+   * Resume Form Delivery
+   * tier: external · scope: forms:run
+   */
+  resume_form_delivery_forms__form_key__delivery_resume_post: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormSourceScopedRequest;
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * POST /forms/deliveries/{receipt_id}/retry
+   * Retry Form Delivery
+   * tier: external · scope: forms:run
+   */
+  retry_form_delivery_forms_deliveries__receipt_id__retry_post: {
+    input: {
+    path: {
+      /** Delivery receipt id from the activity feed. */
+      receipt_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * DELETE /forms/{form_key}/route
+   * Rollback Form Route
+   * tier: destructive · scope: forms:delete
+   */
+  rollback_form_route_forms__form_key__route_delete: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormRouteRollbackRequest;
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * POST /forms/{form_key}/mapping/save
+   * Save Form Mapping
+   * tier: write · scope: forms:write
+   */
+  save_form_mapping_forms__form_key__mapping_save_post: {
+    input: {
+    path: {
+      /** The form's `form_key` (the `id` from `GET /forms`). */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormMappingRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * PUT /forms/{form_key}/route
+   * Save Form Route
+   * tier: write · scope: forms:write
+   */
+  save_form_route_forms__form_key__route_put: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormRouteRequest;
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * PUT /forms/views/saved/{view_id}
+   * Save Form View
+   * tier: write · scope: forms:write
+   */
+  save_form_view_forms_views_saved__view_id__put: {
+    input: {
+    path: {
+      /** The view's id. Created when it does not exist. */
+      view_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormSavedViewRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/{form_key}/submissions
+   * Search Form Submissions
+   * tier: read · scope: forms:read
+   */
+  search_form_submissions_forms__form_key__submissions_post: {
+    input: {
+    path: {
+      /** The form's `form_key` (the `id` from `GET /forms`). */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormSubmissionsSearchRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * PUT /forms/unidentified/grouping
+   * Set Unidentified Grouping
+   * tier: write · scope: forms:write
+   */
+  set_unidentified_grouping_forms_unidentified_grouping_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormGroupingRuleRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/unidentified/groups/sync
+   * Sync Unidentified Group
+   * tier: write · scope: forms:write
+   */
+  sync_unidentified_group_forms_unidentified_groups_sync_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormGroupSyncRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * POST /forms/{form_key}/route/test
+   * Test Form Route
+   * tier: write · scope: forms:write
+   */
+  test_form_route_forms__form_key__route_test_post: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormSourceScopedRequest;
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * PATCH /forms/groups/{group_id}
+   * Update Form Group
+   * tier: write · scope: forms:write
+   */
+  update_form_group_forms_groups__group_id__patch: {
+    input: {
+    path: {
+      /** The group's id. */
+      group_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormGroupPatchRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+  /**
+   * PATCH /forms/{form_key}
+   * Update Form Registry
+   * tier: write · scope: forms:write
+   */
+  update_form_registry_forms__form_key__patch: {
+    input: {
+    path: {
+      /** Form key. */
+      form_key: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormRegistryPatchRequest;
+  };
+    output: ApiResponse_FormPayload_;
+  };
+  /**
+   * PATCH /forms/site-audit/findings/{finding_id}
+   * Update Site Audit Finding
+   * tier: write · scope: forms:write
+   */
+  update_site_audit_finding_forms_site_audit_findings__finding_id__patch: {
+    input: {
+    path: {
+      /** The finding's id. */
+      finding_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormSiteAuditStatusRequest;
+  };
+    output: ApiResponse_FormsAdminPayload_;
+  };
+}
+
+// 29 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_FormOverview_ {
+  data: FormOverview;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_FormPayload_ {
+  data: FormPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_FormsAdminPayload_ {
+  data: FormsAdminPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_FormsListResponse_ {
+  data: FormsListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Re-deliver submissions captured in a window. Mirrors `BackfillRequest`.
+ *
+ * `preview` DEFAULTS TO TRUE, as it does in the app: a real backfill delivers
+ * real leads to the form's route and cannot be undone.
+ */
+export interface FormBackfillRequest {
+  end_at?: string | null;
+  /** The count a preview reported, echoed back. */
+  estimated?: number;
+  /** True reports what would be delivered without delivering it. */
+  preview?: boolean;
+  /** The site (write key) the form is installed on. */
+  source_id: string;
+  start_at?: string | null;
+}
+
+/** One submitted field and the contact field it lands in. Mirrors `MappedFieldName`. */
+export interface FormFieldMapping {
+  /** Id of that dynamic column. */
+  dynamic_column_id?: number | null;
+  /** Whether `target_field` is a dynamic column created by this mapping. */
+  is_new_column?: boolean;
+  /** Display name of that dynamic column. */
+  new_column_name?: string | null;
+  /** Name of the submitted form field. */
+  source_field: string;
+  /** Constant written to `target_field` instead of reading a submitted field. */
+  static_value?: string | null;
+  /** Contact field it is written to. */
+  target_field: string;
+}
+
+/** Mirrors `CuratedGroupCreateRequest`. Members already in another group are MOVED here. */
+export interface FormGroupCreateRequest {
+  form_type?: ("lead" | "newsletter" | "meeting" | "contact" | "download" | "other") | null;
+  members?: Array<FormGroupMemberRef>;
+  name: string;
+}
+
+/** One inventory row in a curated group. Mirrors `GroupMemberRefRequest`. */
+export interface FormGroupMemberRef {
+  form_key: string;
+  /** Write key, or its bare key id. */
+  source_id: string;
+}
+
+/** Mirrors `CuratedGroupMembersRequest`. */
+export interface FormGroupMembersRequest {
+  members: Array<FormGroupMemberRef>;
+}
+
+/** Mirrors `CuratedGroupPatchRequest`. */
+export interface FormGroupPatchRequest {
+  form_type?: ("lead" | "newsletter" | "meeting" | "contact" | "download" | "other") | null;
+  name?: string | null;
+}
+
+/** Name one group of id-less submissions and route its leads to a list. Mirrors `GroupSyncRequest`. */
+export interface FormGroupSyncRequest {
+  axis: "fields" | "component" | "page" | "campaign" | "source_attribute";
+  group_id: string;
+  /** The axis value this group covers. */
+  matcher?: string;
+  name?: string;
+  source_id: string;
+  target_list_id?: number | null;
+}
+
+/** How one site's id-less submissions are split into forms. Mirrors `GroupingRuleRequest`. */
+export interface FormGroupingRuleRequest {
+  axis?: "none" | "fields" | "component" | "page" | "campaign" | "source_attribute";
+  source_id: string;
+}
+
+/** The inventory filter set a saved view stores. Mirrors `PaginationRequest`. */
+export interface FormInventoryFilters {
+  activity_end?: string | null;
+  activity_start?: string | null;
+  capture_health?: ("healthy" | "no_data") | null;
+  delivery_state?: ("active" | "paused" | "failed" | "not_configured") | null;
+  destination_list_id?: number | null;
+  has_failures?: boolean | null;
+  has_new_fields?: boolean | null;
+  identity_quality?: ("verified" | "variant" | "collision" | "historic_uncertain") | null;
+  mapping_state?: ("mapped" | "unmapped") | null;
+  owner_id?: string | null;
+  page?: number;
+  per_page?: number;
+  saved_view?: ("live" | "needs_setup" | "failing" | "ignored" | "healthy" | "failures" | "new_fields" | "no_recent_submissions" | "missing_or_collision" | "destination_unavailable" | "newly_discovered") | null;
+  search?: string | null;
+  sort_field?: ("submissions_30d" | "total_submissions" | "latest_submitted_at" | "form_tag_id") | null;
+  sort_order?: ("asc" | "desc") | null;
+  source_id?: string | null;
+  write_key?: string | null;
+}
+
+/**
+ * How a form's submitted fields become contact fields.
+ *
+ * Mirrors `PreviewFormToContactMappingRequest`, which the app uses for both
+ * the preview and the save.
+ */
+export interface FormMappingRequest {
+  /** Optimistic-concurrency guard: the route version you last read. Omit for last-writer-wins. */
+  expected_route_version?: number | null;
+  /** Submitted field -> contact field. */
+  form_to_contact_field_mapping?: Array<FormFieldMapping>;
+  source_id?: string | null;
+  submissions_page?: number;
+  submissions_per_page?: number;
+  /** Id of that list, when it already exists. */
+  target_list_id?: number | null;
+  /** Name of the list the mapped submissions are saved to. */
+  target_list_name: string;
+}
+
+/**
+ * Per-form operational detail (health, metrics, destination).
+ *
+ * Mirrors the scalar fields of the in-app ``GET /forms/{form_key}/overview``
+ * response. The config-oriented ``route`` / ``permissions`` blocks from the
+ * internal payload are intentionally omitted — an agent describing a form does
+ * not need route-editing internals.
+ */
+export interface FormOverview {
+  activation_health?: string | null;
+  capture_health?: string | null;
+  delivery_health?: string | null;
+  display_name?: string | null;
+  form_key: string;
+  identity_state?: string | null;
+  last_destination_verified_at?: string | null;
+  metrics?: Record<string, unknown>;
+  owner_id?: string | null;
+  placement_count?: number;
+  recommended_action?: string | null;
+  source_id: string;
+  technical_form_id?: string | null;
+}
+
+/**
+ * An open envelope for a form operational view.
+ *
+ * `overview`, `fields`, `placements`, `activity`, a route save result and a
+ * submission trace each return a different shape assembled from several
+ * upstreams. Pinning any of them would drop a field the moment one is added,
+ * and on a delivery-diagnostics surface a missing field reads as a missing
+ * delivery.
+ */
+export type FormPayload = Record<string, unknown>;
+
+/** Which observed placement to capture. Mirrors `PlacementPreviewRequest`. */
+export interface FormPlacementPreviewRequest {
+  /** A page the form was actually seen on. */
+  page_url: string;
+  /** The site (write key) the form is installed on. */
+  source_id: string;
+}
+
+/** Rename, reassign or archive a form. */
+export interface FormRegistryPatchRequest {
+  /** Archive or unarchive. Omit to leave unchanged. */
+  archived?: boolean | null;
+  display_name?: string | null;
+  owner_id?: string | null;
+  /** Which INSTALLED SOURCE of this form. A form key can be present on more than one source, and every operation on this surface is scoped to one - omitting it would silently act on whichever the backend picked. */
+  source_id: string;
+}
+
+/**
+ * Save a form's route: where its submissions land, and how they map.
+ *
+ * `extra="forbid"` mirrors the app. An unknown key here is a typo in a
+ * caller's mapping, and silently dropping it would send submissions to the
+ * right list with the wrong fields.
+ */
+export interface FormRouteRequest {
+  /** Values applied to every submission. */
+  defaults?: Record<string, unknown>;
+  /** PRECONDITION. The route version you are replacing. Without it the save is last-writer-wins and can silently overwrite a colleague's route. */
+  expected_current_route_version?: number | null;
+  /** PRECONDITION on the route's history log. */
+  expected_route_history_version?: number | null;
+  /** PRECONDITION, not a setting. The form schema version this mapping was built against; the save is rejected if the form has changed shape since. Omitting it saves a mapping against a schema you have not seen. */
+  expected_schema_version?: number | null;
+  /** Form field -> graph8 field. */
+  mapping?: Array<Record<string, unknown>>;
+  /** Save anyway when the schema HAS drifted. Deliberate override. */
+  schema_drift_approved?: boolean;
+  source_id: string;
+  /** Audience list submissions land in. */
+  target_list_id: number;
+  /** Whether routed submissions trigger workflows. `simulate` records what WOULD have run without running it - the safe way to turn automation on for a live form. Defaults to `disabled`. */
+  workflow_policy?: "disabled" | "simulate" | "enabled";
+}
+
+/**
+ * Roll a route back to an earlier version, or cancel the pending one.
+ *
+ * Sent as the body of a DELETE, matching the app: this is not "delete the
+ * route", it is "move it back", and which version to move to has to travel
+ * with the request.
+ */
+export interface FormRouteRollbackRequest {
+  /** Cancel a pending route instead of restoring an old one. */
+  cancel_current?: boolean;
+  /** PRECONDITION: the version you believe is live. Guards a concurrent rollback. */
+  expected_current_version?: number | null;
+  /** Version to restore. Omit to take the previous one. */
+  restore_version?: number | null;
+  source_id: string;
+}
+
+/** A named inventory filter set. Mirrors `SavedFormsViewRequest`. */
+export interface FormSavedViewRequest {
+  filters: FormInventoryFilters;
+  name: string;
+}
+
+/** Mirrors `SiteAuditStatusRequest`. */
+export interface FormSiteAuditStatusRequest {
+  status: "open" | "acknowledged" | "ignored" | "resolved";
+}
+
+/** Every form operation is scoped to one installed source. */
+export interface FormSourceScopedRequest {
+  source_id: string;
+}
+
+/** One filter over a form's submissions. Mirrors the app's `ConditionRequest`. */
+export interface FormSubmissionCondition {
+  /** Submitted field name, or a submission attribute. */
+  field: string;
+  /** Comparison operator, in the app's filter grammar. */
+  operator: string;
+  /** Value compared against. */
+  value: unknown;
+  /** Upper bound, for range operators. */
+  value_to?: unknown;
+}
+
+/** Which page of a form's submissions to read. Mirrors `FormSubmissionsRequest`. */
+export interface FormSubmissionsSearchRequest {
+  conditions?: Array<FormSubmissionCondition>;
+  page?: number;
+  per_page?: number;
+  /** One site. Omit for every site the form is on. */
+  source_id?: string | null;
+}
+
+/** One lead-capture form as returned by the list/search endpoint. */
+export interface FormSummary {
+  /** Human-friendly name for the form. */
+  display_name?: string | null;
+  /** Alias for id; the addressable key for detail lookups. */
+  form_key?: string | null;
+  /** The form's HTML tag id (or the id-less group key). */
+  id: string;
+  /** Most recent submission timestamp. */
+  latest_submitted_at?: string | null;
+  /** URL of a page where the form was submitted. */
+  page_url?: string | null;
+  /** Write key / site the form was submitted from. */
+  source_id?: string | null;
+  /** Destination list id, if the form is routed. */
+  target_list_id?: number | null;
+  /** Destination list name, if the form is routed. */
+  target_list_name?: string | null;
+  /** Total submissions received for this form. */
+  total_submissions?: number;
+}
+
+/**
+ * One forms object, or one handler response.
+ *
+ * Open-shaped: the submission, mapping, group and audit payloads grow with
+ * the product, and a closed model here would silently drop what it does not
+ * name.
+ */
+export type FormsAdminPayload = Record<string, unknown>;
+
+/** Paginated envelope for the forms list/search endpoint. */
+export interface FormsListResponse {
+  items?: Array<FormSummary>;
+  page?: number;
+  per_page?: number;
+  total?: number;
+}
+
+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;
+}