openapi-sync 5.0.7 → 6.0.0

package/dist/mcp/server.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import {o,l,m,j,k as k$1}from'../chunk-TTLQP4UN.mjs';import'../chunk-L52BXDAC.mjs';import {c,b}from'../chunk-3VKPQNDD.mjs';import {e,f}from'../chunk-VLACEFT4.mjs';import {McpServer}from'@modelcontextprotocol/sdk/server/mcp.js';import {StdioServerTransport}from'@modelcontextprotocol/sdk/server/stdio.js';import {z}from'zod';import f$1 from'path';import x from'fs';var k=e(c$1=>{o();c();var s=(...t)=>process.stderr.write(t.join(" ")+`
+`),d=process.cwd(),a=new McpServer({name:"openapi-sync",version:"1.0.0"});a.tool("openapi_sync_validate","Validate the openapi-sync config file and all configured API specs without writing any files to disk. Use this as a pre-flight check before syncing. Returns a structured result with per-API validity and endpoint counts.",{},()=>f(null,null,function*(){s("[openapi-sync-mcp] Running validate...");try{let t=yield l({silent:!0});return {content:[{type:"text",text:JSON.stringify(t,null,2)}]}}catch(t){return {content:[{type:"text",text:JSON.stringify({valid:false,configErrors:[t.message],apis:{}})}],isError:true}}}));a.tool("openapi_sync_list_endpoints","Fetch and parse all configured OpenAPI specs, then return a structured list of every endpoint (name, HTTP method, path, tags, summary). No files are written. Use this to understand the API surface before deciding on a client type or tag filters.",{apiName:z.string().optional().describe("Limit results to a specific API name from the config. Omit to list endpoints for all configured APIs."),tags:z.array(z.string()).optional().describe("Filter endpoints to only those with one of these OpenAPI tags.")},n=>f(null,[n],function*({apiName:t,tags:r}){s("[openapi-sync-mcp] Listing endpoints...");try{let o=yield m({apiName:t,tags:r,silent:!0});return {content:[{type:"text",text:JSON.stringify(o,null,2)}]}}catch(o){return {content:[{type:"text",text:`Error: ${o.message}`}],isError:true}}}));a.tool("openapi_sync_sync","Run a full openapi-sync \u2014 fetches all configured OpenAPI specs and writes TypeScript types, endpoint builder functions, and optional validation schemas (Zod/Yup/Joi) to disk. Returns a SyncResult with the list of files written and any errors. Run this after validating your config.",{refetchInterval:z.number().optional().describe("If set, enables continuous auto-sync at this interval (ms). Omit for a single one-time sync.")},r=>f(null,[r],function*({refetchInterval:t}){s("[openapi-sync-mcp] Running sync...");try{let n=yield j({refetchInterval:t,silent:!0});return {content:[{type:"text",text:JSON.stringify(n,null,2)}],isError:!n.success}}catch(n){return {content:[{type:"text",text:JSON.stringify({success:false,apis:[],filesWritten:[],endpointCount:0,warnings:[],errors:[n.message]})}],isError:true}}}));a.tool("openapi_sync_generate_client","Generate a fully-typed API client for one or all configured APIs. Supports: fetch, axios, react-query, swr, rtk-query. Syncs the latest spec first, then writes client files to disk. Returns a SyncResult with the list of files written.",{type:z.enum(["fetch","axios","react-query","swr","rtk-query"]).describe("The type of API client to generate."),apiName:z.string().optional().describe("API name from the config to generate a client for. Omit to generate for all configured APIs."),baseURL:z.string().optional().describe("Base URL to bake into the generated client (e.g. https://api.example.com). Can be overridden at runtime in the generated code."),tags:z.array(z.string()).optional().describe("Only generate client methods for endpoints with these tags."),endpoints:z.array(z.string()).optional().describe("Only generate client methods for these specific endpoint names / operationIds."),outputDir:z.string().optional().describe("Custom output directory for the generated client files. Defaults to the path set in your openapi.sync config.")},I=>f(null,[I],function*({type:t,apiName:r,baseURL:n,tags:o,endpoints:u,outputDir:y}){s(`[openapi-sync-mcp] Generating ${t} client...`);try{let p=yield k$1({type:t,apiName:r,baseURL:n,tags:o,endpoints:u,outputDir:y,silent:!0});return {content:[{type:"text",text:JSON.stringify(p,null,2)}],isError:!p.success}}catch(p){return {content:[{type:"text",text:JSON.stringify({success:false,apis:[],filesWritten:[],endpointCount:0,warnings:[],errors:[p.message]})}],isError:true}}}));a.tool("openapi_sync_init","Create an openapi.sync config file in the current working directory without any interactive prompts. Use this to set up a project from scratch. After calling this tool, run openapi_sync_validate and then openapi_sync_sync.",{apiName:z.string().describe("A short identifier for this API used as a folder name and config key (e.g. 'petstore', 'my-api'). Letters, numbers, hyphens and underscores only."),apiSource:z.string().describe("URL to the OpenAPI spec (https://...) or relative path to a local file (e.g. ./api/openapi.yaml)."),outputFolder:z.string().optional().default("./src/api").describe("Output folder for generated files (default: ./src/api)."),configFormat:z.enum(["typescript","json","javascript"]).optional().default("typescript").describe("Config file format (default: typescript)."),clientType:z.enum(["react-query","swr","fetch","axios","rtk-query"]).optional().describe("Client type to pre-configure in the config. Omit to skip client generation."),validationLibrary:z.enum(["zod","yup","joi"]).optional().describe("Validation library to pre-configure. Omit to skip validation schema generation."),folderSplit:z.boolean().optional().default(false).describe("Organize generated files into folders by OpenAPI tags."),typesPrefix:z.string().optional().default("I").describe("Prefix for generated TypeScript interface names (default: 'I', e.g. IPet)."),excludeTags:z.array(z.string()).optional().describe("Tags to exclude from generation (e.g. ['deprecated', 'internal'])."),runSync:z.boolean().optional().default(false).describe("If true, immediately run a full sync after creating the config file.")},$=>f(null,[$],function*({apiName:t,apiSource:r,outputFolder:n,configFormat:o,clientType:u,validationLibrary:y,folderSplit:I,typesPrefix:p,excludeTags:S,runSync:O}){s("[openapi-sync-mcp] Creating config...");try{let l=yield b({apiName:t,apiSource:r,outputFolder:n,configFormat:o,clientType:u,validationLibrary:y,folderSplit:I,typesPrefix:p,excludeTags:S,runSync:O,silent:!0});return {content:[{type:"text",text:JSON.stringify(l,null,2)}],isError:!l.success}}catch(l){return {content:[{type:"text",text:JSON.stringify({success:false,configFile:"",message:l.message,errors:[l.message]})}],isError:true}}}));a.tool("openapi_sync_read_config","Read the current openapi.sync config file from the working directory and return its contents as a string. Useful to inspect what APIs are configured before running sync or generate-client.",{},()=>f(null,null,function*(){s("[openapi-sync-mcp] Reading config...");let t=[f$1.join(d,"openapi.sync.ts"),f$1.join(d,"openapi.sync.js"),f$1.join(d,"openapi.sync.json")];for(let r of t)if(x.existsSync(r))try{let n=x.readFileSync(r,"utf-8");return {content:[{type:"text",text:JSON.stringify({found:!0,file:f$1.basename(r),path:r,content:n},null,2)}]}}catch(n){return {content:[{type:"text",text:JSON.stringify({found:false,error:`Could not read ${r}: ${n.message}`})}],isError:true}}return {content:[{type:"text",text:JSON.stringify({found:false,searched:t,message:"No openapi.sync config file found. Use the openapi_sync_init tool to create one."})}]}}));function R(){return f(this,null,function*(){let t=new StdioServerTransport;yield a.connect(t),s("[openapi-sync-mcp] Server running on stdio. Ready for tool calls.");})}R().catch(t=>{s("[openapi-sync-mcp] Fatal error:",t),process.exit(1);});});var server = k();
+export{server as default};

