# @apocaliss92/nodepetkit 中文文档

规范地址：https://npmcn.com/package/%40apocaliss92/nodepetkit/

版本：0\.1\.0
npm 元数据更新时间：2026-07-03T16:26:19.794Z
中文译文更新时间：2026-11-07T06:51:13.983Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40apocaliss92/nodepetkit
原文对照：https://npmcn.com/package/%40apocaliss92/nodepetkit/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：274 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-07-03T16:26:19.260Z
- 最新版本发布：2026-07-03T16:26:19.564Z
- 近 30 天下载量：2023（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

PetKit智能宠物设备的节点.js/TypeScript客户端 在PetKit云(REST)上

## 安装

```sh
npm install @apocaliss92/nodepetkit
```

也可以使用：`pnpm add @apocaliss92/nodepetkit`、`yarn add @apocaliss92/nodepetkit`、`bun add @apocaliss92/nodepetkit`

## README

# 节点

节点.js / TypeScript 客户端 **PetKit 智能宠物设备** 过佩特基特云.

精神继承人 [pypetkitapi 语法](https://github.com/Jezza34000/py-petkit-api) ——同线协议,同云端点,TypeScript-native. 如果您能在PetKit移动应用程序中控制您的设备,您可以通过这个库控制它.

> **只有节点.** 密码和 `fetch` 20号节点有原始物可用. 它不运行在浏览器中 .

* * *

## 安装

```bash
npm i @apocaliss92/nodepetkit
```

**要求节点20或更后.**

* * *

## 快开始

```ts
import { Nodepetkit, FeederDevice } from '@apocaliss92/nodepetkit';

const petkit = new Nodepetkit(
  { email: 'you@example.com', password: 'secret' },
  { region: 'us' }, // region name or ISO id — resolved to a gateway at login
);

// 1. Authenticate (resolves your region gateway, then logs in)
await petkit.login();

// 2. Discover devices registered to your account
const devices = await petkit.discoverDevices();

// 3. Create a typed device handle (fetches its initial state)
const feeder = (await petkit.createDevice(devices[0])) as FeederDevice;

// 4. React to polled state changes
feeder.on('stateChanged', ({ changed }) => console.log('changed:', changed));

// 5. Send commands
await feeder.feed(20); // dispense 20g now
await feeder.setChildLock(true);

// 6. Poll again whenever you like (PetKit has no realtime push)
await feeder.refresh();
```

### 基于托肯认证

如果您已经拥有会话符号 :

```ts
const petkit = new Nodepetkit({ token: 'your-session-id', region: 'us' });
await petkit.login(); // resolves the gateway; pass `gateway` too to skip that call
```

> PetKit 只允许 **每个账户一个活动会话**。在此登录可以登录 离开你的手机应用(反之亦然). 考虑一个专门的共享"家庭成员" 根据家庭助理PetKit社区的建议.

* * *

## 支持的设备

| 设备类 | 系列 | 状态 |
| --- | --- | --- |
| `FeederDevice` | 新鲜元素/ 小型/ D3 / D4 / **D4S (格米尼语)** / D4H / D4SH | 核心命令 |
| `LitterDevice` | Pura X (T3), Pura MAX (T4), T5 / T6 / T7 | 核心命令 |
| `PurifierDevice` | K2 / K3 除臭剂 | 核心命令 |
| `FountainDevice` | 相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相相相相接相接相相接相接相接相接相相接相接相接相接相接相接相相相相接相接相接相相相相接相接相相相接相接相相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 | 国家+设置; **BLE 控制 `@experimental`** |
| `UnknownDevice` | 任何未识别类型 | 退后( 初始状态 + 通过命令) |

国家战地名称和命令有效载荷转自 `pypetkitapi`他们是 **尚未进行硬件核查** 在这个端口中——如果一个字段或命令错误,打开一个问题.

* * *

## 如何运作

1.  **地区** —— 说 `login()` 电话 `GET v1/regionservers` 打开 `passport.petkt.com` 来映射您的 区域到网关( e)`api.eu-pet.com`, (中文(简体) ), `api.petkt.com`, (中文(简体) ), `api.petktasia.com`(中文(简体) ).
2.  **认证** - 它的POSTs(英语: `user/login` 带有 MD5 隐藏密码; 返回的会话 id 是 以 `X-Session` 编号 : `F-Session` 在以后的每一个电话.
3.  **发现** —— 说 `discoverDevices()` 读取 `group/family/list` (加上共用设备名册).
4.  **状态** —— 说 `createDevice()` 职位 `{deviceType}/device_detail` (或 `deviceData`和存储它.
5.  **图标** —— 说 `updateSettings` 对于持久的选择, `controlDevice` 暂时行动, 和每台设备的终点`saveDailyFeed`, (中文(简体) ), `deodorantReset`,... ) 对于其余的.

PetKit的经典 REST API 有 **没有实时推** 频道,所以州 通过投票刷新 (单位:千美元)`device.refresh()`);没有WebSocket可以继续打开.

所有内部`PetkitHttp`, (中文(简体) ), `CloudDeviceGateway`, (中文(简体) ), `login`,加密帮助) 保护API稳定性的公众表面.

