@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

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 });
+    }
+}