@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

package/dist/pipefy/internal.js

@@ -0,0 +1,406 @@
+import { ENDPOINTS } from "../config.js";
+import { debug, warn } from "../util/log.js";
+import { retry } from "../util/pool.js";
+import { AI_BEHAVIOR_PARAMS_SELECTION } from "./agents.js";
+/**
+ * The internal-API adapter. PLAN.md §2.1 flags this as an unversioned endpoint
+ * with no compatibility contract, so it is isolated here, behind one module,
+ * and every entry point degrades to `null`/`unsupported` rather than throwing.
+ *
+ * Two things live only here — both taken from the Change Migrator recipes,
+ * which have been running them in production:
+ *
+ *  1. Automations. Public `getAutomations` returns a summary; the recipes use
+ *     `loadAutomationToEdit` to get `action_params.field_map`, `searchFor`,
+ *     `responseSchema`, `schedulerCron` and `aiParams` — everything a
+ *     round trip needs and the summary omits.
+ *  2. Phase jumps. `GET/PUT /internal_api/settings/phases/:id`, set-replacing.
+ *
+ * Both accept the same personal API token as the public endpoint, so there is
+ * no session-cookie or CSRF subsystem here.
+ */
+/** Sent by `listAutomations`; module-level so `checkQueries` validates the same text. */
+const LIST_AUTOMATIONS_QUERY = `
+  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 }
+    }
+  }`;
+/** Sent by `loadAutomation`; module-level so `checkQueries` validates the same text. */
+const LOAD_AUTOMATION_QUERY = `
+  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 ${AI_BEHAVIOR_PARAMS_SELECTION}
+        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 }
+      }
+    }
+  }`;
+/**
+ * Every read query document this adapter sends over GraphQL, with variables
+ * that match nothing. GraphQL validates the document before resolving any of
+ * it, so a query that has drifted from the schema is refused the same way
+ * whichever id it names — and a valid one answers `data` with a not-found
+ * error. No write is in this list, and none may be added: probing is not free
+ * on this platform (AGENTS.md §4).
+ */
+const READ_QUERIES = [
+    { label: 'listAutomations', query: LIST_AUTOMATIONS_QUERY, variables: { orgId: '0', repoId: '0' } },
+    { label: 'loadAutomation', query: LOAD_AUTOMATION_QUERY, variables: { id: '0' } },
+];
+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) {
+        if (this.status !== 'incompatible')
+            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.`);
+        }
+    }
+    /** One answered call does not clear a refused query: that stays visible. */
+    markOk() {
+        if (this.status !== 'incompatible')
+            this.status = 'ok';
+    }
+    markIncompatible(label, reason) {
+        this.status = 'incompatible';
+        if (!this.warned) {
+            this.warned = true;
+            warn(`internal API rejected this tool's ${label} query as invalid (${reason}). ` +
+                `That is a bug in pipe, not an outage — the endpoint changed under it. Automation ` +
+                `details will be reported as unknown rather than empty; \`pipe doctor\` checks every internal query.`);
+        }
+    }
+    /**
+     * Validate every read query against the live schema without reading anything
+     * real. Null when the endpoint itself could not be reached, which says
+     * nothing about the queries.
+     */
+    async checkQueries() {
+        const results = [];
+        for (const { label, query, variables } of READ_QUERIES) {
+            let body;
+            try {
+                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 }),
+                });
+                if (!res.ok) {
+                    debug(`internal query check ${label}: HTTP ${res.status}`);
+                    return null;
+                }
+                body = JSON.parse(await res.text());
+            }
+            catch (e) {
+                debug(`internal query check ${label}: ${e.message}`);
+                return null;
+            }
+            if ('data' in body)
+                results.push({ label, ok: true });
+            else
+                results.push({ label, ok: false, message: (body.errors ?? []).map((e) => e.message).join('; ') || 'no data' });
+        }
+        this.status = results.every((r) => r.ok) ? 'ok' : 'incompatible';
+        return results;
+    }
+    /** 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;
+                    // No `data` key at all is a document the schema refused, not a
+                    // resolver failing on this one id — see InternalStatus.
+                    err.invalidQuery = !('data' in body);
+                    throw err;
+                }
+                return body.data ?? null;
+            }, { label });
+            if (data)
+                this.markOk();
+            return data;
+        }
+        catch (e) {
+            debug(`internal gql ${label} failed: ${e.message}`);
+            if (e.invalidQuery)
+                this.markIncompatible(label, e.message);
+            else
+                this.markUnavailable(`${label}: ${e.message}`);
+            return null;
+        }
+    }
+    // ── Automations ────────────────────────────────────────────────────────────
+    /** Recipe `Pipe Data Treatment` step 156. */
+    async listAutomations(orgId, repoId) {
+        const data = await this.gql(LIST_AUTOMATIONS_QUERY, { 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 data = await this.gql(LOAD_AUTOMATION_QUERY, { 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.markOk();
+            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.markOk();
+            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 };
+        }
+    }
+}

package/dist/pipefy/ipaas.js

@@ -0,0 +1,269 @@
+import { debug } from "../util/log.js";
+/**
+ * A pipe's iPaaS workspace — "Advanced Automations", Activepieces underneath.
+ *
+ * Every pipe has its own workspace, and the session proves it: the identity that
+ * comes back has the pipe's name as `firstName` and its id as `lastName`. Flows
+ * and connections are scoped to it, so a flow belongs to exactly one pipe even
+ * though it may orchestrate across many.
+ *
+ * Authentication needs no new credential. Two hops from the token `pipe` already
+ * holds:
+ *
+ *   1. the INTERNAL API mints a short-lived, pipe-scoped JWT
+ *      (`advancedAutomationsToken(repoId:)`)
+ *   2. `POST /managed-authn/external-token` exchanges it for a session — which
+ *      also hands back the projectId, so nothing has to be configured
+ *
+ * The OAuth + PKCE dance in Pipefy's own gateway exists only to reach the iPaaS
+ * MCP tool surface. The REST API used here answers the step-2 session directly.
+ */
+export const IPAAS_BASE = 'https://ipaas.pipefy.com/api/v1';
+/**
+ * Operations that act on an empty request instead of rejecting it.
+ *
+ * Learned the hard way: probing the enum by sending every candidate with
+ * `request: {}` published and enabled a draft flow, because these four do not
+ * validate a request they can default. Nothing in this module may send one
+ * without an explicit, complete request.
+ */
+export const ACTS_ON_EMPTY_REQUEST = new Set([
+    'CHANGE_STATUS',
+    'LOCK_AND_PUBLISH',
+    'LOCK_FLOW',
+    'CHANGE_FOLDER',
+    'UPDATE_METADATA',
+]);
+export class IpaasError extends Error {
+    status;
+    step;
+    constructor(step, status, body) {
+        super(`iPaaS ${step} failed (HTTP ${status}): ${body.slice(0, 300)}`);
+        this.name = 'IpaasError';
+        this.status = status;
+        this.step = step;
+    }
+}
+/** iPaaS is off for the org, or the caller cannot administer this pipe's automations. */
+export class IpaasUnavailable extends Error {
+    pipeId;
+    constructor(pipeId, reason) {
+        super(reason);
+        this.name = 'IpaasUnavailable';
+        this.pipeId = pipeId;
+    }
+}
+export class IpaasClient {
+    internal;
+    base;
+    /** pipeId → session, because minting is two round trips and a pull does many reads. */
+    sessions = new Map();
+    /** A session lives a while, but not forever; re-mint rather than discover expiry mid-apply. */
+    static TTL_MS = 10 * 60 * 1000;
+    constructor(internal, base = IPAAS_BASE) {
+        this.internal = internal;
+        this.base = base.replace(/\/$/, '');
+    }
+    /**
+     * Whether this pipe has a reachable iPaaS workspace.
+     *
+     * A refusal here is `unknown` coverage, never "no flows" — the distinction the
+     * whole coverage doctrine rests on. Minting requires iPaaS enabled on the
+     * organization and permission to create automations on the pipe.
+     */
+    async available(pipeId) {
+        try {
+            const session = await this.session(pipeId);
+            return { ok: true, session };
+        }
+        catch (e) {
+            return { ok: false, reason: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async session(pipeId) {
+        const hit = this.sessions.get(pipeId);
+        if (hit && Date.now() - hit.at < IpaasClient.TTL_MS)
+            return hit.session;
+        const minted = await this.internal.gql(`query GetAdvancedAutomationsToken($repoId: ID!) {
+         advancedAutomationsToken(repoId: $repoId) { token }
+       }`, { repoId: String(pipeId) }, 'GetAdvancedAutomationsToken');
+        const token = minted?.advancedAutomationsToken?.token;
+        if (!token) {
+            throw new IpaasUnavailable(pipeId, `no advanced-automations token for pipe ${pipeId} — iPaaS may be off for this organization, ` +
+                'or this credential may not be allowed to create automations on the pipe');
+        }
+        const res = await fetch(`${this.base}/managed-authn/external-token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ externalAccessToken: token }),
+        });
+        const body = await res.text();
+        if (!res.ok)
+            throw new IpaasError('session exchange', res.status, body);
+        const parsed = JSON.parse(body);
+        if (!parsed.token || !parsed.projectId) {
+            throw new IpaasError('session exchange', res.status, 'the response carried no token or projectId');
+        }
+        const session = { pipeId, projectId: parsed.projectId, userId: parsed.id };
+        this.sessions.set(pipeId, { session, token: parsed.token, at: Date.now() });
+        debug(`ipaas session for pipe ${pipeId}: project ${parsed.projectId}`);
+        return session;
+    }
+    async token(pipeId) {
+        await this.session(pipeId);
+        return this.sessions.get(pipeId).token;
+    }
+    async request(pipeId, method, path, body) {
+        const token = await this.token(pipeId);
+        const res = await fetch(`${this.base}/${path.replace(/^\//, '')}`, {
+            method,
+            // Content-Type only with a body: a bodyless DELETE carrying it is rejected
+            // outright with FST_ERR_CTP_EMPTY_JSON_BODY, so deleting a flow used to fail
+            // on a header rather than on anything to do with the flow.
+            headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await res.text();
+        if (res.status === 401) {
+            // The session aged out mid-run; mint once more before giving up.
+            this.sessions.delete(pipeId);
+            const retryToken = await this.token(pipeId);
+            const again = await fetch(`${this.base}/${path.replace(/^\//, '')}`, {
+                method,
+                headers: { Authorization: `Bearer ${retryToken}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+            const againText = await again.text();
+            if (!again.ok)
+                throw new IpaasError(`${method} ${path}`, again.status, againText);
+            return (againText ? JSON.parse(againText) : null);
+        }
+        if (!res.ok)
+            throw new IpaasError(`${method} ${path}`, res.status, text);
+        return (text ? JSON.parse(text) : null);
+    }
+    // ── reads ─────────────────────────────────────────────────────────────────
+    async listFlows(pipeId) {
+        const { projectId } = await this.session(pipeId);
+        const out = await this.request(pipeId, 'GET', `flows?projectId=${projectId}`);
+        return out?.data ?? [];
+    }
+    async getFlow(pipeId, flowId) {
+        return this.request(pipeId, 'GET', `flows/${flowId}`);
+    }
+    async listConnections(pipeId) {
+        const { projectId } = await this.session(pipeId);
+        const out = await this.request(pipeId, 'GET', `app-connections?projectId=${projectId}`);
+        // Only the four columns a reference needs. A credential is never one of them.
+        return (out?.data ?? []).map((c) => ({
+            externalId: String(c['externalId'] ?? ''),
+            pieceName: String(c['pieceName'] ?? ''),
+            displayName: String(c['displayName'] ?? ''),
+            status: String(c['status'] ?? ''),
+        }));
+    }
+    async listRuns(pipeId) {
+        const { projectId } = await this.session(pipeId);
+        const out = await this.request(pipeId, 'GET', `flow-runs?projectId=${projectId}`);
+        return (out?.data ?? []).map((r) => ({
+            id: String(r['id'] ?? ''),
+            flowId: String(r['flowId'] ?? ''),
+            status: String(r['status'] ?? ''),
+            startTime: String(r['startTime'] ?? ''),
+        }));
+    }
+    /** pieceName → the version this instance offers. Instance-wide, not per project. */
+    async listPieces(pipeId) {
+        const raw = await this.request(pipeId, 'GET', 'pieces');
+        return Object.fromEntries((raw ?? []).filter((p) => p.name && p.version).map((p) => [p.name, p.version]));
+    }
+    /** One piece's action and trigger names, for checking a node against the catalogue. */
+    async pieceMembers(pipeId, pieceName) {
+        const meta = await this.request(pipeId, 'GET', `pieces/${encodeURIComponent(pieceName)}`);
+        return { actions: Object.keys(meta?.actions ?? {}), triggers: Object.keys(meta?.triggers ?? {}) };
+    }
+    // ── writes ────────────────────────────────────────────────────────────────
+    /**
+     * Create a connection with a placeholder credential.
+     *
+     * A pipe whose iPaaS workspace has no connections cannot host a flow, and the
+     * credential is not obtainable here: `piece-pipefy` authenticates by
+     * `client_credentials` against Pipefy's own OAuth token endpoint, and this
+     * host has no OAuth client registered for it — only for Slack. Connections are
+     * also hard-isolated per project: the update endpoint accepts `scope` and
+     * `projectIds` and returns 200 while ignoring both, and a different project's
+     * session gets 403 on the connection itself.
+     *
+     * So a placeholder is created instead, which is how Pipefy's own import path
+     * behaves — import, then remap the connection in the UI. The flow structure is
+     * what is being built and it does not depend on the credential working.
+     *
+     * **The host does not validate the value.** It answers 201 and marks the
+     * connection ACTIVE whatever is sent, so `status: ACTIVE` is not evidence that
+     * a connection works. Everything this tool creates is tagged `_placeholder` so
+     * a flow that depends on one can be reported as unreconnected, and a flow with
+     * a placeholder connection is never enabled.
+     */
+    async createPlaceholderConnection(pipeId, spec) {
+        const { projectId } = await this.session(pipeId);
+        const externalId = spec.externalId ?? `pipe-placeholder-${spec.pieceName.split('/').pop()}`;
+        const type = 'CUSTOM_AUTH';
+        const out = await this.request(pipeId, 'POST', 'app-connections', {
+            externalId,
+            displayName: spec.displayName,
+            pieceName: spec.pieceName,
+            projectId,
+            // The discriminator goes in both positions; the host wants it twice.
+            type,
+            value: {
+                type,
+                props: {
+                    // Named so anyone reading the connection in the product knows what it is.
+                    placeholder: 'created by pipe — reconnect this before enabling any flow',
+                },
+            },
+        });
+        return {
+            externalId: String(out?.['externalId'] ?? externalId),
+            pieceName: spec.pieceName,
+            displayName: spec.displayName,
+            status: String(out?.['status'] ?? 'UNKNOWN'),
+            _placeholder: true,
+        };
+    }
+    async deleteConnection(pipeId, connectionId) {
+        await this.request(pipeId, 'DELETE', `app-connections/${connectionId}`);
+    }
+    async createFlow(pipeId, displayName) {
+        const { projectId } = await this.session(pipeId);
+        const out = await this.request(pipeId, 'POST', 'flows', { projectId, displayName });
+        if (!out?.id)
+            throw new IpaasError('POST flows', 200, 'the response carried no flow id');
+        return out.id;
+    }
+    async deleteFlow(pipeId, flowId) {
+        await this.request(pipeId, 'DELETE', `flows/${flowId}`);
+    }
+    /**
+     * One flow operation.
+     *
+     * `IMPORT_FLOW` is refused here on purpose. It replaces the whole tree *and*
+     * runs the schema migration an old export needs, so a flow already in live form
+     * has every datapill rewritten — `{{step_1['output'].x}}` becomes
+     * `{{step_1['output']['output'].x}}` — and then resolves nothing at runtime,
+     * while every validator still calls it valid. The granular operations do not
+     * migrate. If an actual export ever needs importing, that is a separate path
+     * with its own conversion.
+     */
+    async operate(pipeId, flowId, type, request) {
+        if (type === 'IMPORT_FLOW') {
+            throw new Error('IMPORT_FLOW is not used by this tool: it migrates the tree it is given, which silently ' +
+                'doubles every datapill of a flow already in live form. Use the granular operations.');
+        }
+        if (ACTS_ON_EMPTY_REQUEST.has(type) && Object.keys(request).length === 0) {
+            throw new Error(`${type} acts on an empty request rather than rejecting it — sending one would take a ` +
+                'default nobody asked for. Supply the request explicitly.');
+        }
+        return this.request(pipeId, 'POST', `flows/${flowId}`, { type, request });
+    }
+}