@sonatel-os/openapi-runtime 0.1.1 → 0.2.1

package/dist/src/index.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Registers an OpenAPI spec by name.
+ * Normalizes missing operationIds and auto-detects auth.
+ *
+ * @param {{ name: string, specName: string | object, autoAuth?: boolean }} opts
+ * @returns {Promise<{ name: string, operations: import('./core/registry.js').OperationInfo[] }>}
+ * @throws {InvalidInputError} If name or specName is missing/invalid
+ * @throws {SpecLoadError} If spec file cannot be loaded
+ *
+ * @example
+ * // From file
+ * await save({ name: 'products', specName: 'products.openapi.json' })
+ *
+ * // From object
+ * await save({ name: 'users', specName: openApiSpec })
+ */
+export function save({ name, specName, autoAuth }: {
+    name: string;
+    specName: string | object;
+    autoAuth?: boolean;
+}): Promise<{
+    name: string;
+    operations: import("./core/registry.js").OperationInfo[];
+}>;
+/**
+ * Re-registers a spec (alias for save).
+ *
+ * @param {Parameters<typeof save>[0]} opts - Same as save()
+ * @returns {ReturnType<typeof save>}
+ */
+export function update(opts: Parameters<typeof save>[0]): ReturnType<typeof save>;
+/**
+ * Removes a spec from the registry.
+ *
+ * @param {{ name: string }} opts
+ *
+ * @example
+ * remove({ name: 'products' })
+ */
+export function remove({ name }: {
+    name: string;
+}): void;
+/**
+ * Lists all registered spec names.
+ *
+ * @returns {string[]} Array of spec names
+ *
+ * @example
+ * const specs = listSpecs() // ['products', 'users']
+ */
+export function listSpecs(): string[];
+/**
+ * Lists all operations for a registered spec.
+ *
+ * @param {{ name: string }} opts
+ * @returns {import('./core/registry.js').OperationInfo[]}
+ * @throws {SpecNotFoundError} If spec is not registered
+ *
+ * @example
+ * const apis = listAPIs({ name: 'products' })
+ * // [{ operationId: 'getProducts', method: 'get', path: '/products' }, ...]
+ */
+export function listAPIs({ name }: {
+    name: string;
+}): import("./core/registry.js").OperationInfo[];
+/**
+ * Returns the raw OpenAPI operation object.
+ *
+ * @param {{ name: string, api: string }} opts
+ * @returns {object} OpenAPI operation object with method/path
+ * @throws {SpecNotFoundError} If spec is not registered
+ * @throws {OperationNotFoundError} If operation doesn't exist
+ *
+ * @example
+ * const contract = showContract({ name: 'products', api: 'getProducts' })
+ */
+export function showContract({ name, api }: {
+    name: string;
+    api: string;
+}): object;
+/**
+ * Generates a sample response for an operation.
+ *
+ * @param {{ name: string, api: string, status?: string | number }} opts
+ * @returns {any} Sample response data or null
+ *
+ * @example
+ * const sample = showResponseSample({ name: 'products', api: 'getProducts' })
+ */
+export function showResponseSample({ name, api, status }: {
+    name: string;
+    api: string;
+    status?: string | number;
+}): any;
+/**
+ * Generates a sample request body for an operation.
+ *
+ * @param {{ name: string, api: string }} opts
+ * @returns {any} Sample request body or null
+ *
+ * @example
+ * const sample = showRequestSample({ name: 'products', api: 'createProduct' })
+ */
+export function showRequestSample({ name, api }: {
+    name: string;
+    api: string;
+}): any;
+/**
+ * Executes an API operation.
+ *
+ * @param {{ name: string, api: string, params?: object, body?: any, headers?: object, qs?: object }} opts
+ * @returns {Promise<object>} API response
+ * @throws {SpecNotFoundError} If spec is not registered
+ * @throws {AuthenticationError} If auth is required but fails
+ *
+ * @example
+ * const response = await executeAPI({
+ *   name: 'products',
+ *   api: 'createProduct',
+ *   body: { name: 'Widget', price: 9.99 }
+ * })
+ */
+export function executeAPI({ name, api, params, body, headers, qs }: {
+    name: string;
+    api: string;
+    params?: object;
+    body?: any;
+    headers?: object;
+    qs?: object;
+}): Promise<object>;
+/**
+ * Validates data against an operation's response schema.
+ *
+ * @param {{ name: string, api: string, status: string | number, contentType?: string, data: any }} opts
+ * @returns {{ valid: boolean, errors?: object[] }}
+ *
+ * @example
+ * const result = validateResponseData({
+ *   name: 'products',
+ *   api: 'getProducts',
+ *   status: 200,
+ *   data: responseData
+ * })
+ */
+export function validateResponseData(opts: {
+    name: string;
+    api: string;
+    status: string | number;
+    contentType?: string;
+    data: any;
+}): {
+    valid: boolean;
+    errors?: object[];
+};
+/**
+ * Validates data against an operation's request schema.
+ *
+ * @param {{ name: string, api: string, body: any, contentType?: string }} opts
+ * @returns {{ valid: boolean, errors?: object[] }}
+ *
+ * @example
+ * const result = validateRequestData({
+ *   name: 'products',
+ *   api: 'createProduct',
+ *   body: productData
+ * })
+ */
+export function validateRequestData(opts: {
+    name: string;
+    api: string;
+    body: any;
+    contentType?: string;
+}): {
+    valid: boolean;
+    errors?: object[];
+};
+/**
+ * Returns a mocked response (no network call).
+ *
+ * @param {{ name: string, api: string, status?: string | number }} opts
+ * @returns {any} Mock response data
+ *
+ * @example
+ * const mock = mockAPI({ name: 'products', api: 'getProducts' })
+ */
+export function mockAPI({ name, api, status }: {
+    name: string;
+    api: string;
+    status?: string | number;
+}): any;
+/**
+ * Sets global headers applied to all specs.
+ *
+ * @param {Record<string, string>} headers
+ *
+ * @example
+ * setGlobalHeaders({ 'X-Correlation-ID': correlationId })
+ */
+export function setGlobalHeaders(headers: Record<string, string>): void;
+/**
+ * Sets default headers for a specific spec.
+ *
+ * @param {string} name - Spec name
+ * @param {Record<string, string>} headers
+ *
+ * @example
+ * setSpecHeaders('products', { 'X-Tenant': 'acme' })
+ */
+export function setSpecHeaders(name: string, headers: Record<string, string>): void;
+/**
+ * Sets interceptors for a spec.
+ *
+ * @param {string} name - Spec name
+ * @param {{ request?: Function, response?: Function, error?: Function }} interceptors
+ *
+ * @example
+ * setInterceptors('products', {
+ *   request: (req) => { console.log('Request:', req); return req },
+ *   response: (res) => { console.log('Response:', res); return res },
+ *   error: (err) => { console.error('Error:', err); throw err }
+ * })
+ */
+export function setInterceptors(name: string, interceptors: {
+    request?: Function;
+    response?: Function;
+    error?: Function;
+}): void;
+export { clearRegistry } from "./core/registry.js";
+export { setAuth, apiKey, bearer, basic, clientCredentials } from "./auth/index.js";
+export { OpenAPIRuntimeError, SpecNotFoundError, OperationNotFoundError, AuthenticationError, SecurityError, ValidationError, SpecLoadError, ConfigurationError, InvalidInputError } from "./errors.js";

