@sonatel-os/openapi-runtime 0.1.1 → 0.2.1

package/dist/src/auth/providers.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Authentication provider interface.
+ * @typedef {Object} AuthProvider
+ * @property {(entry: object, schemeName: string, scopes: string[], req: object) => Promise<void>} apply
+ */
+/**
+ * API Key provider options.
+ * @typedef {Object} ApiKeyOptions
+ * @property {'header' | 'query'} in - Where to place the API key
+ * @property {string} name - Header name or query param name
+ * @property {string | (() => string) | (() => Promise<string>)} getValue - Key value or getter
+ */
+/**
+ * Bearer token provider options.
+ * @typedef {Object} BearerOptions
+ * @property {string} [token] - Static token value
+ * @property {(() => string) | (() => Promise<string>)} [getToken] - Dynamic token getter
+ */
+/**
+ * Basic auth provider options.
+ * @typedef {Object} BasicOptions
+ * @property {string} [username] - Static username
+ * @property {string} [password] - Static password
+ * @property {(() => { username: string, password: string }) | (() => Promise<{ username: string, password: string }>)} [getCredentials] - Dynamic credentials getter
+ */
+/**
+ * OAuth2 Client Credentials provider options.
+ * @typedef {Object} ClientCredentialsOptions
+ * @property {string} tokenUrl - Token endpoint URL (must be HTTPS in production)
+ * @property {string} clientId - OAuth client ID
+ * @property {string} clientSecret - OAuth client secret
+ * @property {string} [scope] - OAuth scopes (space-separated)
+ * @property {string} [audience] - Token audience
+ * @property {Record<string, string>} [extraParams] - Additional token request params
+ * @property {boolean} [allowInsecure=false] - Allow HTTP for testing (DANGEROUS)
+ */
+/**
+ * Creates an API Key authentication provider.
+ *
+ * @param {ApiKeyOptions} opts - Provider options
+ * @returns {AuthProvider} Configured provider
+ * @throws {ConfigurationError} If required options are missing
+ *
+ * @example
+ * apiKey({ in: 'header', name: 'X-API-Key', getValue: () => process.env.API_KEY })
+ */
+export function apiKey({ in: placement, name, getValue }: ApiKeyOptions): AuthProvider;
+/**
+ * Creates a Basic authentication provider.
+ *
+ * @param {BasicOptions} opts - Provider options
+ * @returns {AuthProvider} Configured provider
+ *
+ * @example
+ * basic({ username: 'user', password: 'pass' })
+ * basic({ getCredentials: async () => fetchCredentials() })
+ */
+export function basic({ username, password, getCredentials }: BasicOptions): AuthProvider;
+/**
+ * Creates a Bearer token authentication provider.
+ *
+ * @param {BearerOptions} opts - Provider options
+ * @returns {AuthProvider} Configured provider
+ *
+ * @example
+ * bearer({ token: 'static-token' })
+ * bearer({ getToken: async () => await refreshToken() })
+ */
+export function bearer({ token, getToken }: BearerOptions): AuthProvider;
+/**
+ * Creates an OAuth2 Client Credentials provider with token caching.
+ *
+ * @param {ClientCredentialsOptions} opts - Provider options
+ * @returns {AuthProvider} Configured provider
+ * @throws {ConfigurationError} If required options are missing
+ * @throws {SecurityError} If tokenUrl is not HTTPS (unless allowInsecure=true)
+ *
+ * @example
+ * clientCredentials({
+ *   tokenUrl: 'https://auth.example.com/oauth/token',
+ *   clientId: 'my-app',
+ *   clientSecret: 'secret',
+ *   scope: 'read write'
+ * })
+ */
+export function clientCredentials({ tokenUrl, clientId, clientSecret, scope, audience, extraParams, allowInsecure }: ClientCredentialsOptions): AuthProvider;
+/**
+ * Authentication provider interface.
+ */
+export type AuthProvider = {
+    apply: (entry: object, schemeName: string, scopes: string[], req: object) => Promise<void>;
+};
+/**
+ * API Key provider options.
+ */
+export type ApiKeyOptions = {
+    /**
+     * - Where to place the API key
+     */
+    in: "header" | "query";
+    /**
+     * - Header name or query param name
+     */
+    name: string;
+    /**
+     * - Key value or getter
+     */
+    getValue: string | (() => string) | (() => Promise<string>);
+};
+/**
+ * Bearer token provider options.
+ */
+export type BearerOptions = {
+    /**
+     * - Static token value
+     */
+    token?: string | undefined;
+    /**
+     * - Dynamic token getter
+     */
+    getToken?: (() => string) | (() => Promise<string>) | undefined;
+};
+/**
+ * Basic auth provider options.
+ */
+export type BasicOptions = {
+    /**
+     * - Static username
+     */
+    username?: string | undefined;
+    /**
+     * - Static password
+     */
+    password?: string | undefined;
+    /**
+     * - Dynamic credentials getter
+     */
+    getCredentials?: (() => {
+        username: string;
+        password: string;
+    }) | (() => Promise<{
+        username: string;
+        password: string;
+    }>) | undefined;
+};
+/**
+ * OAuth2 Client Credentials provider options.
+ */
+export type ClientCredentialsOptions = {
+    /**
+     * - Token endpoint URL (must be HTTPS in production)
+     */
+    tokenUrl: string;
+    /**
+     * - OAuth client ID
+     */
+    clientId: string;
+    /**
+     * - OAuth client secret
+     */
+    clientSecret: string;
+    /**
+     * - OAuth scopes (space-separated)
+     */
+    scope?: string | undefined;
+    /**
+     * - Token audience
+     */
+    audience?: string | undefined;
+    /**
+     * - Additional token request params
+     */
+    extraParams?: Record<string, string> | undefined;
+    /**
+     * - Allow HTTP for testing (DANGEROUS)
+     */
+    allowInsecure?: boolean | undefined;
+};

