@openapi-flow/core 0.1.0

package/dist/types/openapi.d.ts

@@ -0,0 +1,49 @@
+export type JsonObject = Record<string, unknown>;
+export type Scalar = string | number | boolean;
+export type OperationMethod = string;
+export interface OperationEntry {
+    method: string;
+    key: string;
+    value: unknown;
+}
+export interface ScalarSchema {
+    type: string;
+    enum?: Scalar[];
+}
+export type ScalarProperties = Record<string, ScalarSchema>;
+export interface OperationParameter {
+    name: string;
+    in: 'path' | 'query';
+    required: boolean;
+    schema: ScalarSchema;
+}
+export interface OperationBody {
+    required: boolean;
+    requiredProperties: string[];
+    properties: ScalarProperties;
+}
+export interface OperationMetadata {
+    operationId?: string;
+    summary: string;
+    description: string;
+    tags: string[];
+}
+export interface Operation extends OperationMetadata {
+    operationRef: string;
+    method: OperationMethod;
+    path: string;
+    effect: 'read' | 'write' | 'unknown';
+    status: number;
+    parameters: OperationParameter[];
+    body?: OperationBody;
+    responseProperties: ScalarProperties;
+}
+export type OperationCandidate = Pick<Operation, 'operationRef' | 'operationId' | 'method' | 'path' | 'summary' | 'description' | 'tags'>;
+export interface ObjectSchemaProperties {
+    properties: JsonObject;
+    required: string[];
+}
+export interface ParsedDocument {
+    spec: JsonObject;
+    paths: JsonObject;
+}

package/dist/types/openapi.js

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

package/dist/types/workflow.d.ts

@@ -0,0 +1,75 @@
+import type { WorkflowJSON } from '@n8n/workflow-sdk';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { Operation, Scalar } from './openapi.js';
+export type Primitive = Scalar;
+export type ExpectedBody = Record<string, Primitive>;
+export type WorkflowInputs = Record<string, Primitive | ExpectedBody>;
+export type InputValues = Record<string, unknown>;
+export type RequiredFields = Record<string, string>;
+export type PreviousOperations = Map<string, Operation>;
+export type RequiredOutputs = Map<string, Set<string>>;
+export type CompileStatus = 'complete' | 'needs_input' | 'blocked';
+export type OperationEvidence = Pick<Operation, 'operationRef' | 'operationId' | 'method' | 'path' | 'status' | 'effect'>;
+export interface WorkflowPlan {
+    version: '1';
+    goal: string;
+    operationRef: string;
+    inputs?: WorkflowInputs;
+    expectedBody?: ExpectedBody;
+}
+export interface CompileRequest {
+    spec: unknown;
+    baseUrl: string;
+    profile: 'read-only' | 'test';
+    plan: WorkflowPlan;
+}
+export type CompileOperationRequest = Pick<CompileRequest, 'baseUrl' | 'profile' | 'plan'>;
+export interface CompileResult {
+    status: CompileStatus;
+    plan: WorkflowPlan;
+    evidence: OperationEvidence;
+    missingInputs: string[];
+    workflow?: WorkflowJSON;
+}
+export interface ResponseReference {
+    fromStep: string;
+    field: string;
+}
+export interface SequenceStep {
+    id: string;
+    operationRef: string;
+    inputs?: Record<string, Primitive | ResponseReference | ExpectedBody>;
+    expectedBody?: ExpectedBody;
+}
+export interface SequencePlan {
+    version: '1';
+    goal: string;
+    steps: SequenceStep[];
+}
+export interface SequenceRequest {
+    spec: unknown;
+    baseUrl: string;
+    profile: CompileRequest['profile'];
+    plan: SequencePlan;
+}
+export interface SequenceEvidence extends OperationEvidence {
+    stepId: string;
+}
+export interface SequenceResult {
+    status: CompileStatus;
+    plan: SequencePlan;
+    evidence: SequenceEvidence[];
+    missingInputs: string[];
+    workflow?: WorkflowJSON;
+}
+export interface PreparedSequenceNode {
+    operation: Operation;
+    id: string;
+    url: string;
+    body?: string;
+    expectedBody: ExpectedBody;
+}
+export interface GenerateRequest extends Omit<CompileRequest, 'plan'> {
+    scenario: string;
+    model: BaseChatModel;
+}

package/dist/types/workflow.js

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

