@pipefy/pipefy-process-coder 0.1.0

package/src/pipefy/automations.ts

@@ -0,0 +1,219 @@
+import { debug } from '../util/log.ts';
+import type { PipefyClient } from './client.ts';
+
+/**
+ * The automation event and action catalogue, read from the **public** API.
+ *
+ * Pipefy publishes exactly what each event and each action accepts —
+ * `automationEvents.acceptedParameters`, `automationActions.acceptedParameters` —
+ * and which combinations are refused. Without reading it, a wrong parameter name
+ * is only discovered by sending the mutation, and the answer is the single word
+ * `is invalid`, from both the public and the internal endpoint. Nothing names the
+ * parameter, the event, or the action.
+ *
+ * The case that motivated this: an automation meaning "when a card lands in
+ * New Request, move it to Archived" was written as
+ *
+ *     event_id: 'card_moved', event_params: { inPhaseId: '<phaseId>' }
+ *
+ * `inPhaseId` is real — it belongs to `card_inbox_received_email`. `card_moved`
+ * accepts only `to_phase_id`. Both endpoints answered `is invalid` and the apply
+ * failed at step one with nothing to act on.
+ */
+
+export type AutomationEventSpec = {
+  id: string;
+  /** Parameter names this event accepts, in the API's own snake_case. */
+  acceptedParameters: string[];
+  /** Actions this event cannot be paired with. */
+  actionsBlacklist: string[];
+};
+
+export type AutomationActionSpec = {
+  id: string;
+  acceptedParameters: string[];
+  eventsBlacklist: string[];
+};
+
+export type AutomationCatalogue = {
+  events: Map<string, AutomationEventSpec>;
+  actions: Map<string, AutomationActionSpec>;
+};
+
+const EVENTS_QUERY = `query AutomationEvents {
+  automationEvents { id acceptedParameters actionsBlacklist }
+}`;
+
+const ACTIONS_QUERY = `query AutomationActions($repoId: ID!) {
+  automationActions(repoId: $repoId) { id acceptedParameters eventsBlacklist }
+}`;
+
+/**
+ * Read the catalogue for one pipe. Actions are per-repo (a pipe without AI
+ * enabled offers fewer), events are global.
+ */
+export const readAutomationCatalogue = async (
+  client: PipefyClient,
+  repoId: number | string,
+): Promise<AutomationCatalogue> => {
+  const [ev, ac] = await Promise.all([
+    client.raw<{ automationEvents: AutomationEventSpec[] }>(EVENTS_QUERY),
+    client.raw<{ automationActions: AutomationActionSpec[] }>(ACTIONS_QUERY, { repoId: String(repoId) }),
+  ]);
+
+  const events = new Map<string, AutomationEventSpec>();
+  for (const e of ev?.automationEvents ?? []) {
+    events.set(e.id, {
+      id: e.id,
+      acceptedParameters: e.acceptedParameters ?? [],
+      actionsBlacklist: e.actionsBlacklist ?? [],
+    });
+  }
+  const actions = new Map<string, AutomationActionSpec>();
+  for (const a of ac?.automationActions ?? []) {
+    actions.set(a.id, {
+      id: a.id,
+      acceptedParameters: a.acceptedParameters ?? [],
+      eventsBlacklist: a.eventsBlacklist ?? [],
+    });
+  }
+  debug(`automation catalogue: ${events.size} events, ${actions.size} actions for repo ${repoId}`);
+  return { events, actions };
+};
+
+/**
+ * Parameter names the payload spells differently from the API.
+ *
+ * The stored row and the mutation input disagree in both directions, so a check
+ * against `acceptedParameters` has to normalise first or it reports correct
+ * automations as broken.
+ */
+const PARAM_ALIASES: Record<string, string> = {
+  // event params
+  inPhaseId: 'in_phase_id',
+  fromPhaseId: 'from_phase_id',
+  toPhaseId: 'to_phase_id',
+  triggerFieldIds: 'trigger_field_ids',
+  triggerAutomationId: 'trigger_automation_id',
+  kindOfSla: 'kind_of_sla',
+  // action params
+  fieldsMapOrder: 'fields_map_order',
+  cardId: 'card_id',
+  toPhaseIdAction: 'to_phase_id',
+  taskParams: 'task_params',
+  aiParams: 'ai_params',
+  aiBehaviorParams: 'ai_behavior_params',
+  slaParams: 'sla_params',
+  httpMethod: 'http_method',
+  emailTemplateId: 'email_template_id',
+  authenticationKey: 'authentication_key',
+  authenticationValue: 'authentication_value',
+  authenticationAddTo: 'authentication_add_to',
+  authenticationType: 'authentication_type',
+  oauth2Uuid: 'oauth2_uuid',
+};
+
+const canonical = (name: string) => PARAM_ALIASES[name] ?? name;
+
+/**
+ * Params the API accepts on every action regardless of the catalogue.
+ *
+ * `field_map` carries the values an `update_card_field` or `create_card` writes
+ * and is not listed in `acceptedParameters` — the catalogue lists
+ * `fields_map_order` beside it and stops. Flagging `field_map` would refuse every
+ * automation that writes a field, which is most of them.
+ */
+const ALWAYS_ALLOWED_ACTION_PARAMS = new Set(['field_map', 'schema']);
+
+export type ParamFinding = {
+  severity: 'error' | 'warning';
+  where: 'event' | 'action' | 'pairing';
+  message: string;
+  fix?: string;
+};
+
+/**
+ * Check one automation against the catalogue, before anything is sent.
+ *
+ * Returns findings rather than throwing, so the compiler can refuse the step and
+ * name the parameter — which is the whole point. An unknown event or action is an
+ * error; a catalogue this pipe does not offer is silence, not a guess.
+ */
+export const checkAutomationParams = (
+  auto: Record<string, unknown>,
+  catalogue: AutomationCatalogue,
+): ParamFinding[] => {
+  const findings: ParamFinding[] = [];
+  const eventId = String(auto['event_id'] ?? '');
+  const actionId = String(auto['action_id'] ?? '');
+
+  const event = catalogue.events.get(eventId);
+  const action = catalogue.actions.get(actionId);
+
+  if (eventId && !event) {
+    findings.push({
+      severity: 'error',
+      where: 'event',
+      message: `event_id ${JSON.stringify(eventId)} is not an event this endpoint offers`,
+      fix: `available: ${[...catalogue.events.keys()].join(', ')}`,
+    });
+  }
+  if (actionId && !action) {
+    findings.push({
+      severity: 'error',
+      where: 'action',
+      message: `action_id ${JSON.stringify(actionId)} is not an action this pipe offers`,
+      fix: `available: ${[...catalogue.actions.keys()].join(', ')}`,
+    });
+  }
+
+  if (event && action) {
+    if (event.actionsBlacklist.includes(actionId)) {
+      findings.push({
+        severity: 'error',
+        where: 'pairing',
+        message: `event ${eventId} cannot be paired with action ${actionId}`,
+      });
+    } else if (action.eventsBlacklist.includes(eventId)) {
+      findings.push({
+        severity: 'error',
+        where: 'pairing',
+        message: `action ${actionId} cannot be triggered by event ${eventId}`,
+      });
+    }
+  }
+
+  if (event) {
+    const accepted = new Set(event.acceptedParameters.map(canonical));
+    for (const key of Object.keys((auto['event_params'] ?? {}) as Record<string, unknown>)) {
+      const name = canonical(key);
+      if (accepted.has(name)) continue;
+      findings.push({
+        severity: 'error',
+        where: 'event',
+        message: `event ${eventId} does not accept event_params.${key}`,
+        fix: accepted.size
+          ? `it accepts: ${[...accepted].join(', ')}`
+          : `it accepts no parameters — remove event_params.${key}`,
+      });
+    }
+  }
+
+  if (action) {
+    const accepted = new Set(action.acceptedParameters.map(canonical));
+    for (const key of Object.keys((auto['action_params'] ?? {}) as Record<string, unknown>)) {
+      const name = canonical(key);
+      if (accepted.has(name) || ALWAYS_ALLOWED_ACTION_PARAMS.has(name)) continue;
+      findings.push({
+        severity: 'error',
+        where: 'action',
+        message: `action ${actionId} does not accept action_params.${key}`,
+        fix: accepted.size
+          ? `it accepts: ${[...accepted].join(', ')}`
+          : `it accepts no parameters — remove action_params.${key}`,
+      });
+    }
+  }
+
+  return findings;
+};

