@api-client/core 0.19.19 → 0.19.20

package/build/src/modeling/generators/oas_312/OasGenerator.js

@@ -0,0 +1,1452 @@
+import pluralize from '@jarrodek/pluralize';
+import { OasSchemaGenerator } from './OasSchemaGenerator.js';
+import { CURSOR_PAGINATION_DEFAULT_LIMIT, CURSOR_PAGINATION_MAX_LIMIT, CURSOR_PAGINATION_MIN_LIMIT, OFFSET_PAGINATION_DEFAULT_LIMIT, OFFSET_PAGINATION_MAX_LIMIT, OFFSET_PAGINATION_MIN_LIMIT, } from '../../../runtime/constants.js';
+export class OasGenerator {
+    model;
+    whereAstInjected = false;
+    #hasListAction = false;
+    get hasListAction() {
+        return this.#hasListAction;
+    }
+    #hasSearchAction = false;
+    /**
+     * A flag that determines whether any of the entities has the `Search` action.
+     */
+    get hasSearchAction() {
+        return this.#hasSearchAction;
+    }
+    /**
+     * @param model The API model to generate OAS for.
+     */
+    constructor(model) {
+        this.model = model;
+    }
+    generate() {
+        const { domain } = this.model;
+        if (!domain) {
+            throw new Error('Data domain is required for OAS generation');
+        }
+        const schemaGen = new OasSchemaGenerator();
+        const paths = this.generatePaths(schemaGen);
+        const schemas = schemaGen.getSchemas();
+        Object.assign(schemas, this.generateErrorSchemas());
+        const securitySchemes = this.generateSecuritySchemes();
+        const components = {};
+        if (this.whereAstInjected) {
+            Object.assign(schemas, getAstComponentSchemas());
+        }
+        if (this.hasListAction || this.hasSearchAction) {
+            const paginationMeta = this.model.pagination.kind === 'cursor' ? createCursorPaginationMeta() : createOffsetPaginationMeta();
+            schemas.PaginationMeta = paginationMeta;
+        }
+        if (this.hasSearchAction) {
+            schemas.SearchRequestBody = generateSearchRequestBody(this.model.pagination);
+        }
+        components.schemas = schemas;
+        if (Object.keys(securitySchemes).length > 0) {
+            components.securitySchemes = securitySchemes;
+        }
+        const result = {
+            openapi: '3.1.0',
+            info: this.generateInfo(),
+        };
+        if (Object.keys(paths).length > 0) {
+            result.paths = paths;
+        }
+        if (Object.keys(components).length > 0) {
+            result.components = components;
+        }
+        const securityRequirements = [];
+        if (this.model.session?.jwt?.enabled) {
+            securityRequirements.push({ BearerAuth: [] });
+        }
+        if (this.model.session?.cookie?.enabled) {
+            securityRequirements.push({ CookieAuth: [] });
+        }
+        if (securityRequirements.length > 0) {
+            result.security = securityRequirements;
+        }
+        if (schemaGen.hasFileUpload) {
+            if (!result.tags) {
+                result.tags = [];
+            }
+            result.tags.push({
+                name: 'File Upload',
+                description: 'To maintain a strict `application/json` data exchange contract for standard API entity actions, ' +
+                    'this API utilizes a decoupled upload architecture for handling binary data.\n\n' +
+                    '### The `POST /upload` System Endpoint\nThis API exposes a dedicated, API-level ' +
+                    '`POST /upload` endpoint to handle multipart binary uploads for properties configured with `FileURL` ' +
+                    'or `ImageURL` semantics.\n\n1. **Upload:** The API Consumer uploads the file to ' +
+                    '`POST /upload`. ' +
+                    '*Note: This endpoint strictly enforces the Max File Size and Allowed MIME Types configured by the API ' +
+                    'Author.*\n2. **Response:** The Runtime stores the file and returns a temporary, ' +
+                    'platform-managed URL string.\n3. **Attach:** The API Consumer passes this URL string as a standard JSON ' +
+                    'value when calling the `POST` (Create) or `PUT/PATCH` (Update) action for the actual entity.\n\n' +
+                    '### Asset Expiration (Orphan Prevention)\nTo prevent storage bloat from abandoned uploads, any file ' +
+                    'uploaded to the `/upload` endpoint is assigned a Time-to-Live (TTL) limit. If the generated URL is not ' +
+                    'successfully associated with an entity record (via Create or Update actions) within this time limit, ' +
+                    'the asset is automatically purged from storage. The endpoint explicitly informs the API Consumer ' +
+                    'of this limit via the `expires_at` response property and the `X-Asset-Expiration` HTTP header.',
+            });
+            paths['/upload'] = {
+                post: {
+                    tags: ['File Upload'],
+                    summary: 'Upload a binary file',
+                    description: 'Uploads a physical file directly in the request body as raw binary data. ' +
+                        'This endpoint acts purely as a blob store; it does not accept or store ' +
+                        'file metadata (such as original filenames). Metadata should be managed ' +
+                        'within your entity schemas.\n\nPass the raw file bytes as the payload and ' +
+                        'specify the exact MIME type in the `Content-Type` header (e.g., `image/jpeg` or `application/pdf`).',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            '*/*': {
+                                schema: {
+                                    type: 'string',
+                                    format: 'binary',
+                                    description: 'The raw bytes of the file.',
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '201': {
+                            description: 'File uploaded successfully. Returns the temporary URL and expiration details.',
+                            headers: {
+                                'X-Asset-Expiration': {
+                                    description: 'The exact timestamp when this temporary file will be purged if not attached to an entity.',
+                                    schema: {
+                                        type: 'string',
+                                        format: 'date-time',
+                                    },
+                                },
+                            },
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            url: {
+                                                type: 'string',
+                                                format: 'uri',
+                                                description: 'The temporary URL of the uploaded file. Pass this string into the entity Create ' +
+                                                    'or Update payload.',
+                                            },
+                                            expires_at: {
+                                                type: 'string',
+                                                format: 'date-time',
+                                                description: 'The exact timestamp when this temporary file will be purged if not attached to an entity.',
+                                            },
+                                        },
+                                        required: ['url', 'expires_at'],
+                                    },
+                                },
+                            },
+                        },
+                        '400': {
+                            description: 'Validation Error. The file exceeded the maximum allowed size, its MIME type is restricted, ' +
+                                'or the payload is missing the required `file` property.',
+                            summary: 'Bad Request',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        $ref: '#/components/schemas/Error400BadRequestValidationFailed',
+                                    },
+                                },
+                            },
+                        },
+                        '401': {
+                            description: 'Unauthorized. The API key is missing or invalid.',
+                            summary: 'Unauthorized',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        $ref: '#/components/schemas/Error401Unauthorized',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+        }
+        return result;
+    }
+    generateInfo() {
+        const info = {
+            title: this.model.info.displayName || this.model.info.name || 'API',
+            version: this.model.info.version || '1.0.0',
+        };
+        if (this.model.info.description) {
+            info.description = this.model.info.description;
+        }
+        if (this.model.termsOfService) {
+            info.termsOfService = this.model.termsOfService;
+        }
+        if (this.model.contact) {
+            info.contact = { ...this.model.contact };
+        }
+        if (this.model.license) {
+            info.license = { ...this.model.license };
+        }
+        return info;
+    }
+    generateSecuritySchemes() {
+        const schemes = {};
+        // OpenAPI doesn't have a native "Username/Password" strategy (except via OAuth2 flows).
+        // The actual security required to make calls to the API is defined by the Session transport.
+        if (this.model.session) {
+            if (this.model.session.jwt?.enabled) {
+                schemes['BearerAuth'] = {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT',
+                    description: 'JWT authorization obtained after trading Username/Password credentials',
+                };
+            }
+            if (this.model.session.cookie?.enabled) {
+                schemes['CookieAuth'] = {
+                    type: 'apiKey',
+                    in: 'cookie',
+                    name: this.model.session.cookie.name || 'as',
+                    description: 'Session cookie obtained after authenticating',
+                };
+            }
+        }
+        return schemes;
+    }
+    generateErrorSchemas() {
+        const createErrorSchema = (name, status, typeUri, title, description) => {
+            const properties = {
+                type: {
+                    type: 'string',
+                    format: 'uri',
+                    description: 'A URI reference that identifies the problem type.',
+                    example: typeUri,
+                },
+                title: {
+                    type: 'string',
+                    description: 'A short, human-readable summary of the problem type.',
+                    example: title,
+                },
+                status: {
+                    type: 'integer',
+                    description: 'The HTTP status code generated by the origin server for this occurrence of the problem.',
+                    example: status,
+                },
+                detail: {
+                    type: 'string',
+                    description: 'A human-readable explanation specific to this occurrence of the problem.',
+                },
+                instance: {
+                    type: 'string',
+                    format: 'uri',
+                    description: 'A URI reference that identifies the specific occurrence of the problem.',
+                },
+            };
+            // Add a generic "errors" array specifically for validation errors to align with popular JSON frameworks
+            if (name === 'ValidationError') {
+                properties['errors'] = {
+                    type: 'array',
+                    description: 'A list of specifically mapped validation rule failures.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            field: { type: 'string', description: 'The property name that failed validation.' },
+                            message: { type: 'string', description: 'Description of the validation failure.' },
+                        },
+                    },
+                };
+            }
+            return {
+                title: name,
+                type: 'object',
+                description,
+                properties,
+                required: ['type', 'title', 'status'],
+            };
+        };
+        return {
+            Error400BadRequestValidationFailed: createErrorSchema('ValidationError', 400, 'https://docs.apinow.app/errors/validation-failed', 'Validation Error', 'Request payload fails schema validation (missing fields, wrong types) or contains invalid query parameters.'),
+            Error400BadRequestInvalidFormat: createErrorSchema('InvalidRequestFormatError', 400, 'https://docs.apinow.app/errors/invalid-request', 'Invalid Request Format', 'The request body is not parsable as JSON (when expected), or other malformations.'),
+            Error401Unauthorized: createErrorSchema('AuthenticationRequiredError', 401, 'https://docs.apinow.app/errors/authentication-required', 'Authentication Required', 'JWT is missing, malformed, or invalid (e.g., signature mismatch, expired).'),
+            Error403Forbidden: createErrorSchema('AccessDeniedError', 403, 'https://docs.apinow.app/errors/access-denied', 'Access Denied', 'An authenticated user does not have permission to perform the requested operation on the resource ' +
+                'based on rules.'),
+            Error404NotFound: createErrorSchema('ResourceNotFoundError', 404, 'https://docs.apinow.app/errors/resource-not-found', 'Resource Not Found', 'The requested resource (e.g., specific entity instance via ID) does not exist.'),
+            Error409Conflict: createErrorSchema('ResourceConflictError', 409, 'https://docs.apinow.app/errors/resource-conflict', 'Resource Conflict', 'Attempt to create a resource that would violate a uniqueness constraint (e.g., unique email already exists).'),
+            Error429TooManyRequests: createErrorSchema('RateLimitExceededError', 429, 'https://docs.apinow.app/errors/rate-limit-exceeded', 'Rate Limit Exceeded', 'API consumer has exceeded configured rate limits.'),
+            Error500InternalServerError: createErrorSchema('InternalServerError', 500, 'https://docs.apinow.app/errors/internal-server-error', 'Internal Server Error', 'An unexpected error occurred on the server while processing the request. Details should not expose ' +
+                'sensitive info.'),
+        };
+    }
+    generatePaths(schemaGen) {
+        const paths = {};
+        // Depending on the configured session transports, the API will expose different login endpoints.
+        if (this.model.authentication?.strategy === 'UsernamePassword') {
+            if (this.model.session?.jwt?.enabled) {
+                const jwtEndpoints = createJwtEndpoints();
+                Object.assign(paths, jwtEndpoints);
+            }
+            if (this.model.session?.cookie?.enabled) {
+                const cookieEndpoints = createCookieEndpoints();
+                Object.assign(paths, cookieEndpoints);
+            }
+        }
+        for (const expose of this.model.exposes.values()) {
+            const colPath = expose.getAbsoluteCollectionPath();
+            const resPath = expose.getAbsoluteResourcePath();
+            const domainEntity = this.model.domain?.findEntity(expose.entity.key);
+            if (!domainEntity) {
+                // This should not happen after the API model is validated.
+                // Our runtime require a schema for each expose.
+                continue;
+            }
+            const schemaRef = schemaGen.generateRootRef(domainEntity);
+            if (!schemaRef) {
+                // This should not happen after the API model is validated.
+                // Our runtime require a schema for each expose.
+                continue;
+            }
+            const links = {};
+            for (const assoc of domainEntity.associations) {
+                if (assoc.schema?.linked === false) {
+                    continue;
+                }
+                const targets = Array.from(assoc.listTargets());
+                if (targets.length === 0)
+                    continue;
+                const targetEntity = targets[0];
+                const targetExpose = Array.from(this.model.exposes.values()).find((e) => e.entity.key === targetEntity.key && e.actions.some((a) => a.kind === 'read'));
+                if (targetExpose) {
+                    const targetResPath = targetExpose.getAbsoluteResourcePath();
+                    if (targetResPath) {
+                        const params = this.extractPathParameters(targetResPath);
+                        const paramName = params[0]?.name || 'id';
+                        const propName = assoc.info.name || assoc.key;
+                        links[`${targetEntity.info.name || targetEntity.key}By${propName}`] = {
+                            operationId: `read_${targetEntity.info.name || 'entity ' + targetEntity.key}`,
+                            parameters: {
+                                [paramName]: `$response.body#/${propName}`,
+                            },
+                            description: `Fetch the associated ${targetEntity.info.name || targetEntity.key} using the ${propName} property`,
+                        };
+                    }
+                }
+            }
+            const hasLinks = Object.keys(links).length > 0;
+            const operationIdKey = domainEntity.info.name || domainEntity.key;
+            const entityName = domainEntity.info.getLabel();
+            const entityNameUpper = upperFirst(entityName);
+            const pluralName = pluralize(entityNameUpper);
+            // We discover the search action in the collection processing,
+            // but since it's a dedicated path, we process it separately.
+            let searchAction;
+            if (expose.hasCollection && colPath) {
+                const pathItem = paths[colPath] || {};
+                paths[colPath] = pathItem;
+                const listAction = expose.actions.find((a) => a.kind === 'list');
+                const createAction = expose.actions.find((a) => a.kind === 'create');
+                searchAction = expose.actions.find((a) => a.kind === 'search');
+                if (listAction) {
+                    this.#hasListAction = true;
+                    const isCursor = this.model.pagination.kind === 'cursor';
+                    const paginationParameters = isCursor
+                        ? this.createCursorPaginationQueryParameters(colPath)
+                        : this.createOffsetPaginationQueryParameters(colPath);
+                    const op = {
+                        operationId: `list_${operationIdKey}`,
+                        summary: `Retrieves a paginated list of ${pluralName}`,
+                        description: `This endpoint is optimized for high-performance index lookups. It supports advanced filtering, ` +
+                            `sorting, and ${this.model.pagination.kind}-based pagination.\n\n` +
+                            `You can filter the list using bracket notation directly in the query string. Filters are appended to the field name: \`?field[operator]=value\`.\n\n` +
+                            `Note: You can apply multiple filters to the same request. By default, all filters are evaluated using logical \`AND\`.`,
+                        parameters: [
+                            ...paginationParameters,
+                            ...this.createListParameters(domainEntity, colPath, expose.paginationContract),
+                        ],
+                        responses: {
+                            '200': {
+                                description: `Successfully retrieved a paginated list of **${entityNameUpper}** records.\n\nReturns an array of records wrapped in a standard \`data\` envelope. The response also includes a \`meta\` object containing pagination details.`,
+                                content: {
+                                    'application/json': {
+                                        schema: {
+                                            title: `Paginated${upperFirst(domainEntity.info.name) || domainEntity.key}List`,
+                                            type: 'object',
+                                            properties: {
+                                                data: {
+                                                    type: 'array',
+                                                    items: schemaRef,
+                                                    description: `List of page results for ${pluralName}. Can be empty. See the \`meta\` object for pagination details.`,
+                                                },
+                                                meta: { $ref: '#/components/schemas/PaginationMeta' },
+                                            },
+                                            required: ['data', 'meta'],
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    };
+                    this.applyActionSecurity(listAction, op);
+                    this.applyStandardResponse(listAction, op, { hasBody: false, isResource: false, isCreate: false });
+                    pathItem.get = op;
+                }
+                if (createAction) {
+                    const op = {
+                        operationId: `create_${operationIdKey}`,
+                        summary: `Creates a ${entityNameUpper}`,
+                        description: `Creates a new **${entityNameUpper}** record.\n\n` +
+                            `This endpoint accepts a standard JSON payload representing the properties of the new entity. ` +
+                            `The provided payload is strictly validated against the ${entityNameUpper} schema.\n\n` +
+                            '**Required Fields:** Any property marked as required must be included in the payload, ' +
+                            'otherwise the request will be rejected with a `400 Bad Request`.\n' +
+                            '* **System Fields:** System-generated properties (such as `id`, `created_at`, or `updated_at`) ' +
+                            'cannot be set via this endpoint and will be safely ignored if included.\n\n' +
+                            '*Note: This endpoint does not accept `multipart/form-data` payloads. If your resource contains ' +
+                            "binary properties, you must first upload the physical file to the API's `/upload` endpoint, " +
+                            'and then pass the resulting URL string in this JSON payload.*',
+                        requestBody: {
+                            required: true,
+                            content: {
+                                'application/json': {
+                                    schema: schemaRef,
+                                },
+                            },
+                        },
+                        responses: {
+                            '201': {
+                                description: `The **${entityNameUpper}** was successfully created.\n\nReturns the fully realized record. The payload includes all properties validated from the request, alongside all system-generated fields such as the unique \`id\` and initialization timestamps (\`created_at\`, \`updated_at\`).`,
+                                content: {
+                                    'application/json': {
+                                        schema: schemaRef,
+                                    },
+                                },
+                                ...(hasLinks && { links }),
+                            },
+                        },
+                    };
+                    this.applyActionSecurity(createAction, op);
+                    this.applyStandardResponse(createAction, op, { hasBody: true, isResource: false, isCreate: true });
+                    pathItem.post = op;
+                }
+            }
+            if (resPath) {
+                const pathItem = paths[resPath] || {};
+                paths[resPath] = pathItem;
+                const readAction = expose.actions.find((a) => a.kind === 'read');
+                const updateAction = expose.actions.find((a) => a.kind === 'update');
+                const deleteAction = expose.actions.find((a) => a.kind === 'delete');
+                const parameters = this.extractPathParameters(resPath);
+                if (readAction) {
+                    const op = {
+                        operationId: `read_${operationIdKey}`,
+                        summary: `Retrieves the details of an existing record for the ${entityNameUpper}`,
+                        description: `You must supply the unique system-generated identifier (id) that was returned upon creation.`,
+                        parameters,
+                        responses: {
+                            '200': {
+                                description: `Successfully retrieved the **${entityNameUpper}** record.`,
+                                content: {
+                                    'application/json': { schema: schemaRef },
+                                },
+                                ...(hasLinks && { links }),
+                            },
+                        },
+                    };
+                    this.applyActionSecurity(readAction, op);
+                    this.applyStandardResponse(readAction, op, { hasBody: false, isResource: true, isCreate: false });
+                    pathItem.get = op;
+                }
+                if (updateAction) {
+                    if (updateAction.allowedMethods.includes('PUT')) {
+                        pathItem.put = {
+                            parameters,
+                            requestBody: {
+                                required: true,
+                                content: { 'application/json': { schema: schemaRef } },
+                            },
+                            responses: {
+                                '200': {
+                                    description: `The **${entityNameUpper}** was successfully replaced.\n\nReturns the complete, current state of the record. The payload reflects all modifications made during the request, as well as any system-generated updates (such as a newly modified \`updated_at\` timestamp).`,
+                                    content: {
+                                        'application/json': { schema: schemaRef },
+                                    },
+                                    ...(hasLinks && { links }),
+                                },
+                            },
+                            operationId: `replace_${operationIdKey}`,
+                            summary: `Replace a ${entityNameUpper}`,
+                            description: `Replaces the entire **${entityNameUpper}** record with the provided JSON payload. \n\nThis is a strict replacement operation. Any editable properties that are omitted from the request payload will be cleared or reset to their default values. The payload is strictly validated against the ${entityNameUpper} schema. System-generated fields cannot be modified and will be ignored if included.\n\n*Note: For properties configured as \`FileURL\` or \`ImageURL\`, you must upload the file to the API's \`/upload\` endpoint first and pass the resulting URL string in this payload.*`,
+                        };
+                        this.applyActionSecurity(updateAction, pathItem.put);
+                        this.applyStandardResponse(updateAction, pathItem.put, { hasBody: true, isResource: true, isCreate: false });
+                    }
+                    if (updateAction.allowedMethods.includes('PATCH')) {
+                        // @todo: the patch operation makes all properties optional
+                        pathItem.patch = {
+                            parameters,
+                            requestBody: {
+                                required: true,
+                                content: { 'application/json': { schema: schemaRef } },
+                            },
+                            responses: {
+                                '200': {
+                                    description: `The **${entityNameUpper}** was successfully updated.\n\nReturns the complete, current state of the record. The payload reflects all modifications made during the request, as well as any system-generated updates (such as a newly modified \`updated_at\` timestamp).`,
+                                    content: {
+                                        'application/json': { schema: schemaRef },
+                                    },
+                                    ...(hasLinks && { links }),
+                                },
+                            },
+                            operationId: `partial_update_${operationIdKey}`,
+                            summary: `Update a ${entityNameUpper}`,
+                            description: `Updates specific properties of the specified **${entityNameUpper}** without affecting other existing data. \n\nOnly the fields provided in the payload will be modified; any parameters omitted from the request will remain unchanged. The request payload is validated against the ${entityNameUpper} schema. System-generated fields (like \`id\` and \`created_at\`) cannot be modified.\n\n*Note: For properties configured as \`FileURL\` or \`ImageURL\`, you must upload the file to the API's \`/upload\` endpoint first and pass the resulting URL string in this payload.*`,
+                        };
+                        this.applyActionSecurity(updateAction, pathItem.patch);
+                        this.applyStandardResponse(updateAction, pathItem.patch, {
+                            hasBody: true,
+                            isResource: true,
+                            isCreate: false,
+                        });
+                    }
+                }
+                if (deleteAction) {
+                    const isSoftDelete = deleteAction.strategy === 'soft';
+                    const actionText = isSoftDelete ? 'marked for deletion' : 'permanently deleted';
+                    const op = {
+                        operationId: `delete_${operationIdKey}`,
+                        parameters,
+                        responses: {
+                            '204': {
+                                description: `The **${entityNameUpper}** was successfully ${actionText}.\n\nThis endpoint returns a \`204 No Content\` status code upon success, indicating that the server has fulfilled the request and there is intentionally no content to send in the response payload body.`,
+                            },
+                        },
+                    };
+                    if (isSoftDelete) {
+                        op.summary = `Delete a ${entityNameUpper}`;
+                        op.description = `Soft-deletes the specified **${entityNameUpper}** record.\n\nThis action immediately removes the record from standard API responses (such as List and Read operations). The record is retained securely in the system for a recovery period of **${deleteAction.retentionPeriod} days**, after which it is permanently destroyed. \n\nIf the record is successfully marked for deletion, the endpoint returns a \`204 No Content\` response with an empty body.`;
+                    }
+                    else {
+                        op.summary = `Permanently delete a ${entityNameUpper}`;
+                        op.description = `Permanently deletes the specified **${entityNameUpper}** record.\n\nThis action is immediate and **cannot be undone**. You must supply the unique system-generated identifier (\`id\`) of the record to delete. If the record is successfully deleted, the endpoint returns a \`204 No Content\` response with an empty body.`;
+                    }
+                    this.applyActionSecurity(deleteAction, op);
+                    this.applyStandardResponse(deleteAction, op, { hasBody: false, isResource: true, isCreate: false });
+                    pathItem.delete = op;
+                }
+            }
+            if (searchAction) {
+                this.#hasSearchAction = true;
+                const searchPath = `${colPath}/search`;
+                const pathItem = paths[searchPath] || {};
+                paths[searchPath] = pathItem;
+                const searchProperties = [];
+                for (const prop of domainEntity.properties) {
+                    if (prop.search) {
+                        searchProperties.push(prop);
+                    }
+                }
+                const formattedSearchFields = searchProperties.length > 0
+                    ? searchProperties.map((p) => `\`${p.info.name}\``).join(', ')
+                    : '*None configured*';
+                if (!this.whereAstInjected) {
+                    this.whereAstInjected = true;
+                }
+                const maxLimit = this.model.pagination.maxLimit ?? 100;
+                const op = {
+                    tags: [entityNameUpper],
+                    operationId: `search_${entityName}s`,
+                    summary: `Search ${entityName}s`,
+                    description: `Retrieves a paginated list of **${entityNameUpper}** records using an advanced JSON query payload.\n\nUnlike the standard \`GET\` List endpoint, this endpoint uses a \`POST\` request to accept a complex Abstract Syntax Tree (AST) for deeply nested logical filtering (\`and\`, \`or\`) and full-text substring searching.\n\n### Full-Text Search Capabilities\nThe API Author has explicitly enabled the \`contains\` operator for the following fields: ${formattedSearchFields}. Attempting to use the \`contains\` operator on any other field will result in a \`400 Bad Request\` to prevent unoptimized table scans.\n\n### Payload Structure\n* \`where\`: The root query object. Supports nested \`and\` / \`or\` arrays, and standard field operators (\`eq\`, \`in\`, \`gt\`, \`contains\`).\n* \`sort\`: An array of objects specifying the \`field\` name and sort \`direction\` (\`asc\` or \`desc\`).\n* \`limit\`: The maximum number of records to return (Max ${maxLimit}).\n* \`cursor\`: The opaque pagination token.`,
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/SearchRequestBody' },
+                                example: {
+                                    where: {
+                                        and: [
+                                            { status: { in: ['active', 'pending'] } },
+                                            searchProperties.length > 0
+                                                ? { [searchProperties[0].info.name]: { contains: 'search keyword' } }
+                                                : { created_at: { gte: '2025-01-01T00:00:00Z' } },
+                                            {
+                                                or: [{ role: { eq: 'admin' } }, { views: { gt: 100 } }],
+                                            },
+                                        ],
+                                    },
+                                    sort: [
+                                        { field: 'created_at', direction: 'desc' },
+                                        { field: 'id', direction: 'asc' },
+                                    ],
+                                    limit: 25,
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: `Successfully retrieved a paginated list of **${entityNameUpper}** records matching the search criteria.\n\nReturns an array of records wrapped in a standard \`data\` envelope. The response also includes a \`meta\` object containing pagination details.`,
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            data: {
+                                                type: 'array',
+                                                items: schemaGen.generateRootRef(domainEntity),
+                                            },
+                                            meta: { $ref: '#/components/schemas/PaginationMeta' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '400': {
+                            description: 'Bad Request. The AST payload is malformed, uses an unsupported operator for a field, ' +
+                                'or targets a non-existent property.',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/Error400BadRequestValidationFailed' },
+                                },
+                            },
+                        },
+                        '401': {
+                            description: 'Unauthorized. Valid authentication is required.',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/Error401Unauthorized' },
+                                },
+                            },
+                        },
+                        '403': {
+                            description: 'Forbidden. The authenticated user lacks permission to search this resource.',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/Error403Forbidden' },
+                                },
+                            },
+                        },
+                    },
+                };
+                pathItem.post = op;
+            }
+        }
+        return paths;
+    }
+    extractPathParameters(path) {
+        const params = [];
+        const regex = /\{([^}]+)\}/g;
+        let match;
+        while ((match = regex.exec(path)) !== null) {
+            params.push({
+                name: match[1],
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+            });
+        }
+        return params;
+    }
+    applyActionSecurity(action, operation) {
+        const rules = action.accessRule;
+        // Check if anonymous access is explicitly allowed via an AllowPublic rule
+        const isPublic = rules.some((r) => r.type === 'allowPublic');
+        if (isPublic) {
+            operation.security = [];
+            return;
+        }
+        if (rules.length > 0) {
+            // It's restricted. Define operational security requirements.
+            const items = [];
+            if (this.model.session?.jwt?.enabled)
+                items.push({ BearerAuth: [] });
+            if (this.model.session?.cookie?.enabled)
+                items.push({ CookieAuth: [] });
+            if (items.length > 0) {
+                operation.security = items;
+            }
+        }
+        // Extract any matching roles specific to the RBAC capabilities
+        const roleRules = rules.filter((r) => r.type === 'matchUserRole');
+        const roles = roleRules.flatMap((r) => r.role || []);
+        if (roles.length > 0) {
+            const uniqueRoles = Array.from(new Set(roles));
+            // Inject natively as vendor extension for processing tooling
+            // ;(operation as any)['x-roles'] = uniqueRoles
+            // Append strictly to the markdown description so developers always see the RBAC bounds
+            const rolesDesc = `**Required Roles:** ${uniqueRoles.join(', ')}`;
+            operation.description = operation.description ? `${operation.description}\n\n${rolesDesc}` : rolesDesc;
+        }
+    }
+    applyStandardResponse(action, operation, opts) {
+        const rules = action.getAllRules();
+        const isPublic = rules.some((r) => r.type === 'allowPublic');
+        if (!operation.responses) {
+            operation.responses = {};
+        }
+        if (opts.hasBody) {
+            operation.responses['400'] = {
+                description: 'The request body is not parsable as JSON (when expected), or other malformations.',
+                summary: 'Bad Request',
+                content: {
+                    'application/json': {
+                        schema: {
+                            $ref: '#/components/schemas/Error400BadRequestInvalidFormat',
+                        },
+                    },
+                },
+            };
+        }
+        else {
+            operation.responses['400'] = {
+                description: 'The request payload failed schema validation (e.g., missing required fields, invalid data types, ' +
+                    'or a string exceeding the maximum configured length). The response body will contain an RFC 7807 ' +
+                    'problem details object explaining the specific validation failures.',
+                summary: 'Bad Request',
+                content: {
+                    'application/json': {
+                        schema: {
+                            $ref: '#/components/schemas/Error400BadRequestValidationFailed',
+                        },
+                    },
+                },
+            };
+        }
+        if (!isPublic) {
+            operation.responses['401'] = {
+                description: 'JWT or session cookie is missing, malformed, or invalid (e.g., signature mismatch, expired).',
+                summary: 'Unauthorized',
+                content: {
+                    'application/json': {
+                        schema: {
+                            $ref: '#/components/schemas/Error401Unauthorized',
+                        },
+                    },
+                },
+            };
+            operation.responses['403'] = {
+                description: 'An authenticated user does not have permission to perform the requested operation on ' +
+                    'the resource based on rules.',
+                summary: 'Forbidden',
+                content: {
+                    'application/json': {
+                        schema: {
+                            $ref: '#/components/schemas/Error403Forbidden',
+                        },
+                    },
+                },
+            };
+        }
+        if (opts.isResource) {
+            operation.responses['404'] = {
+                description: 'The requested resource (e.g., specific entity instance via ID) does not exist.',
+                summary: 'Not Found',
+                content: {
+                    'application/json': {
+                        schema: {
+                            $ref: '#/components/schemas/Error404NotFound',
+                        },
+                    },
+                },
+            };
+        }
+        if (opts.isCreate) {
+            operation.responses['409'] = {
+                description: 'Attempt to create a resource that would violate a uniqueness constraint ' +
+                    '(e.g., unique email already exists).',
+                summary: 'Resource Conflict',
+                content: {
+                    'application/json': {
+                        schema: {
+                            $ref: '#/components/schemas/Error409Conflict',
+                        },
+                    },
+                },
+            };
+        }
+        operation.responses['429'] = {
+            description: 'The request has been rejected because the client has sent too many requests in a given amount of time.',
+            summary: 'Too Many Requests',
+            content: {
+                'application/json': {
+                    schema: {
+                        $ref: '#/components/schemas/Error429TooManyRequests',
+                    },
+                },
+            },
+        };
+        operation.responses['500'] = {
+            description: 'An unexpected error occurred on the server while processing the request. Details should not ' +
+                'expose sensitive info.',
+            summary: 'Internal Server Error',
+            content: {
+                'application/json': {
+                    schema: {
+                        $ref: '#/components/schemas/Error500InternalServerError',
+                    },
+                },
+            },
+        };
+    }
+    resolvePaginationDefault(configuredDefault, min, maximum, fallbackDefault) {
+        const defaultValue = typeof configuredDefault === 'number' && !Number.isNaN(configuredDefault) ? configuredDefault : fallbackDefault;
+        return Math.max(min, Math.min(defaultValue, maximum));
+    }
+    resolvePaginationMaximum(configuredMax, min, fallbackMax) {
+        if (typeof configuredMax !== 'number' || Number.isNaN(configuredMax)) {
+            return fallbackMax;
+        }
+        return Math.max(min, Math.min(configuredMax, fallbackMax));
+    }
+    createCursorPaginationQueryParameters(path) {
+        const maximum = this.resolvePaginationMaximum(this.model.pagination.maxLimit, CURSOR_PAGINATION_MIN_LIMIT, CURSOR_PAGINATION_MAX_LIMIT);
+        const defaultLimit = this.resolvePaginationDefault(this.model.pagination.defaultLimit, CURSOR_PAGINATION_MIN_LIMIT, maximum, CURSOR_PAGINATION_DEFAULT_LIMIT);
+        const result = [
+            {
+                in: 'query',
+                name: 'limit',
+                required: false,
+                schema: {
+                    type: 'integer',
+                    default: defaultLimit,
+                    minimum: CURSOR_PAGINATION_MIN_LIMIT,
+                    maximum,
+                    description: 'Number of items to return. Used with the cursor pagination strategy.',
+                },
+                example: `${path}?limit=10`,
+            },
+            {
+                in: 'query',
+                name: 'cursor',
+                required: false,
+                schema: {
+                    type: 'string',
+                    description: 'The cursor to use for pagination. Use the `next_cursor` from the previous response.',
+                },
+                example: `${path}?cursor=eyJ2IjpbInVzcl85eTIwYTMiXSwicyI6W3siZiI6ImlkIiwiZCI6ImFzYyJ9XX0=`,
+            },
+        ];
+        return result;
+    }
+    createOffsetPaginationQueryParameters(path) {
+        const maximum = this.resolvePaginationMaximum(this.model.pagination.maxLimit, OFFSET_PAGINATION_MIN_LIMIT, OFFSET_PAGINATION_MAX_LIMIT);
+        const defaultLimit = this.resolvePaginationDefault(this.model.pagination.defaultLimit, OFFSET_PAGINATION_MIN_LIMIT, maximum, OFFSET_PAGINATION_DEFAULT_LIMIT);
+        const result = [
+            {
+                in: 'query',
+                name: 'limit',
+                required: false,
+                schema: {
+                    type: 'integer',
+                    default: defaultLimit,
+                    minimum: OFFSET_PAGINATION_MIN_LIMIT,
+                    maximum,
+                    description: 'Number of items to return. Used with the offset pagination strategy.',
+                },
+                example: `${path}?limit=10`,
+            },
+            {
+                in: 'query',
+                name: 'page',
+                required: false,
+                schema: {
+                    type: 'integer',
+                    default: 1,
+                    minimum: 1,
+                    description: 'The page number to return. Used with the offset pagination strategy.',
+                },
+                example: `${path}?page=2`,
+            },
+        ];
+        return result;
+    }
+    createListParameters(entity, path, paginationContract) {
+        const ff = paginationContract?.filterableFields;
+        const filterableFields = Array.isArray(ff) && ff.length ? new Set(ff) : undefined;
+        const sf = paginationContract?.sortableFields;
+        const sortableFields = Array.isArray(sf) && sf.length ? new Set(sf) : undefined;
+        const result = [];
+        if (sortableFields?.size) {
+            result.push(this.createSortParameter(path, entity));
+        }
+        for (const prop of entity.properties) {
+            if (prop.index) {
+                if (filterableFields && !filterableFields.has(prop.key)) {
+                    // The API author explicitly excluded this property from filtering
+                    continue;
+                }
+                const applicableOperators = OPERATOR_MAPPING[prop.type];
+                for (const operator of applicableOperators) {
+                    result.push(this.createListParameter(prop, operator, path));
+                }
+            }
+        }
+        return result;
+    }
+    createListParameter(property, operator, path) {
+        const paramName = `${property.info.name}[${operator}]`;
+        const name = `${property.info.name}`;
+        // Base Parameter scaffolding
+        const result = {
+            in: 'query',
+            name: paramName,
+            description: `${OPERATOR_DESCRIPTIONS[operator]}`,
+            required: false,
+            example: OPERATOR_EXAMPLES[operator](path, name),
+            schema: {},
+        };
+        // The 'exists' operator ALWAYS takes a boolean, regardless of the underlying field type
+        if (operator === 'exists') {
+            result.schema = { type: 'boolean' };
+            return result;
+        }
+        // Get the base schema for the field
+        const baseSchema = resolveOasSchema(property.type);
+        // ParameterObject already has the example. We do not need it on the schema anymore.
+        // If the operator is 'in' or 'nin', we must wrap the schema in an Array
+        if (operator === 'in' || operator === 'nin') {
+            result.style = 'form';
+            result.explode = false;
+            result.schema = {
+                type: 'array',
+                items: baseSchema,
+            };
+        }
+        else {
+            // For scalar operators (eq, lt, gt), just use the base schema directly
+            result.schema = baseSchema;
+        }
+        return result;
+    }
+    createSortParameter(path, entity) {
+        const indexedFields = [];
+        for (const prop of entity.properties) {
+            if (prop.index && prop.info.name) {
+                indexedFields.push(prop.info.name);
+            }
+        }
+        if (indexedFields.length === 0) {
+            indexedFields.push('name');
+            indexedFields.push('created_at');
+        }
+        else if (indexedFields.length === 1) {
+            indexedFields.push('created_at');
+        }
+        const result = {
+            in: 'query',
+            name: 'sort',
+            description: 'Comma-separated list of fields to sort by. Prefix with `-` for descending order.',
+            required: false,
+            example: `${path}?sort=${indexedFields[0]},-${indexedFields[1]}`,
+            schema: {
+                type: 'string',
+            },
+        };
+        return result;
+    }
+}
+const OPERATOR_MAPPING = {
+    string: ['eq', 'neq', 'in', 'nin', 'exists'],
+    number: ['eq', 'neq', 'in', 'nin', 'lt', 'lte', 'gt', 'gte', 'exists'],
+    datetime: ['eq', 'neq', 'lt', 'lte', 'gt', 'gte', 'exists'],
+    date: ['eq', 'neq', 'in', 'nin', 'lt', 'lte', 'gt', 'gte', 'exists'],
+    time: ['eq', 'neq', 'in', 'nin', 'lt', 'lte', 'gt', 'gte', 'exists'],
+    boolean: ['eq', 'neq', 'exists'],
+    binary: ['exists'], // Binary data/URLs should only be queried for existence, not exact match
+};
+const OPERATOR_DESCRIPTIONS = {
+    eq: 'Returns records where the property equals this exact value.',
+    neq: 'Returns records where the property does not equal this value.',
+    in: 'Requires a comma-separated list. Returns records matching any of the listed values.',
+    nin: 'Requires a comma-separated list. Omits records matching any of the listed values.',
+    lt: 'Numeric or Date comparison. Returns records strictly less than the provided value.',
+    lte: 'Numeric or Date comparison. Returns records less than or equal to the provided value.',
+    gt: 'Numeric or Date comparison. Returns records strictly greater than the provided value.',
+    gte: 'Numeric or Date comparison. Returns records greater than or equal to the provided value.',
+    exists: 'Requires a boolean (true/false). Checks if the property is defined and not null.',
+    // These are not used in query parameters
+    contains: 'Not implemented yet',
+    match: 'Not implemented yet',
+};
+const OPERATOR_EXAMPLES = {
+    eq: (path, key) => `${path}?${key}[eq]=value`,
+    neq: (path, key) => `${path}?${key}[neq]=value`,
+    in: (path, key) => `${path}?${key}[in]=value1,value2,value3`,
+    nin: (path, key) => `${path}?${key}[nin]=value1,value2,value3`,
+    lt: (path, key) => `${path}?${key}[lt]=value`,
+    lte: (path, key) => `${path}?${key}[lte]=value`,
+    gt: (path, key) => `${path}?${key}[gt]=value`,
+    gte: (path, key) => `${path}?${key}[gte]=value`,
+    exists: (path, key) => `${path}?${key}[exists]=true`,
+    contains: (path, key) => `${path}?${key}[contains]=value`,
+    match: (path, key) => `${path}?${key}[match]=value`,
+};
+/**
+ * Helper: Maps the internal FieldType to a valid OAS 3.1 Schema Object
+ */
+function resolveOasSchema(fieldType) {
+    switch (fieldType) {
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'datetime':
+            return { type: 'string', format: 'date-time' };
+        case 'date':
+            return { type: 'string', format: 'date' };
+        case 'time':
+            return { type: 'string', format: 'time' };
+        case 'binary':
+            return { type: 'string', format: 'uri' };
+        case 'string':
+        default:
+            return { type: 'string' };
+    }
+}
+function upperFirst(value) {
+    if (!value) {
+        return undefined;
+    }
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/**
+ * Injects the global AST schema definitions into the OAS document.
+ * Call this once when initializing your OAS generator.
+ */
+function getAstComponentSchemas() {
+    return {
+        SearchWhereAST: {
+            type: 'object',
+            description: 'The root query object. Supports nested logical operators and field-level conditions.',
+            $ref: '#/components/schemas/SearchWhereNode',
+        },
+        SearchWhereNode: {
+            type: 'object',
+            description: 'A node in the AST. Can be a logical operator (AND/OR) or a specific field condition.',
+            oneOf: [
+                {
+                    title: 'LogicalAndNode',
+                    type: 'object',
+                    properties: {
+                        and: {
+                            type: 'array',
+                            items: { $ref: '#/components/schemas/SearchWhereNode' },
+                        },
+                    },
+                    required: ['and'],
+                    additionalProperties: false,
+                },
+                {
+                    title: 'LogicalOrNode',
+                    type: 'object',
+                    properties: {
+                        or: {
+                            type: 'array',
+                            items: { $ref: '#/components/schemas/SearchWhereNode' },
+                        },
+                    },
+                    required: ['or'],
+                    additionalProperties: false,
+                },
+                {
+                    title: 'FieldConditionNode',
+                    type: 'object',
+                    minProperties: 1,
+                    maxProperties: 1,
+                    description: 'A dynamic key representing the field name, mapped to its operator conditions.',
+                    patternProperties: {
+                        '^[a-zA-Z0-9_]+$': {
+                            $ref: '#/components/schemas/SearchWhereOperatorMap',
+                        },
+                    },
+                    additionalProperties: false,
+                },
+            ],
+        },
+        SearchWhereOperatorMap: {
+            type: 'object',
+            minProperties: 1,
+            maxProperties: 1,
+            properties: {
+                eq: {},
+                neq: {},
+                in: { type: 'array' },
+                nin: { type: 'array' },
+                gt: { type: ['number', 'string'] },
+                gte: { type: ['number', 'string'] },
+                lt: { type: ['number', 'string'] },
+                lte: { type: ['number', 'string'] },
+                contains: { type: 'string' },
+                match: { type: 'string' },
+                exists: { type: 'boolean' },
+            },
+            additionalProperties: false,
+        },
+    };
+}
+function createJwtEndpoints() {
+    const paths = {};
+    paths['/auth/token'] = {
+        post: {
+            tags: ['Authentication'],
+            operationId: 'session_token_exchange',
+            summary: 'Create a session token',
+            description: 'Authenticates a user via credentials and returns a JSON Web Token (JWT). \n\n' +
+                'This token represents an active user session. You must include this token in the ' +
+                '`Authorization` header as a Bearer token (`Authorization: Bearer <token>`) for all ' +
+                'subsequent requests to protected API endpoints. \n\n*Note: Tokens have a limited ' +
+                'lifespan. Clients are responsible for securely storing the token and handling expiration gracefully.*',
+            requestBody: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                username: {
+                                    type: 'string',
+                                    description: 'The unique identifier or email address of the user.',
+                                    example: 'alex.carter@example.com',
+                                },
+                                password: {
+                                    type: 'string',
+                                    format: 'password',
+                                    description: 'The plain-text password for the account.',
+                                    example: 'correct-horse-battery-staple',
+                                },
+                            },
+                            required: ['username', 'password'],
+                        },
+                    },
+                },
+            },
+            responses: {
+                '200': {
+                    description: 'Authentication successful. Returns the JWT required for accessing protected endpoints.',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    token: {
+                                        type: 'string',
+                                        description: 'The JSON Web Token (JWT) representing the active session.',
+                                        example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI...',
+                                    },
+                                },
+                                required: ['token'],
+                            },
+                        },
+                    },
+                },
+                '400': {
+                    description: 'Bad Request. The request payload is missing the required username or password.',
+                },
+                '401': {
+                    description: 'Unauthorized. The provided credentials are incorrect, or the account is locked.',
+                },
+            },
+            security: [], // Explicitly requires no prior auth to hit this endpoint
+        },
+    };
+    paths['/auth/token/{token}'] = {
+        delete: {
+            tags: ['Authentication'],
+            operationId: 'session_token_revoke',
+            summary: 'Revoke a session token',
+            description: 'Invalidates an active JSON Web Token (JWT), effectively logging the user out and terminating ' +
+                'their session on the API. \n\nOnce revoked, the token is added to a system ' +
+                'blocklist and will be immediately rejected by all protected endpoints. For security best practices, ' +
+                'client applications should call this endpoint whenever a user explicitly logs out.',
+            parameters: [
+                {
+                    name: 'token',
+                    in: 'path',
+                    required: true,
+                    schema: { type: 'string' },
+                    description: 'The exact session token string to be revoked.',
+                },
+            ],
+            responses: {
+                '204': {
+                    description: 'The token was successfully revoked. This endpoint intentionally returns an empty response body.',
+                },
+                '401': {
+                    description: 'Unauthorized. The token provided is already expired, malformed, or previously revoked.',
+                },
+            },
+            security: [], // Usually no global security is needed if the token itself is in the path
+        },
+    };
+    return paths;
+}
+function createCookieEndpoints() {
+    const paths = {};
+    paths['/auth/cookie'] = {
+        post: {
+            tags: ['Authentication'],
+            operationId: 'session_cookie_exchange',
+            summary: 'Authenticate and set session cookie',
+            description: 'Authenticates a user via credentials and establishes a secure session cookie. \n\n' +
+                'Unlike the JWT token endpoint, this route is specifically designed for browser-based ' +
+                'applications. Upon successful authentication, the API will attach a ' +
+                '`Set-Cookie` header (configured as `HttpOnly`, `Secure`, and `SameSite`) to the response, ' +
+                "and return a `302 Found` status to automatically redirect the user's browser to the provided " +
+                '`redirectUri`.',
+            requestBody: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                username: {
+                                    type: 'string',
+                                    description: 'The unique identifier or email address of the user.',
+                                    example: 'alex.carter@example.com',
+                                },
+                                password: {
+                                    type: 'string',
+                                    format: 'password',
+                                    description: 'The plain-text password for the account.',
+                                    example: 'correct-horse-battery-staple',
+                                },
+                                redirectUri: {
+                                    type: 'string',
+                                    format: 'uri',
+                                    description: 'The exact URL destination where the browser should be redirected after ' +
+                                        'the cookie is successfully set.',
+                                    example: 'https://app.yourdomain.com/dashboard',
+                                },
+                            },
+                            required: ['username', 'password', 'redirectUri'],
+                        },
+                    },
+                },
+            },
+            responses: {
+                '302': {
+                    description: 'Authentication successful. The browser is redirected to the `redirectUri` with the session ' +
+                        'cookie established.',
+                    headers: {
+                        'Set-Cookie': {
+                            description: 'The secure session cookie containing the authentication state. Managed automatically ' +
+                                'by the browser.',
+                            schema: { type: 'string' },
+                        },
+                        'Location': {
+                            description: 'The URL destination for the browser redirect.',
+                            schema: { type: 'string' },
+                        },
+                    },
+                },
+                '400': {
+                    description: 'Bad Request. The payload is missing the username, password, or redirectUri.',
+                },
+                '401': {
+                    description: 'Unauthorized. The provided credentials are incorrect.',
+                },
+            },
+            security: [], // No prior authentication required
+        },
+    };
+    paths['/auth/cookie/logout'] = {
+        post: {
+            tags: ['Authentication'],
+            operationId: 'session_cookie_logout',
+            summary: 'Clear session cookie and redirect',
+            description: 'Terminates an active browser session by clearing the authentication cookie and redirecting ' +
+                'the user.\n\nThe API will return a `302 Found` response with a `Set-Cookie` ' +
+                'header that explicitly invalidates the session cookie (by setting its expiration date to the past). ' +
+                'The browser is then seamlessly redirected to the provided `redirectUri` ' +
+                '(e.g., a public login page or homepage).',
+            requestBody: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                redirectUri: {
+                                    type: 'string',
+                                    format: 'uri',
+                                    description: 'The URL destination where the browser should be redirected after the cookie is destroyed.',
+                                    example: 'https://app.yourdomain.com/login?logged_out=true',
+                                },
+                            },
+                            required: ['redirectUri'],
+                        },
+                    },
+                },
+            },
+            responses: {
+                '302': {
+                    description: 'Logout successful. The session cookie is cleared and the browser is redirected.',
+                    headers: {
+                        'Set-Cookie': {
+                            description: 'An invalidated cookie payload instructing the browser to delete the stored session data.',
+                            schema: { type: 'string' },
+                        },
+                        'Location': {
+                            description: 'The URL destination for the browser redirect.',
+                            schema: { type: 'string' },
+                        },
+                    },
+                },
+            },
+            security: [], // Safe to call even if the cookie is already expired
+        },
+    };
+    return paths;
+}
+function createOffsetPaginationMeta() {
+    // We adopt the AdonisJS pagination schema.
+    const properties = {
+        per_page: {
+            type: 'integer',
+            default: OFFSET_PAGINATION_DEFAULT_LIMIT,
+            minimum: OFFSET_PAGINATION_MIN_LIMIT,
+            maximum: OFFSET_PAGINATION_MAX_LIMIT,
+            description: 'Number of items per page',
+            example: '10',
+        },
+        current_page: {
+            type: 'integer',
+            default: 1,
+            minimum: 1,
+            description: 'The current page number',
+            example: '1',
+        },
+        first_page: {
+            type: 'integer',
+            default: 1,
+            minimum: 1,
+            description: 'The first page number. The first page is always 1.',
+            example: '1',
+        },
+        is_empty: {
+            type: 'boolean',
+            description: 'Whether the collection is empty.',
+            example: 'false',
+        },
+        total: {
+            type: 'integer',
+            minimum: 0,
+            description: 'The total number of items',
+            example: '100',
+        },
+        has_total: {
+            type: 'boolean',
+            description: 'Whether the total number of items is available. This is not same as `isEmpty`.\n\n' +
+                'The `isEmpty` reports about the current set of results. However `hasTotal` reports ' +
+                'about the total number of records, regardless of the current.',
+            example: 'true',
+        },
+        last_page: {
+            type: 'integer',
+            minimum: 1,
+            description: 'The last page number.',
+            example: '10',
+        },
+        has_more_pages: {
+            type: 'boolean',
+            description: 'Whether there are more pages.',
+            example: 'true',
+        },
+        has_pages: {
+            type: 'boolean',
+            description: 'Whether the collection has pages.',
+            example: 'true',
+        },
+    };
+    const schema = {
+        type: 'object',
+        description: 'Offset pagination metadata.',
+        properties,
+        required: ['per_page', 'current_page', 'first_page', 'is_empty', 'has_total', 'has_more_pages', 'has_pages'],
+    };
+    return schema;
+}
+function createCursorPaginationMeta() {
+    const properties = {
+        next_cursor: {
+            type: 'string',
+            description: 'The cursor to use for pagination.',
+            title: 'Next cursor',
+            example: 'eyJ2IjpbInVzcl85eTIwYTMiXSwicyI6W3siZiI6ImlkIiwiZCI6ImFzYyJ9XX0=',
+        },
+        has_more: {
+            type: 'boolean',
+            description: 'Whether there are more pages.',
+            title: 'Has more',
+            example: 'true',
+        },
+    };
+    const schema = {
+        type: 'object',
+        description: 'Cursor pagination metadata.',
+        properties,
+        required: ['next_cursor', 'has_more'],
+    };
+    return schema;
+}
+function generateSearchRequestBody(pagination) {
+    const isCursorPagination = pagination.kind === 'cursor';
+    const paginationProperties = isCursorPagination
+        ? {
+            cursor: {
+                type: 'string',
+                description: 'Pagination cursor retrieved from a previous response meta object.',
+            },
+        }
+        : {
+            page: {
+                type: 'integer',
+                minimum: 1,
+                default: 1,
+                description: 'Page number for offset pagination.',
+            },
+        };
+    return {
+        type: 'object',
+        properties: {
+            where: {
+                type: 'object',
+                description: 'The AST query object for filtering records.',
+                $ref: '#/components/schemas/SearchWhereAST',
+            },
+            sort: {
+                type: 'array',
+                description: 'An array of sorting directives applied in order.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        field: {
+                            type: 'string',
+                            description: 'The name of the indexable property to sort by.',
+                        },
+                        direction: {
+                            type: 'string',
+                            enum: ['asc', 'desc'],
+                            description: 'The sort direction (ascending or descending).',
+                        },
+                    },
+                    required: ['field', 'direction'],
+                },
+            },
+            limit: {
+                type: 'integer',
+                minimum: isCursorPagination ? CURSOR_PAGINATION_MIN_LIMIT : OFFSET_PAGINATION_MIN_LIMIT,
+                maximum: isCursorPagination
+                    ? (pagination.maxLimit ?? CURSOR_PAGINATION_MAX_LIMIT)
+                    : (pagination.maxLimit ?? OFFSET_PAGINATION_MAX_LIMIT),
+                default: isCursorPagination
+                    ? (pagination.defaultLimit ?? CURSOR_PAGINATION_DEFAULT_LIMIT)
+                    : (pagination.defaultLimit ?? OFFSET_PAGINATION_DEFAULT_LIMIT),
+            },
+            ...paginationProperties,
+        },
+    };
+}
+//# sourceMappingURL=OasGenerator.js.map