@pipefy/pipefy-process-coder 0.1.0

package/.agents/skills/ppc-pipefy-flow-authoring/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: ppc-pipefy-flow-authoring
+description: Use when reading, authoring or debugging a Pipefy iPaaS flow (Advanced Automations, Activepieces underneath) in a pipefy-process-coder workspace — the flow JSON, node types, linked-list chaining, datapill syntax, connections, the operation set pipe compiles to, and the traps that make a flow validate clean and resolve nothing at runtime.
+---
+
+# Authoring iPaaS flows
+
+Pipefy's iPaaS — "Advanced Automations", "PIP" — is **Activepieces** underneath. A
+flow is where a process does what the automation engine cannot: call external
+systems, and read pipes other than the one that triggered.
+
+## Flows are in the loop
+
+The same five commands cover flows and pipe structure together:
+
+```bash
+pipe pull <pipeId> --out ./my-pipe   # reads the pipe AND its iPaaS flows
+# edit pipes/<id>--<name>/flows/<flowId>--<slug>/nodes/NN--step_N.json
+pipe diff                        # reports flow changes beside pipe changes
+pipe plan --dry-run              # compiles them to iPaaS operations
+pipe apply                       # sends them, then verifies every datapill
+```
+
+No flag is needed — `pipe pull` reads flows because a flow is an entity of the
+pipe. `--no-flows` opts out of the flow half on any of those commands.
+
+```
+pipes/<pipeId>--<slug>/
+  flows/
+    _meta.json                  coverage, projectId, counts, read time
+    connections.json            externalId, pieceName, displayName, status
+    pieces.json                 pieceName -> version the instance offers
+    _readonly/flow-runs.json    recent outcomes; never written back
+    <flowId>--<slug>/
+      flow.json                 the flow row
+      version.json              the version row, without the trigger
+      nodes/NN--<name>.json     one node per file, in execution order
+```
+
+Flows live **under the pipe**, not at the workspace root: a workspace can hold
+several pipes and each has its own iPaaS workspace.
+
+Two safety rules the compiler enforces:
+
+- **Enabling a flow is refused** unless `--allow-flow-enable` is passed. It arms
+  the flow against live traffic, which is never incidental.
+- **After a flow write, every datapill is compared against what was sent.** A
+  mismatch is reported and the apply says not to enable the flow.
+
+Still under `research/ipaas/` and useful for inspection:
+`ipaas-piece.ts` (one piece's metadata from the live catalogue),
+`validate-flow.ts` + `check.ts` (the offline validator, ahead of `pipe validate`),
+`check-negative.ts` (17 cases proving it catches things),
+`probe-operations.ts` and `probe-op-shapes.ts` (how the operation model was learned).
+
+`PLAN-IPAAS.md` is the plan; `workspaces/fde-request/flows/BUILD-LOG.md` is a
+worked run with the findings.
+
+## Reaching a pipe's iPaaS workspace
+
+Two calls from the credential `pipe` already has — no separate token:
+
+```
+1. Pipefy INTERNAL API:  query { advancedAutomationsToken(repoId: "<pipeId>") { token } }
+2. POST https://ipaas.pipefy.com/api/v1/managed-authn/external-token
+     { "externalAccessToken": <that token> }
+   → a session token AND the projectId
+```
+
+The session token alone reads `pieces`, `flows`, `app-connections` and
+`flow-runs`. The OAuth+PKCE steps in the toolkit's gateway are only for the iPaaS
+MCP tool surface.
+
+**Every pipe has its own iPaaS workspace.** The session's identity *is* the pipe —
+`firstName` is the pipe's name, `lastName` its id. Flows and connections are scoped
+to it. A flow may orchestrate across many pipes but lives in exactly one.
+
+**Connections are workspace-scoped too**, and this decides where a flow can live:
+a pipe with 0 connections cannot host a flow that needs auth. Check
+`GET /app-connections?projectId=` before authoring.
+
+**The webhook URL suffix on a pipe is the flow id.** A pipe webhook pointing at
+`https://ipaas.pipefy.com/api/v1/webhooks/<id>` is pointing at the flow whose id
+is `<id>`. That is how a pipe's webhooks and its flows correlate — and it means a
+workspace has held a pointer to every flow since its first pull.
+
+## The flow shape
+
+```
+flow row : id, projectId, externalId, status, publishedVersionId, triggerSource
+version  : id, displayName, valid, schemaVersion, state, connectionIds, trigger
+```
+
+`state: "LOCKED"` means published and immutable; editing produces a new version.
+`status` is `ENABLED`/`DISABLED`. A newly created flow lands **DISABLED / DRAFT**
+with `publishedVersionId: null` — creating one does not arm it.
+
+`connectionIds` is **derived by the API** from the inline `{{connections[…]}}`
+references. Do not send it.
+
+### Nodes are a linked list, not an array
+
+```
+trigger ─nextAction→ step_1 ─nextAction→ step_5 (ROUTER)
+                                          ├─ children[0] → step_6
+                                          ├─ children[1] → step_7
+                                          └─ nextAction  → step_8   ← reconverges
+```
+
+| field | meaning |
+| --- | --- |
+| `nextAction` | the next step in sequence. Absent = end of chain. |
+| `firstLoopAction` | the first step *inside* a `LOOP_ON_ITEMS` |
+| `children[]` | first step of each router branch, **index-aligned with `settings.branches[]`**; `null` for an empty branch |
+
+Node types: `PIECE_TRIGGER` or `EMPTY` for the trigger; `PIECE`, `CODE`,
+`LOOP_ON_ITEMS`, `ROUTER` for actions. The trigger is always named `trigger`;
+steps are `step_N` and each name must be unique. Execution order comes only from
+the chaining, never from the number.
+
+### Datapills
+
+```
+{{trigger['output'].data.card.id}}
+{{step_1['output'].data.card.fields.<slug>.value}}
+{{step_4['output'].user.id}}
+{{connections['<connectionId>']}}
+```
+
+**Single `['output']`.** Card fields by **slug**. Only reference steps that run
+*earlier* — referencing a later step, or a sibling router branch, fails at runtime.
+
+Older exports use `{{step_1['data']['card']['fields']['<Phase>']['<Label>']['report_value']}}`.
+The engine migrates that on import, so both exist in the wild. **Author the live
+form.** Which brings us to:
+
+### A connector field's value is the connected cards' ids — nothing else
+
+`fields.<slug>.value` for a **`connector`** field (a card-relationship field — "this
+card's Pareceres", a pipe relation's connected items) is the connected records'
+**id(s) only**. It does not carry those cards' own field values, however the
+payload is shaped or how deep you index into it. Assuming otherwise is the trap
+this skill exists to name: it does not error, it just produces empty or
+`undefined` output for every field you tried to read off the connected card.
+
+To use a connected card's *own* fields — e.g. reading a child card's Área,
+Avaliador, Nível de Impacto and Justificativa through a parent's connector field
+— add an explicit step per id that fetches that card, and reference **that
+step's** output, never the parent's connector-field datapill:
+
+```
+{{trigger['output'].data.card.fields.pareceres.value}}   -> ["1234", "5678"]   ids only
+
+step_2  getCardById(id: {{trigger['output'].data.card.fields.pareceres.value[0]}})
+{{step_2['output'].fields.area.value}}                                        the child's own field
+```
+
+`getCardById` (piece-pipefy) is the tool for this. A parent card with N connected
+children needs N such calls — typically inside a `LOOP_ON_ITEMS` over the id
+array — before anything about the children's own fields can be formatted.
+
+## The trap: IMPORT_FLOW rewrites your datapills
+
+`POST /flows/{id}` with `{type: "IMPORT_FLOW", request: {displayName, trigger}}`
+replaces the whole tree **and runs the schema migration an old export needs**. Give
+it a flow already in live form and it migrates twice:
+
+```
+sent   {{trigger['output'].data.card.id}}
+stored {{trigger['output']['output'].data.card.id}}
+```
+
+The flow then resolves nothing at runtime. Both the offline validator and Pipefy's
+own `ap_validate_flow` call it valid — both forms are structurally fine — and
+`ap_flow_structure` shows every step `configured`. Only comparing stored bytes
+against sent bytes finds it.
+
+**So `pipe` never sends IMPORT_FLOW** — `IpaasClient.operate` refuses it — and
+compiles to the granular operations instead. The operation set, probed against
+the endpoint:
+
+| operation | request |
+| --- | --- |
+| `UPDATE_TRIGGER` | the whole trigger node: `{ name, type, displayName, valid, settings }` |
+| `UPDATE_ACTION` | the whole node, same shape. **A router's branches are edited this way** — they live in `settings.branches`, and there is no `UPDATE_BRANCH` in the enum |
+| `ADD_ACTION` | `{ parentStep, action: {...whole node...}, stepLocationRelativeToParent?, branchIndex? }` |
+| `DELETE_ACTION` | `{ names: [ ... ] }` — an **array**; a single `name` is rejected |
+| `CHANGE_NAME` | `{ displayName }` |
+| `CHANGE_STATUS` | `{ status: "ENABLED" or "DISABLED" }` |
+
+Also in the enum: `MOVE_ACTION`, `DUPLICATE_ACTION`, `LOCK_AND_PUBLISH`,
+`LOCK_FLOW`, `USE_AS_DRAFT`, `CHANGE_FOLDER`, `UPDATE_METADATA`,
+`SAVE_SAMPLE_DATA`, `SET_SKIP_ACTION`, `ADD_BRANCH`, `DELETE_BRANCH`,
+`DUPLICATE_BRANCH`.
+
+**Five operations act on an empty request instead of rejecting it:**
+`CHANGE_STATUS`, `LOCK_AND_PUBLISH`, `LOCK_FLOW`, `CHANGE_FOLDER`,
+`UPDATE_METADATA`. Enumerating the enum by sending each with `request: {}`
+published and enabled a draft flow. `IpaasClient` refuses an empty request for
+those types; never work around it.
+
+`['output']['output']` in a stored pill is a known signature: a double migration.
+
+Reserve `IMPORT_FLOW` for importing an actual export, in the file form.
+
+## Real examples
+
+`examples/` holds 13 sanitized flows from a real production trade-finance
+integration — `examples/README.md` catalogues what each one demonstrates and
+which node types/pieces it uses. Reach for one when you need to see a shape
+rather than infer it: a `LOOP_ON_ITEMS` with a `ROUTER` in its body,
+`piece-store` used as cross-step state, a `WEBHOOK` trigger paired with a
+`CALLABLE_FLOW` chain, `piece-http-oauth2` for an authenticated external
+call. Field names inside the (blanked) sample data are real; only the values
+are placeholders.
+
+## Check the catalogue, never guess
+
+```bash
+node research/ipaas-piece.ts '@activepieces/piece-pipefy' getCardsByFieldValue
+```
+
+Piece versions, action names and required props all move between versions. The
+instance offers 765 pieces; read what it has. This caught a real error once: a
+hand-typed fixture listed `slack-find-user-by-email` as a trigger when it is an
+action.
+
+Useful `piece-pipefy@0.2.1` actions: `getCardById`, `getCardsByFieldValue`,
+`getCardsByPhase`, `createCard`, `updateCard`, `moveCard`, `updateListField`,
+`uploadAttachment`, `custom_api_call`. Triggers: `cardCreated`, `cardDone`,
+`cardMoved`, `cardFieldUpdated`, and the record equivalents.
+
+## Before you write anything
+
+Run the offline validator. It checks node types, unique names, backward-only
+references, router `children.length == branches.length`, one trailing `FALLBACK`,
+condition operators, `CODE` shape, semver, action names against the catalogue,
+connections resolving and being `ACTIVE`, clear-text credentials, and the
+cross-surface group — phases and field slugs against the pipe schemas on disk.
+
+```bash
+node research/ipaas/check.ts <path to flow json>
+```
+
+The condition-operator trap: it is **`TEXT_START_WITH`**, singular, not
+`TEXT_STARTS_WITH`.
+
+## After you write, always
+
+Read the flow back and diff the datapills against what you sent. That is the only
+check that catches the migration bug, and no structural rule ever will.
+
+```bash
+node research/ipaas/diff-readback.ts <flowId>
+```
+
+## Never
+
+- Put a credential in `settings.input`. Reference a connection.
+- Write a connection. They hold secrets; read them, reference them, refuse.
+- Publish a flow as a side effect. `ap_lock_and_publish` arms it against live
+  traffic — that is the user's decision, made explicitly.

package/.agents/skills/ppc-pipefy-flow-authoring/examples/01-main-2-danfe-consulta.json

@@ -0,0 +1,247 @@
+{
+  "name": "✅[PRD][1/2 MAIN][DANFE] Consulta",
+  "type": "SHARED",
+  "summary": "",
+  "description": "",
+  "tags": [],
+  "blogUrl": "",
+  "metadata": {
+    "externalId": "exampleFlowId01aaaaaa"
+  },
+  "author": "Integrações Ipaas 000000000",
+  "categories": [],
+  "pieces": [
+    "@activepieces/piece-subflows",
+    "@activepieces/piece-date-helper",
+    "@activepieces/piece-http-oauth2",
+    "@activepieces/piece-tables"
+  ],
+  "flows": [
+    {
+      "displayName": "✅[PRD][1/2 MAIN][DANFE] Consulta",
+      "trigger": {
+        "name": "trigger",
+        "valid": true,
+        "displayName": "Callable Flow",
+        "nextAction": {
+          "name": "step_3",
+          "skip": false,
+          "type": "PIECE",
+          "valid": true,
+          "settings": {
+            "input": {
+              "timeZone": "America/Sao_Paulo",
+              "timeFormat": "YYYY-MM-DDTHH:mm:ss"
+            },
+            "pieceName": "@activepieces/piece-date-helper",
+            "actionName": "get_current_date",
+            "sampleData": {},
+            "pieceVersion": "0.1.28",
+            "propertySettings": {
+              "timeZone": {
+                "type": "MANUAL"
+              },
+              "timeFormat": {
+                "type": "MANUAL"
+              }
+            },
+            "errorHandlingOptions": {
+              "retryOnFailure": {
+                "value": false
+              },
+              "continueOnFailure": {
+                "value": false
+              }
+            }
+          },
+          "nextAction": {
+            "name": "step_2",
+            "skip": false,
+            "type": "PIECE",
+            "valid": true,
+            "settings": {
+              "input": {
+                "url": "{{variables['PRD_BASE_URL']}}/v1/danfe/processar-nfe",
+                "auth": "{{connections['exampleConnectionId1']}}",
+                "body": {
+                  "data": {
+                    "xml_base64": "{{trigger['output']['data']['nfXmlBase64']}}",
+                    "webhook_url": "https://ipaas.pipefy.com/api/v1/webhooks/EXAMPLE0WEBHOOK0ID0000"
+                  }
+                },
+                "method": "POST",
+                "headers": {
+                  "timestamp": "{{step_3['output']['result']}}",
+                  "Content-Type": "application/json",
+                  "correlation-id": "123e4567-e89b-12d3-a456-426614174000"
+                },
+                "failsafe": false,
+                "body_type": "json",
+                "use_proxy": false,
+                "queryParams": {},
+                "proxy_settings": {}
+              },
+              "pieceName": "@activepieces/piece-http-oauth2",
+              "actionName": "send-oauth2-request",
+              "sampleData": {},
+              "pieceVersion": "0.2.5",
+              "propertySettings": {
+                "url": {
+                  "type": "MANUAL"
+                },
+                "body": {
+                  "type": "MANUAL",
+                  "schema": {
+                    "data": {
+                      "type": "JSON",
+                      "required": true,
+                      "displayName": "JSON Body"
+                    }
+                  }
+                },
+                "method": {
+                  "type": "MANUAL"
+                },
+                "headers": {
+                  "type": "MANUAL"
+                },
+                "timeout": {
+                  "type": "MANUAL"
+                },
+                "failsafe": {
+                  "type": "MANUAL"
+                },
+                "body_type": {
+                  "type": "MANUAL"
+                },
+                "use_proxy": {
+                  "type": "MANUAL"
+                },
+                "queryParams": {
+                  "type": "MANUAL"
+                },
+                "proxy_settings": {
+                  "type": "MANUAL",
+                  "schema": {}
+                }
+              },
+              "errorHandlingOptions": {
+                "retryOnFailure": {
+                  "value": false
+                },
+                "continueOnFailure": {
+                  "value": false
+                }
+              }
+            },
+            "nextAction": {
+              "name": "step_1",
+              "skip": false,
+              "type": "PIECE",
+              "valid": true,
+              "settings": {
+                "input": {
+                  "values": {
+                    "values": [
+                      {
+                        "7bH9z7hla9ZpsWc2uKpvI": "{{trigger['output']['data']['cardId']}}",
+                        "fmGH4R1KROvWCjlqLsoSe": "{{step_2['output']['body']['transactionId']}}"
+                      }
+                    ]
+                  },
+                  "table_id": "exampleTableId000000"
+                },
+                "pieceName": "@activepieces/piece-tables",
+                "actionName": "tables-create-records",
+                "sampleData": {},
+                "pieceVersion": "0.3.2",
+                "propertySettings": {
+                  "values": {
+                    "type": "MANUAL",
+                    "schema": {
+                      "values": {
+                        "type": "ARRAY",
+                        "required": true,
+                        "properties": {
+                          "7bH9z7hla9ZpsWc2uKpvI": {
+                            "type": "SHORT_TEXT",
+                            "required": false,
+                            "description": "Text",
+                            "displayName": "cardId",
+                            "defaultValue": ""
+                          },
+                          "fmGH4R1KROvWCjlqLsoSe": {
+                            "type": "SHORT_TEXT",
+                            "required": false,
+                            "description": "Text",
+                            "displayName": "transactionId",
+                            "defaultValue": ""
+                          }
+                        },
+                        "description": "Add one or more records to insert",
+                        "displayName": "Records"
+                      }
+                    }
+                  },
+                  "table_id": {
+                    "type": "MANUAL"
+                  }
+                },
+                "errorHandlingOptions": {
+                  "retryOnFailure": {
+                    "value": false
+                  },
+                  "continueOnFailure": {
+                    "value": false
+                  }
+                }
+              },
+              "displayName": "Create Record(s)",
+              "lastUpdatedDate": "2026-08-21T12:47:05.847Z"
+            },
+            "displayName": "Consulta Cedente",
+            "lastUpdatedDate": "2026-08-21T12:47:00.766Z"
+          },
+          "displayName": "Get Current Date",
+          "lastUpdatedDate": "2026-08-21T12:47:00.766Z"
+        },
+        "lastUpdatedDate": "2026-08-21T12:47:00.766Z",
+        "type": "PIECE_TRIGGER",
+        "settings": {
+          "sampleData": {},
+          "propertySettings": {
+            "mode": {
+              "type": "MANUAL"
+            },
+            "exampleData": {
+              "type": "MANUAL",
+              "schema": {
+                "sampleData": {
+                  "type": "example",
+                  "required": false,
+                  "displayName": "example"
+                }
+              }
+            }
+          },
+          "pieceName": "@activepieces/piece-subflows",
+          "pieceVersion": "0.4.12",
+          "triggerName": "callableFlow",
+          "input": {
+            "mode": "advanced",
+            "exampleData": {
+              "sampleData": {
+                "cardId": "example",
+                "nfXmlBase64": "example"
+              }
+            }
+          }
+        }
+      },
+      "valid": true,
+      "schemaVersion": "22",
+      "notes": []
+    }
+  ],
+  "status": "PUBLISHED"
+}