@voltro/plugin-notifications 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -127,6 +127,8 @@ export declare interface InboxItem {
     readonly body: string;
     readonly data: Record<string, unknown>;
     readonly readAt: string | null;
+    /** When the user cleared it out of the inbox. A different state from read. */
+    readonly archivedAt: string | null;
     readonly createdAt: string;
     readonly tenantId: string | null;
 }
@@ -139,6 +141,17 @@ export declare const inboxTable: Table<"_voltro_notification_inbox", FieldDefini
     readonly body: ColumnBuilder<string, "text", boolean>;
     readonly data: ColumnBuilder<Record<string, unknown>, "json", boolean>;
     readonly readAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+    /**
+     * ARCHIVED is a different state from READ, and for a user the more important
+     * one: it is what empties the inbox.
+     *
+     * Reported as the reason an app could not adopt this plugin. `readAt` covers
+     * read and `status` on the delivery table is the delivery outcome
+     * ('sent' | 'failed' | 'skipped') — neither is an archive, and the word did
+     * not appear anywhere in this plugin's types. An inbox a user cannot clear is
+     * one they stop opening.
+     */
+    readonly archivedAt: ColumnBuilder<Date | null, "timestamp", boolean>;
     readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
     readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
 }>, true, "byInboxSubject">;
@@ -147,6 +160,35 @@ export declare const inboxTable: Table<"_voltro_notification_inbox", FieldDefini
  *  midnight, e.g. 22:00→08:00). An empty window (start === end) is never active. */
 export declare const inQuietHours: (qh: QuietHours, at: Date) => boolean;
 
+/**
+ * WHO an inbox belongs to.
+ *
+ * `subject.id` is the framework's answer and it is not always the app's. A
+ * reporter's addressing unit is the EMPLOYEE: a shift change, an absence
+ * request or a task reminder is addressed to a person, and a person does not
+ * necessarily have an auth user. Their numbers, on 14 670 rows:
+ *
+ *   employee WITH a userId    4 677  representable
+ *   employee WITHOUT one        668  NOT — 4 people, 516 of those rows read,
+ *                                    most recent 2026-06-19
+ *
+ * The 668 are live traffic, read by someone, and unaddressable under a
+ * subject-only model. Worse is what comes after a migration: every producer
+ * would resolve employee → userId and silently deliver NOTHING for anyone
+ * without an auth user — the exact failure this plugin's own docstring warns
+ * about, one level up and structural rather than accidental.
+ *
+ * So the app supplies it, the same seam `auth.resolveScopes` already offers for
+ * this shape. Absent keeps today's behaviour exactly.
+ */
+export declare const makeSubjectId: (resolve: NotificationsPluginOptions["resolveSubjectId"]) => (ctx: {
+    request: {
+        subject: {
+            id?: string | null;
+        };
+    };
+}) => string;
+
 export declare const memoryNotificationStore: () => NotificationStore;
 
 /** The minute-of-day (0–1439) `at` falls on in the IANA `tz`. Uses `Intl` so no
@@ -166,6 +208,13 @@ export declare interface NotificationServiceShape {
     }) => Promise<ReadonlyArray<InboxItem>>;
     readonly unreadCount: (subjectId: string) => Promise<number>;
     readonly markRead: (id: string, subjectId: string) => Promise<boolean>;
+    /** Undo a read. An inbox without the way back is a one-way ratchet. */
+    readonly markUnread: (id: string, subjectId: string) => Promise<boolean>;
+    /** Read everything; returns how many rows changed. */
+    readonly markAllRead: (subjectId: string) => Promise<number>;
+    /** Archive / unarchive. A different state from read — and the one that
+     *  empties the inbox, which is why it matters more to a user. */
+    readonly setArchived: (id: string, subjectId: string, archived: boolean) => 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>;
@@ -180,6 +229,27 @@ export declare interface NotificationServiceShape {
 export declare const notificationsPlugin: (options?: NotificationsPluginOptions) => VoltroPlugin;
 
 export declare interface NotificationsPluginOptions {
+    /**
+     * Resolve WHO the caller's inbox belongs to, when that is not `subject.id`.
+     *
+     * The addressing unit is the app's, not the framework's. If yours is an
+     * employee, a member or a contact — something that need not have an auth user
+     * — return its id here and the whole surface (`inbox`, `unreadCount`,
+     * `markRead`, `archive`, preferences, quiet hours) follows.
+     *
+     *   notificationsPlugin({ resolveSubjectId: (ctx) => resolveCallerEmployeeId(ctx) })
+     *
+     * Absent keeps `subject.id`, so nothing changes for an app whose units line
+     * up. Returning `undefined` for one caller falls back the same way rather
+     * than failing the read.
+     */
+    readonly resolveSubjectId?: (ctx: {
+        readonly request: {
+            readonly subject: {
+                readonly id?: string | null;
+            };
+        };
+    }) => string | undefined;
     /** 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>;
@@ -198,7 +268,7 @@ export declare interface NotificationsPluginOptions {
 }
 
 export declare interface NotificationStore {
-    readonly addInbox: (item: Omit<InboxItem, 'id' | 'readAt' | 'createdAt'> & {
+    readonly addInbox: (item: Omit<InboxItem, 'id' | 'readAt' | 'archivedAt' | 'createdAt'> & {
         id: string;
         createdAt: string;
     }) => Promise<void>;
@@ -207,6 +277,13 @@ export declare interface NotificationStore {
         limit?: number;
     }) => Promise<ReadonlyArray<InboxItem>>;
     readonly markRead: (id: string, subjectId: string) => Promise<boolean>;
+    /** Clear the read stamp — an inbox needs the way back, not just forward. */
+    readonly markUnread: (id: string, subjectId: string) => Promise<boolean>;
+    /** Read EVERYTHING for this subject. Returns how many rows changed. */
+    readonly markAllRead: (subjectId: string) => Promise<number>;
+    /** Archive / unarchive — a different state from read, and the one that
+     *  actually empties the inbox. */
+    readonly setArchived: (id: string, subjectId: string, archived: boolean) => Promise<boolean>;
     readonly unreadCount: (subjectId: string) => Promise<number>;
     readonly getPreferences: (subjectId: string) => Promise<ReadonlyArray<ChannelPreference>>;
     readonly setPreference: (pref: ChannelPreference) => Promise<void>;