package/src/pipefy/capability.ts

@@ -0,0 +1,119 @@
+import { debug } from '../util/log.ts';
+import type { PipefyClient } from './client.ts';
+import type { InternalApi } from './internal.ts';
+
+/**
+ * Capability detection. PLAN.md §1.2: `restoreRepoSnapshot` and
+ * `createRepoDraft` carry the entire safety model but do not exist on every
+ * endpoint, so the app detects them at startup and degrades explicitly rather
+ * than failing mid-apply.
+ */
+
+export type Capabilities = {
+  /** Read paths. */
+  snapshots: boolean;
+  /** Safety primitives. */
+  restoreRepoSnapshot: boolean;
+  /** Which spelling this endpoint has, so the caller does not guess. */
+  restoreMutation: 'restoreRepoToSnapshot' | 'restoreRepoSnapshot' | null;
+  /** Whether a restore is limited to the newest snapshot. Measured, not assumed. */
+  restoreLatestOnly: boolean;
+  createRepoDraft: boolean;
+  /** Route B, tracked so `pipe doctor` reports the day it lands. */
+  importRepoSnapshot: boolean;
+  /** Public write paths this build depends on. */
+  mutations: Record<string, boolean>;
+  /** The internal endpoint — phase jumps and automation details. */
+  internalApi: 'ok' | 'unavailable' | 'unknown';
+  checkedAt: string;
+};
+
+/** Mutations the plan compiler emits, checked as a set so gaps are visible up front. */
+export const REQUIRED_MUTATIONS = [
+  'updatePipe',
+  'createPhase',
+  'updatePhase',
+  'deletePhase',
+  'createPhaseField',
+  'updatePhaseField',
+  'deletePhaseField',
+  'createLabel',
+  'updateLabel',
+  'deleteLabel',
+  'createWebhook',
+  'updateWebhook',
+  'deleteWebhook',
+  'createFieldCondition',
+  'updateFieldCondition',
+  'deleteFieldCondition',
+  'setFieldConditionOrder',
+  'createAutomation',
+  'updateAutomation',
+  'deleteAutomation',
+  'createPipeRelation',
+  'updatePipeRelation',
+  'deletePipeRelation',
+  'phaseSettings',
+  'updateRepoPreferences',
+  'archiveField',
+  'unarchiveField',
+  'moveCardToPhase',
+] as const;
+
+export const detect = async (client: PipefyClient, internal?: InternalApi): Promise<Capabilities> => {
+  const mutationFields = await client.typeFields('Mutation');
+  const pipeFields = await client.typeFields('Pipe');
+  const has = (n: string) => Boolean(mutationFields?.has(n));
+
+  const mutations: Record<string, boolean> = {};
+  for (const m of REQUIRED_MUTATIONS) mutations[m] = has(m);
+
+  const caps: Capabilities = {
+    snapshots: has('createRepoSnapshot') && Boolean(pipeFields?.has('snapshots') || pipeFields?.has('snapshot')),
+    /**
+     * Both spellings, because this build was looking for the wrong one.
+     *
+     * `restoreRepoSnapshot` does not exist on this endpoint and never did.
+     * **`restoreRepoToSnapshot`** does — "Restores a Pipe structure to its latest
+     * uploaded snapshot" — so every apply has printed "no one-command rollback"
+     * beside a snapshot that could in fact be restored, and `pipe rollback` has
+     * refused to try. That is the same failure as automations sitting on the
+     * internal endpoint: a name assumed once and never re-checked.
+     *
+     * The capability is still narrower than it sounds, and `restoreLatestOnly`
+     * below is what says so.
+     */
+    restoreRepoSnapshot: has('restoreRepoSnapshot') || has('restoreRepoToSnapshot'),
+    restoreMutation: has('restoreRepoToSnapshot')
+      ? 'restoreRepoToSnapshot'
+      : has('restoreRepoSnapshot')
+        ? 'restoreRepoSnapshot'
+        : null,
+    /**
+     * A restore only accepts the **latest** uploaded snapshot. Measured: an
+     * older versionId is refused with "Version_id must reference the latest
+     * uploaded snapshot of the Pipe".
+     *
+     * That is the whole story for rollback on this endpoint, and it is why the
+     * pre-apply snapshot is usually not restorable: `pipe apply` reads the repo
+     * back to verify, and that read takes a snapshot of its own, which becomes
+     * the latest. Recovery stays forward-first.
+     */
+    restoreLatestOnly: has('restoreRepoToSnapshot'),
+    createRepoDraft: has('createRepoDraft'),
+    importRepoSnapshot: has('importRepoSnapshot') || has('createRepoSnapshotFromPayload'),
+    mutations,
+    internalApi: internal?.status ?? 'unknown',
+    checkedAt: new Date().toISOString(),
+  };
+  debug(
+    `capabilities: snapshots=${caps.snapshots} restore=${caps.restoreRepoSnapshot} ` +
+      `draft=${caps.createRepoDraft} import=${caps.importRepoSnapshot}`,
+  );
+  return caps;
+};
+
+export const missingMutations = (c: Capabilities): string[] =>
+  Object.entries(c.mutations)
+    .filter(([, present]) => !present)
+    .map(([name]) => name);

