@vertz/openapi 0.1.1 → 0.1.2

package/README.md

@@ -104,15 +104,31 @@ console.log(`${result.written} files written, ${result.skipped} unchanged`);
 
 ## Using the Generated SDK
 
+The generated SDK uses `@vertz/fetch` under the hood. Install it in the project that consumes the SDK:
+
+```bash
+bun add @vertz/fetch
+```
+
 ```ts
 import { createClient } from './generated/client';
+import { isOk } from '@vertz/fetch';
 
 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' });
+// Returns FetchResponse<T> (Result type) — use isOk/isErr to handle
+const result = await api.tasks.list();
+if (isOk(result)) {
+  console.log(result.data); // typed as Task[]
+}
+
+// All FetchClient features available: auth strategies, retries, hooks
+const api = createClient({
+  baseURL: 'https://api.example.com',
+  authStrategies: [{ type: 'bearer', token: 'my-token' }],
+  retry: { retries: 3 },
+});
 ```
 
 ## Custom Operation ID Normalization

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   loadSpec,
   parseOpenAPI,
   resolveConfig
-} from "./shared/chunk-er3k8t3a.js";
+} from "./shared/chunk-h8tb765a.js";
 
 // src/cli.ts
 function parseArgs(args) {

package/dist/index.d.ts

@@ -7,6 +7,7 @@ interface ParsedSpec {
 	};
 	resources: ParsedResource[];
 	schemas: ParsedSchema[];
+	securitySchemes: ParsedSecurityScheme[];
 }
 interface ParsedResource {
 	name: string;
@@ -24,6 +25,11 @@ interface ParsedOperation {
 	response?: ParsedSchema;
 	responseStatus: number;
 	tags: string[];
+	security?: OperationSecurity;
+}
+interface OperationSecurity {
+	required: boolean;
+	schemes: string[];
 }
 interface ParsedParameter {
 	name: string;
@@ -34,6 +40,37 @@ interface ParsedSchema {
 	name?: string;
 	jsonSchema: Record<string, unknown>;
 }
+type ParsedSecurityScheme = {
+	type: "bearer";
+	name: string;
+	description?: string;
+} | {
+	type: "basic";
+	name: string;
+	description?: string;
+} | {
+	type: "apiKey";
+	name: string;
+	in: "header" | "query" | "cookie";
+	paramName: string;
+	description?: string;
+} | {
+	type: "oauth2";
+	name: string;
+	flows: ParsedOAuthFlows;
+	description?: string;
+};
+interface ParsedOAuthFlows {
+	authorizationCode?: {
+		authorizationUrl: string;
+		tokenUrl: string;
+		scopes: Record<string, string>;
+	};
+	clientCredentials?: {
+		tokenUrl: string;
+		scopes: Record<string, string>;
+	};
+}
 interface OperationContext {
 	/** Raw operationId from the spec */
 	operationId: string;
@@ -117,9 +154,11 @@ declare function sanitizeIdentifier(name: string): string;
 declare function generateAll(spec: ParsedSpec, options?: GenerateOptions): GeneratedFile[];
 /**
 * Generate the main client.ts file.
+* Uses @vertz/fetch FetchClient instead of hand-rolling HTTP methods.
 */
 declare function generateClient(resources: ParsedResource[], config: {
 	baseURL?: string;
+	securitySchemes?: ParsedSecurityScheme[];
 }): GeneratedFile;
 /**
 * Convert a JSON Schema object to a TypeScript type expression string.
@@ -154,6 +193,7 @@ declare function generateTypes(resources: ParsedResource[], schemas: ParsedSchem
 declare function parseOpenAPI(spec: Record<string, unknown>): {
 	operations: ParsedOperation[];
 	schemas: ParsedSchema[];
+	securitySchemes: ParsedSecurityScheme[];
 	version: "3.0" | "3.1";
 };
 interface ResolveOptions {

package/dist/index.js

@@ -21,7 +21,7 @@ import {
   sanitizeIdentifier,
   sanitizeTypeName,
   writeIncremental
-} from "./shared/chunk-er3k8t3a.js";
+} from "./shared/chunk-h8tb765a.js";
 export {
   writeIncremental,
   sanitizeTypeName,

package/dist/shared/{chunk-er3k8t3a.js → chunk-h8tb765a.js}

@@ -41,86 +41,93 @@ function groupOperations(operations, strategy, options) {
 }
 
 // src/generators/client-generator.ts
+function camelCase(name) {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+function generateAuthField(scheme) {
+  switch (scheme.type) {
+    case "bearer":
+      return `  ${camelCase(scheme.name)}?: string | (() => string | Promise<string>);`;
+    case "basic":
+      return `  ${camelCase(scheme.name)}?: { username: string; password: string };`;
+    case "apiKey":
+      return `  ${camelCase(scheme.name)}?: string | (() => string | Promise<string>);`;
+    case "oauth2":
+      return `  ${camelCase(scheme.name)}?: string | (() => string | Promise<string>);`;
+  }
+}
+function generateAuthStrategy(scheme) {
+  const fieldName = camelCase(scheme.name);
+  const lines = [];
+  switch (scheme.type) {
+    case "bearer":
+      lines.push(`    ...(options.auth?.${fieldName} ? [{`);
+      lines.push(`      type: 'bearer' as const,`);
+      lines.push(`      token: options.auth?.${fieldName},`);
+      lines.push("    }] : []),");
+      break;
+    case "basic":
+      lines.push(`    ...(options.auth?.${fieldName} ? [{`);
+      lines.push(`      type: 'basic' as const,`);
+      lines.push(`      ...options.auth?.${fieldName},`);
+      lines.push("    }] : []),");
+      break;
+    case "apiKey":
+      lines.push(`    ...(options.auth?.${fieldName} ? [{`);
+      lines.push(`      type: 'apiKey' as const,`);
+      lines.push(`      key: options.auth?.${fieldName},`);
+      lines.push(`      location: '${scheme.in}' as const,`);
+      lines.push(`      name: '${scheme.paramName}',`);
+      lines.push("    }] : []),");
+      break;
+    case "oauth2":
+      lines.push(`    ...(options.auth?.${fieldName} ? [{`);
+      lines.push(`      type: 'bearer' as const,`);
+      lines.push(`      token: options.auth?.${fieldName},`);
+      lines.push("    }] : []),");
+      break;
+  }
+  return lines;
+}
 function generateClient(resources, config) {
   const defaultBaseURL = config.baseURL ? `'${config.baseURL.replace(/'/g, "\\'")}'` : "''";
+  const schemes = config.securitySchemes ?? [];
+  const hasAuth = schemes.length > 0;
   const lines = [];
   lines.push("// Generated by @vertz/openapi — do not edit");
   lines.push("");
+  lines.push("import { FetchClient } from '@vertz/fetch';");
+  lines.push("import type { FetchClientConfig } from '@vertz/fetch';");
   for (const r of resources) {
     lines.push(`import { create${r.name}Resource } from './resources/${r.identifier}';`);
   }
   lines.push("");
-  lines.push("export interface HttpClient {");
-  lines.push("  get<T>(path: string, options?: { query?: Record<string, unknown> }): Promise<T>;");
-  lines.push("  post<T>(path: string, body?: unknown, options?: { query?: Record<string, unknown> }): Promise<T>;");
-  lines.push("  put<T>(path: string, body?: unknown, options?: { query?: Record<string, unknown> }): Promise<T>;");
-  lines.push("  patch<T>(path: string, body?: unknown, options?: { query?: Record<string, unknown> }): Promise<T>;");
-  lines.push("  delete<T>(path: string, options?: { query?: Record<string, unknown> }): Promise<T>;");
-  lines.push("}");
-  lines.push("");
-  lines.push("export interface ClientOptions {");
-  lines.push("  baseURL?: string;");
-  lines.push("  headers?: Record<string, string>;");
-  lines.push("  fetch?: typeof globalThis.fetch;");
-  lines.push("}");
+  if (hasAuth) {
+    lines.push("export interface ClientAuth {");
+    for (const scheme of schemes) {
+      lines.push(generateAuthField(scheme));
+    }
+    lines.push("}");
+    lines.push("");
+  }
+  if (hasAuth) {
+    lines.push("export type ClientOptions = FetchClientConfig & { auth?: ClientAuth };");
+  } else {
+    lines.push("export type ClientOptions = FetchClientConfig;");
+  }
   lines.push("");
   lines.push("export function createClient(options: ClientOptions = {}) {");
-  lines.push(`  const baseURL = (options.baseURL ?? ${defaultBaseURL}).replace(/\\/$/, '');`);
-  lines.push("  const customFetch = options.fetch ?? globalThis.fetch.bind(globalThis);");
-  lines.push("  const defaultHeaders = options.headers ?? {};");
-  lines.push("");
-  lines.push("  const client: HttpClient = {");
-  lines.push("    async get<T>(path: string, opts?: { query?: Record<string, unknown> }): Promise<T> {");
-  lines.push("      let url = `${baseURL}${path}`;");
-  lines.push("      if (opts?.query) {");
-  lines.push("        const params = new URLSearchParams();");
-  lines.push("        for (const [k, v] of Object.entries(opts.query)) { if (v != null) params.set(k, String(v)); }");
-  lines.push("        const qs = params.toString();");
-  lines.push("        if (qs) url += `?${qs}`;");
-  lines.push("      }");
-  lines.push("      const res = await customFetch(url, { method: 'GET', headers: defaultHeaders });");
-  lines.push("      if (!res.ok) throw await ApiError.from(res);");
-  lines.push("      if (res.status === 204) return undefined as T;");
-  lines.push("      return res.json();");
-  lines.push("    },");
-  lines.push("");
-  for (const method of ["post", "put", "patch"]) {
-    lines.push(`    async ${method}<T>(path: string, body?: unknown, opts?: { query?: Record<string, unknown> }): Promise<T> {`);
-    lines.push(`      let url = \`\${baseURL}\${path}\`;`);
-    lines.push("      if (opts?.query) {");
-    lines.push("        const params = new URLSearchParams();");
-    lines.push("        for (const [k, v] of Object.entries(opts.query)) { if (v != null) params.set(k, String(v)); }");
-    lines.push("        const qs = params.toString();");
-    lines.push("        if (qs) url += `?${qs}`;");
-    lines.push("      }");
-    lines.push(`      const res = await customFetch(url, {`);
-    lines.push(`        method: '${method.toUpperCase()}',`);
-    lines.push("        headers: { ...defaultHeaders, 'Content-Type': 'application/json' },");
-    lines.push("        body: body !== undefined ? JSON.stringify(body) : undefined,");
-    lines.push("      });");
-    lines.push("      if (!res.ok) throw await ApiError.from(res);");
-    lines.push("      if (res.status === 204) return undefined as T;");
-    lines.push("      return res.json();");
-    lines.push("    },");
-    lines.push("");
+  lines.push(`  const client = new FetchClient({`);
+  lines.push(`    baseURL: ${defaultBaseURL},`);
+  if (hasAuth) {
+    lines.push("    authStrategies: [");
+    for (const scheme of schemes) {
+      lines.push(...generateAuthStrategy(scheme));
+    }
+    lines.push("    ],");
   }
-  lines.push("    async delete<T>(path: string, opts?: { query?: Record<string, unknown> }): Promise<T> {");
-  lines.push("      let url = `${baseURL}${path}`;");
-  lines.push("      if (opts?.query) {");
-  lines.push("        const params = new URLSearchParams();");
-  lines.push("        for (const [k, v] of Object.entries(opts.query)) { if (v != null) params.set(k, String(v)); }");
-  lines.push("        const qs = params.toString();");
-  lines.push("        if (qs) url += `?${qs}`;");
-  lines.push("      }");
-  lines.push("      const res = await customFetch(url, {");
-  lines.push("        method: 'DELETE',");
-  lines.push("        headers: defaultHeaders,");
-  lines.push("      });");
-  lines.push("      if (!res.ok) throw await ApiError.from(res);");
-  lines.push("      if (res.status === 204) return undefined as T;");
-  lines.push("      return res.json();");
-  lines.push("    },");
-  lines.push("  };");
+  lines.push("    ...options,");
+  lines.push("  });");
   lines.push("");
   lines.push("  return {");
   for (const r of resources) {
@@ -129,21 +136,6 @@ function generateClient(resources, config) {
   lines.push("  };");
   lines.push("}");
   lines.push("");
-  lines.push("export class ApiError extends Error {");
-  lines.push("  override name = 'ApiError';");
-  lines.push("  public data: unknown;");
-  lines.push("");
-  lines.push("  constructor(public status: number, body: string) {");
-  lines.push("    super(`API error ${status}: ${body}`);");
-  lines.push("    try { this.data = JSON.parse(body); } catch { this.data = body; }");
-  lines.push("  }");
-  lines.push("");
-  lines.push("  static async from(res: Response): Promise<ApiError> {");
-  lines.push("    const body = await res.text();");
-  lines.push("    return new ApiError(res.status, body);");
-  lines.push("  }");
-  lines.push("}");
-  lines.push("");
   lines.push("export type Client = ReturnType<typeof createClient>;");
   lines.push("");
   return { path: "client.ts", content: lines.join(`
@@ -268,13 +260,13 @@ function generateResources(resources) {
 function generateResourceFile(resource) {
   const lines = [];
   const typeImports = collectTypeImports(resource);
-  lines.push("import type { HttpClient } from '../client';");
+  lines.push("import type { FetchClient, FetchResponse } from '@vertz/fetch';");
   if (typeImports.size > 0) {
     const sorted = [...typeImports].sort();
     lines.push(`import type { ${sorted.join(", ")} } from '../types/${resource.identifier}';`);
   }
   lines.push("");
-  lines.push(`export function create${resource.name}Resource(client: HttpClient) {`);
+  lines.push(`export function create${resource.name}Resource(client: FetchClient) {`);
   lines.push("  return {");
   validateUniqueMethodNames(resource);
   for (const op of resource.operations) {
@@ -330,22 +322,22 @@ function buildParams(op) {
 }
 function buildReturnType(op) {
   if (op.responseStatus === 204)
-    return "Promise<void>";
+    return "Promise<FetchResponse<void>>";
   if (op.response?.name) {
     const safeName = sanitizeTypeName(op.response.name);
     if (op.response.jsonSchema.type === "array") {
-      return `Promise<${safeName}[]>`;
+      return `Promise<FetchResponse<${safeName}[]>>`;
     }
-    return `Promise<${safeName}>`;
+    return `Promise<FetchResponse<${safeName}>>`;
   }
   if (op.response?.jsonSchema.type === "array") {
-    return "Promise<unknown[]>";
+    return "Promise<FetchResponse<unknown[]>>";
   }
   if (op.response) {
     const name = capitalize(op.operationId) + "Response";
-    return `Promise<${name}>`;
+    return `Promise<FetchResponse<${name}>>`;
   }
-  return "Promise<void>";
+  return "Promise<FetchResponse<void>>";
 }
 function buildCall(op) {
   const method = op.method.toLowerCase();
@@ -721,7 +713,10 @@ function generateAll(spec, options) {
   const files = [];
   files.push(...generateTypes(resources, schemas));
   files.push(...generateResources(resources));
-  files.push(generateClient(resources, { baseURL: opts.baseURL }));
+  files.push(generateClient(resources, {
+    baseURL: opts.baseURL,
+    securitySchemes: spec.securitySchemes
+  }));
   if (opts.schemas) {
     files.push(...generateSchemas(resources, schemas));
   }
@@ -734,10 +729,19 @@ function generateReadme(spec, options) {
   lines.push("");
   lines.push(`> Auto-generated from OpenAPI ${spec.version} spec (v${spec.info.version})`);
   lines.push("");
+  lines.push("## Prerequisites");
+  lines.push("");
+  lines.push("This SDK requires `@vertz/fetch` as a peer dependency:");
+  lines.push("");
+  lines.push("```bash");
+  lines.push("bun add @vertz/fetch");
+  lines.push("```");
+  lines.push("");
   lines.push("## Usage");
   lines.push("");
   lines.push("```typescript");
   lines.push("import { createClient } from './client';");
+  lines.push("import { isOk } from '@vertz/fetch';");
   lines.push("");
   lines.push(`const api = createClient(${options.baseURL ? `{ baseURL: '${options.baseURL}' }` : ""});`);
   lines.push("```");
@@ -1212,6 +1216,64 @@ function collectComponentSchemas(spec, version) {
     name
   }));
 }
+function extractSecuritySchemes(spec) {
+  const components = isRecord2(spec.components) ? spec.components : undefined;
+  const schemes = components && isRecord2(components.securitySchemes) ? components.securitySchemes : undefined;
+  if (!schemes)
+    return [];
+  const result = [];
+  for (const [name, scheme] of Object.entries(schemes)) {
+    if (!isRecord2(scheme))
+      continue;
+    const description = typeof scheme.description === "string" ? scheme.description : undefined;
+    if (scheme.type === "http") {
+      if (scheme.scheme === "bearer") {
+        result.push({ type: "bearer", name, description });
+      } else if (scheme.scheme === "basic") {
+        result.push({ type: "basic", name, description });
+      }
+    } else if (scheme.type === "apiKey") {
+      const location = scheme.in;
+      const paramName = typeof scheme.name === "string" ? scheme.name : name;
+      result.push({ type: "apiKey", name, in: location, paramName, description });
+    } else if (scheme.type === "oauth2" && isRecord2(scheme.flows)) {
+      const flows = {};
+      const rawFlows = scheme.flows;
+      if (isRecord2(rawFlows.authorizationCode)) {
+        const ac = rawFlows.authorizationCode;
+        flows.authorizationCode = {
+          authorizationUrl: String(ac.authorizationUrl ?? ""),
+          tokenUrl: String(ac.tokenUrl ?? ""),
+          scopes: isRecord2(ac.scopes) ? ac.scopes : {}
+        };
+      }
+      if (isRecord2(rawFlows.clientCredentials)) {
+        const cc = rawFlows.clientCredentials;
+        flows.clientCredentials = {
+          tokenUrl: String(cc.tokenUrl ?? ""),
+          scopes: isRecord2(cc.scopes) ? cc.scopes : {}
+        };
+      }
+      result.push({ type: "oauth2", name, flows, description });
+    }
+  }
+  return result;
+}
+function extractOperationSecurity(operation, globalSecurity) {
+  const security = Array.isArray(operation.security) ? operation.security : globalSecurity;
+  if (security.length === 0 && !Array.isArray(operation.security))
+    return;
+  const schemes = [];
+  for (const requirement of security) {
+    if (isRecord2(requirement)) {
+      schemes.push(...Object.keys(requirement));
+    }
+  }
+  return {
+    required: schemes.length > 0,
+    schemes
+  };
+}
 function parseOpenAPI(spec) {
   const version = getVersion(spec);
   if (!isRecord2(spec.info)) {
@@ -1220,6 +1282,7 @@ function parseOpenAPI(spec) {
   if (!isRecord2(spec.paths)) {
     throw new OpenAPIParserError2("OpenAPI spec is missing required field: paths");
   }
+  const globalSecurity = Array.isArray(spec.security) ? spec.security : [];
   const operations = [];
   for (const [path, pathItem] of Object.entries(spec.paths)) {
     if (!isRecord2(pathItem)) {
@@ -1233,7 +1296,8 @@ function parseOpenAPI(spec) {
       const operationId = typeof operation.operationId === "string" ? operation.operationId : `${method}_${path}`;
       const { pathParams, queryParams } = extractParameters(path, pathItem, operation, spec, version);
       const successResponse = pickSuccessResponse(operation, spec);
-      operations.push({
+      const security = extractOperationSecurity(operation, globalSecurity);
+      const parsed = {
         operationId,
         methodName: normalizeOperationId(operationId, method.toUpperCase(), path),
         method: method.toUpperCase(),
@@ -1244,10 +1308,18 @@ function parseOpenAPI(spec) {
         response: successResponse.schema ? resolveSchemaForOutput(successResponse.schema, spec, version) : undefined,
         responseStatus: successResponse.status,
         tags: Array.isArray(operation.tags) ? operation.tags.filter((tag) => typeof tag === "string") : []
-      });
+      };
+      if (security)
+        parsed.security = security;
+      operations.push(parsed);
     }
   }
-  return { operations, schemas: collectComponentSchemas(spec, version), version };
+  return {
+    operations,
+    schemas: collectComponentSchemas(spec, version),
+    securitySchemes: extractSecuritySchemes(spec),
+    version
+  };
 }
 
 // src/writer/incremental.ts
@@ -1358,7 +1430,8 @@ async function generateFromOpenAPI(config) {
       version: typeof info?.version === "string" ? info.version : "0.0.0"
     },
     resources,
-    schemas: parsed.schemas
+    schemas: parsed.schemas,
+    securitySchemes: parsed.securitySchemes
   };
   const files = generateAll(spec, {
     schemas: config.schemas,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/openapi",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "OpenAPI 3.x parser and TypeScript SDK generator for Vertz",
   "license": "MIT",
   "repository": {