* * *

## API 参考

### `Nodepetkit`

```ts
new Nodepetkit(
  creds: { email: string; password: string } | { token: string; region: string; gateway?: string },
  opts?: { region?: string; timezone?: string },
)
```

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `login()` | `Promise<void>` | 解决区域网关和认证 |
| `discoverDevices()` | `Promise<PetkitDeviceInfo[]>` | 账户上的列表设备 |
| `createDevice(info)` | `Promise<BaseDevice>` | 构建打入的控点并获取其状态 |
| `getSession()` | `PetkitSession | null` | 活动符号 + 已解决的网关 |

### `BaseDevice`

所有设备类扩展 `BaseDevice`,一个已键入的事件发送器.

| 成员 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `string` | PetKit 设备 ID |
| `deviceType` | `string` | 原始类型( E)`d4s`, (中文(简体) ), `t4`, (中文(简体) ), `w5`, (...) (中文(简体) ) |
| `type` | `DeviceType` | 家属: `feeder` 编号 : `litter` 编号 : `fountain` 编号 : `purifier` 编号 : `unknown` |
| `name` | `string` | 友好名称 |
| `online` | `boolean` | 最佳网络旗帜 |
| `state` | `Readonly<DeviceState>` | 最新调查的细节 |
| `refresh()` | `Promise<void>` | 打开云和合并状态 |
| 事件 `stateChanged` | `{ changed }` | 在民意调查状态改变时被披露 |

### `FeederDevice`

`food` • 妇女 `food1` • 妇女 `food2` • 妇女 `batteryPower` • 妇女 `desiccantLeftDays` • 妇女 `feeding` • 妇女 `errorCode` • 妇女 `feed(grams | { hopper1, hopper2 })` • 妇女 `cancelFeed()` • 妇女 `resetDesiccant()` • 妇女 `markFoodReplenished()` • 妇女 `callPet()` _(D3级)_ • 妇女 `playSound(id)` _(D3/D4H/D4SH) (中文(简体) )_ • 妇女 `setChildLock()` • 妇女 `setIndicatorLight()` • 妇女 `setFeedSound()` • 妇女 `setVolume()` • 妇女 `setSetting(kv)`

### `LitterDevice`

`boxFull` • 妇女 `sandPercent` • 妇女 `sandLack` • 妇女 `liquidLack` • 妇女 `deodorantLeftDays` • 妇女 `errorCode` • 妇女 `battery` • 妇女 `usedTimes` • 妇女 `startCleaning()` • 妇女 `dumpLitter()` • 妇女 `removeOdor()` • 妇女 `levelLitter()` • 妇女 `resetN60Deodorizer()` • 妇女 `resetN50Deodorant()` • 妇女 `setLight()` • 妇女 `setMaintenance()` • 妇女 `setPower()` • 妇女 `stop(code)` • 妇女 `setAutoClean()` • 妇女 `setChildLock()` • 妇女 `setSandType(1|2|3)` • 妇女 `setAutoInterval(seconds)` • 妇女 `setSetting(kv)`