package/dist/validate-3G3NZCPG.mjs

@@ -0,0 +1,11 @@
+import {o,d as d$1,f as f$1}from'./chunk-L52BXDAC.mjs';import {d,f,c}from'./chunk-VLACEFT4.mjs';import l from'path';import $ from'fs';import P from'axios';import w from'@apidevtools/swagger-parser';var g,E,b,O,S=d(()=>{o();g=process.cwd(),E=()=>{let i=l.join(g,"openapi.sync.js"),d=l.join(g,"openapi.sync.ts"),r=l.join(g,"openapi.sync.json"),o=[i,d,r];try{c("esbuild-register");}catch(s){}for(let s of o)if($.existsSync(s))try{let n=c(s);return Object.keys(n).length===1&&n.default&&(n=n.default),typeof n=="function"&&(n=n()),{config:n,errors:[]}}catch(n){let c=n instanceof Error?n.message:String(n);return {config:null,errors:[`Failed to parse ${s}: ${c}`]}}return {config:null,errors:[`No config file found. Searched: ${o.join(", ")}. Run \`npx openapi-sync init --no-interactive\` to create one.`]}},b=(i,d)=>f(null,null,function*(){var c;let r;try{if(i.startsWith("http://")||i.startsWith("https://"))r=(yield P.get(i,{timeout:15e3})).data;else {let a=l.isAbsolute(i)?i:l.join(g,i);r=yield $.promises.readFile(a,"utf-8");}}catch(t){return {endpointCount:0,error:`Could not fetch/read spec: ${t instanceof Error?t.message:String(t)}`}}let o;try{let t=d$1(r)?r:f$1(r);o=yield w.parse(t);}catch(t){return {endpointCount:0,error:`Could not parse spec: ${t instanceof Error?t.message:String(t)}`}}let s=0,n=(o==null?void 0:o.paths)||{};for(let t of Object.keys(n)){let a=["get","post","put","patch","delete","head","options"];for(let e of a)(c=n[t])!=null&&c[e]&&s++;}return {endpointCount:s}}),O=i=>f(null,null,function*(){var a;let r=((a=i==null?void 0:i.silent)!=null?a:false)?{log:()=>{},warn:()=>{},error:()=>{}}:{log:console.log,warn:console.warn,error:console.error},o={valid:false,apis:{},configErrors:[]},{config:s,errors:n}=E();if(n.length>0)return o.configErrors=n,r.error(`\u274C Config errors:
+${n.map(e=>`  \u2022 ${e}`).join(`
+`)}`),o;if(!s)return o.configErrors=["Config loaded but is empty or null."],o;if((!s.api||Object.keys(s.api).length===0)&&o.configErrors.push('Config must have at least one API defined under the "api" key.'),o.configErrors.length>0)return r.error(`\u274C Config validation errors:
+${o.configErrors.map(e=>`  \u2022 ${e}`).join(`
+`)}`),o;let c=Object.keys(s.api);r.log(`
+\u{1F50D} Validating ${c.length} API spec(s)...
+`);let t=true;return yield Promise.all(c.map(e=>f(null,null,function*(){let h=s.api[e];r.log(`  \u{1F50E} ${e}: ${h}`);let{endpointCount:m,error:p}=yield b(h,e);p?(o.apis[e]={valid:false,endpointCount:0,error:p},r.error(`  \u274C ${e}: ${p}`),t=false):(o.apis[e]={valid:true,endpointCount:m},r.log(`  \u2705 ${e}: ${m} endpoint(s) found`));}))),o.valid=t&&o.configErrors.length===0,o.valid?r.log(`
+\u2705 All checks passed \u2014 config and specs are valid.
+`):r.error(`
+\u274C Validation failed \u2014 see errors above.
+`),o});});S();export{O as validateConfig};

