genoc 0.4.2 → 0.5.0

package/dist/parser/version/version-detector.js

@@ -1,32 +1,35 @@
 /**
  * Version detector for multi-version OpenAPI support
  */
+import { specLinkUrl, SpecViolationError } from './spec-links.js';
 export function detectSpecVersion(rawSpec) {
     if (typeof rawSpec !== 'object' || rawSpec === null || Array.isArray(rawSpec)) {
-        throw new Error('Invalid spec: must be a non-null object');
+        throw new SpecViolationError('Invalid spec: must be a non-null object', 'document-root');
     }
     const spec = rawSpec;
     // Check for Swagger 2.0
     if ('swagger' in spec && typeof spec.swagger === 'string') {
         if (spec.swagger === '2.0') {
+            // Unsupported feature, not a spec violation — the document is valid.
             throw new Error('Swagger 2.0 is not supported. Convert to OpenAPI using swagger2openapi first.');
         }
         throw new Error(`Unsupported Swagger version: ${spec.swagger}`);
     }
     // Check for OpenAPI 3.0+
     if (!('openapi' in spec) || typeof spec.openapi !== 'string') {
-        throw new Error("Invalid spec: missing or invalid 'openapi' field");
+        throw new SpecViolationError("Invalid spec: missing or invalid 'openapi' field", 'openapi-field');
     }
     const openapiVersion = spec.openapi;
-    // Extract major.minor version
-    const versionMatch = openapiVersion.match(/^(\d+\.\d+)/);
-    if (!versionMatch) {
-        throw new Error(`Invalid OpenAPI version format: ${openapiVersion}`);
+    // The version must be major.minor, optionally with a patch segment.
+    if (!openapiVersion.match(/^\d+\.\d+(\.\d+)?$/)) {
+        throw new SpecViolationError(`Invalid OpenAPI version format: ${openapiVersion}`, 'openapi-field');
     }
-    const majorMinorVersion = versionMatch[1];
+    // The format check above guarantees two leading numeric segments.
+    const majorMinorVersion = openapiVersion.split('.').slice(0, 2).join('.');
     // Validate supported versions
     const supportedVersions = ['3.0', '3.1', '3.2'];
     if (!supportedVersions.includes(majorMinorVersion)) {
+        // Unsupported feature, not a spec violation — the document is valid.
         throw new Error(`Unsupported OpenAPI version: ${openapiVersion}. ` +
             `Supported versions: ${supportedVersions.join(', ')}`);
     }
@@ -40,8 +43,24 @@ export function detectSpecVersion(rawSpec) {
  * dialect; `preserveRefSiblings` follows the effective dialect.
  */
 export function resolveVersion(doc, override) {
-    const detected = detectSpecVersion(doc);
+    let detected;
+    try {
+        detected = detectSpecVersion(doc);
+    }
+    catch (error) {
+        if (error instanceof SpecViolationError) {
+            // The dialect is unknown (or the document is not a document at all), so
+            // the link targets the dialect being applied; the override decides when
+            // given, otherwise the latest dialect. Two-space indent: this error is
+            // thrown standalone, not as a `  - ` bullet of validateSpec's message.
+            throw new Error(`${error.message}\n  ${specLinkUrl(override ?? '3.1', error.linkKey)}`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
     if (detected !== '3.0' && detected !== '3.1') {
+        // Unsupported feature, not a spec violation — the document is valid.
         throw new Error('OpenAPI 3.2 is not yet supported. Supported versions: 3.0, 3.1');
     }
     const effective = override ?? detected;

package/dist/runtime/defined-errors.d.ts

@@ -9,8 +9,9 @@ export declare function decorateWithErrors<T, E>(item: T, runtimeErrors: unknown
 };
 /**
  * Type guard that narrows a caught error to a method's defined error union.
- * Returns false for `UnspecifiedApiError` (status not declared in the spec)
- * and for anything that is not an `ApiError`.
+ * Returns false for `UnspecifiedApiError` (status not declared in the spec),
+ * for `DefaultApiError` (declared `default` response - not part of the
+ * per-status error union), and for anything that is not an `ApiError`.
  */
 export declare function isDefinedError<E extends ApiError<number, unknown>>(err: unknown, _fn: {
     __definedErrors: E;

package/dist/runtime/defined-errors.js

@@ -1,4 +1,4 @@
-import { ApiError, UnspecifiedApiError } from './errors.js';
+import { ApiError, DefaultApiError, UnspecifiedApiError } from './errors.js';
 /**
  * Attaches the `__definedErrors` metadata property to a client method.
  * The property carries the method's error codes and is used by
@@ -15,12 +15,15 @@ export function decorateWithErrors(item, runtimeErrors) {
 }
 /**
  * Type guard that narrows a caught error to a method's defined error union.
- * Returns false for `UnspecifiedApiError` (status not declared in the spec)
- * and for anything that is not an `ApiError`.
+ * Returns false for `UnspecifiedApiError` (status not declared in the spec),
+ * for `DefaultApiError` (declared `default` response - not part of the
+ * per-status error union), and for anything that is not an `ApiError`.
  */
 export function isDefinedError(err, _fn) {
     if (err instanceof UnspecifiedApiError)
         return false;
+    if (err instanceof DefaultApiError)
+        return false;
     if (!(err instanceof ApiError))
         return false;
     return true;

package/dist/runtime/errors.d.ts

@@ -16,9 +16,7 @@ export declare class UnspecifiedApiError extends ApiError<number, unknown> {
     constructor(status: number, data: unknown, message: string);
 }
 /** Error thrown for operations that declare a `default` response. */
-export declare class DefaultApiError<TData> extends Error {
-    readonly status: number;
-    readonly data: TData;
+export declare class DefaultApiError<TData> extends ApiError<number, TData> {
     constructor(status: number, data: TData, message: string);
 }
 /** Wraps unexpected failures inside a `Requester` implementation. */

package/dist/runtime/errors.js

@@ -24,13 +24,9 @@ export class UnspecifiedApiError extends ApiError {
     }
 }
 /** Error thrown for operations that declare a `default` response. */
-export class DefaultApiError extends Error {
-    status;
-    data;
+export class DefaultApiError extends ApiError {
     constructor(status, data, message) {
-        super(message);
-        this.status = status;
-        this.data = data;
+        super(status, data, message);
         this.name = 'DefaultApiError';
     }
 }

package/dist/runtime/index.d.ts

@@ -8,4 +8,4 @@
 export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError } from './errors.js';
 export { StreamResponse, ErrorResponse } from './responses.js';
 export { decorateWithErrors, isDefinedError } from './defined-errors.js';
-export type { Requester } from './requester.js';
+export type { Requester, SecurityScheme, SecurityCall, SecurityRequirement, OAuthFlow, OAuthFlows, } from './requester.js';

package/dist/runtime/requester.d.ts

@@ -1,14 +1,81 @@
 import type { ErrorResponse, StreamResponse } from './responses.js';
+/**
+ * OAuth 2.0 flow configuration, spec-agnostic structural twin of the OpenAPI
+ * OAuth Flow Object. Which URLs are meaningful depends on the flow kind.
+ */
+export type OAuthFlow = {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+};
+/**
+ * OAuth 2.0 flows, spec-agnostic structural twin of the OpenAPI OAuth Flows
+ * Object.
+ */
+export type OAuthFlows = {
+    implicit?: OAuthFlow;
+    password?: OAuthFlow;
+    clientCredentials?: OAuthFlow;
+    authorizationCode?: OAuthFlow;
+};
+/**
+ * Spec-agnostic structural twin of an OpenAPI security scheme object,
+ * discriminated on `type` so implementations can narrow.
+ */
+export type SecurityScheme = {
+    type: 'apiKey';
+    name: string;
+    in: string;
+    description?: string;
+} | {
+    type: 'http';
+    scheme: string;
+    bearerFormat?: string;
+    description?: string;
+} | {
+    type: 'oauth2';
+    flows: OAuthFlows;
+    description?: string;
+} | {
+    type: 'openIdConnect';
+    openIdConnectUrl: string;
+    description?: string;
+} | {
+    type: 'mutualTLS';
+    description?: string;
+};
+/**
+ * One scheme invocation inside a security requirement: the scheme name as
+ * declared in the spec, the scopes requested for it, and the resolved scheme
+ * object.
+ */
+export type SecurityCall = {
+    schemeName: string;
+    scopes: readonly string[];
+    scheme: SecurityScheme;
+};
+/**
+ * One security alternative. Several `SecurityCall`s inside one requirement are
+ * conjunctive — all must be satisfied.
+ */
+export type SecurityRequirement = readonly SecurityCall[];
 /**
  * Performs an HTTP request and returns the response.
  *
  * When `expectStream` is true, the implementation should return
  * a `StreamResponse` containing the stream data, filename (from
  * Content-Disposition header), and response headers.
+ *
+ * When `security` is present, it carries the operation's security requirements
+ * as an OR-list of AND-alternatives (spec `security` semantics): satisfying any
+ * one requirement authorizes the request. Each call carries the fully resolved
+ * scheme object. Absent `security` means the operation is public.
  */
 export type Requester = <TResponse>(method: string, path: string, options: {
     query?: Record<string, unknown>;
     body?: unknown;
     headers?: Record<string, string>;
     expectStream?: true;
+    security?: readonly SecurityRequirement[];
 }) => Promise<TResponse | StreamResponse | ErrorResponse>;

package/dist/types/openapi.d.ts

@@ -72,7 +72,7 @@ export type OperationObject = {
     requestBody?: RequestBodyObject | ReferenceObject;
     responses: ResponsesObject;
     deprecated?: boolean;
-    security?: unknown[];
+    security?: SecurityRequirementObject[];
     servers?: unknown[];
 };
 export type PathItemObject = {
@@ -140,8 +140,9 @@ export type OAuth2FlowsObject = {
     clientCredentials?: OAuth2FlowClientCredentials;
     authorizationCode?: OAuth2FlowAuthorizationCode;
 };
+export type SecurityRequirementObject = Record<string, string[]>;
 export type SecuritySchemeObject = {
-    type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+    type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect' | 'mutualTLS';
     description?: string;
     name?: string;
     in?: 'query' | 'header' | 'cookie';
@@ -156,7 +157,7 @@ export type ComponentsObject = {
     parameters?: Record<string, ParameterObject | ReferenceObject>;
     requestBodies?: Record<string, RequestBodyObject | ReferenceObject>;
     headers?: Record<string, unknown>;
-    securitySchemes?: Record<string, SecuritySchemeObject>;
+    securitySchemes?: Record<string, SecuritySchemeObject | ReferenceObject>;
     links?: Record<string, unknown>;
     callbacks?: Record<string, unknown>;
     examples?: Record<string, unknown>;
@@ -167,7 +168,7 @@ export type OpenAPIDocument = {
     servers?: ServerObject[];
     paths?: PathsObject;
     components?: ComponentsObject;
-    security?: unknown[];
+    security?: SecurityRequirementObject[];
     tags?: unknown[];
     externalDocs?: {
         description?: string;

package/dist/utils/http-methods.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The eight OpenAPI Operation Object HTTP methods, in canonical generation
+ * order (the order methods appear in generated clients).
+ *
+ * Single source shared by the analyzer (path-item iteration) and the
+ * validators (per-operation checks) — do not inline local copies.
+ */
+export declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete", "options", "head", "trace"];

package/dist/utils/http-methods.js

@@ -0,0 +1,17 @@
+/**
+ * The eight OpenAPI Operation Object HTTP methods, in canonical generation
+ * order (the order methods appear in generated clients).
+ *
+ * Single source shared by the analyzer (path-item iteration) and the
+ * validators (per-operation checks) — do not inline local copies.
+ */
+export const HTTP_METHODS = [
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'options',
+    'head',
+    'trace',
+];

package/dist/utils/operation-naming.js

@@ -44,6 +44,7 @@ export const RESERVED_TYPE_NAMES = new Set([
     ...RUNTIME_CLASS_NAMES,
     ...CLIENT_SURFACE_NAMES,
     'FileInput',
+    'SecuritySchemeName',
 ]);
 /**
  * Build a PascalCase type-name prefix from an operation's method + path.
@@ -151,6 +152,11 @@ export function clientImportedNames(op) {
         names.push(emissions.headers);
     if (emissions.body !== undefined)
         names.push(emissions.body);
+    // `$ref` path params reference named contract types directly in the method
+    // signature, so the client file must import them (fact collected by
+    // `analyze()` from the mapper's import list).
+    if (op.pathParamTypeNames !== undefined)
+        names.push(...op.pathParamTypeNames);
     if (emissions.response !== undefined) {
         const successType = getSuccessType(op);
         if (successType !== 'void' && successType !== 'unknown' && /^[A-Z]/.test(successType)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genoc",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Generate typed HTTP clients from OpenAPI 3.0 / 3.1 specifications",
   "keywords": [
     "client",