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
The api client package provides two main client variants: a WebSocket client and a REST client. The WebSocket client holds persistent connection to the Huly Platform API. The REST client uses standard HTTP requests to perform operations.
import { connect } from '@hcengineering/api-client'
// Connect to Huly
const client = await connect('https://huly.app', {
email: 'johndoe@example.com',
password: 'password',
workspace: 'my-workspace',
})
// Use the client to perform operations
...
// Close the client when done
await client.close()
import { connectRest } from '@hcengineering/api-client'
// Connect to Huly
const client = await connectRest('https://huly.app', {
email: 'johndoe@example.com',
password: 'password',
workspace: 'my-workspace'
})
// Use the client to perform operations
...
The client supports two authentication methods: using email and password, or using a token. When authenticated, the client will have access to the same resources as the user.
Note: The examples below use the WebSocket client (
connect
). To use the REST client instead, import and callconnectRest
with the same options.
Parameters:
url
: URL of the Huly instance, for Huly Cloud usehttps://huly.app
options
: Connection optionsworkspace
: Name of the workspace to connect to, the workspace name can be found in the URL of the workspace:https://huly.app/workbench/<workspace-name>
token
: Optional authentication tokenemail
: Optional user emailpassword
: Optional user password
import { connect } from '@hcengineering/api-client'
const client = await connect('https://huly.app', {
email: 'johndoe@example.com',
password: 'password',
workspace: 'my-workspace'
})
...
await client.close()
import { connect } from '@hcengineering/api-client'
const client = await connect('https://huly.app', {
token: '...',
workspace: 'my-workspace'
})
...
await client.close()
The client provides a set of methods for interacting with the Huly Platform API. This section describes the main methods available in the client.
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 target classquery
: Query criteriaoptions
: Find optionslimit
: Limit the number of results returnedsort
: Sorting criterialookup
: Lookup criteriaprojection
: Projection criteriatotal
: 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 target classquery
: Query criteriaoptions
: Find optionslimit
: Limit the number of results returnedsort
: Sorting criterialookup
: Lookup criteriaprojection
: Projection criteriatotal
: 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 objectspace
: Space of the objectattributes
: Attributes of the objectid
: 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 existing document.
Parameters:
_class
: Class of the objectspace
: Space of the objectobjectId
: Id of the objectoperations
: 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 existing document.
Parameters:
_class
: Class of the objectspace
: Space of the objectobjectId
: 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 createspace
: Space of the object to createattachedTo
: Id of the object to attach toattachedToClass
: Class of the object to attach tocollection
: Name of the collection containing attached documentsattributes
: Attributes of the objectid
: 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 existing attached document in collection.
Parameters:
_class
: Class of the object to updatespace
: Space of the object to updateobjectId
: Space of the object to updateattachedTo
: Id of the parent objectattachedToClass
: Class of the parent objectcollection
: Name of the collection containing attached documentsattributes
: 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 existing attached document from collection.
Parameters:
_class
: Class of the object to removespace
: Space of the object to removeobjectId
: Space of the object to removeattachedTo
: Id of the parent objectattachedToClass
: Class of the parent objectcollection
: 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 toobjectClass
: Class of the object the mixin is attached toobjectSpace
: Space of the object the mixin is attached tomixin
: Id of the mixin type to updateattributes
: 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 toobjectClass
: Class of the object the mixin is attached toobjectSpace
: Space of the object the mixin is attached tomixin
: Id of the mixin type to updateattributes
: 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
}
)