@voltro/plugin-notifications 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -160,6 +160,49 @@ 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.
+ *
+ * **It is ASYNC, and the sync-only first version was the defect.** The seam was
+ * built for an app whose addressing unit is its own, and an app that has one
+ * keeps it in a TABLE — the three examples in the option's own docstring
+ * (employee, member, contact) are all rows. So the resolver reads the store,
+ * so it returns a promise, so the call written in our docstring did not
+ * typecheck for the only readers it was written for. A resolver that happens to
+ * be sync still satisfies the type; nothing about that case changed.
+ *
+ * NOT cached here on purpose. A per-connection cache is the obvious next step
+ * and it is the app's to make, not ours: the first call decides the answer for
+ * the life of the connection, so a member created a second after connect
+ * resolves to the fallback until reconnect. An app that knows its own
+ * invalidation can memoise inside the resolver; the framework cannot know it.
+ */
+export declare const makeSubjectId: (resolve: NotificationsPluginOptions["resolveSubjectId"]) => (ctx: {
+    request: {
+        subject: {
+            id?: string | null;
+        };
+    };
+}) => Promise<string>;
+
 export declare const memoryNotificationStore: () => NotificationStore;
 
 /** The minute-of-day (0–1439) `at` falls on in the IANA `tz`. Uses `Intl` so no
@@ -200,6 +243,34 @@ 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) })
+     *
+     * **May be async, and usually has to be.** An app that HAS its own addressing
+     * unit almost always stores it in a table — an employee, a member, a contact
+     * are rows, not token claims. If the mapping were in the token there would be
+     * no need for this seam at all: `subject.id` would already be the right id.
+     * The sync-only signature this shipped with made the call in the line above —
+     * our own docstring — fail to typecheck for exactly the apps it was built for.
+     *
+     * 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 | Promise<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>;