@edium/halifax 2.1.0 → 2.2.1

package/dist/core/hooks.d.ts

@@ -0,0 +1,217 @@
+import type { AuthContext } from '../auth/AuthStrategy.js';
+import type { HttpRequest, ListOptions, ListResult, QueryResult, UpdateManyResult, DeleteManyResult, ResourceDefinition } from '../core/types.js';
+import type { IQueryOptions } from '@edium/halifax-types';
+/** Synchronous or asynchronous return — hook functions may return either. */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Context object passed to every hook function. Provides the caller's resolved auth, the
+ * normalized resource definition, and the raw HTTP request so hooks have access to headers,
+ * IP addresses, and any properties set by upstream framework middleware.
+ */
+export interface HookContext {
+    /** Resolved identity and permissions for the current caller. */
+    auth: AuthContext;
+    /** The normalized resource being accessed (name, fields, routePrefix, etc.). */
+    resource: ResourceDefinition;
+    /** The incoming HTTP request — access headers, the raw framework request, etc. */
+    req: HttpRequest;
+}
+/**
+ * Lifecycle hooks for a single Halifax resource.
+ *
+ * Attach these under `ResourceDefinition.hooks` to inject custom logic before or after
+ * any CRUD operation without writing a custom repository or HTTP middleware.
+ *
+ * **Before hooks** receive the incoming data and can:
+ * - Return a **modified copy** to replace the payload going into the database.
+ * - Return **`void` / `undefined`** to leave the data unchanged.
+ * - **Throw** any error to abort the operation — Halifax catches it and sends the
+ *   appropriate HTTP error response. Use Halifax's own error classes
+ *   (`AuthorizationError`, `BadRequestError`, `UnprocessableEntityError`, …) for
+ *   precise status codes.
+ *
+ * **After hooks** receive the outgoing result and can:
+ * - Return a **modified copy** to replace what is sent to the client.
+ * - Return **`void` / `undefined`** to leave the result unchanged.
+ * - **Throw** to replace a successful DB result with an error response (rare but valid).
+ *
+ * After hooks run after the database write but **before** response field-filtering
+ * (`readRoles` / `selectable`). The hook therefore sees every field the DB returned, not
+ * just the fields the caller is allowed to read.
+ *
+ * Method syntax is intentional — TypeScript applies bivariant parameter checking to
+ * interface methods, which allows a typed `CrudHooks<Post>` to be assigned to an
+ * untyped `CrudHooks` (the generic defaults to `unknown`) without a cast.
+ *
+ * @template TRecord Shape of a full record returned by the server.
+ * @template TCreate Shape of a create payload.
+ * @template TUpdate Shape of an update payload.
+ *
+ * @example Stamp audit fields and emit events
+ * ```ts
+ * const posts: ResourceDefinition = {
+ *   routePrefix: 'posts',
+ *   repository: new PrismaAdapter({ delegate: prisma.post }),
+ *   hooks: {
+ *     beforeCreate: (data, { auth }) => ({ ...data, createdBy: auth.userId }),
+ *     afterCreate:  async (result)   => { await events.emit('post.created', result) },
+ *     beforeUpdateOne: (id, data, { auth }) => ({ ...data, updatedBy: auth.userId }),
+ *   }
+ * }
+ * ```
+ */
+export interface CrudHooks<TRecord = unknown, TCreate = Partial<TRecord>, TUpdate = Partial<TRecord>> {
+    /**
+     * Fired once **per record** before it is inserted — for both single-object and array POST bodies.
+     *
+     * Return a modified payload to replace the incoming data, or `void` to use as-is.
+     * Throw to abort the entire create operation.
+     *
+     * @example Stamp `createdBy` from the auth context:
+     * ```ts
+     * beforeCreate: (data, { auth }) => ({ ...data, createdBy: auth.userId })
+     * ```
+     */
+    beforeCreate?(data: TCreate, ctx: HookContext): MaybePromise<TCreate | void>;
+    /**
+     * Fired once **per record** after it is inserted — for both single and bulk POST.
+     *
+     * Return a modified record to replace what is sent to the client, or `void` to use as-is.
+     * Readable-field filtering (`readRoles` / `selectable`) is applied after this hook.
+     *
+     * @example Emit a domain event:
+     * ```ts
+     * afterCreate: async (result, { resource }) => {
+     *   await events.emit(`${resource.name}.created`, result)
+     * }
+     * ```
+     */
+    afterCreate?(result: TRecord, ctx: HookContext): MaybePromise<TRecord | void>;
+    /**
+     * Fired before a single record is fetched by ID (`GET /resource/:id`).
+     *
+     * Cannot modify the ID — use this for additional ownership/authorization checks or
+     * audit logging. Throw to block the read.
+     *
+     * @example Block reads on records not owned by the caller:
+     * ```ts
+     * beforeReadOne: async (id, { auth }) => {
+     *   const record = await db.find(id)
+     *   if (record.ownerId !== auth.userId) throw new AuthorizationError()
+     * }
+     * ```
+     */
+    beforeReadOne?(id: string | number, ctx: HookContext): MaybePromise<void>;
+    /**
+     * Fired after a single record is fetched.
+     * Return a modified record or `void` to use as-is (e.g. attach computed / virtual fields).
+     */
+    afterReadOne?(result: TRecord, ctx: HookContext): MaybePromise<TRecord | void>;
+    /**
+     * Fired before a paginated list query (`GET /resource`).
+     *
+     * Return modified `ListOptions` to adjust pagination, inject extra filters, or force a
+     * sort — or `void` to leave the options unchanged.
+     *
+     * @example Restrict results to the caller's own records:
+     * ```ts
+     * beforeReadMany: (options, { auth }) => ({
+     *   ...options,
+     *   where: { ...options.where, ownerId: auth.userId }
+     * })
+     * ```
+     */
+    beforeReadMany?(options: ListOptions, ctx: HookContext): MaybePromise<ListOptions | void>;
+    /**
+     * Fired after a list query.
+     * Return a modified `ListResult` or `void` (e.g. annotate each record or replace `count`).
+     */
+    afterReadMany?(result: ListResult<TRecord>, ctx: HookContext): MaybePromise<ListResult<TRecord> | void>;
+    /**
+     * Fired before a single-record update (`PATCH /resource/:id`).
+     * Return modified data or `void`. Throw to abort.
+     *
+     * @example Stamp `updatedBy` and `updatedAt`:
+     * ```ts
+     * beforeUpdateOne: (id, data, { auth }) => ({
+     *   ...data,
+     *   updatedBy: auth.userId,
+     *   updatedAt: new Date().toISOString()
+     * })
+     * ```
+     */
+    beforeUpdateOne?(id: string | number, data: TUpdate, ctx: HookContext): MaybePromise<TUpdate | void>;
+    /**
+     * Fired after a single-record update.
+     * Return a modified record or `void` to use as-is.
+     */
+    afterUpdateOne?(result: TRecord, ctx: HookContext): MaybePromise<TRecord | void>;
+    /**
+     * Fired before a bulk update (`PATCH /resource` with a query body).
+     *
+     * Use for authorization checks or audit logging. Throw to abort.
+     * The query and update data cannot be modified from this hook — throw if the operation
+     * should be blocked, or use a custom repository wrapper for query rewriting.
+     */
+    beforeUpdateMany?(query: IQueryOptions, data: TUpdate, ctx: HookContext): MaybePromise<void>;
+    /**
+     * Fired after a bulk update.
+     * Return a modified `UpdateManyResult` or `void` to use as-is.
+     */
+    afterUpdateMany?(result: UpdateManyResult<TRecord>, ctx: HookContext): MaybePromise<UpdateManyResult<TRecord> | void>;
+    /**
+     * Fired before an upsert (`PUT /resource/:id`).
+     * Return modified data or `void`. Throw to abort.
+     */
+    beforeUpsertOne?(id: string | number, data: TCreate & TUpdate, ctx: HookContext): MaybePromise<(TCreate & TUpdate) | void>;
+    /**
+     * Fired after an upsert.
+     * Return a modified record or `void` to use as-is.
+     */
+    afterUpsertOne?(result: TRecord, ctx: HookContext): MaybePromise<TRecord | void>;
+    /**
+     * Fired before a single-record delete (`DELETE /resource/:id`).
+     *
+     * Use for cascades, soft-delete interceptors, or authorization checks. Throw to abort.
+     * The record still exists in the database when this hook fires.
+     */
+    beforeDeleteOne?(id: string | number, ctx: HookContext): MaybePromise<void>;
+    /**
+     * Fired after a single-record delete.
+     * The record is already gone from the database. Use for cleanup, event emission, or audit.
+     */
+    afterDeleteOne?(id: string | number, ctx: HookContext): MaybePromise<void>;
+    /**
+     * Fired before a bulk delete (`DELETE /resource` with a query body).
+     * Use for authorization checks or audit logging. Throw to abort.
+     */
+    beforeDeleteMany?(query: IQueryOptions, ctx: HookContext): MaybePromise<void>;
+    /**
+     * Fired after a bulk delete.
+     * Return a modified `DeleteManyResult` or `void` to use as-is.
+     */
+    afterDeleteMany?(result: DeleteManyResult, ctx: HookContext): MaybePromise<DeleteManyResult | void>;
+    /**
+     * Fired before a query-builder execution (`POST /resource/query`).
+     *
+     * Return a modified `IQueryOptions` to augment or restrict the query (e.g. inject a
+     * mandatory tenant filter that the client cannot remove), or `void` to use as-is.
+     *
+     * @example Inject a mandatory filter the client cannot remove:
+     * ```ts
+     * beforeQuery: (query, { auth }) => ({
+     *   ...query,
+     *   where: [
+     *     ...(query.where ?? []),
+     *     { field: 'tenantId', comparison: '=', value: auth.tenantId, operator: 'AND' }
+     *   ]
+     * })
+     * ```
+     */
+    beforeQuery?(query: IQueryOptions, ctx: HookContext): MaybePromise<IQueryOptions | void>;
+    /**
+     * Fired after a query-builder execution.
+     * Return a modified `QueryResult` or `void` to use as-is.
+     */
+    afterQuery?(result: QueryResult<TRecord>, ctx: HookContext): MaybePromise<QueryResult<TRecord> | void>;
+}

