@lastshotlabs/slingshot-notifications
npm install @lastshotlabs/slingshot-notifications
Functions
Section titled “Functions”createIntervalDispatcher
Section titled “createIntervalDispatcher”Control surface for the notification dispatcher, providing start/stop lifecycle and per-tick dispatch execution.
function createIntervalDispatcher(options: CreateIntervalDispatcherOptions,): DispatcherAdapterSource: packages/slingshot-notifications/src/dispatcher.ts
createNotificationBuilder
Section titled “createNotificationBuilder”Notification source identifier (e.g. “community”, “push”). Used for preference resolution and rate-limit scoping.
function createNotificationBuilder(options: CreateNotificationBuilderOptions,): NotificationBuilderSource: packages/slingshot-notifications/src/builder.ts
createNotificationsPackage
Section titled “createNotificationsPackage”Filter list responses by notificationTtlMs so expired rows don’t appear
to clients before the periodic sweep deletes them. P-NOTIF-8.
function createNotificationsPackage(rawConfig: Partial<NotificationsPluginConfig> = {},): SlingshotPackageDefinitionSource: packages/slingshot-notifications/src/plugin.ts
freezeNotificationData
Section titled “freezeNotificationData”Error thrown when notification data exceeds the size cap.
function freezeNotificationData(data: Readonly<Record<string, unknown>>,): Readonly<Record<string, unknown>>Source: packages/slingshot-notifications/src/data.ts
isWithinQuietHours
Section titled “isWithinQuietHours”Resolve the effective notification preference chain for one recipient.
function isWithinQuietHours(prefs: ResolvedPreference, now: Date): booleanSource: packages/slingshot-notifications/src/preferences.ts
Notification
Section titled “Notification”Safely parse a row’s data column. Tolerates the four shapes we see across
backends (and one we should not see, but might if the row is corrupt):
- already-parsed object (memory, mongo, postgres jsonb) -> returned as-is
- JSON-encoded string (sqlite, legacy postgres rows) -> parsed
- null/undefined -> undefined
- corrupt JSON string -> undefined + throttled warn
- JSON array (data column is supposed to hold a plain object) -> undefined
The data column should never be present as anything other than an object,
so we explicitly reject arrays and primitive parse results.
Source: packages/slingshot-notifications/src/entities/notification.ts
notificationOperations
Section titled “notificationOperations”Safely parse a row’s data column. Tolerates the four shapes we see across
backends (and one we should not see, but might if the row is corrupt):
- already-parsed object (memory, mongo, postgres jsonb) -> returned as-is
- JSON-encoded string (sqlite, legacy postgres rows) -> parsed
- null/undefined -> undefined
- corrupt JSON string -> undefined + throttled warn
- JSON array (data column is supposed to hold a plain object) -> undefined
The data column should never be present as anything other than an object,
so we explicitly reject arrays and primitive parse results.
Source: packages/slingshot-notifications/src/entities/notification.ts
NotificationPreference
Section titled “NotificationPreference”Notification preference entity.
Source: packages/slingshot-notifications/src/entities/preference.ts
notificationPreferenceOperations
Section titled “notificationPreferenceOperations”Notification preference entity.
Source: packages/slingshot-notifications/src/entities/preference.ts
Notifications
Section titled “Notifications”Public contract for slingshot-notifications.
Other packages and plugins consume this surface through typed capability handles
instead of reaching into NOTIFICATIONS_PLUGIN_STATE_KEY directly. The plugin
publishes implementations during setupPost via registerPluginCapabilities;
consumers fetch them through ctx.capabilities.require(...) or
services.capabilities.require(...) (in out-of-request hooks).
Legacy state-key access (getNotificationsStateOrNull) remains supported for
backward compatibility, but new code should consume the contract.
Source: packages/slingshot-notifications/src/public.ts
NotificationsBuilderFactoryCap
Section titled “NotificationsBuilderFactoryCap”Public contract for slingshot-notifications.
Other packages and plugins consume this surface through typed capability handles
instead of reaching into NOTIFICATIONS_PLUGIN_STATE_KEY directly. The plugin
publishes implementations during setupPost via registerPluginCapabilities;
consumers fetch them through ctx.capabilities.require(...) or
services.capabilities.require(...) (in out-of-request hooks).
Legacy state-key access (getNotificationsStateOrNull) remains supported for
backward compatibility, but new code should consume the contract.
Source: packages/slingshot-notifications/src/public.ts
NotificationsDeliveryRegistryCap
Section titled “NotificationsDeliveryRegistryCap”Public contract for slingshot-notifications.
Other packages and plugins consume this surface through typed capability handles
instead of reaching into NOTIFICATIONS_PLUGIN_STATE_KEY directly. The plugin
publishes implementations during setupPost via registerPluginCapabilities;
consumers fetch them through ctx.capabilities.require(...) or
services.capabilities.require(...) (in out-of-request hooks).
Legacy state-key access (getNotificationsStateOrNull) remains supported for
backward compatibility, but new code should consume the contract.
Source: packages/slingshot-notifications/src/public.ts
NotificationsHealthCap
Section titled “NotificationsHealthCap”Public contract for slingshot-notifications.
Other packages and plugins consume this surface through typed capability handles
instead of reaching into NOTIFICATIONS_PLUGIN_STATE_KEY directly. The plugin
publishes implementations during setupPost via registerPluginCapabilities;
consumers fetch them through ctx.capabilities.require(...) or
services.capabilities.require(...) (in out-of-request hooks).
Legacy state-key access (getNotificationsStateOrNull) remains supported for
backward compatibility, but new code should consume the contract.
Source: packages/slingshot-notifications/src/public.ts
notificationsPluginConfigSchema
Section titled “notificationsPluginConfigSchema”Runtime schema for validating notifications plugin configuration.
Config Fields
Section titled “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. |
sseEnabled | Whether the notification SSE stream is mounted. Default: true. |
Source: packages/slingshot-notifications/src/types/config.ts
resolveEffectivePriority
Section titled “resolveEffectivePriority”Resolve the effective notification preference chain for one recipient.
function resolveEffectivePriority(priority: NotificationPriority, prefs: ResolvedPreference, now: Date,): NotificationPrioritySource: packages/slingshot-notifications/src/preferences.ts
resolvePreferences
Section titled “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
Section titled “Constants”notificationFactories
Section titled “notificationFactories”Entity runtime factories (adapter, router, routes) for the Notification entity.
Source: packages/slingshot-notifications/src/entities/factories.ts
notificationPreferenceFactories
Section titled “notificationPreferenceFactories”Entity runtime factories (adapter, router, routes) for the Notification entity.
Source: packages/slingshot-notifications/src/entities/factories.ts
Classes
Section titled “Classes”NotificationDataTooLargeError
Section titled “NotificationDataTooLargeError”Error thrown when notification data exceeds the size cap.
Source: packages/slingshot-notifications/src/data.ts
NotificationDeliveryError
Section titled “NotificationDeliveryError”Errors thrown by the notifications plugin.
Source: packages/slingshot-notifications/src/errors.ts
NotificationDispatchTimeoutError
Section titled “NotificationDispatchTimeoutError”Errors thrown by the notifications plugin.
Source: packages/slingshot-notifications/src/errors.ts
NotificationRateLimitExceededError
Section titled “NotificationRateLimitExceededError”Errors thrown by the notifications plugin.
Source: packages/slingshot-notifications/src/errors.ts
Interfaces
Section titled “Interfaces”CreateIntervalDispatcherOptions
Section titled “CreateIntervalDispatcherOptions”Control surface for the notification dispatcher, providing start/stop lifecycle and per-tick dispatch execution.
Source: packages/slingshot-notifications/src/dispatcher.ts
DeadLetterEvent
Section titled “DeadLetterEvent”Control surface for the notification dispatcher, providing start/stop lifecycle and per-tick dispatch execution.
Source: packages/slingshot-notifications/src/dispatcher.ts
DispatcherAdapter
Section titled “DispatcherAdapter”Control surface for the notification dispatcher, providing start/stop lifecycle and per-tick dispatch execution.
Source: packages/slingshot-notifications/src/dispatcher.ts
DispatcherBreakerOptions
Section titled “DispatcherBreakerOptions”Control surface for the notification dispatcher, providing start/stop lifecycle and per-tick dispatch execution.
Source: packages/slingshot-notifications/src/dispatcher.ts
DispatcherRetryOptions
Section titled “DispatcherRetryOptions”Control surface for the notification dispatcher, providing start/stop lifecycle and per-tick dispatch execution.
Source: packages/slingshot-notifications/src/dispatcher.ts
NotificationAdapter
Section titled “NotificationAdapter”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
NotificationBuilder
Section titled “NotificationBuilder”Shared notification record / adapter / builder types used across packages.
These types form the typed surface that slingshot-notifications publishes through
its Notifications package contract (@lastshotlabs/slingshot-notifications/public.ts).
Cross-package consumers resolve the contract handles via ctx.capabilities.require(...)
— the legacy NOTIFICATIONS_PLUGIN_STATE_KEY peer-state publish has been removed.
Source: packages/slingshot-core/src/notificationsPeer.ts
NotificationPreferenceAdapter
Section titled “NotificationPreferenceAdapter”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
NotificationPreferenceRecord
Section titled “NotificationPreferenceRecord”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
NotificationsDeliveryRegistry
Section titled “NotificationsDeliveryRegistry”Public contract for slingshot-notifications.
Other packages and plugins consume this surface through typed capability handles
instead of reaching into NOTIFICATIONS_PLUGIN_STATE_KEY directly. The plugin
publishes implementations during setupPost via registerPluginCapabilities;
consumers fetch them through ctx.capabilities.require(...) or
services.capabilities.require(...) (in out-of-request hooks).
Legacy state-key access (getNotificationsStateOrNull) remains supported for
backward compatibility, but new code should consume the contract.
Source: packages/slingshot-notifications/src/public.ts
NotificationsHealth
Section titled “NotificationsHealth”Public contract for slingshot-notifications.
Other packages and plugins consume this surface through typed capability handles
instead of reaching into NOTIFICATIONS_PLUGIN_STATE_KEY directly. The plugin
publishes implementations during setupPost via registerPluginCapabilities;
consumers fetch them through ctx.capabilities.require(...) or
services.capabilities.require(...) (in out-of-request hooks).
Legacy state-key access (getNotificationsStateOrNull) remains supported for
backward compatibility, but new code should consume the contract.
Source: packages/slingshot-notifications/src/public.ts
DeliveryAdapter
Section titled “DeliveryAdapter”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
NotificationCreatedEventPayload
Section titled “NotificationCreatedEventPayload”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
NotificationPriority
Section titled “NotificationPriority”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
NotificationRecord
Section titled “NotificationRecord”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
NotificationsPluginConfig
Section titled “NotificationsPluginConfig”Runtime schema for validating notifications plugin configuration.
Source: packages/slingshot-notifications/src/types/config.ts
NotifyInput
Section titled “NotifyInput”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
NotifyManyInput
Section titled “NotifyManyInput”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts
ResolvedPreference
Section titled “ResolvedPreference”Persisted notification preference record controlling per-user, per-source, or per-type delivery channel settings.
Source: packages/slingshot-notifications/src/types.ts