@openapi-flow/n8n 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 carefreelife98
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @openapi-flow/n8n
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deterministic OpenAPI request-node creation and explicit n8n DAG assembly with the official workflow SDK. Unreleased `0.2.0` source; this package is not yet published.
+
+## Installed declaration dependencies
+
+This adapter's public types reference `@n8n/workflow-sdk@0.36.4`, which depends on `n8n-workflow@2.43.4`. Declarations in that SDK/workflow chain, `@n8n/errors@0.15.0` and `@n8n/utils@1.50.1` import modules/types listed only as development dependencies. A consumer does not install another package's development dependencies. This adapter therefore declares the required packages in its own `dependencies`: `@n8n/config@2.41.2`, `@sentry/node@10.70.0`, `nock@14.0.14`, `@types/estree@1.0.8`, `@types/express@5.0.1`, `@types/json-schema@7.0.15`, `@types/luxon@3.2.0`, `@types/semver@7.7.0` and `@types/ssh2@1.15.0`. These versions follow the corresponding upstream manifests; a fresh strict consumer verifies compatibility. Installing Sentry does not initialize telemetry in this adapter.
+
+Normal installation brings these packages automatically, including production installations that omit development dependencies. Consumers do not need to install them manually, enable `skipLibCheck`, add declaration shims or run a custom installation script. These dependencies do not start an HTTP server, execute nock or configure an n8n instance. Core and LangChain packages do not own this SDK-specific contract. Keep these declarations until a verified SDK/workflow upgrade supplies its complete public declaration dependency graph; remove them only after the independent strict consumer still passes. See the [TypeScript publishing guidance](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#dependencies).
+
+## Public APIs
+
+- `createHttpRequestNode`: full selected OAS contract + literal values/response bindings + optional trusted base URL/credential references → SDK node fragment. Bound requests additionally require `apiNodeNames` and compile into materialization Code → HTTP Request.
+- `httpRequestDeploymentOptionsSchema`: shared validation for optional execution settings. Missing URLs become `https://replace_me.invalid`; required missing Bearer references become `REPLACE_ME:<documentId>:<schemeName>`. Supplied invalid settings fail rather than becoming placeholders.
+- `assembleN8nWorkflow`: explicit fragments, named ports, edges and starts → SDK-validated importable JSON. Fan-out is supported; node-array order does not define execution order.
+- `createN8nNativeCapabilities`: described Zod configuration schemas and deterministic compilers for IF, Merge Append, response-assertion Code and StopAndError. Custom capability registration is supported.
+- `compilePlannedN8nWorkflow`: validates model/host graph plans against materials/capabilities, checks response availability and joins, and builds importable JSON using the SDK.
+- `compileBatchedN8nWorkflow`: the same complete-plan checks plus explicit finite batch scopes → SDK Loop Over Items wiring, unchanged item ancestry and completion-time downstream execution.
+- `compileReviewableN8nWorkflow`: validated review plan + ready/blocked API materials + ready fragments + native capabilities → common `workflow` JSON. Complete plans use the strict compiler. Gap plans return `{ status: 'needs-review', workflow, diagnostics }` with connected internal nodes and a detached Start.
+- `compileInboundWorkflow`: preserved Webhook/Callback response compilation.
+
+Built-in IF and response assertions provide capability-owned planning-schema hooks. Their response `nodeId` is an enum of supplied API call instances during generation, while their runtime parameter schemas remain unchanged. Without API materials, only literal operands are offered; other native capabilities remain usable. The specialized schema does not change OAS acceptance, data types, response values or SDK compilation. Both generation-time and final graph/reference checks are retained.
+
+No LLM dependency, HTTP server, workflow import/publication or API execution. Compilation does not require per-path `effectPolicy`; the host owns execution approval. Bound requests preserve actual JSON types, validate the complete request against its OAS schema and reuse literal serialization. Ordinary reads require one unambiguous item; explicit linked mode uses n8n ancestry for HTTP bindings, IF and assertions. Native JSON output binding, Split Out array iteration including linked nested API arrays, Aggregate collection, shared-scope API item joins and explicit linear/complete-fan-out batch paths are implemented; conditional/filtering and nested batch scopes, cross-invocation joins and exhaustive response-schema proof remain pending. The validator is compiled on the host with [Ajv standalone code generation](https://ajv.js.org/standalone.html); n8n receives no schema compiler or eval requirement. Its bundled equality helper compares JSON structurally rather than inspecting constructors across isolated realms, without changing schemas or values. Missing required API values fail without defaults. Code is library-owned, not model-written. Multi-node fragments require explicit internal edges, validated and wired by the assembler. Earlier policy-aware single/sequence compilers live under `/legacy`.
+
+Template nodes visibly list missing execution settings in their notes. No OAS server is selected automatically, no credential secret is embedded, and anonymous APIs receive no credential placeholder. Provide settings and regenerate before execution, or replace placeholders and select existing n8n credentials. Bound URLs also live in the Materialize node configuration; editing only the HTTP Request URL is insufficient. Fully configured output and strict `/legacy` contracts remain unchanged.
+
+Review workflows preserve confirmed HTTP Request/native nodes, materialization nodes and internal DAG edges. Each gap and blocked API call becomes a main-input/main-output Code placeholder that always throws `OPENAPI_FLOW_UNRESOLVED_STEP`; a Sticky Note explains the reported requirement. Placeholder code is library-owned and encodes descriptions as data, never JavaScript instructions. No unavailable API, argument or response is fabricated. Every Start-to-root connection is omitted, and `active: false` is supplementary. Review status does not certify scenario coverage or execution safety. Reconnecting Start can execute real preceding API calls before the placeholder fails; host approval and credential controls remain necessary.
+
+Each placeholder is enclosed in a red Sticky Note region with the Korean heading `확인 필요`, localized stage labels, replacement guidance and execution warnings. The node is named `확인 필요 · <nodeId>` and displays a short Korean note in the canvas. The region reserves space for its complete diagnostic text above the node; multiple regions are placed separately below existing positioned nodes. Supplied descriptions, identifiers and OAS contracts are preserved, not automatically translated or truncated. This uses built-in nodes only and needs no community-node installation.
+
+Compilation types live in `src/types/reviewable-workflow.ts` and `src/types/workflow-compilation.ts`; fixed failure nodes in `src/nodes/gap/`; annotations/escaping in `src/workflow/review/`; assembly in `src/workflow/build-n8n-workflow.ts`. The assembler creates the sole Manual Trigger and preserves all internal edges. Core validates topology even with gaps. Unblocked calls cannot reference blocked API responses; confirmed response-dependent calls must themselves be explicitly blocked. Invalid OAS, literal inputs, ports, references or unsupported unblocked compilers are errors, not automatic gaps. Existing strict compilers retain their fail-fast behavior. The old unpublished notes-only preview API was replaced, not aliased.
+
+`integration/workflow-review-local-n8n.mjs` imports/exports three public scripted-model gap cases and an independent-root case, executes only Start with zero API calls, then deliberately reconnects one case against a local contract server and verifies failure at the placeholder without downstream calls. Output is in `.local-artifacts/workflow-review/`. This tests CLI runtime, not browser partial execution, real LLM selection quality or business APIs. [n8n distinguishes manual, partial and production execution](https://docs.n8n.io/build/understand-workflows/understand-executions/types-of-executions/); `active: false` alone does not prevent manual execution. Redact scenario/request/diagnostic content before sharing workflow JSON.
+
+Our code is MIT-licensed. The separately licensed `@n8n/workflow-sdk` dependency is subject to n8n's [Sustainable Use License](https://docs.n8n.io/n8n-community-license/). Our license does not change those terms. See [third-party notices](./THIRD_PARTY_NOTICES.md) and the [workspace guide](https://github.com/carefreelife98/openapi-flow#implemented-checkpoint-and-remaining-work).
+
+## Native response checks
+
+`compilePlannedN8nWorkflow`, `compileBatchedN8nWorkflow` and `compileReviewableN8nWorkflow` provide original API response contracts from their materials to native compilers. IF/assertions require the original OAS contract and actual source name for each referenced API. If invoking a capability's `compile` directly, supply `apiResponseContracts` alongside `apiNodeNames`; literal-only checks need no response context. Assembly rejects a different declared contract or producer.
+
+Shared compilation lives in `nodes/native/response-checks/`, with types in `types/response-check-compilation.ts` and `types/response-check-guard.ts`. IF uses Code guard → official IF, preserving input values, binary fields and paired-item ancestry. Its expressions contain only source reads and comparisons. Assertions use the same full-response reader before checking values. Runtime status/media select the OAS response contract; matching one field never exempts invalid sibling fields. No schema or data conversion is introduced.
+
+`test:array-iteration-local-n8n` covers 14 cases, including five new IF/assertion failures with no forbidden downstream calls. Its report explicitly retains the original error and the n8n display message. n8n 2.37.10's [task-runner parser](https://github.com/n8n-io/n8n/blob/n8n%402.37.10/packages/%40n8n/task-runner/src/js-task-runner/errors/execution-error.ts) truncates colon-containing errors despite preserving the original stack. This display defect remains unresolved; the adapter does not rewrite errors to accommodate it.
+
+## Declared native output bindings
+
+`createJsonOutputCapability({ name, description, parametersSchema })` creates an opt-in typed literal producer using the official SDK's Edit Fields (`n8n-nodes-base.set`, version 3.4) JSON mode. Parameters are validated unchanged: schema coercion, defaults or transformations cannot silently rewrite them. Expression-like strings and dotted keys remain data. This is not a general calculation engine or an automatic conversion step.
+
+Native producers declare `outputSchema(parameters)` in their capability. `createN8nNativeOutputSources({ nativeNodes, capabilities, apiNodeNames })` derives the schema and actual SDK exit name. Pass these as `nativeOutputSources` to `createHttpRequestNode`; retain `apiNodeNames` for API response producers. API values are read from `json.body`; native values from the JSON item root. Both use the same pointer materializer and OAS request validation/serialization. Native source schemas are also validated before HTTP. A missing field, incompatible type, ambiguous multiple item output, wrong runtime name/schema or unavailable graph producer is an error, not a fallback.
+
+`integration/native-output-bindings-local-n8n.mjs` uses a supplied private ICL OAS file and a local contract endpoint. Its CLI is an explicitly scripted baseline; `runNativeOutputValidation` also accepts a real LangChain model. It validates unchanged mixed JSON types, dotted keys, expression-like literal text and three producer failures. It does not call ICL, prove response business semantics, add iteration or broaden authentication. Artifacts live under `.local-artifacts/native-output-bindings/<plannerLabel>/` and are not published. The [Edit Fields documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.set/) and [upstream implementation](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Set/v2/SetV2.node.ts) describe JSON mode; the adapter disables inclusion of other input fields and dot notation explicitly.
+
+Each validation attempt now retains an independent `runs/<UUID>/` directory: `planning-context.json`, successful `workflow.json`/`report.json`, or a `failure.json` containing the phase and application-owned planning stage/cause/raw output. It never copies unclassified transport messages, headers or request objects. Top-level workflow/report files still represent the latest successful result, not an aggregate success rate. No failure is repaired or retried by the runner.
+
+Observed upstream issue: on n8n `2.37.10`, a valid top-level JSON string response with `autodetect` + `fullResponse: true` failed before the next node. The installed HTTP Request implementation parses the JSON at `HttpRequestV3.node.js:688`, then parses the resulting string again at line `799`. Current `createHttpRequestNode` fragments now use an explicit OSS response adapter: official File-mode HTTP transport `Receive <callId>` → deterministic Code decoder `Request <callId>`. The latter is the public fragment exit; all response names must refer to that decoded exit. The adapter reads original bytes using the official `this.helpers.getBinaryDataBuffer` API and parses JSON once, without changing OAS contracts or repairing values. This is an OSS mitigation, not an upstream n8n fix. Legacy generation entrypoints are unchanged.
+
+`createResponseCollectionCapability({ materials })` registers `collect-api-responses`. Only source call ID and pointer are planned; code validates every original response and compiles Code reader → Aggregate. Its `{items: values}` output preserves nesting, nulls, duplicates and input item order. Missing pointers fail before Aggregate, never becoming null substitutes. Collection applies to one incoming stream in one invocation, not a join or standalone accumulator. A batch scope's done stream can supply all processed items in one invocation; the reader uses each item's ancestry to resolve source responses across node runs. Empty streams do not fabricate output. Source name/contract declarations are checked against compiled workflow materials for both API and native fragments.
+
+File mode disables n8n's automatic JSON request encoding too. The OSS serializer encodes the OAS value once; the node adapter encodes that wire text into the JSON Body setting, which n8n parses back to the unchanged wire text before sending. The API does not receive the setting envelope. Both literal and materialized JSON bodies use this contract, including strings, nulls, arrays and DELETE bodies.
+
+`npm run test:json-response-local-n8n` verifies nine unchanged JSON values through source → OAS validation → response-bound echo POST → literal echo DELETE → response collection. Both actual received bodies and responses must equal the original values. Ordinary, numeric-looking, JSON-shaped and empty strings retain their types. `node integration/json-response-local-n8n.mjs --native` retains a separately failing unmodified-n8n baseline. Artifacts: `.local-artifacts/json-response/` and its `native/` subdirectory. `npm run test:http-response-decoding-local-n8n` checks twelve additional transport cases, including malformed JSON, invalid UTF-8, structured `+json`, text charsets, binary bytes and no-body responses. Raw metadata/status and item ancestry remain intact; invalid content is never replaced by `{}`, `null` or an empty item. JSON is UTF-8; text uses its explicit header charset or the native UTF-8 codec default. Binary routing retains the verified HTTP Request v4.3 policy, with bytes exposed as `binary.data`. The temporary `openApiFlowRawResponse` binary field is reserved for the transport adapter and removed from its output. See [official binary access](https://docs.n8n.io/code/cookbook/code-node/get-binary-data-buffer/).
+
+`createItemJoinCapability({ materials, scopes })` registers `join-api-items` with existing API contracts and actual compiled native scope sources. Only `scopeNodeId` and unique `sourceCallIds` are planned. Input ports correspond to that call order; each port requires its own API and the shared native ancestor. Per-branch readers validate full OAS responses and the native scope, official Merge Append waits for the branches, and library-owned grouping combines only responses whose n8n ancestry identifies the same scope object. It never matches business IDs, equal JSON or independent stream positions. Missing/duplicate branch results and ambiguous ancestry are errors.
+
+Output `{ responses: { callId: unchangedBody } }` preserves values and every contributing item link. Results follow original scope order. Both branches excluding an item yields no result for that item; an asymmetric exclusion is an error, not a silently dropped join. Empty scopes emit nothing. Scope names/schemas and API contracts are checked against the compiled producers. The implementation is invocation-scoped and can join complete branches in each explicit batch invocation, as described below. Cross-invocation joins and nested batch scopes remain pending. SDK fragments may declare validated `inputEndpoints` for separate input readers; the workflow assembler routes the ports to those actual entry nodes.
+
+Derived response pointer/item candidates preserve conjunctive constraints and normalize OAS 3.0 syntax before native validation. They do not replace full source validation: projected oneOf branches can overlap, and item candidates do not prove tuple positions, sibling conditions or complete schema implication. `npm run test:schema-projection-local-n8n` checks composite item binding and nullable scalar collection through the installed n8n runtime. Neither original OAS contracts nor data are modified.
+
+## Nested API response arrays
+
+Register `createResponseArrayCapability({ materials, itemMode: 'linked' })` to split each input's linked API response array. The host selects execution mode; the planner still supplies only `sourceNodeId` and `pointer`. The reader validates every full OAS response before Split Out and pairs each array wrapper with its own input. Split Out preserves that parent link for every unchanged child. Dependent linked API calls can read both split levels and intermediate API responses. Empty arrays produce no child requests; missing/ambiguous ancestry and invalid OAS values fail without substitution. The ordinary array registry retains its singleton guard.
+
+`npm run test:nested-array-iteration-local-n8n` verifies two split levels, five APIs, repeated parent/child IDs, IF-filtered parents, an empty middle array, full empty streams and invalid response/media cases on n8n 2.37.10. Local import JSON/report: `.local-artifacts/nested-array-iteration/`. This is a deterministic regression, not an LLM quality score. Cross-invocation accumulation and automatic scope selection remain pending. Explicit batch execution is a separate compiler below.
+
+### Native JSON output arrays
+
+`createNativeArrayCapability({ sources, itemMode: 'linked' })` accepts actual native output contracts and compiled names from `createN8nNativeOutputSources`. Its structured-output parameters contain only the supplied `sourceNodeId` and array `pointer`. Code derives the item contract and validates the whole original native output before official Split Out, sharing mechanics with API array splitting in `src/nodes/native/arrays/`. Native pointers start at the JSON root rather than an HTTP response body. No conversion, flattening or default values are added. Empty arrays emit no children; linked mode retains parent ancestry; ordinary mode rejects ambiguous multiple inputs/sources.
+
+The host derives parent contracts before registering a child planning stage; automatic recursive scope discovery remains pending. Source names/schemas and dependencies are checked by workflow assembly. `npm run test:native-array-iteration-local-n8n` covers twenty cases: ten each with inline and recursive-reference producer contracts. Both variants include two splits, five distinct REST APIs, fan-out/join/collection, empty streams and original native/API contract failures. Local artifacts: `.local-artifacts/native-array-iteration/`, including `five-api-references-workflow.json`. These are deterministic fixtures, not model quality results.
+
+Native output validation compiles each original schema independently instead of embedding producers under a shared root. Core's item/pointer projections bundle the original resource and reference its locations using Ajv's public registry and fast-uri; local and recursive `$ref`, anchors and nested IDs retain scope. The host assigns an offline retrieval URI to anonymous resources without changing original input contracts or values. Runtime nodes receive standalone validators, not a schema resolver. `npm run test:native-schema-references` now verifies the original compiler and reusable item contract as a passing regression. Missing references fail; external registry injection, dynamic-scope projection coverage and exhaustive schema implication remain pending.
+
+## Finite batch paths
+
+Call `compileBatchedN8nWorkflow({ ...completePlanInput, batchScopes })`. Required scopes contain `id`, `batchSize`, `nodeIds`, `entryNodeId` and `exitNodeId`. No scope, size or member is inferred. The logical DAG and all existing provenance/response/port checks remain intact; only the adapter adds official SDK Loop Over Items v3 controllers and their return edges. Scope size is a positive safe integer, reset is false and controller IDs/names must not collide with any existing SDK node.
+
+Scopes must not overlap and must have a single entry/exit. Fragments declare either `preservesInputItems` for one-to-one linked steps or `joinsInputItemsByAncestry: { scopeNodeId }` for explicit joins of complete branches. `validateBatchItemFlow` traces the declared flow, checks one branch per join input and requires a shared scope ancestor that identifies every entry item. Fan-out is allowed without cloning logical/API nodes. Item-preserving relays before the scope retain ancestry. Earlier batch completion is not assumed to be the original exit node's latest run. Custom compilers must honor their declarations; this is not arbitrary JavaScript proof.
+
+`createPassThroughCapability()` is opt-in and compiles the official [No Operation node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.noop/), version 1, with a strict empty configuration. It preserves input items/links unchanged and can supply the common entry before fan-out. It neither emits synthetic items nor declares a guessed native output schema.
+
+IF with a discarded alternative, item-dropping Filter, Split Out, Aggregate and ordinary Merge Append lack a complete batch return contract: an empty branch may never execute its return and stop the remaining batches. Place Split Out before the scope and Aggregate after completion. This does not narrow OAS intake. Item-dropping Filter completion, nested batch scopes, cross-invocation joins and automatic model scope planning remain pending.
+
+Register `createExclusiveBranchMergeCapability()` explicitly for `rejoin-exclusive-branches`. Its only parameter is an existing IF's `sourceNodeId`; code owns the official Merge 3.2 append parameters and two input ports. Core verifies distinct complete alternatives and retains route-specific response availability. Batch validation requires every IF output to return through a one-to-one linked path and rejoin inside the same scope. IF declares `partitionsInputItems`; rejoin declares `rejoinsExclusiveOutputs`, rather than claiming a single-input contract. Normal Merge Append is unchanged. Custom compilers must preserve these declarations.
+
+An explicit `createPassThroughCapability()` skip branch returns the actual item unchanged, not an empty completion item. In n8n 2.37.10 with `executionOrder: 'v1'`, waiting Merge handles an alternative that never ran after runnable work is exhausted. No `alwaysOutputData`, forced execution order changes or missing-response defaults are added. A response from only the executed business branch is still unavailable unconditionally after rejoin.
+
+`npm run test:conditional-batch-local-n8n` checks 14 deterministic cases with five distinct API nodes, all/mixed/no eligible items at batch sizes 1/2/10, empty input and contract/assertion failures. It collects all original detail items once after completion; skipped items are not successful business API responses. Import JSONs/report: `.local-artifacts/conditional-batch/`. These tests do not measure real-model planning or call business services. Source contracts and validators remain separated under `src/schemas/`, `src/types/`, core `src/workflow/` and n8n `src/workflow/batch/`.
+
+`npm run test:batch-iteration-local-n8n` verifies ten cases on n8n 2.37.10, including five API instances, multiple batch sizes, linked cross-run references and one final array-body request. Import JSONs/report live under `.local-artifacts/batch-iteration/`; regenerate with a running endpoint before execution. Types and schema are separated in `src/types/batch-execution.ts` and `src/schemas/batch-execution-schema.ts`; validation/lowering live in `src/workflow/batch/` and reuse `compile-validated-workflow-fragments.ts`.
+
+`npm run test:batch-item-join-local-n8n` verifies eight complete-branch cases on the same pinned runtime. Reordered branches and identical original values retain distinct ancestry; source/branch contract errors and wrong media type stop later batches and final collection. The three-branch/five-API case makes 13 requests for three items and collects once. Local import JSONs/report: `.local-artifacts/batch-item-join/`. These deterministic fixtures test runtime behavior, not Chomsky selection quality or business APIs.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third-party notices
+
+`@openapi-flow/n8n` depends on `@n8n/workflow-sdk`, separately licensed under n8n's [Sustainable Use License](https://github.com/n8n-io/n8n/blob/master/LICENSE.md). Its terms restrict use and redistribution; check them for your intended use. This package does not bundle the SDK's source code.
+
+Other dependencies retain their own licenses. The MIT license in this package applies to openapi-flow's code only.
+
+The adapter also installs `@n8n/config` and its dependencies to resolve the pinned SDK's public declaration imports. The installed `@n8n/config`, `@n8n/di` and `@n8n/constants` packages ship their own n8n license notices; this adapter does not replace those notices or bundle those packages' source code. `nock` and the Express, JSON Schema, SSH2 and Luxon declaration packages likewise retain their own license notices.
+
+Runtime-bound HTTP requests include library-owned materialization code and an Ajv-generated standalone request validator. Any bundled validator dependency retains its complete license notice in the generated Code node. Ajv and ajv-formats are MIT-licensed; their transitive runtime helpers retain their own MIT or BSD notices when bundled. The schema compiler and the n8n SDK are not embedded in these Code nodes. esbuild is used on the host to bundle standalone runtime code and is separately MIT-licensed.

package/dist/legacy/workflow/common/plan-validation.d.ts

@@ -0,0 +1 @@
+export declare function assertSerializablePlan(plan: unknown): void;

package/dist/legacy/workflow/common/plan-validation.js

@@ -0,0 +1,11 @@
+export function assertSerializablePlan(plan) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(plan);
+    }
+    catch {
+        throw new Error('plan must be JSON-serializable');
+    }
+    if (!serialized)
+        throw new Error('plan must be a JSON document');
+}

package/dist/legacy/workflow/common/workflow-id.d.ts

@@ -0,0 +1 @@
+export declare function workflowId(baseUrl: string, plan: unknown): string;

package/dist/legacy/workflow/common/workflow-id.js

@@ -0,0 +1,8 @@
+import { createHash } from 'node:crypto';
+export function workflowId(baseUrl, plan) {
+    return ('openapi-flow-' +
+        createHash('sha256')
+            .update(JSON.stringify({ baseUrl, plan }))
+            .digest('hex')
+            .slice(0, 16));
+}

package/dist/legacy/workflow/inbound/build-inbound-workflow.d.ts

@@ -0,0 +1,2 @@
+import type { InboundResult, InboundWorkflowContext } from '../../../types/legacy/inbound-workflow.js';
+export declare function buildInboundWorkflow(context: InboundWorkflowContext): InboundResult;

package/dist/legacy/workflow/inbound/build-inbound-workflow.js

@@ -0,0 +1,60 @@
+import { node, trigger, validateWorkflow, workflow } from '@n8n/workflow-sdk';
+import { UnsupportedOperationError } from '@openapi-flow/core/internal';
+import { workflowId } from '../common/workflow-id.js';
+import { inboundResponseBody } from './inbound-response.js';
+export function buildInboundWorkflow(context) {
+    const { document, selected, plan } = context;
+    const { candidate, operation } = selected;
+    if (!['DELETE', 'GET', 'HEAD', 'PATCH', 'POST', 'PUT'].includes(candidate.method))
+        throw new UnsupportedOperationError(candidate.operationRef, `operationRef ${candidate.operationRef} uses HTTP method ${candidate.method}, which n8n Webhook node v2.1 does not expose`);
+    const effectiveSecurity = operation.security === undefined
+        ? document.spec.security
+        : operation.security;
+    if (Array.isArray(effectiveSecurity) && effectiveSecurity.length > 0)
+        throw new UnsupportedOperationError(candidate.operationRef, `operationRef ${candidate.operationRef} requires inbound authentication that has no n8n Webhook credential mapping`);
+    const responseBody = inboundResponseBody(context);
+    const id = workflowId(plan.webhookPath, plan);
+    const start = trigger({
+        type: 'n8n-nodes-base.webhook',
+        version: 2.1,
+        config: {
+            id: 'webhook',
+            name: 'Webhook',
+            webhookId: id,
+            position: [240, 300],
+            parameters: {
+                httpMethod: candidate.method,
+                path: plan.webhookPath,
+                authentication: 'none',
+                responseMode: 'responseNode',
+            },
+        },
+    });
+    const respond = node({
+        type: 'n8n-nodes-base.respondToWebhook',
+        version: 1.5,
+        config: {
+            id: 'respond',
+            name: 'Respond to Webhook',
+            position: [480, 300],
+            parameters: {
+                respondWith: responseBody === undefined ? 'noData' : 'json',
+                ...(responseBody === undefined ? {} : { responseBody }),
+                options: { responseCode: plan.responseStatus },
+            },
+        },
+    });
+    const built = workflow(id, 'OpenAPI ' + candidate.source + ' ' + candidate.method)
+        .add(start)
+        .to(respond);
+    const validation = validateWorkflow(built);
+    if (!validation.valid)
+        throw new Error('n8n SDK validation failed: ' +
+            validation.errors.map((error) => error.message).join('; '));
+    return {
+        status: 'complete',
+        plan,
+        evidence: candidate,
+        workflow: built.toJSON(),
+    };
+}

package/dist/legacy/workflow/inbound/compile-inbound-workflow.d.ts

@@ -0,0 +1,2 @@
+import type { InboundRequest, InboundResult } from '../../../types/legacy/inbound-workflow.js';
+export declare function compileInboundWorkflow({ spec, plan, }: InboundRequest): Promise<InboundResult>;

package/dist/legacy/workflow/inbound/compile-inbound-workflow.js

@@ -0,0 +1,25 @@
+import { validateAndResolveOpenApiDocument } from '@openapi-flow/core/internal';
+import { inboundOperationSourcesFromDocument } from '@openapi-flow/core/internal';
+import { isObject } from '@openapi-flow/core/internal';
+import { assertSerializablePlan } from '../common/plan-validation.js';
+import { buildInboundWorkflow } from './build-inbound-workflow.js';
+export async function compileInboundWorkflow({ spec, plan, }) {
+    if (!isObject(plan) ||
+        plan.version !== '1' ||
+        typeof plan.goal !== 'string' ||
+        !plan.goal.trim() ||
+        typeof plan.operationRef !== 'string' ||
+        typeof plan.webhookPath !== 'string' ||
+        !plan.webhookPath.trim() ||
+        !Number.isInteger(plan.responseStatus) ||
+        plan.responseStatus < 100 ||
+        plan.responseStatus > 599)
+        throw new Error('plan must contain version 1, goal, operationRef, webhookPath, and responseStatus');
+    assertSerializablePlan(plan);
+    const document = await validateAndResolveOpenApiDocument(spec);
+    const selected = inboundOperationSourcesFromDocument(document).find(({ candidate }) => candidate.operationRef === plan.operationRef);
+    if (!selected)
+        throw new Error('plan.operationRef is not in spec.webhooks or callbacks: ' +
+            plan.operationRef);
+    return buildInboundWorkflow({ document, selected, plan });
+}

package/dist/legacy/workflow/inbound/inbound-response.d.ts

@@ -0,0 +1,2 @@
+import type { InboundWorkflowContext } from '../../../types/legacy/inbound-workflow.js';
+export declare function inboundResponseBody({ selected, plan, }: InboundWorkflowContext): string | undefined;

package/dist/legacy/workflow/inbound/inbound-response.js

@@ -0,0 +1,51 @@
+import { checkSchemaValue } from '@openapi-flow/core/internal';
+import { dereferencedObject, object } from '@openapi-flow/core/internal';
+import { UnsupportedOperationError } from '@openapi-flow/core/internal';
+export function inboundResponseBody({ selected, plan, }) {
+    const { candidate, operation } = selected;
+    const responses = object(operation.responses, `operationRef ${candidate.operationRef}.responses`);
+    const status = String(plan.responseStatus);
+    const responseKey = Object.hasOwn(responses, status)
+        ? status
+        : Object.hasOwn(responses, status[0] + 'XX')
+            ? status[0] + 'XX'
+            : Object.hasOwn(responses, 'default')
+                ? 'default'
+                : undefined;
+    if (responseKey === undefined)
+        throw new Error(`plan.responseStatus ${status} is not declared by operationRef ${candidate.operationRef}`);
+    const response = dereferencedObject(responses[responseKey], `operationRef ${candidate.operationRef}.responses.${responseKey}`);
+    if (response.headers !== undefined) {
+        const headers = object(response.headers, `operationRef ${candidate.operationRef}.responses.${responseKey}.headers`);
+        for (const [name, raw] of Object.entries(headers)) {
+            const header = dereferencedObject(raw, `operationRef ${candidate.operationRef}.responses.${responseKey}.headers.${name}`);
+            if (header.required === true)
+                throw new UnsupportedOperationError(candidate.operationRef, `operationRef ${candidate.operationRef} response header ${name} needs a host value`);
+        }
+    }
+    let responseBody;
+    if (plan.responseBody !== undefined) {
+        const content = object(response.content, `operationRef ${candidate.operationRef}.responses.${responseKey}.content`);
+        const declared = Object.keys(content);
+        const mediaType = plan.responseMediaType ??
+            (declared.length === 1 ? declared[0] : undefined);
+        if (mediaType === undefined)
+            throw new Error('plan.responseMediaType is required for this response body');
+        if (!Object.hasOwn(content, mediaType))
+            throw new Error(`plan.responseMediaType ${mediaType} is not declared by operationRef ${candidate.operationRef}`);
+        if (mediaType !== 'application/json')
+            throw new UnsupportedOperationError(candidate.operationRef, `operationRef ${candidate.operationRef} response media type ${mediaType} has no n8n mapping`);
+        const media = dereferencedObject(content[mediaType], `operationRef ${candidate.operationRef}.responses.${responseKey}.content.${mediaType}`);
+        if (media.schema !== undefined) {
+            const schema = typeof media.schema === 'boolean'
+                ? media.schema
+                : dereferencedObject(media.schema, `operationRef ${candidate.operationRef}.responses.${responseKey}.content.${mediaType}.schema`);
+            checkSchemaValue(plan.responseBody, schema, 'plan.responseBody');
+        }
+        responseBody = JSON.stringify(plan.responseBody);
+    }
+    else if (plan.responseMediaType !== undefined) {
+        throw new Error('plan.responseMediaType requires plan.responseBody');
+    }
+    return responseBody;
+}

package/dist/legacy/workflow/request/base-url.d.ts

@@ -0,0 +1 @@
+export declare function originFrom(baseUrl: string): URL;

package/dist/legacy/workflow/request/base-url.js

@@ -0,0 +1,14 @@
+export function originFrom(baseUrl) {
+    if (typeof baseUrl !== 'string' || !URL.canParse(baseUrl)) {
+        throw new Error('baseUrl must be an absolute HTTP(S) URL');
+    }
+    const url = new URL(baseUrl);
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new Error('baseUrl must be an HTTP(S) URL without credentials, query, or fragment');
+    }
+    return url;
+}

package/dist/legacy/workflow/request/build-request-workflow.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowJSON } from '@n8n/workflow-sdk';
+import type { BuildRequestWorkflowInput } from '../../../types/legacy/request-workflow.js';
+export declare function buildRequestWorkflow({ baseUrl, plan, operation, url, body, headers, authentication, expectedBody, }: BuildRequestWorkflowInput): WorkflowJSON;

