@mustafakurtt/pushover

Modern, TypeScript-first Pushover API client. Zero dependencies. Works with Bun & Node.js.

Why This Package?

Other Pushover packages are just thin wrappers — you still write the same boilerplate every time. This one is different:

Semantic methods — .success(), .error(), .warning(), .info(), .emergency() with smart defaults
Fluent builder — pushover.message('text').to('iphone').withSound('siren').send()
Message queue — batch multiple notifications and flush at once
Rate limiting — built-in sliding window protection
Auto-retry — exponential backoff on failures
Limit checker — check your remaining monthly quota via API
Multi-device — .to('iphone', 'pixel') or .sendToDevices() — one call, multiple devices
Device groups — define named groups, send with .toGroup('mobile')
Templates — reusable message presets: .template('deploy', 'v2.0 shipped!')
Conditional sending — .onlyBetween('09:00', '18:00') — time-based filtering
Delivery groups — full group management API: add/remove/enable/disable users, rename, list
Receipt tracking — track emergency notifications: acknowledged? expired? cancel & poll
User validation — verify user keys, list devices, detect groups
String shorthand — pushover.send('Deploy done!') — no object needed
One-liner notify() — fire-and-forget without creating a client instance
Factory function — createPushover() — no new keyword
Default config — set defaultSound, defaultDevice, defaultTitle once
Full TypeScript — strict types, autocomplete everything
Zero dependencies — native fetch, no bloat

// Other packages
const push = new Pushover({ user: '...', token: '...' })
push.send({ message: 'done', title: 'Deploy', sound: 'magic', priority: 0 }, callback)

// This package
const pushover = createPushover({ token: '...', user: '...' })
await pushover.success('Deploy done!')

// Or with fluent builder
await pushover
  .message('Server down!')
  .to('iphone')
  .withSound('siren')
  .withPriority(1)
  .send()

Installation

# bun
bun add @mustafakurtt/pushover

# npm
npm install @mustafakurtt/pushover

# pnpm
pnpm add @mustafakurtt/pushover

Quick Start

import { createPushover } from '@mustafakurtt/pushover'

const pushover = createPushover({
  token: 'YOUR_APP_TOKEN',
  user: 'YOUR_USER_KEY',
})

// Simple string
await pushover.send('Hello from Pushover!')

// Semantic methods — priority, sound, title are auto-set
await pushover.success('Deployment completed')
await pushover.error('Payment service is down')
await pushover.warning('Disk usage at 85%')
await pushover.info('New user registered')
await pushover.emergency('Database unreachable!')

Usage

One-Liner (No Client Needed)

import { notify } from '@mustafakurtt/pushover'

await notify(
  { token: 'YOUR_APP_TOKEN', user: 'YOUR_USER_KEY' },
  'Server restarted successfully',
)

Fluent Builder (Method Chaining)

Build notifications step-by-step with full IDE autocomplete:

await pushover
  .message('CPU usage above 95%')
  .title('Server Alert')
  .to('iphone')
  .withSound('siren')
  .withPriority(1)
  .withUrl('https://monitor.example.com', 'View Dashboard')
  .send()

// Emergency with retry
await pushover
  .message('All replicas are down!')
  .withPriority(2)
  .retry(60)
  .expire(3600)
  .send()

// HTML content
await pushover
  .message('<b>Bold</b> and <i>italic</i>')
  .html()
  .send()

Message Queue (Batch Sending)

Queue multiple messages and send them all at once:

pushover
  .queue('Backup started')
  .queue('Database optimized')
  .queue({ message: 'Backup completed', title: 'Backup' })

console.log(pushover.queueSize) // 3

const result = await pushover.flush()
console.log(result.succeeded.length) // 3
console.log(result.failed.length)    // 0

Rate Limiting

Protect against accidentally exceeding API limits:

const pushover = createPushover({
  token: 'YOUR_APP_TOKEN',
  user: 'YOUR_USER_KEY',
  rateLimit: {
    maxPerInterval: 10,   // max 10 messages
    intervalMs: 60_000,   // per minute
  },
})

// 11th message within a minute throws PushoverValidationError

Auto-Retry with Exponential Backoff

Automatically retry failed requests:

const pushover = createPushover({
  token: 'YOUR_APP_TOKEN',
  user: 'YOUR_USER_KEY',
  retry: {
    maxAttempts: 3,        // try up to 3 times
    baseDelayMs: 1000,     // 1s → 2s → 4s (exponential)
    maxDelayMs: 30_000,    // cap at 30s
  },
})

// If API is temporarily down, it will retry automatically
await pushover.send('This will retry on failure')

Check Monthly Limits