package/dist/utils/validation.d.ts

@@ -0,0 +1,7 @@
+import type { JsonObject, ScalarSchema } from '../types/openapi.js';
+import type { Primitive } from '../types/workflow.js';
+export declare function isObject(value: unknown): value is JsonObject;
+export declare function looksLikeCredential(name: string): boolean;
+export declare function checkPrimitive(value: unknown, schema: ScalarSchema, source: string): asserts value is Primitive;
+export declare function originFrom(baseUrl: string): URL;
+export declare function checkPlanSize(plan: unknown): void;

package/dist/utils/validation.js

@@ -0,0 +1,44 @@
+export function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function looksLikeCredential(name) {
+    return /(token|secret|password|authorization|api.?key)/i.test(name);
+}
+export function checkPrimitive(value, schema, source) {
+    if (schema.type === 'integer'
+        ? !Number.isSafeInteger(value)
+        : schema.type === 'number'
+            ? typeof value !== 'number' || !Number.isFinite(value)
+            : typeof value !== schema.type) {
+        throw new Error(source + ' must be ' + schema.type);
+    }
+    if (schema.enum && !schema.enum.includes(value))
+        throw new Error(source + ' is outside the OAS enum');
+}
+export function originFrom(baseUrl) {
+    if (typeof baseUrl !== 'string' || !URL.canParse(baseUrl)) {
+        throw new Error('baseUrl must be an absolute HTTP(S) origin');
+    }
+    const url = new URL(baseUrl);
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.pathname !== '/' ||
+        url.search ||
+        url.hash) {
+        throw new Error('baseUrl must be an HTTP(S) origin without credentials, path, query, or fragment');
+    }
+    return url;
+}
+export function checkPlanSize(plan) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(plan);
+    }
+    catch {
+        throw new Error('plan must be JSON-serializable');
+    }
+    if (!serialized || Buffer.byteLength(serialized) > 100_000) {
+        throw new Error('plan must be a JSON document under 100 KB');
+    }
+}

package/dist/utils/workflow-id.d.ts

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

package/dist/utils/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/workflow/compile-sequence.d.ts

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

package/dist/workflow/compile-sequence.js

