@api-client/core 0.14.3 → 0.14.5

package/data/models/example-generator-api.json

@@ -42071,15 +42071,15 @@
 "@id": "#197"
 },
 {
-"@id": "#206"
-},
-{
 "@id": "#200"
 },
 {
 "@id": "#203"
 },
 {
+"@id": "#206"
+},
+{
 "@id": "#209"
 }
 ],
@@ -42810,9 +42810,6 @@
 "@id": "#219"
 },
 {
-"@id": "#219"
-},
-{
 "@id": "#210"
 },
 {
@@ -42820,6 +42817,9 @@
 },
 {
 "@id": "#216"
+},
+{
+"@id": "#219"
 }
 ],
 "doc:root": false,
@@ -43499,7 +43499,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43520,7 +43520,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
+"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43541,7 +43541,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44232,7 +44232,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44253,7 +44253,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44274,7 +44274,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
+"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44295,7 +44295,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
+"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44771,17 +44771,17 @@
 {
 "@id": "#202/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#202",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#205/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#205",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#208/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#208",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#223/source-map/lexical/element_0",
@@ -45121,17 +45121,17 @@
 {
 "@id": "#215/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#215",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#218/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#218",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#221/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#221",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#338/source-map/synthesized-field/element_1",

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.14.3",
+  "version": "0.14.5",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/events/BaseEvents.ts

@@ -439,6 +439,10 @@ export interface ContextListOptions {
    * Some specific list operations might use this directly if not part of the main path.
    */
   oid?: string
+  /**
+   * Optional user id to filter results by the user
+   */
+  uid?: string
   /**
    * A structured filter object for advanced querying.
    */

package/src/models/kinds.ts

@@ -22,3 +22,4 @@ export const OrganizationKind = 'Core#Organization'
 export const InvitationKind = 'Core#Invitation'
 export const ApiModelKind = 'Core#ApiModel'
 export const ApiFileKind = 'Core#ApiFile'
+export const GroupKind = 'Core#Group'

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,214 @@
+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)
+    }
+  }
+
+  async addUsers(oid: string, gid: string, uids: string[], request: SdkOptions = {}): Promise<GroupSchema> {
+    const { token } = request
+    const url = this.sdk.getUrl(RouteBuilder.groupUsers(oid, gid))
+    const body = JSON.stringify({ ids: uids })
+    const result = await this.sdk.http.post(url.toString(), {
+      token,
+      body,
+      headers: {
+        'content-type': 'application/json',
+      },
+    })
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to add users to 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
+  }
+
+  async removeUsers(oid: string, gid: string, uids: string[], request: SdkOptions = {}): Promise<GroupSchema> {
+    const { token } = request
+    const url = this.sdk.getUrl(RouteBuilder.groupUsers(oid, gid))
+    const body = JSON.stringify({ ids: uids })
+    const result = await this.sdk.http.delete(url.toString(), {
+      token,
+      body,
+      headers: {
+        'content-type': 'application/json',
+      },
+    })
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to remove users from 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
+  }
+}

package/src/sdk/RouteBuilder.ts

@@ -287,4 +287,16 @@ 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}`
+  }
+
+  static groupUsers(oid: string, gid: string): string | undefined {
+    return `/v1/orgs/${oid}/groups/${gid}/users`
+  }
 }

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.