A TypeScript client library for interacting with the Huly Platform API.

In order to be able to install required packages, you will need to obtain GitHub access token. You can create a token by following the instructions here.

npm install @hcengineering/api-client

There are two ways to connect to the platform, using email and password, or using token.

Parameters:

• url: URL of the Huly instance
• options: Connection options
  • workspace: Name of the workspace to connect to
  • token: Optional authentication token
  • email: Optional user email
  • password: Optional user password
  • connectionTimeout: Optional connection timeout
  • socketFactory: Optional socket factory

const client = await connect('http://localhost:8087', {
  email: 'user1',
  password: '1234',
  workspace: 'ws1'
})

...

await client.close()

const client = await connect('http://localhost:8087', {
  token: '...',
  workspace: 'ws1'
})

...

await client.close()

The client provides two main methods for retrieving documents: findOne and findAll.

Retrieves a single document matching the query criteria.

Parameters:

• _class: Class of the object to find, results will include all subclasses of the targe class
• query: Query criteria
• options: Find options
  • limit: Limit the number of results returned
  • sort: Sorting criteria
  • lookup: Lookup criteria
  • projection: Projection criteria
  • total: If specified total will be returned

Example:

import contact from '@hcengineering/contact'

...

const person = await client.findOne(
  contact.class.Person,
  {
    _id: 'person-id'
  }
)

Retrieves multiple document matching the query criteria.

Parameters:

• _class: Class of the object to find, results will include all subclasses of the targe class
• query: Query criteria
• options: Find options
  • limit: Limit the number of results returned
  • sort: Sorting criteria
  • lookup: Lookup criteria
  • projection: Projection criteria
  • total: If specified total will be returned

Example:

import { SortingOrder } from '@hcengineering/core'
import contact from '@hcengineering/contact'

..

const persons = await client.findAll(
  contact.class.Person,
  {
    city: 'New York'
  },
  {
    limit: 10,
    sort: {
      name: SortingOrder.Ascending
    }
  }
)

The client provides three main methods for managing documents: createDoc, updateDoc, and removeDoc. These methods allow you to perform CRUD operations on documents.

Creates a new document in the specified space.

Parameters:

• _class: Class of the object
• space: Space of the object
• attributes: Attributes of the object
• id: Optional id of the object, if not provided, a new id will be generated

Example:

import contact, { AvatarType } from '@hcengineering/contact'

..

const personId = await client.createDoc(
  contact.class.Person,
  contact.space.Contacts,
  {
    name: 'Doe,John',
    city: 'New York',
    avatarType: AvatarType.COLOR
  }
)

Updates exising document.

Parameters:

• _class: Class of the object
• space: Space of the object
• objectId: Id of the object
• operations: Attributes of the object to update

Example:

import contact from '@hcengineering/contact'

..

await client.updateDoc(
  contact.class.Person,
  contact.space.Contacts,
  personId,
  {
    city: 'New York',
  }
)

Removes exising document.

Parameters:

• _class: Class of the object
• space: Space of the object
• objectId: Id of the object

Example:

import contact from '@hcengineering/contact'

..

await client.removeDoc(
  contact.class.Person,
  contact.space.Contacts,
  personId
)

Creates a new attached document in the specified collection.

Parameters:

• _class: Class of the object to create
• space: Space of the object to create
• attachedTo: Id of the object to attach to
• attachedToClass: Class of the object to attach to
• collection: Name of the collection containing attached documents
• attributes: Attributes of the object
• id: Optional id of the object, if not provided, a new id will be generated

Example:

import contact, { AvatarType } from '@hcengineering/contact'

..

const personId = await client.createDoc(
  contact.class.Person,
  contact.space.Contacts,
  {
    name: 'Doe,John',
    city: 'New York',
    avatarType: AvatarType.COLOR
  }
)

await client.addCollection(
  contact.class.Channel,
  contact.space.Contacts,
  personId,
  contact.class.Person,
  'channels',
  {
    provider: contact.channelProvider.Email,
    value: 'john.doe@example.com'
  }
)

Updates exising attached document in collection.

Parameters:

• _class: Class of the object to update
• space: Space of the object to update
• objectId: Space of the object to update
• attachedTo: Id of the parent object
• attachedToClass: Class of the parent object
• collection: Name of the collection containing attached documents
• attributes: Attributes of the object to update

Example:

import contact from '@hcengineering/contact'

..

await client.updateCollection(
  contact.class.Channel,
  contact.space.Contacts,
  channelId,
  personId,
  contact.class.Person,
  'channels',
  {
    city: 'New York',
  }
)

Removes exising attached document from collection.

Parameters:

• _class: Class of the object to remove
• space: Space of the object to remove
• objectId: Space of the object to remove
• attachedTo: Id of the parent object
• attachedToClass: Class of the parent object
• collection: Name of the collection containing attached documents

Example:

import contact from '@hcengineering/contact'

..

await client.removeCollection(
  contact.class.Channel,
  contact.space.Contacts,
  channelId,
  personId,
  contact.class.Person,
  'channels'
)

The client provides two methods for managing mixins: createMixin and updateMixin.

Creates a new mixin for a specified document.

Parameters:

• objectId: Id of the object the mixin is attached to
• objectClass: Class of the object the mixin is attached to
• objectSpace: Space of the object the mixin is attached to
• mixin: Id of the mixin type to update
• attributes: Attributes of the mixin

import contact, { AvatarType } from '@hcengineering/contact'

..

const personId = await client.createDoc(
  contact.class.Person,
  contact.space.Contacts,
  {
    name: 'Doe,John',
    city: 'New York',
    avatarType: AvatarType.COLOR
  }
)

await client.createMixin(
  personId,
  contact.class.Person,
  contact.space.Contacts,
  contact.mixin.Employee,
  {
    active: true,
    position: 'CEO'
  }
)

Updates an existing mixin.

Parameters:

• objectId: Id of the object the mixin is attached to
• objectClass: Class of the object the mixin is attached to
• objectSpace: Space of the object the mixin is attached to
• mixin: Id of the mixin type to update
• attributes: Attributes of the mixin to update

import contact, { AvatarType } from '@hcengineering/contact'

..

const person = await client.findOne(
  contact.class.Person,
  {
    _id: 'person-id'
  }
)

await client.updateMixin(
  personId,
  contact.class.Person,
  contact.space.Contacts,
  contact.mixin.Employee,
  {
    active: false
  }
)