@api-client/core 0.14.2 → 0.14.4

package/src/models/store/Group.ts

@@ -1,21 +1,167 @@
+import { GroupKind } from '../kinds.js'
+import type { IDeletion } from './Deletion.js'
+import { nanoid } from '../../nanoid.js'
+
+/**
+ * @deprecated Use `GroupSchema` instead.
+ * This interface is kept for backward compatibility.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface IGroup extends GroupSchema {}
+
 /**
  * An object representing a user group.
  */
-export interface IGroup {
+export interface GroupSchema {
+  kind: typeof GroupKind
   /**
    * The key of the group.
+   * If not provided, it will be generated automatically by the API
    */
   key: string
   /**
-   * The name of the group
+   * The name of the group.
+   * This is a required field and must be unique within the organization.
+   * @required
    */
   name: string
+  /**
+   * The description of the group.
+   */
+  description?: string
   /**
    * The id of the user that created this group.
+   * This field is ignored by the API and is set automatically.
+   * @readonly
    */
   owner: string
+  /**
+   * The icon of the group, if any.
+   * An optional icon for the group, stored as a URL or path.
+   * Max 255 characters.
+   */
+  icon?: string
+  /**
+   * The color of the group, if any.
+   * An optional color for the group, stored as a hex code.
+   * Max 50 characters (including the #).
+   */
+  color?: string
+  /**
+   * The organization ID this group belongs to.
+   * This field is ignored by the API and is set automatically.
+   * @readonly
+   */
+  oid: string
   /**
    * The list of users in this group.
+   * This field is ignored by the API and is set automatically.
+   * @readonly
    */
   users: string[]
+  /**
+   * Describes when this group was created
+   * This field is ignored by the API and is set automatically.
+   * @readonly
+   */
+  createdAt: number
+  /**
+   * Describes when this group was updated
+   * This field is ignored by the API and is set automatically.
+   * @readonly
+   */
+  updatedAt: number
+  /**
+   * Optional deletion information if the group has been deleted.
+   * This field is ignored by the API and is set automatically.
+   * @readonly
+   */
+  deleteInfo?: IDeletion
+}
+
+export class Group implements GroupSchema {
+  kind: typeof GroupKind = GroupKind
+  key = ''
+  name = ''
+  description?: string
+  owner = ''
+  icon?: string
+  color?: string
+  oid = ''
+  users: string[] = []
+  createdAt = 0
+  updatedAt = 0
+  deleteInfo?: IDeletion
+
+  static createSchema(input: Partial<GroupSchema> = {}): GroupSchema {
+    const { key = nanoid() } = input
+    const result: GroupSchema = {
+      kind: GroupKind,
+      key,
+      name: input.name || 'Unnamed group',
+      oid: input.oid || '',
+      owner: input.owner || '',
+      users: input.users || [],
+      createdAt: input.createdAt || Date.now(),
+      updatedAt: input.updatedAt || Date.now(),
+    }
+    if (input.description) {
+      result.description = input.description
+    }
+    if (input.icon) {
+      result.icon = input.icon
+    }
+    if (input.color) {
+      result.color = input.color
+    }
+    if (input.deleteInfo) {
+      result.deleteInfo = input.deleteInfo
+    }
+    return result
+  }
+
+  static fromName(name: string, oid: string): Group {
+    return new Group({ name, oid })
+  }
+
+  constructor(state?: Partial<GroupSchema>) {
+    const init = Group.createSchema(state)
+    this.key = init.key
+    this.name = init.name
+    this.description = init.description
+    this.owner = init.owner
+    this.icon = init.icon
+    this.color = init.color
+    this.oid = init.oid
+    this.users = init.users
+    this.createdAt = init.createdAt
+    this.updatedAt = init.updatedAt
+    this.deleteInfo = init.deleteInfo
+  }
+
+  toJSON(): GroupSchema {
+    const result: GroupSchema = {
+      kind: this.kind,
+      key: GroupKind,
+      name: this.name,
+      oid: this.oid,
+      owner: this.owner,
+      users: [...this.users],
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt,
+    }
+    if (this.description) {
+      result.description = this.description
+    }
+    if (this.icon) {
+      result.icon = this.icon
+    }
+    if (this.color) {
+      result.color = this.color
+    }
+    if (this.deleteInfo) {
+      result.deleteInfo = { ...this.deleteInfo }
+    }
+    return result
+  }
 }

package/src/sdk/GroupsSdk.ts

@@ -0,0 +1,150 @@
+import { ContextListOptions, ContextListResult } from '../browser.js'
+import { Exception } from '../exceptions/exception.js'
+import type { GroupSchema } from '../models/store/Group.js'
+import { RouteBuilder } from './RouteBuilder.js'
+import {
+  E_INVALID_JSON,
+  E_RESPONSE_NO_VALUE,
+  E_RESPONSE_STATUS,
+  E_RESPONSE_UNKNOWN,
+  SdkBase,
+  type SdkOptions,
+} from './SdkBase.js'
+
+export class GroupsSdk extends SdkBase {
+  /**
+   * Creates a new group in the specified organization.
+   * @param oid The organization ID where the group will be created.
+   * @param info The information about the group to create. See the `GroupSchema` interface for required fields.
+   * @param request Optional SDK options, including authentication token.
+   * @returns A promise that resolves to the created group.
+   */
+  async create(oid: string, info: Partial<GroupSchema>, request: SdkOptions = {}): Promise<GroupSchema> {
+    const { token } = request
+    const url = this.sdk.getUrl(RouteBuilder.groups(oid))
+    const body = JSON.stringify(info)
+    const result = await this.sdk.http.post(url.toString(), {
+      token,
+      body,
+      headers: {
+        'content-type': 'application/json',
+      },
+    })
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to create a group. '
+    if (result.status !== 201) {
+      this.logInvalidResponse(result)
+      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
+    }
+
+    if (!result.body) {
+      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
+    }
+    let data: GroupSchema
+    try {
+      data = JSON.parse(result.body)
+    } catch {
+      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
+    }
+    if (!data.key) {
+      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
+    }
+    return data
+  }
+
+  /**
+   * Lists user groups in the specified organization.
+   * If you want to list specific user groups, you can use the `uid` option to filter by user ID.
+   * @param oid The organization ID to list groups from.
+   * @param options Optional parameters for filtering, sorting, and pagination.
+   * @param request Optional SDK options, including authentication token.
+   * @returns A promise that resolves to a list of groups in the organization.
+   */
+  async list(
+    oid: string,
+    options: ContextListOptions = {},
+    request: SdkOptions = {}
+  ): Promise<ContextListResult<GroupSchema>> {
+    const { token } = request
+    const url = this.sdk.getUrl(RouteBuilder.groups(oid))
+    this.sdk.appendListOptions(url, options)
+    const result = await this.sdk.http.get(url.toString(), { token })
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to create a group. '
+    if (result.status !== 200) {
+      this.logInvalidResponse(result)
+      throw this.createApiError(E_PREFIX + E_RESPONSE_STATUS + result.status, result.body)
+    }
+    if (!result.body) {
+      throw new Exception(E_PREFIX + E_RESPONSE_NO_VALUE, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
+    }
+    let data: ContextListResult<GroupSchema>
+    try {
+      data = JSON.parse(result.body)
+    } catch {
+      throw new Exception(E_PREFIX + E_INVALID_JSON, { code: 'E_INVALID_JSON', status: result.status })
+    }
+    return data
+  }
+
+  /**
+   * Updates an existing group in the specified organization.
+   * Note that this method support PUT requests only. Some fields are ignored by the API and are set automatically.
+   * @param oid The organization ID where the group exists.
+   * @param updated The updated information for the group. Must include the `key` of the group to update.
+   * @param request Optional SDK options, including authentication token.
+   * @returns A promise that resolves to the updated group.
+   */
+  async update(oid: string, updated: GroupSchema, request: SdkOptions = {}): Promise<GroupSchema> {
+    const { token } = request
+    const url = this.sdk.getUrl(RouteBuilder.group(oid, updated.key))
+    const body = JSON.stringify(updated)
+    const result = await this.sdk.http.put(url.toString(), {
+      token,
+      body,
+      headers: {
+        'content-type': 'application/json',
+      },
+    })
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to update a group. '
+    if (result.status !== 200) {
+      this.logInvalidResponse(result)
+      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
+    }
+
+    if (!result.body) {
+      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
+    }
+    let data: GroupSchema
+    try {
+      data = JSON.parse(result.body)
+    } catch {
+      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
+    }
+    if (!data.key) {
+      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
+    }
+    return data
+  }
+
+  /**
+   * Deletes a group in the specified organization.
+   * The groups support soft deletion, meaning that the group is not immediately removed from the database.
+   * @param oid The organization ID where the group exists.
+   * @param gid The group ID to delete.
+   * @param request Optional SDK options, including authentication token.
+   * @returns A promise that resolves when the group is deleted.
+   */
+  async delete(oid: string, gid: string, request: SdkOptions = {}): Promise<void> {
+    const { token } = request
+    const url = this.sdk.getUrl(RouteBuilder.group(oid, gid))
+    const result = await this.sdk.http.delete(url.toString(), { token })
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to delete a group. '
+    if (result.status !== 204) {
+      this.logInvalidResponse(result)
+      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
+    }
+  }
+}

package/src/sdk/RouteBuilder.ts

@@ -287,4 +287,12 @@ export class RouteBuilder {
   static dataCatalogVersionUnpublish(entryId: string, version: string): string {
     return `${RouteBuilder.dataCatalogVersion(entryId, version)}/unpublish`
   }
+
+  static groups(oid: string): string {
+    return `/v1/orgs/${oid}/groups`
+  }
+
+  static group(oid: string, gid: string): string {
+    return `/v1/orgs/${oid}/groups/${gid}`
+  }
 }

package/src/sdk/Sdk.ts

@@ -11,6 +11,7 @@ import { TrashSdk } from './TrashSdk.js'
 import { ProjectExecutionSdk } from './ProjectExecutionsSdk.js'
 import { OrganizationsSdk } from './OrganizationsSdk.js'
 import { DataCatalogSdk } from './DataCatalogSdk.js'
+import { GroupsSdk } from './GroupsSdk.js'
 
 const baseUriSymbol = Symbol('baseUri')
 
@@ -70,6 +71,8 @@ export abstract class Sdk {
   organizations = new OrganizationsSdk(this)
 
   dataCatalog = new DataCatalogSdk(this)
+
+  groups = new GroupsSdk(this)
   /**
    * When set it limits log output to minimum.
    */
@@ -162,6 +165,9 @@ export abstract class Sdk {
     if (options.oid) {
       searchParams.set('oid', String(options.oid))
     }
+    if (options.uid) {
+      searchParams.set('uid', String(options.uid))
+    }
     if (options.filter) {
       const bytes = new TextEncoder().encode(JSON.stringify(options.filter))
       // To be used when Uint8Array.prototype.toBase64() is available.

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

@@ -0,0 +1,291 @@
+import { test } from '@japa/runner'
+import {
+  ApiModel,
+  ApiModelKind,
+  DataDomain,
+  type RolesBasedAccessControl,
+  type ApiModelSchema,
+  type ExposedEntity,
+} from '../../../src/index.js'
+
+test.group('ApiModel.createSchema()', () => {
+  test('creates a schema with default values', ({ assert }) => {
+    const schema = ApiModel.createSchema()
+    assert.equal(schema.kind, ApiModelKind)
+    assert.typeOf(schema.key, 'string')
+    assert.isNotEmpty(schema.key)
+    assert.deepInclude(schema.info, { name: 'Unnamed API' })
+    assert.deepEqual(schema.exposes, [])
+    assert.isUndefined(schema.userKey)
+    assert.isUndefined(schema.domain)
+    assert.isUndefined(schema.authentication)
+    assert.isUndefined(schema.authorization)
+    assert.isUndefined(schema.session)
+    assert.isUndefined(schema.accessRule)
+    assert.isUndefined(schema.rateLimiting)
+  })
+
+  test('creates a schema with provided values', ({ assert }) => {
+    const input: Partial<ApiModelSchema> = {
+      key: 'test-api',
+      info: { name: 'Test API', description: 'A test API' },
+      exposes: [{ key: 'entity1', actions: [] }],
+      userKey: 'user-entity',
+      domain: { 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: [] },
+    }
+    const schema = ApiModel.createSchema(input)
+
+    assert.equal(schema.kind, ApiModelKind)
+    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.domain, { 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: [] })
+  })
+
+  test('creates a schema with partial info', ({ assert }) => {
+    const schema = ApiModel.createSchema({ info: { name: 'Partial API' } })
+    assert.deepInclude(schema.info, { name: 'Partial API' })
+  })
+
+  test('creates a schema with empty info', ({ assert }) => {
+    const schema = ApiModel.createSchema({ info: {} })
+    assert.deepInclude(schema.info, { name: 'Unnamed API' })
+  })
+})
+
+test.group('ApiModel.constructor()', () => {
+  test('creates an instance with default values', ({ assert }) => {
+    const model = new ApiModel()
+    assert.equal(model.kind, ApiModelKind)
+    assert.typeOf(model.key, 'string')
+    assert.isNotEmpty(model.key)
+    assert.equal(model.info.name, 'Unnamed API')
+    assert.deepEqual(model.exposes, [])
+    assert.isUndefined(model.userKey)
+    assert.isUndefined(model.domain)
+    assert.isUndefined(model.authentication)
+    assert.isUndefined(model.authorization)
+    assert.isUndefined(model.session)
+    assert.isUndefined(model.accessRule)
+    assert.isUndefined(model.rateLimiting)
+    assert.isUndefined(model.dataDomain)
+  })
+
+  test('creates an instance with provided schema values', ({ assert }) => {
+    const schema: ApiModelSchema = {
+      kind: ApiModelKind,
+      key: 'test-api',
+      info: { name: 'Test API', description: 'A test API' },
+      exposes: [{ key: 'entity1', actions: [] }],
+      userKey: 'user-entity',
+      domain: { 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: [] },
+    }
+    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.domain, { 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.isUndefined(model.dataDomain)
+  })
+
+  test('creates an instance with a DataDomain', ({ assert }) => {
+    const domainSchema = DataDomain.createSchema({ key: 'my-domain' })
+    const model = new ApiModel({}, domainSchema)
+    assert.isDefined(model.dataDomain)
+    assert.instanceOf(model.dataDomain, DataDomain)
+    assert.equal(model.dataDomain!.key, 'my-domain')
+  })
+
+  test('notifies change when info is modified', async ({ assert }) => {
+    const model = new ApiModel()
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.info.name = 'New Name'
+    await Promise.resolve() // Allow microtask to run
+    assert.isTrue(notified)
+  })
+})
+
+test.group('ApiModel.toJSON()', () => {
+  test('serializes default values', ({ assert }) => {
+    const model = new ApiModel()
+    const json = model.toJSON()
+
+    assert.equal(json.kind, ApiModelKind)
+    assert.equal(json.key, model.key)
+    assert.deepInclude(json.info, { name: 'Unnamed API' })
+    assert.deepEqual(json.exposes, [])
+    assert.isUndefined(json.userKey)
+    assert.isUndefined(json.domain)
+    assert.isUndefined(json.authentication)
+    assert.isUndefined(json.authorization)
+    assert.isUndefined(json.session)
+    assert.isUndefined(json.accessRule)
+    assert.isUndefined(json.rateLimiting)
+  })
+
+  test('serializes all provided values', ({ assert }) => {
+    const schema: ApiModelSchema = {
+      kind: ApiModelKind,
+      key: 'test-api',
+      info: { name: 'Test API', description: 'A test API' },
+      exposes: [{ key: 'entity1', actions: [] }],
+      userKey: 'user-entity',
+      domain: { 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: [] },
+    }
+    const model = new ApiModel(schema)
+    const json = model.toJSON()
+
+    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.domain, { 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: [] })
+  })
+})
+
+test.group('ApiModel.exposeEntity()', () => {
+  test('exposes a new entity', ({ assert }) => {
+    const model = new ApiModel()
+    const entityKey = 'new-entity'
+    const exposedEntity = model.exposeEntity(entityKey)
+
+    assert.isDefined(exposedEntity)
+    assert.equal(exposedEntity.key, entityKey)
+    assert.deepEqual(exposedEntity.actions, [])
+    assert.includeDeepMembers(model.exposes, [exposedEntity])
+  })
+
+  test('returns an existing entity if already exposed', ({ assert }) => {
+    const model = new ApiModel()
+    const entityKey = 'existing-entity'
+    const initialExposedEntity = model.exposeEntity(entityKey)
+    const retrievedExposedEntity = model.exposeEntity(entityKey)
+
+    assert.strictEqual(retrievedExposedEntity, initialExposedEntity)
+    assert.lengthOf(model.exposes, 1)
+  })
+
+  test('notifies change when a new entity is exposed', async ({ assert }) => {
+    const model = new ApiModel()
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.exposeEntity('notify-entity')
+    await Promise.resolve() // Allow microtask to run
+    assert.isTrue(notified)
+  })
+
+  test('does not notify change if entity already exposed', async ({ assert }) => {
+    const model = new ApiModel()
+    model.exposeEntity('no-notify-entity') // First exposure
+    await Promise.resolve() // Allow microtask to run
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.exposeEntity('no-notify-entity') // Second exposure
+    await Promise.resolve() // Allow microtask to run
+    assert.isFalse(notified)
+  })
+})
+
+test.group('ApiModel.removeEntity()', () => {
+  test('removes an existing entity', ({ assert }) => {
+    const model = new ApiModel()
+    const entityKey = 'entity-to-remove'
+    model.exposeEntity(entityKey)
+    assert.lengthOf(model.exposes, 1)
+
+    model.removeEntity(entityKey)
+    assert.lengthOf(model.exposes, 0)
+  })
+
+  test('does nothing if entity does not exist', ({ assert }) => {
+    const model = new ApiModel()
+    model.exposeEntity('existing-entity')
+    const initialExposes = [...model.exposes]
+
+    model.removeEntity('non-existing-entity')
+    assert.deepEqual(model.exposes, initialExposes)
+  })
+
+  test('notifies change when an entity is removed', async ({ assert }) => {
+    const model = new ApiModel()
+    const entityKey = 'notify-remove-entity'
+    model.exposeEntity(entityKey)
+
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.removeEntity(entityKey)
+    await Promise.resolve() // Allow microtask to run
+    assert.isTrue(notified)
+  })
+
+  test('does not notify change if entity to remove does not exist', async ({ assert }) => {
+    const model = new ApiModel()
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.removeEntity('no-notify-remove-entity')
+    await Promise.resolve() // Allow microtask to run
+    assert.isFalse(notified)
+  })
+})
+
+test.group('ApiModel.getExposedEntity()', () => {
+  test('returns an existing exposed entity', ({ assert }) => {
+    const model = new ApiModel()
+    const entityKey = 'get-entity'
+    const exposed: ExposedEntity = { key: entityKey, actions: [] }
+    model.exposes.push(exposed)
+
+    const retrievedEntity = model.getExposedEntity(entityKey)
+    assert.deepEqual(retrievedEntity, exposed)
+  })
+
+  test('returns undefined if entity is not exposed', ({ assert }) => {
+    const model = new ApiModel()
+    const retrievedEntity = model.getExposedEntity('non-exposed-entity')
+    assert.isUndefined(retrievedEntity)
+  })
+})