package/dist/src/constants.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module constants
+ * @description Centralized constants - no magic values in codebase.
+ */
+/** @type {readonly string[]} Valid HTTP methods for OpenAPI operations */
+export const HTTP_METHODS: readonly string[];
+/** @type {string} Default content type for API requests/responses */
+export const DEFAULT_CONTENT_TYPE: string;
+/** @type {string} Form URL encoded content type for OAuth */
+export const FORM_URLENCODED_CONTENT_TYPE: string;
+/** @type {number} Default OAuth token expiry in seconds */
+export const DEFAULT_TOKEN_EXPIRY_SECONDS: number;
+/** @type {number} Buffer before token expiry to trigger refresh (seconds) */
+export const TOKEN_REFRESH_BUFFER_SECONDS: number;
+/** @type {number} Minimum buffer to prevent negative expiry calculations */
+export const MIN_TOKEN_BUFFER_SECONDS: number;
+/** @type {string} Default auth configuration filename */
+export const AUTH_CONFIG_FILENAME: string;
+/** @type {string} Default directory for OpenAPI spec files */
+export const SPECS_DIRECTORY: string;
+/** @type {string} Environment variable prefix for auto-detection */
+export const ENV_PREFIX: string;
+/** @type {RegExp} Pattern for valid spec names (alphanumeric, dash, underscore) */
+export const VALID_SPEC_NAME_PATTERN: RegExp;
+/** @type {RegExp} Pattern for valid operation IDs */
+export const VALID_OPERATION_ID_PATTERN: RegExp;
+/** @type {string} Required protocol for OAuth token endpoints */
+export const SECURE_PROTOCOL: string;
+/** @type {boolean} Whether to enforce HTTPS for OAuth (disable only for testing) */
+export const ENFORCE_HTTPS: boolean;