@@ -0,0 +1,167 @@
+import { node, trigger, validateWorkflow, workflow } from '@n8n/workflow-sdk';
+import { operationFromDocument } from '../openapi/parse-spec.js';
+import { validatedDocument } from '../openapi/validate-spec.js';
+import { checkPlanSize, checkPrimitive, isObject, looksLikeCredential, originFrom, } from '../utils/validation.js';
+import { workflowId } from '../utils/workflow-id.js';
+import { assertionCode, isSafeMethod, makeBody } from './workflow-helpers.js';
+import { sequenceUrl } from './sequence-url.js';
+export async function compileSequence({ spec, baseUrl, profile, plan, }) {
+    const origin = originFrom(baseUrl);
+    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() ||
+        plan.goal.length > 2_000 ||
+        !Array.isArray(plan.steps) ||
+        plan.steps.length < 1 ||
+        plan.steps.length > 5) {
+        throw new Error('plan must contain version 1, goal, and 1–5 steps');
+    }
+    checkPlanSize(plan);
+    const document = await validatedDocument(spec);
+    const previous = new Map();
+    const requiredOutputs = new Map();
+    const evidence = [];
+    const missingInputs = [];
+    const nodes = [];
+    let blocked = false;
+    for (const step of plan.steps) {
+        if (!isObject(step) ||
+            typeof step.id !== 'string' ||
+            !/^[A-Za-z][A-Za-z0-9_-]*$/.test(step.id) ||
+            previous.has(step.id) ||
+            typeof step.operationRef !== 'string') {
+            throw new Error('plan.steps must have unique id and operationRef values');
+        }
+        const operation = operationFromDocument(document, step.operationRef);
+        const inputs = step.inputs === undefined ? {} : step.inputs;
+        const expectedBody = step.expectedBody === undefined ? {} : step.expectedBody;
+        if (!isObject(inputs) || !isObject(expectedBody)) {
+            throw new Error('plan.steps[' + step.id + '] inputs and expectedBody must be objects');
+        }
+        for (const [key, value] of Object.entries(expectedBody)) {
+            if (looksLikeCredential(key)) {
+                throw new Error('plan.steps[' +
+                    step.id +
+                    '].expectedBody.' +
+                    key +
+                    ' looks like a credential');
+            }
+            if (!Object.hasOwn(operation.responseProperties, key)) {
+                throw new Error('plan.steps[' +
+                    step.id +
+                    '].expectedBody.' +
+                    key +
+                    ' is not in the OAS response schema');
+            }
+            checkPrimitive(value, operation.responseProperties[key], 'plan.steps[' + step.id + '].expectedBody.' + key);
+        }
+        const allowed = new Set(operation.parameters.map((parameter) => parameter.in + '.' + parameter.name));
+        if (operation.body)
+            allowed.add('body');
+        for (const key of Object.keys(inputs)) {
+            if (!allowed.has(key))
+                throw new Error('plan.steps[' +
+                    step.id +
+                    '].inputs.' +
+                    key +
+                    ' is not declared in OAS');
+            if (looksLikeCredential(key)) {
+                throw new Error('plan.steps[' +
+                    step.id +
+                    '].inputs.' +
+                    key +
+                    ' looks like a credential');
+            }
+        }
+        const stepMissing = [];
+        const url = sequenceUrl(operation, origin, inputs, previous, requiredOutputs, stepMissing);
+        const body = makeBody(operation, inputs, stepMissing);
+        missingInputs.push(...stepMissing.map((key) => step.id + '.' + key));
+        if (operation.effect === 'unknown' ||
+            (!isSafeMethod(operation.method) && operation.effect !== 'write') ||
+            (profile === 'read-only' &&
+                (!isSafeMethod(operation.method) || operation.effect !== 'read')))
+            blocked = true;
+        evidence.push({
+            stepId: step.id,
+            operationRef: operation.operationRef,
+            operationId: operation.operationId,
+            method: operation.method,
+            path: operation.path,
+            status: operation.status,
+            effect: operation.effect,
+        });
+        nodes.push({
+            operation,
+            id: step.id,
+            url,
+            body,
+            expectedBody: expectedBody,
+        });
+        previous.set(step.id, operation);
+    }
+    if (blocked)
+        return { status: 'blocked', plan, evidence, missingInputs };
+    if (missingInputs.length)
+        return { status: 'needs_input', plan, evidence, missingInputs };
+    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, expectedBody }, index) => {
+        const requiredFields = {};
+        for (const field of requiredOutputs.get(id) ?? []) {
+            requiredFields[field] = operation.responseProperties[field].type;
+        }
+        const request = node({
+            type: 'n8n-nodes-base.httpRequest',
+            version: 4.3,
+            config: {
+                id: 'request-' + id,
+                name: 'Request ' + id,
+                position: [480 + index * 480, 300],
+                parameters: {
+                    method: operation.method,
+                    url,
+                    ...(body === undefined
+                        ? {}
+                        : { sendBody: true, specifyBody: 'json', jsonBody: body }),
+                    options: {
+                        response: {
+                            response: { fullResponse: true, responseFormat: 'json' },
+                        },
+                    },
+                },
+            },
+        });
+        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(operation.status, expectedBody, requiredFields),
+                },
+            },
+        });
+        built = built.to(request).to(assert);
+    });
+    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,
+        missingInputs,
+        workflow: built.toJSON(),
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { Operation } from '../types/openapi.js';
+import type { CompileOperationRequest, CompileRequest, CompileResult } from '../types/workflow.js';
+export declare function compileWorkflow(request: CompileRequest): Promise<CompileResult>;
+export declare function compileWorkflowFromOperation({ baseUrl, profile, plan }: CompileOperationRequest, operation: Operation): CompileResult;

package/dist/workflow/compile-workflow.js

