uptime-kuma-sdk

TypeScript client for Uptime Kuma, communicating over Socket.IO.

Full parity with the Python uptime-kuma-api client — 86 methods across 11 modules, fully typed, with one runtime dependency.

npm install uptime-kuma-sdk

Requires Node 18+. Ships both ESM and CommonJS builds with type declarations.

Quick start

import { UptimeKumaClient, MonitorType } from 'uptime-kuma-sdk'

const client = new UptimeKumaClient({
  baseUrl: 'http://localhost:3001',
  username: 'admin',
  password: 'secret',
})

await client.initialize()

const id = await client.monitor.addMonitor({
  type: MonitorType.HTTP,
  name: 'My site',
  url: 'https://example.com',
  interval: 60,
})

const monitors = await client.monitor.getMonitors()
console.log(monitors.length)

client.disconnect()

CommonJS works too:

const { UptimeKumaClient, MonitorType } = require('uptime-kuma-sdk')

disconnect() is not optional — the open socket keeps the Node process alive.

Configuration

new UptimeKumaClient({
  baseUrl: 'http://localhost:3001',
  username: 'admin',
  password: 'secret',
  token: '123456',   // optional: 2FA token
  timeout: 10_000,   // optional: ms to wait for a response, default 10000
})

Modules

Everything hangs off the client after initialize().

| Module | Methods | |---|---| | client.monitor | CRUD, pause/resume, heartbeats, status, tags, game list, chrome test | | client.notification | CRUD, test, Apprise check — 53 typed providers | | client.proxy | CRUD | | client.statusPage | CRUD, save, incidents | | client.maintenance | CRUD, pause/resume, monitor and status-page assignment | | client.tag | CRUD | | client.dockerHost | CRUD, connection test | | client.apiKey | CRUD, enable/disable | | client.settings | Settings, password, backup, database, clear operations | | client.auth | Login, token login, 2FA, setup | | client.info | Server info, uptime, ping, certificates, heartbeats |

Typed monitors

addMonitor is a discriminated union over 22 monitor types, so the compiler only accepts fields valid for the type you chose:

import { MonitorType, AuthMethod } from 'uptime-kuma-sdk'

await client.monitor.addMonitor({
  type: MonitorType.KEYWORD,
  name: 'Login page',
  url: 'https://example.com/login',
  keyword: 'Sign in',
  authMethod: AuthMethod.HTTP_BASIC,
  basic_auth_user: 'user',
  basic_auth_pass: 'pass',
})

Typed notifications

All 53 providers are discriminated on type:

import { NotificationType } from 'uptime-kuma-sdk'

await client.notification.addNotification({
  type: NotificationType.DISCORD,
  name: 'Team channel',
  discordWebhookUrl: 'https://discord.com/api/webhooks/…',
})

Live heartbeats

Uptime Kuma pushes heartbeats over the socket. Subscribe directly:

const unsubscribe = client.on('heartbeat', (beat) => {
  console.log(beat.monitorID, beat.status)
})

unsubscribe()

Error handling

Failures throw ApiError, carrying a statusCode that classifies what went wrong. Uptime Kuma is not HTTP — these describe the failure, not a response.

import { ApiError, HttpStatus } from 'uptime-kuma-sdk'

try {
  await client.monitor.getMonitor(999)
} catch (error) {
  if (error instanceof ApiError && error.statusCode === HttpStatus.NOT_FOUND) {
    // …
  }
}

| Code | Meaning | |---|---| | 401 | Login rejected | | 404 | Entity not found | | 412 | Client used before initialize() | | 500 | Server reported a failure | | 504 | No response before the timeout |

How it reads data

Uptime Kuma pushes most collections rather than answering requests for them. The client caches those pushes, so getters like getMonitors(), getHeartbeats() and uptime() resolve from the cache — waiting for the first push if it has not arrived yet. Writes update the cache directly rather than relying on the server to re-push, which it does not do consistently.

Compatibility

Verified against Uptime Kuma 2.5.0. The Python client this was ported from targets 1.23.x, and the two versions differ in required fields and push behaviour. 1.x is currently untested — please open an issue if you hit problems there.

Contributing

See AGENT.md and .wiki/ for architecture notes, protocol quirks and conventions.

npm run typecheck     # primary correctness gate
npm run format:check
npm run build         # dual ESM + CJS with declarations
npm run smoke         # live round-trip; needs a throwaway server

There is no unit test suite yet. Because wire types are hand-written and not validated at runtime, a clean typecheck does not prove wire correctness — run the smoke test against a real instance for anything touching the server.

Releasing

npm version patch
git push --follow-tags

The tag push triggers .github/workflows/publish.yml, which typechecks, builds, verifies the tag matches the manifest version, audits the tarball for leaked sources or credentials, and publishes with provenance. It can also be run manually from the Actions tab, with a dry-run option.

License

Apache-2.0