package/dist/src/core/client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Options for building a client.
+ * @typedef {Object} BuildClientOptions
+ * @property {string} name - Name to register the spec under
+ * @property {string | object} spec - URL to spec or spec object
+ */
+/**
+ * Options for executing an API request.
+ * @typedef {Object} ExecuteOptions
+ * @property {string} operationId - Operation to execute
+ * @property {Record<string, any>} [parameters] - Path/query parameters
+ * @property {any} [requestBody] - Request body
+ * @property {Record<string, string>} [headers] - Additional headers
+ * @property {Record<string, string>} [qs] - Additional query string params
+ */
+/**
+ * Builds a Swagger client for an OpenAPI spec.
+ * Resolves $refs, validates the spec, and indexes operations.
+ *
+ * @param {BuildClientOptions} opts - Client options
+ * @returns {Promise<import('./registry.js').SpecEntry>} Fully initialized spec entry
+ *
+ * @example
+ * const entry = await buildClient({
+ *   name: 'products',
+ *   spec: './specs/products.openapi.json'
+ * })
+ */
+export function buildClient({ name, spec }: BuildClientOptions): Promise<import("./registry.js").SpecEntry>;
+/**
+ * Executes an API request by operationId.
+ * Applies authentication, interceptors, and merges headers.
+ *
+ * @param {import('./registry.js').SpecEntry} entry - Spec entry
+ * @param {ExecuteOptions} req - Request options
+ * @returns {Promise<object>} API response
+ * @throws {Error} If request fails and no error interceptor handles it
+ *
+ * @example
+ * const response = await executeByOperationId(entry, {
+ *   operationId: 'getProducts',
+ *   parameters: { category: 'electronics' }
+ * })
+ */
+export function executeByOperationId(entry: import("./registry.js").SpecEntry, req: ExecuteOptions): Promise<object>;
+/**
+ * Options for building a client.
+ */
+export type BuildClientOptions = {
+    /**
+     * - Name to register the spec under
+     */
+    name: string;
+    /**
+     * - URL to spec or spec object
+     */
+    spec: string | object;
+};
+/**
+ * Options for executing an API request.
+ */
+export type ExecuteOptions = {
+    /**
+     * - Operation to execute
+     */
+    operationId: string;
+    /**
+     * - Path/query parameters
+     */
+    parameters?: Record<string, any> | undefined;
+    /**
+     * - Request body
+     */
+    requestBody?: any;
+    /**
+     * - Additional headers
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * - Additional query string params
+     */
+    qs?: Record<string, string> | undefined;
+};

package/dist/src/core/registry.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Returns the global spec registry singleton.
+ *
+ * @returns {Registry} The global registry instance
+ *
+ * @example
+ * const registry = getRegistry()
+ * registry.set('users', entry)
+ */
+export function getRegistry(): Registry;
+/**
+ * Retrieves a spec entry from the registry, throwing if not found.
+ *
+ * @param {string} name - Registered spec name
+ * @returns {SpecEntry} The spec entry
+ * @throws {SpecNotFoundError} If spec is not registered
+ *
+ * @example
+ * const entry = ensureEntry('products')
+ */
+export function ensureEntry(name: string): SpecEntry;
+/**
+ * Clears all entries from the registry.
+ * Useful for testing or cleanup.
+ *
+ * @example
+ * clearRegistry()
+ */
+export function clearRegistry(): void;
+/**
+ * Indexes all operations in a spec by operationId.
+ * Creates both a Map for fast lookup and an array for iteration.
+ *
+ * @param {object} spec - Resolved OpenAPI specification
+ * @returns {{ opsById: Map<string, object>, operations: OperationInfo[] }}
+ *
+ * @example
+ * const { opsById, operations } = indexOperations(spec)
+ * const getUsers = opsById.get('getUsers')
+ */
+export function indexOperations(spec: object): {
+    opsById: Map<string, object>;
+    operations: OperationInfo[];
+};
+/**
+ * Information about a single API operation.
+ */
+export type OperationInfo = {
+    /**
+     * - Unique operation identifier
+     */
+    operationId: string;
+    /**
+     * - HTTP method (get, post, etc.)
+     */
+    method: string;
+    /**
+     * - URL path template
+     */
+    path: string;
+    /**
+     * - Short operation description
+     */
+    summary?: string | undefined;
+    /**
+     * - Grouping tags
+     */
+    tags?: string[] | undefined;
+};
+/**
+ * A registered spec entry in the registry.
+ */
+export type SpecEntry = {
+    /**
+     * - Registered name for this spec
+     */
+    name: string;
+    /**
+     * - Swagger client instance
+     */
+    client: any;
+    /**
+     * - Resolved OpenAPI specification
+     */
+    spec: object;
+    /**
+     * - Operations indexed by operationId
+     */
+    opsById: Map<string, object>;
+    /**
+     * - List of all operations
+     */
+    operations: OperationInfo[];
+    /**
+     * - Default request options
+     */
+    defaults: {
+        headers?: Record<string, string>;
+    };
+    /**
+     * - Lifecycle hooks
+     */
+    interceptors: {
+        request?: Function;
+        response?: Function;
+        error?: Function;
+    };
+};
+/**
+ * Global registry with attached globals.
+ */
+export type Registry = Map<string, SpecEntry> & {
+    __globals: {
+        headers: Record<string, string>;
+    };
+};

