@api-client/core 0.19.18 → 0.19.20

package/src/modeling/generators/oas_312/OasGenerator.ts

@@ -0,0 +1,1685 @@
+import { type JSONSchema } from 'json-schema-typed/draft-2020-12'
+import pluralize from '@jarrodek/pluralize'
+import type {
+  InfoObject,
+  OpenApi312,
+  ParameterObject,
+  PathItemObject,
+  PathsObject,
+  SecurityRequirementObject,
+  SecuritySchemeObject,
+  OperationObject,
+  LinkObject,
+  SchemaObject,
+} from './types.js'
+import type { ApiModel } from '../../ApiModel.js'
+import type { Action } from '../../actions/Action.js'
+import { OasSchemaGenerator } from './OasSchemaGenerator.js'
+import type { MatchUserRoleAccessRule } from '../../rules/MatchUserRole.js'
+import type { UpdateAction } from '../../actions/UpdateAction.js'
+import type { ListAction } from '../../actions/ListAction.js'
+import type { CreateAction } from '../../actions/CreateAction.js'
+import type { ReadAction } from '../../actions/ReadAction.js'
+import type { DeleteAction } from '../../actions/DeleteAction.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'
+import { DomainEntity } from '../../DomainEntity.js'
+import type { DomainPropertyType } from '../../DataFormat.js'
+import type {
+  CursorPaginationStrategy,
+  OffsetPaginationStrategy,
+  PaginationContract,
+  ResourceFilterOperator,
+} from '../../types.js'
+import type { DomainProperty } from '../../DomainProperty.js'
+import type { SearchAction } from '../../actions/SearchAction.js'
+
+export class OasGenerator {
+  private whereAstInjected = false
+
+  #hasListAction = false
+
+  get hasListAction(): boolean {
+    return this.#hasListAction
+  }
+
+  #hasSearchAction = false
+
+  /**
+   * A flag that determines whether any of the entities has the `Search` action.
+   */
+  get hasSearchAction(): boolean {
+    return this.#hasSearchAction
+  }
+
+  /**
+   * @param model The API model to generate OAS for.
+   */
+  constructor(private model: ApiModel) {}
+
+  generate(): OpenApi312 {
+    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: NonNullable<OpenApi312['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: OpenApi312 = {
+      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: SecurityRequirementObject[] = []
+    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
+  }
+
+  private generateInfo(): InfoObject {
+    const info: InfoObject = {
+      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
+  }
+
+  private generateSecuritySchemes(): Record<string, SecuritySchemeObject> {
+    const schemes: Record<string, SecuritySchemeObject> = {}
+
+    // 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
+  }
+
+  private generateErrorSchemas(): Record<string, SchemaObject> {
+    const createErrorSchema = (
+      name: string,
+      status: number,
+      typeUri: string,
+      title: string,
+      description: string
+    ): SchemaObject => {
+      const properties: Record<string, SchemaObject> = {
+        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.'
+      ),
+    }
+  }
+
+  private generatePaths(schemaGen: OasSchemaGenerator): PathsObject {
+    const paths: PathsObject = {}
+
+    // 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: Record<string, LinkObject> = {}
+      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) as string
+      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: SearchAction | undefined
+
+      if (expose.hasCollection && colPath) {
+        const pathItem: PathItemObject = paths[colPath] || {}
+        paths[colPath] = pathItem
+
+        const listAction = expose.actions.find((a) => a.kind === 'list') as ListAction | undefined
+        const createAction = expose.actions.find((a) => a.kind === 'create') as CreateAction | undefined
+        searchAction = expose.actions.find((a) => a.kind === 'search') as SearchAction | undefined
+
+        if (listAction) {
+          this.#hasListAction = true
+          const isCursor = this.model.pagination.kind === 'cursor'
+          const paginationParameters = isCursor
+            ? this.createCursorPaginationQueryParameters(colPath)
+            : this.createOffsetPaginationQueryParameters(colPath)
+          const op: OperationObject = {
+            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: OperationObject = {
+            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: PathItemObject = paths[resPath] || {}
+        paths[resPath] = pathItem
+
+        const readAction = expose.actions.find((a) => a.kind === 'read') as ReadAction | undefined
+        const updateAction = expose.actions.find((a) => a.kind === 'update') as UpdateAction | undefined
+        const deleteAction = expose.actions.find((a) => a.kind === 'delete') as DeleteAction | undefined
+
+        const parameters = this.extractPathParameters(resPath)
+
+        if (readAction) {
+          const op: OperationObject = {
+            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: OperationObject = {
+            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: PathItemObject = paths[searchPath] || {}
+        paths[searchPath] = pathItem
+
+        const searchProperties: DomainProperty[] = []
+        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: OperationObject = {
+          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 as string]: { 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
+  }
+
+  private extractPathParameters(path: string): ParameterObject[] {
+    const params: ParameterObject[] = []
+    const regex = /\{([^}]+)\}/g
+    let match: RegExpExecArray | null
+    while ((match = regex.exec(path)) !== null) {
+      params.push({
+        name: match[1],
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      })
+    }
+    return params
+  }
+
+  private applyActionSecurity(action: Action, operation: OperationObject): void {
+    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: SecurityRequirementObject[] = []
+      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') as MatchUserRoleAccessRule[]
+    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
+    }
+  }
+
+  private applyStandardResponse(
+    action: Action,
+    operation: OperationObject,
+    opts: { hasBody: boolean; isResource: boolean; isCreate: boolean }
+  ): void {
+    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',
+          },
+        },
+      },
+    }
+  }
+
+  private resolvePaginationDefault(
+    configuredDefault: number | undefined,
+    min: number,
+    maximum: number,
+    fallbackDefault: number
+  ): number {
+    const defaultValue =
+      typeof configuredDefault === 'number' && !Number.isNaN(configuredDefault) ? configuredDefault : fallbackDefault
+    return Math.max(min, Math.min(defaultValue, maximum))
+  }
+
+  private resolvePaginationMaximum(configuredMax: number | undefined, min: number, fallbackMax: number): number {
+    if (typeof configuredMax !== 'number' || Number.isNaN(configuredMax)) {
+      return fallbackMax
+    }
+    return Math.max(min, Math.min(configuredMax, fallbackMax))
+  }
+
+  private createCursorPaginationQueryParameters(path: string): ParameterObject[] {
+    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: ParameterObject[] = [
+      {
+        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
+  }
+
+  private createOffsetPaginationQueryParameters(path: string): ParameterObject[] {
+    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: ParameterObject[] = [
+      {
+        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
+  }
+
+  private createListParameters(
+    entity: DomainEntity,
+    path: string,
+    paginationContract?: PaginationContract
+  ): ParameterObject[] {
+    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: ParameterObject[] = []
+    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
+  }
+
+  private createListParameter(
+    property: DomainProperty,
+    operator: ResourceFilterOperator,
+    path: string
+  ): ParameterObject {
+    const paramName = `${property.info.name}[${operator}]`
+    const name = `${property.info.name}`
+
+    // Base Parameter scaffolding
+    const result: ParameterObject = {
+      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
+  }
+
+  private createSortParameter(path: string, entity: DomainEntity): ParameterObject {
+    const indexedFields: string[] = []
+    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: ParameterObject = {
+      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: Record<DomainPropertyType, ResourceFilterOperator[]> = {
+  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: Record<ResourceFilterOperator, string> = {
+  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: Record<ResourceFilterOperator, (path: string, key: string) => string> = {
+  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: DomainPropertyType): JSONSchema {
+  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?: string): string | undefined {
+  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(): PathsObject {
+  const paths: PathsObject = {}
+  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'],
+            } as SchemaObject,
+          },
+        },
+      },
+      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'],
+              } as SchemaObject,
+            },
+          },
+        },
+        '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(): PathsObject {
+  const paths: PathsObject = {}
+  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'],
+            } as SchemaObject,
+          },
+        },
+      },
+      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'],
+            } as SchemaObject,
+          },
+        },
+      },
+      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(): SchemaObject {
+  // We adopt the AdonisJS pagination schema.
+  const properties: Record<string, SchemaObject> = {
+    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: SchemaObject = {
+    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(): SchemaObject {
+  const properties: Record<string, SchemaObject> = {
+    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: SchemaObject = {
+    type: 'object',
+    description: 'Cursor pagination metadata.',
+    properties,
+    required: ['next_cursor', 'has_more'],
+  }
+  return schema
+}
+
+function generateSearchRequestBody(pagination: CursorPaginationStrategy | OffsetPaginationStrategy): SchemaObject {
+  const isCursorPagination = pagination.kind === 'cursor'
+  const paginationProperties: Record<string, SchemaObject> = 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,
+    },
+  }
+}