@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/apply/mutations.js

@@ -0,0 +1,704 @@
+import { randomUUID } from 'node:crypto';
+import { debug, warn } from "../util/log.js";
+/**
+ * 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) => {
+    const out = {};
+    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, mutation, input, selection) => {
+    /**
+     * 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();
+    const filtered = {};
+    const dropped = [];
+    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, pipeId, phase) => 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, phase) => 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, phaseId) => 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, phaseId, settings) => 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'].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) => ({
+    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, phaseId, field) => 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, field) => 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) => ({
+    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, tableId, field) => 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, tableId, field) => 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, tableId, field) => 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, tableId, fields) => 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) => 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, field, pipeUuid) => {
+    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, field, archived) => 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, repoId, label, kind = '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, label) => buildGraphql(client, 'updateLabel', { id: String(label['id']), name: label['name'], color: label['color'] }, 'label { id }');
+export const deleteLabel = (client, id) => buildGraphql(client, 'deleteLabel', { id: String(id) }, 'success');
+// ── webhooks ─────────────────────────────────────────────────────────────────
+export const createWebhook = (client, pipeId, hook) => 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, hook) => 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, id) => 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, style) => {
+    const cond = fc['condition'];
+    const base = {
+        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, fc) => buildGraphql(client, 'createFieldCondition', fieldConditionInput(fc, 'create'), 'fieldCondition { id }');
+export const updateFieldCondition = (client, fc) => buildGraphql(client, 'updateFieldCondition', fieldConditionInput(fc, 'update'), 'fieldCondition { id }');
+export const deleteFieldCondition = (client, id) => buildGraphql(client, 'deleteFieldCondition', { id: String(id) }, 'success');
+export const setFieldConditionOrder = (client, phaseId, ids) => 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) => {
+    const flag = (...keys) => {
+        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, r) => buildGraphql(client, 'createPipeRelation', { parentId: String(r['parent_id']), childId: String(r['child_id']), name: r['name'], ...relationFlags(r) }, 'pipeRelation { id }');
+export const updatePipeRelation = (client, r) => buildGraphql(client, 'updatePipeRelation', { id: String(r['id']), name: r['name'], ...relationFlags(r) }, 'pipeRelation { id }');
+export const deletePipeRelation = (client, id) => 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, repo, fieldUuidById = {}) => 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, repo, fieldSlugById = {}) => 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, repoUuid, prefs) => 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, repoId, prefs) => 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, repoId, form) => 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 = {
+    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 = {
+    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 = {
+    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, top) => {
+    if (Array.isArray(value))
+        return value.map((v) => toInputNames(v, NESTED_PARAM_INPUT_NAMES));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            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) => Array.isArray(v) ? v.map(structureIds) : v === null || v === undefined ? v : String(v);
+export const conditionInput = (cond) => {
+    const rows = cond['expressions'] ?? [];
+    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, auto) => buildGraphql(client, 'createAutomation', automationVariables(auto), 'automation { id name event_id action_id }');
+export const updateAutomation = (client, auto) => buildGraphql(client, 'updateAutomation', { id: String(auto['id'] ?? ''), ...automationVariables(auto) }, 'automation { id name }');
+export const deleteAutomation = (client, id) => buildGraphql(client, 'deleteAutomation', { id: String(id) }, 'success');
+export const automationVariables = (auto) => {
+    const actionParams = {
+        ...(toInputNames(auto['action_params'] ?? {}, ACTION_PARAM_INPUT_NAMES) ?? {}),
+    };
+    const fieldMaps = auto['field_maps'] ?? [];
+    if (Array.isArray(fieldMaps) && fieldMaps.length) {
+        actionParams['field_map'] = fieldMaps.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'].length
+            ? auto['fields_map_order']
+            : fieldMaps.map((m) => String(m['field_id'] ?? ''));
+    }
+    const cond = auto['condition'];
+    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']).length ? auto['search_for'] : undefined,
+        schedulerCron: auto['scheduler_cron'] ?? undefined,
+        responseSchema: auto['response_schema'] ?? undefined,
+    });
+};
+// ── 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) => String(a['reference_id'] ?? a['referenceId'] ?? randomUUID());
+/** One behavior, in the shape `AiAgentInput.behaviors[]` actually takes. */
+export const behaviorInput = (b) => {
+    const params = b['action_params']?.['ai_behavior_params'];
+    const actionsAttributes = (params?.['actions_attributes'] ?? []).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) : null,
+        actionParams: { aiBehaviorParams },
+    });
+};
+/** The agent itself plus its complete behaviors list, as `AiAgentInput`. */
+export const agentInput = (agent, behaviors) => dropUndefined({
+    repoUuid: agent['repoUuid'] ? String(agent['repoUuid']) : undefined,
+    name: agent['name'],
+    instruction: agent['instruction'] ?? '',
+    dataSourceIds: agent['dataSourceIds'] ?? [],
+    behaviors: behaviors.map((b) => behaviorInput(b)),
+});
+export const createAiAgent = (client, agent, behaviors) => buildGraphql(client, 'createAiAgent', { agent: agentInput(agent, behaviors) }, 'agent { uuid name }');
+export const updateAiAgent = (client, uuid, agent, behaviors) => buildGraphql(client, 'updateAiAgent', { uuid, agent: agentInput(agent, behaviors) }, 'agent { uuid name behaviors { id } }');
+export const deleteAiAgent = (client, uuid) => buildGraphql(client, 'deleteAiAgent', { uuid }, 'success');
+export const warnUnverified = (what) => warn(`${what}: shape could not be verified against this schema — the step is marked unverified and will report its own failure`);