@@ -0,0 +1,128 @@
+import { node, trigger, validateWorkflow, workflow } from '@n8n/workflow-sdk';
+import { operationFromSpec } from '../openapi/parse-spec.js';
+import { checkPlanSize, isObject, looksLikeCredential, originFrom, checkPrimitive, } from '../utils/validation.js';
+import { workflowId } from '../utils/workflow-id.js';
+import { assertionCode, isSafeMethod, makeBody, makeUrl, } from './workflow-helpers.js';
+export async function compileWorkflow(request) {
+    if (!isObject(request.plan) ||
+        typeof request.plan.operationRef !== 'string') {
+        throw new Error('plan must contain version 1, goal, and operationRef');
+    }
+    const operation = await operationFromSpec(request.spec, request.plan.operationRef);
+    return compileWorkflowFromOperation(request, operation);
+}
+export function compileWorkflowFromOperation({ baseUrl, profile, plan }, operation) {
+    const origin = originFrom(baseUrl);
+    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() ||
+        plan.goal.length > 2_000 ||
+        typeof plan.operationRef !== 'string') {
+        throw new Error('plan must contain version 1, goal, and operationRef');
+    }
+    checkPlanSize(plan);
+    const evidence = {
+        operationRef: operation.operationRef,
+        operationId: operation.operationId,
+        method: operation.method,
+        path: operation.path,
+        status: operation.status,
+        effect: operation.effect,
+    };
+    const inputs = plan.inputs === undefined ? {} : plan.inputs;
+    if (!isObject(inputs))
+        throw new Error('plan.inputs must be an object');
+    const expectedBody = plan.expectedBody === undefined ? {} : plan.expectedBody;
+    if (!isObject(expectedBody))
+        throw new Error('plan.expectedBody must be an object');
+    for (const [key, value] of Object.entries(expectedBody)) {
+        if (looksLikeCredential(key)) {
+            throw new Error('plan.expectedBody.' + key + ' looks like a credential');
+        }
+        if (!Object.hasOwn(operation.responseProperties, key)) {
+            throw new Error('plan.expectedBody.' + key + ' is not in the OAS response schema');
+        }
+        checkPrimitive(value, operation.responseProperties[key], 'plan.expectedBody.' + key);
+    }
+    const allowed = new Set(operation.parameters.map((parameter) => parameter.in + '.' + parameter.name));
+    if (operation.body)
+        allowed.add('body');
+    for (const key of Object.keys(inputs)) {
+        if (!allowed.has(key))
+            throw new Error('plan.inputs.' + key + ' is not declared in the OAS operation');
+        if (looksLikeCredential(key)) {
+            throw new Error('plan.inputs.' +
+                key +
+                ' looks like a credential; v1 has no credential binding');
+        }
+    }
+    const missingInputs = [];
+    const url = makeUrl(operation, origin, inputs, missingInputs);
+    const body = makeBody(operation, inputs, missingInputs);
+    if (operation.effect === 'unknown' ||
+        (!isSafeMethod(operation.method) && operation.effect !== 'write') ||
+        (profile === 'read-only' &&
+            (!isSafeMethod(operation.method) || operation.effect !== 'read'))) {
+        return { status: 'blocked', plan, evidence, missingInputs };
+    }
+    if (missingInputs.length)
+        return { status: 'needs_input', plan, evidence, missingInputs };
+    const start = trigger({
+        type: 'n8n-nodes-base.manualTrigger',
+        version: 1,
+        config: { id: 'start', name: 'Start', position: [240, 300] },
+    });
+    const request = node({
+        type: 'n8n-nodes-base.httpRequest',
+        version: 4.3,
+        config: {
+            id: 'request',
+            name: operation.method + ' ' + operation.path,
+            position: [480, 300],
+            parameters: {
+                method: operation.method,
+                url,
+                ...(body === undefined
+                    ? {}
+                    : { sendBody: true, specifyBody: 'json', jsonBody: body }),
+                options: {
+                    response: {
+                        response: { fullResponse: true, responseFormat: 'json' },
+                    },
+                },
+            },
+        },
+    });
+    const assert = node({
+        type: 'n8n-nodes-base.code',
+        version: 2,
+        config: {
+            id: 'assert',
+            name: 'Assert response',
+            position: [720, 300],
+            parameters: {
+                mode: 'runOnceForAllItems',
+                jsCode: assertionCode(operation.status, expectedBody),
+            },
+        },
+    });
+    const built = workflow(workflowId(baseUrl, plan), 'OpenAPI ' + operation.method + ' ' + operation.path)
+        .add(start)
+        .to(request)
+        .to(assert);
+    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,
+        missingInputs,
+        workflow: built.toJSON(),
+    };
+}

package/dist/workflow/sequence-url.d.ts

@@ -0,0 +1,3 @@
+import type { Operation } from '../types/openapi.js';
+import type { InputValues, PreviousOperations, RequiredOutputs } from '../types/workflow.js';
+export declare function sequenceUrl(operation: Operation, origin: URL, inputs: InputValues, previous: PreviousOperations, requiredOutputs: RequiredOutputs, missing: string[]): string;

