@lastshotlabs/slingshot-push
npm install @lastshotlabs/slingshot-push
Functions
Section titled “Functions”buildProviderIdempotencyKey
Section titled “buildProviderIdempotencyKey”Build a deterministic provider idempotency key for a given delivery attempt.
The same (deliveryId, attempt) pair always produces the same string. Pass this
value to upstream provider APIs that accept an idempotency token so retries within
the same attempt do not produce duplicate sends.
function buildProviderIdempotencyKey(deliveryId: string, attempt: number): stringSource: packages/slingshot-push/src/lib/idempotency.ts
compilePushFormatters
Section titled “compilePushFormatters”Compile declarative formatter templates into a runtime formatter table.
function compilePushFormatters(templates: Partial<Record<string, PushFormatterTemplate>> = {},): CompiledPushFormatterTableSource: packages/slingshot-push/src/formatter.ts
createPushDeliveryAdapter
Section titled “createPushDeliveryAdapter”Create a notifications delivery adapter backed by the push router.
function createPushDeliveryAdapter(opts: { router: PushRouter; formatters: CompiledPushFormatterTable; skipSources?: string[]; defaults?: NotificationDefaults; /** * Per-call override forwarded into `router.sendToUser`. When omitted, the * router falls back to its construction-time default. */ providerTimeoutMs?: number; }): DeliveryAdapterSource: packages/slingshot-push/src/deliveryAdapter.ts
createPushPackage
Section titled “createPushPackage”Create the multi-provider push package.
Validates rawConfig via pushPluginConfigSchema, mounts the four push
entities (subscriptions, topics, topic memberships, deliveries) through the
declarative package authoring path, wires Web Push / APNS / FCM providers,
mounts the bespoke topic-subscribe / unsubscribe / ack routes, and registers
a delivery adapter with slingshot-notifications when present.
Cross-package consumers resolve the runtime via PushRuntimeCap and the
aggregated health snapshot via PushHealthCap.
function createPushPackage(rawConfig: PushPluginConfig): SlingshotPackageDefinitionSource: packages/slingshot-push/src/plugin.ts
createPushRouter
Section titled “createPushRouter”Cancellable sleep used by router retry backoff. When signal is provided
and aborted, the sleep rejects immediately with an 'aborted' error so the
outer retry loop can unwind and stop spawning further attempts. Without
cancellation, in-flight sleeps would tick through stop() and continue
touching repositories long after teardown began. P-PUSH-6.
function createPushRouter(options: { providers: Readonly<Partial<Record<PushPlatform, PushProvider>>>; repos: PushRouterRepos; retries?: { maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number }; bus?: DynamicBus; /** Maximum milliseconds for a single provider.send() call before it is treated as transient failure. Default: 30000. */ providerTimeoutMs?: number; /** Subscriptions per topic-fan-out batch. Default: 1000. */ topicFanoutBatchSize?: number; /** Max concurrent in-flight batches before back-pressure kicks in. Default: 10. */ topicFanoutMaxPending?: number; /** * Optional metrics sink. When provided, the router records per-send * counters/timings, topic fan-out counters, subscription-cleanup counters, * and per-provider circuit-breaker / consecutive-failure gauges so * operators can wire ad-hoc dashboards without parsing logs. Defaults to * a no-op emitter. */ metrics?: MetricsEmitter; /** * Maximum subscriptions that may receive a single topic publish before the * router emits `push:topic.fanout.truncated`, returns a partial result, and * stops scheduling further batches. Default: 10000. P-PUSH-11. */ topicMaxRecipients?: number; /** * Router-level circuit breaker threshold — consecutive total-fan-out * failures (every subscription in a sendToUser/sendToUsers/publishTopic * returned allFailed) before the breaker opens and short-circuits * subsequent sends. Default: 10. Set to 0 to disable the router-level * breaker. */ routerCircuitBreakerThreshold?: number; /** * Router-level circuit breaker cooldown in ms before admitting a * half-open probe after the breaker opens. Default: 30000. */ routerCircuitBreakerCooldownMs?: number; }): PushRouterSource: packages/slingshot-push/src/router.ts
deriveUuidV4FromKey
Section titled “deriveUuidV4FromKey”Build a deterministic provider idempotency key for a given delivery attempt.
The same (deliveryId, attempt) pair always produces the same string. Pass this
value to upstream provider APIs that accept an idempotency token so retries within
the same attempt do not produce duplicate sends.
function deriveUuidV4FromKey(key: string): stringSource: packages/slingshot-push/src/lib/idempotency.ts
Public contract for slingshot-push.
Cross-package consumers (notably slingshot-chat for formatter registration) resolve
PushRuntimeCap through ctx.capabilities.require(...).
Source: packages/slingshot-push/src/public.ts
PushHealthCap
Section titled “PushHealthCap”Public contract for slingshot-push.
Cross-package consumers (notably slingshot-chat for formatter registration) resolve
PushRuntimeCap through ctx.capabilities.require(...).
Source: packages/slingshot-push/src/public.ts
pushPluginConfigSchema
Section titled “pushPluginConfigSchema”Imperative formatter escape hatch used after config compilation.
Config Fields
Section titled “Config Fields”| Field | Description |
|---|---|
android | Service-account private key used to authenticate with Firebase. |
enabledPlatforms | Platforms this plugin should deliver to. One or more of: web, ios, android. |
ios | Default iOS app bundle identifier used when a notification does not provide one. Omit to require bundle IDs per target.’, ), defaultEnvironment: z .enum([‘sandbox’, ‘production’]) .optional() .describe( ‘Default APNS environment. One of: sandbox, production. Omit to use the provider default.’, ), }) .optional() .describe(‘iOS push configuration for APNS delivery. Omit when iOS push is not enabled. |
notifications | Default notification icon URL. Omit to send no default icon. |
web | Web push configuration for browser clients. Omit when web push is not enabled. |
Source: packages/slingshot-push/src/types/config.ts
PushRuntimeCap
Section titled “PushRuntimeCap”Public contract for slingshot-push.
Cross-package consumers (notably slingshot-chat for formatter registration) resolve
PushRuntimeCap through ctx.capabilities.require(...).
Source: packages/slingshot-push/src/public.ts
Constants
Section titled “Constants”PushDeliveryEntity
Section titled “PushDeliveryEntity”Entity definition for one delivery attempt against one subscription.
Source: packages/slingshot-push/src/entities/pushDelivery.ts
pushDeliveryFactories
Section titled “pushDeliveryFactories”Store-type keyed factories for PushSubscription.
Source: packages/slingshot-push/src/entities/factories.ts
pushDeliveryOperations
Section titled “pushDeliveryOperations”Entity definition for one delivery attempt against one subscription.
Source: packages/slingshot-push/src/entities/pushDelivery.ts
PushFormatterRegistryCap
Section titled “PushFormatterRegistryCap”Public contract for slingshot-push.
Cross-package consumers (notably slingshot-chat for formatter registration) resolve
PushRuntimeCap through ctx.capabilities.require(...).
Source: packages/slingshot-push/src/public.ts
PushSubscriptionEntity
Section titled “PushSubscriptionEntity”Entity definition for persisted device subscriptions across all platforms.
Source: packages/slingshot-push/src/entities/pushSubscription.ts
pushSubscriptionFactories
Section titled “pushSubscriptionFactories”Store-type keyed factories for PushSubscription.
Source: packages/slingshot-push/src/entities/factories.ts
pushSubscriptionOperations
Section titled “pushSubscriptionOperations”Entity definition for persisted device subscriptions across all platforms.
Source: packages/slingshot-push/src/entities/pushSubscription.ts
PushTopicEntity
Section titled “PushTopicEntity”Entity definition for named push topics.
Source: packages/slingshot-push/src/entities/pushTopic.ts
pushTopicFactories
Section titled “pushTopicFactories”Store-type keyed factories for PushSubscription.
Source: packages/slingshot-push/src/entities/factories.ts
PushTopicMembershipEntity
Section titled “PushTopicMembershipEntity”Entity definition linking subscriptions to topics.
Source: packages/slingshot-push/src/entities/pushTopicMembership.ts
pushTopicMembershipFactories
Section titled “pushTopicMembershipFactories”Store-type keyed factories for PushSubscription.
Source: packages/slingshot-push/src/entities/factories.ts
pushTopicMembershipOperations
Section titled “pushTopicMembershipOperations”Entity definition linking subscriptions to topics.
Source: packages/slingshot-push/src/entities/pushTopicMembership.ts
pushTopicOperations
Section titled “pushTopicOperations”Entity definition for named push topics.
Source: packages/slingshot-push/src/entities/pushTopic.ts
Classes
Section titled “Classes”ApnsDeliveryError
Section titled “ApnsDeliveryError”Errors thrown by the push notification plugin.
Source: packages/slingshot-push/src/errors.ts
FcmTokenError
Section titled “FcmTokenError”Default consecutive token-fetch failures before classifying further attempts
as permanent. Prevents infinite retry loops when service-account credentials
are invalid or the FCM project is misconfigured.
Source: packages/slingshot-push/src/providers/fcm.ts
PushRouterError
Section titled “PushRouterError”Errors thrown by the push notification plugin.
Source: packages/slingshot-push/src/errors.ts
PushTopicFanoutError
Section titled “PushTopicFanoutError”Errors thrown by the push notification plugin.
Source: packages/slingshot-push/src/errors.ts
WebPushDeliveryError
Section titled “WebPushDeliveryError”Errors thrown by the push notification plugin.
Source: packages/slingshot-push/src/errors.ts
Interfaces
Section titled “Interfaces”CompiledPushFormatterTable
Section titled “CompiledPushFormatterTable”Compiled formatter registry used by the push delivery adapter.
Source: packages/slingshot-push/src/state.ts
FirebaseServiceAccount
Section titled “FirebaseServiceAccount”Imperative formatter escape hatch used after config compilation.
Source: packages/slingshot-push/src/types/config.ts
NotificationDefaults
Section titled “NotificationDefaults”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
PushDelivery
Section titled “PushDelivery”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
PushFormatterRegistry
Section titled “PushFormatterRegistry”Public contract for slingshot-push.
Cross-package consumers (notably slingshot-chat for formatter registration) resolve
PushRuntimeCap through ctx.capabilities.require(...).
Source: packages/slingshot-push/src/public.ts
PushFormatterTemplate
Section titled “PushFormatterTemplate”Imperative formatter escape hatch used after config compilation.
Source: packages/slingshot-push/src/types/config.ts
PushMessage
Section titled “PushMessage”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
PushPluginHealth
Section titled “PushPluginHealth”Public contract for slingshot-push.
Cross-package consumers (notably slingshot-chat for formatter registration) resolve
PushRuntimeCap through ctx.capabilities.require(...).
Source: packages/slingshot-push/src/public.ts
PushPluginState
Section titled “PushPluginState”Compiled formatter registry used by the push delivery adapter.
Source: packages/slingshot-push/src/state.ts
PushProvider
Section titled “PushProvider”Per-provider observability snapshot. Cross-package consumers should read the
aggregated push health via PushHealthCap; this provider-internal
getHealth() hook is what the package uses to populate that capability.
Implementations must keep this cheap (no I/O) — it is read from a health endpoint and may be polled.
Source: packages/slingshot-push/src/providers/provider.ts
PushProviderHealth
Section titled “PushProviderHealth”Per-provider observability snapshot. Cross-package consumers should read the
aggregated push health via PushHealthCap; this provider-internal
getHealth() hook is what the package uses to populate that capability.
Implementations must keep this cheap (no I/O) — it is read from a health endpoint and may be polled.
Source: packages/slingshot-push/src/providers/provider.ts
PushRouter
Section titled “PushRouter”Cancellable sleep used by router retry backoff. When signal is provided
and aborted, the sleep rejects immediately with an 'aborted' error so the
outer retry loop can unwind and stop spawning further attempts. Without
cancellation, in-flight sleeps would tick through stop() and continue
touching repositories long after teardown began. P-PUSH-6.
Source: packages/slingshot-push/src/router.ts
PushRouterRepos
Section titled “PushRouterRepos”Cancellable sleep used by router retry backoff. When signal is provided
and aborted, the sleep rejects immediately with an 'aborted' error so the
outer retry loop can unwind and stop spawning further attempts. Without
cancellation, in-flight sleeps would tick through stop() and continue
touching repositories long after teardown began. P-PUSH-6.
Source: packages/slingshot-push/src/router.ts
PushSendResult
Section titled “PushSendResult”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
PushSendResultSummary
Section titled “PushSendResultSummary”Cancellable sleep used by router retry backoff. When signal is provided
and aborted, the sleep rejects immediately with an 'aborted' error so the
outer retry loop can unwind and stop spawning further attempts. Without
cancellation, in-flight sleeps would tick through stop() and continue
touching repositories long after teardown began. P-PUSH-6.
Source: packages/slingshot-push/src/router.ts
PushSubscription
Section titled “PushSubscription”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
PushTopic
Section titled “PushTopic”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
PushTopicMembership
Section titled “PushTopicMembership”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
ApnsAuthInput
Section titled “ApnsAuthInput”Imperative formatter escape hatch used after config compilation.
Source: packages/slingshot-push/src/types/config.ts
PlatformData
Section titled “PlatformData”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
PushFormatterFn
Section titled “PushFormatterFn”Imperative formatter escape hatch used after config compilation.
Source: packages/slingshot-push/src/types/config.ts
PushPlatform
Section titled “PushPlatform”Supported push delivery platforms.
Source: packages/slingshot-push/src/types/models.ts
PushPluginConfig
Section titled “PushPluginConfig”Imperative formatter escape hatch used after config compilation.
Source: packages/slingshot-push/src/types/config.ts
PushRouteKey
Section titled “PushRouteKey”Imperative formatter escape hatch used after config compilation.
Source: packages/slingshot-push/src/types/config.ts