### `PurifierDevice`

`mode` • 妇女 `power` • 妇女 `liquid` • 妇女 `liquidLack` • 妇女 `humidity` • 妇女 `temperature` • 妇女 `setPower()` • 妇女 `setMode(PUR_MODE)` • 妇女 `setAutoWork()` • 妇女 `setChildLock()` • 妇女 `setSetting(kv)`

### `FountainDevice`

`mode` • 妇女 `powered` • 妇女 `running` • 妇女 `filterPercent` • 妇女 `filterWarning` • 妇女 `lackWarning` • 妇女 `batteryPercent` · 云: `setLightRing()` • 妇女 `setLightBrightness()` • 妇女 `setDoNotDisturb()` • 妇女 `setSetting(kv)` · BLE(`@experimental`: `powerOn()` • 妇女 `powerOff()` • 妇女 `pause()` • 妇女 `resume()` • 妇女 `setNormalMode()` • 妇女 `setSmartMode()` • 妇女 `resetFilter()`

喷泉没有直接控制云层——指令通过附近地区传送到BLE上空 PetKit 设备,所以 BLE 方法只有在您账户/网络上有这样的接力时才有效 .

* * *

## 诊断倾倒器

```ts
import { createDumper } from '@apocaliss92/nodepetkit';

const snapshot = createDumper(feeder, { redact: true }).dump();
// { id: '******1234', deviceType: 'd4', type: 'feeder', name: '***chen', state: {…} }
```

`redact: true` (默认)遮住设备的id和名称,这样垃圾可以安全共享.

* * *

## 错误类型

| 类 | 掷出时 |
| --- | --- |
| `PetkitError` | 所有库错误的基准类 |
| `PetkitAuthError` | 登录/ 区域分辨率/ 符号失败 |
| `PetkitApiError` | PetKit 应用程序出错 (`.code`)或非-2xxHTTP 软件 |
| `PetkitTransportError` | 网络错误到达 REST API |
| `PetkitDeviceOfflineError` | 备用——尚未投出 |

* * *

## 信用范围

逆向工程从 [`pypetkitapi`](https://github.com/Jezza34000/py-petkit-api) (图书馆) 后边 [Jezza34000 家庭助理PetKit融入社会](https://github.com/Jezza34000/homeassistant_petkit)) (中文(简体) ). 见 [`docs/petkit-cloud-api-spec.md`](https://npmcn.com/package/%40apocaliss92/nodepetkit/docs/petkit-cloud-api-spec.md) 整个协议 注意此端口的构建来源。 不隶属于PetKit或得到其认可.

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40apocaliss92/nodepetkit/LICENSE)。 。 。 .

## 常见问题

### @apocaliss92/nodepetkit 是什么？

PetKit智能宠物设备的节点\.js/TypeScript客户端 在PetKit云\(REST\)上

### 如何安装 @apocaliss92/nodepetkit？

在项目目录运行 npm install @apocaliss92/nodepetkit，或使用 pnpm add / yarn add / bun add。

### @apocaliss92/nodepetkit 支持 TypeScript 吗？

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

### @apocaliss92/nodepetkit 支持 ESM 还是 CommonJS？

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

### @apocaliss92/nodepetkit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @apocaliss92/nodepetkit 可以商用吗？

@apocaliss92/nodepetkit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @apocaliss92/nodepetkit 的下载量有多少？

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

### @apocaliss92/nodepetkit 还在维护吗？

最新版本 0\.1\.0 发布于 2026/07/04（4 个月前）；至今共发布 1 个版本，其中过去 12 个月发布了 1 个；首次发布于 2026/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。