x-openapi-flow 1.3.7 → 1.4.0

package/README.md

@@ -11,10 +11,8 @@
 [![last commit](https://img.shields.io/github/last-commit/tiago-marques/x-openapi-flow)](https://github.com/tiago-marques/x-openapi-flow/commits/main)
 ![copilot ready](https://img.shields.io/badge/Copilot-Ready-00BFA5?logo=githubcopilot&logoColor=white)
 
-# x-openapi-flow
-
-**OpenAPI describes APIs.**
-**x-openapi-flow describes how they actually work — for developers and AI.**
+# OpenAPI describes APIs.
+# x-openapi-flow describes how they actually work — for developers and AI.
 
 `x-openapi-flow` is an OpenAPI vendor extension and CLI for documenting and validating resource lifecycle workflows.
 It adds explicit state-machine metadata (`x-openapi-flow`) to operations and validates both schema and lifecycle graph consistency.
@@ -52,14 +50,22 @@ Default adoption path:
 2. Run `init` to create/sync sidecar flow metadata.
 3. Run `apply` whenever the OpenAPI file is regenerated.
 
-Full rollout guide: [docs/wiki/Adoption-Playbook.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Adoption-Playbook.md)
-Troubleshooting: [docs/wiki/Troubleshooting.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Troubleshooting.md)
+Sidecar and output roles:
 
----
+- `{context}.x.(json|yaml)`: sidecar source of lifecycle metadata (the file you edit).
+- `{context}.flow.(json|yaml)`: generated OpenAPI output after merge (the file you validate and serve in docs/tools).
+
+Practical rule:
 
-## Day-to-Day Workflow (API Server Team)
+1. edit `.x`
+2. run `apply`
+3. validate/use `.flow`
+
+Full rollout guide: [docs/wiki/getting-started/Adoption-Playbook.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/getting-started/Adoption-Playbook.md)
+Troubleshooting: [docs/wiki/reference/Troubleshooting.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Troubleshooting.md)
+
+---
 
-Typical routine when your OpenAPI source changes frequently:
 
 1. Bootstrap once per project.
 
@@ -73,8 +79,6 @@ npx x-openapi-flow init
 npx x-openapi-flow apply openapi.yaml
 ```
 
-3. Validate lifecycle quality before opening a PR.
-
 ```bash
 npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality
 ```
@@ -93,8 +97,6 @@ What this gives your team in practice:
 - explicit transition contracts instead of implicit tribal knowledge
 - safer API evolution with fewer integration regressions
 
----
-
 ## Integration Experience (What You See)
 
 ### Swagger UI
@@ -108,6 +110,8 @@ npm run apply
 npm start
 ```
 
+Note: in this example, `npm run apply` prefers local sidecars (`swagger.x.yaml|yml|json`) and falls back to `examples/swagger.x.yaml|json` when a local sidecar is not present.
+
 Experience outcome:
 
 - operation docs enriched with `x-openapi-flow` fields
@@ -115,8 +119,8 @@ Experience outcome:
 
 Demo media:
 
-- GIF slot: `docs/assets/demo-swagger-ui.gif`
-- Image slot: `docs/assets/demo-swagger-ui.png`
+![Swagger UI Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/swagger-ui-flow-lifecycle.png)
+![Swagger UI Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/swagger-ui-flow-lifecycle-2.png)
 
 ### Redoc
 
@@ -136,8 +140,9 @@ Experience outcome:
 
 Demo media:
 
-- GIF slot: `docs/assets/demo-redoc.gif`
-- Image slot: `docs/assets/demo-redoc.png`
+![Redoc Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle.png)
+![Redoc Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle-2.png)
+![Redoc Flow Lifecycle 3](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle-3.png)
 
 ### Postman
 
@@ -157,8 +162,8 @@ Experience outcome:
 
 Demo media:
 
-- GIF slot: `docs/assets/demo-postman.gif`
-- Image slot: `docs/assets/demo-postman.png`
+![Postman Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/postman-flow-lifecycle.png)
+![Postman Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/postman-flow-lifecycle-2.png)
 
 ### Insomnia
 
@@ -178,15 +183,37 @@ Experience outcome:
 
 Demo media:
 
-- GIF slot: `docs/assets/demo-insomnia.gif`
-- Image slot: `docs/assets/demo-insomnia.png`
+![Insomnia Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/insomnia-flow-lifecycle.png)
+![Insomnia Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/insomnia-flow-lifecycle-2.png)
+
+### SDK (TypeScript)
+
+Use this when you want a generated flow-aware SDK for application integration.
+
+```bash
+cd example/sdk/typescript
+npm install
+npm run apply
+npm run generate
+npm run run:sample
+```
+
+Experience outcome:
+
+- generated TypeScript SDK in `sdk/` from `x-openapi-flow` metadata
+- minimal runnable sample showing typed SDK usage in `src/sample.ts`
+- lifecycle-oriented methods and transition-aware resource instances
+
+Example project:
+
+- [example/sdk/typescript/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/example/sdk/typescript/README.md)
 
 More integration details:
 
-- [docs/wiki/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Swagger-UI-Integration.md)
-- [docs/wiki/Redoc-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Redoc-Integration.md)
-- [docs/wiki/Postman-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Postman-Integration.md)
-- [docs/wiki/Insomnia-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Insomnia-Integration.md)
+- [docs/wiki/integrations/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Swagger-UI-Integration.md)
+- [docs/wiki/integrations/Redoc-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Redoc-Integration.md)
+- [docs/wiki/integrations/Postman-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Postman-Integration.md)
+- [docs/wiki/integrations/Insomnia-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Insomnia-Integration.md)
 
 ---
 
@@ -249,11 +276,6 @@ await payment.authorize();
 await payment.capture();
 ```
 
-Demo media:
-
-- GIF slot: `docs/assets/demo-sdk-generation.gif`
-- Image slot: `docs/assets/demo-sdk-generation.png`
-
 ---
 
 ## Example: Payment Flow
@@ -316,10 +338,8 @@ npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]
 npx x-openapi-flow analyze [openapi-file] [--format pretty|json] [--out path] [--merge] [--flows path]
 npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]
 npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]
-npx x-openapi-flow generate-postman [openapi-file] [--output path] [--with-scripts]
-npx x-openapi-flow generate-insomnia [openapi-file] [--output path]
 npx x-openapi-flow generate-redoc [openapi-file] [--output path]
-npx x-openapi-flow graph <openapi-file> [--format mermaid|json]
+<!-- Demo media removed -->
 npx x-openapi-flow doctor [--config path]
 npx x-openapi-flow completion [bash|zsh]
 ```
@@ -332,14 +352,12 @@ npx x-openapi-flow <command> --verbose
 
 Full command details:
 
-- [docs/wiki/CLI-Reference.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/CLI-Reference.md)
+- [docs/wiki/reference/CLI-Reference.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/CLI-Reference.md)
 - [x-openapi-flow/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/README.md)
 
 ---
 
-## Initialization Behavior
-
-Running `init`:
+<!-- Demo media removed -->
 
 - Auto-detects OpenAPI source files (`openapi.yaml`, `openapi.json`, `swagger.yaml`, etc.)
 - Creates or syncs `{context}.x.(json|yaml)` (sidecar with lifecycle metadata)
@@ -357,12 +375,8 @@ npx x-openapi-flow validate openapi.yaml --profile strict
 
 ## Validation Profiles
 
-- `strict` (default): schema + advanced graph checks as errors; quality as warnings (or errors with `--strict-quality`)
-- `relaxed`: schema and orphan checks as errors; advanced/quality checks as warnings
 - `core`: schema and orphan checks only
-
-Validation covers:
-
+<!-- Demo media removed -->
 - Schema contract correctness
 - Orphan states
 - Initial/terminal state structure
@@ -378,20 +392,11 @@ Validation covers:
 - Postman and Insomnia: generated lifecycle-aware collections/workspaces
 - SDK generator: TypeScript available, other languages planned
 
-Example images:
-
-![Guided graph example](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/x-openapi-flow-overview.png)
-![Swagger UI integration result](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/x-openapi-flow-extension.png)
-
+<!-- Demo media removed -->
 Integration docs:
 
-- [docs/wiki/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Swagger-UI-Integration.md)
-- [docs/wiki/Redoc-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Redoc-Integration.md)
-- [docs/wiki/Postman-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Postman-Integration.md)
-- [docs/wiki/Insomnia-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Insomnia-Integration.md)
-
+- [docs/wiki/integrations/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Swagger-UI-Integration.md)
 ---
-
 ## Copilot Ready (AI Sidecar Authoring)
 
 Use [llm.txt](https://github.com/tiago-marques/x-openapi-flow/blob/main/llm.txt) as authoring guidance for sidecar population.
@@ -435,7 +440,7 @@ npx x-openapi-flow apply openapi.x.yaml
 - `quality-warning-api.yaml` (quality warnings)
 - `non-terminating-api.yaml` (non-terminating states)
 
-More examples: [docs/wiki/Real-Examples.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/Real-Examples.md)
+More examples: [docs/wiki/engineering/Real-Examples.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/engineering/Real-Examples.md)
 
 ---
 
@@ -452,7 +457,7 @@ More examples: [docs/wiki/Real-Examples.md](https://github.com/tiago-marques/x-o
 ## Changelog
 
 Version history: [CHANGELOG.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/CHANGELOG.md)
-Release notes: [RELEASE_NOTES_v1.3.7.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/RELEASE_NOTES_v1.3.7.md)
+Release notes: [docs/wiki/releases/RELEASE_NOTES_v1.4.0.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/releases/RELEASE_NOTES_v1.4.0.md)
 
 ---
 

package/adapters/collections/insomnia-adapter.js

@@ -6,14 +6,179 @@ const { loadApi } = require("../../lib/validator");
 const { buildIntermediateModel } = require("../../lib/sdk-generator");
 const { toTitleCase, pathToPostmanUrl, buildLifecycleSequences } = require("../shared/helpers");
 
+function getOperationMapById(api) {
+  const map = new Map();
+  const paths = (api && api.paths) || {};
+
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    for (const [method, operation] of Object.entries(pathItem || {})) {
+      if (!operation || typeof operation !== "object") continue;
+      if (!operation.operationId) continue;
+      map.set(operation.operationId, {
+        ...operation,
+        __path: pathKey,
+        __method: String(method || "get").toLowerCase(),
+      });
+    }
+  }
+
+  return map;
+}
+
+function buildExampleFromSchema(schema) {
+  if (!schema || typeof schema !== "object") return {};
+
+  if (Object.prototype.hasOwnProperty.call(schema, "example")) {
+    return schema.example;
+  }
+
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    return schema.enum[0];
+  }
+
+  if (schema.default !== undefined) {
+    return schema.default;
+  }
+
+  const type = schema.type;
+  if (type === "string") {
+    if (schema.format === "date-time") return "2026-01-01T00:00:00Z";
+    if (schema.format === "date") return "2026-01-01";
+    if (schema.format === "email") return "user@example.com";
+    return "string";
+  }
+  if (type === "number" || type === "integer") return 0;
+  if (type === "boolean") return false;
+  if (type === "array") {
+    const itemExample = buildExampleFromSchema(schema.items || {});
+    return itemExample === undefined ? [] : [itemExample];
+  }
+
+  const properties = schema.properties || {};
+  const required = Array.isArray(schema.required) ? schema.required : Object.keys(properties);
+  const payload = {};
+  for (const key of required) {
+    if (!properties[key]) continue;
+    payload[key] = buildExampleFromSchema(properties[key]);
+  }
+
+  if (Object.keys(payload).length === 0) {
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      payload[key] = buildExampleFromSchema(propertySchema);
+    }
+  }
+
+  return payload;
+}
+
+function extractJsonRequestExample(rawOperation) {
+  if (!rawOperation || !rawOperation.requestBody || !rawOperation.requestBody.content) {
+    return null;
+  }
+
+  const jsonContent = rawOperation.requestBody.content["application/json"];
+  if (!jsonContent) return null;
+
+  if (jsonContent.example !== undefined) {
+    return jsonContent.example;
+  }
+
+  if (jsonContent.examples && typeof jsonContent.examples === "object") {
+    const firstExample = Object.values(jsonContent.examples)[0];
+    if (firstExample && typeof firstExample === "object" && firstExample.value !== undefined) {
+      return firstExample.value;
+    }
+  }
+
+  if (jsonContent.schema) {
+    return buildExampleFromSchema(jsonContent.schema);
+  }
+
+  return null;
+}
+
+function buildJourneyName(sequence, index) {
+  if (!Array.isArray(sequence) || sequence.length === 0) {
+    return `Journey ${index + 1}`;
+  }
+
+  if (sequence.length === 1) {
+    return `Journey ${index + 1}: ${sequence[0].operationId}`;
+  }
+
+  const first = sequence[0].operationId;
+  const last = sequence[sequence.length - 1].operationId;
+  return `Journey ${index + 1}: ${first} -> ${last}`;
+}
+
+function buildFlowDescription(operation) {
+  const lines = [];
+
+  if (operation.currentState) {
+    lines.push(`Current state: ${operation.currentState}`);
+  }
+
+  if (Array.isArray(operation.prerequisites) && operation.prerequisites.length > 0) {
+    lines.push(`Prerequisites: ${operation.prerequisites.join(", ")}`);
+  }
+
+  if (Array.isArray(operation.nextOperations) && operation.nextOperations.length > 0) {
+    const transitions = operation.nextOperations
+      .map((next) => {
+        const parts = [];
+        if (next.targetState) parts.push(`state ${next.targetState}`);
+        if (next.nextOperationId) parts.push(`op ${next.nextOperationId}`);
+        if (next.triggerType) parts.push(`trigger ${next.triggerType}`);
+        return parts.join(" | ");
+      })
+      .filter(Boolean);
+    if (transitions.length > 0) {
+      lines.push(`Next: ${transitions.join(" ; ")}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function createInsomniaRequest(requestId, parentId, operation, resource, rawOperation) {
+  const request = {
+    _id: requestId,
+    _type: "request",
+    parentId,
+    name: operation.operationId,
+    method: String(operation.httpMethod || "get").toUpperCase(),
+    url: `{{ base_url }}${pathToPostmanUrl(operation.path, resource.resourcePropertyName)}`,
+    headers: [],
+    body: {},
+  };
+
+  const description = buildFlowDescription(operation);
+  if (description) {
+    request.description = description;
+  }
+
+  if (["POST", "PUT", "PATCH"].includes(request.method)) {
+    request.headers.push({ name: "Content-Type", value: "application/json" });
+    const bodyExample = extractJsonRequestExample(rawOperation);
+    request.body = {
+      mimeType: "application/json",
+      text: JSON.stringify(bodyExample !== null ? bodyExample : {}, null, 2),
+    };
+  }
+
+  return request;
+}
+
 function generateInsomniaWorkspace(options) {
   const apiPath = path.resolve(options.apiPath);
   const outputPath = path.resolve(options.outputPath || path.join(process.cwd(), "x-openapi-flow.insomnia.json"));
 
   const api = loadApi(apiPath);
   const model = buildIntermediateModel(api);
+  const operationMapById = getOperationMapById(api);
 
   const workspaceId = "wrk_x_openapi_flow";
+  const environmentId = "env_x_openapi_flow_base";
   const resources = [
     {
       _id: workspaceId,
@@ -22,6 +187,15 @@ function generateInsomniaWorkspace(options) {
       description: `Generated from ${apiPath}`,
       scope: "collection",
     },
+    {
+      _id: environmentId,
+      _type: "environment",
+      parentId: workspaceId,
+      name: "Base Environment",
+      data: {
+        base_url: "http://localhost:3000",
+      },
+    },
   ];
 
   for (const resource of model.resources) {
@@ -34,22 +208,44 @@ function generateInsomniaWorkspace(options) {
     });
 
     const sequences = buildLifecycleSequences(resource);
-    const operations = sequences.length > 0
-      ? Array.from(new Map(sequences.flat().map((op) => [op.operationId, op])).values())
-      : resource.operations.filter((operation) => operation.hasFlow);
-
-    operations.forEach((operation, index) => {
-      const requestId = `req_${resource.resourcePropertyName}_${index + 1}`;
-      resources.push({
-        _id: requestId,
-        _type: "request",
-        parentId: groupId,
-        name: operation.operationId,
-        method: String(operation.httpMethod || "get").toUpperCase(),
-        url: `{{ base_url }}${pathToPostmanUrl(operation.path, resource.resourcePropertyName)}`,
-        body: {},
+    if (sequences.length > 0) {
+      sequences.forEach((sequence, sequenceIndex) => {
+        const journeyId = `fld_${resource.resourcePropertyName}_journey_${sequenceIndex + 1}`;
+        resources.push({
+          _id: journeyId,
+          _type: "request_group",
+          parentId: groupId,
+          name: buildJourneyName(sequence, sequenceIndex),
+        });
+
+        sequence.forEach((operation, operationIndex) => {
+          const requestId = `req_${resource.resourcePropertyName}_${sequenceIndex + 1}_${operationIndex + 1}`;
+          resources.push(
+            createInsomniaRequest(
+              requestId,
+              journeyId,
+              operation,
+              resource,
+              operationMapById.get(operation.operationId)
+            )
+          );
+        });
       });
-    });
+    } else {
+      const operations = resource.operations.filter((operation) => operation.hasFlow);
+      operations.forEach((operation, index) => {
+        const requestId = `req_${resource.resourcePropertyName}_${index + 1}`;
+        resources.push(
+          createInsomniaRequest(
+            requestId,
+            groupId,
+            operation,
+            resource,
+            operationMapById.get(operation.operationId)
+          )
+        );
+      });
+    }
   }
 
   const exportPayload = {