@openapi-flow/n8n 0.3.7 → 0.3.8

package/README.md

@@ -2,7 +2,9 @@
 
 Zod `^4.6.5` is a required host peer for the public configuration schemas. It is not an independently pinned runtime dependency. The n8n SDK's internal Zod 3 remains separately owned; this does not pass a Zod 4 instance into an API requiring Zod 3.
 
-Version **0.3.5**, with matching `@openapi-flow/core@0.3.5`. There is no n8n implementation change in this patch. Known limitation: Ajv 8.20.0 ignores a declared `properties.__proto__`. Generated validation can reject valid data or omit that property's constraints; do not rely on it for contracts using that key. The previously accepted limitation and original failing regression remain unchanged. No field substitution or schema compatibility transform is included. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.5.md) for publication and host status.
+Version **0.3.8**, with matching `@openapi-flow/core@0.3.8`. This patch adds named composition of unchanged API responses through the registered `ComposeApiResponses` capability. Known limitation: Ajv 8.20.0 ignores a declared `properties.__proto__`. Generated validation can reject valid data or omit that property's constraints; do not rely on it for contracts using that key. The previously accepted limitation and original failing regression remain unchanged. No field substitution or schema compatibility transform is included. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.8.md) for publication and host status.
+
+`createApiResponseObjectCapability({ materials })` / `N8nNativeFeature.ComposeApiResponses` register `compose-api-responses`. The model selects only `fields: [{ name, sourceNodeId, pointer }]`. Code derives value schemas from original OAS contracts, validates full responses and derives join inputs from distinct sources in first-field occurrence order. The compiler reuses official SDK Merge Append and Edit Fields (Set); one source needs no Merge. Literal names, nulls, scalar types and nested values are preserved. Duplicate names, absent pointers, undeclared bodies and ambiguous source item counts fail without defaults or coercion. This is one response item per API invocation, not a native-output projection or per-item batch join. See [the source guide](https://github.com/carefreelife98/openapi-flow#named-api-response-objects-038).
 
 `describeN8nManualTrigger()` describes the Manual Trigger already supplied by this compiler. Pass that descriptor as `entrypoint` to native and connection planning so a model sees the actual compiler contract without selecting an extra trigger. The descriptor is not a data producer or a substitute for graph validation.
 
@@ -18,7 +20,7 @@ materializer check presence separately from the unchanged OAS, including missing
 optional descendants of a response-bound object. Strict HTTP node creation also
 rejects missing requested literals. See [requested inputs](../../docs/workflow-draft-api-binding-questions.md#값이-미정인-선택-입력의-요청-추적).
 
-`resolveN8nNativePlanningFeatures` separates selectable implementation definitions from material readiness. Four source-dependent families can be selected before producers exist, then bind the original contracts through existing snapshots and SDK compilation. No guessed source schema or runtime name is used. See [planning and host integration](../../docs/native-feature-planning.md).
+`resolveN8nNativePlanningFeatures` separates selectable implementation definitions from material readiness. Five source-dependent families can be selected before producers exist, then bind the original contracts through existing snapshots and SDK compilation. No guessed source schema or runtime name is used. See [planning and host integration](../../docs/native-feature-planning.md).
 
 material-dependent array/collection/item-join compilation rebinds current data contracts and resolves runtime names from actual SDK producer exits. `createN8nNativeOutputSources` requires actual `apiResponseContracts` for referenced APIs; partial subsets can declare external native outputs explicitly. Template requests accept `itemMode: 'linked'` for ancestry-preserving item streams. No old-contract/name fallback is used; custom compiler extensions must retain a coherent material binder. See [material snapshots and runtime proof](../../docs/native-material-snapshots.md).
 
@@ -28,9 +30,9 @@ Standalone strict, reviewable and finite-batch compilation also accepts explicit
 
 `describeN8nManualTrigger()` exposes the compiler-owned start contract for requirement planning. Its description and actual SDK trigger creation share one module, so hosts can declare the existing start separately from selectable native instances. It is explicit planning metadata, not a registry default, deployment check or extra trigger node.
 
-`resolveN8nNativeFeatures` and `N8nNativeFeature` expose one registry for eleven existing feature families. Omission inventories every family with explicit `ready`/`requires-context` status; an explicit enum list is strict and `[]` selects none. Ready capabilities retain the existing schemas, source declarations and SDK compilers. Material-dependent families require actual OAS/native contracts, not invented placeholders. The published four-feature factory keeps its original selection. See the [registration and extension contract](../../docs/native-feature-registry.md).
+`resolveN8nNativeFeatures` and `N8nNativeFeature` expose one registry for twelve existing feature families. Omission inventories every family with explicit `ready`/`requires-context` status; an explicit enum list is strict and `[]` selects none. Ready capabilities retain the existing schemas, source declarations and SDK compilers. Material-dependent families require actual OAS/native contracts, not invented placeholders. The published four-feature factory keeps its original selection. See the [registration and extension contract](../../docs/native-feature-registry.md).
 
-Deterministic OpenAPI request-node creation and explicit n8n DAG assembly with the official workflow SDK. Version `0.3.3` depends on matching core `0.3.3`.
+Deterministic OpenAPI request-node creation and explicit n8n DAG assembly with the official workflow SDK. Version `0.3.8` depends on matching core `0.3.8`.
 
 ## Installed declaration dependencies
 

package/dist/nodes/native/objects/api-response-object-definition.d.ts

@@ -0,0 +1,2 @@
+import type { NativeMaterialFeatureDefinition } from '../../../types/native-material-binding.js';
+export declare const apiResponseObjectDefinition: NativeMaterialFeatureDefinition;

package/dist/nodes/native/objects/api-response-object-definition.js

@@ -0,0 +1,28 @@
+import { apiResponseObjectParametersSchema } from '../../../schemas/api-response-object-schema.js';
+export const apiResponseObjectDefinition = {
+    name: 'compose-api-responses',
+    description: 'Wait for all referenced API branches and compose explicitly named properties into one JSON object from unchanged whole response bodies or RFC 6901 values. Code derives all value types and input ports from actual references, validates full OAS responses and compiles official Merge plus Edit Fields (Set). Input1..inputN correspond to distinct sourceNodeIds in first-field occurrence order. Connect each API branch to its matching input; do not add a separate branch join for this operation. Requires exactly one item per referenced API execution. No casting, flattening or inferred matching. Repeated fields may read the same source under different names without adding an input.',
+    materialRequirements: [{ field: 'apiMaterials', minimumItems: 1 }],
+    parametersSchema: apiResponseObjectParametersSchema,
+    parameterReferenceSources: ['response'],
+    referenceStructureSchema: apiResponseObjectParametersSchema,
+    parameterReferenceBindings: (value) => apiResponseObjectParametersSchema
+        .parse(value)
+        .fields.map((field, index) => ({
+        nodeIdPointer: `/fields/${index}/sourceNodeId`,
+        valuePointer: `/fields/${index}/pointer`,
+        reference: {
+            source: 'response',
+            nodeId: field.sourceNodeId,
+            pointer: field.pointer,
+        },
+    })),
+    inputPorts: (value) => [
+        ...new Set(apiResponseObjectParametersSchema
+            .parse(value)
+            .fields.map((field) => field.sourceNodeId)),
+    ].map((_, index) => `input${index + 1}`),
+    outputPorts: () => ['main'],
+    waitsForAllInputs: true,
+    exclusiveOutputPorts: false,
+};

package/dist/nodes/native/objects/compile-api-response-object.d.ts

@@ -0,0 +1,3 @@
+import type { CompileApiResponseObjectInput } from '../../../types/api-response-object.js';
+import type { N8nNodeFragment } from '../../../types/node-fragment.js';
+export declare function compileApiResponseObject(input: CompileApiResponseObjectInput): N8nNodeFragment;

package/dist/nodes/native/objects/compile-api-response-object.js

@@ -0,0 +1,86 @@
+import { node } from '@n8n/workflow-sdk';
+import { readFileSync } from 'node:fs';
+import { createOutputReaderCode } from '../../request/bindings/create-output-reader-code.js';
+import { javascriptJsonLiteral } from '../../../utils/javascript-json-literal.js';
+import { createMergeAppendCapability } from '../merge-append-capability.js';
+import { apiResponseObjectDefinition } from './api-response-object-definition.js';
+export function compileApiResponseObject(input) {
+    const { planned, parameters, position } = input;
+    const sources = input.materials.map((material) => {
+        const nodeName = input.apiNodeNames[material.callId];
+        if (!Object.hasOwn(input.apiNodeNames, material.callId) ||
+            !nodeName?.trim())
+            throw new Error(`apiNodeNames is missing ${material.callId}`);
+        return {
+            kind: 'api-response',
+            nodeId: material.callId,
+            nodeName,
+            operation: material.operation,
+        };
+    });
+    const runtime = readFileSync(new URL('../../request/runtime/request-runtime.bundle.js', import.meta.url), 'utf8');
+    const reader = createOutputReaderCode(sources);
+    const join = sources.length > 1
+        ? createMergeAppendCapability().compile({
+            ...input,
+            planned: {
+                id: `${planned.id}-join-responses`,
+                capability: 'merge-append',
+                parameters: { numberInputs: sources.length },
+            },
+        })
+        : undefined;
+    const readPosition = [
+        position[0] + (join === undefined ? 0 : 220),
+        position[1],
+    ];
+    const extract = node({
+        type: 'n8n-nodes-base.code',
+        version: 2,
+        config: {
+            id: `${planned.id}-read-object-values`,
+            name: `Read object values ${planned.id}`,
+            position: readPosition,
+            parameters: {
+                mode: 'runOnceForAllItems',
+                language: 'javaScript',
+                jsCode: `${runtime}\n${reader}\nconst parameters=${javascriptJsonLiteral(parameters)};\nconst entries=parameters.fields.map(field=>{const value=OpenApiFlowRequestRuntime.pointerValue(responses[field.sourceNodeId],field.pointer);if(value===undefined)throw new Error('Missing response pointer '+field.sourceNodeId+field.pointer);return [field.name,value];});\nreturn [{json:Object.fromEntries(entries),pairedItem:$input.all().map((_,item)=>({item}))}];`,
+            },
+        },
+    });
+    const output = node({
+        type: 'n8n-nodes-base.set',
+        version: 3.4,
+        config: {
+            id: planned.id,
+            name: planned.id,
+            position: [readPosition[0] + 220, readPosition[1]],
+            parameters: {
+                mode: 'raw',
+                jsonOutput: '={{ JSON.stringify($json) }}',
+                includeOtherFields: false,
+                options: { dotNotation: false },
+            },
+        },
+    });
+    return {
+        nodeId: planned.id,
+        nodes: [...(join === undefined ? [] : join.nodes), extract, output],
+        entry: join === undefined ? extract : join.entry,
+        exit: output,
+        inputPorts: Object.fromEntries(apiResponseObjectDefinition
+            .inputPorts(parameters)
+            .map((port, index) => [port, index])),
+        outputPorts: { main: 0 },
+        internalEdges: [
+            ...(join === undefined
+                ? []
+                : [
+                    ...(join.internalEdges === undefined ? [] : join.internalEdges),
+                    { from: join.exit.id, output: 0, to: extract.id, input: 0 },
+                ]),
+            { from: extract.id, output: 0, to: output.id, input: 0 },
+        ],
+        bindingSources: sources,
+    };
+}

package/dist/nodes/native/objects/create-api-response-object-capability.d.ts

@@ -0,0 +1,3 @@
+import type { N8nNativeCapability } from '../../../types/native-capability.js';
+import type { CreateApiResponseObjectCapabilityInput } from '../../../types/api-response-object.js';
+export declare function createApiResponseObjectCapability(input: CreateApiResponseObjectCapabilityInput): N8nNativeCapability;

package/dist/nodes/native/objects/create-api-response-object-capability.js

@@ -0,0 +1,60 @@
+import { createResponseValueSchema } from '@openapi-flow/core';
+import { createApiResponseObjectParametersSchema } from '../../../schemas/api-response-object-schema.js';
+import { defineMaterialBoundCapability } from '../common/define-material-bound-capability.js';
+import { apiResponseObjectDefinition } from './api-response-object-definition.js';
+import { compileApiResponseObject } from './compile-api-response-object.js';
+export function createApiResponseObjectCapability(input) {
+    const supplied = structuredClone(input.materials);
+    const materials = new Map(supplied.map((material) => [material.callId, material]));
+    if (!materials.size ||
+        materials.size !== supplied.length ||
+        supplied.some((material) => !material.callId.trim()))
+        throw new Error('response object capability requires unique API materials');
+    const parametersSchema = createApiResponseObjectParametersSchema([
+        ...materials.keys(),
+    ]);
+    function describeFields(parameters) {
+        return parameters.fields.map((field) => {
+            const material = materials.get(field.sourceNodeId);
+            if (!material)
+                throw new Error(`response object: unknown sourceNodeId ${field.sourceNodeId}`);
+            return {
+                field,
+                material,
+                schema: createResponseValueSchema(material.operation, field.pointer),
+            };
+        });
+    }
+    return defineMaterialBoundCapability({
+        ...apiResponseObjectDefinition,
+        parametersSchema,
+        materialSources: { apiMaterials: supplied, nativeOutputs: [] },
+        bindMaterialContracts: (sources) => createApiResponseObjectCapability({ materials: sources.apiMaterials }),
+        responseReferences: (value) => describeFields(parametersSchema.parse(value)).map(({ field }) => ({
+            source: 'response',
+            nodeId: field.sourceNodeId,
+            pointer: field.pointer,
+        })),
+        outputSchema: (value) => {
+            const fields = describeFields(parametersSchema.parse(value));
+            return {
+                type: 'object',
+                properties: Object.fromEntries(fields.map(({ field, schema }) => [field.name, schema])),
+                required: fields.map(({ field }) => field.name),
+                additionalProperties: false,
+            };
+        },
+        compile: (source) => {
+            const parameters = parametersSchema.parse(source.planned.parameters);
+            const fields = describeFields(parameters);
+            const used = [
+                ...new Map(fields.map(({ material }) => [material.callId, material])).values(),
+            ];
+            return compileApiResponseObject({
+                ...source,
+                parameters,
+                materials: used,
+            });
+        },
+    });
+}

package/dist/nodes/native/registry/native-feature-definitions.js

@@ -14,6 +14,8 @@ import { createBoundItemJoinCapability } from '../item-join/create-bound-item-jo
 import { createMaterialPlanningCapability } from '../common/create-material-planning-capability.js';
 import { responseArrayDefinition } from '../response-array-definition.js';
 import { responseCollectionDefinition } from '../response-collection-definition.js';
+import { apiResponseObjectDefinition } from '../objects/api-response-object-definition.js';
+import { createApiResponseObjectCapability } from '../objects/create-api-response-object-capability.js';
 import { nativeArrayDefinition } from '../arrays/native-array-definition.js';
 import { itemJoinDefinition } from '../item-join/item-join-definition.js';
 import { nativeFeatureMaterialRequirements } from './native-feature-material-requirements.js';
@@ -66,6 +68,11 @@ export const nativeFeatureDefinitions = {
         })),
         create: (context) => createResponseCollectionCapability({ materials: context.apiMaterials }),
     },