package/dist/legacy/workflow/request/build-request-workflow.js

@@ -0,0 +1,47 @@
+import { node, trigger, validateWorkflow, workflow } from '@n8n/workflow-sdk';
+import { workflowId } from '../common/workflow-id.js';
+import { httpRequestNode } from './http-request-node.js';
+import { assertionCode } from './response-assertion-code.js';
+export function buildRequestWorkflow({ baseUrl, plan, operation, url, body, headers, authentication, expectedBody, }) {
+    const shouldAssert = Object.keys(expectedBody).length > 0;
+    const start = trigger({
+        type: 'n8n-nodes-base.manualTrigger',
+        version: 1,
+        config: { id: 'start', name: 'Start', position: [240, 300] },
+    });
+    const request = httpRequestNode({
+        operation,
+        id: 'request',
+        name: operation.method + ' ' + operation.path,
+        position: [480, 300],
+        url,
+        body,
+        headers,
+        authentication,
+        shouldAssert,
+    });
+    const built = workflow(workflowId(baseUrl, plan), 'OpenAPI ' + operation.method + ' ' + operation.path)
+        .add(start)
+        .to(request);
+    const result = shouldAssert
+        ? built.to(node({
+            type: 'n8n-nodes-base.code',
+            version: 2,
+            config: {
+                id: 'assert',
+                name: 'Assert response',
+                position: [720, 300],
+                parameters: {
+                    mode: 'runOnceForAllItems',
+                    jsCode: assertionCode(expectedBody),
+                },
+            },
+        }))
+        : built;
+    const validation = validateWorkflow(result);
+    if (!validation.valid) {
+        throw new Error('n8n SDK validation failed: ' +
+            validation.errors.map((error) => error.message).join('; '));
+    }
+    return result.toJSON();
+}

