@warlock.js/notifications 5.44.0 → 5.46.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `@warlock.js/notifications` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.46.0 - 2026-11-06
+
+### Upgrading
+
+- **Security: different identity types could read each other's notifications.** Recipients were keyed by a bare id, so with several auth models (staff, customers, platform users) that each count ids from 1, staff `5` and customer `5` shared one inbox. Add a recipient type column and declare it: create a nullable `recipient_type` column, backfill existing rows with the type that owned them, then set `columnMap = { recipientType: "recipient_type", … }` on the notification model. Until you declare it, behavior is unchanged (ids are the only key), which is only safe for an app with a single identity type. See "Recipient types" in the in-app store guide.
+- Once `recipientType` is declared, rows with no type match no read until backfilled, and a bare id passed to an `inApp` method or repository method throws `RecipientTypeRequiredError`; pass the model or `{ type, id }`.
+
+### Added
+
+- `columnMap.recipientType`: stores the recipient's identity type next to its id. The `database` channel writes it from the recipient model (an auth model's `userType`, otherwise the table name), and `notificationColumns()` emits the column.
+- `inApp` read, count, mark-read, mark-unread, find and dismiss methods (and the matching repository methods) accept `{ type, id }` (`RecipientRef`) as well as a model or bare id, and filter by type and id when the column is declared.
+- `RecipientTypeRequiredError`, `recipientTypeOf()`, `RecipientRef`, `RecipientInput`.
+- `notificationColumns(…, { recipientModel })` derives the id column type from the recipient model (`integer`, or `uuid` when it sets `autoGenerateId = false`). Without it the default stays UUID.
+
 ## 5.34.3 - 2026-10-20
 
 ### Changed

package/cjs/index.cjs

@@ -56,6 +56,19 @@ var UnresolvableRouteError = class UnresolvableRouteError extends Error {
 		captureStack$1(this, UnresolvableRouteError);
 	}
 };
+/**
+* Thrown when the notification table keys recipients by type and a read or
+* write names the recipient by a bare id. A bare id cannot say which identity
+* type it belongs to, so serving it would let types sharing that id read each
+* other's notifications. Pass the recipient model, or `{ type, id }`.
+*/
+var RecipientTypeRequiredError = class RecipientTypeRequiredError extends Error {
+	constructor(recipientId) {
+		super(`The notifications table stores a recipient type, so recipient ${recipientId ?? "(unknown)"} must be given as the model or as \`{ type, id }\`, not as a bare id.`);
+		this.name = "RecipientTypeRequiredError";
+		captureStack$1(this, RecipientTypeRequiredError);
+	}
+};
 
 //#endregion
 //#region ../../packages/notifications/src/config.ts
@@ -489,17 +502,49 @@ const notify = new Proxy({}, { get(_target, prop) {
 	return (to, payload, options) => notifyImpl(prop, to, payload, options);
 } });
 
+//#endregion
+//#region ../../packages/notifications/src/in-app/recipient.ts
+/**
+* The identity type of a recipient model. Auth models name it with `userType`
+* (the same value the auth config and token payloads use); any other model
+* falls back to its table name.
+*/
+function recipientTypeOf(notifiable) {
+	const userType = notifiable.userType;
+	if (typeof userType === "string" && userType) return userType;
+	return notifiable.constructor.table;
+}
+/** Normalize any accepted recipient form to `{ id, type? }` (`type` absent for bare ids). */
+function toRecipientRef(recipient) {
+	if (typeof recipient !== "object") return { id: recipient };
+	if ("get" in recipient && typeof recipient.get === "function") return {
+		id: recipient.id,
+		type: recipientTypeOf(recipient)
+	};
+	return {
+		id: recipient.id,
+		type: recipient.type
+	};
+}
+
 //#endregion
 //#region ../../packages/notifications/src/channels/database-channel.ts
 function databaseChannel(repo) {
 	return defineChannel({
 		name: "database",
-		route: (notifiable) => ({ id: notifiable.id }),
+		route: (notifiable) => ({
+			id: notifiable.id,
+			type: recipientTypeOf(notifiable)
+		}),
 		async send({ payload, route, notifiable }) {
 			const id = typeof route === "object" ? route.id : route;
+			const type = typeof route === "object" ? route.type : void 0;
 			const { tenantColumn } = repo;
 			const tenantId = tenantColumn && notifiable ? notifiable.get(tenantColumn) : void 0;
-			await repo.createFor(id, payload, tenantId);
+			await repo.createFor({
+				id,
+				type
+			}, payload, tenantId);
 		}
 	});
 }