Check your app's remaining monthly message quota:

const limits = await pushover.limits()

console.log(limits.limit)     // 10000 (monthly limit)
console.log(limits.remaining) // 9500  (remaining this month)
console.log(limits.reset)     // Unix timestamp when limit resets

Multi-Device Targeting

Send to multiple devices in one call:

// Via method
const results = await pushover.sendToDevices('Alert!', ['iphone', 'pixel', 'desktop'])

results.forEach(r => {
  console.log(`${r.device}: ${r.success ? 'sent' : r.error?.message}`)
})

// Via fluent builder
await pushover.message('Server down!').to('iphone', 'pixel').send()

Device Groups

Define named device groups in config:

const pushover = createPushover({
  token: 'YOUR_APP_TOKEN',
  user: 'YOUR_USER_KEY',
  deviceGroups: {
    mobile: ['iphone', 'pixel'],
    all: ['iphone', 'pixel', 'desktop'],
  },
})

// Send to a group
await pushover.sendToGroup('Alert!', 'mobile')

// Or via builder
await pushover.message('Alert!').toGroup('all').send()

Template Messages

Define reusable message presets:

const pushover = createPushover({
  token: 'YOUR_APP_TOKEN',
  user: 'YOUR_USER_KEY',
  templates: {
    deploy: { title: 'Deploy', sound: 'magic', priority: 0 },
    alert: { title: 'ALERT', sound: 'siren', priority: 1 },
    monitoring: { title: 'Monitor', url: 'https://grafana.example.com', urlTitle: 'Open Grafana' },
  },
})

await pushover.template('deploy', 'v2.1.0 deployed to production')
await pushover.template('alert', 'CPU at 99%')

Conditional Sending (Time-Based)

Send notifications only during specific hours:

// Only send during business hours
await pushover
  .message('Report generated')
  .onlyBetween('09:00', '18:00')
  .send()

// Overnight window also works (e.g. night shift)
await pushover
  .message('Batch job complete')
  .onlyBetween('22:00', '06:00')
  .send()

// With timezone — critical for cloud/serverless deployments
await pushover
  .message('Report generated')
  .onlyBetween('09:00', '18:00', 'Europe/Istanbul')
  .send()

Important: Without a timezone parameter, onlyBetween() uses the server's local time. If your server runs in UTC (e.g. AWS, Vercel), always pass an explicit timezone to avoid unexpected behavior.

Image Attachments

Send images with notifications (security cameras, charts, screenshots):

// From a Blob
const imageBlob = new Blob([imageBuffer], { type: 'image/jpeg' })
await pushover.send({
  message: 'Motion detected!',
  attachment: imageBlob,
  attachmentName: 'front-door.jpg',
})

// From a Buffer / Uint8Array
const screenshot = fs.readFileSync('/tmp/screenshot.png')
await pushover.send({
  message: 'Error screenshot',
  attachment: screenshot,
  attachmentName: 'error.png',
})

// Via fluent builder
await pushover
  .message('Camera alert')
  .withAttachment(imageBlob, 'camera.jpg')
  .send()

Pushover supports JPEG, PNG, and GIF up to 2.5 MB. Attachments are sent as multipart/form-data automatically.

Response Limits (Zero-Cost)

Every send() response now includes your remaining API quota — parsed from response headers at no extra API cost:

const response = await pushover.send('Hello!')

if (response.limits) {
  console.log(response.limits.limit)      // 10000 (monthly max)
  console.log(response.limits.remaining)  // 9543
  console.log(response.limits.reset)      // Unix timestamp of reset
}

This is more efficient than calling limits() separately, which makes a dedicated API request.

Delivery Groups (Multi-User)

Manage Pushover Delivery Groups via API — add/remove friends, enable/disable users, rename groups:

const pushover = createPushover({
  token: 'YOUR_APP_TOKEN',
  user: 'YOUR_USER_KEY',
})

const team = pushover.group('DELIVERY_GROUP_KEY')

// Get group info & members
const info = await team.info()
console.log(info.name)   // "Project Team"
console.log(info.users)  // [{ user: '...', memo: 'Mustafa', ... }, ...]

// Add a friend to the group
await team.addUser({
  user: 'FRIEND_USER_KEY',
  memo: 'Ali',
  device: 'iphone',       // optional: target specific device
})

// Remove, disable, enable users
await team.removeUser('FRIEND_USER_KEY')
await team.disableUser('FRIEND_USER_KEY')
await team.enableUser('FRIEND_USER_KEY')

// Rename the group
await team.rename('Dev Team')

// Helper methods
const users = await team.listUsers()
const exists = await team.hasUser('FRIEND_USER_KEY')