package/dist/src/mocking/index.d.ts

@@ -0,0 +1 @@
+export { sampleResponse, sampleRequest, sampleParameters, generateMock } from "./sampler.js";

package/dist/src/mocking/sampler.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Sampler options.
+ * @typedef {Object} SamplerOptions
+ * @property {boolean} [skipReadOnly=false] - Skip readOnly properties
+ * @property {boolean} [skipWriteOnly=false] - Skip writeOnly properties
+ * @property {boolean} [skipNonRequired=false] - Skip non-required properties
+ */
+/**
+ * Generates a sample response for an operation.
+ *
+ * @param {import('../core/registry.js').SpecEntry} entry - Spec entry
+ * @param {string} operationId - Operation ID
+ * @param {string | number} [status] - HTTP status code (default: first 2xx or first available)
+ * @param {SamplerOptions} [options] - Sampling options
+ * @returns {any} Sample response data or null if no schema
+ *
+ * @example
+ * const mockUser = sampleResponse(entry, 'getUser', 200)
+ * // { id: 123, name: 'string', email: 'user@example.com' }
+ */
+export function sampleResponse(entry: import("../core/registry.js").SpecEntry, operationId: string, status?: string | number, options?: SamplerOptions): any;
+/**
+ * Generates a sample request body for an operation.
+ *
+ * @param {import('../core/registry.js').SpecEntry} entry - Spec entry
+ * @param {string} operationId - Operation ID
+ * @param {SamplerOptions} [options] - Sampling options
+ * @returns {any} Sample request body or null if no schema
+ *
+ * @example
+ * const mockBody = sampleRequest(entry, 'createUser')
+ * // { name: 'string', email: 'user@example.com' }
+ */
+export function sampleRequest(entry: import("../core/registry.js").SpecEntry, operationId: string, options?: SamplerOptions): any;
+/**
+ * Generates sample parameters for an operation.
+ *
+ * @param {import('../core/registry.js').SpecEntry} entry - Spec entry
+ * @param {string} operationId - Operation ID
+ * @returns {{ path: Record<string, any>, query: Record<string, any>, header: Record<string, any> }}
+ *
+ * @example
+ * const params = sampleParameters(entry, 'getUserById')
+ * // { path: { id: 123 }, query: {}, header: {} }
+ */
+export function sampleParameters(entry: import("../core/registry.js").SpecEntry, operationId: string): {
+    path: Record<string, any>;
+    query: Record<string, any>;
+    header: Record<string, any>;
+};
+/**
+ * Generates a complete mock for an operation including parameters and body.
+ *
+ * @param {import('../core/registry.js').SpecEntry} entry - Spec entry
+ * @param {string} operationId - Operation ID
+ * @returns {{ parameters: object, body: any, response: any }}
+ *
+ * @example
+ * const mock = generateMock(entry, 'createUser')
+ * // {
+ * //   parameters: { path: {}, query: {}, header: {} },
+ * //   body: { name: 'string', email: 'user@example.com' },
+ * //   response: { id: 123, name: 'string' }
+ * // }
+ */
+export function generateMock(entry: import("../core/registry.js").SpecEntry, operationId: string): {
+    parameters: object;
+    body: any;
+    response: any;
+};
+/**
+ * Sampler options.
+ */
+export type SamplerOptions = {
+    /**
+     * - Skip readOnly properties
+     */
+    skipReadOnly?: boolean | undefined;
+    /**
+     * - Skip writeOnly properties
+     */
+    skipWriteOnly?: boolean | undefined;
+    /**
+     * - Skip non-required properties
+     */
+    skipNonRequired?: boolean | undefined;
+};