package/dist/legacy/workflow/request/build-sequence-workflow.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowJSON } from '@n8n/workflow-sdk';
+import type { BuildSequenceWorkflowInput } from '../../../types/legacy/sequence-workflow.js';
+export declare function buildSequenceWorkflow({ baseUrl, plan, nodes, requiredOutputs, }: BuildSequenceWorkflowInput): WorkflowJSON;

package/dist/legacy/workflow/request/build-sequence-workflow.js

@@ -0,0 +1,53 @@
+import { node, trigger, validateWorkflow, workflow } from '@n8n/workflow-sdk';
+import { responseFieldType } from '@openapi-flow/core/internal';
+import { workflowId } from '../common/workflow-id.js';
+import { httpRequestNode } from './http-request-node.js';
+import { assertionCode } from './response-assertion-code.js';
+export function buildSequenceWorkflow({ baseUrl, plan, nodes, requiredOutputs, }) {
+    let built = workflow(workflowId(baseUrl, plan), 'OpenAPI sequence').add(trigger({
+        type: 'n8n-nodes-base.manualTrigger',
+        version: 1,
+        config: { id: 'start', name: 'Start', position: [240, 300] },
+    }));
+    nodes.forEach(({ operation, id, url, body, headers, expectedBody, authentication }, index) => {
+        const requiredFields = {};
+        for (const field of requiredOutputs.get(id) ?? []) {
+            requiredFields[field] = responseFieldType(operation, field);
+        }
+        const shouldAssert = Object.keys(expectedBody).length > 0 ||
+            Object.keys(requiredFields).length > 0;
+        const request = httpRequestNode({
+            operation,
+            id: 'request-' + id,
+            name: 'Request ' + id,
+            position: [480 + index * 480, 300],
+            url,
+            body,
+            headers,
+            authentication,
+            shouldAssert,
+        });
+        built = built.to(request);
+        if (!shouldAssert)
+            return;
+        const assert = node({
+            type: 'n8n-nodes-base.code',
+            version: 2,
+            config: {
+                id: 'assert-' + id,
+                name: 'Assert ' + id,
+                position: [720 + index * 480, 300],
+                parameters: {
+                    mode: 'runOnceForAllItems',
+                    jsCode: assertionCode(expectedBody, requiredFields),
+                },
+            },
+        });
+        built = built.to(assert);
+    });
+    const validation = validateWorkflow(built);
+    if (!validation.valid)
+        throw new Error('n8n SDK validation failed: ' +
+            validation.errors.map((error) => error.message).join('; '));
+    return built.toJSON();
+}

