Notification SDK Documentation

The lightweight JavaScript client for sending Sparkstrand notifications from backend jobs, scripts, and services without pulling in the larger framework packages.

Installation

npm install @sparkstrand/notifications-sdk

Usage

import { createNotificationClient } from '@sparkstrand/notifications-sdk';

const client = createNotificationClient({
  baseUrl: process.env.NOTIFICATIONS_API_URL,
  appId: process.env.NOTIFICATIONS_APP_ID,
  apiKey: process.env.NOTIFICATIONS_API_KEY,
});

await client.sendSlack({
  title: 'Build Ready',
  message: 'Preview deployment is available.',
  recipients: [{ email: 'dev@sparkstrand.com', slackId: 'U123', name: 'Dev' }],
  slack: { channel: '#taxdone_notifications' },
  metadata: { source: 'ci.preview' },
});

This SDK wraps the direct send endpoints. It is intended for backend jobs, services, and scripts, not for authenticating an end user into the in-app notification center.

For direct sends, keep using an email-backed recipient whenever possible. If you are targeting Slack, pass the Slack identity inside recipient preferences or helper fields, but do not assume every consumer only uses email-backed resolution.

You can optionally pass slack.channel to target a shared Slack channel. If omitted, direct Slack sends fall back to the recipient Slack ID.

Capabilities

  • • Send notifications with a single shared client.
  • • Target multiple recipients in one call.
  • • Use channel-specific helpers like `sendSlack` and `sendEmail`.
  • • Pass metadata, email content, and Slack payload details through to the API.
  • • Safe no-op behavior when required config or recipients are missing.

Configuration

  • • `baseUrl`: Base URL for the notifications API.
  • • `appId`: The Sparkstrand application identifier.
  • • `apiKey`: Optional bearer token for authenticated sends.