TP-TUMS SDK

Node.js SDK for TP-LINK TUMS (Video Management System)

简介

TP-TUMS SDK 是一个用于与 TP-LINK TUMS (视频管理系统) 进行交互的 Node.js SDK。它提供了完整的 API 封装，包括账户管理、设备管理、视频预览、录像回放和消息推送等功能。

功能特性

• 账户管理 - 登录、注销、获取加密密钥
• 设备管理 - 获取设备详情信息
• 视频预览 - 添加预览通道、获取预览 URL
• 录像回放 - 搜索录像日期、搜索录像片段、上传至 FTP
• 消息推送 - 配置消息推送服务
• 自动会话管理 - 自动处理 Session 和 Cookie
• RSA 加密支持 - 支持登录接口的 RSA 加密

安装

npm install tp-tums-sdk

快速开始

1. 环境变量配置

创建 .env 文件：

TP_TUMS_SERVERURL=https://192.168.1.1:8888
TP_TUMS_USERNAME=admin
TP_TUMS_PASSWORD=your_password_here

2. 基础使用

import { TumsClient } from 'tp-tums-sdk';

async function main() {
  try {
    // 创建客户端实例（自动从环境变量加载配置）
    const client = new TumsClient();

    console.log('正在连接并登录...');
    // 连接并登录
    await client.connect();
    console.log('✓ 登录成功');

    console.log('正在获取设备列表...');
    // 获取设备列表
    const deviceList = await client.device.getDeviceList({
      start: 0,
      limit: 20,
      filterAnd: {
        projectId: '1',  // 必填：项目 ID
        deviceStatus: 1
      },
      sort: [
        { key: 'deviceName', value: 'asc' }  // 可选：排序规则
      ]
    });
    console.log('✓ 设备列表:', deviceList);

    console.log('正在获取设备详情...');
    // 获取设备详情
    const deviceDetails = await client.device.getDeviceDetails({
      deviceIndex: '1'
    });
    console.log('✓ 设备详情:', deviceDetails);

    // 断开连接
    console.log('正在断开连接...');
    await client.disconnect();
    console.log('✓ 已断开连接');
  } catch (error) {
    console.error('❌ 发生错误:', error instanceof Error ? error.message : error);
    throw error;
  }
}

main().catch(console.error);

3. 手动配置

import { TumsClient } from 'tp-tums-sdk';

async function main() {
  try {
    // 手动创建客户端实例（显式配置参数）
    const client = new TumsClient({
      serverUrl: 'https://192.168.1.242:8888',
      username: 'admin',
      password: 'admin123'
    });

    console.log('正在连接并登录...');
    await client.connect();
    console.log('✓ 登录成功');


    console.log('\n正在获取设备列表...');
    const deviceList = await client.device.getDeviceList({
      start: 0,
      limit: 20,
      filterAnd: {
        projectId: '1',  // 必填：项目 ID
        deviceStatus: 1
      },
      sort: [
        { key: 'deviceName', value: 'asc' }  // 可选：排序规则
      ]
    });
    console.log('✓ 设备列表:', JSON.stringify(deviceList, null, 2));

    console.log('\n正在获取设备详情...');
    const deviceDetails = await client.device.getDeviceDetails({
      deviceIndex: '1'
    });
    console.log('✓ 设备详情:', JSON.stringify(deviceDetails, null, 2));

    console.log('\n正在断开连接...');
    await client.disconnect();
    console.log('✓ 已断开连接');

    console.log('\n✅ 测试完成！');
  } catch (error) {
    console.error('\n❌ 发生错误:', error instanceof Error ? error.message : error);
    if (error?.errorCode) {
      console.error('错误码:', error.errorCode);
    }
    throw error;
  }
}

main().catch(console.error);

API 模块

Account API

// 获取登录加密密钥
const encryptKey = await client.account.getEncryptKeyForLogin();

// 用户登录
const loginResult = await client.account.login({
  username: 'admin',
  password: 'password'
});

// 用户注销
await client.account.logout();

Device API

