@vertz/openapi 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,229 @@
+# @vertz/openapi
+
+Generate typed TypeScript SDKs from OpenAPI 3.x specs. Produces a fully typed client with resource methods, TypeScript interfaces, and optional Zod schemas.
+
+## Install
+
+```bash
+bun add @vertz/openapi
+```
+
+## Quick Start
+
+```bash
+npx @vertz/openapi generate --from ./openapi.json --output ./src/generated
+```
+
+This generates:
+
+```
+src/generated/
+  client.ts          # createClient() factory + HttpClient interface
+  types/             # TypeScript interfaces per resource
+  resources/         # Typed resource methods per resource
+  schemas/           # Zod schemas (opt-in with --schemas)
+  README.md          # Usage documentation
+```
+
+## CLI
+
+### `generate` — Generate SDK from a spec
+
+```bash
+npx @vertz/openapi generate [options]
+```
+
+| Flag                   | Description                              | Default                       |
+| ---------------------- | ---------------------------------------- | ----------------------------- |
+| `--from <path-or-url>` | Path to OpenAPI spec file or URL         | Required (or use config file) |
+| `--output <dir>`       | Output directory                         | `./src/generated`             |
+| `--base-url <url>`     | Default base URL for API calls           | `''`                          |
+| `--group-by <mode>`    | Grouping strategy: `tag`, `path`, `none` | `tag`                         |
+| `--schemas`            | Generate Zod validation schemas          | `false`                       |
+| `--exclude-tags <t>`   | Comma-separated tags to exclude          | none                          |
+| `--dry-run`            | Preview without writing files            | `false`                       |
+
+### `validate` — Validate a spec without generating
+
+```bash
+npx @vertz/openapi validate --from ./openapi.json
+```
+
+## Config File
+
+Create an `openapi.config.ts` in your project root:
+
+```ts
+import { defineConfig } from '@vertz/openapi';
+
+export default defineConfig({
+  source: './openapi.json',
+  output: './src/generated',
+  baseURL: 'https://api.example.com',
+  groupBy: 'tag',
+  schemas: true,
+});
+```
+
+CLI flags override config file values.
+
+## Excluding Tags
+
+Skip internal, deprecated, or catch-all tags that don't map cleanly to SDK resources:
+
+```ts
+export default defineConfig({
+  source: './openapi.json',
+  excludeTags: ['internal', 'deprecated'],
+});
+```
+
+Or via CLI:
+
+```bash
+npx @vertz/openapi generate --from ./openapi.json --exclude-tags internal,deprecated
+```
+
+Operations where **any** tag matches the exclude list are skipped entirely.
+
+## Programmatic API
+
+```ts
+import { generateFromOpenAPI } from '@vertz/openapi';
+
+const result = await generateFromOpenAPI({
+  source: './openapi.json',
+  output: './src/generated',
+  baseURL: 'https://api.example.com',
+  groupBy: 'tag',
+  schemas: false,
+});
+
+console.log(`${result.written} files written, ${result.skipped} unchanged`);
+```
+
+## Using the Generated SDK
+
+```ts
+import { createClient } from './generated/client';
+
+const api = createClient({ baseURL: 'https://api.example.com' });
+
+// Fully typed — params, body, and response types are inferred
+const tasks = await api.tasks.list();
+const task = await api.tasks.get(taskId);
+const created = await api.tasks.create({ title: 'New task' });
+```
+
+## Custom Operation ID Normalization
+
+The generator auto-cleans operationIds (strips controller prefixes, detects CRUD patterns). For more control:
+
+### Static overrides
+
+```ts
+export default defineConfig({
+  source: './openapi.json',
+  operationIds: {
+    overrides: {
+      listTasks: 'fetchAll',
+      getTask: 'findById',
+    },
+  },
+});
+```
+
+### Transform function
+
+The transform receives the auto-cleaned name and a full `OperationContext`:
+
+```ts
+export default defineConfig({
+  source: './openapi.json',
+  operationIds: {
+    transform: (cleaned, ctx) => {
+      // ctx.operationId  — raw operationId from the spec
+      // ctx.method       — GET, POST, PUT, DELETE, PATCH
+      // ctx.path         — /v1/tasks/{id}
+      // ctx.tags         — ['tasks']
+      // ctx.hasBody      — whether the operation has a request body
+      return cleaned;
+    },
+  },
+});
+```
+
+## Framework Adapters
+
+Built-in adapters handle operationId quirks for common backend frameworks. Import from `@vertz/openapi/adapters`:
+
+### FastAPI
+
+FastAPI generates operationIds like `list_tasks_tasks_get` (function name + route + verb). The adapter strips the route+verb suffix and handles API version prefixes.
+
+```ts
+import { defineConfig } from '@vertz/openapi';
+import { fastapi } from '@vertz/openapi/adapters';
+
+export default defineConfig({
+  source: './openapi.json',
+  output: './src/generated',
+  operationIds: fastapi(),
+});
+```
+
+| FastAPI operationId          | Path             | Result           |
+| ---------------------------- | ---------------- | ---------------- |
+| `list_tasks_tasks_get`       | `/tasks`         | `list_tasks`     |
+| `get_user_v1_users__id__get` | `/v1/users/{id}` | `get_user_v1`    |
+| `create_task_v2_tasks_post`  | `/v2/tasks`      | `create_task_v2` |
+
+### NestJS
+
+NestJS (`@nestjs/swagger`) generates operationIds like `TasksController_findAll`. The adapter strips the Controller prefix.
+
+```ts
+import { defineConfig } from '@vertz/openapi';
+import { nestjs } from '@vertz/openapi/adapters';
+
+export default defineConfig({
+  source: './openapi.json',
+  output: './src/generated',
+  operationIds: nestjs(),
+});
+```
+
+| NestJS operationId        | Result    |
+| ------------------------- | --------- |
+| `TasksController_findAll` | `findAll` |
+| `UsersController.getById` | `getById` |
+
+### Writing a Custom Adapter
+
+An adapter is just a function that returns `{ transform }`:
+
+```ts
+function myFramework() {
+  return {
+    transform: (cleaned, ctx) => {
+      // Your logic here using ctx.operationId, ctx.method, ctx.path, etc.
+      return cleaned;
+    },
+  };
+}
+
+export default defineConfig({
+  operationIds: myFramework(),
+});
+```
+
+## Incremental Writes
+
+The generator only writes files whose content has changed (SHA-256 comparison). Unchanged files are left untouched, so downstream tools (watchers, bundlers) aren't triggered unnecessarily. Stale files are automatically removed.
+
+## Supported Specs
+
+- OpenAPI 3.0.x
+- OpenAPI 3.1.x
+- JSON and YAML formats
+- File paths and URLs