@@ -555,13 +600,16 @@ const DEFAULT_READ_AT_COLUMN = "read_at";
 function resolveColumnMap(map) {
 	const recipient = map?.recipient ?? DEFAULT_RECIPIENT_COLUMN;
 	const tenant = map?.tenant;
+	const recipientType = map?.recipientType;
 	if (!map?.readAt && !map?.isRead) return {
 		recipient,
+		recipientType,
 		tenant,
 		readAt: DEFAULT_READ_AT_COLUMN
 	};
 	return {
 		recipient,
+		recipientType,
 		tenant,
 		readAt: map.readAt,
 		isRead: map.isRead
@@ -619,7 +667,7 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 	* direct filtering only when the model declares those columns.
 	*/
 	buildFilterBy() {
-		const { recipient, tenant, readAt, isRead } = this.columns;
+		const { recipient, recipientType, tenant, readAt, isRead } = this.columns;
 		const rules = {
 			id: "=",
 			type: "=",
@@ -631,12 +679,29 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 				else if (readAt) query.whereNull(readAt);
 			}
 		};
+		if (recipientType) rules.recipientType = ["=", recipientType];
 		if (isRead) rules.isRead = ["=", isRead];
 		if (readAt) rules.readAt = ["=", readAt];
 		if (tenant) rules.tenant = ["=", tenant];
 		return rules;
 	}
 	/**
+	* Resolve a recipient into the logical filter keys that scope a query to it.
+	* When the model stores a recipient type the scope is `(recipientType,
+	* recipientId)`; a bare id then throws, since an id alone can't say which
+	* identity type it belongs to. Without a type column the scope is the id
+	* alone and any type on the recipient is ignored.
+	*/
+	scopeOf(recipient) {
+		const { id, type } = toRecipientRef(recipient);
+		if (!this.columns.recipientType) return { recipientId: id };
+		if (!type) throw new RecipientTypeRequiredError(id);
+		return {
+			recipientId: id,
+			recipientType: type
+		};
+	}
+	/**
 	* Translate an object keyed by LOGICAL names into one keyed by PHYSICAL
 	* columns, using `filterBy` as the lookup. Keys with no `[op, column]` tuple
 	* (e.g. `title`, `body`, `payload`, `type`, `id`) pass through unchanged —
@@ -665,10 +730,12 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 	* the recipient column directly.
 	*/
 	stripServerOwnedKeys(input) {
-		const { recipient, tenant, readAt, isRead } = this.columns;
+		const { recipient, recipientType, tenant, readAt, isRead } = this.columns;
 		const serverOwned = /* @__PURE__ */ new Set([
 			"id",
 			"recipientId",
+			"recipientType",
+			recipientType,
 			"tenant",
 			"readAt",
 			"isRead",
@@ -692,15 +759,16 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 	* the existing row instead of inserting a duplicate. A unique index on the
 	* key is the backstop for the rare insert race (we re-fetch on conflict).
 	*/
-	async createFor(recipientId, input, tenantId) {
+	async createFor(recipient, input, tenantId) {
 		const { idempotencyKey } = input;
+		const scope = this.scopeOf(recipient);
 		if (idempotencyKey) {
-			const existing = await this.firstByIdempotencyKey(recipientId, idempotencyKey);
+			const existing = await this.firstByIdempotencyKey(scope, idempotencyKey);
 			if (existing) return existing;
 		}
 		const row = {
 			...this.stripServerOwnedKeys(input),
-			recipientId
+			...scope
 		};
 		if (this.columns.isRead) row.isRead = false;
 		if (this.columns.tenant && tenantId !== void 0) row.tenant = tenantId;
@@ -708,7 +776,7 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 			return await this.create(this.toRow(row));
 		} catch (error) {
 			if (idempotencyKey) {
-				const existing = await this.firstByIdempotencyKey(recipientId, idempotencyKey);
+				const existing = await this.firstByIdempotencyKey(scope, idempotencyKey);
 				if (existing) return existing;
 			}
 			throw error;
@@ -719,8 +787,8 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 	* for the Phase-2 `Channel.sendMany` fan-out hook; not on the per-recipient
 	* send path yet.
 	*/
-	createManyFor(recipientIds, input, tenantId) {
-		return Promise.all(recipientIds.map((recipientId) => this.createFor(recipientId, input, tenantId)));
+	createManyFor(recipients, input, tenantId) {
+		return Promise.all(recipients.map((recipient) => this.createFor(recipient, input, tenantId)));
 	}
 	/**
 	* Mark rows read — recipient-scoped. `id` omitted → all unread rows for the
@@ -728,14 +796,14 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 	* to unread so a re-mark never overwrites an earlier `read_at` timestamp.
 	* Sets whichever read-state column(s) the model declares.
 	*/
-	markRead(recipientId, id) {
+	markRead(recipient, id) {
 		const { isRead, readAt } = this.columns;
 		const unreadScope = isRead ? { isRead: false } : { readAt: null };
 		const data = {};
 		if (isRead) data.isRead = true;
 		if (readAt) data.readAt = /* @__PURE__ */ new Date();
 		return this.updateMany(this.toRow({
-			recipientId,
+			...this.scopeOf(recipient),
 			...unreadScope,
 			...id !== void 0 ? { id } : {}
 		}), this.toRow(data));
@@ -744,20 +812,20 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 	* Inverse of `markRead`, same recipient-scoping. No unread scope needed —
 	* clearing the read-state of an already-unread row is a no-op.
 	*/
-	markUnread(recipientId, id) {
+	markUnread(recipient, id) {
 		const { isRead, readAt } = this.columns;
 		const data = {};
 		if (isRead) data.isRead = false;
 		if (readAt) data.readAt = null;
 		return this.updateMany(this.toRow({
-			recipientId,
+			...this.scopeOf(recipient),
 			...id !== void 0 ? { id } : {}
 		}), this.toRow(data));
 	}
 	/** Find one row for a recipient (read path — `filterBy` maps the keys). */
-	findFor(recipientId, id) {
+	findFor(recipient, id) {
 		return this.first({
-			recipientId,
+			...this.scopeOf(recipient),
 			id
 		});
 	}
@@ -765,16 +833,16 @@ var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManag
 	* Delete rows — recipient-scoped. `id` omitted → clear all for the
 	* recipient; `id` given → that one row.
 	*/
-	deleteFor(recipientId, id) {
+	deleteFor(recipient, id) {
 		return this.deleteMany(this.toRow({
-			recipientId,
+			...this.scopeOf(recipient),
 			...id !== void 0 ? { id } : {}
 		}));
 	}
-	/** Read path — `filterBy` maps `recipientId`/`idempotencyKey` to columns. */
-	firstByIdempotencyKey(recipientId, idempotencyKey) {
+	/** Read path — `filterBy` maps `recipientId`/`recipientType`/`idempotencyKey` to columns. */
+	firstByIdempotencyKey(scope, idempotencyKey) {
 		return this.first({
-			recipientId,
+			...scope,
 			idempotencyKey
 		});
 	}
@@ -847,7 +915,6 @@ var DatabaseNotification = class extends _warlock_js_cascade.Model {
 
 //#endregion
 //#region ../../packages/notifications/src/in-app/in-app.ts
-const idOf = (recipient) => typeof recipient === "object" ? recipient.id : recipient;
 var InApp = class {
 	repo;
 	/**
@@ -866,14 +933,14 @@ var InApp = class {
 	list(recipient, options) {
 		return this.repository.list({
 			...options,
-			recipientId: idOf(recipient)
+			...this.repository.scopeOf(recipient)
 		});
 	}
 	/** Unread-only list — common case for badges + dashboards. */
 	listUnread(recipient, options) {
 		return this.repository.list({
 			...options,
-			recipientId: idOf(recipient),
+			...this.repository.scopeOf(recipient),
 			unread: true
 		});
 	}
@@ -883,25 +950,25 @@ var InApp = class {
 	*/
 	countUnread(recipient) {
 		return this.repository.countCached({
-			recipientId: idOf(recipient),
+			...this.repository.scopeOf(recipient),
 			unread: true
 		});
 	}
 	/** Find one notification for a recipient — for a detail view. */
 	find(recipient, id) {
-		return this.repository.findFor(idOf(recipient), id);
+		return this.repository.findFor(recipient, id);
 	}
 	/** Mark read — `id` omitted = all unread for this recipient. */
 	markAsRead(recipient, id) {
-		return this.repository.markRead(idOf(recipient), id);
+		return this.repository.markRead(recipient, id);
 	}
 	/** Mark unread — same recipient-scoping. */
 	markAsUnread(recipient, id) {
-		return this.repository.markUnread(idOf(recipient), id);
+		return this.repository.markUnread(recipient, id);
 	}
 	/** Delete/dismiss — `id` omitted = clear all for this recipient. */
 	dismiss(recipient, id) {
-		return this.repository.deleteFor(idOf(recipient), id);
+		return this.repository.deleteFor(recipient, id);
 	}
 };
 /** Single in-app facade — bound at boot via `inApp.configure(...)`. */
@@ -916,6 +983,10 @@ const inApp = new InApp();
 * agree by construction. The stable lexical columns (`type`, `title`, `body`,
 * `payload`, `idempotency_key`) keep fixed names.
 *
+* `columnMap.recipientType` adds the recipient-type string column (see
+* `NotificationColumnMap`). For a table created earlier, add that column with a
+* migration instead of re-creating the table.
+*
 * Read-state follows the map's presence rules (see `NotificationColumnMap`):
 * `readAt` → a nullable timestamp, `isRead` → an indexed boolean, both → both.
 *
@@ -936,8 +1007,9 @@ const inApp = new InApp();
 */
 function notificationColumns(modelOrOptions, options) {
 	const model = isNotificationColumnsOptions(modelOrOptions) ? void 0 : modelOrOptions;
-	const idType = (isNotificationColumnsOptions(modelOrOptions) ? modelOrOptions : options)?.idType ?? "uuid";
-	const { recipient, tenant, readAt, isRead } = resolveColumnMap(model?.columnMap);
+	const resolvedOptions = isNotificationColumnsOptions(modelOrOptions) ? modelOrOptions : options;
+	const idType = resolvedOptions?.idType ?? deriveIdType(resolvedOptions?.recipientModel);
+	const { recipient, recipientType, tenant, readAt, isRead } = resolveColumnMap(model?.columnMap);
 	const idColumn = getIdColumn(idType);
 	const columns = {
 		[recipient]: idColumn().index().notNullable(),
@@ -946,6 +1018,7 @@ function notificationColumns(modelOrOptions, options) {
 		body: (0, _warlock_js_cascade.text)().nullable(),
 		payload: (0, _warlock_js_cascade.json)().nullable()
 	};
+	if (recipientType) columns[recipientType] = (0, _warlock_js_cascade.string)().index().notNullable();
 	if (readAt) columns[readAt] = (0, _warlock_js_cascade.timestamp)().nullable();
 	if (isRead) columns[isRead] = (0, _warlock_js_cascade.boolCol)().default(false).index();
 	if (tenant) columns[tenant] = idColumn().index().notNullable();
@@ -953,7 +1026,7 @@ function notificationColumns(modelOrOptions, options) {
 	return columns;
 }
 function isNotificationColumnsOptions(value) {
-	return "idType" in (value ?? {});
+	return "idType" in (value ?? {}) || "recipientModel" in (value ?? {});
 }
 function getIdColumn(idType) {
 	switch (idType) {
@@ -963,6 +1036,10 @@ function getIdColumn(idType) {
 		default: return _warlock_js_cascade.uuid;
 	}
 }
+function deriveIdType(recipientModel) {
+	if (!recipientModel || recipientModel.autoGenerateId === false) return "uuid";
+	return "integer";
+}
 
 //#endregion
 //#region ../../packages/notifications/src/queue/load-herald.ts
@@ -1164,6 +1241,7 @@ exports.NOTIFICATION_JOB_NAME = NOTIFICATION_JOB_NAME;
 exports.NoQueueDispatcherError = NoQueueDispatcherError;
 exports.NotificationsNotConfiguredError = NotificationsNotConfiguredError;
 exports.QueuePackageNotInstalledError = QueuePackageNotInstalledError;
+exports.RecipientTypeRequiredError = RecipientTypeRequiredError;
 exports.UnresolvableRouteError = UnresolvableRouteError;
 exports.bullmqQueue = bullmqQueue;
 exports.databaseChannel = databaseChannel;
@@ -1177,8 +1255,10 @@ exports.mailChannel = mailChannel;
 exports.notificationColumns = notificationColumns;
 exports.notifications = notifications;
 exports.notify = notify;
+exports.recipientTypeOf = recipientTypeOf;
 exports.resetNotificationConfig = resetNotificationConfig;
 exports.resolveColumnMap = resolveColumnMap;
 exports.setNotificationConfig = setNotificationConfig;
 exports.startNotificationsWorker = startNotificationsWorker;
+exports.toRecipientRef = toRecipientRef;
 //# sourceMappingURL=index.cjs.map