+    [N8nNativeFeature.ComposeApiResponses]: {
+        requirements: nativeFeatureMaterialRequirements(apiResponseObjectDefinition),
+        createPlanning: () => createMaterialPlanningCapability(apiResponseObjectDefinition, (sources) => createApiResponseObjectCapability({ materials: sources.apiMaterials })),
+        create: (context) => createApiResponseObjectCapability({ materials: context.apiMaterials }),
+    },
     [N8nNativeFeature.SplitNativeOutputArray]: {
         requirements: nativeFeatureMaterialRequirements(nativeArrayDefinition),
         createPlanning: (context) => createMaterialPlanningCapability(nativeArrayDefinition, (sources) => createBoundNativeArrayCapability({

package/dist/public-api.d.ts

@@ -33,6 +33,8 @@ export { createNativeArrayCapability } from './nodes/native/arrays/create-native
 export type * from './types/native-array.js';
 export { createResponseCollectionCapability } from './nodes/native/create-response-collection-capability.js';
 export type * from './types/response-collection.js';
+export { createApiResponseObjectCapability } from './nodes/native/objects/create-api-response-object-capability.js';
+export type * from './types/api-response-object.js';
 export { createItemJoinCapability } from './nodes/native/item-join/create-item-join-capability.js';
 export type * from './types/item-join.js';
 export { compileBatchedN8nWorkflow } from './workflow/batch/compile-batched-n8n-workflow.js';

package/dist/public-api.js

@@ -19,6 +19,7 @@ export { resolveHttpRequestAuthentication } from './nodes/request/authentication
 export { createResponseArrayCapability } from './nodes/native/create-response-array-capability.js';
 export { createNativeArrayCapability } from './nodes/native/arrays/create-native-array-capability.js';
 export { createResponseCollectionCapability } from './nodes/native/create-response-collection-capability.js';
+export { createApiResponseObjectCapability } from './nodes/native/objects/create-api-response-object-capability.js';
 export { createItemJoinCapability } from './nodes/native/item-join/create-item-join-capability.js';
 export { compileBatchedN8nWorkflow } from './workflow/batch/compile-batched-n8n-workflow.js';
 export { describeN8nManualTrigger } from './workflow/entrypoint/manual-trigger.js';

package/dist/schemas/api-response-object-schema.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const apiResponseObjectParametersSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        sourceNodeId: z.ZodString;
+        pointer: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare function createApiResponseObjectParametersSchema(callIds: string[]): z.ZodObject<{
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        pointer: z.ZodString;
+        sourceNodeId: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/schemas/api-response-object-schema.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+const apiResponseObjectFieldSchema = z.strictObject({
+    name: z
+        .string()
+        .describe('Literal output property name; dots are not nesting instructions.'),
+    sourceNodeId: z
+        .string()
+        .min(1)
+        .describe('An existing selected API callId, never an operation name or invented producer.'),
+    pointer: z
+        .string()
+        .regex(/^(?:\/(?:[^~]|~[01])*)*$/u)
+        .describe('RFC 6901 pointer into the unchanged API response body; empty string selects the whole body.'),
+});
+export const apiResponseObjectParametersSchema = z
+    .strictObject({
+    fields: z
+        .array(apiResponseObjectFieldSchema)
+        .min(1)
+        .describe('Explicit named output fields. Each value is copied unchanged from the declared OAS response. No formatting, casting, merging, calculations or inferred matching.'),
+})
+    .superRefine((value, context) => {
+    const names = new Set();
+    value.fields.forEach((field, index) => {
+        if (names.has(field.name))
+            context.addIssue({
+                code: 'custom',
+                path: ['fields', index, 'name'],
+                message: 'Output property names must be unique',
+            });
+        names.add(field.name);
+    });
+});
+export function createApiResponseObjectParametersSchema(callIds) {
+    if (!callIds.length)
+        throw new Error('response object parameters require API callIds');
+    return apiResponseObjectParametersSchema.safeExtend({
+        fields: z
+            .array(apiResponseObjectFieldSchema.extend({
+            sourceNodeId: z
+                .enum(callIds)
+                .describe('Only a supplied API callId. Code derives the output schema from this source contract.'),
+        }))
+            .min(1),
+    });
+}

package/dist/schemas/native-feature-registry-schema.d.ts

@@ -9,6 +9,7 @@ export declare const n8nNativeFeatureSelectionSchema: z.ZodArray<z.ZodEnum<Reado
     readonly JsonOutput: "json-output";
     readonly SplitApiResponseArray: "split-api-response-array";
     readonly CollectApiResponses: "collect-api-responses";
+    readonly ComposeApiResponses: "compose-api-responses";
     readonly SplitNativeOutputArray: "split-native-output-array";
     readonly JoinApiItems: "join-api-items";
 }>>>;

package/dist/types/api-response-object.d.ts

@@ -0,0 +1,12 @@
+import type { z } from 'zod';
+import type { ApiBindingMaterial } from '@openapi-flow/core';
+import type { apiResponseObjectParametersSchema } from '../schemas/api-response-object-schema.js';
+import type { CompileNativeNodeInput } from './native-capability.js';
+export type ApiResponseObjectParameters = z.infer<typeof apiResponseObjectParametersSchema>;
+export interface CreateApiResponseObjectCapabilityInput {
+    materials: ApiBindingMaterial[];
+}
+export interface CompileApiResponseObjectInput extends CompileNativeNodeInput {
+    parameters: ApiResponseObjectParameters;
+    materials: ApiBindingMaterial[];
+}

package/dist/types/api-response-object.js

@@ -0,0 +1 @@
+export {};

package/dist/types/native-feature-registry.d.ts

@@ -12,6 +12,7 @@ export declare const N8nNativeFeature: Readonly<{
     readonly JsonOutput: "json-output";
     readonly SplitApiResponseArray: "split-api-response-array";
     readonly CollectApiResponses: "collect-api-responses";
+    readonly ComposeApiResponses: "compose-api-responses";
     readonly SplitNativeOutputArray: "split-native-output-array";
     readonly JoinApiItems: "join-api-items";
 }>;

package/dist/types/native-feature-registry.js

@@ -9,6 +9,7 @@ export const N8nNativeFeature = Object.freeze({
     JsonOutput: 'json-output',
     SplitApiResponseArray: 'split-api-response-array',
     CollectApiResponses: 'collect-api-responses',
+    ComposeApiResponses: 'compose-api-responses',
     SplitNativeOutputArray: 'split-native-output-array',
     JoinApiItems: 'join-api-items',
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-flow/n8n",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "license": "MIT",
   "type": "module",
   "description": "Deterministic OpenAPI request nodes and n8n workflow assembly",
@@ -30,7 +30,7 @@
   "dependencies": {
     "@n8n/config": "2.41.2",
     "@n8n/workflow-sdk": "0.36.4",
-    "@openapi-flow/core": "0.3.7",
+    "@openapi-flow/core": "0.3.8",
     "@sentry/node": "10.70.0",
     "@types/estree": "1.0.8",
     "@types/express": "5.0.1",