@lastshotlabs/slingshot-notifications

npm install @lastshotlabs/slingshot-notifications

Functions

`createIntervalDispatcher`

Create the default polling dispatcher for scheduled notifications.

Remarks: The dispatcher publishes scheduled notifications to the event bus. When a publish call throws (provider failure), the dispatcher retries with exponential backoff up to retry.maxAttempts, clamping each delay to retry.maxDelayMs (mirrors the push router’s clamp). Consecutive failures to the same destination (row.userId) trip a circuit breaker — once breaker.threshold consecutive failures accumulate, further sends to that destination are short-circuited (the row is rolled back to undispatched and skipped) until breaker.cooldownMs elapses. A successful publish resets the breaker for that destination.

function createIntervalDispatcher(options: CreateIntervalDispatcherOptions,): DispatcherAdapter

Source: packages/slingshot-notifications/src/dispatcher.ts

`createNotificationBuilder`

Create a source-scoped notification builder.

The returned builder provides a fluent API for creating, scheduling, and managing notifications within a single source scope. All methods automatically resolve user preferences, enforce rate limits, and handle dedup key collision.

function createNotificationBuilder(options: CreateNotificationBuilderOptions,): NotificationBuilder

Source: packages/slingshot-notifications/src/builder.ts

`createNotificationsPackage`

Create the shared notifications package.

Two entity modules (Notification, NotificationPreference) flow through the declarative package entity-mounting path; imperative work (event registration, SSE route, dispatcher startup, capability publication, TTL sweep) lives in setupMiddleware / setupRoutes / setupPost.

Health observability is exposed through the NotificationsHealthCap capability — cross-package consumers resolve it via ctx.capabilities.require(NotificationsHealthCap)().

function createNotificationsPackage(rawConfig: Partial<NotificationsPluginConfig> = {},): SlingshotPackageDefinition

Source: packages/slingshot-notifications/src/plugin.ts

`freezeNotificationData`

Freeze notification data after validating its JSON size.

function freezeNotificationData(data: Readonly<Record<string, unknown>>,): Readonly<Record<string, unknown>>

Source: packages/slingshot-notifications/src/data.ts

`isWithinQuietHours`

Returns whether the current time falls within quiet hours.

function isWithinQuietHours(prefs: ResolvedPreference, now: Date): boolean

Source: packages/slingshot-notifications/src/preferences.ts

`Notification`

Shared notification entity.

Source: packages/slingshot-notifications/src/entities/notification.ts

`notificationOperations`

Notification named operations.

Source: packages/slingshot-notifications/src/entities/notification.ts

`NotificationPreference`

Notification preference entity.

Source: packages/slingshot-notifications/src/entities/preference.ts

`notificationPreferenceOperations`

Notification preference lookups and delivery-resolution operations.

Source: packages/slingshot-notifications/src/entities/preference.ts

`Notifications`

Provider-owned contract for slingshot-notifications.

Source: packages/slingshot-notifications/src/public.ts

`NotificationsBuilderFactoryCap`

Capability for creating source-scoped notification builders.

Consumers do ctx.capabilities.require(NotificationsBuilderFactoryCap)({ source: 'my-plugin' }) to get a builder bound to their plugin name. Each builder publishes notifications, resolves preferences, and applies rate limits on behalf of the calling source.

Source: packages/slingshot-notifications/src/public.ts

`NotificationsDeliveryRegistryCap`

Capability for registering a delivery adapter. Consumers resolve through ctx.capabilities.require(NotificationsDeliveryRegistryCap) and call register(adapter) once per dispatch sink.

Source: packages/slingshot-notifications/src/public.ts

`NotificationsHealthCap`

Capability for reading the aggregated notifications health snapshot.

Consumers resolve via ctx.capabilities.require(NotificationsHealthCap)() and receive a frozen NotificationsHealth representing adapter, delivery, rate-limit, and dispatcher state at call time.

Source: packages/slingshot-notifications/src/public.ts

`notificationsPluginConfigSchema`

Runtime schema for validating notifications plugin configuration.

Config Fields

Field	Description
`defaultPreferences`	Default in-app notification preference for new subscriptions. Default: true.
`dispatcher`	Maximum queued notifications processed per dispatcher tick. Default: 500.
`rateLimit`	Backend used to track notification rate limits. Default: memory.
`reliability`	Stable transactional inbox consumer identity.
`sseEnabled`	Whether the notification SSE stream is mounted. Default: true.

Source: packages/slingshot-notifications/src/types/config.ts

`resolveEffectivePriority`

Downgrade standard-priority notifications during quiet hours.

function resolveEffectivePriority(priority: NotificationPriority, prefs: ResolvedPreference, now: Date,): NotificationPriority

