@pipefy/pipefy-process-coder 0.1.0

package/src/pipefy/ipaas.ts

@@ -0,0 +1,365 @@
+import { debug } from '../util/log.ts';
+import type { InternalApi } from './internal.ts';
+import type { Row } from '../model/payload.ts';
+
+/**
+ * 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';
+
+export type FlowRow = Row & { id: string; status: string; version: Row };
+export type ConnectionRow = {
+  externalId: string;
+  pieceName: string;
+  displayName: string;
+  status: string;
+  /** Set by this tool when it created the connection with a placeholder credential. */
+  _placeholder?: boolean;
+  /** Authored, not yet created. */
+  _new?: boolean;
+};
+export type RunRow = { id: string; flowId: string; status: string; startTime: string };
+
+/**
+ * The flow operations this endpoint accepts, probed against it. `UPDATE_BRANCH`
+ * is deliberately absent: it is not in the enum, and a router's branches are
+ * edited by sending the router through `UPDATE_ACTION`, since `settings.branches`
+ * is part of its settings.
+ */
+export type FlowOperation =
+  | 'IMPORT_FLOW'
+  | 'UPDATE_TRIGGER'
+  | 'ADD_ACTION'
+  | 'UPDATE_ACTION'
+  | 'DELETE_ACTION'
+  | 'MOVE_ACTION'
+  | 'DUPLICATE_ACTION'
+  | 'CHANGE_NAME'
+  | 'CHANGE_STATUS'
+  | 'LOCK_AND_PUBLISH'
+  | 'LOCK_FLOW'
+  | 'USE_AS_DRAFT'
+  | 'CHANGE_FOLDER'
+  | 'UPDATE_METADATA'
+  | 'SAVE_SAMPLE_DATA'
+  | 'SET_SKIP_ACTION'
+  | 'ADD_BRANCH'
+  | 'DELETE_BRANCH'
+  | 'DUPLICATE_BRANCH';
+
+/**
+ * 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<FlowOperation>([
+  'CHANGE_STATUS',
+  'LOCK_AND_PUBLISH',
+  'LOCK_FLOW',
+  'CHANGE_FOLDER',
+  'UPDATE_METADATA',
+]);
+
+export class IpaasError extends Error {
+  readonly status: number;
+  readonly step: string;
+  constructor(step: string, status: number, body: string) {
+    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 {
+  readonly pipeId: number;
+  constructor(pipeId: number, reason: string) {
+    super(reason);
+    this.name = 'IpaasUnavailable';
+    this.pipeId = pipeId;
+  }
+}
+
+export type IpaasSession = {
+  pipeId: number;
+  projectId: string;
+  /** The pipe's iPaaS user id, kept for the record rather than used. */
+  userId: string;
+};
+
+export class IpaasClient {
+  private internal: InternalApi;
+  private base: string;
+  /** pipeId → session, because minting is two round trips and a pull does many reads. */
+  private sessions = new Map<number, { session: IpaasSession; token: string; at: number }>();
+  /** A session lives a while, but not forever; re-mint rather than discover expiry mid-apply. */
+  private static readonly TTL_MS = 10 * 60 * 1000;
+
+  constructor(internal: InternalApi, 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: number): Promise<{ ok: true; session: IpaasSession } | { ok: false; reason: string }> {
+    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: number): Promise<IpaasSession> {
+    const hit = this.sessions.get(pipeId);
+    if (hit && Date.now() - hit.at < IpaasClient.TTL_MS) return hit.session;
+
+    const minted = await this.internal.gql<{ advancedAutomationsToken: { token: string } | null }>(
+      `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) as { token: string; projectId: string; id: string };
+    if (!parsed.token || !parsed.projectId) {
+      throw new IpaasError('session exchange', res.status, 'the response carried no token or projectId');
+    }
+    const session: IpaasSession = { 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;
+  }
+
+  private async token(pipeId: number): Promise<string> {
+    await this.session(pipeId);
+    return this.sessions.get(pipeId)!.token;
+  }
+
+  private async request<T>(pipeId: number, method: string, path: string, body?: unknown): Promise<T> {
+    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) as T;
+    }
+    if (!res.ok) throw new IpaasError(`${method} ${path}`, res.status, text);
+    return (text ? JSON.parse(text) : null) as T;
+  }
+
+  // ── reads ─────────────────────────────────────────────────────────────────
+
+  async listFlows(pipeId: number): Promise<FlowRow[]> {
+    const { projectId } = await this.session(pipeId);
+    const out = await this.request<{ data: FlowRow[] }>(pipeId, 'GET', `flows?projectId=${projectId}`);
+    return out?.data ?? [];
+  }
+
+  async getFlow(pipeId: number, flowId: string): Promise<FlowRow> {
+    return this.request<FlowRow>(pipeId, 'GET', `flows/${flowId}`);
+  }
+
+  async listConnections(pipeId: number): Promise<ConnectionRow[]> {
+    const { projectId } = await this.session(pipeId);
+    const out = await this.request<{ data: Array<Record<string, unknown>> }>(
+      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: number): Promise<RunRow[]> {
+    const { projectId } = await this.session(pipeId);
+    const out = await this.request<{ data: Array<Record<string, unknown>> }>(
+      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: number): Promise<Record<string, string>> {
+    const raw = await this.request<Array<{ name: string; version: string }>>(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: number, pieceName: string): Promise<{ actions: string[]; triggers: string[] }> {
+    const meta = await this.request<{ actions?: Record<string, unknown>; triggers?: Record<string, unknown> }>(
+      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: number,
+    spec: { pieceName: string; displayName: string; externalId?: string },
+  ): Promise<ConnectionRow> {
+    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<Record<string, unknown>>(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: number, connectionId: string): Promise<void> {
+    await this.request<null>(pipeId, 'DELETE', `app-connections/${connectionId}`);
+  }
+
+  async createFlow(pipeId: number, displayName: string): Promise<string> {
+    const { projectId } = await this.session(pipeId);
+    const out = await this.request<{ id: string }>(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: number, flowId: string): Promise<void> {
+    await this.request<null>(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: number, flowId: string, type: FlowOperation, request: Record<string, unknown>): Promise<FlowRow> {
+    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<FlowRow>(pipeId, 'POST', `flows/${flowId}`, { type, request });
+  }
+}