package/dist/core/queryString.js

@@ -1,4 +1,4 @@
-import { SqlOrder } from '../enums/SqlOrder.js';
+import { SqlOrder } from '@edium/halifax-types';
 import { UnprocessableEntityError } from '../errors/UnprocessableEntityError.js';
 import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '../core/types.js';
 import { isValidInt32, validateFields, validateIncludes, validateQueryString, validateSelectableFields, validateSortableFields } from '../core/validation.js';

package/dist/core/types.d.ts

@@ -1,4 +1,6 @@
-import type { IQueryOptions } from '../interfaces/IQueryOptions.js';
+import type { IQueryOptions, ListResult, QueryResult, UpdateManyResult, DeleteManyResult } from '@edium/halifax-types';
+import type { CrudHooks } from '../core/hooks.js';
+export type { ListResult, QueryResult, UpdateManyResult, DeleteManyResult };
 /** HTTP methods supported by Halifax routes. `'*'` matches any method (used for 405 fallbacks). */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | '*';
 /** Framework-agnostic representation of an incoming HTTP request. */
@@ -84,32 +86,6 @@ export interface ListOptions {
     /** Relation names to eager-load. */
     include?: string[] | undefined;
 }
-/** Paginated result envelope returned by `getMany`. */
-export interface ListResult<TRecord> {
-    /** Total number of matching records (before pagination). */
-    count: number;
-    /** Records for the current page. */
-    results: TRecord[];
-}
-/** Result envelope returned by `deleteMany`. */
-export interface DeleteManyResult {
-    /** IDs (or records) of the deleted rows. */
-    deleted: unknown[];
-}
-/** Result envelope returned by `updateMany`. */
-export interface UpdateManyResult<TRecord> {
-    /** IDs of the updated rows. */
-    updated: unknown[];
-    /** Updated records, when the adapter supports returning them. */
-    results?: TRecord[];
-}
-/** Result envelope returned by `executeQuery`. */
-export interface QueryResult<TRecord> {
-    /** Total number of matching records (before pagination). */
-    count?: number;
-    /** Records for the current page. */
-    results: TRecord[];
-}
 /** Options passed to `createOne` / `createMany` for idempotent writes. */
 export interface CreateOptions {
     /** An idempotency key — the adapter may de-duplicate requests with the same key. */
@@ -248,6 +224,8 @@ export interface ModelField {
     isReadOnly: boolean;
     /** True when Prisma provides a default value (e.g. `@default(autoincrement())`). */
     hasDefault: boolean;
+    /** Prisma scalar type name (e.g. `'String'`, `'Int'`, `'Boolean'`, `'DateTime'`). Used for OpenAPI type inference. */
+    type?: string;
 }
 /** Minimal shape of a Prisma DMMF model — structurally compatible with `Prisma.DMMF.Model`. */
 export interface ModelSchema {
@@ -277,9 +255,14 @@ export interface ModelResourceOptions {
     defaultLimit?: number;
     /** Hard cap on page size. Requests above this are silently capped. */
     maxLimit?: number;
-    /** Maximum nesting depth for WHERE clause children (default: 3). */
+    /** Maximum nesting depth for WHERE clause children (default: 4). */
     maxFilterDepth?: number;
 }
+/**
+ * OpenAPI-compatible scalar type for a field. Used for spec generation only — has no effect
+ * on runtime behaviour. Auto-populated by `PrismaAdapter`; set manually for custom repositories.
+ */
+export type FieldType = 'string' | 'integer' | 'number' | 'boolean' | 'object';
 /**
  * Describes a single column exposed through the Halifax API.
  *
@@ -299,6 +282,24 @@ export interface FieldDefinition {
     selectable?: boolean;
     /** When `false`, the field is stripped from POST/PATCH/PUT bodies. Defaults to `true` (except the primary key). */
     writable?: boolean;
+    /** OpenAPI scalar type. Auto-populated from Prisma DMMF; set manually for non-Prisma fields. Defaults to `'string'`. */
+    type?: FieldType;
+    /** OpenAPI format modifier (e.g. `'date-time'`, `'int64'`, `'binary'`). Auto-populated from Prisma DMMF. */
+    format?: string;
+    /**
+     * Roles or permissions required to **read** this field. Any single match grants access.
+     * When absent or empty, any authenticated caller can read the field (no restriction).
+     * Values are matched against `AuthContext.roles` and `AuthContext.permissions`.
+     */
+    readRoles?: string[];
+    /**
+     * Roles or permissions required to **write** this field. Any single match grants access.
+     * Fields the caller cannot write are silently dropped from POST/PATCH/PUT bodies
+     * (consistent with how `writable: false` behaves). When absent or empty, any caller
+     * with general write access can write this field.
+     * Values are matched against `AuthContext.roles` and `AuthContext.permissions`.
+     */
+    writeRoles?: string[];
 }
 /**
  * Declares that a resource is tenant-scoped: every request is confined to rows whose
@@ -371,8 +372,16 @@ export interface ResourceDefinition<TRecord = unknown, TCreate = Partial<TRecord
      * the cap entirely — combine `defaultLimit: 0` and `maxLimit: 0` to disable pagination.
      */
     maxLimit?: number;
-    /** Maximum nesting depth for WHERE clause children. Defaults to 3. */
+    /** Maximum nesting depth for WHERE clause children. Defaults to 4. */
     maxFilterDepth?: number;
+    /**
+     * Lifecycle hooks for this resource. Halifax calls these before and after every CRUD
+     * operation, letting you inject custom logic — validation, auditing, event emission,
+     * data transformation — without writing a custom repository or HTTP middleware.
+     *
+     * See {@link CrudHooks} for the full list of available hooks and their signatures.
+     */
+    hooks?: CrudHooks<TRecord, TCreate, TUpdate>;
     /**
      * Read-through caching for this resource. When set, the router caches
      * `getOne`/`getMany`/query reads and invalidates them on any write to this resource.

package/dist/core/validation.d.ts

@@ -1,5 +1,4 @@
-import type { IQueryFilter } from '../interfaces/IQueryFilter.js';
-import type { IQueryOptions } from '../interfaces/IQueryOptions.js';
+import type { IQueryFilter, IQueryOptions } from '@edium/halifax-types';
 import type { ResourceDefinition } from '../core/types.js';
 /**
  * Returns `true` when `value` is a safe 32-bit integer >= `min`.

package/dist/core/validation.js

@@ -1,7 +1,5 @@
 import { validate as uuidValidate } from 'uuid';
-import { SqlComparison } from '../enums/SqlComparison.js';
-import { SqlOperator } from '../enums/SqlOperator.js';
-import { SqlOrder } from '../enums/SqlOrder.js';
+import { SqlComparison, SqlOperator, SqlOrder } from '@edium/halifax-types';
 import { BadRequestError } from '../errors/BadRequestError.js';
 import { UnprocessableEntityError } from '../errors/UnprocessableEntityError.js';
 const reservedQueryStringProperties = ['fields', 'limit', 'offset', 'order', 'include'];

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 export * from './adapters/http/ExpressAdapter.js';
+export * from './openapi/index.js';
 export * from './adapters/orm/prisma/index.js';
 export * from './auth/AuthStrategy.js';
 export * from './core/cache/index.js';
 export * from './core/crudRouter.js';
+export * from './core/hooks.js';
 export * from './core/queryString.js';
 export * from './core/types.js';
 export * from './core/validation.js';
-export * from './enums/SqlComparison.js';
-export * from './enums/SqlOperator.js';
-export * from './enums/SqlOrder.js';
+export * from '@edium/halifax-types';
 export * from './errors/AuthenticationError.js';
 export * from './errors/AuthorizationError.js';
 export * from './errors/BadRequestError.js';
@@ -20,6 +20,3 @@ export * from './errors/NotImplementedError.js';
 export * from './errors/ServerError.js';
 export * from './errors/UnprocessableEntityError.js';
 export * from './errors/UnsupportedMediaTypeError.js';
-export * from './interfaces/IQueryFilter.js';
-export * from './interfaces/IQueryOptions.js';
-export * from './interfaces/ISort.js';

package/dist/index.js

@@ -1,14 +1,14 @@
 export * from './adapters/http/ExpressAdapter.js';
+export * from './openapi/index.js';
 export * from './adapters/orm/prisma/index.js';
 export * from './auth/AuthStrategy.js';
 export * from './core/cache/index.js';
 export * from './core/crudRouter.js';
+export * from './core/hooks.js';
 export * from './core/queryString.js';
 export * from './core/types.js';
 export * from './core/validation.js';
-export * from './enums/SqlComparison.js';
-export * from './enums/SqlOperator.js';
-export * from './enums/SqlOrder.js';
+export * from '@edium/halifax-types';
 export * from './errors/AuthenticationError.js';
 export * from './errors/AuthorizationError.js';
 export * from './errors/BadRequestError.js';
@@ -20,6 +20,3 @@ export * from './errors/NotImplementedError.js';
 export * from './errors/ServerError.js';
 export * from './errors/UnprocessableEntityError.js';
 export * from './errors/UnsupportedMediaTypeError.js';
-export * from './interfaces/IQueryFilter.js';
-export * from './interfaces/IQueryOptions.js';
-export * from './interfaces/ISort.js';

package/dist/openapi/generateDocsHtml.d.ts

@@ -0,0 +1 @@
+export declare function generateDocsHtml(specPath: string, docsPath: string): string;

package/dist/openapi/generateDocsHtml.js

@@ -0,0 +1,47 @@
+export function generateDocsHtml(specPath, docsPath) {
+    // Build a browser-relative URL so it works at any router mount prefix.
+    const specParts = specPath.replace(/^\//, '').split('/');
+    const docsDirParts = docsPath.replace(/^\//, '').split('/').slice(0, -1);
+    const specFilename = specParts[specParts.length - 1] ?? 'openapi.json';
+    const specDirParts = specParts.slice(0, -1);
+    let common = 0;
+    while (common < specDirParts.length &&
+        common < docsDirParts.length &&
+        specDirParts[common] === docsDirParts[common])
+        common++;
+    const ups = docsDirParts.length - common;
+    const downs = specDirParts.slice(common);
+    const upSegments = new Array(ups).fill('..');
+    const relSpecUrl = [...upSegments, ...downs, specFilename].join('/') || specFilename;
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>API Docs</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
+  <style>
+    body { margin: 0; }
+    .swagger-ui .topbar { display: none; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
+  <script>
+    window.onload = function () {
+      SwaggerUIBundle({
+        url: new URL('${relSpecUrl}', window.location.href).href,
+        dom_id: '#swagger-ui',
+        presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+        layout: 'BaseLayout',
+        deepLinking: true,
+        tryItOutEnabled: true,
+        persistAuthorization: true,
+        filter: true
+      })
+    }
+  </script>
+</body>
+</html>`;
+}

package/dist/openapi/index.d.ts

@@ -0,0 +1,3 @@
+export { generateOpenApiSpec } from './specGenerator.js';
+export { generateDocsHtml } from './generateDocsHtml.js';
+export type { OpenApiOptions } from './specGenerator.js';

package/dist/openapi/index.js

@@ -0,0 +1,2 @@
+export { generateOpenApiSpec } from './specGenerator.js';
+export { generateDocsHtml } from './generateDocsHtml.js';

package/dist/openapi/specGenerator.d.ts

@@ -0,0 +1,149 @@
+import { type ResourceDefinition } from '../core/types.js';
+import type { SecurityScheme } from '../auth/AuthStrategy.js';
+/** Options for OpenAPI spec generation and the built-in docs UI. */
+export interface OpenApiOptions {
+    /**
+     * Set `false` to disable OpenAPI entirely (routes not registered, spec not generated).
+     * Useful for conditionally enabling in non-production environments:
+     *
+     * ```ts
+     * openapi: {
+     *   enabled: process.env.NODE_ENV !== 'production',
+     *   title: 'My API'
+     * }
+     * ```
+     *
+     * Defaults to `true` when the `openapi` option object is present.
+     */
+    enabled?: boolean;
+    /** API title shown in the docs. Defaults to `'Halifax API'`. */
+    title?: string;
+    /** API version string shown in the docs. Defaults to `'1.0.0'`. */
+    version?: string;
+    /** Optional markdown description shown at the top of the docs. */
+    description?: string;
+    /** Server URLs listed in the spec (e.g. `[{ url: 'https://api.example.com/v1' }]`). */
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    /**
+     * API-wide response envelope key — mirrors the `envelope` option on `CrudApiOptions`.
+     * When set, every success response body is wrapped under this key.
+     * Per-resource `ResourceDefinition.envelope` takes precedence.
+     */
+    envelope?: string | null;
+    /**
+     * Path for the raw OpenAPI JSON endpoint, relative to the router mount point.
+     * Defaults to `'/openapi.json'` → full path is `<mountPoint>/openapi.json`.
+     */
+    specPath?: string;
+    /**
+     * Path for the Swagger UI docs page, relative to the router mount point.
+     * Defaults to `'/docs'` → full path is `<mountPoint>/docs`.
+     */
+    docsPath?: string;
+    /**
+     * OpenAPI security scheme to document. When provided, Halifax adds the scheme to
+     * `components/securitySchemes` and applies it globally to all operations.
+     *
+     * This is auto-populated from the `authStrategy` when it implements `openApiScheme()`.
+     * You can override it here if you use a custom strategy or want a different description.
+     *
+     * @example API key
+     * ```ts
+     * securityScheme: { type: 'apiKey', in: 'header', name: 'X-Api-Key' }
+     * ```
+     * @example Bearer JWT
+     * ```ts
+     * securityScheme: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }
+     * ```
+     */
+    securityScheme?: SecurityScheme;
+    /**
+     * When `true`, the `/openapi.json` and `/docs` routes require authentication via the
+     * configured `authStrategy` — unauthenticated callers receive 401/403 just like any
+     * other protected route. Defaults to `false` (docs are publicly accessible).
+     */
+    requireAuth?: boolean;
+}
+type JsonSchema = {
+    type?: string | string[];
+    format?: string;
+    properties?: Record<string, JsonSchema>;
+    additionalProperties?: boolean | JsonSchema;
+    items?: JsonSchema;
+    required?: string[];
+    description?: string;
+    nullable?: boolean;
+    $ref?: string;
+    enum?: unknown[];
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    minimum?: number;
+    default?: unknown;
+    example?: unknown;
+    readOnly?: boolean;
+};
+type OpenApiParameter = {
+    name: string;
+    in: 'query' | 'path' | 'header';
+    description?: string;
+    required?: boolean;
+    schema: JsonSchema;
+};
+type OpenApiOperation = {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        required: boolean;
+        content: {
+            'application/json': {
+                schema: JsonSchema;
+            };
+        };
+    };
+    responses: Record<string, {
+        description: string;
+        content?: {
+            'application/json': {
+                schema: JsonSchema;
+            };
+        };
+    }>;
+};
+type OpenApiSecuritySchemeObject = {
+    type: 'apiKey';
+    in: string;
+    name: string;
+    description?: string;
+} | {
+    type: 'http';
+    scheme: string;
+    bearerFormat?: string;
+    description?: string;
+};
+type OpenApiSpec = {
+    openapi: '3.1.0';
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    security?: Array<Record<string, []>>;
+    paths: Record<string, Partial<Record<'get' | 'post' | 'put' | 'patch' | 'delete', OpenApiOperation>>>;
+    components: {
+        schemas: Record<string, JsonSchema>;
+        securitySchemes?: Record<string, OpenApiSecuritySchemeObject>;
+    };
+};
+export declare function generateOpenApiSpec(resources: ResourceDefinition[], options?: OpenApiOptions): OpenApiSpec;
+export {};