package/dist/src/react/useOpenAPI.d.ts

@@ -1,6 +1,130 @@
 /**
- * React helper to bind a spec name.
- * @param {string} name
+ * Hook return type.
+ * @typedef {Object} UseOpenAPIReturn
+ * @property {(specName: string | object, options?: { autoAuth?: boolean }) => Promise<object>} save - Register a spec
+ * @property {() => import('../core/registry.js').OperationInfo[]} listAPIs - List operations
+ * @property {(api: string) => object} showContract - Get operation details
+ * @property {(api: string, status?: string | number) => any} showResponseSample - Get response sample
+ * @property {(api: string) => any} showRequestSample - Get request sample
+ * @property {(api: string, options?: { params?: object, body?: any, headers?: object, qs?: object }) => Promise<object>} executeAPI - Execute an operation
+ * @property {(api: string, options: { status: string | number, data: any, contentType?: string }) => object} validateResponse - Validate response
+ * @property {(api: string, options: { body: any, contentType?: string }) => object} validateRequest - Validate request
+ * @property {(api: string, status?: string | number) => any} mockAPI - Get mock response
  */
-export function useOpenAPI(name: string): any;
+/**
+ * Hook options.
+ * @typedef {Object} UseOpenAPIOptions
+ * @property {boolean} [throwOnError=false] - Throw errors instead of returning them
+ */
+/**
+ * React hook for OpenAPI runtime operations.
+ * Binds all operations to a specific spec name for convenience.
+ *
+ * @param {string} name - Registered spec name
+ * @param {UseOpenAPIOptions} [options] - Hook options
+ * @returns {UseOpenAPIReturn} Bound API operations
+ *
+ * @example
+ * function ProductList() {
+ *   const api = useOpenAPI('products')
+ *
+ *   useEffect(() => {
+ *     api.executeAPI('getProducts')
+ *       .then(res => setProducts(res.body))
+ *   }, [])
+ *
+ *   return <div>...</div>
+ * }
+ */
+export function useOpenAPI(name: string, options?: UseOpenAPIOptions): UseOpenAPIReturn;
+/**
+ * React hook for OpenAPI with loading/error state management.
+ *
+ * @param {string} name - Registered spec name
+ * @returns {{ api: UseOpenAPIReturn, loading: boolean, error: Error | null, execute: Function }}
+ *
+ * @example
+ * function ProductList() {
+ *   const { api, loading, error, execute } = useOpenAPIWithState('products')
+ *
+ *   const loadProducts = () => execute(
+ *     () => api.executeAPI('getProducts'),
+ *     (res) => setProducts(res.body)
+ *   )
+ *
+ *   if (loading) return <Spinner />
+ *   if (error) return <Error message={error.message} />
+ *   return <div>...</div>
+ * }
+ */
+export function useOpenAPIWithState(name: string): {
+    api: UseOpenAPIReturn;
+    loading: boolean;
+    error: Error | null;
+    execute: Function;
+};
 export default useOpenAPI;