package/bin/openapi.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+import { runCLI } from '../src/cli';
+
+const result = await runCLI(process.argv.slice(2));
+
+if (result.message) {
+  if (result.exitCode === 0) {
+    console.log(result.message);
+  } else {
+    console.error(result.message);
+  }
+}
+
+process.exit(result.exitCode);

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+interface CLIResult {
+	exitCode: number;
+	message: string;
+}
+/**
+* Run the CLI with the given arguments.
+* Returns a result with exit code and message (for testability).
+*/
+declare function runCLI(args: string[], cwd?: string): Promise<CLIResult>;
+export { runCLI, CLIResult };

package/dist/cli.js

@@ -0,0 +1,133 @@
+import {
+  generateFromOpenAPI,
+  loadConfigFile,
+  loadSpec,
+  parseOpenAPI,
+  resolveConfig
+} from "./shared/chunk-er3k8t3a.js";
+
+// src/cli.ts
+function parseArgs(args) {
+  const command = args[0] ?? "";
+  const flags = {};
+  for (let i = 1;i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    }
+  }
+  return { command, flags };
+}
+function flagsToPartialConfig(flags) {
+  const result = {};
+  if (typeof flags.from === "string")
+    result.from = flags.from;
+  if (typeof flags.output === "string")
+    result.output = flags.output;
+  if (typeof flags["base-url"] === "string")
+    result.baseURL = flags["base-url"];
+  if (typeof flags["group-by"] === "string") {
+    const value = flags["group-by"];
+    if (value === "tag" || value === "path" || value === "none") {
+      result.groupBy = value;
+    }
+  }
+  if (flags.schemas === true)
+    result.schemas = true;
+  if (typeof flags["exclude-tags"] === "string") {
+    result.excludeTags = flags["exclude-tags"].split(",").map((t) => t.trim());
+  }
+  if (flags["dry-run"] === true)
+    result.dryRun = true;
+  return result;
+}
+async function handleGenerate(flags, cwd) {
+  const cliFlags = flagsToPartialConfig(flags);
+  const configFile = await loadConfigFile(cwd);
+  let config;
+  try {
+    const resolved = resolveConfig(cliFlags, configFile);
+    config = { ...resolved, dryRun: cliFlags.dryRun };
+  } catch (err) {
+    return {
+      exitCode: 1,
+      message: `Error: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  try {
+    const result = await generateFromOpenAPI(config);
+    if (config.dryRun) {
+      return {
+        exitCode: 0,
+        message: `Generated ${result.written + result.skipped} files (dry run) — ${result.written} would be written, ${result.skipped} unchanged`
+      };
+    }
+    const parts = [];
+    parts.push(`Generated ${result.written + result.skipped} files in ${config.output}`);
+    parts.push(`${result.written} written`);
+    if (result.skipped > 0)
+      parts.push(`${result.skipped} unchanged`);
+    if (result.removed > 0)
+      parts.push(`${result.removed} removed`);
+    return {
+      exitCode: 0,
+      message: parts.join(", ")
+    };
+  } catch (err) {
+    return {
+      exitCode: 1,
+      message: `Error: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+async function handleValidate(flags) {
+  const source = typeof flags.from === "string" ? flags.from : undefined;
+  if (!source) {
+    return {
+      exitCode: 1,
+      message: "Error: Missing --from flag for validate command"
+    };
+  }
+  try {
+    const raw = await loadSpec(source);
+    const parsed = parseOpenAPI(raw);
+    return {
+      exitCode: 0,
+      message: `Spec is valid — OpenAPI ${parsed.version}, ${parsed.operations.length} operations`
+    };
+  } catch (err) {
+    return {
+      exitCode: 1,
+      message: `Error: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+async function runCLI(args, cwd) {
+  const { command, flags } = parseArgs(args);
+  if (!command) {
+    return {
+      exitCode: 1,
+      message: "Usage: @vertz/openapi <generate|validate> [options]"
+    };
+  }
+  if (command === "generate") {
+    return handleGenerate(flags, cwd ?? process.cwd());
+  }
+  if (command === "validate") {
+    return handleValidate(flags);
+  }
+  return {
+    exitCode: 1,
+    message: `Unknown command: ${command}. Use "generate" or "validate".`
+  };
+}
+export {
+  runCLI
+};

package/dist/index.d.ts

@@ -34,14 +34,123 @@ interface ParsedSchema {
 	name?: string;
 	jsonSchema: Record<string, unknown>;
 }
-type GroupByStrategy = "tag" | "path" | "none";
-declare function groupOperations(operations: ParsedOperation[], strategy: GroupByStrategy): ParsedResource[];
-declare function sanitizeIdentifier(name: string): string;
+interface OperationContext {
+	/** Raw operationId from the spec */
+	operationId: string;
+	/** HTTP method (GET, POST, etc.) */
+	method: HttpMethod;
+	/** Route path (e.g. /v1/tasks/{id}) */
+	path: string;
+	/** Tags from the operation */
+	tags: string[];
+	/** Whether the operation has a request body */
+	hasBody: boolean;
+}
 interface NormalizerConfig {
 	overrides?: Record<string, string>;
-	transform?: (cleaned: string, original: string) => string;
+	transform?: (cleaned: string, context: OperationContext) => string;
+}
+declare function normalizeOperationId(operationId: string, method: HttpMethod, path: string, config?: NormalizerConfig, context?: OperationContext): string;
+interface OpenAPIConfig {
+	source: string;
+	output: string;
+	baseURL: string;
+	groupBy: "tag" | "path" | "none";
+	schemas: boolean;
+	excludeTags?: string[];
+	operationIds?: {
+		overrides?: Record<string, string>;
+		transform?: (cleaned: string, context: OperationContext) => string;
+	};
+}
+/**
+* Merge CLI flags with config file values. CLI flags take precedence.
+*/
+declare function resolveConfig(cliFlags: Partial<OpenAPIConfig> & {
+	from?: string;
+}, configFile?: Partial<OpenAPIConfig>): OpenAPIConfig;
+/**
+* Load config from openapi.config.ts if it exists.
+*/
+declare function loadConfigFile(cwd: string): Promise<Partial<OpenAPIConfig> | undefined>;
+/**
+* Type helper for config files.
+*/
+declare function defineConfig(config: Partial<OpenAPIConfig>): Partial<OpenAPIConfig>;
+interface GeneratedFile {
+	path: string;
+	content: string;
+}
+interface GenerateOptions {
+	schemas?: boolean;
+	baseURL?: string;
 }
-declare function normalizeOperationId(operationId: string, method: HttpMethod, path: string, config?: NormalizerConfig): string;
+interface WriteResult {
+	written: number;
+	skipped: number;
+	removed: number;
+	filesWritten: string[];
+}
+/**
+* Write generated files to disk, only updating files whose content changed.
+*/
+declare function writeIncremental(files: GeneratedFile[], outputDir: string, options?: {
+	clean?: boolean;
+	dryRun?: boolean;
+}): Promise<WriteResult>;
+/**
+* Generate a typed SDK from an OpenAPI spec.
+* This is the main programmatic API.
+*/
+declare function generateFromOpenAPI(config: OpenAPIConfig & {
+	dryRun?: boolean;
+}): Promise<WriteResult>;
+type GroupByStrategy = "tag" | "path" | "none";
+interface GroupOptions {
+	excludeTags?: string[];
+}
+declare function groupOperations(operations: ParsedOperation[], strategy: GroupByStrategy, options?: GroupOptions): ParsedResource[];
+declare function sanitizeIdentifier(name: string): string;
+/**
+* Generate all SDK files from a parsed spec.
+*/
+declare function generateAll(spec: ParsedSpec, options?: GenerateOptions): GeneratedFile[];
+/**
+* Generate the main client.ts file.
+*/
+declare function generateClient(resources: ParsedResource[], config: {
+	baseURL?: string;
+}): GeneratedFile;
+/**
+* Convert a JSON Schema object to a TypeScript type expression string.
+*/
+declare function jsonSchemaToTS(schema: Record<string, unknown>, namedSchemas: Map<string, string>): string;
+/**
+* Sanitize a name to be a valid TypeScript identifier (PascalCase for types).
+* Strips invalid chars, preserves casing of segments, prefixes with _ if starts with digit.
+*/
+declare function sanitizeTypeName(name: string): string;
+/**
+* Generate a full TypeScript interface declaration from a named schema.
+*/
+declare function generateInterface(name: string, schema: Record<string, unknown>, namedSchemas: Map<string, string>): string;
+declare function isValidIdentifier(name: string): boolean;
+/**
+* Convert a JSON Schema object to a Zod expression string.
+*/
+declare function jsonSchemaToZod(schema: Record<string, unknown>, namedSchemas: Map<string, string>): string;
+/**
+* Generate resource SDK files for all resources + a barrel index.
+*/
+declare function generateResources(resources: ParsedResource[]): GeneratedFile[];
+/**
+* Generate Zod schema files for all resources + barrel index.
+*/
+declare function generateSchemas(resources: ParsedResource[], schemas: ParsedSchema[]): GeneratedFile[];
+/**
+* Generate types files for all resources + a barrel index.
+*/
+declare function generateTypes(resources: ParsedResource[], schemas: ParsedSchema[]): GeneratedFile[];
 declare function parseOpenAPI(spec: Record<string, unknown>): {
 	operations: ParsedOperation[];
 	schemas: ParsedSchema[];
@@ -52,4 +161,9 @@ interface ResolveOptions {
 }
 declare function resolveRef(ref: string, document: Record<string, unknown>, options: ResolveOptions): Record<string, unknown>;
 declare function resolveSchema(schema: Record<string, unknown>, document: Record<string, unknown>, options: ResolveOptions, resolving?: Set<string>): Record<string, unknown>;
-export { sanitizeIdentifier, resolveSchema, resolveRef, parseOpenAPI, normalizeOperationId, groupOperations, ResolveOptions, ParsedSpec, ParsedSchema, ParsedResource, ParsedParameter, ParsedOperation, NormalizerConfig, HttpMethod, GroupByStrategy };
+/**
+* Load an OpenAPI spec from a file path or URL.
+* Auto-detects JSON vs YAML from file extension or content.
+*/
+declare function loadSpec(source: string): Promise<Record<string, unknown>>;
+export { writeIncremental, sanitizeTypeName, sanitizeIdentifier, resolveSchema, resolveRef, resolveConfig, parseOpenAPI, normalizeOperationId, loadSpec, loadConfigFile, jsonSchemaToZod, jsonSchemaToTS, isValidIdentifier, groupOperations, generateTypes, generateSchemas, generateResources, generateInterface, generateFromOpenAPI, generateClient, generateAll, defineConfig, WriteResult, ResolveOptions, ParsedSpec, ParsedSchema, ParsedResource, ParsedParameter, ParsedOperation, OperationContext, OpenAPIConfig, NormalizerConfig, HttpMethod, GroupOptions, GroupByStrategy, GeneratedFile, GenerateOptions };