nodepetkit

Node.js / TypeScript client for PetKit smart pet devices over the PetKit cloud (REST).

Spiritual successor to pypetkitapi — same wire protocol, same cloud endpoints, TypeScript-native. If you can control your device in the PetKit mobile app, you can control it with this library.

Node only. Uses crypto and fetch primitives available in Node ≥ 20. It does not run in browsers.

Install

npm i @apocaliss92/nodepetkit

Requires Node 20 or later.

Quick start

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

const petkit = new Nodepetkit(
  { email: '[email protected]', 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();

Token-based authentication

If you already have a session token:

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

⚠️ PetKit only allows one active session per account. Logging in here can log out your phone app (and vice-versa). Consider a dedicated shared "family member" account, as recommended by the Home Assistant PetKit community.

Supported devices

State field names and command payloads are transcribed from pypetkitapi. They are not yet hardware-verified in this port — open an issue if a field or command is wrong.

How it works

1. Region — login() calls GET v1/regionservers on passport.petkt.com to map your region to a gateway (api.eu-pet.com, api.petkt.com, api.petktasia.com, …).
2. Auth — it POSTs user/login with an MD5-hashed password; the returned session id is sent as X-Session / F-Session on every later call.
3. Discovery — discoverDevices() reads group/family/list (plus the shared-device roster).
4. State — createDevice() POSTs {deviceType}/device_detail (or deviceData) and stores it.
5. Commands — updateSettings for persistent options, controlDevice for transient actions, and per-device endpoints (saveDailyFeed, deodorantReset, …) for the rest.

PetKit's classic REST API has no realtime push channel, so state is refreshed by polling (device.refresh()); there is no WebSocket to keep open.

All internals (PetkitHttp, CloudDeviceGateway, login, crypto helpers) are kept out of the public surface to preserve API stability.

API reference

Nodepetkit

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

BaseDevice

All device classes extend BaseDevice, a typed event emitter.

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 · cloud: setLightRing() · setLightBrightness() · setDoNotDisturb() · setSetting(kv) · BLE (@experimental): powerOn() · powerOff() · pause() · resume() · setNormalMode() · setSmartMode() · resetFilter()

Fountains have no direct cloud control — commands are relayed over BLE through a nearby PetKit device, so BLE methods only work when such a relay is on your account/network.

Diagnostics dumper

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

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

redact: true (default) masks the device id and name so dumps can be shared safely.

Error types

Credits & scope

Reverse-engineered from pypetkitapi (the library behind the Jezza34000 Home Assistant PetKit integration). See docs/petkit-cloud-api-spec.md for the full protocol notes this port is built from. Not affiliated with or endorsed by PetKit.

License

MIT — see LICENSE.