Tip: To send notifications to the entire group, use the group key as the user parameter in your config. Pushover delivers to all group members automatically.

Receipt Tracking (Emergency)

Track and manage emergency (priority=2) notifications:

// Send emergency → returns receipt
const response = await pushover.emergency('All servers down!', {
  retry: 30,
  expire: 3600,
})

// Track the receipt
const tracker = pushover.receipt(response.receipt!)

// Check status
const status = await tracker.status()
console.log(status.acknowledged)      // 0 or 1
console.log(status.acknowledged_by)   // user key who acknowledged
console.log(status.expired)           // 0 or 1

// Convenience getters
if (await tracker.isAcknowledged) console.log('Someone acknowledged!')
if (await tracker.isExpired) console.log('Nobody responded...')

// Cancel the emergency repeat
await tracker.cancel()

// Or poll until someone acknowledges (with timeout)
const ack = await tracker.waitForAcknowledgement({
  intervalMs: 5000,   // check every 5s (default)
  timeoutMs: 300000,  // give up after 5min (default)
})
console.log(`Acknowledged by ${ack.acknowledged_by} on ${ack.acknowledged_by_device}`)

User Validation

Verify user/group keys and discover devices before sending:

// Full validation
const result = await pushover.validateUser('USER_KEY')
console.log(result.devices)   // ['iphone', 'pixel']
console.log(result.group)     // 0 (user) or 1 (group)
console.log(result.licenses)  // ['ios', 'android']

// Validate specific device
await pushover.validateUser('USER_KEY', 'iphone')

// Simple checks
const valid = await pushover.isValidUser('USER_KEY')       // true/false
const devices = await pushover.getUserDevices('USER_KEY')   // string[]

Default Config

const pushover = createPushover({
  token: 'YOUR_APP_TOKEN',
  user: 'YOUR_USER_KEY',
  defaultSound: 'cosmic',
  defaultDevice: 'my-iphone',
  defaultTitle: 'My App',
})

// Every notification will use these defaults unless overridden
await pushover.send('Uses default sound, device, and title')

Semantic Methods with Options

await pushover.error('Payment failed for order #1234', {
  title: 'Payment Error',
  url: 'https://admin.example.com/orders/1234',
  urlTitle: 'View Order',
})

await pushover.emergency('All replicas are down!', {
  retry: 30,
  expire: 7200,
})

Error Handling

import { PushoverApiError, PushoverValidationError } from '@mustafakurtt/pushover'

try {
  await pushover.send('Hello!')
} catch (err) {
  if (err instanceof PushoverValidationError) {
    console.error('Validation:', err.message, err.field)
  } else if (err instanceof PushoverApiError) {
    console.error('API:', err.apiErrors, err.code)
  }
}

Semantic Methods

Method	Priority	Sound	Default Title
`info(text)`	Low (-1)	pushover	Info
`success(text)`	Normal (0)	magic	Success
`warning(text)`	High (1)	falling	Warning
`error(text)`	High (1)	siren	Error
`emergency(text)`	Emergency (2)	persistent	EMERGENCY

All semantic methods accept an optional second argument to override any field.

API Reference

`createPushover(config)` / `new PushoverClient(config)`

Parameter	Type	Required	Description
`token`	`string`	Yes	Application API token
`user`	`string`	Yes	User/group key
`defaultDevice`	`string`	No	Default target device
`defaultSound`	`PushoverSound`	No	Default notification sound
`defaultTitle`	`string`	No	Default notification title
`fetchFn`	`FetchFunction`	No	Custom fetch for testing (DI)
`retry`	`RetryConfig`	No	Auto-retry configuration
`rateLimit`	`RateLimitConfig`	No	Rate limiting configuration
`queue`	`QueueConfig`	No	Message queue configuration
`deviceGroups`	`DeviceGroupMap`	No	Named device groups
`templates`	`TemplateMap`	No	Reusable message presets

`send(message)`

Accepts a string or a PushoverMessage object:

Field	Type	Required	Description
`message`	`string`	Yes	Notification body (max 1024 chars)
`title`	`string`	No	Notification title (max 250 chars)
`url`	`string`	No	Supplementary URL (max 512 chars)
`urlTitle`	`string`	No	URL title (max 100 chars)
`priority`	`number`	No	-2 to 2 (use `PushoverPriority`)
`sound`	`string`	No	Notification sound (use `PushoverSound`)
`device`	`string`	No	Target device name
`html`	`0 \| 1`	No	Enable HTML formatting
`timestamp`	`number`	No	Unix timestamp
`retry`	`number`	No	Emergency retry interval (sec, min 30)
`expire`	`number`	No	Emergency expiry (sec, max 10800)
`attachment`	`Blob \| Buffer \| Uint8Array`	No	Image attachment (max 2.5 MB)
`attachmentName`	`string`	No	Filename for the attachment

