@api-client/core 0.19.18 → 0.19.20

package/tests/unit/modeling/exposed_entity.spec.ts

@@ -231,6 +231,77 @@ test.group('ExposedEntity', () => {
     assert.equal(ex.accessRule![0].type, 'allowPublic')
   }).tags(['@modeling', '@exposed-entity', '@immutability'])
 
+  test('initializes with paginationContract', ({ assert }) => {
+    const model = new ApiModel()
+    const contract = {
+      searchableFields: ['name'],
+      filterableFields: ['status'],
+      sortableFields: ['createdAt'],
+    }
+    const ex = new ExposedEntity(model, {
+      paginationContract: contract,
+    })
+
+    assert.deepEqual(ex.paginationContract, contract)
+  }).tags(['@modeling', '@exposed-entity'])
+
+  test('toJSON serializes paginationContract safely', ({ assert }) => {
+    const model = new ApiModel()
+    const ex = new ExposedEntity(model, {
+      paginationContract: { sortableFields: ['name'], filterableFields: [], searchableFields: [] },
+    })
+
+    const json = ex.toJSON()
+    assert.deepEqual(json.paginationContract, { sortableFields: ['name'], filterableFields: [], searchableFields: [] })
+
+    // Modify json to ensure immutability
+    json.paginationContract!.sortableFields.push('modified')
+    assert.lengthOf(ex.paginationContract!.sortableFields, 1)
+  }).tags(['@modeling', '@exposed-entity', '@serialization', '@immutability'])
+
+  test('constructor deep copies paginationContract (immutability)', ({ assert }) => {
+    const model = new ApiModel()
+    const contract = {
+      searchableFields: ['name'],
+      filterableFields: [],
+      sortableFields: [],
+    }
+    const ex = new ExposedEntity(model, {
+      paginationContract: contract,
+    })
+
+    contract.searchableFields.push('age')
+    assert.lengthOf(ex.paginationContract!.searchableFields, 1)
+  }).tags(['@modeling', '@exposed-entity', '@immutability'])
+
+  test('notifies change when paginationContract changes', async ({ assert }) => {
+    const model = new ApiModel()
+    const ex = new ExposedEntity(model, {})
+    let notified = false
+    ex.addEventListener('change', () => {
+      notified = true
+    })
+
+    ex.paginationContract = { sortableFields: [], filterableFields: [], searchableFields: [] }
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@exposed-entity', '@observed'])
+
+  test('notifies change when paginationContract property mutates', async ({ assert }) => {
+    const model = new ApiModel()
+    const ex = new ExposedEntity(model, {
+      paginationContract: { sortableFields: [], filterableFields: [], searchableFields: [] },
+    })
+    let notified = false
+    ex.addEventListener('change', () => {
+      notified = true
+    })
+
+    ex.paginationContract!.sortableFields.push('name')
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@exposed-entity', '@observed'])
+
   test('getAllRules() aggregates rules from entity, parent, and API', ({ assert }) => {
     const model = new ApiModel()
     model.accessRule = [new AccessRule({ type: 'allowPublic' })]

package/tests/unit/modeling/generators/OasGenerator.spec.ts

@@ -0,0 +1,302 @@
+import { test } from '@japa/runner'
+import { OasGenerator } from '../../../../src/modeling/generators/oas_312/OasGenerator.js'
+import { ApiModel } from '../../../../src/modeling/ApiModel.js'
+import { DataDomain } from '../../../../src/modeling/DataDomain.js'
+import { SemanticType } from '../../../../src/modeling/Semantics.js'
+import { AllowAuthenticatedAccessRule } from '../../../../src/modeling/rules/AllowAuthenticated.js'
+
+test.group('OasGenerator', (group) => {
+  let domain: DataDomain
+  let api: ApiModel
+
+  group.each.setup(() => {
+    domain = new DataDomain({ info: { name: 'Test Domain', version: '1.0.0' } })
+    const model = domain.addModel({ info: { name: 'model1' } })
+    const user = model.addEntity({ info: { name: 'user' } })
+    user.addSemantic({ id: SemanticType.User })
+    user.addProperty({
+      type: 'string',
+      required: true,
+      info: { name: 'id' },
+      index: true,
+      primary: true,
+      readOnly: true,
+    })
+    const name = user.addProperty({ type: 'string', required: true, info: { name: 'name' }, search: true })
+    const email = user.addProperty({
+      type: 'string',
+      required: true,
+      index: true,
+      unique: true,
+      search: true,
+      info: { name: 'email' },
+      semantics: [{ id: SemanticType.Email }, { id: SemanticType.Username }],
+    })
+    const passwd = user.addProperty({
+      type: 'string',
+      required: true,
+      info: { name: 'password' },
+      writeOnly: true,
+      semantics: [{ id: SemanticType.Password }],
+    })
+    const role = user.addProperty({
+      type: 'string',
+      required: true,
+      info: { name: 'role' },
+      schema: { enum: ['admin', 'user'] },
+      index: true,
+    })
+    role.addSemantic({ id: SemanticType.UserRole })
+    user.addProperty({
+      type: 'string',
+      required: true,
+      info: { name: 'avatar' },
+      semantics: [{ id: SemanticType.ImageURL }],
+    })
+    user.addProperty({
+      type: 'string',
+      required: false,
+      info: { name: 'cv' },
+      semantics: [{ id: SemanticType.FileURL }],
+    })
+
+    const post = model.addEntity({
+      info: { name: 'post', description: 'Represents a post published by a user', displayName: 'Post' },
+    })
+    post.addProperty({
+      type: 'string',
+      required: true,
+      info: { name: 'id', description: 'Post ID', displayName: 'ID' },
+      primary: true,
+      readOnly: true,
+    })
+    const postTitle = post.addProperty({
+      type: 'string',
+      required: true,
+      info: { name: 'title', description: 'Post title', displayName: 'Title' },
+      semantics: [{ id: SemanticType.Title }],
+      schema: {
+        examples: ['My blog title', 'Another title'],
+        minimum: 5,
+        maximum: 255,
+      },
+      search: true,
+    })
+    const postSlug = post.addProperty({
+      type: 'string',
+      required: true,
+      info: {
+        name: 'slug',
+        description: 'Post slug. It is auto generated when a post is created and cannot be changed.',
+        displayName: 'Slug',
+      },
+      readOnly: true,
+      index: true,
+      semantics: [{ id: SemanticType.PublicUniqueName, config: {} }],
+    })
+    post.addProperty({ type: 'string', required: true, info: { name: 'content' }, search: true })
+    const postCreatedAt = post.addProperty({
+      type: 'string',
+      required: true,
+      info: { name: 'created_at' },
+      index: true,
+      semantics: [{ id: SemanticType.CreatedTimestamp }],
+    })
+    post.addProperty({
+      type: 'string',
+      required: true,
+      info: { name: 'updated_at' },
+      index: true,
+      semantics: [{ id: SemanticType.UpdatedTimestamp }],
+    })
+    post.addAssociation({
+      info: { name: 'author' },
+      targets: [{ key: user.key }],
+      multiple: false,
+      schema: { linked: true },
+      semantics: [{ id: SemanticType.ResourceOwnerIdentifier }],
+    })
+
+    api = new ApiModel({ key: 'api1', info: { name: 'Test API', version: '1.0.0' } }, domain)
+    api.license = {
+      name: 'BSD-3-Clause-No-Nuclear-License-2014',
+      url: 'https://opensource.org/licenses/BSD-3-Clause-No-Nuclear-License-2014',
+    }
+    api.contact = {
+      email: 'info@api.com',
+      name: 'API Admin',
+      url: 'https://api.com',
+    }
+    api.accessRule = [new AllowAuthenticatedAccessRule()]
+    api.session = {
+      properties: [email.key],
+      secret: 'test-secret',
+      cookie: {
+        enabled: true,
+        httpOnly: true,
+        secure: true,
+        kind: 'cookie',
+        lifetime: '30d',
+        name: 'sis',
+        sameSite: 'lax',
+      },
+      jwt: {
+        enabled: true,
+        kind: 'jwt',
+        lifetime: '30d',
+      },
+    }
+    api.authentication = {
+      strategy: 'UsernamePassword',
+      passwordKey: passwd.key,
+    }
+    api.authorization = {
+      strategy: 'RBAC',
+      roleKey: role.key,
+    }
+    api.pagination = { kind: 'cursor', defaultLimit: 50, maxLimit: 70 }
+    const userExposure = api.exposeEntity({ key: user.key })
+    userExposure.paginationContract = {
+      filterableFields: [role.key],
+      sortableFields: [name.key, email.key, role.key],
+      searchableFields: [name.key, email.key],
+    }
+    const postExposure = api.exposeEntity({ key: post.key })
+    postExposure.paginationContract = {
+      filterableFields: [postSlug.key, postCreatedAt.key],
+      sortableFields: [postSlug.key, postCreatedAt.key],
+      searchableFields: [postTitle.key],
+    }
+    userExposure.addAction({ kind: 'list', cacheTtl: 1800 })
+    userExposure.addAction({ kind: 'create', accessRule: [{ type: 'allowPublic' }] })
+    userExposure.addAction({ kind: 'read' })
+    userExposure.addAction({ kind: 'update', allowedMethods: ['PUT'] })
+    userExposure.addAction({ kind: 'delete', strategy: 'soft', retentionPeriod: 30 })
+    userExposure.addAction({ kind: 'search', maxAstDepth: 1 })
+    postExposure.addAction({ kind: 'list', cacheTtl: 3600 })
+    postExposure.addAction({ kind: 'update', allowedMethods: ['PUT', 'PATCH'] })
+    postExposure.addAction({ kind: 'delete', strategy: 'hard' })
+    postExposure.addAction({ kind: 'search', maxAstDepth: 2 })
+  })
+
+  test('generates basic OAS structure', async ({ assert }) => {
+    const generator = new OasGenerator(api)
+    const oas = generator.generate()
+
+    assert.equal(oas.openapi, '3.1.0')
+    assert.typeOf(oas.info, 'object')
+    assert.isObject(oas.paths)
+    assert.isObject(oas.components)
+  })
+
+  test('generates cookie auth endpoints', ({ assert }) => {
+    const generator = new OasGenerator(api)
+    const oas = generator.generate()
+
+    const components = oas.components as any
+    assert.deepEqual(components.securitySchemes.CookieAuth, {
+      type: 'apiKey',
+      in: 'cookie',
+      name: 'sis',
+      description: 'Session cookie obtained after authenticating',
+    })
+
+    const paths = oas.paths as any
+    assert.isObject(paths['/auth/cookie'].post)
+    assert.isObject(paths['/auth/cookie/logout'].post)
+    assert.include(paths['/auth/cookie'].post.tags, 'Authentication')
+  })
+
+  test('generates jwt auth endpoints', ({ assert }) => {
+    const generator = new OasGenerator(api)
+    const oas = generator.generate()
+
+    const components = oas.components as any
+    assert.deepEqual(components.securitySchemes.BearerAuth, {
+      type: 'http',
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+      description: 'JWT authorization obtained after trading Username/Password credentials',
+    })
+
+    const paths = oas.paths as any
+    assert.isObject(paths['/auth/token'].post)
+    assert.isObject(paths['/auth/token/{token}'].delete)
+    assert.include(paths['/auth/token'].post.tags, 'Authentication')
+  })
+
+  test('generates paths for exposed entity actions', ({ assert }) => {
+    const generator = new OasGenerator(api)
+    const oas = generator.generate()
+
+    const paths = oas.paths as any
+
+    // User endpoints (CRUD)
+    assert.isObject(paths['/users'].get, 'User list')
+    assert.isObject(paths['/users'].post, 'User create')
+    assert.isObject(paths['/users/{id}'].get, 'User read')
+    assert.isObject(paths['/users/{id}'].put, 'User put')
+    assert.isObject(paths['/users/{id}'].delete, 'User delete')
+
+    // Post endpoints (list, update, delete)
+    assert.isObject(paths['/posts'].get)
+    assert.isUndefined(paths['/posts'].post) // no create Action
+    assert.isUndefined(paths['/posts/{id}'].get) // no read action
+    assert.isObject(paths['/posts/{id}'].patch)
+    assert.isObject(paths['/posts/{id}'].put)
+    assert.isObject(paths['/posts/{id}'].delete)
+  })
+
+  test('generates standard error responses', ({ assert }) => {
+    const generator = new OasGenerator(api)
+    const oas = generator.generate()
+
+    const paths = oas.paths as any
+    const postUser = paths['/users'].post
+    const getUser = paths['/users'].get
+
+    assert.isObject(postUser.responses['400']) // Validation Error
+    assert.equal(
+      postUser.responses['400'].content['application/json'].schema.$ref,
+      '#/components/schemas/Error400BadRequestInvalidFormat'
+    )
+
+    // Should have 401 when using auth
+    assert.isObject(getUser.responses['401'])
+    assert.equal(
+      getUser.responses['401'].content['application/json'].schema.$ref,
+      '#/components/schemas/Error401Unauthorized'
+    )
+  })
+
+  test('generates search endpoints and AST queries', ({ assert }) => {
+    const generator = new OasGenerator(api)
+    const oas = generator.generate()
+
+    const paths = oas.paths as any
+    assert.isObject(paths['/users/search'].post)
+    assert.isObject(paths['/posts/search'].post)
+
+    assert.include(paths['/users/search'].post.tags, 'User')
+    assert.include(paths['/posts/search'].post.tags, 'Post')
+
+    const components = oas.components as any
+    assert.isObject(components.schemas.SearchWhereAST)
+    assert.isObject(components.schemas.SearchWhereNode)
+    assert.isObject(components.schemas.SearchWhereOperatorMap)
+  })
+
+  test('generates file upload endpoint', ({ assert }) => {
+    const generator = new OasGenerator(api)
+    const oas = generator.generate()
+
+    const paths = oas.paths as any
+    assert.isObject(paths['/upload'].post)
+    assert.include(paths['/upload'].post.tags, 'File Upload')
+
+    const requestBody = paths['/upload'].post.requestBody
+    assert.isObject(requestBody.content['*/*'])
+    assert.equal(requestBody.content['*/*'].schema.type, 'string')
+    assert.equal(requestBody.content['*/*'].schema.format, 'binary')
+  })
+})

package/tests/unit/modeling/validation/api_model_rules.spec.ts

@@ -9,6 +9,7 @@ import {
   validateApiModelMetadata,
   validateExposedEntity,
   validateAction,
+  validateApiPagination,
 } from '../../../../src/modeling/validation/api_model_rules.js'
 import { ApiValidation } from '../../../../src/modeling/ApiValidation.js'
 import { ExposedEntity } from '../../../../src/modeling/ExposedEntity.js'
@@ -248,25 +249,60 @@ test.group('ApiModel Validation', () => {
     assert.isTrue(issues.some((i) => i.code === 'EXPOSURE_INVALID_RESOURCE_PATH_FORMAT'))
   })
 
-  test('validateAction - List needs pagination', ({ assert }) => {
-    const model = new ApiModel()
-    const exposure = new ExposedEntity(model, { entity: { key: '1' } })
-    const action = new ListAction(exposure)
-    // @ts-expect-error testing undefined pagination
-    action.pagination = undefined
+  test('validateExposedEntity - List needs pagination contract', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const model = new ApiModel({}, domain)
+    const exposure = new ExposedEntity(model, {
+      entity: { key: 'fake' },
+      hasCollection: true,
+      collectionPath: '/items',
+      resourcePath: '/items/{id}',
+    })
+    exposure.actions = [new ListAction(exposure)]
 
-    const issues = validateAction(action, exposure, model.key)
-    assert.isTrue(issues.some((i) => i.code === 'ACTION_LIST_MISSING_PAGINATION'))
+    const issues = validateExposedEntity(exposure, model)
+    assert.isTrue(issues.some((i) => i.code === 'EXPOSURE_MISSING_PAGINATION_CONTRACT'))
   })
 
-  test('validateAction - Search needs fields', ({ assert }) => {
-    const model = new ApiModel()
-    const exposure = new ExposedEntity(model, { entity: { key: '1' } })
-    const action = new SearchAction(exposure)
-    action.fields = []
+  test('validateExposedEntity - Search needs fields', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const model = new ApiModel({}, domain)
+    const exposure = new ExposedEntity(model, {
+      entity: { key: 'fake' },
+      hasCollection: true,
+      collectionPath: '/items',
+      resourcePath: '/items/{id}',
+    })
+    exposure.actions = [new SearchAction(exposure)]
+    exposure.paginationContract = {
+      searchableFields: [],
+      filterableFields: [],
+      sortableFields: [],
+    }
 
-    const issues = validateAction(action, exposure, model.key)
-    assert.isTrue(issues.some((i) => i.code === 'ACTION_SEARCH_MISSING_FIELDS'))
+    const issues = validateExposedEntity(exposure, model)
+    assert.isTrue(issues.some((i) => i.code === 'EXPOSURE_SEARCH_MISSING_FIELDS'))
+  })
+
+  test('validateExposedEntity - List needs filters and sorting', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const model = new ApiModel({}, domain)
+    const exposure = new ExposedEntity(model, {
+      entity: { key: 'fake' },
+      hasCollection: true,
+      collectionPath: '/items',
+      resourcePath: '/items/{id}',
+    })
+    exposure.actions = [new ListAction(exposure)]
+    exposure.paginationContract = {
+      searchableFields: [],
+      filterableFields: [],
+      sortableFields: [],
+    }
+
+    const issues = validateExposedEntity(exposure, model)
+    assert.isTrue(issues.some((i) => i.code === 'EXPOSURE_LIST_MISSING_FILTERS'))
+    assert.isTrue(issues.some((i) => i.code === 'EXPOSURE_LIST_MISSING_SORTING'))
   })
 
   test('validateAction - Delete needs strategy', ({ assert }) => {
@@ -289,6 +325,68 @@ test.group('ApiModel Validation', () => {
     const issues = validateAction(action, exposure, model.key)
     assert.isTrue(issues.some((i) => i.code === 'ACTION_UPDATE_MISSING_METHODS'))
   })
+
+  test('validateApiPagination - missing pagination', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const model = new ApiModel({}, domain)
+    // @ts-expect-error testing missing pagination property
+    model.pagination = undefined
+
+    const exposure = new ExposedEntity(model, {
+      entity: { key: 'fake' },
+      hasCollection: true,
+      collectionPath: '/items',
+      resourcePath: '/items/{id}',
+    })
+    exposure.actions = [new ListAction(exposure)]
+    model.exposes.set(exposure.key, exposure)
+
+    const issues = validateApiPagination(model)
+    assert.isTrue(issues.some((i) => i.code === 'API_MISSING_PAGINATION'))
+  })
+
+  test('validateApiPagination - missing default limit', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const model = new ApiModel(
+      {
+        pagination: { kind: 'offset', maxLimit: 100 },
+      },
+      domain
+    )
+    const exposure = new ExposedEntity(model, {
+      entity: { key: 'fake' },
+      hasCollection: true,
+      collectionPath: '/items',
+      resourcePath: '/items/{id}',
+    })
+    exposure.actions = [new ListAction(exposure)]
+    model.exposes.set(exposure.key, exposure)
+
+    const issues = validateApiPagination(model)
+    assert.isTrue(issues.some((i) => i.code === 'API_MISSING_PAGINATION_DEFAULT_LIMIT'))
+  })
+
+  test('validateApiPagination - missing max limit', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const model = new ApiModel(
+      {
+        pagination: { kind: 'offset', defaultLimit: 20 },
+      },
+      domain
+    )
+    const exposure = new ExposedEntity(model, {
+      entity: { key: 'fake' },
+      hasCollection: true,
+      collectionPath: '/items',
+      resourcePath: '/items/{id}',
+    })
+    exposure.actions = [new ListAction(exposure)]
+    model.exposes.set(exposure.key, exposure)
+
+    const issues = validateApiPagination(model)
+    assert.isTrue(issues.some((i) => i.code === 'API_MISSING_PAGINATION_MAX_LIMIT'))
+  })
+
   test('validateApiModel - success aggregates without issues', ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const modelNode = domain.addModel({ key: 'users' })