@api-client/core 0.18.1 → 0.18.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/ApiModel.ts

@@ -3,6 +3,7 @@ import { ApiModelKind, DataDomainKind } from '../models/kinds.js'
 import { type IThing, Thing } from '../models/Thing.js'
 import type {
   AccessRule,
+  AssociationTarget,
   AuthenticationConfiguration,
   AuthorizationConfiguration,
   ExposedEntity,
@@ -12,7 +13,40 @@ import type {
   UsernamePasswordConfiguration,
 } from './types.js'
 import { DataDomain } from './DataDomain.js'
-import { DependentModel, type DomainDependency, type DependentModelSchema } from './DependentModel.js'
+import { DependentModel, type DependentModelSchema, type DomainDependency } from './DependentModel.js'
+import { observed, toRaw } from './observed.js'
+
+/**
+ * Contact information for the exposed API.
+ */
+export interface ApiContact {
+  /**
+   * The identifying name of the contact person/organization.
+   */
+  name?: string
+  /**
+   * The URL pointing to the contact information. MUST be in the format of a URL.
+   */
+  url?: string
+  /**
+   * The email address of the contact person/organization. MUST be in the format of an email address.
+   */
+  email?: string
+}
+
+/**
+ * License information for the exposed API.
+ */
+export interface ApiLicense {
+  /**
+   * The license name used for the API. It is recommended to be an SPDX license identifier.
+   */
+  name: string
+  /**
+   * A URL to the license used for the API. MUST be in the format of a URL.
+   */
+  url?: string
+}
 
 export interface ApiModelSchema extends DependentModelSchema {
   /**
@@ -31,11 +65,11 @@ export interface ApiModelSchema extends DependentModelSchema {
 
   /**
    * The designated Data Entity that represents a "User".
-   * This entity must be marked with the "User" semantic in the Data Modeler.
+   * This entity should be marked with the "User" semantic in the Data Modeler.
    *
    * This property is required to publish the API.
    */
-  userKey?: string
+  user?: AssociationTarget
 
   /**
    * Configuration for how users prove their identity.
@@ -74,6 +108,18 @@ export interface ApiModelSchema extends DependentModelSchema {
    * Defines rules to protect the API from overuse.
    */
   rateLimiting?: RateLimitingConfiguration
+  /**
+   * A URL to the Terms of Service for the API.
+   */
+  termsOfService?: string
+  /**
+   * The contact information for the exposed API.
+   */
+  contact?: ApiContact
+  /**
+   * The license information for the API.
+   */
+  license?: ApiLicense
 }
 
 export class ApiModel extends DependentModel {
@@ -97,7 +143,7 @@ export class ApiModel extends DependentModel {
    *
    * This property is required to publish the API.
    */
-  userKey?: string
+  user?: AssociationTarget
 
   /**
    * Configuration for how users prove their identity.
@@ -135,6 +181,18 @@ export class ApiModel extends DependentModel {
    * Defines rules to protect the API from overuse.
    */
   rateLimiting?: RateLimitingConfiguration
+  /**
+   * A URL to the Terms of Service for the API.
+   */
+  @observed() accessor termsOfService: string | undefined
+  /**
+   * The contact information for the exposed API.
+   */
+  @observed({ deep: true }) accessor contact: ApiContact | undefined
+  /**
+   * The license information for the API.
+   */
+  @observed({ deep: true }) accessor license: ApiLicense | undefined
 
   /**
    * When the initializing flag is set to true,
@@ -175,8 +233,8 @@ export class ApiModel extends DependentModel {
       info,
       exposes,
     }
-    if (input.userKey) {
-      result.userKey = input.userKey
+    if (input.user) {
+      result.user = { ...input.user }
     }
     if (input.dependencyList) {
       result.dependencyList = structuredClone(input.dependencyList)
@@ -196,6 +254,15 @@ export class ApiModel extends DependentModel {
     if (input.rateLimiting) {
       result.rateLimiting = input.rateLimiting
     }
+    if (input.termsOfService) {
+      result.termsOfService = input.termsOfService
+    }
+    if (input.contact) {
+      result.contact = structuredClone(input.contact)
+    }
+    if (input.license) {
+      result.license = structuredClone(input.license)
+    }
     return result
   }
 
@@ -213,7 +280,7 @@ export class ApiModel extends DependentModel {
     this.kind = init.kind
     this.key = init.key
     this.info = new Thing(init.info)
-    this.userKey = init.userKey
+    this.user = init.user
     if (init.authentication) {
       this.authentication = structuredClone(init.authentication)
     }
@@ -234,6 +301,15 @@ export class ApiModel extends DependentModel {
     if (init.rateLimiting) {
       this.rateLimiting = structuredClone(init.rateLimiting)
     }
+    if (init.termsOfService) {
+      this.termsOfService = init.termsOfService
+    }
+    if (init.contact) {
+      this.contact = init.contact
+    }
+    if (init.license) {
+      this.license = init.license
+    }
     this.#initializing = false
     this.info.addEventListener('change', () => {
       this.notifyChange()
@@ -247,8 +323,8 @@ export class ApiModel extends DependentModel {
       info: this.info.toJSON(),
       exposes: structuredClone(this.exposes),
     }
-    if (this.userKey) {
-      result.userKey = this.userKey
+    if (this.user) {
+      result.user = { ...this.user }
     }
     if (this.dependencyList.length > 0) {
       result.dependencyList = structuredClone(this.dependencyList)
@@ -268,6 +344,15 @@ export class ApiModel extends DependentModel {
     if (this.rateLimiting) {
       result.rateLimiting = structuredClone(this.rateLimiting)
     }
+    if (this.termsOfService) {
+      result.termsOfService = this.termsOfService
+    }
+    if (this.contact) {
+      result.contact = structuredClone(toRaw(this, this.contact))
+    }
+    if (this.license) {
+      result.license = structuredClone(toRaw(this, this.license))
+    }
     return result
   }
 
@@ -330,14 +415,14 @@ export class ApiModel extends DependentModel {
 
   /**
    * Clears the API model for a new entity change.
-   * This method resets the dependencies, exposes, userKey,
+   * This method resets the dependencies, exposes, user,
    * authentication, authorization, and session properties.
    */
   cleanForEntityChange(): void {
     this.dependencies.clear()
     this.dependencyList = []
     this.exposes = []
-    this.userKey = undefined
+    this.user = undefined
     if (this.session) {
       this.session.properties = []
     }

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

@@ -6,6 +6,8 @@ import {
   type RolesBasedAccessControl,
   type ApiModelSchema,
   type ExposedEntity,
+  type ApiContact,
+  type ApiLicense,
 } from '../../../src/index.js'
 
 test.group('ApiModel.createSchema()', (g) => {
@@ -19,13 +21,16 @@ test.group('ApiModel.createSchema()', (g) => {
     assert.isNotEmpty(schema.key)
     assert.deepInclude(schema.info, { name: 'Unnamed API' })
     assert.deepEqual(schema.exposes, [])
-    assert.isUndefined(schema.userKey)
+    assert.isUndefined(schema.user)
     assert.isUndefined(schema.dependencyList)
     assert.isUndefined(schema.authentication)
     assert.isUndefined(schema.authorization)
     assert.isUndefined(schema.session)
     assert.isUndefined(schema.accessRule)
     assert.isUndefined(schema.rateLimiting)
+    assert.isUndefined(schema.termsOfService)
+    assert.isUndefined(schema.contact)
+    assert.isUndefined(schema.license)
   })
 
   test('creates a schema with provided values', ({ assert }) => {
@@ -33,13 +38,16 @@ test.group('ApiModel.createSchema()', (g) => {
       key: 'test-api',
       info: { name: 'Test API', description: 'A test API' },
       exposes: [{ key: 'entity1', actions: [] }],
-      userKey: 'user-entity',
+      user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
       authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
       session: { secret: 'secret', properties: ['email'] },
       accessRule: [{ type: 'public' }],
       rateLimiting: { rules: [] },
+      termsOfService: 'https://example.com/terms',
+      contact: { name: 'John Doe', email: 'john.doe@example.com' } as ApiContact,
+      license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' } as ApiLicense,
     }
     const schema = ApiModel.createSchema(input)
 
@@ -47,13 +55,16 @@ test.group('ApiModel.createSchema()', (g) => {
     assert.equal(schema.key, 'test-api')
     assert.deepInclude(schema.info, { name: 'Test API', description: 'A test API' })
     assert.deepEqual(schema.exposes, [{ key: 'entity1', actions: [] }])
-    assert.equal(schema.userKey, 'user-entity')
+    assert.deepEqual(schema.user, { key: 'user-entity' })
     assert.deepEqual(schema.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(schema.authentication, { strategy: 'UsernamePassword' })
     assert.deepEqual(schema.authorization, { strategy: 'RBAC', roleKey: 'role' })
     assert.deepEqual(schema.session, { secret: 'secret', properties: ['email'] })
     assert.deepEqual(schema.accessRule, [{ type: 'public' }])
     assert.deepEqual(schema.rateLimiting, { rules: [] })
+    assert.equal(schema.termsOfService, 'https://example.com/terms')
+    assert.deepEqual(schema.contact, { name: 'John Doe', email: 'john.doe@example.com' })
+    assert.deepEqual(schema.license, { name: 'MIT', url: 'https://opensource.org/licenses/MIT' })
   })
 
   test('creates a schema with partial info', ({ assert }) => {
@@ -79,12 +90,15 @@ test.group('ApiModel.constructor()', (g) => {
     assert.isNotEmpty(model.key)
     assert.equal(model.info.name, 'Unnamed API')
     assert.deepEqual(model.exposes, [])
-    assert.isUndefined(model.userKey)
+    assert.isUndefined(model.user)
     assert.isUndefined(model.authentication)
     assert.isUndefined(model.authorization)
     assert.isUndefined(model.session)
     assert.isUndefined(model.accessRule)
     assert.isUndefined(model.rateLimiting)
+    assert.isUndefined(model.termsOfService)
+    assert.isUndefined(model.contact)
+    assert.isUndefined(model.license)
     assert.deepEqual(model.dependencyList, [])
   })
 
@@ -94,26 +108,32 @@ test.group('ApiModel.constructor()', (g) => {
       key: 'test-api',
       info: { name: 'Test API', description: 'A test API' },
       exposes: [{ key: 'entity1', actions: [] }],
-      userKey: 'user-entity',
+      user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
       authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
       session: { secret: 'secret', properties: ['email'] },
       accessRule: [{ type: 'public' }],
       rateLimiting: { rules: [] },
+      termsOfService: 'https://example.com/terms',
+      contact: { name: 'John Doe', email: 'john.doe@example.com' },
+      license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' },
     }
     const model = new ApiModel(schema)
 
     assert.equal(model.key, 'test-api')
     assert.equal(model.info.name, 'Test API')
     assert.deepEqual(model.exposes, [{ key: 'entity1', actions: [] }])
-    assert.equal(model.userKey, 'user-entity')
+    assert.deepEqual(model.user, { key: 'user-entity' })
     assert.deepEqual(model.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(model.authentication, { strategy: 'UsernamePassword' })
     assert.deepEqual(model.authorization, { strategy: 'RBAC', roleKey: 'role' })
     assert.deepEqual(model.session, { secret: 'secret', properties: ['email'] })
     assert.deepEqual(model.accessRule, [{ type: 'public' }])
     assert.deepEqual(model.rateLimiting, { rules: [] })
+    assert.equal(model.termsOfService, 'https://example.com/terms')
+    assert.deepEqual(model.contact, { name: 'John Doe', email: 'john.doe@example.com' })
+    assert.deepEqual(model.license, { name: 'MIT', url: 'https://opensource.org/licenses/MIT' })
   })
 
   test('creates an instance with a DataDomain', ({ assert }) => {
@@ -152,13 +172,16 @@ test.group('ApiModel.toJSON()', (g) => {
     assert.equal(json.key, model.key)
     assert.deepInclude(json.info, { name: 'Unnamed API' })
     assert.deepEqual(json.exposes, [])
-    assert.isUndefined(json.userKey)
+    assert.isUndefined(json.user)
     assert.isUndefined(json.dependencyList)
     assert.isUndefined(json.authentication)
     assert.isUndefined(json.authorization)
     assert.isUndefined(json.session)
     assert.isUndefined(json.accessRule)
     assert.isUndefined(json.rateLimiting)
+    assert.isUndefined(json.termsOfService)
+    assert.isUndefined(json.contact)
+    assert.isUndefined(json.license)
   })
 
   test('serializes all provided values', ({ assert }) => {
@@ -167,13 +190,16 @@ test.group('ApiModel.toJSON()', (g) => {
       key: 'test-api',
       info: { name: 'Test API', description: 'A test API' },
       exposes: [{ key: 'entity1', actions: [] }],
-      userKey: 'user-entity',
+      user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
       authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
       session: { secret: 'secret', properties: ['email'] },
       accessRule: [{ type: 'public' }],
       rateLimiting: { rules: [] },
+      termsOfService: 'https://example.com/terms',
+      contact: { name: 'John Doe', email: 'john.doe@example.com' },
+      license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' },
     }
     const model = new ApiModel(schema)
     const json = model.toJSON()
@@ -181,13 +207,16 @@ test.group('ApiModel.toJSON()', (g) => {
     assert.equal(json.key, 'test-api')
     assert.deepInclude(json.info, { name: 'Test API', description: 'A test API' })
     assert.deepEqual(json.exposes, [{ key: 'entity1', actions: [] }])
-    assert.equal(json.userKey, 'user-entity')
+    assert.deepEqual(json.user, { key: 'user-entity' })
     assert.deepEqual(json.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(json.authentication, { strategy: 'UsernamePassword' })
     assert.deepEqual(json.authorization, { strategy: 'RBAC', roleKey: 'role' })
     assert.deepEqual(json.session, { secret: 'secret', properties: ['email'] })
     assert.deepEqual(json.accessRule, [{ type: 'public' }])
     assert.deepEqual(json.rateLimiting, { rules: [] })
+    assert.equal(json.termsOfService, 'https://example.com/terms')
+    assert.deepEqual(json.contact, { name: 'John Doe', email: 'john.doe@example.com' })
+    assert.deepEqual(json.license, { name: 'MIT', url: 'https://opensource.org/licenses/MIT' })
   })
 })