package/llms.txt

@@ -0,0 +1,334 @@
+# openapi-sync
+
+A CLI + Node.js library that generates TypeScript types, fully-typed API clients,
+and runtime validation schemas from OpenAPI (Swagger) specifications.
+
+Supports: TypeScript, Python, Fetch, Axios, React Query, SWR, RTK Query, Zod, Yup, Joi.
+npm: https://www.npmjs.com/package/openapi-sync
+Docs: https://openapi-sync.com
+GitHub: https://github.com/akintomiwa-fisayo/openapi-sync
+
+
+## AGENT QUICK-START
+
+Minimum working setup (no interactive prompts needed):
+
+```bash
+# 1. Create config (agent-safe, no prompts)
+npx openapi-sync init --no-interactive \
+  --api-name petstore \
+  --api-url https://petstore3.swagger.io/api/v3/openapi.json \
+  --output-folder ./src/api \
+  --config-format typescript
+
+# 2. Validate config and spec before writing any files
+npx openapi-sync validate --json
+
+# 3. Sync — generates types, endpoints, validation schemas
+npx openapi-sync --json
+
+# 4. (Optional) generate a typed API client
+npx openapi-sync generate-client --type react-query --json
+```
+
+All commands support `--json` (machine-readable stdout) and exit codes:
+  0 = success | 1 = config/validation error | 2 = network error | 3 = generation error
+
+
+## CLI COMMANDS
+
+### Agent-safe commands (no stdin required)
+
+| Command | Description |
+|---------|-------------|
+| `npx openapi-sync` | Sync specs, generate types + endpoints + schemas |
+| `npx openapi-sync validate` | Validate config + specs; no files written |
+| `npx openapi-sync list-endpoints` | List all endpoints from spec; no files written |
+| `npx openapi-sync generate-client --type <TYPE>` | Generate typed API client |
+| `npx openapi-sync init --no-interactive [FLAGS]` | Create config file without prompts |
+
+### Interactive-only (requires human stdin — NOT safe for agents)
+
+| Command | Description |
+|---------|-------------|
+| `npx openapi-sync init` | Interactive wizard |
+
+### Global flags (all commands)
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Emit a single JSON object to stdout; suppress emoji logs |
+| `--silent` | Suppress all console output |
+| `--dry-run` | Show what would be written without writing (sync, generate-client) |
+| `--help, -h` | Help |
+| `--version, -v` | Version |
+
+### `init` flags (used with `--no-interactive`)
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--api-name` | `"myapi"` | API key in config |
+| `--api-url` | — | URL to OpenAPI spec |
+| `--api-file` | — | Path to local spec file |
+| `--output-folder` | `"./src/api"` | Generated files output |
+| `--config-format` | `"typescript"` | `typescript`, `json`, `javascript` |
+| `--client-type` | — | `react-query`, `swr`, `fetch`, `axios`, `rtk-query` |
+| `--validation-library` | — | `zod`, `yup`, `joi` |
+| `--folder-split` | `false` | Organise by OpenAPI tags |
+| `--types-prefix` | `"I"` | TS interface name prefix |
+| `--use-operation-id` | `true` | Use operationId for names |
+| `--exclude-tags` | — | Comma-separated tags to exclude |
+| `--show-curl` | `true` | Include cURL in JSDoc |
+| `--refetch-interval` | `0` | Auto-refetch ms (0=disabled) |
+| `--run-sync` | `false` | Run sync after config creation |
+
+### `generate-client` flags
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--type` | `-t` | Client type (required) |
+| `--api` | `-a` | Specific API from config |
+| `--tags` | | Filter endpoints by tags |
+| `--endpoints` | `-e` | Filter by endpoint names |
+| `--output` | `-o` | Output directory |
+| `--base-url` | `-b` | Base URL baked into client |
+
+### `list-endpoints` flags
+
+| Flag | Description |
+|------|-------------|
+| `--api` | Limit to a specific API |
+| `--tags` | Comma-separated tag filter |
+
+
+## PROGRAMMATIC API
+
+All functions are exported from the `openapi-sync` package.
+
+```typescript
+import {
+  Init,            // Sync specs → types, endpoints, schemas
+  GenerateClient,  // Generate typed API client
+  ValidateConfig,  // Pre-flight check (no file writes)
+  ListEndpoints,   // Inspect API surface (no file writes)
+  InteractiveInit, // NOT agent-safe — requires stdin
+} from "openapi-sync";
+```
+
+### Init(options?) → Promise<SyncResult>
+Agent-safe. Returns SyncResult.
+
+```typescript
+const result = await Init({ silent: true });
+// result: { success, apis, filesWritten, endpointCount, warnings, errors }
+```
+
+### GenerateClient(options) → Promise<SyncResult>
+Agent-safe. Syncs then generates a typed client.
+
+```typescript
+const result = await GenerateClient({
+  type: "react-query",    // "fetch"|"axios"|"react-query"|"swr"|"rtk-query"
+  apiName: "petstore",    // optional; defaults to all APIs
+  baseURL: "https://api.example.com",
+  tags: ["pets"],         // optional tag filter
+  silent: true,
+});
+```
+
+### ValidateConfig(options?) → Promise<ValidationResult>
+Agent-safe. No files written.
+
+```typescript
+const validation = await ValidateConfig({ silent: true });
+// validation: { valid, apis: { [name]: { valid, endpointCount, error? } }, configErrors }
+if (!validation.valid) process.exit(1);
+```
+
+### ListEndpoints(options?) → Promise<Record<string, EndpointSummary[]>>
+Agent-safe. No files written.
+
+```typescript
+const map = await ListEndpoints({ apiName: "petstore", tags: ["pet"] });
+// map: { petstore: [{ name, method, path, operationId, tags, summary }] }
+```
+
+### InteractiveInit() → Promise<void>
+NOT agent-safe — blocks on stdin prompts.
+Use CLI `init --no-interactive` instead.
+
+
+## CONFIG FILE FORMAT
+
+Config file: `openapi.sync.ts` | `openapi.sync.js` | `openapi.sync.json`
+JSON Schema: https://openapi-sync.com/schema/openapi.sync.schema.json
+
+### Minimal config
+
+```json
+{
+  "folder": "./src/api",
+  "api": {
+    "petstore": "https://petstore3.swagger.io/api/v3/openapi.json"
+  }
+}
+```
+
+### Full TypeScript config
+
+```typescript
+import { IConfig } from "openapi-sync";
+const config: IConfig = {
+  folder: "./src/api",
+  api: { petstore: "https://petstore3.swagger.io/api/v3/openapi.json" },
+  refetchInterval: 5000,
+  language: "typescript",           // "typescript" | "python"
+  folderSplit: { byTags: true },
+  types: { name: { prefix: "I", useOperationId: true } },
+  endpoints: {
+    doc: { showCurl: true },
+    exclude: { tags: ["deprecated"] },
+  },
+  validations: { library: "zod" },  // "zod" | "yup" | "joi"
+  clientGeneration: {
+    enabled: true,
+    type: "react-query",            // "fetch"|"axios"|"react-query"|"swr"|"rtk-query"
+    baseURL: "https://api.example.com",
+    reactQuery: { version: 5, mutations: true },
+  },
+  customCode: { enabled: true, position: "bottom" },
+};
+export default config;
+```
+
+### Key IConfig fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `api` | `Record<string, string>` | **Required.** Map of API name → spec URL or file path |
+| `folder` | `string` | Output folder (default: `"api"`) |
+| `language` | `"typescript"\|"python"` | Output language |
+| `refetchInterval` | `number` | Auto-refetch ms |
+| `folderSplit.byTags` | `boolean` | Split output by OpenAPI tags |
+| `validations.library` | `"zod"\|"yup"\|"joi"` | Validation schema library |
+| `clientGeneration.type` | string | Client type to generate |
+| `clientGeneration.baseURL` | `string` | Base URL for generated client |
+| `endpoints.exclude.tags` | `string[]` | Tags to exclude from generation |
+
+
+## STRUCTURED RETURN TYPES
+
+### SyncResult (returned by Init, GenerateClient)
+
+```typescript
+type SyncResult = {
+  success: boolean;
+  apis: string[];
+  filesWritten: string[];
+  endpointCount: number;
+  warnings: string[];
+  errors: string[];
+};
+```
+
+### ValidationResult (returned by ValidateConfig)
+
+```typescript
+type ValidationResult = {
+  valid: boolean;
+  apis: Record<string, { valid: boolean; endpointCount: number; error?: string }>;
+  configErrors: string[];
+};
+```
+
+### EndpointSummary (items in ListEndpoints result)
+
+```typescript
+type EndpointSummary = {
+  name: string;
+  method: string;
+  path: string;
+  operationId?: string;
+  tags?: string[];
+  summary?: string;
+};
+```
+
+
+## GENERATED FILE STRUCTURE
+
+```
+./src/api/
+  {apiName}/
+    types.ts          ← TypeScript interfaces for all schemas
+    endpoints.ts      ← Typed endpoint URL builder functions
+    shared.ts         ← Shared component types
+    validations.ts    ← Zod/Yup/Joi schemas (if enabled)
+    client/
+      client.ts       ← Fetch/Axios client instance
+      hooks.ts        ← React Query / SWR hooks (if enabled)
+```
+
+When `folderSplit.byTags` is true, types/endpoints/validations are split into
+tag-named subdirectories with aggregator index files for easy imports.
+
+
+## ERROR CODES (typed errors)
+
+| Code | Class | Trigger |
+|------|-------|---------|
+| `CONFIG_NOT_FOUND` | ConfigNotFoundError | No config file in cwd |
+| `CONFIG_PARSE_FAILED` | ConfigParseError | Config file parse error |
+| `CONFIG_INVALID` | ConfigValidationError | Bad config field value |
+| `SPEC_FETCH_FAILED` | SpecFetchError | Network error fetching spec |
+| `SPEC_READ_FAILED` | SpecReadError | Local file read error |
+| `SPEC_PARSE_FAILED` | SpecParseError | Not a valid OpenAPI spec |
+| `GENERATION_FAILED` | GenerationError | File write error |
+| `UNKNOWN_API` | UnknownApiError | API name not in config |
+
+All error classes extend `OpenApiSyncError` and expose `.code`, `.message`, and `.toJSON()`.
+
+
+## COMMON AGENT WORKFLOWS
+
+### Workflow 1: First-time setup
+
+```bash
+npx openapi-sync init --no-interactive \
+  --api-name myapi \
+  --api-url https://api.example.com/openapi.json \
+  --output-folder ./src/api \
+  --client-type react-query \
+  --validation-library zod \
+  --config-format typescript \
+  --json
+npx openapi-sync validate --json
+npx openapi-sync --json
+npx openapi-sync generate-client --type react-query --json
+```
+
+### Workflow 2: Inspect before generating
+
+```bash
+# See what endpoints exist before committing to a client type
+npx openapi-sync list-endpoints --json | jq '.petstore | map(.method + " " + .path)'
+
+# Preview what would be written
+npx openapi-sync --dry-run --json
+npx openapi-sync generate-client --type fetch --dry-run --json
+```
+
+### Workflow 3: Programmatic (TypeScript)
+
+```typescript
+import { ValidateConfig, Init, GenerateClient } from "openapi-sync";
+
+const validation = await ValidateConfig({ silent: true });
+if (!validation.valid) throw new Error(JSON.stringify(validation));
+
+const syncResult = await Init({ silent: true });
+if (!syncResult.success) throw new Error(JSON.stringify(syncResult));
+
+const clientResult = await GenerateClient({ type: "axios", silent: true });
+console.log(JSON.stringify(clientResult));
+```