@pikku/openapi-parser 0.12.21 → 0.12.23

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { parseOpenAPISpec, computeContractHash, type ParsedSpec, } from './parse-openapi.js';
+export { parseOpenAPISpec, computeContractHash, filterOperations, specCoverageWarning, detectLoginOperation, type ParsedSpec, type ParseOptions, type AuthType, type OperationFilter, type LoginOperation, } from './parse-openapi.js';
 export { generateAddonFromOpenAPI } from './codegen.js';
 export { loadAuthConfig, type AuthConfig, type DelegatedLoginConfig, } from './auth-config.js';
 export { type NamedOperation } from './naming.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { parseOpenAPISpec, computeContractHash, } from './parse-openapi.js';
+export { parseOpenAPISpec, computeContractHash, filterOperations, specCoverageWarning, detectLoginOperation, } from './parse-openapi.js';
 export { generateAddonFromOpenAPI } from './codegen.js';
 export { loadAuthConfig, } from './auth-config.js';
 export { createContext, schemaToZod, schemaVarName, sanitizeTypeName, } from './openapi-to-zod-schema.js';

package/dist/parse-openapi.d.ts

@@ -4,7 +4,7 @@ export interface ErrorResponse {
     description: string;
 }
 export interface SecuritySchemeInfo {
-    type: 'oauth2' | 'http' | 'apiKey';
+    type: 'oauth2' | 'http' | 'apiKey' | 'openIdConnect';
     scheme?: string;
     bearerFormat?: string;
     name?: string;
@@ -23,12 +23,17 @@ export interface ParsedSpec {
     };
     baseUrl: string;
     serverUrls: string[];
-    authType: 'bearer' | 'oauth2' | 'apiKey' | 'none';
+    authType: AuthType;
     operations: ParsedOperation[];
     componentSchemas: Record<string, OpenAPISchema>;
     securitySchemes: Record<string, SecuritySchemeInfo>;
     tagDescriptions: Record<string, string>;
 }
