JavaScript and TypeScript Alerts SDK

The API Alerts JavaScript SDK sends alerts from your JavaScript or TypeScript code through API Alerts. Drop it into Node.js, React, Next.js, Bun, or any JavaScript runtime that needs to notify you when something important happens. Minimal setup, fire-and-forget by default with optional response handling, and zero infrastructure.

Installation

The npm package was renamed from apialerts-js to apialerts. The old package is deprecated and will not receive 2.0 routing fields or further updates. Switch from apialerts-js to apialerts and update your imports to import { ApiAlerts } from 'apialerts'.

The rename tidies up the @apialerts/* namespace as the new @apialerts/cli package launches, and drops the accidental -js suffix that should never have been there.

npm install apialerts

Usage

import { ApiAlerts } from 'apialerts'

ApiAlerts.configure('YOUR-API-KEY')

// Simple notification
ApiAlerts.send({ message: 'Deployment successful' })

// With routing (recommended for production)
ApiAlerts.send({ event: 'ci.deploy.success', message: 'Deployment successful' })

// With all options
ApiAlerts.send({
  event: 'user.signup',
  message: 'New user signed up',
  channel: 'developers',
  title: 'New Signup',
  tags: ['signup', 'organic'],
  link: 'https://dashboard.example.com/users/123',
  data: { plan: 'pro', region: 'us-east-1' },
})

Event fields

Field	Type	Required	Description
`message`	`string`	Yes	Human-readable notification text. This is what appears on the push notification lock screen.
`channel`	`string`	No	Workspace channel the push notification fires on. Defaults to the workspace default channel when omitted.
`event`	`string`	No	What kind of thing happened. Optional but recommended. Routers match this value with Unix glob (fnmatch): dotted keys like `ci.deploy.success` match `ci.`, and free-form keys like `User Signup` match `User `. Dotted notation is just a tidy convention, not a requirement.
`title`	`string`	No	Short headline some destinations render separately from the message body.
`tags`	`string[]`	No	Categorisation tags for filtering and search.
`link`	`string`	No	URL associated with the event. Available as a deeplink for push notifications and as a call-to-action for routed destinations.
`data`	`Record<string, unknown>`	No	Arbitrary key-value metadata. Available to non-push destinations for templating (Slack message bodies, email templates, webhook payloads).

Optional fields are omitted from the request body when undefined - they’re never sent as null.

Wait for the response

send is fire-and-forget and never throws. For a result you can inspect, use sendAsync. It never throws either - check result.success.

const result = await ApiAlerts.sendAsync({ message: 'Deployment successful' })
if (!result.success) {
  console.error(result.error)
} else {
  console.log(`Sent to ${result.workspace} (${result.channel})`)
}

The SendResult shape:

interface SendResult {
  success: boolean
  workspace?: string  // populated on success
  channel?: string    // populated on success
  warnings: string[]  // non-fatal server warnings
  error?: string      // populated on failure
}

Send to multiple workspaces

Pass an apiKey as the optional second argument to override the configured key for a single call.

ApiAlerts.send({ message: 'Deploy complete' }, 'other-workspace-api-key')

Debug logging

Pass true as the second argument to configure to log success, warning, and error events to the console.

ApiAlerts.configure('YOUR-API-KEY', true)

Resources

GitHub Repository Full documentation, examples, and source code.