package/dist/legacy/workflow/request/compile-catalog-sequence.d.ts

@@ -0,0 +1,2 @@
+import type { CatalogSequenceRequest, CatalogSequenceResult } from './../../../types/legacy/catalog-workflow.js';
+export declare function compileCatalogSequence({ sources, profile, plan, }: CatalogSequenceRequest): Promise<CatalogSequenceResult>;

package/dist/legacy/workflow/request/compile-catalog-sequence.js

@@ -0,0 +1,122 @@
+import { createOperationCatalog } from '@openapi-flow/core/internal';
+import { operationFromDocument } from '@openapi-flow/core/internal';
+import { isObject } from '@openapi-flow/core/internal';
+import { assertSerializablePlan } from '../common/plan-validation.js';
+import { originFrom } from './base-url.js';
+import { isSafeMethod } from './effect-policy.js';
+import { buildSequenceWorkflow } from './build-sequence-workflow.js';
+import { prepareSteps } from './prepare-sequence.js';
+export async function compileCatalogSequence({ sources, profile, plan, }) {
+    if (profile !== 'read-only' && profile !== 'test')
+        throw new Error('profile must be read-only or test');
+    if (!isObject(plan) ||
+        plan.version !== '1' ||
+        typeof plan.goal !== 'string' ||
+        !plan.goal.trim() ||
+        !Array.isArray(plan.steps) ||
+        (plan.gaps !== undefined && !Array.isArray(plan.gaps)) ||
+        (plan.steps.length === 0 && (!plan.gaps || plan.gaps.length === 0)))
+        throw new Error('plan must contain version 1, goal, steps or gaps');
+    assertSerializablePlan(plan);
+    const catalog = await createOperationCatalog(sources);
+    const gaps = plan.gaps ?? [];
+    for (const gap of gaps) {
+        if (!isObject(gap) ||
+            (gap.kind !== 'missing_operation' &&
+                gap.kind !== 'insufficient_contract') ||
+            typeof gap.description !== 'string' ||
+            !gap.description.trim())
+            throw new Error('plan.gaps[] must contain kind and non-empty description');
+        if (gap.kind === 'missing_operation' &&
+            (gap.documentId !== undefined || gap.operationRef !== undefined))
+            throw new Error('plan.gaps[] missing_operation must not identify an operation');
+        if (gap.kind === 'insufficient_contract') {
+            if (typeof gap.documentId !== 'string' ||
+                typeof gap.operationRef !== 'string')
+                throw new Error('plan.gaps[] insufficient_contract needs documentId and operationRef');
+            const source = catalog.sources.get(gap.documentId);
+            if (!source ||
+                !source.operations.some((operation) => operation.operationRef === gap.operationRef))
+                throw new Error('plan.gaps[] insufficient_contract operation is not in sources');
+        }
+    }
+    const stepById = new Map();
+    for (const step of plan.steps) {
+        if (!isObject(step) ||
+            typeof step.documentId !== 'string' ||
+            !step.documentId.trim())
+            throw new Error('plan.steps[].documentId must be non-empty');
+        if (typeof step.id !== 'string' || !step.id.trim() || stepById.has(step.id))
+            throw new Error('plan.steps must have unique non-empty id values');
+        stepById.set(step.id, step.documentId);
+    }
+    const prepared = prepareSteps({
+        profile,
+        plan,
+        resolveStep: (step) => {
+            const documentId = stepById.get(step.id);
+            const source = documentId === undefined ? undefined : catalog.sources.get(documentId);
+            if (!source)
+                throw new Error(`plan.steps[${step.id}].documentId is not in sources: ${documentId}`);
+            const target = sources.find((item) => item.id === source.id);
+            if (!target)
+                throw new Error(`sources[${source.id}] execution configuration is missing`);
+            return {
+                operation: operationFromDocument(source.document, step.operationRef),
+                origin: originFrom(target.baseUrl),
+                effectPolicy: target.effectPolicy,
+                credentialBindings: target.credentialBindings,
+            };
+        },
+    });
+    const evidence = prepared.evidence.map((entry) => ({
+        ...entry,
+        documentId: stepById.get(entry.stepId),
+    }));
+    const diagnostics = [
+        ...gaps.map((gap) => ({
+            code: gap.kind,
+            message: gap.description,
+            ...(gap.documentId === undefined ? {} : { documentId: gap.documentId }),
+            ...(gap.operationRef === undefined
+                ? {}
+                : { operationRef: gap.operationRef }),
+        })),
+        ...prepared.missingInputs.map((missing) => ({
+            code: 'missing_input',
+            message: missing,
+            stepId: missing.split('.')[0],
+        })),
+        ...evidence
+            .filter((entry) => entry.effect === 'unknown' ||
+            (!isSafeMethod(entry.method) && entry.effect !== 'write') ||
+            (profile === 'read-only' &&
+                (!isSafeMethod(entry.method) || entry.effect !== 'read')))
+            .map((entry) => ({
+            code: 'effect_not_approved',
+            message: `step ${entry.stepId} requires an approved effect`,
+            stepId: entry.stepId,
+        })),
+    ];
+    const status = gaps.length
+        ? 'needs_capability'
+        : prepared.blocked
+            ? 'blocked'
+            : prepared.missingInputs.length
+                ? 'needs_input'
+                : 'complete';
+    if (status !== 'complete')
+        return { status, plan, evidence, diagnostics };
+    return {
+        status,
+        plan,
+        evidence,
+        diagnostics,
+        workflow: buildSequenceWorkflow({
+            baseUrl: JSON.stringify(sources.map(({ id, baseUrl }) => ({ id, baseUrl }))),
+            plan,
+            nodes: prepared.nodes,
+            requiredOutputs: prepared.requiredOutputs,
+        }),
+    };
+}

package/dist/legacy/workflow/request/compile-sequence.d.ts

@@ -0,0 +1,2 @@
+import type { SequenceRequest, SequenceResult } from '../../../types/legacy/sequence-workflow.js';
+export declare function compileSequence({ spec, baseUrl, profile, effectPolicy, credentialBindings, plan, }: SequenceRequest): Promise<SequenceResult>;