@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/pipefy/client.js

@@ -0,0 +1,204 @@
+import { ENDPOINTS } from "../config.js";
+import { debug } from "../util/log.js";
+import { retry } from "../util/pool.js";
+export class GraphQLRequestError extends Error {
+    errors;
+    retryable;
+    status;
+    constructor(message, errors, status, retryable) {
+        super(message);
+        this.name = 'GraphQLRequestError';
+        this.errors = errors;
+        this.status = status;
+        this.retryable = retryable;
+    }
+}
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+/** Rate limiting and transient upstream faults are retryable; a bad query is not. */
+const isRetryableMessage = (m) => /rate limit|too many requests|timeout|timed out|temporarily|try again|internal server error/i.test(m);
+export class PipefyClient {
+    tokenProvider;
+    endpoint;
+    /** Every request, for `--stats` and for measuring the rate-limit ceiling. */
+    requestCount = 0;
+    retryCount = 0;
+    /** Times a 401 forced a credential refresh. Surfaced by `pipe doctor`. */
+    reauthCount = 0;
+    typeFieldCache = new Map();
+    inputFieldCache = new Map();
+    requiredInputCache = new Map();
+    mutationInputTypeCache = new Map();
+    constructor(opts) {
+        this.tokenProvider = typeof opts.token === 'string' ? async () => opts.token : opts.token;
+        this.endpoint = opts.endpoint ?? ENDPOINTS.graphql;
+    }
+    /** The current bearer, refreshed only when something rejected the last one. */
+    async token(forceRefresh = false) {
+        if (forceRefresh)
+            this.reauthCount++;
+        return this.tokenProvider({ forceRefresh });
+    }
+    async raw(query, variables, label) {
+        let refreshed = false;
+        return retry(async () => {
+            this.requestCount++;
+            const res = await fetch(this.endpoint, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${await this.token()}`,
+                    'content-type': 'application/json',
+                    accept: 'application/json',
+                },
+                body: JSON.stringify({ query, variables: variables ?? {} }),
+            });
+            /**
+             * An expired OAuth access token looks like a 401. Refresh once and let
+             * the retry loop send it again; a second 401 is a real permission
+             * problem and must not spin.
+             */
+            if ((res.status === 401 || res.status === 403) && !refreshed) {
+                refreshed = true;
+                await this.token(true);
+                const err = new Error(`HTTP ${res.status} — credential refreshed, retrying`);
+                err.retryable = true;
+                throw err;
+            }
+            const text = await res.text();
+            let body = {};
+            try {
+                body = text ? JSON.parse(text) : {};
+            }
+            catch {
+                const retryable = RETRYABLE_STATUS.has(res.status);
+                throw new GraphQLRequestError(`HTTP ${res.status} from ${this.endpoint}: ${text.slice(0, 200)}`, [], res.status, retryable);
+            }
+            if (body.errors?.length) {
+                const msg = body.errors.map((e) => e.message).join('; ');
+                const retryable = RETRYABLE_STATUS.has(res.status) || isRetryableMessage(msg);
+                throw new GraphQLRequestError(msg, body.errors, res.status, retryable);
+            }
+            if (!res.ok) {
+                throw new GraphQLRequestError(`HTTP ${res.status} from ${this.endpoint}`, [], res.status, RETRYABLE_STATUS.has(res.status));
+            }
+            if (body.data === undefined || body.data === null) {
+                throw new GraphQLRequestError('GraphQL response had no data', [], res.status, false);
+            }
+            return body.data;
+        }, { label: label ?? 'graphql' });
+    }
+    /** A query whose failure is a fact about the endpoint, not an error. */
+    async tryRaw(query, variables, label) {
+        try {
+            return await this.raw(query, variables, label);
+        }
+        catch (e) {
+            debug(`probe failed (${label ?? 'unnamed'}): ${e.message}`);
+            return null;
+        }
+    }
+    /**
+     * Which fields a type actually has.
+     *
+     * The reconstruction path (reconstruct.ts) asks for columns that PLAN.md marks
+     * unverified. Rather than sending a query that fails wholesale on one unknown
+     * field, we introspect once and ask only for what exists. One cheap query
+     * buys a read path that degrades field-by-field instead of all-or-nothing.
+     */
+    async typeFields(typeName) {
+        if (this.typeFieldCache.has(typeName))
+            return this.typeFieldCache.get(typeName) ?? null;
+        const data = await this.tryRaw('query($n:String!){ __type(name:$n){ fields{ name } } }', { n: typeName }, `introspect ${typeName}`);
+        const fields = data?.__type?.fields;
+        const set = fields ? new Set(fields.map((f) => f.name)) : null;
+        this.typeFieldCache.set(typeName, set);
+        return set;
+    }
+    /** Whether a mutation exists — the basis of capability detection (PLAN.md §1.2). */
+    async hasMutation(name) {
+        const fields = await this.typeFields('Mutation');
+        if (!fields)
+            return false;
+        return fields.has(name);
+    }
+    /**
+     * The named type of a mutation's `input` argument.
+     *
+     * Never guessed. The registry documents traps like `createFieldConditionInput`
+     * being lowercase-c while `UpdateFieldConditionInput` is not; asking the schema
+     * removes a whole class of "mutation exists, input type name wrong" failures.
+     */
+    async mutationInputType(mutation) {
+        if (this.mutationInputTypeCache.has(mutation))
+            return this.mutationInputTypeCache.get(mutation) ?? null;
+        const data = await this.tryRaw(`query {
+        __type(name: "Mutation") {
+          fields {
+            name
+            args { name type { kind name ofType { kind name ofType { kind name } } } }
+          }
+        }
+      }`, undefined, 'introspect Mutation args');
+        const field = data?.__type?.fields?.find((f) => f.name === mutation);
+        const arg = field?.args.find((a) => a.name === 'input') ?? field?.args[0];
+        const named = arg ? unwrapTypeName(arg.type) : null;
+        this.mutationInputTypeCache.set(mutation, named);
+        return named;
+    }
+    /**
+     * Input fields that are NON_NULL with no default — the ones a request must
+     * carry a value for.
+     *
+     * CreatePipeRelationInput makes every boolean required, including
+     * autoFillFieldEnabled, which the snapshot payload has no column for at all.
+     * Sent without it the mutation is rejected mid-apply; knowing up front turns
+     * that into something `pipe plan` can say before anything is written.
+     */
+    async requiredInputFields(typeName) {
+        const cached = this.requiredInputCache.get(typeName);
+        if (cached)
+            return cached;
+        const data = await this.tryRaw('query($n:String!){ __type(name:$n){ inputFields { name defaultValue type { kind } } } }', { n: typeName }, `introspect required ${typeName}`);
+        const req = new Set();
+        for (const fld of data?.__type?.inputFields ?? []) {
+            if (fld.type.kind === 'NON_NULL' && fld.defaultValue === null)
+                req.add(fld.name);
+        }
+        this.requiredInputCache.set(typeName, req);
+        return req;
+    }
+    /** The fields an input object type accepts. */
+    async inputFields(typeName) {
+        if (this.inputFieldCache.has(typeName))
+            return this.inputFieldCache.get(typeName) ?? null;
+        const data = await this.tryRaw('query($n:String!){ __type(name:$n){ inputFields{ name } } }', { n: typeName }, `introspect input ${typeName}`);
+        const fields = data?.__type?.inputFields;
+        const set = fields ? new Set(fields.map((f) => f.name)) : null;
+        this.inputFieldCache.set(typeName, set);
+        return set;
+    }
+    /**
+     * Filter a wanted selection down to what the type has. `selection` entries may
+     * be a bare field (`"label"`) or a field with a sub-selection
+     * (`["connectedRepo", "{ id name }"]`).
+     */
+    async prune(typeName, selection) {
+        const have = await this.typeFields(typeName);
+        const keep = [];
+        for (const s of selection) {
+            const [name, sub] = Array.isArray(s) ? s : [s, ''];
+            if (have && !have.has(name)) {
+                debug(`skipping ${typeName}.${name} — not in schema`);
+                continue;
+            }
+            keep.push(sub ? `${name} ${sub}` : name);
+        }
+        return keep.join('\n      ');
+    }
+}
+/** Unwrap NON_NULL / LIST wrappers down to the named type. */
+const unwrapTypeName = (t) => {
+    let cur = t;
+    while (cur && !cur.name)
+        cur = cur.ofType ?? null;
+    return cur?.name ?? null;
+};

package/dist/pipefy/discovery.js

@@ -0,0 +1,148 @@
+import { debug, step, warn } from "../util/log.js";
+import { rel } from "../model/payload.js";
+const asNum = (v) => {
+    if (v === null || v === undefined || v === '')
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+/** The three sources, applied to one already-read payload. */
+export const edgesFromPayload = (p) => {
+    const self = Number(p.id);
+    const out = [];
+    // 1. pipe_relations
+    for (const r of rel(p, 'pipe_relations')) {
+        for (const key of ['parent_id', 'child_id']) {
+            const id = asNum(r[key]);
+            if (id !== null && id !== self)
+                out.push({ to: id, kind: 'pipe_relation', label: String(r['name'] ?? '') });
+        }
+    }
+    // 2. connector fields — the only source that finds the test pipe's two
+    //    connections, and the reason this function exists.
+    for (const f of rel(p, 'fields')) {
+        if (f['type_id'] !== 'connector')
+            continue;
+        const id = asNum(f['connected_pipe_id']);
+        if (id !== null && id !== self)
+            out.push({ to: id, kind: 'connector_field', label: String(f['label'] ?? '') });
+    }
+    // 3. cross-repo automations
+    for (const a of rel(p, 'automations')) {
+        for (const key of ['event_repo_id', 'action_repo_id']) {
+            const id = asNum(a[key]);
+            if (id !== null && id !== self)
+                out.push({ to: id, kind: 'automation', label: String(a['name'] ?? '') });
+        }
+    }
+    return out;
+};
+/**
+ * Resolve a numeric repo id to what it actually is.
+ *
+ * **Neither root field discriminates.** Verified live: `pipe(id:)` and
+ * `table(id:)` both answer for *every* repo id, and both return plausible data —
+ * `pipe.phases` on a database returns its status phases, and `table.table_fields`
+ * on a pipe returns its start-form fields. A repo is one object viewed two ways.
+ * Trying `pipe` first and taking the win, as an earlier version did, classified
+ * every database as a pipe.
+ *
+ * `Table.url` is the real discriminator: a pipe lives at `/pipes/<id>` and a
+ * database at `/apollo_databases/<id>`. One query settles both the kind and
+ * PLAN.md §2.2's id duality, since `Table` carries the slug as `id` and the
+ * numeric form as `internal_id`.
+ */
+/**
+ * Resolve one repo id, in **either** spelling.
+ *
+ * `table(id:)` accepts a database's numeric internal id and its api id (a slug
+ * like `dzmxcuxz`) and always answers with the slug — measured both ways. So
+ * `pipe pull 302908356` and `pipe pull 3LhkZu_h` must reach the same database,
+ * and the `RepoRef` this returns normalises to the numeric id either way, which
+ * is what keeps one database from being pulled twice under two identities.
+ */
+export const resolveRepo = async (client, id) => {
+    const res = await client.tryRaw(`query($id: ID!) { table(id: $id) { id internal_id name uuid url } }`, { id: String(id) }, `resolve repo ${id}`);
+    const repo = res?.table;
+    if (!repo)
+        return null;
+    const url = String(repo.url ?? '');
+    const kind = /apollo_databases/.test(url) ? 'table' : 'pipe';
+    debug(`repo ${id} is a ${kind} (${url || 'no url'})`);
+    return {
+        kind,
+        id: Number(repo.internal_id ?? id),
+        /** The slug for a database, the numeric string for a pipe. */
+        apiId: kind === 'table' ? String(repo.id) : String(repo.internal_id ?? id),
+        name: repo.name,
+        uuid: repo.uuid ?? null,
+        via: [],
+        depth: 0,
+    };
+};
+/**
+ * Walk outward from a root repo. `read` is injected so discovery works
+ * identically whether payloads come from snapshots or from reconstruction.
+ */
+export const discover = async (client, rootId, opts) => {
+    const found = new Map();
+    const edges = [];
+    const warnings = [];
+    const root = await resolveRepo(client, rootId);
+    if (!root)
+        throw new Error(`repo ${rootId} is neither a readable pipe nor a readable table`);
+    root.via = ['root'];
+    found.set(rootId, root);
+    let frontier = [root];
+    for (let depth = 0; depth <= opts.depth && frontier.length; depth++) {
+        const next = [];
+        for (const ref of frontier) {
+            if (depth === opts.depth)
+                break;
+            const payload = await opts.read(ref);
+            if (!payload) {
+                warnings.push(`${ref.kind} ${ref.id} (${ref.name ?? '?'}) could not be read — its connections are unexplored`);
+                continue;
+            }
+            for (const e of edgesFromPayload(payload)) {
+                edges.push({ from: ref.id, to: e.to, kind: e.kind, label: e.label });
+                const seen = found.get(e.to);
+                if (seen) {
+                    if (!seen.via.includes(e.kind))
+                        seen.via.push(e.kind);
+                    continue;
+                }
+                const resolved = await resolveRepo(client, e.to);
+                if (!resolved) {
+                    warnings.push(`${ref.kind} ${ref.id} references repo ${e.to} via ${e.kind}, but the token cannot read it — ` +
+                        `the pull is partial (PLAN.md §9, cross-repo permission)`);
+                    continue;
+                }
+                resolved.via = [e.kind];
+                resolved.depth = depth + 1;
+                found.set(e.to, resolved);
+                next.push(resolved);
+                debug(`discovered ${resolved.kind} ${resolved.id} "${resolved.name}" via ${e.kind}`);
+            }
+        }
+        frontier = next;
+    }
+    const repos = [...found.values()].sort((a, b) => a.depth - b.depth || a.id - b.id);
+    step(`discovered ${repos.length} repo${repos.length === 1 ? '' : 's'} within depth ${opts.depth}`);
+    for (const w of warnings)
+        warn(w);
+    return { repos, edges, warnings };
+};
+/**
+ * `pipeMapGraph` is kept for the graph view and for `hasHiddenAutomations` —
+ * never as the discovery mechanism. PLAN.md §2.2 and ask 7.
+ */
+export const mapGraph = async (client, repoId, depth = 2) => {
+    const data = await client.tryRaw(`query($id: ID!, $depth: Int) {
+      pipeMapGraph(pipeId: $id, depth: $depth) {
+        nodes { id name __typename hasHiddenAutomations hasHiddenIntegrations }
+        edges { from to }
+      }
+    }`, { id: String(repoId), depth }, 'pipeMapGraph');
+    return data?.pipeMapGraph ?? null;
+};

package/dist/pipefy/internal.js

@@ -0,0 +1,315 @@
+import { ENDPOINTS } from "../config.js";
+import { debug, warn } from "../util/log.js";
+import { retry } from "../util/pool.js";
+export class InternalApi {
+    tokenProvider;
+    status = 'unknown';
+    requestCount = 0;
+    /** Set once, so a broken endpoint produces one warning and not one per call. */
+    warned = false;
+    constructor(token) {
+        this.tokenProvider = typeof token === 'string' ? async () => token : token;
+    }
+    async bearer() {
+        return this.tokenProvider();
+    }
+    markUnavailable(reason) {
+        this.status = 'unavailable';
+        if (!this.warned) {
+            this.warned = true;
+            warn(`internal API unavailable (${reason}). Automation details and phase jumps ` +
+                `will be reported as unknown rather than empty — see PLAN.md §2.1.`);
+        }
+    }
+    /** GraphQL over the internal endpoint. Returns null when the endpoint fails. */
+    async gql(query, variables, label) {
+        try {
+            const data = await retry(async () => {
+                this.requestCount++;
+                const res = await fetch(ENDPOINTS.internal, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${await this.bearer()}`,
+                        'content-type': 'application/json',
+                        accept: 'application/json',
+                    },
+                    body: JSON.stringify({ query, variables }),
+                });
+                const text = await res.text();
+                if (!res.ok) {
+                    const err = new Error(`HTTP ${res.status}: ${text.slice(0, 160)}`);
+                    err.retryable = res.status >= 500 || res.status === 429;
+                    throw err;
+                }
+                const body = JSON.parse(text);
+                if (body.errors?.length) {
+                    const err = new Error(body.errors.map((e) => e.message).join('; '));
+                    err.retryable = false;
+                    throw err;
+                }
+                return body.data ?? null;
+            }, { label });
+            if (data)
+                this.status = 'ok';
+            return data;
+        }
+        catch (e) {
+            debug(`internal gql ${label} failed: ${e.message}`);
+            this.markUnavailable(`${label}: ${e.message}`);
+            return null;
+        }
+    }
+    // ── Automations ────────────────────────────────────────────────────────────
+    /** Recipe `Pipe Data Treatment` step 156. */
+    async listAutomations(orgId, repoId) {
+        const q = `
+      query getAutomations($orgId: ID!, $repoId: ID) {
+        automations(organizationId: $orgId, repoId: $repoId) {
+          id
+          name
+          action_id
+          event_id
+          created_at
+          active
+          action_repo: action_repo_v2 {
+            __typename
+            ... on Pipe { id }
+            ... on Table { id }
+          }
+          event_repo { __typename id }
+        }
+      }`;
+        const data = await this.gql(q, { orgId: String(orgId), repoId: String(repoId) }, 'listAutomations');
+        return data?.automations ?? null;
+    }
+    /**
+     * Recipe `Apply Changes` step 118 — the full editable definition. This is the
+     * only read path that returns `action_params.field_map`, `searchFor`,
+     * `responseSchema` and `aiParams`, which is why the reconstruction path
+     * cannot avoid the internal API for automations.
+     */
+    async loadAutomation(id) {
+        const q = `
+      query loadAutomationToEdit($id: ID!) {
+        automation(id: $id) {
+          name
+          event_id
+          active
+          event_repo { id }
+          event_params {
+            toPhaseId: to_phase_id
+            fromPhaseId
+            inPhaseId
+            triggerFieldIds
+            kindOfSla
+            triggerAutomationId
+          }
+          action_id
+          action_repo: action_repo_v2 {
+            ... on Pipe { id uuid }
+            ... on Table { id uuid }
+          }
+          scheduler_frequency
+          schedulerCron { minute hour dayOfWeek dayOfMonth month }
+          searchFor { id field operation value }
+          responseSchema
+          action_params {
+            toPhaseId: to_phase_id
+            fieldsMapOrder: fields_map_order
+            email_template_id
+            fieldMap: field_map { fieldId value inputMode }
+            cardId: card_id
+            headers
+            body
+            url
+            httpMethod
+            authenticationKey
+            hasAuthenticationValue
+            authenticationAddTo
+            authenticationType
+            strategy
+            # taskParams is not in the recipe's query, and the omission is not
+            # cosmetic: every send_a_task automation came back with an empty
+            # action_params, so a reconstructed read lost its recipients and
+            # title, and a recreate would have rebuilt it blank. Introspected
+            # from AutomationActionParams on the internal endpoint.
+            taskParams { recipients title }
+            aiParams { fieldIds value skillsIds }
+            aiBehaviorParams
+            slaParams {
+              monday { startHour endHour enabled }
+              tuesday { startHour endHour enabled }
+              wednesday { startHour endHour enabled }
+              thursday { startHour endHour enabled }
+              friday { startHour endHour enabled }
+              saturday { startHour endHour enabled }
+              sunday { startHour endHour enabled }
+              timezone
+              holidays { date recurrence description }
+            }
+          }
+          condition {
+            expressions_structure
+            expressions { id field_address operation value structure_id }
+          }
+        }
+      }`;
+        const data = await this.gql(q, { id: String(id) }, `loadAutomation ${id}`);
+        return data?.automation ?? null;
+    }
+    /** Recipe `Apply Changes` step 121. `input` is the AutomationInput variable set. */
+    async createAutomation(vars) {
+        const q = `
+      mutation createAutomation(
+        $name: String!, $action_id: ID!, $event_id: ID!,
+        $action_repo_id: ID, $event_repo_id: ID,
+        $event_params: AutomationEventParamsInput,
+        $action_params: AutomationActionParamsInput,
+        $condition: ConditionInput,
+        $scheduler_frequency: String,
+        $searchFor: [SearchConditionInput],
+        $schedulerCron: CronInput,
+        $responseSchema: JSON
+      ) {
+        createAutomation(input: {
+          name: $name, action_id: $action_id, event_id: $event_id,
+          action_repo_id: $action_repo_id, event_repo_id: $event_repo_id,
+          event_params: $event_params, action_params: $action_params,
+          condition: $condition, scheduler_frequency: $scheduler_frequency,
+          searchFor: $searchFor, schedulerCron: $schedulerCron,
+          responseSchema: $responseSchema
+        }) {
+          automation { id }
+          error_details { object_key messages }
+        }
+      }`;
+        const data = await this.gql(q, vars, 'createAutomation');
+        const payload = data?.createAutomation;
+        if (!payload)
+            return null;
+        if (payload.error_details?.length) {
+            const detail = payload.error_details.map((d) => `${d.object_key}: ${d.messages.join(', ')}`).join(' | ');
+            throw new Error(`createAutomation rejected — ${detail}`);
+        }
+        return payload.automation;
+    }
+    /** Recipe `Apply Changes` step 126. */
+    async deleteAutomation(id) {
+        const q = `
+      mutation deleteAutomation($id: ID!) {
+        deleteAutomation(input: { id: $id }) { success }
+      }`;
+        const data = await this.gql(q, { id: String(id) }, `deleteAutomation ${id}`);
+        return Boolean(data?.deleteAutomation?.success);
+    }
+    // ── Phase jumps ────────────────────────────────────────────────────────────
+    /**
+     * `GET /internal_api/settings/phases/:id` — recipe step 23.
+     *
+     * **The GET and the PUT answer in different shapes.** Both captured live:
+     *
+     *   GET  { data: { attributes: { name, phases: [[id, name, done], …],
+     *                                jump_targets: [344054275] } } }
+     *   PUT  { data: { name, back_phase_ids: [], next_phase_ids: [344054275] } }
+     *
+     * The GET's `jump_targets` is one merged set, which is exactly what the
+     * payload's `phase_jumps` array holds. Reading it as `data.next_phase_ids` —
+     * the shape PLAN.md §2.1 recorded, from the PUT — yields an empty set for
+     * every phase without any error, and a diff that then proposes deleting every
+     * jump in the pipe.
+     */
+    async getPhaseSettings(phaseId) {
+        try {
+            const res = await retry(async () => {
+                this.requestCount++;
+                const r = await fetch(`${ENDPOINTS.internalSettings}/phases/${phaseId}`, {
+                    method: 'GET',
+                    headers: { authorization: `Bearer ${await this.bearer()}`, accept: 'application/json' },
+                });
+                if (!r.ok) {
+                    const err = new Error(`HTTP ${r.status}`);
+                    err.retryable = r.status >= 500 || r.status === 429;
+                    throw err;
+                }
+                return (await r.json());
+            }, { label: `getPhaseSettings ${phaseId}` });
+            const d = res.data ?? {};
+            const attrs = d.attributes ?? {};
+            const targets = attrs.jump_targets ?? d.jump_targets ?? [...(d.next_phase_ids ?? []), ...(d.back_phase_ids ?? [])];
+            this.status = 'ok';
+            return {
+                jump_targets: [...new Set(targets.map(Number).filter((n) => Number.isFinite(n)))],
+                phases: (attrs.phases ?? []).map(([id, name, done]) => ({ id: Number(id), name: String(name), done: Boolean(done) })),
+            };
+        }
+        catch (e) {
+            debug(`getPhaseSettings ${phaseId} failed: ${e.message}`);
+            this.markUnavailable(`getPhaseSettings: ${e.message}`);
+            return null;
+        }
+    }
+    /**
+     * `PUT /internal_api/settings/phases/:id` with the complete desired jump set.
+     * Recipe step 24 does the same thing in Python. Set-replacing, so we send the
+     * whole set and assert on the echoed `next_phase_ids` rather than on the HTTP
+     * status — PLAN.md §2.1.
+     */
+    async setPhaseJumpTargets(phaseId, targetPhaseIds) {
+        const params = new URLSearchParams();
+        if (targetPhaseIds.length === 0) {
+            // An empty set still has to be expressible, or "remove the last jump"
+            // becomes impossible. The form convention for an empty array is a single
+            // blank entry.
+            params.append('phase[jump_target_ids][]', '');
+        }
+        for (const t of targetPhaseIds)
+            params.append('phase[jump_target_ids][]', String(t));
+        try {
+            const res = await retry(async () => {
+                this.requestCount++;
+                const r = await fetch(`${ENDPOINTS.internalSettings}/phases/${phaseId}`, {
+                    method: 'PUT',
+                    headers: {
+                        authorization: `Bearer ${await this.bearer()}`,
+                        'content-type': 'application/x-www-form-urlencoded',
+                        accept: 'application/json',
+                    },
+                    body: params.toString(),
+                });
+                const text = await r.text();
+                if (!r.ok) {
+                    const err = new Error(`HTTP ${r.status}: ${text.slice(0, 160)}`);
+                    err.retryable = r.status >= 500 || r.status === 429;
+                    throw err;
+                }
+                return JSON.parse(text);
+            }, { label: `setPhaseJumpTargets ${phaseId}` });
+            /**
+             * The echo is the union of both directions.
+             *
+             * `next_phase_ids` alone is forward-only, so a jump to an *earlier* phase
+             * echoes back as an empty next list even though the write succeeded — which
+             * this assertion reported as a failed write. Asserting on the union is what
+             * the sent set actually means.
+             */
+            const d = res.data ?? {};
+            const echoed = [
+                ...(d.attributes?.jump_targets ?? []),
+                ...(d.jump_targets ?? []),
+                ...(d.next_phase_ids ?? []),
+                ...(d.back_phase_ids ?? []),
+            ].map(Number);
+            const want = [...new Set(targetPhaseIds.map(Number))].sort((a, b) => a - b);
+            const got = [...new Set(echoed)].sort((a, b) => a - b);
+            const ok = want.length === got.length && want.every((v, i) => v === got[i]);
+            this.status = 'ok';
+            return ok
+                ? { ok, echoed }
+                : { ok, echoed, error: `echo mismatch: wanted [${want.join(',')}], endpoint reports [${got.join(',')}]` };
+        }
+        catch (e) {
+            this.markUnavailable(`setPhaseJumpTargets: ${e.message}`);
+            return { ok: false, echoed: [], error: e.message };
+        }
+    }
+}