// 查询设备列表
const deviceList = await client.device.getDeviceList({
  start: 0,
  limit: 20,
  filterAnd: {
    projectId: 'your-project-id',  // 必填：项目 ID
    deviceStatus: 1,                // 可选：设备状态（1: 在线，0: 离线）
    deviceTypeList: ["SURVEILLANCECAMERA"],      // 可选：设备类型列表
    macList: ["00-FF-00-1D-E2-1C","00-FF-00-2C-B1-54"] // 可选：MAC地址列表
  },
  filterOr: {
    deviceNameLike: 'Camera'        // 可选：设备名称模糊匹配
  },
  sort: [
    { key: 'deviceName', value: 'asc' }  // 可选：排序规则
  ]
});

console.log('设备总数:', deviceList.total);
console.log('设备列表:', deviceList.list);

// 获取设备详情
const deviceDetails = await client.device.getDeviceDetails({
  deviceIndex: '1'
});

Preview API

// 添加预览通道
const channel = await client.preview.addPreviewChannel({
  id: '1',
  streamType: 1,  // 0: 主码流, 1: 子码流
  channelId: 1    // 可选，适配枪球联动 IPC
});

// 获取预览 URL
const url = await client.preview.getPreviewUrl({
  id: '1',
  streamType: 1,
  sessionId: channel.sessionId
});

Playback API

// 搜索存在录像的日期
const yearResult = await client.playback.searchYear({
  id: [{ videoDevId: '1' }],
  year: '2024'
});

// 搜索当天的录像数据
const videoResult = await client.playback.searchVideo({
  id: [{ videoDevId: '1' }],
  searchDay: '20240320',
  startIdx: 0,
  endIdx: 799
});

// 上传回放视频至 FTP 服务器
const uploadResult = await client.playback.uploadToServer({
  videoDevId: '1',
  videoType: 3,
  startTime: 1622699529,
  endTime: 1622701671,
  downloadInfo: {
    ftpIp: '192.168.1.140',
    ftpPort: 21,
    username: 'admin',
    password: '123456',
    path: '/'
  }
});

// 获取上传进度
const progress = await client.preview.getUploadProgress({
  taskId: 'task-id'
});

// 停止上传
await client.preview.stopUpload({
  taskId: 'task-id'
});

Message Push API

// 获取消息推送配置列表
const configList = await client.messagePush.getMsgPushConfigList();

// 批量添加消息推送配置
await client.messagePush.batchAddMsgPushConfig({
  serverUrl: 'http://192.168.1.77:8888/api/v1/receiveMsg',
  msgTypeList: ['gateRecord', 'accessAttendance']
});

// 删除消息推送配置
await client.messagePush.deleteMsgPushConfig({
  idList: ['1', '2']
});

错误处理

SDK 提供了多种错误类型，方便进行精确的错误处理：

import {
  TumsClient,
  TumsApiError,
  TumsAuthError,
  TumsSessionExpiredError,
  TumsNetworkError
} from 'tp-tums-sdk';

try {
  await client.connect();
} catch (error) {
  if (error instanceof TumsAuthError) {
    console.error('认证失败:', error.message);
  } else if (error instanceof TumsSessionExpiredError) {
    console.error('会话已过期，需要重新登录');
  } else if (error instanceof TumsNetworkError) {
    console.error('网络错误:', error.message);
  } else if (error instanceof TumsApiError) {
    console.error('API 错误:', error.errorCode, error.message);
  }
}

类型定义

SDK 提供了完整的 TypeScript 类型定义：

import type {
  TumsClientConfig,
  TumsResponse,
  LoginParams,
  LoginResult,
  DeviceDetails,
  PreviewUrlResult,
  // ... 更多类型
} from 'tp-tums-sdk';

开发

安装依赖

npm install

构建

npm run build

运行测试

# 单元测试
npm test

# 集成测试（需要配置环境变量）
npm run test:integration

# 测试监视模式
npm run test:watch

类型检查

npm run typecheck

技术特性

• TypeScript 支持 - 完整的类型定义和 IntelliSense 支持
• 双模块格式 - 同时支持 ESM 和 CommonJS
• 自动会话管理 - 自动处理 Session 创建、续期和销毁
• RSA 加密 - 支持登录接口的 RSA/ECB/OAEPPadding 加密
• 错误处理 - 细粒度的错误类型和清晰的错误信息
• 完整的测试 - 单元测试和集成测试覆盖

系统要求

• Node.js >= 18

许可证

MIT