+export type AuthType = 'bearer' | 'oauth2' | 'apiKey' | 'basic' | 'none';
+export interface ParseOptions {
+    /** Sent with the request when the spec is fetched from a URL. */
+    headers?: Record<string, string>;
+}
 export interface ParsedOperation {
     operationId?: string;
     method: string;
@@ -42,7 +47,9 @@ export interface ParsedOperation {
     requestBody?: OpenAPISchema;
     requestBodyDescription?: string;
     requestBodyRequired?: boolean;
+    requestBodyMediaType?: string;
     responseSchema?: OpenAPISchema;
+    responseMediaType?: string;
     responseDescription?: string;
     errorResponses: ErrorResponse[];
     deprecated: boolean;
@@ -55,13 +62,32 @@ export interface ParsedParam {
     example?: unknown;
 }
 /**
- * Read and parse an OpenAPI spec from a file path.
- * Supports both YAML (.yaml, .yml) and JSON (.json) files.
+ * Read and parse an OpenAPI spec from a file path or an http(s) URL.
+ * JSON and YAML are both accepted, whatever the extension.
  */
-export declare function parseOpenAPISpec(filePath: string): Promise<ParsedSpec>;
+export declare function parseOpenAPISpec(source: string, options?: ParseOptions): Promise<ParsedSpec>;
 /**
  * Compute a SHA-256 hash of the contract-relevant parts of a parsed spec.
  * Excludes presentation fields (summary, description, tags, operationId)
  * so that only structural API changes produce a different hash.
  */
 export declare function computeContractHash(spec: ParsedSpec): string;
+export interface OperationFilter {
+    tags?: string[];
+    include?: string[];
+    exclude?: string[];
+}
+export declare function filterOperations(spec: ParsedSpec, filter: OperationFilter): ParsedSpec;
+/**
+ * Specs served by API explorers often hide every authenticated route until
+ * the request carries a key, so a spec that is nearly empty — or holds only
+ * its own login route — is a sign the real one was never fetched.
+ */
+export declare function specCoverageWarning(spec: ParsedSpec): string | undefined;
+export interface LoginOperation {
+    method: string;
+    path: string;
+    tokenPath?: string;
+}
+/** A login route that trades credentials for a token, if the spec has one. */
+export declare function detectLoginOperation(spec: ParsedSpec): LoginOperation | undefined;

package/dist/parse-openapi.js

@@ -5,18 +5,17 @@ import { createHash } from 'crypto';
 import { readFile } from 'fs/promises';
 import { parse as parseYAML } from 'yaml';
 /**
- * Read and parse an OpenAPI spec from a file path.
- * Supports both YAML (.yaml, .yml) and JSON (.json) files.
+ * Read and parse an OpenAPI spec from a file path or an http(s) URL.
+ * JSON and YAML are both accepted, whatever the extension.
  */
-export async function parseOpenAPISpec(filePath) {
-    const content = await readFile(filePath, 'utf-8');
-    let doc;
-    if (filePath.endsWith('.json')) {
-        doc = JSON.parse(content);
-    }
-    else {
-        doc = parseYAML(content);
-    }
+export async function parseOpenAPISpec(source, options = {}) {
+    const isUrl = /^https?:\/\//i.test(source);
+    const content = isUrl
+        ? await fetchSpec(source, options.headers ?? {})
+        : await readFile(source, 'utf-8');
+    const doc = content.trimStart().startsWith('{')
+        ? JSON.parse(content)
+        : parseYAML(content);
     // Validate spec version
     const specVersion = doc.openapi ?? doc.swagger;
     if (!specVersion) {
@@ -33,7 +32,7 @@ export async function parseOpenAPISpec(filePath) {
         version: doc.info?.version ?? '1.0.0',
         description: doc.info?.description,
     };
-    const serverUrls = extractServerUrls(doc);
+    const serverUrls = extractServerUrls(doc, isUrl ? source : undefined);
     const baseUrl = serverUrls[0] ?? '';
     const authType = detectAuthType(doc);
     const securitySchemes = extractSecuritySchemes(doc);
@@ -61,6 +60,8 @@ export async function parseOpenAPISpec(filePath) {
                 // OpenAPI 3.x: op.requestBody, Swagger 2.x: parameters[].in === 'body'
                 const body3 = op.requestBody;
                 const body2 = allParams.find((p) => p.in === 'body');
+                const body = extractRequestBody(op, allParams, doc);
+                const response = extractResponse(op, doc);
                 operations.push({
                     operationId: op.operationId,
                     method,
@@ -71,10 +72,12 @@ export async function parseOpenAPISpec(filePath) {
                     pathParams: extractParams(allParams, 'path'),
                     queryParams: extractParams(allParams, 'query'),
                     headerParams: extractParams(allParams, 'header'),
-                    requestBody: extractRequestBody(op),
+                    requestBody: body?.schema,
+                    requestBodyMediaType: body?.mediaType,
                     requestBodyDescription: body3?.description ?? body2?.description,
-                    requestBodyRequired: body3?.required ?? body2?.required,
-                    responseSchema: extractResponseSchema(op),
+                    requestBodyRequired: body3?.required ?? body2?.required ?? body?.required,
+                    responseSchema: response?.schema,
+                    responseMediaType: response?.mediaType,
                     responseDescription: extractResponseDescription(op),
                     errorResponses: extractErrorResponses(op),
                     deprecated: false,
@@ -137,16 +140,44 @@ function resolveRefPath(ref, root) {
     }
     return current;
 }
-function extractServerUrls(doc) {
+async function fetchSpec(url, headers) {
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        const hint = response.status === 401 || response.status === 403
+            ? ' — the spec needs credentials; pass them with --openapi-header "NAME: value"'
+            : '';
+        throw new Error(`Could not fetch the spec from ${url}: HTTP ${response.status}${hint}`);
+    }
+    return response.text();
+}
+const trimSlash = (url) => url.replace(/\/+$/, '');
+function resolveServerUrl(server, specUrl) {
+    if (typeof server?.url !== 'string' || !server.url)
+        return undefined;
+    const url = server.url.replace(/\{([^}]+)\}/g, (match, name) => server.variables?.[name]?.default ?? match);
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url))
+        return trimSlash(url);
+    if (specUrl)
+        return trimSlash(new URL(url, specUrl).toString());
+    return trimSlash(url);
+}
+function extractServerUrls(doc, specUrl) {
     // OpenAPI 3.x
     if (doc.servers && doc.servers.length > 0) {
-        return doc.servers.map((s) => s.url).filter((url) => !!url);
+        return doc.servers
+            .map((server) => resolveServerUrl(server, specUrl))
+            .filter((url) => !!url);
     }
-    // Swagger 2.x
-    if (doc.host) {
-        const schemes = doc.schemes?.length ? doc.schemes : ['https'];
+    // Swagger 2.x: host defaults to the one serving the document
+    const host = doc.host ?? (specUrl ? new URL(specUrl).host : undefined);
+    if (host) {
+        const schemes = doc.schemes?.length
+            ? doc.schemes
+            : specUrl
+                ? [new URL(specUrl).protocol.replace(':', '')]
+                : ['https'];
         const basePath = doc.basePath ?? '';
-        return schemes.map((scheme) => `${scheme}://${doc.host}${basePath}`);
+        return schemes.map((scheme) => trimSlash(`${scheme}://${host}${basePath}`));
     }
     return [];
 }
@@ -155,10 +186,13 @@ function detectAuthType(doc) {
     for (const scheme of Object.values(securitySchemes)) {
         if (scheme.type === 'oauth2')
             return 'oauth2';
-        if (scheme.type === 'http' && scheme.scheme === 'bearer')
+        if (scheme.type === 'http' && scheme.scheme?.toLowerCase() === 'bearer')
             return 'bearer';
         if (scheme.type === 'apiKey')
             return 'apiKey';
+        if (scheme.type === 'basic' ||
+            (scheme.type === 'http' && scheme.scheme?.toLowerCase() === 'basic'))
+            return 'basic';
     }
     return 'none';
 }
@@ -189,26 +223,49 @@ function extractParams(params, location) {
         example: p.example,
     }));
 }
-function extractRequestBody(op) {
-    // OpenAPI 3.x: op.requestBody.content['application/json'].schema
-    const body = op.requestBody;
-    if (body) {
-        const content = body.content;
-        if (content) {
-            const jsonContent = content['application/json'];
-            if (jsonContent?.schema)
-                return jsonContent.schema;
-            const firstKey = Object.keys(content)[0];
-            if (firstKey && content[firstKey]?.schema) {
-                return content[firstKey].schema;
-            }
-        }
-    }
+function pickContent(content) {
+    if (!content)
+        return undefined;
+    const mediaTypes = Object.keys(content);
+    const mediaType = mediaTypes.find((type) => /[/+]json\b/i.test(type) && content[type]?.schema) ?? mediaTypes.find((type) => content[type]?.schema);
+    if (!mediaType)
+        return undefined;
+    return { schema: content[mediaType].schema, mediaType };
+}
+function extractRequestBody(op, params, doc) {
+    // OpenAPI 3.x: op.requestBody.content[<media type>].schema
+    const fromContent = pickContent(op.requestBody?.content);
+    if (fromContent)
+        return fromContent;
     // Swagger 2.x: parameters[].in === 'body' → schema
-    if (op.parameters) {
-        const bodyParam = op.parameters.find((p) => p.in === 'body');
-        if (bodyParam?.schema)
-            return bodyParam.schema;
+    const consumes = op.consumes ?? doc.consumes ?? [];
+    const bodyParam = params.find((p) => p.in === 'body');
+    if (bodyParam?.schema) {
+        return {
+            schema: bodyParam.schema,
+            mediaType: consumes[0] ?? 'application/json',
+        };
+    }
+    // Swagger 2.x: parameters[].in === 'formData' → one object body
+    const formParams = params.filter((p) => p.in === 'formData');
+    if (formParams.length > 0) {
+        const properties = {};
+        const required = [];
+        for (const p of formParams) {
+            properties[p.name] = {
+                ...paramToSchema(p),
+                ...(p.description ? { description: p.description } : {}),
+            };
+            if (p.required)
+                required.push(p.name);
+        }
+        return {
+            schema: { type: 'object', properties, required },
+            mediaType: consumes.includes('multipart/form-data')
+                ? 'multipart/form-data'
+                : 'application/x-www-form-urlencoded',
+            required: required.length > 0,
+        };
     }
     return undefined;
 }
@@ -223,41 +280,38 @@ function extractResponseDescription(op) {
     }
     return undefined;
 }
-function extractResponseSchema(op) {
+function extractResponse(op, doc) {
     const responses = op.responses;
     if (!responses)
         return undefined;
-    // Look for 2xx responses in order of preference
-    for (const code of ['200', '201', '202', '204']) {
-        const resp = responses[code];
+    const produces = op.produces ?? doc.produces ?? [];
+    const fromResponse = (resp) => {
         if (!resp)
-            continue;
-        // OpenAPI 3.x: resp.content['application/json'].schema
-        const content = resp.content;
-        if (content) {
-            const jsonContent = content['application/json'];
-            if (jsonContent?.schema)
-                return jsonContent.schema;
-            const firstKey = Object.keys(content)[0];
-            if (firstKey && content[firstKey]?.schema) {
-                return content[firstKey].schema;
-            }
+            return undefined;
+        const fromContent = pickContent(resp.content);
+        if (fromContent)
+            return fromContent;
+        if (resp.schema) {
+            return {
+                schema: resp.schema,
+                mediaType: produces.find((type) => /[/+]json\b/i.test(type)) ??
+                    produces[0] ??
+                    'application/json',
+            };
         }
-        // Swagger 2.x: resp.schema directly
-        if (resp.schema)
-            return resp.schema;
+        return undefined;
+    };
+    for (const code of ['200', '201', '202', '204']) {
+        const found = fromResponse(responses[code]);
+        if (found)
+            return found;
     }
-    // Fallback: any 2xx
     for (const [code, resp] of Object.entries(responses)) {
         if (!code.startsWith('2'))
             continue;
-        if (resp.content) {
-            const jsonContent = resp.content['application/json'];
-            if (jsonContent?.schema)
-                return jsonContent.schema;
-        }
-        if (resp.schema)
-            return resp.schema;
+        const found = fromResponse(resp);
+        if (found)
+            return found;
     }
     return undefined;
 }
@@ -284,8 +338,11 @@ function extractSecuritySchemes(doc) {
     const result = {};
     for (const [name, scheme] of Object.entries(raw)) {
         const info = {
-            type: scheme.type === 'http' ? 'http' : scheme.type,
+            type: scheme.type === 'basic' ? 'http' : scheme.type,
         };
+        if (scheme.type === 'basic') {
+            info.scheme = 'basic';
+        }
         if (scheme.type === 'http') {
             info.scheme = scheme.scheme;
             info.bearerFormat = scheme.bearerFormat;
@@ -296,10 +353,12 @@ function extractSecuritySchemes(doc) {
         }
         if (scheme.type === 'oauth2') {
             // Extract flows — prefer authorizationCode, then implicit, then clientCredentials
-            const flows = scheme.flows ?? {};
-            const flow = flows.authorizationCode ??
+            const flows = scheme.flows ?? (scheme.flow ? { [scheme.flow]: scheme } : {});
+            const flow = flows.accessCode ??
+                flows.authorizationCode ??
                 flows.implicit ??
                 flows.clientCredentials ??
+                flows.application ??
                 flows.password;
             if (flow) {
                 info.flows = {
@@ -371,3 +430,72 @@ function extractTagDescriptions(doc) {
     }
     return result;
 }
+const globToRegExp = (glob) => new RegExp(`^${glob
+    .split('*')
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+    .join('.*')}$`, 'i');
+/**
+ * `include` / `exclude` patterns match an operationId, a path, or
+ * `METHOD /path`, with `*` as a wildcard.
+ */
+function matchesAny(op, patterns) {
+    const candidates = [
+        op.operationId ?? '',
+        op.path,
+        `${op.method.toUpperCase()} ${op.path}`,
+    ];
+    return patterns
+        .map(globToRegExp)
+        .some((pattern) => candidates.some((c) => pattern.test(c)));
+}
+export function filterOperations(spec, filter) {
+    const tags = filter.tags?.map((tag) => tag.toLowerCase());
+    const operations = spec.operations.filter((op) => (!tags?.length ||
+        op.tags.some((tag) => tags.includes(tag.toLowerCase()))) &&
+        (!filter.include?.length || matchesAny(op, filter.include)) &&
+        !(filter.exclude?.length && matchesAny(op, filter.exclude)));
+    return { ...spec, operations };
+}
+const AUTH_ROUTE = /(^|\/)(log-?in|log-?out|sign-?in|sign-?out|auth\w*|token|session|oauth2?)(\/|$)/i;
+/**
+ * Specs served by API explorers often hide every authenticated route until
+ * the request carries a key, so a spec that is nearly empty — or holds only
+ * its own login route — is a sign the real one was never fetched.
+ */
+export function specCoverageWarning(spec) {
+    const count = spec.operations.length;
+    const onlyAuth = count > 0 && spec.operations.every((op) => AUTH_ROUTE.test(op.path));
+    if (count >= 5 && !onlyAuth)
+        return undefined;
+    const what = onlyAuth
+        ? `only authentication routes (${spec.operations.map((op) => `${op.method.toUpperCase()} ${op.path}`).join(', ')})`
+        : `only ${count} operation${count === 1 ? '' : 's'}`;
+    return `The spec has ${what}. Many APIs publish their full spec only to an authenticated request — fetch it again with credentials (--openapi-header "NAME: value", or the key in the URL's query string if the API reads it there) before generating, or the addon will be missing most of the API.`;
+}
+const TOKEN_KEY = /^(access_?token|token|id_?token|jwt|api_?key|session_?token)$/i;
+function findTokenPath(schema, prefix = '', depth = 0) {
+    if (!schema || typeof schema !== 'object' || depth > 3)
+        return undefined;
+    for (const [key, prop] of Object.entries(schema.properties ?? {})) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (TOKEN_KEY.test(key))
+            return path;
+        const nested = findTokenPath(prop, path, depth + 1);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}
+/** A login route that trades credentials for a token, if the spec has one. */
+export function detectLoginOperation(spec) {
+    const candidates = spec.operations.filter((op) => op.method === 'post' &&
+        /(^|\/)(log-?in|sign-?in|auth(enticate)?|token|sessions?)$/i.test(op.path));
+    for (const op of candidates) {
+        return {
+            method: op.method,
+            path: op.path,
+            tokenPath: findTokenPath(op.responseSchema),
+        };
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/openapi-parser",
-  "version": "0.12.21",
+  "version": "0.12.23",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",