Statocysts

December 26, 2025 · View on GitHub

English | 简体中文

Statocysts

A modern notification library for JavaScript — the sensory organ for your infrastructure.

NPM Version npm bundle size GitHub License

Features

  • URL-based addressing — select a provider and recipient with one notification target URL.
  • Parallel delivery — attempt every target concurrently.
  • Actionable failures — inspect each failed target through NotificationDeliveryError.
  • Provider-specific options — configure timeouts, API bases, and request payloads.
  • Node.js and browser entries — import only providers supported by your runtime.
  • Command-line interface — send and verify targets with stato.

Install

pnpm add statocysts

Quick start

import { send } from 'statocysts'

await send('slack://webhook/T00000000/B00000000/WEBHOOK_TOKEN', {
  title: 'Deployment complete',
  body: 'Production is healthy.',
})

Reuse a notifier for multiple targets:

import { createNotifier } from 'statocysts'

const notifier = createNotifier([
  process.env.SLACK_TARGET!,
  process.env.TELEGRAM_TARGET!,
])

await notifier.send({ title: 'Service recovered' })

All targets are attempted. If any delivery fails, the promise rejects with NotificationDeliveryError after the complete batch settles.

Browser

import { send } from 'statocysts/browser'

The browser entry includes every provider except email. Remote services must allow browser-origin requests, and privileged target credentials should stay on your server.

CLI

pnpm add --global @statocysts/cli

stato -u "$NOTIFICATION_TARGET" -t "Deployment complete"
stato verify -u "$NOTIFICATION_TARGET"

verify checks the target URL and provider-specific format locally. It does not send a notification or confirm remote credentials, recipients, or connectivity.

Providers

Slack, Discord, Lark/Feishu, QQ Bot, Telegram, Bark, Server Chan, email, HTTP/HTTPS JSON endpoints, and local console logging are included.

Notification target URLs often contain credentials. Keep them in environment variables or secret stores and redact them from logs.

Documentation

Read the full documentation at octoplorer.github.io/statocysts:

License

MIT