+/**
+ * Hook return type.
+ */
+export type UseOpenAPIReturn = {
+    /**
+     * - Register a spec
+     */
+    save: (specName: string | object, options?: {
+        autoAuth?: boolean;
+    }) => Promise<object>;
+    /**
+     * - List operations
+     */
+    listAPIs: () => import("../core/registry.js").OperationInfo[];
+    /**
+     * - Get operation details
+     */
+    showContract: (api: string) => object;
+    /**
+     * - Get response sample
+     */
+    showResponseSample: (api: string, status?: string | number) => any;
+    /**
+     * - Get request sample
+     */
+    showRequestSample: (api: string) => any;
+    /**
+     * - Execute an operation
+     */
+    executeAPI: (api: string, options?: {
+        params?: object;
+        body?: any;
+        headers?: object;
+        qs?: object;
+    }) => Promise<object>;
+    /**
+     * - Validate response
+     */
+    validateResponse: (api: string, options: {
+        status: string | number;
+        data: any;
+        contentType?: string;
+    }) => object;
+    /**
+     * - Validate request
+     */
+    validateRequest: (api: string, options: {
+        body: any;
+        contentType?: string;
+    }) => object;
+    /**
+     * - Get mock response
+     */
+    mockAPI: (api: string, status?: string | number) => any;
+};
+/**
+ * Hook options.
+ */
+export type UseOpenAPIOptions = {
+    /**
+     * - Throw errors instead of returning them
+     */
+    throwOnError?: boolean | undefined;
+};

