@mingdaocom/hap-sdk

通过应用网关访问 HAP v3 的 JavaScript SDK，适用于 React、Vue 等前端项目，提供 ESM 入口和 TypeScript 类型声明。

方法目录 · Apifox API 文档

安装

npm install @mingdaocom/hap-sdk

快速开始

import { createHapClient } from '@mingdaocom/hap-sdk';

const hap = createHapClient({ token: 'your-gateway-token' });

const result = await hap.worksheets.getWorksheetStructure({
  path: { worksheet_id: 'your-worksheet-id' },
  query: { responseFormat: 'json' },
});

console.log(result.data);

默认请求地址为 /hap/v3/...，无需传入 baseURL。项目需将 /hap 转发到 HAP 网关：开发环境使用开发服务器代理，生产环境由部署网关转发。HAP 应用凭证由网关注入，不放入前端。

中转服务认证

token 用于认证中转服务，以 Authorization 请求头原样发送，不自动添加前缀。若中转协议要求 Bearer，传入完整的 Bearer <token>。它与 HAP 应用的 Appkey/Sign 不同，后者仍由网关管理。

可在初始化时设置默认 token，也可在单次调用时传入当前 token：

const hap = createHapClient();
const result = await hap.app.getApp({}, { token: 'your-current-gateway-token' });

单次 token 覆盖该请求的 Authorization，不修改客户端默认值。同一配置同时提供 token 和 headers.Authorization 时，token 优先。凭证刷新后由应用传入新值；SDK 不负责登录、获取或存储 token，也不会自动重试认证失败。需要其他认证头时使用 headers 或请求拦截器。

调用约定

await hap.<模块>.<方法>({ path, query, body }, config);

| 参数 | 对应 Apifox 内容 | | -------- | ---------------------------------------------------------- | | path | Path 参数，例如 worksheet_id | | query | Query 参数 | | body | JSON 请求体 | | config | SDK 请求配置，例如 token、signal、timeout、headers |

没有参数的方法可直接调用，例如 hap.app.getApp()。方法返回完整响应载荷，不自动提取其中的 data，也不自动分页或重试。各接口的字段、必填规则、返回结构和业务错误码见下方 Apifox 链接。

客户端配置

const hap = createHapClient({ token: 'your-gateway-token', timeout: 15000 });

| 配置 | 默认值 | 说明 | | ----------------- | -------------------------- | ----------------------------------------- | | token | 无 | 中转服务 Authorization 完整值 | | baseURL | /hap | 网关基础地址，支持同源路径或 HTTP(S) 地址 | | timeout | 30000 | 超时毫秒数，0 表示关闭超时 | | headers | Accept: application/json | 默认请求头 | | withCredentials | false | 是否携带跨域凭证 |

每次创建的客户端配置和拦截器独立。SDK 不读取环境变量或浏览器存储。Node.js 环境要求 Node.js 22 及以上，并需要显式传入绝对 baseURL。

单次调用可传入常规 Axios 配置；url、method、baseURL、params、data、adapter、transformRequest、transformResponse、validateStatus 由 SDK 管理，不可覆盖。

const controller = new AbortController();
const request = hap.app.getApp({}, { signal: controller.signal });
// 需要取消时调用 controller.abort()；在调用方处理取消错误。
const result = await request;

错误处理

import { createHapClient, HapBusinessError } from '@mingdaocom/hap-sdk';

const hap = createHapClient({ token: 'your-gateway-token' });

try {
  const result = await hap.app.getApp();
  console.log(result.data);
} catch (error) {
  if (error instanceof HapBusinessError) {
    console.error(error.code, error.message, error.payload);
  } else {
    // HTTP、网络、超时与取消错误保持 Axios 行为。
    throw error;
  }
}

success === false 会抛出 HapBusinessError。知识库列表接口还会在缺少 success 且 error_code 为非零整数时抛出该错误。responseType: 'text' 和二进制响应保持原样，不解析为业务错误。

拦截器

可通过 hap.interceptors.request 和 hap.interceptors.response 注册 Axios 拦截器，支持 use、eject、clear。请求拦截器返回 config，响应拦截器返回完整 response；SDK 随后读取 response.data 并判断业务错误。

类型提示与版本

包内自带类型声明，JavaScript / TypeScript 编辑器均可提供方法补全和参数提示，无需安装额外的 @types 包。类型声明对应当前 SDK 版本；Apifox 可能更新得更快，新增接口或参数需要升级 SDK。上游定义缺失或冲突的结构使用 unknown，使用前需检查实际响应。

可通过 import { sdkInfo } from '@mingdaocom/hap-sdk' 查看 SDK 版本及接口定义版本信息。

方法目录

以下方法均通过 hap.<模块>.<方法>() 调用。点击 Apifox 查看具体入参、出参及示例。

hap.app

| 方法 | 用途 | 参数与返回值 | | ---------------------- | ------------------ | ------------------------------------------------- | | getApp | 获取应用信息 | Apifox | | postAppItemsBatch | 批量创建应用项 | Apifox | | postAppSectionsBatch | 批量创建应用项分组 | Apifox |

hap.charts

| 方法 | 用途 | 参数与返回值 | | ------------- | ---------- | ------------------------------------------------ | | createChart | 新建统计图 | Apifox |

hap.chatbots