`message(text)` → `MessageBuilder`

Fluent builder methods: .title(), .to(...devices), .toGroup(name), .withSound(), .withPriority(), .withUrl(), .html(), .timestamp(), .retry(), .expire(), .withAttachment(data, filename?), .onlyBetween(start, end, timezone?), .send()

`template(name, text)`

Send using a predefined template. Templates are defined in config.

`sendToDevices(message, devices)`

Send to multiple devices. Returns MultiDeviceResult[] with per-device success/failure.

`sendToGroup(message, groupName)`

Send to a named device group. Groups are defined in config.

`queue(message)` / `flush()`

Queue messages and send them in batch. Returns QueueResult with succeeded and failed arrays.

`limits()`

Returns PushoverLimitsResponse with limit, remaining, and reset fields.

`group(groupKey)` → `GroupManager`

Full Delivery Group management:

Method	Description
`.info()`	Get group name and member list
`.addUser({ user, device?, memo? })`	Add a user to the group
`.removeUser(userKey)`	Remove a user from the group
`.disableUser(userKey)`	Temporarily disable a user
`.enableUser(userKey)`	Re-enable a disabled user
`.rename(name)`	Rename the delivery group
`.listUsers()`	Shorthand for `info().users`
`.hasUser(userKey)`	Check if a user is in the group

`receipt(receiptId)` → `ReceiptTracker`

Track emergency notifications:

Method	Description
`.status()`	Get full receipt status (acknowledged, expired, etc.)
`.cancel()`	Cancel the emergency notification repeat
`.isAcknowledged`	`Promise<boolean>` — was it acknowledged?
`.isExpired`	`Promise<boolean>` — did it expire?
`.waitForAcknowledgement(options?)`	Poll until acknowledged, expired, or timeout

`validateUser(userKey, device?)`

Validate a user/group key. Returns UserValidationResponse with devices, group, licenses.

`isValidUser(userKey)` → `Promise<boolean>`

Quick check if a user key is valid.

`getUserDevices(userKey)` → `Promise<string[]>`

Get all registered devices for a user.

`notify(config, message)`

Standalone function — creates a client and sends in one call.

Serverless & Stateless Environments

⚠️ Important: The queue(), rateLimit, and retry features use in-memory state. In serverless environments (Vercel, AWS Lambda, Cloudflare Workers), each invocation runs in a fresh context — queued messages may be lost, rate-limit counters will reset per invocation, and retry state won't persist across calls.

Recommendation: In serverless, use send() directly (it's stateless) and rely on response.limits for quota tracking. Queue and rate limiting are designed for long-lived Node.js/Bun servers.

Requirements

Node.js >= 18.0.0 (native fetch)
Bun >= 1.0.0

License

MIT - Mustafa Kurt

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

@mustafakurtt/pushover

Why This Package?

Installation

Quick Start

Usage

One-Liner (No Client Needed)

Fluent Builder (Method Chaining)

Message Queue (Batch Sending)

Rate Limiting

Auto-Retry with Exponential Backoff

Check Monthly Limits

Multi-Device Targeting

Device Groups

Template Messages

Conditional Sending (Time-Based)

Image Attachments

Response Limits (Zero-Cost)

Delivery Groups (Multi-User)

Receipt Tracking (Emergency)

User Validation

Default Config

Semantic Methods with Options

Error Handling

Semantic Methods

API Reference

createPushover(config) / new PushoverClient(config)

send(message)

message(text) → MessageBuilder

template(name, text)

sendToDevices(message, devices)

sendToGroup(message, groupName)

queue(message) / flush()

limits()

group(groupKey) → GroupManager

receipt(receiptId) → ReceiptTracker

validateUser(userKey, device?)

isValidUser(userKey) → Promise<boolean>

getUserDevices(userKey) → Promise<string[]>

notify(config, message)

Serverless & Stateless Environments

Requirements

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`createPushover(config)` / `new PushoverClient(config)`

`send(message)`

`message(text)` → `MessageBuilder`

`template(name, text)`

`sendToDevices(message, devices)`

`sendToGroup(message, groupName)`

`queue(message)` / `flush()`

`limits()`

`group(groupKey)` → `GroupManager`

`receipt(receiptId)` → `ReceiptTracker`

`validateUser(userKey, device?)`

`isValidUser(userKey)` → `Promise<boolean>`

`getUserDevices(userKey)` → `Promise<string[]>`

`notify(config, message)`

Packages