package/dist/src/utils.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Resolves the media type object from OpenAPI content map.
+ * Prefers the specified type, falls back to application/json, then first available.
+ *
+ * @param {Record<string, object> | undefined} content - OpenAPI content object
+ * @param {string} [preferredType] - Preferred content type
+ * @returns {object | null} Media type object or null if not found
+ *
+ * @example
+ * const media = resolveMediaType(response.content)
+ * const schema = media?.schema
+ */
+export function resolveMediaType(content: Record<string, object> | undefined, preferredType?: string): object | null;
+/**
+ * Retrieves an operation from a spec entry, throwing if not found.
+ *
+ * @param {import('./core/registry.js').SpecEntry} entry - Spec registry entry
+ * @param {string} operationId - Operation ID to find
+ * @returns {object} The operation object
+ * @throws {OperationNotFoundError} If operation doesn't exist
+ *
+ * @example
+ * const op = getOperation(entry, 'getUsers')
+ */
+export function getOperation(entry: import("./core/registry.js").SpecEntry, operationId: string): object;
+/**
+ * Safely merges headers, handling undefined/null cases.
+ *
+ * @param {Record<string, string> | undefined} existing - Current headers
+ * @param {Record<string, string>} additions - Headers to add
+ * @returns {Record<string, string>} Merged headers object
+ *
+ * @example
+ * req.headers = mergeHeaders(req.headers, { Authorization: 'Bearer xxx' })
+ */
+export function mergeHeaders(existing: Record<string, string> | undefined, additions: Record<string, string>): Record<string, string>;
+/**
+ * Validates a spec name against allowed pattern.
+ *
+ * @param {string} name - Spec name to validate
+ * @throws {InvalidInputError} If name is invalid
+ *
+ * @example
+ * validateSpecName('my-api') // OK
+ * validateSpecName('123bad') // throws
+ */
+export function validateSpecName(name: string): void;
+/**
+ * Validates that required fields are present in an options object.
+ *
+ * @param {object} opts - Options object to validate
+ * @param {string[]} required - List of required field names
+ * @param {string} context - Function/context name for error messages
+ * @throws {InvalidInputError} If any required field is missing
+ *
+ * @example
+ * validateRequired({ name: 'foo' }, ['name', 'spec'], 'save()')
+ */
+export function validateRequired(opts: object, required: string[], context: string): void;
+/**
+ * Resolves a value that may be a function (sync or async).
+ *
+ * @template T
+ * @param {T | (() => T) | (() => Promise<T>)} valueOrFn - Value or function
+ * @returns {Promise<T>} Resolved value
+ *
+ * @example
+ * const token = await resolveMaybeFn(getToken) // works with fn or value
+ */
+export function resolveMaybeFn<T>(valueOrFn: T | (() => T) | (() => Promise<T>)): Promise<T>;
+/**
+ * Finds the best 2xx status code from a responses object.
+ *
+ * @param {Record<string, object> | undefined} responses - OpenAPI responses object
+ * @returns {string | undefined} Best 2xx status code or first available
+ *
+ * @example
+ * const status = pick2xxStatus(operation.responses) // '200'
+ */
+export function pick2xxStatus(responses: Record<string, object> | undefined): string | undefined;
+/**
+ * Safely reads an environment variable with optional default.
+ * Supports "KEY|default" syntax for inline defaults.
+ *
+ * @param {string | undefined} keyOrExpr - Env var key or "key|default" expression
+ * @returns {string | undefined} Environment variable value or default
+ *
+ * @example
+ * getEnv('API_KEY')           // process.env.API_KEY
+ * getEnv('API_KEY|fallback')  // API_KEY value or 'fallback'
+ */
+export function getEnv(keyOrExpr: string | undefined): string | undefined;
+/**
+ * Validates that a URL uses HTTPS protocol.
+ *
+ * @param {string} url - URL to validate
+ * @param {string} context - Context for error message
+ * @throws {import('./errors.js').SecurityError} If URL is not HTTPS
+ *
+ * @example
+ * enforceHttps('https://auth.example.com/token', 'OAuth token URL')
+ */
+export function enforceHttps(url: string, context: string): void;