| 方法 | 用途 | 参数与返回值 | | ----------------- | -------------- | ------------------------------------------------ | | createWorksheet | 新建对话机器人 | Apifox |

hap.customPages

| 方法 | 用途 | 参数与返回值 | | ---------------- | -------------- | ------------------------------------------------ | | saveCustomPage | 更新自定义页面 | Apifox |

hap.knowledge

| 方法 | 用途 | 参数与返回值 | | ------------------------ | -------------------- | ----------------------------------------------------------- | | postAppKnowledgeList | 获取应用下知识库列表 | Apifox | | postAppKnowledgeSearch | 知识库检索 | Apifox |

hap.optionsets

| 方法 | 用途 | 参数与返回值 | | ---------------------------------- | -------------- | ------------------------------------------------------- | | deleteAppOptionsetsByOptionsetId | 停用选项集 | Apifox | | getAppOptionsets | 获取选项集列表 | Apifox | | postAppOptionsets | 创建选项集 | Apifox | | putAppOptionsetsByOptionsetId | 编辑选项集 | Apifox |

hap.queries

| 方法 | 用途 | 参数与返回值 | | ---------------------- | ------------ | ---------------------------------------------------- | | getDepartmentsLookup | 查找部门 | Apifox | | getRegions | 获取地区信息 | Apifox | | getUsersLookup | 查找成员 | Apifox |

hap.records

| 方法 | 用途 | 参数与返回值 | | ------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------- | | createRecord | 新建行记录 | Apifox | | deleteAppWorksheetsByWorksheetIdRowsBatch | 批量删除行记录 | Apifox | | deleteAppWorksheetsByWorksheetIdRowsByRowId | 删除行记录 | Apifox | | getAppWorkflowByWorksheetIdRowsByRowIdApprovalByApprovalId | 获取审批流程执行详情 | Apifox | | getAppWorksheetsByWorksheetIdRowsByRowId | 获取行记录详情 | Apifox | | getAppWorksheetsByWorksheetIdRowsByRowIdDiscussions | 获取行记录讨论 | Apifox | | getAppWorksheetsByWorksheetIdRowsByRowIdLogs | 获取行记录日志 | Apifox | | getAppWorksheetsByWorksheetIdRowsByRowIdRelationsByField | 获取关联记录 | Apifox | | getRecordList | 获取行记录列表 | Apifox | | patchAppWorksheetsByWorksheetIdRowsBatch | 批量更新行记录详情 | Apifox | | postAppWorkflowByWorksheetIdRowsByRowIdApprovalList | 根据行记录获取审批流程执行列表 | Apifox | | postAppWorksheetsByWorksheetIdRowsBatch | 批量新增行记录 | Apifox | | postAppWorksheetsByWorksheetIdRowsByRowIdShareLink | 获取记录分享链接 | Apifox | | postAppWorksheetsByWorksheetIdRowsPivot | 获取行记录透视数据 | Apifox | | updateRecord | 更新行记录 | Apifox |

hap.roles

| 方法 | 用途 | 参数与返回值 | | ------------------------------- | ---------------- | ------------------------------------------------------------ | | deleteAppRolesByRoleId | 删除角色 | Apifox | | deleteAppRolesByRoleIdMembers | 移除角色成员 | Apifox | | deleteAppRolesUsersByUserId | 成员退出所有角色 | Apifox | | getAppRoles | 获取角色列表 | Apifox | | getAppRolesByRoleId | 获取角色详情 | Apifox | | postAppRoles | 创建角色 | Apifox | | postAppRolesByRoleIdMembers | 添加角色成员 | Apifox |

hap.views

| 方法 | 用途 | 参数与返回值 | | ------------------------------------------ | ------------ | ------------------------------------------------ | | postAppWorksheetsByWorksheetIdViewsBatch | 批量创建视图 | Apifox |

hap.workflows

| 方法 | 用途 | 参数与返回值 | | --------------------------------------------- | ------------------ | --------------------------------------------------------- | | deleteAppWorkflowsByWorkflowId | 删除工作流 | Apifox | | deleteAppWorkflowsByWorkflowIdNodesByNodeId | 删除工作流节点 | Apifox | | getAppWorkflowProcesses | 获取触发流程列表 | Apifox | | getAppWorkflowProcessesByProcessId | 获取触发流程详情 | Apifox | | getAppWorkflowsByWorkflowId | 获取工作流结构详情 | Apifox | | postAppWorkflowHooksByProcessId | 触发流程 | Apifox | | postAppWorkflows | 创建工作流 | Apifox | | postAppWorkflowsByWorkflowIdNodesBatch | 批量添加工作流节点 | Apifox | | postAppWorkflowsByWorkflowIdPublish | 发布工作流 | Apifox | | postAppWorkflowsByWorkflowIdValidate | 校验工作流 | Apifox |

hap.worksheets

| 方法 | 用途 | 参数与返回值 | | -------------------------------------------------- | ------------------ | ------------------------------------------------------------ | | createWorksheet | 新建工作表 | Apifox | | deleteAppWorksheetsByWorksheetId | 删除工作表 | Apifox | | getWorksheetStructure | 获取工作表结构信息 | Apifox | | postAppWorksheetsByWorksheetIdCustomActionsBatch | 批量创建自定义动作 | Apifox | | postAppWorksheetsList | 获取工作表列表 | Apifox | | updateWorksheet | 更新工作表结构 | Apifox |