Source: packages/slingshot-notifications/src/preferences.ts

`resolvePreferences`

Resolve the effective notification preference chain for one recipient.

async function resolvePreferences(adapter: NotificationPreferenceAdapter, userId: string, source: string, type: string, defaults: NotificationPreferenceDefaults = DEFAULT_NOTIFICATION_PREFERENCE_DEFAULTS,): Promise<ResolvedPreference>

Source: packages/slingshot-notifications/src/preferences.ts

Constants

`notificationFactories`

Entity runtime factories (adapter, router, routes) for the Notification entity.

Source: packages/slingshot-notifications/src/entities/factories.ts

`notificationPreferenceFactories`

Entity runtime factories (adapter, router, routes) for the NotificationPreference entity.

Source: packages/slingshot-notifications/src/entities/factories.ts

Classes

`NotificationDataTooLargeError`

Error thrown when notification data exceeds the size cap.

Source: packages/slingshot-notifications/src/data.ts

`NotificationDeliveryError`

Error thrown when a notification delivery attempt fails after exhausting all retry attempts (e.g., the downstream provider rejected the event).

Source: packages/slingshot-notifications/src/errors.ts

`NotificationDispatchTimeoutError`

Error thrown when a notification dispatch tick exceeds its time budget and is aborted before all rows could be processed.

Source: packages/slingshot-notifications/src/errors.ts

`NotificationRateLimitExceededError`

Error thrown when a per-source, per-user rate limit is exceeded during a notify call, and the calling code opts into throwing rather than silently dropping the notification.

Source: packages/slingshot-notifications/src/errors.ts

Interfaces

`CreateIntervalDispatcherOptions`

Options for createIntervalDispatcher, including adapters, bus, polling intervals, retry/breaker tuning, and observability hooks.

Source: packages/slingshot-notifications/src/dispatcher.ts

`DeadLetterEvent`

Payload delivered to the CreateIntervalDispatcherOptions.onDeadLetter callback when a notification exhausts all retry attempts within a tick.

Source: packages/slingshot-notifications/src/dispatcher.ts

`DispatcherAdapter`

Control surface for the notification dispatcher, providing start/stop lifecycle and per-tick dispatch execution.

Source: packages/slingshot-notifications/src/dispatcher.ts

`DispatcherBreakerOptions`

Configuration for the per-destination circuit breaker that short-circuits delivery after consecutive failures.

Source: packages/slingshot-notifications/src/dispatcher.ts

`DispatcherRetryOptions`

Configuration for exponential-backoff retries on per-notification publish failures.

Source: packages/slingshot-notifications/src/dispatcher.ts

`NotificationAdapter`

Persistence adapter for notification records and dispatch state.

Source: packages/slingshot-notifications/src/types.ts

`NotificationBuilder`

Builder contract published by slingshot-notifications to peer plugins.

Source: packages/slingshot-core/src/notificationsPeer.ts

`NotificationPreferenceAdapter`

Persistence adapter for per-user notification preference records.

Source: packages/slingshot-notifications/src/types.ts

`NotificationPreferenceRecord`

Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.

Source: packages/slingshot-notifications/src/types.ts

`NotificationsDeliveryRegistry`

Typed registry for delivery adapters published by sibling packages (slingshot-push, mailers, etc.). The notifications package invokes registered adapters via the in-process event bus when a notification is created and dispatched.

Source: packages/slingshot-notifications/src/public.ts

`NotificationsHealth`

Aggregated health snapshot for the notifications package.

Source: packages/slingshot-notifications/src/public.ts

Types

`DeliveryAdapter`

Peer-facing notification contracts re-exported from slingshot-core.

Source: packages/slingshot-notifications/src/types.ts

`NotificationCreatedEventPayload`

Peer-facing notification contracts re-exported from slingshot-core.

Source: packages/slingshot-notifications/src/types.ts

`NotificationPriority`

Peer-facing notification contracts re-exported from slingshot-core.

Source: packages/slingshot-notifications/src/types.ts

`NotificationRecord`

Peer-facing notification contracts re-exported from slingshot-core.

Source: packages/slingshot-notifications/src/types.ts

`NotificationsPluginConfig`

Resolved configuration object for the notifications plugin, inferred from notificationsPluginConfigSchema.

Source: packages/slingshot-notifications/src/types/config.ts

`NotifyInput`

Peer-facing notification contracts re-exported from slingshot-core.

Source: packages/slingshot-notifications/src/types.ts

`NotifyManyInput`

Peer-facing notification contracts re-exported from slingshot-core.

Source: packages/slingshot-notifications/src/types.ts

`ResolvedPreference`

Peer-facing notification contracts re-exported from slingshot-core.

Source: packages/slingshot-notifications/src/types.ts