@voltro/plugin-notifications 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,322 @@
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Schema } from 'effect';
+import { VoltroPlugin } from '@voltro/protocol';
+
+export declare interface BroadcastResult {
+    /** How many topic subscribers the broadcast fanned out to. */
+    readonly recipients: number;
+    /** The per-recipient `send` outcomes, in subscriber order. */
+    readonly results: ReadonlyArray<SendResult>;
+}
+
+export declare const buildNotificationService: (deps: {
+    readonly channels: ReadonlyArray<Channel>;
+    readonly store: NotificationStore;
+    readonly now?: () => string;
+    /** Digest rollup window in ms. When > 0, sends whose category is NOT forced to
+     *  a specific `channels:` list coalesce into one digest per subject per window.
+     *  0 (default) disables digesting — every send goes out immediately. */
+    readonly digestWindowMs?: number;
+}) => NotificationServiceShape;
+
+/** A delivery channel. `id` is the channel key prefs target (e.g. 'email',
+ *  'slack', 'sms', 'push', 'inApp'). */
+export declare interface Channel {
+    readonly id: string;
+    readonly deliver: (msg: ChannelMessage) => Promise<void>;
+}
+
+/** A built notification to deliver on one channel. */
+export declare interface ChannelMessage {
+    readonly to: string;
+    readonly category: string;
+    readonly title: string;
+    readonly body: string;
+    readonly data?: Record<string, unknown>;
+    readonly tenantId?: string | null;
+}
+
+/** Per-subject preference: which channels are on for a category. A missing
+ *  entry = default-on for every configured channel. */
+export declare interface ChannelPreference {
+    readonly subjectId: string;
+    readonly category: string;
+    readonly channel: string;
+    readonly enabled: boolean;
+}
+
+/** Logs to the console — dev default + a safe fallback. */
+export declare const consoleChannel: () => Channel;
+
+/** Bring-your-own channel (push/APNs/FCM/anything). */
+export declare const customChannel: (id: string, deliver: (msg: ChannelMessage) => Promise<void>) => Channel;
+
+/**
+ * Durable NotificationStore over the framework DataStore. Persists the in-app
+ * inbox, per-subject channel preferences, and the delivery log in three
+ * plugin-contributed tables (`notification_inbox` / `notification_preferences`
+ * / `notification_deliveries`). `notificationsPlugin` binds this automatically
+ * once the app's store exists (unless an explicit `store` was passed), so the
+ * inbox/unreadCount/markRead routes work on real, migrated data.
+ */
+export declare const dataStoreNotificationStore: (store: DataStore) => NotificationStore;
+
+/** Per-channel delivery outcome (for the delivery log). */
+export declare interface DeliveryRecord {
+    readonly id: string;
+    readonly to: string;
+    readonly category: string;
+    readonly channel: string;
+    readonly status: 'sent' | 'failed' | 'skipped';
+    readonly error?: string;
+    readonly at: string;
+}
+
+/** Email channel — the app supplies the sender (compose with
+ *  `@voltro/plugin-mail`'s `MailService.send`). Keeps the mail dep out of here. */
+export declare const emailChannel: (send: (msg: {
+    to: string;
+    subject: string;
+    html: string;
+    text: string;
+}) => Promise<void>) => Channel;
+
+/** One notification held for later delivery — a digest window rollup or a
+ *  quiet-hours deferral. `flushAt` is the ISO instant it becomes deliverable
+ *  (the window boundary / the digest flush tick). `kind` marks WHY it was held
+ *  so the flush can coalesce digest rows but deliver quiet-hours rows as-is. */
+export declare interface HeldNotification {
+    readonly id: string;
+    readonly kind: 'digest' | 'quiet';
+    readonly subjectId: string;
+    readonly send: SendInput;
+    readonly flushAt: string;
+}
+
+/** The in-app channel — delivers by writing to the inbox store. */
+export declare const inAppChannel: (store: NotificationStore) => Channel;
+
+/** An in-app inbox item. */
+export declare interface InboxItem {
+    readonly id: string;
+    readonly subjectId: string;
+    readonly category: string;
+    readonly title: string;
+    readonly body: string;
+    readonly data: Record<string, unknown>;
+    readonly readAt: string | null;
+    readonly createdAt: string;
+    readonly tenantId: string | null;
+}
+
+/** True if `at` is inside the subject's DND window (handles a window that WRAPS
+ *  midnight, e.g. 22:00→08:00). An empty window (start === end) is never active. */
+export declare const inQuietHours: (qh: QuietHours, at: Date) => boolean;
+
+export declare const memoryNotificationStore: () => NotificationStore;
+
+/** The minute-of-day (0–1439) `at` falls on in the IANA `tz`. Uses `Intl` so no
+ *  date-math library is needed; an unknown zone falls back to UTC. */
+export declare const minuteOfDayInZone: (at: Date, tz: string) => number;
+
+export declare class NotificationService extends NotificationService_base {
+}
+
+declare const NotificationService_base: Context.TagClass<NotificationService, "@voltro/plugin-notifications/NotificationService", NotificationServiceShape>;
+
+export declare interface NotificationServiceShape {
+    readonly send: (input: SendInput) => Promise<SendResult>;
+    readonly inbox: (subjectId: string, opts?: {
+        unreadOnly?: boolean;
+        limit?: number;
+    }) => Promise<ReadonlyArray<InboxItem>>;
+    readonly unreadCount: (subjectId: string) => Promise<number>;
+    readonly markRead: (id: string, subjectId: string) => Promise<boolean>;
+    readonly getPreferences: (subjectId: string) => Promise<ReadonlyArray<ChannelPreference>>;
+    readonly setPreference: (pref: ChannelPreference) => Promise<void>;
+    readonly subscribe: (topic: string, subjectId: string, tenantId?: string | null) => Promise<void>;
+    readonly unsubscribe: (topic: string, subjectId: string) => Promise<void>;
+    readonly broadcast: (topic: string, input: Omit<SendInput, 'to'>) => Promise<BroadcastResult>;
+    readonly setQuietHours: (qh: QuietHours) => Promise<void>;
+    readonly clearQuietHours: (subjectId: string) => Promise<void>;
+    readonly getQuietHours: (subjectId: string) => Promise<QuietHours | null>;
+    readonly flushDue: (now?: Date) => Promise<number>;
+}
+
+export declare const notificationsPlugin: (options?: NotificationsPluginOptions) => VoltroPlugin;
+
+export declare interface NotificationsPluginOptions {
+    /** Delivery channels. The in-app inbox channel is added automatically unless
+     *  you pass your own `inApp` channel. Default `[consoleChannel()]` + in-app. */
+    readonly channels?: ReadonlyArray<Channel>;
+    /** Inbox / prefs / delivery-log store. Default in-memory (swap for a durable
+     *  custom store in production). */
+    readonly store?: NotificationStore;
+    /** Digest/batching rollup window in ms. When > 0, multiple sends to the same
+     *  subject within the window coalesce into ONE digest delivery (flushed on the
+     *  boundary by the scheduled flush). A send that forces its own `channels:`
+     *  bypasses the digest. 0 (default) = every send delivers immediately. */
+    readonly digestWindowMs?: number;
+    /** How often the scheduled flush drains due digest windows + quiet-hours
+     *  deferrals. Default 30s. Only runs once the store is bound at boot. */
+    readonly flushIntervalMs?: number;
+    readonly name?: string;
+}
+
+export declare interface NotificationStore {
+    readonly addInbox: (item: Omit<InboxItem, 'id' | 'readAt' | 'createdAt'> & {
+        id: string;
+        createdAt: string;
+    }) => Promise<void>;
+    readonly listInbox: (subjectId: string, opts?: {
+        unreadOnly?: boolean;
+        limit?: number;
+    }) => Promise<ReadonlyArray<InboxItem>>;
+    readonly markRead: (id: string, subjectId: string) => Promise<boolean>;
+    readonly unreadCount: (subjectId: string) => Promise<number>;
+    readonly getPreferences: (subjectId: string) => Promise<ReadonlyArray<ChannelPreference>>;
+    readonly setPreference: (pref: ChannelPreference) => Promise<void>;
+    readonly recordDelivery: (record: DeliveryRecord) => Promise<void>;
+    readonly listDeliveries: (opts?: {
+        limit?: number;
+    }) => Promise<ReadonlyArray<DeliveryRecord>>;
+    readonly subscribeTopic: (sub: TopicSubscription) => Promise<void>;
+    readonly unsubscribeTopic: (topic: string, subjectId: string) => Promise<void>;
+    readonly listTopicSubscribers: (topic: string) => Promise<ReadonlyArray<TopicSubscription>>;
+    readonly getQuietHours: (subjectId: string) => Promise<QuietHours | null>;
+    readonly setQuietHours: (qh: QuietHours) => Promise<void>;
+    readonly clearQuietHours: (subjectId: string) => Promise<void>;
+    readonly enqueueHeld: (held: HeldNotification) => Promise<void>;
+    /** Pending digest holds for a subject whose window has NOT yet elapsed — the
+     *  coalescing check: if any exist, this send joins the open window instead of
+     *  opening a new one. */
+    readonly pendingDigest: (subjectId: string) => Promise<ReadonlyArray<HeldNotification>>;
+    /** Every held notification now due (`flushAt <= now`), oldest-first — the
+     *  scheduled flush drains these and clears them. */
+    readonly dueHeld: (now: string) => Promise<ReadonlyArray<HeldNotification>>;
+    readonly clearHeld: (ids: ReadonlyArray<string>) => Promise<void>;
+}
+
+/** A first-class push channel (APNs / FCM shape) — the built-in alternative to
+ *  hand-rolling `customChannel` for mobile push. You supply two seams:
+ *
+ *   - `tokensFor(subjectId)` → the subject's device tokens (from your own
+ *     device-registration table); a subject with no tokens is a no-op deliver.
+ *   - `transport(payload)` → hand ONE formatted `PushPayload` to APNs / FCM /
+ *     Expo. Throw `PushTokenRejected({ token, reason })` on an unregistered /
+ *     invalid token so the fan-out records the delivery `failed` and your app
+ *     can prune the token. The push AUTH secret (APNs key / FCM server key)
+ *     lives in YOUR transport closure — it never enters this package and is
+ *     never logged.
+ *
+ *  `deliver` formats the message into a `PushPayload` per token and sends each;
+ *  a rejected token surfaces as a `PushTokenRejected` (naming the token, not the
+ *  secret). Default `id` is `'push'`. */
+export declare const pushChannel: (opts: {
+    readonly id?: string;
+    readonly tokensFor: (subjectId: string) => Promise<ReadonlyArray<string>>;
+    readonly transport: (payload: PushPayload) => Promise<void>;
+}) => Channel;
+
+/** The provider-agnostic push payload `pushChannel` builds per device token —
+ *  the shape an APNs `aps` / FCM `notification` transport consumes. */
+export declare interface PushPayload {
+    readonly token: string;
+    readonly title: string;
+    readonly body: string;
+    /** Best-effort unread/badge count if the app supplies it via `msg.data.badge`. */
+    readonly badge?: number;
+    /** The message `data` bag, forwarded as the push data/custom section. */
+    readonly data: Record<string, unknown>;
+}
+
+/** A push transport rejected a device token (unregistered / invalid / expired —
+ *  the APNs `Unregistered` / FCM `UNREGISTERED` class). Thrown by `pushChannel`'s
+ *  `deliver` so the fan-out records the delivery `failed` with the token that was
+ *  rejected — the app can prune it from its device-token table. `token` carries
+ *  the rejected token itself; a push AUTH secret (APNs key / FCM server key) is
+ *  never part of this error and is never logged. */
+export declare class PushTokenRejected extends PushTokenRejected_base {
+}
+
+declare const PushTokenRejected_base: Schema.TaggedErrorClass<PushTokenRejected, "PushTokenRejected", {
+    readonly _tag: Schema.tag<"PushTokenRejected">;
+} & {
+    token: typeof Schema.String;
+    reason: typeof Schema.String;
+}>;
+
+/** A per-subject Do-Not-Disturb window, expressed in minutes-of-day in the
+ *  subject's `tz` (an IANA zone). A window may WRAP midnight (`startMinute` >
+ *  `endMinute`, e.g. 22:00→08:00). `policy` decides what a send during the
+ *  window does: `hold` (default — deferred and delivered after the window) or
+ *  `drop` (silently discarded). */
+export declare interface QuietHours {
+    readonly subjectId: string;
+    /** Minutes past local midnight the DND window opens (0–1439). */
+    readonly startMinute: number;
+    /** Minutes past local midnight the DND window closes (0–1439). */
+    readonly endMinute: number;
+    /** IANA timezone the window is evaluated in (e.g. 'Europe/Berlin'). Default 'UTC'. */
+    readonly tz?: string;
+    /** What a send during the window does. Default 'hold'. */
+    readonly policy?: 'hold' | 'drop';
+}
+
+/** The next instant the DND window CLOSES, at or after `at` — where a
+ *  held-during-quiet-hours notification becomes deliverable. */
+export declare const quietHoursEnd: (qh: QuietHours, at: Date) => Date;
+
+/**
+ * Resolve which channel ids to deliver on. Order: caller-requested `channels`
+ * (intersected with configured) ELSE all configured; then drop any the
+ * subject has turned OFF for this category. A missing preference = on.
+ */
+export declare const resolveChannels: (configured: ReadonlyArray<string>, category: string, requested: ReadonlyArray<string> | undefined, prefs: ReadonlyArray<ChannelPreference>, subjectId: string) => ReadonlyArray<string>;
+
+/** What a caller asks to send. `channels` overrides the default routing. */
+export declare interface SendInput {
+    readonly to: string;
+    readonly category: string;
+    readonly title: string;
+    readonly body: string;
+    readonly data?: Record<string, unknown>;
+    readonly channels?: ReadonlyArray<string>;
+    readonly tenantId?: string | null;
+}
+
+export declare interface SendResult {
+    readonly delivered: ReadonlyArray<string>;
+    readonly failed: ReadonlyArray<{
+        channel: string;
+        error: string;
+    }>;
+    readonly skipped: ReadonlyArray<string>;
+    /** Set when the send did NOT go out immediately: `digest` (joined/opened a
+     *  rollup window), `quiet-held` (deferred past a DND window), or `quiet-drop`
+     *  (discarded per the `drop` policy). Absent on an immediate delivery. */
+    readonly held?: 'digest' | 'quiet-held' | 'quiet-drop';
+}
+
+/** SMS via a generic REST sender (Twilio etc.) — app supplies the send fn. */
+export declare const smsChannel: (send: (to: string, body: string) => Promise<void>) => Channel;
+
+/** A subscription of a subject to a broadcast topic. `broadcast(topic, …)` fans
+ *  a single send out to every subscriber of that topic. */
+export declare interface TopicSubscription {
+    readonly topic: string;
+    readonly subjectId: string;
+    readonly tenantId?: string | null;
+}
+
+/** POST the message to an incoming webhook (Slack / Discord / Teams / generic).
+ *  `format` shapes the JSON body; default Slack-style `{ text }`. */
+export declare const webhookChannel: (opts: {
+    readonly id?: string;
+    readonly url: string;
+    readonly format?: (msg: ChannelMessage) => unknown;
+    readonly headers?: Record<string, string>;
+}) => Channel;
+
+export { }