x-openapi-flow 1.2.3 → 1.3.1

package/lib/validator.js

@@ -169,6 +169,8 @@ function getOperationsById(api) {
 
       operationsById.set(operation.operationId, {
         operation,
+        path_item: pathItem,
+        path_key: pathKey,
         endpoint: `${method.toUpperCase()} ${pathKey}`,
       });
     }
@@ -224,15 +226,15 @@ function parseFieldReference(refValue) {
     return null;
   }
 
-  const match = refValue.match(/^([^:]+):(request\.body|response\.(\d{3}|default)\.body)\.(.+)$/);
+  const match = refValue.match(/^([^:]+):(request\.(body|path)|response\.(\d{3}|default)\.body)\.(.+)$/);
   if (!match) {
     return null;
   }
 
   const operationId = match[1];
   const scope = match[2];
-  const responseCode = match[3];
-  const fieldPath = match[4];
+  const responseCode = match[4];
+  const fieldPath = match[5];
 
   return {
     operation_id: operationId,
@@ -332,6 +334,34 @@ function resolveFieldReferenceSchema(api, operationsById, parsedRef) {
     return { schema: requestSchema };
   }
 
+  if (parsedRef.scope === "request.path") {
+    const pathLevelParams = Array.isArray(operationInfo.path_item && operationInfo.path_item.parameters)
+      ? operationInfo.path_item.parameters
+      : [];
+    const operationLevelParams = Array.isArray(operation.parameters)
+      ? operation.parameters
+      : [];
+
+    const allParams = [...pathLevelParams, ...operationLevelParams].filter(
+      (param) => param && typeof param === "object" && param.in === "path" && param.name
+    );
+
+    if (!allParams.length) {
+      return { error: "path_parameters_not_found" };
+    }
+
+    const pathSchema = {
+      type: "object",
+      properties: {},
+    };
+
+    for (const param of allParams) {
+      pathSchema.properties[param.name] = param.schema || { type: "string" };
+    }
+
+    return { schema: pathSchema };
+  }
+
   const responseCode = parsedRef.response_code;
   const responseSchema = operation.responses
     && operation.responses[responseCode]
@@ -985,5 +1015,8 @@ module.exports = {
   validateFlows,
   detectOrphanStates,
   buildStateGraph,
+  detectDuplicateTransitions,
+  detectInvalidOperationReferences,
+  detectTerminalCoverage,
   run,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x-openapi-flow",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "OpenAPI extension for resource workflow and lifecycle management",
   "main": "lib/validator.js",
   "repository": {
@@ -14,6 +14,9 @@
   "files": [
     "bin",
     "lib",
+    "adapters",
+    "templates",
+    "schema",
     "schema",
     "examples",
     "README.md",
@@ -29,8 +32,10 @@
     "x-openapi-flow": "bin/x-openapi-flow.js"
   },
   "scripts": {
-    "test": "npm run test:cli && npm run test:smoke",
-    "test:cli": "node --test tests/cli.test.js",
+    "test": "npm run test:cli && npm run test:ui && npm run test:integration && npm run test:smoke",
+    "test:cli": "node --test tests/cli/cli.test.js",
+    "test:ui": "node --test tests/plugins/plugin-ui.test.js",
+    "test:integration": "node --test tests/integration/*.test.js",
     "test:smoke": "node bin/x-openapi-flow.js validate examples/payment-api.yaml --profile strict"
   },
   "keywords": [
@@ -44,6 +49,7 @@
   "license": "MIT",
   "dependencies": {
     "ajv": "^8.17.1",
+    "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0"
   }
 }

package/schema/flow-schema.json

@@ -72,14 +72,14 @@
           },
           "prerequisite_field_refs": {
             "type": "array",
-            "description": "Field references required before this transition. Format: operationId:request.body.field or operationId:response.<status>.body.field",
+            "description": "Field references required before this transition. Format: operationId:request.body.field, operationId:request.path.paramName, or operationId:response.<status>.body.field",
             "items": {
               "type": "string"
             }
           },
           "propagated_field_refs": {
             "type": "array",
-            "description": "Field references produced/propagated for downstream flows. Format: operationId:request.body.field or operationId:response.<status>.body.field",
+            "description": "Field references produced/propagated for downstream flows. Format: operationId:request.body.field, operationId:request.path.paramName, or operationId:response.<status>.body.field",
             "items": {
               "type": "string"
             }

package/templates/go/README.md

@@ -0,0 +1,3 @@
+# Go Templates
+
+Reserved for Go SDK generation templates.

package/templates/kotlin/README.md

@@ -0,0 +1,3 @@
+# Kotlin Templates
+
+Reserved for Kotlin SDK generation templates.

package/templates/python/README.md

@@ -0,0 +1,3 @@
+# Python Templates
+
+Reserved for Python SDK generation templates.

package/templates/typescript/flow-helpers.hbs

@@ -0,0 +1,26 @@
+export interface FlowExecutable {
+  [methodName: string]: (...args: unknown[]) => Promise<unknown>;
+}
+
+export async function runFlow(
+  executable: FlowExecutable,
+  flow: string,
+  ...args: unknown[]
+): Promise<unknown> {
+  const steps = flow
+    .split("->")
+    .map((step) => step.trim())
+    .filter(Boolean);
+
+  let current: unknown = executable;
+  for (const step of steps) {
+    const target = current as FlowExecutable;
+    if (!target || typeof target[step] !== "function") {
+      throw new Error(`Flow step '${step}' is not available in the current state.`);
+    }
+
+    current = await target[step](...args);
+  }
+
+  return current;
+}

package/templates/typescript/http-client.hbs

@@ -0,0 +1,37 @@
+export interface RequestOptions {
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+export interface HttpClient {
+  request(method: string, path: string, options?: RequestOptions): Promise<unknown>;
+}
+
+export class FetchHttpClient implements HttpClient {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly defaultHeaders: Record<string, string> = {},
+  ) {}
+
+  async request(method: string, path: string, options: RequestOptions = {}): Promise<unknown> {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...this.defaultHeaders,
+        ...(options.headers || {}),
+      },
+      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} when calling ${method} ${path}`);
+    }
+
+    if (response.status === 204) {
+      return undefined;
+    }
+
+    return response.json();
+  }
+}

package/templates/typescript/index.hbs

@@ -0,0 +1,16 @@
+import type { HttpClient } from "./http-client";
+{{#each resources}}
+import { {{resourceClassName}}Resource } from "./resources/{{resourceClassName}}";
+{{/each}}
+
+export class FlowApiClient {
+{{#each resources}}
+  public readonly {{resourcePropertyName}}: {{resourceClassName}}Resource;
+{{/each}}
+
+  constructor(httpClient: HttpClient) {
+{{#each resources}}
+    this.{{resourcePropertyName}} = new {{resourceClassName}}Resource(httpClient);
+{{/each}}
+  }
+}

package/templates/typescript/resource.hbs

@@ -0,0 +1,24 @@
+import type { HttpClient, RequestOptions } from "../http-client";
+
+const ensurePrerequisites = (
+  completedOperations: Set<string>,
+  requiredOperationIds: string[],
+  methodName: string,
+): void => {
+  const missing = requiredOperationIds.filter((operationId) => !completedOperations.has(operationId));
+  if (missing.length > 0) {
+    throw new Error(
+      `Cannot call ${methodName} before prerequisites are satisfied: ${missing.join(", ")}`,
+    );
+  }
+};
+
+{{{sharedTypesCode}}}
+
+{{{stateClassesCode}}}
+
+export class {{resourceClassName}}Resource {
+  constructor(private readonly httpClient: HttpClient) {}
+
+{{{serviceMethodsCode}}}
+}

package/examples/swagger-ui/index.html

@@ -1,33 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>x-openapi-flow + Swagger UI</title>
-    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
-    <style>
-      body { margin: 0; }
-      #swagger-ui { max-width: 1200px; margin: 0 auto; }
-    </style>
-  </head>
-  <body>
-    <div id="swagger-ui"></div>
-
-    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
-    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
-    <script>
-      window.XOpenApiFlowGraphImageUrl = "https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/graph-order-guided.svg";
-    </script>
-    <script src="../../lib/swagger-ui/x-openapi-flow-plugin.js"></script>
-    <script>
-      window.ui = SwaggerUIBundle({
-        url: "../payment-api.yaml",
-        dom_id: "#swagger-ui",
-        deepLinking: true,
-        presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
-        plugins: [window.XOpenApiFlowPlugin],
-        showExtensions: true,
-      });
-    </script>
-  </body>
-</html>