HabitaXX Node.js / TypeScript SDK

栖界 HabitaXX 开放平台官方 Node.js / TypeScript SDK，支持 Node.js (18+)、Deno、Bun 等服务端运行环境，提供全面的 TypeScript 类型定义和 Promise 异步调用。

完整 API 文档

各接口的参数定义与完整调用方法可参考 api.md。

安装

npm install habitaxx

或者使用 yarn / pnpm / bun：

pnpm add habitaxx
# 或 yarn add habitaxx
# 或 bun add habitaxx

核心授权与调用流程

栖界开放平台采用 两阶段鉴权 机制：

1. 获取 Access Token：使用平台颁发的 x-api-key、项目编号 project_no 和开发者用户标识 user_id，调用 /v1/auth/token 接口换取短效 access_token。
2. 调用业务接口：将换取到的 access_token 作为凭证初始化业务客户端或动态赋值，后续请求将自动在 Header 中携带 Authorization: Bearer <access_token> 调用具体能力接口（如宠物 AI 分析、鸟类识别等）。

1. 完整两阶段调用示例 (TypeScript / ESM)

import Habitaxx from 'habitaxx';

async function main() {
  const API_KEY = process.env['HABITAXX_API_KEY'] || 'qj_live_your_api_key';
  const BASE_URL = process.env['HABITAXX_BASE_URL'] || 'https://open-api.habitaxx.com';

  // 步骤 1：初始化客户端并换取短效 Access Token
  const client = new Habitaxx({
    apiKey: API_KEY,
    baseURL: BASE_URL,
  });

  // 调用认证接口
  // 对应 HTTP 请求：
  // POST /v1/auth/token
  // Headers: x-api-key: <API_KEY>
  // Body: {"project_no": "...", "user_id": "..."}
  const tokenResp: any = await client.auth.token({
    'x-api-key': API_KEY,
    body: {
      project_no: 'prj_your_project_no',
      user_id: 'user_123456',
    },
  });

  const accessToken = tokenResp.data.access_token;
  console.log('成功获取 access_token:', accessToken);

  // 步骤 2：创建或更新携带 access_token 的客户端进行业务调用
  const apiClient = new Habitaxx({
    apiKey: accessToken, // 内部自动注入 Authorization: Bearer <access_token>
    baseURL: BASE_URL,
  });

  // 调用健康检查或业务能力接口
  const healthStatus = await apiClient.health.check();
  console.log('健康检查响应:', healthStatus);

  // 调用宠物行为预测接口示例：
  // const predictResp = await apiClient.predict.new({
  //   data: [[0.1, 0.2, 0.3, 0.4, 0.5, 0.6]],
  //   device_id: 'dev_1001',
  // });
}

main().catch(console.error);

2. CommonJS 规范调用示例

const { Habitaxx } = require('habitaxx');

const client = new Habitaxx({
  apiKey: process.env['HABITAXX_API_KEY'],
});

async function run() {
  const tokenResp = await client.auth.token({
    'x-api-key': process.env['HABITAXX_API_KEY'],
    body: {
      project_no: 'prj_your_project_no',
      user_id: 'user_123456',
    },
  });
  console.log('Token response:', tokenResp);
}

run();

异常与错误处理

当请求遇到网络错误或服务端返回非 2xx 响应时，SDK 会抛出对应的 APIError 异常子类：

import Habitaxx from 'habitaxx';

const client = new Habitaxx({ apiKey: '...' });

try {
  await client.health.check();
} catch (err) {
  if (err instanceof Habitaxx.APIConnectionTimeoutError) {
    console.error('网络请求超时:', err.message);
  } else if (err instanceof Habitaxx.APIConnectionError) {
    console.error('网络不可达或连接中断:', err.message);
  } else if (err instanceof Habitaxx.APIError) {
    console.error('请求执行异常:', err.message);
  } else {
    console.error('其他未知异常:', err);
  }
}

统一业务响应与异常处理

平台接口对外统一返回 HTTP 200 响应，业务状态与错误信息均收敛在响应体中：

• 成功响应：code: 200, message: "success", data: { ... }
• 业务失败：包含全局唯一错误码 code、语义化标识 error_code、脱敏中文提示 message 及全局链路追踪 ID call_id
• 传输与网络异常类：
  • Habitaxx.APIConnectionError: 网络不可达或连接中断
  • Habitaxx.APIConnectionTimeoutError: 请求超时
  • Habitaxx.APIError: API 请求生命周期基类异常

高级配置

1. 超时与重试

默认情况下，客户端提供 1 分钟超时时间，并对网络超时和连接错误进行最多 2 次指数退避重试：

const client = new Habitaxx({
  apiKey: '...',
  timeout: 20 * 1000, // 20 秒
  maxRetries: 3,       // 重试 3 次
});

2. 自定义 HTTP Agent / 代理

在 Node.js 环境中，可通过配置 httpAgent 支持公司内部代理或长连接复用：

import http from 'http';
import Habitaxx from 'habitaxx';

const client = new Habitaxx({
  apiKey: '...',
  httpAgent: new http.Agent({ keepAlive: true }),
});