@hcengineering/api-client

中文文档
0.7.423发布于 2026/05/10EPL-2.0TypeScriptESM + CJS近 30 天下载 1.4万

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

原始使用文档
文档目录12 节
  1. Installation
  2. WebSocket Client vs REST Client
  3. WebSocket Client
  4. REST Client
  5. Authentication
  6. Using Email and Password
  7. Using Token
  8. Client API
  9. Fetch API
  10. Documents API
  11. Collections API
  12. Mixins API

Huly Platform API Client

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

Installation

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

WebSocket Client vs REST 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.

WebSocket Client

import { connect } from '@hcengineering/api-client'

// Connect to Huly
const client = await connect('https://huly.app', {
  email: '[email protected]',
  password: 'password',
  workspace: 'my-workspace',
})

// Use the client to perform operations
...

// Close the client when done
await client.close()

REST Client

import { connectRest } from '@hcengineering/api-client'

// Connect to Huly
const client = await connectRest('https://huly.app', {
  email: '[email protected]',
  password: 'password',
  workspace: 'my-workspace'
})

// Use the client to perform operations
...

Authentication

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 call connectRest with the same options.

Parameters:

  • url: URL of the Huly instance, for Huly Cloud use https://huly.app
  • options: Connection options
    • workspace: 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 token
    • email: Optional user email
    • password: Optional user password

Using Email and Password

import { connect } from '@hcengineering/api-client'

const client = await connect('https://huly.app', {
  email: '[email protected]',
  password: 'password',
  workspace: 'my-workspace'
})

...

await client.close()

Using Token

import { connect } from '@hcengineering/api-client'

const client = await connect('https://huly.app', {
  token: '...',
  workspace: 'my-workspace'
})

...

await client.close()

Client API

The client provides a set of methods for interacting with the Huly Platform API. This section describes the main methods available in the client.

Fetch API

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

findOne

Retrieves a single document matching the query criteria.

Parameters:

  • _class: Class of the object to find, results will include all subclasses of the target 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'
  }
)

findAll

Retrieves multiple document matching the query criteria.

Parameters:

  • _class: Class of the object to find, results will include all subclasses of the target 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
    }
  }
)

Documents API

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

createDoc

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
  }
)

updateDoc

Updates existing 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',
  }
)

removeDoc

Removes existing 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
)

Collections API

addCollection

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: '[email protected]'
  }
)

updateCollection

Updates existing 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',
  }
)

removeCollection

Removes existing 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'
)

Mixins API

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

createMixin

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'
  }
)

updateMixin

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
  }
)

版本与发布记录

@hcengineering/api-client 共发布 13 个版本,首次发布于 2025/10/07;过去 12 个月发布了 5 个版本。

版本发布日期距今
0.7.423latest2026/05/106 个月前
0.7.4132026/04/147 个月前
0.7.4112026/04/127 个月前
0.7.3822026/03/168 个月前
0.7.192026/02/228 个月前
0.7.182025/10/281.1 年前

关于 @hcengineering/api-client 的常见问题

@hcengineering/api-client 是什么?

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

如何安装 @hcengineering/api-client?

在项目目录运行 npm install @hcengineering/api-client,或使用 pnpm add / yarn add / bun add。

@hcengineering/api-client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hcengineering/api-client 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@hcengineering/api-client 可以商用吗?

@hcengineering/api-client 使用 EPL-2.0 许可。声明的许可为 EPL-2.0,请阅读许可原文确认使用条件。以上为概括,不构成法律意见,请以许可原文为准。

@hcengineering/api-client 的下载量有多少?

根据 npm 官方下载统计,@hcengineering/api-client 在 2026/10/18 – 2026/11/16 这 30 天内被下载 13,950 次,日均约 465 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hcengineering/api-client 还在维护吗?

最新版本 0.7.423 发布于 2026/05/10(6 个月前);至今共发布 13 个版本,其中过去 12 个月发布了 5 个;首次发布于 2025/10/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。