package/src/pipefy/client.ts

@@ -0,0 +1,267 @@
+import { ENDPOINTS, type TokenProvider } from '../config.ts';
+import { debug } from '../util/log.ts';
+import { retry } from '../util/pool.ts';
+
+export type GqlError = { message: string; path?: unknown[]; extensions?: Record<string, unknown> };
+
+export class GraphQLRequestError extends Error {
+  errors: GqlError[];
+  retryable: boolean;
+  status: number;
+  constructor(message: string, errors: GqlError[], status: number, retryable: boolean) {
+    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: string) =>
+  /rate limit|too many requests|timeout|timed out|temporarily|try again|internal server error/i.test(m);
+
+export type ClientOpts = {
+  /**
+   * A literal token, or a provider. The toolkit hands out short-lived OAuth
+   * access tokens, so a long apply needs to be able to ask for a fresh one —
+   * see src/config.ts.
+   */
+  token: string | TokenProvider;
+  endpoint?: string;
+  label?: string;
+};
+
+export class PipefyClient {
+  private readonly tokenProvider: TokenProvider;
+  readonly endpoint: string;
+  /** 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;
+
+  private typeFieldCache = new Map<string, Set<string> | null>();
+  private inputFieldCache = new Map<string, Set<string> | null>();
+  private requiredInputCache = new Map<string, Set<string>>();
+  private mutationInputTypeCache = new Map<string, string | null>();
+
+  constructor(opts: ClientOpts) {
+    this.tokenProvider = typeof opts.token === 'string' ? async () => opts.token as string : opts.token;
+    this.endpoint = opts.endpoint ?? ENDPOINTS.graphql;
+  }
+
+  /** The current bearer, refreshed only when something rejected the last one. */
+  async token(forceRefresh = false): Promise<string> {
+    if (forceRefresh) this.reauthCount++;
+    return this.tokenProvider({ forceRefresh });
+  }
+
+  async raw<T>(query: string, variables?: Record<string, unknown>, label?: string): Promise<T> {
+    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 as { retryable?: boolean }).retryable = true;
+          throw err;
+        }
+
+        const text = await res.text();
+        let body: { data?: T; errors?: GqlError[] } = {};
+        try {
+          body = text ? (JSON.parse(text) as typeof body) : {};
+        } 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<T>(query: string, variables?: Record<string, unknown>, label?: string): Promise<T | null> {
+    try {
+      return await this.raw<T>(query, variables, label);
+    } catch (e) {
+      debug(`probe failed (${label ?? 'unnamed'}): ${(e as Error).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: string): Promise<Set<string> | null> {
+    if (this.typeFieldCache.has(typeName)) return this.typeFieldCache.get(typeName) ?? null;
+    const data = await this.tryRaw<{ __type: { fields: Array<{ name: string }> | null } | null }>(
+      '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: string): Promise<boolean> {
+    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: string): Promise<string | null> {
+    if (this.mutationInputTypeCache.has(mutation)) return this.mutationInputTypeCache.get(mutation) ?? null;
+    const data = await this.tryRaw<{
+      __type: {
+        fields: Array<{
+          name: string;
+          args: Array<{ name: string; type: TypeRef }>;
+        }> | null;
+      } | null;
+    }>(
+      `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: string): Promise<Set<string>> {
+    const cached = this.requiredInputCache.get(typeName);
+    if (cached) return cached;
+    const data = await this.tryRaw<{
+      __type: { inputFields: Array<{ name: string; defaultValue: string | null; type: { kind: string } }> | null } | null;
+    }>(
+      'query($n:String!){ __type(name:$n){ inputFields { name defaultValue type { kind } } } }',
+      { n: typeName },
+      `introspect required ${typeName}`,
+    );
+    const req = new Set<string>();
+    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: string): Promise<Set<string> | null> {
+    if (this.inputFieldCache.has(typeName)) return this.inputFieldCache.get(typeName) ?? null;
+    const data = await this.tryRaw<{ __type: { inputFields: Array<{ name: string }> | null } | null }>(
+      '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: string, selection: Array<string | [string, string]>): Promise<string> {
+    const have = await this.typeFields(typeName);
+    const keep: string[] = [];
+    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      ');
+  }
+}
+
+type TypeRef = { kind: string; name: string | null; ofType?: TypeRef | null };
+
+/** Unwrap NON_NULL / LIST wrappers down to the named type. */
+const unwrapTypeName = (t: TypeRef | null | undefined): string | null => {
+  let cur: TypeRef | null | undefined = t;
+  while (cur && !cur.name) cur = cur.ofType ?? null;
+  return cur?.name ?? null;
+};