@pipefy/pipefy-process-coder 0.1.0

package/src/apply/mutations.ts

@@ -0,0 +1,955 @@
+import { randomUUID } from 'node:crypto';
+import { debug, warn } from '../util/log.ts';
+import type { PipefyClient } from '../pipefy/client.ts';
+import type { Row } from '../model/payload.ts';
+import type { StepRequest } from './types.ts';
+
+/**
+ * Mutation builders.
+ *
+ * Every shape here is the one the Change Migrator recipes actually send —
+ * including the details that are easy to get wrong and that the recipes prove:
+ *
+ *   - `deletePhaseField` needs `pipeUuid` alongside the field id (step 43/63)
+ *   - `createPhaseField` takes `label`, `phase_id`, `type`, `options`,
+ *     `description` (step 34)
+ *   - `createFieldCondition` takes the read shape after stripping labels and
+ *     renaming `phase → phaseId`, `phaseField → phaseFieldId` (steps 85/86),
+ *     while `updateFieldCondition` wants `phase_id` (steps 109/110)
+ *
+ * Argument sets are then filtered against the mutation's real input type, so an
+ * argument this Pipefy version does not accept is dropped with a debug line
+ * instead of failing the whole call.
+ */
+
+const dropUndefined = (o: Row): Row => {
+  const out: Row = {};
+  for (const [k, v] of Object.entries(o)) if (v !== undefined) out[k] = v;
+  return out;
+};
+
+/**
+ * Build `mutation($input: <T>!) { <name>(input: $input) { <selection> } }` with
+ * the input filtered to the fields the schema accepts.
+ */
+export const buildGraphql = async (
+  client: PipefyClient | null,
+  mutation: string,
+  input: Row,
+  selection: string,
+): Promise<StepRequest> => {
+  /**
+   * Offline (no token): fall back to the conventional input type name and keep
+   * every argument. Classification and ordering are what `pipe plan` is for, and
+   * both are pure functions of the ChangeSet — so they must not need a network.
+   * The steps are marked unverified, and `pipe apply` re-compiles with a client.
+   */
+  const typeName = (client ? await client.mutationInputType(mutation) : null) ?? `${mutation[0]?.toUpperCase()}${mutation.slice(1)}Input`;
+  const accepted = client ? await client.inputFields(typeName) : null;
+  const required = client ? await client.requiredInputFields(typeName) : new Set<string>();
+
+  const filtered: Row = {};
+  const dropped: string[] = [];
+  for (const [k, v] of Object.entries(dropUndefined(input))) {
+    if (accepted && !accepted.has(k)) {
+      dropped.push(k);
+      continue;
+    }
+    filtered[k] = v;
+  }
+  if (dropped.length) debug(`${mutation}: dropped args not in ${typeName} — ${dropped.join(', ')}`);
+
+  const missingRequired = [...required].filter((k) => filtered[k] === undefined || filtered[k] === null);
+  if (missingRequired.length) {
+    debug(`${mutation}: missing required ${typeName} fields — ${missingRequired.join(', ')}`);
+  }
+
+  return {
+    mutation,
+    ...(missingRequired.length ? { missingRequired } : {}),
+    query: `mutation($input: ${typeName}!) {\n  ${mutation}(input: $input) {\n    clientMutationId\n    ${selection}\n  }\n}`,
+    variables: { input: filtered },
+  };
+};
+
+// ── phases ───────────────────────────────────────────────────────────────────
+
+export const createPhase = (client: PipefyClient | null, pipeId: number, phase: Row) =>
+  buildGraphql(
+    client,
+    'createPhase',
+    {
+      pipe_id: String(pipeId),
+      name: phase['name'],
+      done: phase['done'],
+      description: phase['description'],
+      lateness_time: phase['lateness_time'],
+      can_receive_card_directly_from_draft: phase['can_receive_card_directly_from_draft'],
+      only_admin_can_move_to_previous: phase['only_admin_can_move_to_previous'],
+      // createPhase takes index: Float — updatePhase does not (PLAN.md §2).
+      index: phase['index'],
+      uuid: phase['uuid'],
+    },
+    'phase { id name index }',
+  );
+
+export const updatePhase = (client: PipefyClient | null, phase: Row) =>
+  buildGraphql(
+    client,
+    'updatePhase',
+    {
+      id: String(phase['id']),
+      name: phase['name'],
+      done: phase['done'],
+      description: phase['description'],
+      lateness_time: phase['lateness_time'],
+      can_receive_card_directly_from_draft: phase['can_receive_card_directly_from_draft'],
+      only_admin_can_move_to_previous: phase['only_admin_can_move_to_previous'],
+    },
+    'phase { id name }',
+  );
+
+export const deletePhase = (client: PipefyClient | null, phaseId: string | number) =>
+  buildGraphql(client, 'deletePhase', { id: String(phaseId) }, 'success');
+
+/**
+ * `phaseSettings` takes `SettingsInput`, keyed on `id` — not `phaseId`, which is
+ * what an earlier version sent. It is also a superset of `updatePhase`: name,
+ * description, done, lateness, colour and the team all live here.
+ */
+export const phaseSettings = (client: PipefyClient | null, phaseId: string | number, settings: Row) =>
+  buildGraphql(
+    client,
+    'phaseSettings',
+    {
+      id: String(phaseId),
+      identifyTask: settings['identify_task'],
+      latenessTime: settings['lateness_time'],
+      teamMemberIds: Array.isArray(settings['team_member_ids'])
+        ? (settings['team_member_ids'] as unknown[]).map(String)
+        : undefined,
+    },
+    'clientMutationId',
+  );
+
+// ── fields ───────────────────────────────────────────────────────────────────
+
+/**
+ * `label` is NON_NULL on update, so the compiler always sends the full object
+ * rather than a sparse patch (PLAN.md §2).
+ */
+const fieldArgs = (field: Row): Row => ({
+  label: field['label'],
+  options: field['options'],
+  description: field['description'],
+  help: field['help'],
+  required: field['required'],
+  editable: field['editable'],
+  minimal_view: field['minimal_view'],
+  custom_validation: field['custom_validation'],
+  unique: field['unique'],
+  index: field['index'],
+  sync_with_card: field['card_synced'],
+  can_create_database_record: field['can_create_connected_cards'],
+  can_have_multiple_database_records: field['can_connect_multiple_cards'],
+  child_must_exist_to_finish_parent: field['child_must_exist_to_finish_parent'],
+  all_children_must_be_done_to_move_parent: field['all_children_must_be_done_to_move_parent'],
+  all_children_must_be_done_to_finish_parent: field['all_children_must_be_done_to_finish_parent'],
+});
+
+export const createPhaseField = (client: PipefyClient | null, phaseId: string, field: Row) =>
+  buildGraphql(
+    client,
+    'createPhaseField',
+    {
+      phase_id: phaseId,
+      type: field['type_id'],
+      uuid: field['uuid'],
+      connected_repo_id: field['connected_pipe_id'] ? String(field['connected_pipe_id']) : undefined,
+      ...fieldArgs(field),
+    },
+    'phase_field { id internal_id uuid }',
+  );
+
+export const updatePhaseField = (client: PipefyClient | null, field: Row) =>
+  buildGraphql(
+    client,
+    'updatePhaseField',
+    { id: String(field['id']), uuid: field['uuid'], ...fieldArgs(field) },
+    'phase_field { id internal_id }',
+  );
+
+// ── database (table) fields ──────────────────────────────────────────────────
+
+/**
+ * A database's columns, which are `table_fields` on the write side even though a
+ * database's *payload* calls them `fields` like a pipe's.
+ *
+ * Every identifier below was measured, not inferred (VALIDATION.md §3g). The
+ * short version: **a table field is addressed by its slug** — for update, for
+ * delete and inside the order call. That is the exact opposite of
+ * `updatePhaseField`, whose `id` is the numeric internal id, and sending the
+ * internal id or the uuid here is refused with `Field not found with id: <the id
+ * that plainly exists>`.
+ *
+ * Two arguments this input does not have, both load-bearing:
+ *
+ *  - **no `index`.** A create lands at the end and order is a separate
+ *    `setTableFieldOrder` call.
+ *  - **no `type`** on update. A type change would mean delete + create, which
+ *    destroys that column in every record, so it is refused rather than done
+ *    quietly — the same rule pipe fields already have.
+ */
+const tableFieldArgs = (field: Row): Row => ({
+  label: field['label'],
+  options: field['options'],
+  description: field['description'],
+  help: field['help'],
+  required: field['required'],
+  minimal_view: field['minimal_view'],
+  custom_validation: field['custom_validation'],
+  unique: field['unique'],
+  canConnectExisting: field['can_search_connected_cards'],
+  canConnectMultiples: field['can_connect_multiple_cards'],
+  canCreateNewConnected: field['can_create_connected_cards'],
+  childMustExistToFinishParent: field['child_must_exist_to_finish_parent'],
+  allChildrenMustBeDoneToFinishParent: field['all_children_must_be_done_to_finish_parent'],
+});
+
+/** `table_id` accepts either the api id or the numeric internal id — both measured. */
+export const createTableField = (client: PipefyClient | null, tableId: string | number, field: Row) =>
+  buildGraphql(
+    client,
+    'createTableField',
+    {
+      table_id: String(tableId),
+      type: field['type_id'],
+      connectedRepoId: field['connected_pipe_id'] ? String(field['connected_pipe_id']) : undefined,
+      ...tableFieldArgs(field),
+    },
+    'table_field { id internal_id uuid }',
+  );
+
+/**
+ * `id` is the field's **slug**, and `table_id` is required alongside it.
+ *
+ * Measured: the numeric internal id and the uuid are both refused, and the slug
+ * both succeeds and actually changes the row — the "accepted but unchanged" case
+ * this project has been bitten by elsewhere does not happen here.
+ */
+export const updateTableField = (client: PipefyClient | null, tableId: string | number, field: Row) =>
+  buildGraphql(
+    client,
+    'updateTableField',
+    { id: slugOf(field), table_id: String(tableId), ...tableFieldArgs(field) },
+    'table_field { id internal_id label }',
+  );
+
+/** Also the slug, also with `table_id`. Destroys that column in every record. */
+export const deleteTableField = (client: PipefyClient | null, tableId: string | number, field: Row) =>
+  buildGraphql(
+    client,
+    'deleteTableField',
+    { id: slugOf(field), table_id: String(tableId) },
+    'success',
+  );
+
+/**
+ * Set-replacing per table, and it **returns the applied order**.
+ *
+ * That return is worth having: unlike `setFieldConditionOrder`, which answers a
+ * 200 and nothing else, this one lets the step assert its own effect instead of
+ * trusting the status. `field_ids` are slugs.
+ */
+export const setTableFieldOrder = (
+  client: PipefyClient | null,
+  tableId: string | number,
+  fields: Row[],
+) =>
+  buildGraphql(
+    client,
+    'setTableFieldOrder',
+    { table_id: String(tableId), field_ids: fields.map(slugOf) },
+    'table_fields { id index }',
+  );
+
+/**
+ * The field's slug, which the payload stores in `slug` and the table API returns
+ * as `id`. Falls back to the numeric id only so a request fails loudly rather
+ * than silently addressing nothing.
+ */
+const slugOf = (field: Row): string => String(field['slug'] ?? field['id'] ?? '');
+
+/** Needs the pipe uuid as well as the field id — recipe steps 42/43. */
+/**
+ * `deletePhaseField.id` is the field's **slug**, not the numeric id the payload
+ * stores as `id`.
+ *
+ * A field has three identifiers and the mutations disagree about which one they
+ * take: `updatePhaseField.id` accepts the numeric internal id, `archiveField`
+ * wants the uuid, and this one wants the slug. Sent the numeric id it answers
+ * `Field not found with id: <that id>` — about a field that is plainly there,
+ * which reads like a stale workspace rather than a wrong argument.
+ *
+ * Measured on a throwaway field: delete by internal id was refused with "Phase
+ * field not found with id", delete by slug succeeded. The slug is in the payload
+ * already, so nothing needs looking up.
+ */
+export const deletePhaseField = (client: PipefyClient | null, field: Row, pipeUuid: string | null) => {
+  const slug = field['slug'];
+  return buildGraphql(
+    client,
+    'deletePhaseField',
+    {
+      /**
+       * Falls back to the id only when the row has no slug, which happens for a
+       * field the workspace authored and never pulled. That request will fail,
+       * and failing loudly beats deleting something else.
+       */
+      id: String(slug ?? field['id'] ?? ''),
+      pipeUuid: pipeUuid ?? undefined,
+    },
+    'success',
+  );
+};
+
+/**
+ * `ArchiveFieldInput` is `{ uuid: String! }` — the field's **uuid**, not its id.
+ * Sent as an id, the mutation is rejected; the required-field check now catches
+ * that at plan time, which is how the real shape came to light.
+ */
+export const archiveField = (client: PipefyClient | null, field: Row, archived: boolean) =>
+  buildGraphql(
+    client,
+    archived ? 'archiveField' : 'unarchiveField',
+    { uuid: field['uuid'] ? String(field['uuid']) : undefined },
+    'clientMutationId',
+  );
+
+// ── labels ───────────────────────────────────────────────────────────────────
+
+/**
+ * `CreateLabelInput` has **both** `pipe_id` and `table_id`, and a database's
+ * labels go in the second.
+ *
+ * Worth spelling out because the obvious probe fails in a misleading way: sending
+ * a database id as `pipe_id` is refused with `Pipe not found with id: <the
+ * database id>`, which reads like "databases have no labels" and is not. With
+ * `table_id` it works, and so do `updateLabel` and `deleteLabel`, both of which
+ * take only the label's own id regardless of which kind of repo owns it. Measured
+ * as full CRUD on a throwaway database.
+ */
+export const createLabel = (
+  client: PipefyClient | null,
+  repoId: number | string,
+  label: Row,
+  kind: 'pipe' | 'table' = 'pipe',
+) =>
+  buildGraphql(
+    client,
+    'createLabel',
+    {
+      ...(kind === 'table' ? { table_id: String(repoId) } : { pipe_id: String(repoId) }),
+      name: label['name'],
+      color: label['color'],
+      uuid: label['uuid'],
+    },
+    'label { id name }',
+  );
+
+export const updateLabel = (client: PipefyClient | null, label: Row) =>
+  buildGraphql(client, 'updateLabel', { id: String(label['id']), name: label['name'], color: label['color'] }, 'label { id }');
+
+export const deleteLabel = (client: PipefyClient | null, id: string | number) =>
+  buildGraphql(client, 'deleteLabel', { id: String(id) }, 'success');
+
+// ── webhooks ─────────────────────────────────────────────────────────────────
+
+export const createWebhook = (client: PipefyClient | null, pipeId: number, hook: Row) =>
+  buildGraphql(
+    client,
+    'createWebhook',
+    {
+      pipe_id: String(pipeId),
+      name: hook['name'],
+      url: hook['url'],
+      email: hook['email'],
+      actions: hook['actions'],
+      headers: hook['headers'],
+      filters: hook['filters'],
+    },
+    'webhook { id name url }',
+  );
+
+export const updateWebhook = (client: PipefyClient | null, hook: Row) =>
+  buildGraphql(
+    client,
+    'updateWebhook',
+    { id: String(hook['id']), name: hook['name'], url: hook['url'], email: hook['email'], actions: hook['actions'], headers: hook['headers'] },
+    'webhook { id }',
+  );
+
+export const deleteWebhook = (client: PipefyClient | null, id: string | number) =>
+  buildGraphql(client, 'deleteWebhook', { id: String(id) }, 'success');
+
+// ── field conditions ─────────────────────────────────────────────────────────
+
+/**
+ * Recipe step 85 transforms the read shape into the create input: strip
+ * `label`, `phase` → `phaseId`, `phaseField` → `phaseFieldId`, keep
+ * `whenEvaluator` and `actionId`, keep the condition with its expressions.
+ * Step 109 does the same for update but emits `phase_id`.
+ */
+export const fieldConditionInput = (fc: { [k: string]: unknown; actions?: Row[]; condition?: Row | null }, style: 'create' | 'update'): Row => {
+  const cond = fc['condition'] as Row | null | undefined;
+
+  const base: Row = {
+    name: fc['name'],
+    actions: (fc['actions'] ?? []).map((a) => ({
+      actionId: a['action_id'],
+      phaseFieldId: String(a['field_id'] ?? ''),
+      whenEvaluator: a['when_evaluator'],
+    })),
+    /**
+     * Always sent, even with nothing in it.
+     *
+     * An unconditional hide — one action, no expressions — is a real and useful
+     * shape: it is how a system field that only an automation writes is kept off
+     * a human form, and real pipes carry exactly that, stored as
+     * `expressions_structure: []`. But the mutation will not accept it unless the
+     * `condition` key is present:
+     *
+     *     condition omitted     ->  "Something went wrong"
+     *     condition: null       ->  "Something went wrong"
+     *     condition: {expressions: []}  ->  works
+     *
+     * `condition` is not NON_NULL on the input type, so nothing in the schema
+     * says this, and the endpoint's answer names neither the field nor the
+     * reason. Measured by creating one condition per shape on a throwaway phase.
+     */
+    /**
+     * The same builder automations use.
+     *
+     * This path had its own copy of the expression mapping and passed
+     * `structure_id` straight through, so an authored expression that did not
+     * carry one was rejected with "Invalid input: Structure can't be blank" —
+     * `expressions_structure` names structure ids, and there was nothing to name.
+     * One builder means the derivation cannot be fixed in one place and missed in
+     * the other, which is exactly what happened.
+     */
+    condition: conditionInput(cond ?? {}),
+  };
+
+  if (style === 'create') {
+    base['phaseId'] = String(fc['phase_id'] ?? '');
+  } else {
+    base['id'] = String(fc['id'] ?? '');
+    base['phase_id'] = String(fc['phase_id'] ?? '');
+  }
+  return base;
+};
+
+export const createFieldCondition = (client: PipefyClient | null, fc: Row) =>
+  buildGraphql(client, 'createFieldCondition', fieldConditionInput(fc, 'create'), 'fieldCondition { id }');
+
+export const updateFieldCondition = (client: PipefyClient | null, fc: Row) =>
+  buildGraphql(client, 'updateFieldCondition', fieldConditionInput(fc, 'update'), 'fieldCondition { id }');
+
+export const deleteFieldCondition = (client: PipefyClient | null, id: string | number) =>
+  buildGraphql(client, 'deleteFieldCondition', { id: String(id) }, 'success');
+
+export const setFieldConditionOrder = (client: PipefyClient | null, phaseId: string | number, ids: Array<string | number>) =>
+  buildGraphql(
+    client,
+    'setFieldConditionOrder',
+    { phaseId: String(phaseId), fieldConditionIds: ids.map(String) },
+    'clientMutationId',
+  );
+
+// ── pipe relations ───────────────────────────────────────────────────────────
+
+/**
+ * Every boolean on the relation inputs is NON_NULL, and `autoFillFieldEnabled`
+ * has no column in the snapshot payload at all — so the flags are defaulted
+ * here rather than passed through as the null the payload would hand over.
+ */
+/**
+ * The mutation and the payload spell the same three flags differently.
+ *
+ * `createPipeRelation` takes `canCreateNewItems`, `canConnectExistingItems` and
+ * `canConnectMultipleItems`; the row the payload hands back calls them
+ * `can_create_connected_cards`, `can_search_connected_cards` and
+ * `can_connect_multiple_cards` — items in one, cards in the other. So a relation
+ * read from a pull carries none of the keys this builder was looking for, every
+ * one of them fell through to its `?? default`, and updating a relation's *name*
+ * silently switched off "can create new items" on it. Which is what happened to
+ * the FDE → CS handoff.
+ *
+ * Both spellings are read, mutation-side first, so a hand-authored row and a
+ * pulled row behave identically. A missing value still falls back, but now only
+ * when the value is genuinely absent.
+ */
+const relationFlags = (r: Row): Row => {
+  const flag = (...keys: string[]) => {
+    for (const k of keys) if (r[k] !== undefined && r[k] !== null) return Boolean(r[k]);
+    return undefined;
+  };
+  return {
+    canCreateNewItems: flag('can_create_new_items', 'can_create_connected_cards') ?? false,
+    canConnectExistingItems: flag('can_connect_existing_items', 'can_search_connected_cards') ?? true,
+    canConnectMultipleItems: flag('can_connect_multiple_items', 'can_connect_multiple_cards') ?? false,
+    childMustExistToMoveParent: flag('child_must_exist_to_move_parent') ?? false,
+    childMustExistToFinishParent: flag('child_must_exist_to_finish_parent') ?? false,
+    allChildrenMustBeDoneToMoveParent: flag('all_children_must_be_done_to_move_parent') ?? false,
+    allChildrenMustBeDoneToFinishParent: flag('all_children_must_be_done_to_finish_parent') ?? false,
+    autoFillFieldEnabled: flag('auto_fill_field_enabled') ?? false,
+  };
+};
+
+export const createPipeRelation = (client: PipefyClient | null, r: Row) =>
+  buildGraphql(
+    client,
+    'createPipeRelation',
+    { parentId: String(r['parent_id']), childId: String(r['child_id']), name: r['name'], ...relationFlags(r) },
+    'pipeRelation { id }',
+  );
+
+export const updatePipeRelation = (client: PipefyClient | null, r: Row) =>
+  buildGraphql(
+    client,
+    'updatePipeRelation',
+    { id: String(r['id']), name: r['name'], ...relationFlags(r) },
+    'pipeRelation { id }',
+  );
+
+export const deletePipeRelation = (client: PipefyClient | null, id: string | number) =>
+  buildGraphql(client, 'deletePipeRelation', { id: String(id) }, 'success');
+
+// ── repo root ────────────────────────────────────────────────────────────────
+
+/**
+ * `updatePipe.title_field_id` takes the field's **uuid** or its slug — never the
+ * numeric id, which is exactly what the payload column holds. Probed against the
+ * live endpoint: the numeric id is rejected with "Field not found with id", while
+ * the uuid and `request_title` are both accepted. So the numeric id is
+ * translated, and the argument is dropped rather than guessed when it cannot be.
+ */
+export const updatePipe = (client: PipefyClient | null, repo: Row, fieldUuidById: Record<string, string> = {}) =>
+  buildGraphql(
+    client,
+    'updatePipe',
+    {
+      id: String(repo['id']),
+      name: repo['name'],
+      noun: repo['noun'],
+      icon: repo['icon'],
+      color: repo['color'],
+      public: repo['public'],
+      title_field_id: repo['title_field_id'] ? fieldUuidById[String(repo['title_field_id'])] : undefined,
+      expiration_time_by_unit: repo['expiration_time'],
+      only_admin_can_remove_cards: repo['only_admin_can_remove_cards'],
+      only_assignees_can_edit_cards: repo['only_assignees_can_edit_cards'],
+      /**
+       * `anyone_can_create_card`, `create_card_label` and `description` used to
+       * be sent here. None of the three is in `UpdatePipeInput`, so all three were
+       * dropped by the introspection filter and the mutation reported success
+       * without applying them. They are refused at plan time now, by
+       * `repo.update.settableColumns`, which is the honest answer.
+       */
+    },
+    'pipe { id name }',
+  );
+
+/**
+ * The database row. A different mutation from `updatePipe`, with a different
+ * settable set — so a database's root edit must not be routed through the pipe
+ * builder, where every table-only column would be silently dropped.
+ *
+ * Two arguments disagree about identifiers, and both were measured
+ * (VALIDATION.md §3g):
+ *
+ *  - **`title_field_id` takes the field's uuid or its slug**, never the numeric
+ *    internal id, which is refused with `Field not found with id:`. The slug is
+ *    used here because a database's fields are addressed by slug everywhere else.
+ *  - **`summary_attributes` takes the numeric internal id** — or a repo attribute
+ *    slug such as `created_at` — and refuses a *field* slug with `Something went
+ *    wrong`. It is the one argument on this input that wants the internal form,
+ *    which is why it is spelled out rather than sharing a helper.
+ *
+ * `labels` and `members` are absent from `UpdateTableInput` — they can only be
+ * set when the database is created — so neither is sent, and the registry says so.
+ */
+export const updateTable = (
+  client: PipefyClient | null,
+  repo: Row,
+  fieldSlugById: Record<string, string> = {},
+) =>
+  buildGraphql(
+    client,
+    'updateTable',
+    {
+      id: String(repo['id']),
+      name: repo['name'],
+      noun: repo['noun'],
+      icon: repo['icon'],
+      color: repo['color'],
+      public: repo['public'],
+      description: repo['description'],
+      authorization: repo['authorization'],
+      create_record_button_label: repo['create_card_label'],
+      title_field_id: repo['title_field_id'] ? fieldSlugById[String(repo['title_field_id'])] : undefined,
+    },
+    'table { id internal_id name }',
+  );
+
+/**
+ * `UpdateRepoPreferencesInput` is `{ repoUuid: ID!, hiddenStartFormAttributes,
+ * hiddenTopButtons }` and nothing else — keyed on the repo **uuid**, and covering
+ * only those two arrays. Everything an earlier version sent here (start form
+ * title, custom sorting, the AI toggles) simply has no input.
+ *
+ * The three preferences that *are* settable elsewhere go through
+ * `updatePipe.preferences`, which is `RepoPreferenceInput`: findable,
+ * inboxEmailEnabled, mainTabViews.
+ */
+export const updateRepoPreferences = (client: PipefyClient | null, repoUuid: string | null, prefs: Row) =>
+  buildGraphql(
+    client,
+    'updateRepoPreferences',
+    {
+      repoUuid: repoUuid ?? undefined,
+      hiddenStartFormAttributes: prefs['hidden_start_form_attributes'],
+      hiddenTopButtons: prefs['hidden_top_buttons'],
+    },
+    'clientMutationId',
+  );
+
+/** The preference subset `updatePipe` accepts, as `RepoPreferenceInput`. */
+export const updatePipePreferences = (client: PipefyClient | null, repoId: number, prefs: Row) =>
+  buildGraphql(
+    client,
+    'updatePipe',
+    {
+      id: String(repoId),
+      preferences: {
+        findable: prefs['findable'],
+        inboxEmailEnabled: prefs['inbox_email_enabled'],
+        mainTabViews: prefs['main_tab_views'],
+      },
+    },
+    'pipe { id }',
+  );
+
+/** The public form, as `updatePipe.publicFormSettings`. */
+export const updatePublicForm = (client: PipefyClient | null, repoId: number, form: Row) =>
+  buildGraphql(
+    client,
+    'updatePipe',
+    {
+      id: String(repoId),
+      publicFormSettings: {
+        title: form['title'],
+        description: form['description'],
+        submitButtonText: form['submit_button_text'],
+        afterSubmitMessage: form['after_submit_message'],
+        brandColor: form['brand_color'],
+        backgroundColor: form['background_color'],
+        displayPipefyLogo: form['display_pipefy_logo'],
+        showSubmitAnotherResponseButton: form['show_submit_another_response_button'],
+        submitterEmailCollectionEnabled: form['submitter_email_collection_enabled'],
+        reuseLastSubmissionResponse: form['reuse_last_submission_response'],
+      },
+    },
+    'pipe { id }',
+  );
+
+// ── automations (internal endpoint) ──────────────────────────────────────────
+
+/**
+ * Variables for the internal `createAutomation`, built from a workspace
+ * automation node. The recipes send exactly this variable set (step 121).
+ */
+/**
+ * The payload's snake_case params to the names the *input* types accept.
+ *
+ * Introspected from `AutomationActionParamsInput` and `AutomationEventParamsInput`,
+ * because the casing is genuinely inconsistent — `card_id`, `to_phase_id`,
+ * `field_map` and `fields_map_order` are snake_case while `taskParams`,
+ * `aiParams`, `slaParams`, `httpMethod` and the `authentication*` keys are camel.
+ * No generic camelizer produces this, which is why it is a table.
+ *
+ * Getting it wrong is not cosmetic: sending `task_params` had the recreate half
+ * of an automation update rejected *after* the delete half had succeeded, which
+ * destroyed a live automation. Every `send_a_task` automation in a pipe goes
+ * through this path.
+ */
+const ACTION_PARAM_INPUT_NAMES: Record<string, string> = {
+  task_params: 'taskParams',
+  ai_params: 'aiParams',
+  ai_behavior_params: 'aiBehaviorParams',
+  sla_params: 'slaParams',
+  http_method: 'httpMethod',
+  authentication_key: 'authenticationKey',
+  authentication_value: 'authenticationValue',
+  authentication_add_to: 'authenticationAddTo',
+  authentication_type: 'authenticationType',
+  oauth2_uuid: 'oauth2Uuid',
+};
+
+const EVENT_PARAM_INPUT_NAMES: Record<string, string> = {
+  from_phase_id: 'fromPhaseId',
+  in_phase_id: 'inPhaseId',
+  kind_of_sla: 'kindOfSla',
+  trigger_automation_id: 'triggerAutomationId',
+  trigger_field_ids: 'triggerFieldIds',
+};
+
+/** Nested inputs have their own names again: AutomationAiParamsInput is camel. */
+const NESTED_PARAM_INPUT_NAMES: Record<string, string> = {
+  field_ids: 'fieldIds',
+  skills_ids: 'skillsIds',
+  mcp_server_config: 'mcpServerConfig',
+  start_hour: 'startHour',
+  end_hour: 'endHour',
+  // AiBehaviorParamsInput / AiBehaviorActionAttributesInput / AiBehaviorMetadataInput —
+  // same reasoning: the wire shape is camel two and three levels down from
+  // action_params too, confirmed against captured createAiAgent/updateAiAgent
+  // traffic (src/pipefy/agents.ts has the read side of the same shape).
+  data_source_ids: 'dataSourceIds',
+  referenced_field_ids: 'referencedFieldIds',
+  provider_id: 'providerId',
+  system_provider_id: 'systemProviderId',
+  capabilities_attributes: 'capabilitiesAttributes',
+  capability_type: 'capabilityType',
+  actions_attributes: 'actionsAttributes',
+  action_type: 'actionType',
+  reference_id: 'referenceId',
+  destination_phase_id: 'destinationPhaseId',
+  pipe_id: 'pipeId',
+  table_id: 'tableId',
+  email_template_id: 'emailTemplateId',
+  allow_template_modifications: 'allowTemplateModifications',
+  mcp_server_id: 'mcpServerId',
+  tool_name: 'toolName',
+  tool_inputs: 'toolInputs',
+  fields_attributes: 'fieldsAttributes',
+  field_id: 'fieldId',
+  input_mode: 'inputMode',
+};
+
+/** Keys the read path adds that no input accepts. */
+const NOT_INPUT_KEYS = new Set(['has_authentication_value', 'hasAuthenticationValue', 'phase']);
+
+const toInputNames = (value: unknown, top: Record<string, string>): unknown => {
+  if (Array.isArray(value)) return value.map((v) => toInputNames(v, NESTED_PARAM_INPUT_NAMES));
+  if (value && typeof value === 'object') {
+    const out: Row = {};
+    for (const [k, v] of Object.entries(value as Row)) {
+      if (NOT_INPUT_KEYS.has(k)) continue;
+      if (v === undefined) continue;
+      const name = top[k] ?? NESTED_PARAM_INPUT_NAMES[k] ?? k;
+      out[name] = toInputNames(v, NESTED_PARAM_INPUT_NAMES);
+    }
+    return out;
+  }
+  return value;
+};
+
+/**
+ * A condition, in the shape the API actually binds.
+ *
+ * `expressions_structure` is a nested list of **structure ids**, not indices: it
+ * is how the API links each expression into the and/or tree. An expression with
+ * no `structure_id` therefore has nothing for the structure to point at, and the
+ * whole condition is dropped — mutation successful, `expressions: []` stored, no
+ * error anywhere. Measured on create and on update, with four different
+ * operation and structure shapes; only the variant carrying `structure_id`
+ * survived.
+ *
+ * Pulled automations already carry server-assigned structure ids, which is why
+ * this never showed up on a round trip and only bit hand-authored conditions.
+ * So the id is derived from position when absent and left alone when present,
+ * and the structure's leaves are stringified because that is how the API stores
+ * and compares them.
+ */
+const structureIds = (v: unknown): unknown =>
+  Array.isArray(v) ? v.map(structureIds) : v === null || v === undefined ? v : String(v);
+
+export const conditionInput = (cond: Row): Record<string, unknown> => {
+  const rows = (cond['expressions'] as Row[] | undefined) ?? [];
+  const expressions = rows.map((e, i) => ({
+    field_address: String(e['field_address'] ?? e['field_id'] ?? ''),
+    operation: e['operation'],
+    value: e['value'],
+    structure_id: e['structure_id'] ?? String(i),
+  }));
+  const declared = cond['expressions_structure'];
+  return {
+    expressions,
+    /**
+     * With no structure declared, a single and-group over every expression is the
+     * only reading that keeps them all bound. An empty structure drops them.
+     */
+    expressions_structure: declared
+      ? structureIds(declared)
+      : expressions.length
+        ? [expressions.map((e) => String(e.structure_id))]
+        : [],
+  };
+};
+
+/**
+ * Automations, on the **public** endpoint.
+ *
+ * `createAutomation`, `updateAutomation` and `deleteAutomation` are all on the
+ * public API and documented. This tool used the internal endpoint for all three,
+ * inherited from the Change Migrator recipes and never re-checked — which meant
+ * automations were the one entity written through an unversioned endpoint with no
+ * introspection and no compatibility contract, for no reason.
+ *
+ * Probed to confirm before switching: a create and a delete both succeeded
+ * against the public endpoint.
+ */
+export const createAutomation = (client: PipefyClient | null, auto: Row & { condition?: Row | null; field_maps?: Row[] }) =>
+  buildGraphql(client, 'createAutomation', automationVariables(auto), 'automation { id name event_id action_id }');
+
+export const updateAutomation = (client: PipefyClient | null, auto: Row & { condition?: Row | null; field_maps?: Row[] }) =>
+  buildGraphql(
+    client,
+    'updateAutomation',
+    { id: String(auto['id'] ?? ''), ...automationVariables(auto) },
+    'automation { id name }',
+  );
+
+export const deleteAutomation = (client: PipefyClient | null, id: string | number) =>
+  buildGraphql(client, 'deleteAutomation', { id: String(id) }, 'success');
+
+export const automationVariables = (auto: Row & { condition?: Row | null; field_maps?: Row[] }): Record<string, unknown> => {
+  const actionParams = {
+    ...((toInputNames(auto['action_params'] ?? {}, ACTION_PARAM_INPUT_NAMES) as Row) ?? {}),
+  };
+  const fieldMaps = auto['field_maps'] ?? [];
+
+  if (Array.isArray(fieldMaps) && fieldMaps.length) {
+    actionParams['field_map'] = (fieldMaps as Row[]).map((m) => ({
+      fieldId: String(m['field_id'] ?? ''),
+      value: m['value'] ?? '',
+      inputMode: m['input_mode'] ?? undefined,
+    }));
+
+    /**
+     * `fields_map_order` is not derived from `field_map` by the API — it is a
+     * separate argument, and both the automation editor and the run engine read
+     * it (not `field_map`) to know which fields the automation writes. Omitting
+     * it here does not error and does not no-op quietly either: the automation
+     * is created, `field_map` holds exactly what was authored, and the pipe
+     * still writes nothing and shows no fields configured, because nothing named
+     * them in filling order. Every observed working automation stores the same
+     * ids here as `field_map`, in the same order, so that is the default unless
+     * the row states its own.
+     */
+    actionParams['fields_map_order'] = Array.isArray(auto['fields_map_order']) && (auto['fields_map_order'] as unknown[]).length
+      ? auto['fields_map_order']
+      : (fieldMaps as Row[]).map((m) => String(m['field_id'] ?? ''));
+  }
+
+  const cond = auto['condition'] as Row | null | undefined;
+  const condition = cond ? conditionInput(cond) : undefined;
+
+  return dropUndefined({
+    name: auto['name'],
+    /**
+     * `active` was absent from this builder, so disabling an automation in the
+     * workspace silently did nothing: the mutation succeeded and the automation
+     * stayed on. Measured by toggling it and reading the row back.
+     */
+    active: typeof auto['active'] === 'boolean' ? auto['active'] : undefined,
+    action_id: auto['action_id'],
+    event_id: auto['event_id'],
+    action_repo_id: auto['action_repo_id'] ? String(auto['action_repo_id']) : undefined,
+    event_repo_id: auto['event_repo_id'] ? String(auto['event_repo_id']) : undefined,
+    event_params: toInputNames(auto['event_params'] ?? {}, EVENT_PARAM_INPUT_NAMES),
+    action_params: Object.keys(actionParams).length ? actionParams : undefined,
+    condition,
+    scheduler_frequency: auto['scheduler_frequency'] ?? undefined,
+    searchFor: auto['search_for'] && Object.keys(auto['search_for'] as Row).length ? auto['search_for'] : undefined,
+    schedulerCron: auto['scheduler_cron'] ?? undefined,
+    responseSchema: auto['response_schema'] ?? undefined,
+  }) as Record<string, unknown>;
+};
+
+// ── AI agents ────────────────────────────────────────────────────────────────
+
+/**
+ * `createAiAgent` / `updateAiAgent` — confirmed against real Pipefy web UI
+ * traffic (captured, not guessed) and reproduced directly against the API.
+ *
+ * Both take the **entire** agent in one call: `AiAgentInput` carries the
+ * agent's own fields plus its complete `behaviors` list, existing ones
+ * unchanged (by `id`) alongside whatever is new or edited — there is no
+ * per-behavior mutation. Omitting an existing behavior deletes it, which is
+ * why every caller here sends the workspace's current, complete list for
+ * that agent, never a partial one.
+ *
+ * The behavior shape nested inside is *not* `UpdateAutomationInput` — it is
+ * its own input type, confirmed camelCase at the top (`eventId`, `actionId`,
+ * `eventParams`, `active`) where the automation mutations are snake_case.
+ * Everything below that first level matches what `pipefy/agents.ts` already
+ * reads back, aliased the same way in reverse.
+ */
+
+/** A fresh v4 UUID for an `actionsAttributes[]` entry the author added with none. */
+const referenceIdFor = (a: Row): string => String(a['reference_id'] ?? a['referenceId'] ?? randomUUID());
+
+/** One behavior, in the shape `AiAgentInput.behaviors[]` actually takes. */
+export const behaviorInput = (b: Row & { condition?: Row | null }): Row => {
+  const params = (b['action_params'] as Row | undefined)?.['ai_behavior_params'] as Row | undefined;
+  const actionsAttributes = ((params?.['actions_attributes'] as Row[] | undefined) ?? []).map((a) => ({
+    ...a,
+    reference_id: referenceIdFor(a),
+  }));
+
+  const aiBehaviorParams = toInputNames(
+    { ...(params ?? {}), actions_attributes: actionsAttributes },
+    NESTED_PARAM_INPUT_NAMES,
+  );
+
+  const cond = b['condition'];
+  return dropUndefined({
+    id: b['id'] ? String(b['id']) : undefined,
+    name: b['name'],
+    active: typeof b['active'] === 'boolean' ? b['active'] : true,
+    actionId: b['action_id'] ?? 'ai_behavior',
+    eventId: b['event_id'],
+    eventParams: toInputNames(b['event_params'] ?? {}, EVENT_PARAM_INPUT_NAMES),
+    condition: cond ? conditionInput(cond as Row) : null,
+    actionParams: { aiBehaviorParams },
+  });
+};
+
+/** The agent itself plus its complete behaviors list, as `AiAgentInput`. */
+export const agentInput = (agent: Row, behaviors: Row[]): Row =>
+  dropUndefined({
+    repoUuid: agent['repoUuid'] ? String(agent['repoUuid']) : undefined,
+    name: agent['name'],
+    instruction: agent['instruction'] ?? '',
+    dataSourceIds: agent['dataSourceIds'] ?? [],
+    behaviors: behaviors.map((b) => behaviorInput(b as Row & { condition?: Row | null })),
+  });
+
+export const createAiAgent = (client: PipefyClient | null, agent: Row, behaviors: Row[]) =>
+  buildGraphql(client, 'createAiAgent', { agent: agentInput(agent, behaviors) }, 'agent { uuid name }');
+
+export const updateAiAgent = (client: PipefyClient | null, uuid: string, agent: Row, behaviors: Row[]) =>
+  buildGraphql(
+    client,
+    'updateAiAgent',
+    { uuid, agent: agentInput(agent, behaviors) },
+    'agent { uuid name behaviors { id } }',
+  );
+
+export const deleteAiAgent = (client: PipefyClient | null, uuid: string) =>
+  buildGraphql(client, 'deleteAiAgent', { uuid }, 'success');
+
+export const warnUnverified = (what: string) =>
+  warn(`${what}: shape could not be verified against this schema — the step is marked unverified and will report its own failure`);