package/dist/workflow/sequence-url.js

@@ -0,0 +1,81 @@
+import { checkPrimitive, isObject, looksLikeCredential, } from '../utils/validation.js';
+import { makeUrl } from './workflow-helpers.js';
+export function sequenceUrl(operation, origin, inputs, previous, requiredOutputs, missing) {
+    let path = operation.path;
+    const references = new Map();
+    for (const parameter of operation.parameters) {
+        const key = parameter.in + '.' + parameter.name;
+        const value = inputs[key];
+        if (value === undefined) {
+            if (parameter.required)
+                missing.push(key);
+            continue;
+        }
+        if (isObject(value)) {
+            if (typeof value.fromStep !== 'string' ||
+                typeof value.field !== 'string' ||
+                Object.keys(value).length !== 2) {
+                throw new Error('plan.inputs.' + key + ' must have fromStep and field');
+            }
+            if (looksLikeCredential(value.field)) {
+                throw new Error('plan.inputs.' + key + ' references a credential-like response field');
+            }
+            const source = previous.get(value.fromStep);
+            if (!source || !Object.hasOwn(source.responseProperties, value.field)) {
+                throw new Error('plan.inputs.' + key + ' must reference a prior response field');
+            }
+            const sourceType = source.responseProperties[value.field].type;
+            if (sourceType !== parameter.schema.type &&
+                !(sourceType === 'integer' && parameter.schema.type === 'number')) {
+                throw new Error('plan.inputs.' + key + ' has a response type mismatch');
+            }
+            const required = requiredOutputs.get(value.fromStep) ?? new Set();
+            required.add(value.field);
+            requiredOutputs.set(value.fromStep, required);
+            references.set(key, '$node[' +
+                JSON.stringify('Request ' + value.fromStep) +
+                '].json.body[' +
+                JSON.stringify(value.field) +
+                ']');
+        }
+        else {
+            checkPrimitive(value, parameter.schema, 'plan.inputs.' + key);
+            if (parameter.in === 'path')
+                path = path.replace('{' + parameter.name + '}', encodeURIComponent(String(value)));
+        }
+    }
+    if (missing.length)
+        return '';
+    if (references.size === 0)
+        return makeUrl(operation, origin, inputs, []);
+    const absolute = origin.href.slice(0, -1) + path;
+    const parts = [];
+    let offset = 0;
+    for (const match of absolute.matchAll(/\{([A-Za-z][A-Za-z0-9_]*)\}/g)) {
+        const key = 'path.' + match[1];
+        const reference = references.get(key);
+        if (!reference)
+            throw new Error('plan.inputs.' + key + ' is required');
+        parts.push(JSON.stringify(absolute.slice(offset, match.index)), 'encodeURIComponent(' + reference + ')');
+        offset = match.index + match[0].length;
+    }
+    parts.push(JSON.stringify(absolute.slice(offset)));
+    let expression = parts.join(' + ');
+    let firstQuery = true;
+    for (const parameter of operation.parameters) {
+        if (parameter.in !== 'query' ||
+            inputs['query.' + parameter.name] === undefined)
+            continue;
+        const key = 'query.' + parameter.name;
+        const reference = references.get(key);
+        expression +=
+            ' + ' +
+                JSON.stringify((firstQuery ? '?' : '&') + encodeURIComponent(parameter.name) + '=') +
+                ' + ' +
+                (reference
+                    ? 'encodeURIComponent(' + reference + ')'
+                    : JSON.stringify(encodeURIComponent(String(inputs[key]))));
+        firstQuery = false;
+    }
+    return '={{ ' + expression + ' }}';
+}

package/dist/workflow/workflow-helpers.d.ts

@@ -0,0 +1,6 @@
+import type { Operation } from '../types/openapi.js';
+import type { ExpectedBody, InputValues, RequiredFields } from '../types/workflow.js';
+export declare function isSafeMethod(method: string): boolean;
+export declare function makeUrl(operation: Operation, origin: URL, inputs: InputValues, missing: string[]): string;
+export declare function makeBody(operation: Operation, inputs: InputValues, missing: string[]): string | undefined;
+export declare function assertionCode(status: number, expectedBody: ExpectedBody, requiredFields?: RequiredFields): string;