package/dist/src/errors.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @module errors
+ * @description Custom error types for precise error handling and debugging.
+ */
+/**
+ * Base error class for all OpenAPI Runtime errors.
+ * @extends Error
+ */
+export class OpenAPIRuntimeError extends Error {
+    /**
+     * @param {string} message - Error message
+     * @param {string} code - Error code for programmatic handling
+     * @param {object} [details] - Additional error context
+     */
+    constructor(message: string, code: string, details?: object);
+    code: string;
+    details: object;
+    /**
+     * Convert error to JSON for logging/serialization.
+     * @returns {{ name: string, code: string, message: string, details: object }}
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        details: object;
+    };
+}
+/**
+ * Thrown when a requested spec is not found in the registry.
+ * @extends OpenAPIRuntimeError
+ */
+export class SpecNotFoundError extends OpenAPIRuntimeError {
+    /**
+     * @param {string} specName - Name of the spec that wasn't found
+     */
+    constructor(specName: string);
+}
+/**
+ * Thrown when a requested operation is not found in a spec.
+ * @extends OpenAPIRuntimeError
+ */
+export class OperationNotFoundError extends OpenAPIRuntimeError {
+    /**
+     * @param {string} operationId - The operation ID that wasn't found
+     * @param {string} [specName] - Optional spec name for context
+     */
+    constructor(operationId: string, specName?: string);
+}
+/**
+ * Thrown when authentication fails or is misconfigured.
+ * @extends OpenAPIRuntimeError
+ */
+export class AuthenticationError extends OpenAPIRuntimeError {
+    /**
+     * @param {string} message - Error description
+     * @param {Array<{ scheme: string, error: string }>} [failures] - List of auth failures
+     */
+    constructor(message: string, failures?: Array<{
+        scheme: string;
+        error: string;
+    }>);
+    failures: {
+        scheme: string;
+        error: string;
+    }[];
+}
+/**
+ * Thrown when security requirements are violated.
+ * @extends OpenAPIRuntimeError
+ */
+export class SecurityError extends OpenAPIRuntimeError {
+    /**
+     * @param {string} message - Security violation description
+     * @param {string} [violation] - Type of security violation
+     */
+    constructor(message: string, violation?: string);
+}
+/**
+ * Thrown when validation fails (request or response).
+ * @extends OpenAPIRuntimeError
+ */
+export class ValidationError extends OpenAPIRuntimeError {
+    /**
+     * @param {string} message - Validation error description
+     * @param {Array<object>} errors - AJV validation errors
+     * @param {'request' | 'response'} type - Whether request or response failed
+     */
+    constructor(message: string, errors?: Array<object>, type?: "request" | "response");
+    errors: object[];
+    validationType: "request" | "response";
+}
+/**
+ * Thrown when spec loading or parsing fails.
+ * @extends OpenAPIRuntimeError
+ */
+export class SpecLoadError extends OpenAPIRuntimeError {
+    /**
+     * @param {string} specName - Name/path of the spec that failed to load
+     * @param {string} reason - Why loading failed
+     */
+    constructor(specName: string, reason: string);
+}
+/**
+ * Thrown when configuration is invalid.
+ * @extends OpenAPIRuntimeError
+ */
+export class ConfigurationError extends OpenAPIRuntimeError {
+    /**
+     * @param {string} message - What's wrong with the configuration
+     * @param {string} [configKey] - Which config key is problematic
+     */
+    constructor(message: string, configKey?: string);
+}
+/**
+ * Thrown when input parameters are invalid.
+ * @extends OpenAPIRuntimeError
+ */
+export class InvalidInputError extends OpenAPIRuntimeError {
+    /**
+     * @param {string} message - What input is invalid
+     * @param {string} [field] - Which field is invalid
+     * @param {*} [value] - The invalid value (sanitized)
+     */
+    constructor(message: string, field?: string, value?: any);
+}