package/dist/src/validation/index.d.ts

@@ -0,0 +1 @@
+export { validateResponse, validateRequest, assertValidResponse, assertValidRequest, clearValidationCache } from "./validator.js";

package/dist/src/validation/validator.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Validates a response against the operation's response schema.
+ *
+ * @param {import('../core/registry.js').SpecEntry} entry - Spec entry
+ * @param {ValidateResponseOptions} opts - Validation options
+ * @returns {ValidationResult} Validation result
+ * @throws {OperationNotFoundError} If operation doesn't exist
+ *
+ * @example
+ * const result = validateResponse(entry, {
+ *   api: 'getUsers',
+ *   status: 200,
+ *   data: responseData
+ * })
+ *
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors)
+ * }
+ */
+export function validateResponse(entry: import("../core/registry.js").SpecEntry, { api, status, contentType, data }: ValidateResponseOptions): ValidationResult;
+/**
+ * Validates a request body against the operation's request schema.
+ *
+ * @param {import('../core/registry.js').SpecEntry} entry - Spec entry
+ * @param {ValidateRequestOptions} opts - Validation options
+ * @returns {ValidationResult} Validation result
+ * @throws {OperationNotFoundError} If operation doesn't exist
+ *
+ * @example
+ * const result = validateRequest(entry, {
+ *   api: 'createUser',
+ *   body: { name: 'John', email: 'john@example.com' }
+ * })
+ *
+ * if (!result.valid) {
+ *   throw new Error('Invalid request: ' + JSON.stringify(result.errors))
+ * }
+ */
+export function validateRequest(entry: import("../core/registry.js").SpecEntry, { api, body, contentType }: ValidateRequestOptions): ValidationResult;
+/**
+ * Validates response data, throwing on failure.
+ *
+ * @param {import('../core/registry.js').SpecEntry} entry - Spec entry
+ * @param {ValidateResponseOptions} opts - Validation options
+ * @throws {ValidationError} If validation fails
+ *
+ * @example
+ * assertValidResponse(entry, { api: 'getUsers', status: 200, data })
+ */
+export function assertValidResponse(entry: import("../core/registry.js").SpecEntry, opts: ValidateResponseOptions): void;
+/**
+ * Validates request body, throwing on failure.
+ *
+ * @param {import('../core/registry.js').SpecEntry} entry - Spec entry
+ * @param {ValidateRequestOptions} opts - Validation options
+ * @throws {ValidationError} If validation fails
+ *
+ * @example
+ * assertValidRequest(entry, { api: 'createUser', body: userData })
+ */
+export function assertValidRequest(entry: import("../core/registry.js").SpecEntry, opts: ValidateRequestOptions): void;
+/**
+ * Clears the compiled schema cache.
+ * Useful for testing or after spec updates.
+ */
+export function clearValidationCache(): void;
+/**
+ * Validation result.
+ */
+export type ValidationResult = {
+    /**
+     * - Whether validation passed
+     */
+    valid: boolean;
+    /**
+     * - AJV errors if invalid
+     */
+    errors?: object[] | undefined;
+};
+/**
+ * Response validation options.
+ */
+export type ValidateResponseOptions = {
+    /**
+     * - Operation ID
+     */
+    api: string;
+    /**
+     * - HTTP status code
+     */
+    status: string | number;
+    /**
+     * - Response content type
+     */
+    contentType?: string | undefined;
+    /**
+     * - Response data to validate
+     */
+    data: any;
+};
+/**
+ * Request validation options.
+ */
+export type ValidateRequestOptions = {
+    /**
+     * - Operation ID
+     */
+    api: string;
+    /**
+     * - Request body to validate
+     */
+    body: any;
+    /**
+     * - Request content type
+     */
+    contentType?: string | undefined;
+};