Skip to content
Slingshot

Overview

@lastshotlabs/slingshot-notifications is Slingshot’s shared notification package. It owns notification records, user notification preferences, dispatcher scheduling, rate limiting, preference resolution, and the builder/runtime surface that other packages use to enqueue or deliver notifications. The notification entities themselves follow the shared package-first/entity authoring model; createNotificationsPackage() is the runtime shell that wires storage, dispatch, and delivery.

When To Use It

Section titled “When To Use It”

Use this package when your app or plugin needs:

  • persisted notification records
  • user notification preferences and quiet-hours-aware resolution
  • queued notification dispatch with a polling loop
  • SSE delivery for the current user
  • a common notification builder that feature packages can share

This is the right dependency for chat, community, push, and other product packages that need a shared notification backbone instead of private per-feature notification tables.

What You Need Before Wiring It In

Section titled “What You Need Before Wiring It In”

The package declares slingshot-auth as a dependency. It expects the auth layer to be present before notification routes and user-scoped SSE behavior are used.

The config is intentionally easy to start with. createNotificationsPackage() accepts a partial config object and fills in defaults.

Minimum Setup

Section titled “Minimum Setup”

With no config, the package already gives you:

  • route mount path /notifications
  • SSE endpoint /notifications/sse
  • dispatcher enabled
  • dispatcher interval 30000
  • dispatcher max-per-tick 500
  • memory-backed rate limiting
  • default channel preferences of push, email, and in-app all enabled

The main knobs are:

  • mountPath
  • sseEnabled
  • ssePath
  • dispatcher
  • rateLimit
  • defaultPreferences

What You Get

Section titled “What You Get”

The package provides:

  • notification and notification-preference entities
  • adapters resolved for the active store backend
  • a notification builder surface created from package state
  • a dispatcher that can poll and deliver queued notifications
  • SSE routing for user-scoped notification streams
  • a registration point for delivery adapters

At runtime, the package publishes typed capabilities:

  • NotificationsBuilderFactoryCap — ({ source }) => NotificationBuilder for building source-scoped notification builders
  • NotificationsDeliveryRegistryCap — .register(adapter) for registering delivery adapters
  • NotificationsHealthCap — () => NotificationsHealth for the aggregated health snapshot
import type { HookServices } from '@lastshotlabs/slingshot-core';
import { NotificationsHealthCap } from '@lastshotlabs/slingshot-notifications';


function readNotificationsHealth(ctx: HookServices) {
  return ctx.capabilities.require(NotificationsHealthCap)();
}

Internal state remains published under NOTIFICATIONS_PLUGIN_STATE_KEY for legacy consumers, but new code should resolve the capabilities above.

Common Customization

Section titled “Common Customization”

The first files to read are:

  • src/plugin.ts for package lifecycle and runtime state
  • src/public.ts for the contract and capabilities
  • src/types/config.ts for defaults and configuration
  • src/builder.ts for builder behavior
  • src/dispatcher.ts for queue draining and delivery
  • src/preferences.ts for quiet hours and effective preference resolution

The highest-value changes are usually:

  • dispatcher cadence and throughput
  • default preference behavior
  • rate-limit backend and thresholds
  • delivery adapter registration

Gotchas

Section titled “Gotchas”
  • mountPath must start with /; trailing slashes are trimmed before routes are mounted.
  • Disabling the dispatcher does not remove notification persistence. It only stops the automatic polling loop that drains queued notifications.
  • Delivery adapters are opt-in. Persisted notifications exist without them, but external delivery will not happen until another package registers an adapter.
  • Package state is only complete after setup has resolved the entity adapters. If those adapters are missing, the package throws during setup instead of continuing in a half-wired state.
  • SSE can be disabled independently from storage and dispatch. Treat it as a delivery surface, not the whole notification system.

Key Files

Section titled “Key Files”
  • src/index.ts
  • src/plugin.ts
  • src/types/config.ts
  • src/builder.ts
  • src/dispatcher.ts
  • src/preferences.ts
  • src/sse.ts