@warlock.js/notifications 4.2.0

package/esm/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../@warlock.js/notifications/src/errors.ts"],"mappings":";;AAiBA;;;;;AAWA;;cAXa,+BAAA,SAAwC,KAAK;EAAL,WAAA;AAAA;AAAA,cAWxC,oBAAA,SAA6B,KAAK;cAC1B,WAAA;AAAA;AAAA,cAUR,sBAAA,SAA+B,KAAK;cAC5B,WAAA;AAAA;AAAA,cAUR,oBAAA,SAA6B,KAAK;cAC1B,gBAAA,UAA0B,WAAA;AAAA;;;;AAXP;AAUxC;cAgBa,sBAAA,SAA+B,KAAK;cAC5B,WAAA,UAAqB,WAAA;AAAA"}

package/esm/errors.mjs

@@ -0,0 +1,56 @@
+//#region ../@warlock.js/notifications/src/errors.ts
+/**
+* Domain errors for `@warlock.js/notifications`. All extend `Error` directly
+* (no framework HttpError) so the package stays runtime-agnostic — the host
+* app maps them to its own error shape via `instanceof` if needed.
+*
+* Each captures a clean V8 stack (drops the Error-constructor frame) to match
+* the cascade convention.
+*/
+function captureStack(target, ctor) {
+	Error.captureStackTrace?.(target, ctor);
+}
+var NotificationsNotConfiguredError = class NotificationsNotConfiguredError extends Error {
+	constructor() {
+		super("Notifications not configured — add `src/config/notifications.ts` with a default-exported config; the notifications connector registers it at boot.");
+		this.name = "NotificationsNotConfiguredError";
+		captureStack(this, NotificationsNotConfiguredError);
+	}
+};
+var ChannelNotFoundError = class ChannelNotFoundError extends Error {
+	constructor(channelName) {
+		super(`Channel "${channelName}" is not configured. Add it to the \`channels\` map in \`src/config/notifications.ts\`.`);
+		this.name = "ChannelNotFoundError";
+		captureStack(this, ChannelNotFoundError);
+	}
+};
+var NoQueueDispatcherError = class NoQueueDispatcherError extends Error {
+	constructor(channelName) {
+		super(`Cannot queue to channel "${channelName}" — no queue dispatcher configured. Add a \`queue\` to \`src/config/notifications.ts\`, or call \`.send()\` instead of \`.queue()\`.`);
+		this.name = "NoQueueDispatcherError";
+		captureStack(this, NoQueueDispatcherError);
+	}
+};
+var MissingRendererError = class MissingRendererError extends Error {
+	constructor(notificationType, channelName) {
+		super(`Notification "${notificationType}" routes to channel "${channelName}" via \`via\` but defines no \`${channelName}\` renderer.`);
+		this.name = "MissingRendererError";
+		captureStack(this, MissingRendererError);
+	}
+};
+/**
+* Thrown when a channel's `route()` resolver runs but returns `undefined` for
+* a recipient (e.g. a mail recipient with no email). Distinct from "the
+* channel declares no resolver" — that case falls back to `{ id }`.
+*/
+var UnresolvableRouteError = class UnresolvableRouteError extends Error {
+	constructor(channelName, recipientId) {
+		super(`Channel "${channelName}" could not resolve a route for recipient ${recipientId ?? "(unknown)"}. The channel's \`route()\` returned undefined — the recipient is missing the address column this channel needs.`);
+		this.name = "UnresolvableRouteError";
+		captureStack(this, UnresolvableRouteError);
+	}
+};
+
+//#endregion
+export { ChannelNotFoundError, MissingRendererError, NoQueueDispatcherError, NotificationsNotConfiguredError, UnresolvableRouteError };
+//# sourceMappingURL=errors.mjs.map

package/esm/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../@warlock.js/notifications/src/errors.ts"],"sourcesContent":["/**\n * Domain errors for `@warlock.js/notifications`. All extend `Error` directly\n * (no framework HttpError) so the package stays runtime-agnostic — the host\n * app maps them to its own error shape via `instanceof` if needed.\n *\n * Each captures a clean V8 stack (drops the Error-constructor frame) to match\n * the cascade convention.\n */\n\nfunction captureStack(target: object, ctor: new (...args: any[]) => unknown): void {\n  // V8 only; guarded for non-V8 runtimes.\n  (Error as unknown as { captureStackTrace?: (t: object, c: unknown) => void }).captureStackTrace?.(\n    target,\n    ctor,\n  );\n}\n\nexport class NotificationsNotConfiguredError extends Error {\n  public constructor() {\n    super(\n      \"Notifications not configured — add `src/config/notifications.ts` with a \" +\n        \"default-exported config; the notifications connector registers it at boot.\",\n    );\n    this.name = \"NotificationsNotConfiguredError\";\n    captureStack(this, NotificationsNotConfiguredError);\n  }\n}\n\nexport class ChannelNotFoundError extends Error {\n  public constructor(channelName: string) {\n    super(\n      `Channel \"${channelName}\" is not configured. Add it to the ` +\n        \"`channels` map in `src/config/notifications.ts`.\",\n    );\n    this.name = \"ChannelNotFoundError\";\n    captureStack(this, ChannelNotFoundError);\n  }\n}\n\nexport class NoQueueDispatcherError extends Error {\n  public constructor(channelName: string) {\n    super(\n      `Cannot queue to channel \"${channelName}\" — no queue dispatcher configured. ` +\n        \"Add a `queue` to `src/config/notifications.ts`, or call `.send()` instead of `.queue()`.\",\n    );\n    this.name = \"NoQueueDispatcherError\";\n    captureStack(this, NoQueueDispatcherError);\n  }\n}\n\nexport class MissingRendererError extends Error {\n  public constructor(notificationType: string, channelName: string) {\n    super(\n      `Notification \"${notificationType}\" routes to channel \"${channelName}\" via ` +\n        `\\`via\\` but defines no \\`${channelName}\\` renderer.`,\n    );\n    this.name = \"MissingRendererError\";\n    captureStack(this, MissingRendererError);\n  }\n}\n\n/**\n * Thrown when a channel's `route()` resolver runs but returns `undefined` for\n * a recipient (e.g. a mail recipient with no email). Distinct from \"the\n * channel declares no resolver\" — that case falls back to `{ id }`.\n */\nexport class UnresolvableRouteError extends Error {\n  public constructor(channelName: string, recipientId?: unknown) {\n    super(\n      `Channel \"${channelName}\" could not resolve a route for recipient ` +\n        `${recipientId ?? \"(unknown)\"}. The channel's \\`route()\\` returned undefined — ` +\n        \"the recipient is missing the address column this channel needs.\",\n    );\n    this.name = \"UnresolvableRouteError\";\n    captureStack(this, UnresolvableRouteError);\n  }\n}\n"],"mappings":";;;;;;;;;AASA,SAAS,aAAa,QAAgB,MAA6C;CAEjF,AAAC,MAA6E,oBAC5E,QACA,IACF;AACF;AAEA,IAAa,kCAAb,MAAa,wCAAwC,MAAM;CACzD,AAAO,cAAc;EACnB,MACE,oJAEF;EACA,KAAK,OAAO;EACZ,aAAa,MAAM,+BAA+B;CACpD;AACF;AAEA,IAAa,uBAAb,MAAa,6BAA6B,MAAM;CAC9C,AAAO,YAAY,aAAqB;EACtC,MACE,YAAY,YAAY,wFAE1B;EACA,KAAK,OAAO;EACZ,aAAa,MAAM,oBAAoB;CACzC;AACF;AAEA,IAAa,yBAAb,MAAa,+BAA+B,MAAM;CAChD,AAAO,YAAY,aAAqB;EACtC,MACE,4BAA4B,YAAY,qIAE1C;EACA,KAAK,OAAO;EACZ,aAAa,MAAM,sBAAsB;CAC3C;AACF;AAEA,IAAa,uBAAb,MAAa,6BAA6B,MAAM;CAC9C,AAAO,YAAY,kBAA0B,aAAqB;EAChE,MACE,iBAAiB,iBAAiB,uBAAuB,YAAY,iCACvC,YAAY,aAC5C;EACA,KAAK,OAAO;EACZ,aAAa,MAAM,oBAAoB;CACzC;AACF;;;;;;AAOA,IAAa,yBAAb,MAAa,+BAA+B,MAAM;CAChD,AAAO,YAAY,aAAqB,aAAuB;EAC7D,MACE,YAAY,YAAY,4CACnB,eAAe,YAAY,iHAElC;EACA,KAAK,OAAO;EACZ,aAAa,MAAM,sBAAsB;CAC3C;AACF"}

package/esm/in-app/base-notifications-repository.d.mts

@@ -0,0 +1,82 @@
+import { DatabasePayload, Id } from "../types.mjs";
+import { NotificationContract } from "../contracts/notification.contract.mjs";
+import { NotificationColumnMapHost } from "./column-map.mjs";
+import { DatabaseNotification } from "./database-notification.mjs";
+import { FilterRules, RepositoryManager } from "@warlock.js/core";
+
+//#region ../@warlock.js/notifications/src/in-app/base-notifications-repository.d.ts
+/**
+ * Filter shape — logical keys the repo understands. `filterBy` maps each to a
+ * physical column (or a predicate) derived from the model's `columnMap`.
+ */
+type NotificationsFilter = {
+  id?: Id;
+  type?: string; /** Mode-agnostic unread filter — resolves to the model's read-state column. */
+  unread?: boolean;
+  recipientId?: Id;
+  idempotencyKey?: string;
+};
+/** Class form of a `DatabaseNotification` subclass — what `configure()` accepts. */
+type NotificationModelClass = (new (...args: any[]) => DatabaseNotification) & NotificationColumnMapHost;
+declare class BaseNotificationsRepository<TModel extends NotificationContract = NotificationContract> extends RepositoryManager<TModel, NotificationsFilter> {
+  /** Resolved physical columns for the bound model — the single source. */
+  private readonly columns;
+  filterBy: FilterRules;
+  constructor(model?: NotificationModelClass);
+  /** The tenant column for this model, or `undefined` for single-tenant. */
+  get tenantColumn(): string | undefined;
+  /**
+   * Build `filterBy` from the resolved column map. `unread` is the
+   * mode-agnostic read filter; `isRead` / `readAt` / `tenant` are exposed for
+   * direct filtering only when the model declares those columns.
+   */
+  private buildFilterBy;
+  /**
+   * 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 —
+   * they're already physical. Used for every write / update / delete payload +
+   * filter (the paths `RepositoryManager` does NOT map).
+   */
+  protected toRow(obj: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Create one row for the recipient. New rows start unread; the tenant column
+   * (when the model declares one) is written from `tenantId`, which the
+   * database channel reads off the recipient.
+   *
+   * Idempotency: when `input.idempotencyKey` is set, find-or-create — return
+   * 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).
+   */
+  createFor(recipientId: Id, input: DatabasePayload, tenantId?: Id): Promise<TModel>;
+  /**
+   * Bulk-create one row per recipient sharing the same input + tenant. Reserved
+   * for the Phase-2 `Channel.sendMany` fan-out hook; not on the per-recipient
+   * send path yet.
+   */
+  createManyFor(recipientIds: Id[], input: DatabasePayload, tenantId?: Id): Promise<TModel[]>;
+  /**
+   * Mark rows read — recipient-scoped. `id` omitted → all unread rows for the
+   * recipient; `id` given → that one row, still scoped to the recipient. Scoped
+   * 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, id?: Id): Promise<number>;
+  /**
+   * 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, id?: Id): Promise<number>;
+  /** Find one row for a recipient (read path — `filterBy` maps the keys). */
+  findFor(recipientId: Id, id: Id): Promise<TModel | null>;
+  /**
+   * Delete rows — recipient-scoped. `id` omitted → clear all for the
+   * recipient; `id` given → that one row.
+   */
+  deleteFor(recipientId: Id, id?: Id): Promise<number>;
+  /** Read path — `filterBy` maps `recipientId`/`idempotencyKey` to columns. */
+  private firstByIdempotencyKey;
+}
+//#endregion
+export { BaseNotificationsRepository, NotificationModelClass, NotificationsFilter };
+//# sourceMappingURL=base-notifications-repository.d.mts.map

package/esm/in-app/base-notifications-repository.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-notifications-repository.d.mts","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/in-app/base-notifications-repository.ts"],"mappings":";;;;;;;;;;;KA2CY,mBAAA;EACV,EAAA,GAAK,EAAA;EACL,IAAA,WA0Ge;EAxGf,MAAA;EACA,WAAA,GAAc,EAAE;EAChB,cAAA;AAAA;;KAIU,sBAAA,YAAkC,IAAA,YAAgB,oBAAA,IAC5D,yBAAyB;AAAA,cAEd,2BAAA,gBACI,oBAAA,GAAuB,oBAAA,UAC9B,iBAAA,CAAkB,MAAA,EAAQ,mBAAA;EA4IvB;EAAA,iBA1IM,OAAA;EAEV,QAAA,EAAU,WAAA;cAEE,KAAA,GAAQ,sBAAA;EAkJgB;EAAA,IAtIhC,YAAA;EA8J6B;;;;;EAAA,QArJhC,aAAA;EAgLsB;;;;;;;EAAA,UArIpB,KAAA,CAAM,GAAA,EAAK,MAAA,oBAA0B,MAAA;EAvET;;;;;;;;;EA6FzB,SAAA,CACX,WAAA,EAAa,EAAA,EACb,KAAA,EAAO,eAAA,EACP,QAAA,GAAW,EAAA,GACV,OAAA,CAAQ,MAAA;EA9EA;;;;;EAsHJ,aAAA,CACL,YAAA,EAAc,EAAA,IACd,KAAA,EAAO,eAAA,EACP,QAAA,GAAW,EAAA,GACV,OAAA,CAAQ,MAAA;EAhDE;;;;;;EA4DN,QAAA,CAAS,WAAA,EAAa,EAAA,EAAI,EAAA,GAAK,EAAA,GAAK,OAAA;EAxDxC;;;;EAgFI,UAAA,CAAW,WAAA,EAAa,EAAA,EAAI,EAAA,GAAK,EAAA,GAAK,OAAA;EAtCpC;EAyDF,OAAA,CAAQ,WAAA,EAAa,EAAA,EAAI,EAAA,EAAI,EAAA,GAAK,OAAA,CAAQ,MAAA;EAxDpC;;;;EAgEN,SAAA,CAAU,WAAA,EAAa,EAAA,EAAI,EAAA,GAAK,EAAA,GAAK,OAAA;EAnDf;EAAA,QAwDrB,qBAAA;AAAA"}

package/esm/in-app/base-notifications-repository.mjs

@@ -0,0 +1,187 @@
+import { resolveColumnMap } from "./column-map.mjs";
+import { RepositoryManager } from "@warlock.js/core";
+
+//#region ../@warlock.js/notifications/src/in-app/base-notifications-repository.ts
+/**
+* Shipped behavior repository for the in-app store.
+*
+* Concrete (NOT abstract) so `inApp.configure({ model })` can
+* `new BaseNotificationsRepository(model)` without subclassing. The dev only
+* extends this when they need extra query methods.
+*
+* ## The single source of truth: the model's `columnMap`
+*
+* The model declares its physical columns ONCE via `static columnMap`. The
+* constructor resolves that map and derives BOTH sides from it:
+*
+*  - the READ path — `filterBy` maps logical keys (`recipientId`, `unread`,
+*    `type`, …) onto the model's columns; `RepositoryManager` applies it.
+*  - the WRITE / UPDATE / DELETE path — `createFor` / `markRead` / … translate
+*    logical keys through the same `filterBy` via `toRow`.
+*
+* Because both come from one `columnMap`, reads and writes can never target
+* different columns. `unread` is mode-agnostic: it filters `is_read = false`
+* when the model has that flag, otherwise `read_at IS NULL`.
+*
+* @example  default (SQL snake_case — no subclass needed)
+*   inApp.configure({ model: Notification })
+*
+* @example  custom columns — declare them on the model, not here
+*   class Notification extends DatabaseNotification {
+*     public static columnMap = { recipient: "audience_id", isRead: "seen" };
+*   }
+*/
+var BaseNotificationsRepository = class extends RepositoryManager {
+	/** Resolved physical columns for the bound model — the single source. */
+	columns;
+	filterBy;
+	constructor(model) {
+		super();
+		if (model) this.source = model;
+		this.columns = resolveColumnMap(model?.columnMap);
+		this.filterBy = this.buildFilterBy();
+	}
+	/** The tenant column for this model, or `undefined` for single-tenant. */
+	get tenantColumn() {
+		return this.columns.tenant;
+	}
+	/**
+	* Build `filterBy` from the resolved column map. `unread` is the
+	* mode-agnostic read filter; `isRead` / `readAt` / `tenant` are exposed for
+	* direct filtering only when the model declares those columns.
+	*/
+	buildFilterBy() {
+		const { recipient, tenant, readAt, isRead } = this.columns;
+		const rules = {
+			id: "=",
+			type: "=",
+			recipientId: ["=", recipient],
+			idempotencyKey: ["=", "idempotency_key"],
+			unread: (value, query) => {
+				if (value !== true && value !== "true") return;
+				if (isRead) query.where(isRead, false);
+				else if (readAt) query.whereNull(readAt);
+			}
+		};
+		if (isRead) rules.isRead = ["=", isRead];
+		if (readAt) rules.readAt = ["=", readAt];
+		if (tenant) rules.tenant = ["=", tenant];
+		return rules;
+	}
+	/**
+	* 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 —
+	* they're already physical. Used for every write / update / delete payload +
+	* filter (the paths `RepositoryManager` does NOT map).
+	*/
+	toRow(obj) {
+		const rules = this.filterBy;
+		const row = {};
+		for (const [logical, value] of Object.entries(obj)) {
+			const rule = rules[logical];
+			const column = Array.isArray(rule) ? rule[1] : logical;
+			row[column] = value;
+		}
+		return row;
+	}
+	/**
+	* Create one row for the recipient. New rows start unread; the tenant column
+	* (when the model declares one) is written from `tenantId`, which the
+	* database channel reads off the recipient.
+	*
+	* Idempotency: when `input.idempotencyKey` is set, find-or-create — return
+	* 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) {
+		const { idempotencyKey } = input;
+		if (idempotencyKey) {
+			const existing = await this.firstByIdempotencyKey(recipientId, idempotencyKey);
+			if (existing) return existing;
+		}
+		const row = {
+			recipientId,
+			...input
+		};
+		if (this.columns.isRead) row.isRead = false;
+		if (this.columns.tenant && tenantId !== void 0) row.tenant = tenantId;
+		try {
+			return await this.create(this.toRow(row));
+		} catch (error) {
+			if (idempotencyKey) {
+				const existing = await this.firstByIdempotencyKey(recipientId, idempotencyKey);
+				if (existing) return existing;
+			}
+			throw error;
+		}
+	}
+	/**
+	* Bulk-create one row per recipient sharing the same input + tenant. Reserved
+	* 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)));
+	}
+	/**
+	* Mark rows read — recipient-scoped. `id` omitted → all unread rows for the
+	* recipient; `id` given → that one row, still scoped to the recipient. Scoped
+	* 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) {
+		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,
+			...unreadScope,
+			...id !== void 0 ? { id } : {}
+		}), this.toRow(data));
+	}
+	/**
+	* 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) {
+		const { isRead, readAt } = this.columns;
+		const data = {};
+		if (isRead) data.isRead = false;
+		if (readAt) data.readAt = null;
+		return this.updateMany(this.toRow({
+			recipientId,
+			...id !== void 0 ? { id } : {}
+		}), this.toRow(data));
+	}
+	/** Find one row for a recipient (read path — `filterBy` maps the keys). */
+	findFor(recipientId, id) {
+		return this.first({
+			recipientId,
+			id
+		});
+	}
+	/**
+	* Delete rows — recipient-scoped. `id` omitted → clear all for the
+	* recipient; `id` given → that one row.
+	*/
+	deleteFor(recipientId, id) {
+		return this.deleteMany(this.toRow({
+			recipientId,
+			...id !== void 0 ? { id } : {}
+		}));
+	}
+	/** Read path — `filterBy` maps `recipientId`/`idempotencyKey` to columns. */
+	firstByIdempotencyKey(recipientId, idempotencyKey) {
+		return this.first({
+			recipientId,
+			idempotencyKey
+		});
+	}
+};
+
+//#endregion
+export { BaseNotificationsRepository };
+//# sourceMappingURL=base-notifications-repository.mjs.map

package/esm/in-app/base-notifications-repository.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-notifications-repository.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/in-app/base-notifications-repository.ts"],"sourcesContent":["/**\n * Shipped behavior repository for the in-app store.\n *\n * Concrete (NOT abstract) so `inApp.configure({ model })` can\n * `new BaseNotificationsRepository(model)` without subclassing. The dev only\n * extends this when they need extra query methods.\n *\n * ## The single source of truth: the model's `columnMap`\n *\n * The model declares its physical columns ONCE via `static columnMap`. The\n * constructor resolves that map and derives BOTH sides from it:\n *\n *  - the READ path — `filterBy` maps logical keys (`recipientId`, `unread`,\n *    `type`, …) onto the model's columns; `RepositoryManager` applies it.\n *  - the WRITE / UPDATE / DELETE path — `createFor` / `markRead` / … translate\n *    logical keys through the same `filterBy` via `toRow`.\n *\n * Because both come from one `columnMap`, reads and writes can never target\n * different columns. `unread` is mode-agnostic: it filters `is_read = false`\n * when the model has that flag, otherwise `read_at IS NULL`.\n *\n * @example  default (SQL snake_case — no subclass needed)\n *   inApp.configure({ model: Notification })\n *\n * @example  custom columns — declare them on the model, not here\n *   class Notification extends DatabaseNotification {\n *     public static columnMap = { recipient: \"audience_id\", isRead: \"seen\" };\n *   }\n */\nimport { type FilterRules, RepositoryManager } from \"@warlock.js/core\";\nimport type { NotificationContract } from \"../contracts\";\nimport type { DatabasePayload, Id } from \"../types\";\nimport {\n  type NotificationColumnMapHost,\n  type ResolvedNotificationColumnMap,\n  resolveColumnMap,\n} from \"./column-map\";\nimport type { DatabaseNotification } from \"./database-notification\";\n\n/**\n * Filter shape — logical keys the repo understands. `filterBy` maps each to a\n * physical column (or a predicate) derived from the model's `columnMap`.\n */\nexport type NotificationsFilter = {\n  id?: Id;\n  type?: string;\n  /** Mode-agnostic unread filter — resolves to the model's read-state column. */\n  unread?: boolean;\n  recipientId?: Id;\n  idempotencyKey?: string;\n};\n\n/** Class form of a `DatabaseNotification` subclass — what `configure()` accepts. */\nexport type NotificationModelClass = (new (...args: any[]) => DatabaseNotification) &\n  NotificationColumnMapHost;\n\nexport class BaseNotificationsRepository<\n  TModel extends NotificationContract = NotificationContract,\n> extends RepositoryManager<TModel, NotificationsFilter> {\n  /** Resolved physical columns for the bound model — the single source. */\n  private readonly columns: ResolvedNotificationColumnMap;\n\n  public filterBy: FilterRules;\n\n  public constructor(model?: NotificationModelClass) {\n    super();\n\n    if (model) {\n      this.source = model;\n    }\n\n    this.columns = resolveColumnMap(model?.columnMap);\n    this.filterBy = this.buildFilterBy();\n  }\n\n  /** The tenant column for this model, or `undefined` for single-tenant. */\n  public get tenantColumn(): string | undefined {\n    return this.columns.tenant;\n  }\n\n  /**\n   * Build `filterBy` from the resolved column map. `unread` is the\n   * mode-agnostic read filter; `isRead` / `readAt` / `tenant` are exposed for\n   * direct filtering only when the model declares those columns.\n   */\n  private buildFilterBy(): FilterRules {\n    const { recipient, tenant, readAt, isRead } = this.columns;\n\n    const rules: FilterRules = {\n      id: \"=\",\n      type: \"=\",\n      recipientId: [\"=\", recipient],\n      idempotencyKey: [\"=\", \"idempotency_key\"],\n      unread: (value, query) => {\n        if (value !== true && value !== \"true\") {\n          return;\n        }\n\n        if (isRead) {\n          query.where(isRead, false);\n        } else if (readAt) {\n          query.whereNull(readAt);\n        }\n      },\n    };\n\n    if (isRead) {\n      rules.isRead = [\"=\", isRead];\n    }\n\n    if (readAt) {\n      rules.readAt = [\"=\", readAt];\n    }\n\n    if (tenant) {\n      rules.tenant = [\"=\", tenant];\n    }\n\n    return rules;\n  }\n\n  /**\n   * Translate an object keyed by LOGICAL names into one keyed by PHYSICAL\n   * columns, using `filterBy` as the lookup. Keys with no `[op, column]` tuple\n   * (e.g. `title`, `body`, `payload`, `type`, `id`) pass through unchanged —\n   * they're already physical. Used for every write / update / delete payload +\n   * filter (the paths `RepositoryManager` does NOT map).\n   */\n  protected toRow(obj: Record<string, unknown>): Record<string, unknown> {\n    const rules = this.filterBy as Record<string, unknown>;\n    const row: Record<string, unknown> = {};\n\n    for (const [logical, value] of Object.entries(obj)) {\n      const rule = rules[logical];\n      const column = Array.isArray(rule) ? (rule[1] as string) : logical;\n      row[column] = value;\n    }\n\n    return row;\n  }\n\n  /**\n   * Create one row for the recipient. New rows start unread; the tenant column\n   * (when the model declares one) is written from `tenantId`, which the\n   * database channel reads off the recipient.\n   *\n   * Idempotency: when `input.idempotencyKey` is set, find-or-create — return\n   * the existing row instead of inserting a duplicate. A unique index on the\n   * key is the backstop for the rare insert race (we re-fetch on conflict).\n   */\n  public async createFor(\n    recipientId: Id,\n    input: DatabasePayload,\n    tenantId?: Id,\n  ): Promise<TModel> {\n    const { idempotencyKey } = input;\n\n    if (idempotencyKey) {\n      const existing = await this.firstByIdempotencyKey(recipientId, idempotencyKey);\n      if (existing) {\n        return existing;\n      }\n    }\n\n    const row: Record<string, unknown> = { recipientId, ...input };\n\n    if (this.columns.isRead) {\n      row.isRead = false;\n    }\n\n    if (this.columns.tenant && tenantId !== undefined) {\n      row.tenant = tenantId;\n    }\n\n    try {\n      return await this.create(this.toRow(row));\n    } catch (error) {\n      // Lost the insert race to a concurrent send with the same key → re-fetch.\n      if (idempotencyKey) {\n        const existing = await this.firstByIdempotencyKey(recipientId, idempotencyKey);\n        if (existing) {\n          return existing;\n        }\n      }\n\n      throw error;\n    }\n  }\n\n  /**\n   * Bulk-create one row per recipient sharing the same input + tenant. Reserved\n   * for the Phase-2 `Channel.sendMany` fan-out hook; not on the per-recipient\n   * send path yet.\n   */\n  public createManyFor(\n    recipientIds: Id[],\n    input: DatabasePayload,\n    tenantId?: Id,\n  ): Promise<TModel[]> {\n    return Promise.all(\n      recipientIds.map((recipientId) => this.createFor(recipientId, input, tenantId)),\n    );\n  }\n\n  /**\n   * Mark rows read — recipient-scoped. `id` omitted → all unread rows for the\n   * recipient; `id` given → that one row, still scoped to the recipient. Scoped\n   * to unread so a re-mark never overwrites an earlier `read_at` timestamp.\n   * Sets whichever read-state column(s) the model declares.\n   */\n  public markRead(recipientId: Id, id?: Id): Promise<number> {\n    const { isRead, readAt } = this.columns;\n    const unreadScope = isRead ? { isRead: false } : { readAt: null };\n\n    const data: Record<string, unknown> = {};\n\n    if (isRead) {\n      data.isRead = true;\n    }\n\n    if (readAt) {\n      data.readAt = new Date();\n    }\n\n    return this.updateMany(\n      this.toRow({ recipientId, ...unreadScope, ...(id !== undefined ? { id } : {}) }),\n      this.toRow(data),\n    );\n  }\n\n  /**\n   * Inverse of `markRead`, same recipient-scoping. No unread scope needed —\n   * clearing the read-state of an already-unread row is a no-op.\n   */\n  public markUnread(recipientId: Id, id?: Id): Promise<number> {\n    const { isRead, readAt } = this.columns;\n    const data: Record<string, unknown> = {};\n\n    if (isRead) {\n      data.isRead = false;\n    }\n\n    if (readAt) {\n      data.readAt = null;\n    }\n\n    return this.updateMany(\n      this.toRow({ recipientId, ...(id !== undefined ? { id } : {}) }),\n      this.toRow(data),\n    );\n  }\n\n  /** Find one row for a recipient (read path — `filterBy` maps the keys). */\n  public findFor(recipientId: Id, id: Id): Promise<TModel | null> {\n    return this.first({ recipientId, id } as NotificationsFilter);\n  }\n\n  /**\n   * Delete rows — recipient-scoped. `id` omitted → clear all for the\n   * recipient; `id` given → that one row.\n   */\n  public deleteFor(recipientId: Id, id?: Id): Promise<number> {\n    return this.deleteMany(this.toRow({ recipientId, ...(id !== undefined ? { id } : {}) }));\n  }\n\n  /** Read path — `filterBy` maps `recipientId`/`idempotencyKey` to columns. */\n  private firstByIdempotencyKey(recipientId: Id, idempotencyKey: string): Promise<TModel | null> {\n    return this.first({ recipientId, idempotencyKey } as NotificationsFilter);\n  }\n}\n"],"mappings":"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"}

package/esm/in-app/column-map.d.mts

@@ -0,0 +1,65 @@
+//#region ../@warlock.js/notifications/src/in-app/column-map.d.ts
+/**
+ * `columnMap` — how a notification model's logical roles map to the physical
+ * columns of ITS table. The ONE source the model getters, the repository
+ * (read filter + write mapping), the database channel, and the migration
+ * factory all read, so they can never drift apart.
+ *
+ * Declared as a `static columnMap` on the model and ejected to userland, so
+ * the dev owns it:
+ *
+ *   @RegisterModel()
+ *   export class Notification extends DatabaseNotification {
+ *     public static table = "notifications";
+ *     public static columnMap: NotificationColumnMap = {
+ *       tenant: "organization_id", // omit → single-tenant
+ *       readAt: "read_at",         // read-state (see below)
+ *     };
+ *   }
+ *
+ * ## Read-state is chosen by which keys are PRESENT
+ *
+ * - `readAt` only → unread = `read_at IS NULL`; marking read stamps it.
+ * - `isRead` only → unread = `is_read = false`; no timestamp.
+ * - both        → `is_read` is the indexed flag used for filtering, `read_at`
+ *                 records WHEN; marking read sets both.
+ *
+ * Declare neither and you get the `readAt`-only default — so a model can omit
+ * `columnMap` entirely and still work.
+ */
+/**
+ * The logical → physical column bindings a notification model may declare.
+ * Every key is optional; `resolveColumnMap` fills the defaults. Values are the
+ * app's real column names (rename-friendly: `readAt: "seen_at"`).
+ */
+type NotificationColumnMap = {
+  /** Recipient FK column. Default: `"user_id"`. */recipient?: string; /** Multi-tenant scope column, written from the recipient. Omit → single-tenant. */
+  tenant?: string; /** Read-timestamp column. Present → read-state records "when". */
+  readAt?: string; /** Read-flag column (indexed → fast unread filter). Present → read-state is a boolean. */
+  isRead?: string;
+};
+/**
+ * A `NotificationColumnMap` with the defaults applied. `recipient` is always
+ * set, and at least one of `readAt` / `isRead` is always present (the resolver
+ * falls back to `readAt`), so consumers never face a "no read-state" map.
+ */
+type ResolvedNotificationColumnMap = {
+  recipient: string;
+  tenant?: string;
+  readAt?: string;
+  isRead?: string;
+};
+/** A model class that may carry the `columnMap` static. */
+type NotificationColumnMapHost = {
+  columnMap?: NotificationColumnMap;
+};
+/**
+ * Resolve a model's declared `columnMap` into a complete map: default the
+ * recipient column, and fall back to a `read_at` timestamp when the model
+ * declares no read-state column. The fallback guarantees the result always
+ * has a usable read-state representation, so no boot-time validation is needed.
+ */
+declare function resolveColumnMap(map: NotificationColumnMap | undefined): ResolvedNotificationColumnMap;
+//#endregion
+export { NotificationColumnMap, NotificationColumnMapHost, ResolvedNotificationColumnMap, resolveColumnMap };
+//# sourceMappingURL=column-map.d.mts.map

package/esm/in-app/column-map.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-map.d.mts","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/in-app/column-map.ts"],"mappings":";;AAkCA;;;;;;;;;AAQQ;AAQR;;;;;;;;;AAIQ;AAIR;;;;AACmC;AAYnC;;;;;;;KArCY,qBAAA;EAuCoB,iDArC9B,SAAA;EAEA,MAAA;EAEA,MAAA;EAEA,MAAA;AAAA;;;;;;KAQU,6BAAA;EACV,SAAA;EACA,MAAA;EACA,MAAA;EACA,MAAA;AAAA;;KAIU,yBAAA;EACV,SAAA,GAAY,qBAAqB;AAAA;;;;;;;iBAYnB,gBAAA,CACd,GAAA,EAAK,qBAAA,eACJ,6BAA6B"}

package/esm/in-app/column-map.mjs

@@ -0,0 +1,28 @@
+//#region ../@warlock.js/notifications/src/in-app/column-map.ts
+const DEFAULT_RECIPIENT_COLUMN = "user_id";
+const DEFAULT_READ_AT_COLUMN = "read_at";
+/**
+* Resolve a model's declared `columnMap` into a complete map: default the
+* recipient column, and fall back to a `read_at` timestamp when the model
+* declares no read-state column. The fallback guarantees the result always
+* has a usable read-state representation, so no boot-time validation is needed.
+*/
+function resolveColumnMap(map) {
+	const recipient = map?.recipient ?? DEFAULT_RECIPIENT_COLUMN;
+	const tenant = map?.tenant;
+	if (!map?.readAt && !map?.isRead) return {
+		recipient,
+		tenant,
+		readAt: DEFAULT_READ_AT_COLUMN
+	};
+	return {
+		recipient,
+		tenant,
+		readAt: map.readAt,
+		isRead: map.isRead
+	};
+}
+
+//#endregion
+export { resolveColumnMap };
+//# sourceMappingURL=column-map.mjs.map

package/esm/in-app/column-map.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-map.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/in-app/column-map.ts"],"sourcesContent":["/**\n * `columnMap` — how a notification model's logical roles map to the physical\n * columns of ITS table. The ONE source the model getters, the repository\n * (read filter + write mapping), the database channel, and the migration\n * factory all read, so they can never drift apart.\n *\n * Declared as a `static columnMap` on the model and ejected to userland, so\n * the dev owns it:\n *\n *   @RegisterModel()\n *   export class Notification extends DatabaseNotification {\n *     public static table = \"notifications\";\n *     public static columnMap: NotificationColumnMap = {\n *       tenant: \"organization_id\", // omit → single-tenant\n *       readAt: \"read_at\",         // read-state (see below)\n *     };\n *   }\n *\n * ## Read-state is chosen by which keys are PRESENT\n *\n * - `readAt` only → unread = `read_at IS NULL`; marking read stamps it.\n * - `isRead` only → unread = `is_read = false`; no timestamp.\n * - both        → `is_read` is the indexed flag used for filtering, `read_at`\n *                 records WHEN; marking read sets both.\n *\n * Declare neither and you get the `readAt`-only default — so a model can omit\n * `columnMap` entirely and still work.\n */\n\n/**\n * The logical → physical column bindings a notification model may declare.\n * Every key is optional; `resolveColumnMap` fills the defaults. Values are the\n * app's real column names (rename-friendly: `readAt: \"seen_at\"`).\n */\nexport type NotificationColumnMap = {\n  /** Recipient FK column. Default: `\"user_id\"`. */\n  recipient?: string;\n  /** Multi-tenant scope column, written from the recipient. Omit → single-tenant. */\n  tenant?: string;\n  /** Read-timestamp column. Present → read-state records \"when\". */\n  readAt?: string;\n  /** Read-flag column (indexed → fast unread filter). Present → read-state is a boolean. */\n  isRead?: string;\n};\n\n/**\n * A `NotificationColumnMap` with the defaults applied. `recipient` is always\n * set, and at least one of `readAt` / `isRead` is always present (the resolver\n * falls back to `readAt`), so consumers never face a \"no read-state\" map.\n */\nexport type ResolvedNotificationColumnMap = {\n  recipient: string;\n  tenant?: string;\n  readAt?: string;\n  isRead?: string;\n};\n\n/** A model class that may carry the `columnMap` static. */\nexport type NotificationColumnMapHost = {\n  columnMap?: NotificationColumnMap;\n};\n\nconst DEFAULT_RECIPIENT_COLUMN = \"user_id\";\nconst DEFAULT_READ_AT_COLUMN = \"read_at\";\n\n/**\n * Resolve a model's declared `columnMap` into a complete map: default the\n * recipient column, and fall back to a `read_at` timestamp when the model\n * declares no read-state column. The fallback guarantees the result always\n * has a usable read-state representation, so no boot-time validation is needed.\n */\nexport function resolveColumnMap(\n  map: NotificationColumnMap | undefined,\n): ResolvedNotificationColumnMap {\n  const recipient = map?.recipient ?? DEFAULT_RECIPIENT_COLUMN;\n  const tenant = map?.tenant;\n\n  if (!map?.readAt && !map?.isRead) {\n    return { recipient, tenant, readAt: DEFAULT_READ_AT_COLUMN };\n  }\n\n  return {\n    recipient,\n    tenant,\n    readAt: map.readAt,\n    isRead: map.isRead,\n  };\n}\n"],"mappings":";AA8DA,MAAM,2BAA2B;AACjC,MAAM,yBAAyB;;;;;;;AAQ/B,SAAgB,iBACd,KAC+B;CAC/B,MAAM,YAAY,KAAK,aAAa;CACpC,MAAM,SAAS,KAAK;CAEpB,IAAI,CAAC,KAAK,UAAU,CAAC,KAAK,QACxB,OAAO;EAAE;EAAW;EAAQ,QAAQ;CAAuB;CAG7D,OAAO;EACL;EACA;EACA,QAAQ,IAAI;EACZ,QAAQ,IAAI;CACd;AACF"}

package/esm/in-app/database-notification.d.mts

@@ -0,0 +1,30 @@
+import { Id } from "../types.mjs";
+import { NotificationContract } from "../contracts/notification.contract.mjs";
+import { NotificationColumnMap, ResolvedNotificationColumnMap } from "./column-map.mjs";
+import { Model } from "@warlock.js/cascade";
+
+//#region ../@warlock.js/notifications/src/in-app/database-notification.d.ts
+declare abstract class DatabaseNotification extends Model implements NotificationContract {
+  /**
+   * Physical column bindings for THIS model's table. Override in the subclass;
+   * the empty default resolves to `{ recipient: "user_id", readAt: "read_at" }`.
+   */
+  static columnMap: NotificationColumnMap;
+  /** The resolved column map for this row's model — defaults applied. */
+  protected get columns(): ResolvedNotificationColumnMap;
+  get recipientId(): Id;
+  /** Tenant scope value, or `undefined` for single-tenant models. */
+  get tenantId(): Id | undefined;
+  get type(): string;
+  get isRead(): boolean;
+  get readAt(): Date | null;
+  /**
+   * Mark this row read. Sets whichever read-state column(s) the model
+   * declares — the boolean (fast unread filtering) and/or the timestamp
+   * (when it was read). Persists via `save()`.
+   */
+  markRead(): Promise<void>;
+}
+//#endregion
+export { DatabaseNotification };
+//# sourceMappingURL=database-notification.d.mts.map

package/esm/in-app/database-notification.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-notification.d.mts","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/in-app/database-notification.ts"],"mappings":";;;;;;uBA6BsB,oBAAA,SAA6B,KAAA,YAAiB,oBAAA;EAQzC;;;;EAAA,OAHX,SAAA,EAAW,qBAAA;EAiBd;EAAA,cAdG,OAAA,IAAW,6BAAA;EAAA,IAId,WAAA,IAAe,EAAA;EAwBL;EAAA,IAnBV,QAAA,IAAY,EAAA;EAAA,IAKZ,IAAA;EAAA,IAIA,MAAA;EAAA,IAUA,MAAA,IAAU,IAAA;;;;;;EAUR,QAAA,IAAY,OAAA;AAAA"}

package/esm/in-app/database-notification.mjs

@@ -0,0 +1,70 @@
+import { resolveColumnMap } from "./column-map.mjs";
+import { Model } from "@warlock.js/cascade";
+
+//#region ../@warlock.js/notifications/src/in-app/database-notification.ts
+/**
+* Shipped BASE in-app notification model. The scaffolded user model
+* `extends DatabaseNotification`, sets `static table`, and declares its
+* physical columns ONCE via `static columnMap`. Every accessor below derives
+* from that map, so the model, the repository, and the migration agree by
+* construction.
+*
+* The package ships NO concrete table or migration — those eject to userland
+* (thin eject). See `notificationColumns()` for the matching migration factory.
+*
+* @example
+*   @RegisterModel()
+*   export class Notification extends DatabaseNotification {
+*     public static table = "notifications";
+*     public static columnMap: NotificationColumnMap = {
+*       tenant: "organization_id",
+*       readAt: "read_at",
+*     };
+*   }
+*/
+var DatabaseNotification = class extends Model {
+	/**
+	* Physical column bindings for THIS model's table. Override in the subclass;
+	* the empty default resolves to `{ recipient: "user_id", readAt: "read_at" }`.
+	*/
+	static columnMap = {};
+	/** The resolved column map for this row's model — defaults applied. */
+	get columns() {
+		return resolveColumnMap(this.constructor.columnMap);
+	}
+	get recipientId() {
+		return this.get(this.columns.recipient);
+	}
+	/** Tenant scope value, or `undefined` for single-tenant models. */
+	get tenantId() {
+		const { tenant } = this.columns;
+		return tenant ? this.get(tenant) : void 0;
+	}
+	get type() {
+		return this.get("type");
+	}
+	get isRead() {
+		const { isRead, readAt } = this.columns;
+		if (isRead) return Boolean(this.get(isRead));
+		return readAt ? this.get(readAt) != null : false;
+	}
+	get readAt() {
+		const { readAt } = this.columns;
+		return readAt ? this.get(readAt) ?? null : null;
+	}
+	/**
+	* Mark this row read. Sets whichever read-state column(s) the model
+	* declares — the boolean (fast unread filtering) and/or the timestamp
+	* (when it was read). Persists via `save()`.
+	*/
+	async markRead() {
+		const { isRead, readAt } = this.columns;
+		if (isRead) this.set(isRead, true);
+		if (readAt) this.set(readAt, /* @__PURE__ */ new Date());
+		await this.save();
+	}
+};
+
+//#endregion
+export { DatabaseNotification };
+//# sourceMappingURL=database-notification.mjs.map

package/esm/in-app/database-notification.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-notification.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/in-app/database-notification.ts"],"sourcesContent":["/**\n * Shipped BASE in-app notification model. The scaffolded user model\n * `extends DatabaseNotification`, sets `static table`, and declares its\n * physical columns ONCE via `static columnMap`. Every accessor below derives\n * from that map, so the model, the repository, and the migration agree by\n * construction.\n *\n * The package ships NO concrete table or migration — those eject to userland\n * (thin eject). See `notificationColumns()` for the matching migration factory.\n *\n * @example\n *   @RegisterModel()\n *   export class Notification extends DatabaseNotification {\n *     public static table = \"notifications\";\n *     public static columnMap: NotificationColumnMap = {\n *       tenant: \"organization_id\",\n *       readAt: \"read_at\",\n *     };\n *   }\n */\nimport { Model } from \"@warlock.js/cascade\";\nimport type { NotificationContract } from \"../contracts\";\nimport type { Id } from \"../types\";\nimport {\n  type NotificationColumnMap,\n  type ResolvedNotificationColumnMap,\n  resolveColumnMap,\n} from \"./column-map\";\n\nexport abstract class DatabaseNotification extends Model implements NotificationContract {\n  /**\n   * Physical column bindings for THIS model's table. Override in the subclass;\n   * the empty default resolves to `{ recipient: \"user_id\", readAt: \"read_at\" }`.\n   */\n  public static columnMap: NotificationColumnMap = {};\n\n  /** The resolved column map for this row's model — defaults applied. */\n  protected get columns(): ResolvedNotificationColumnMap {\n    return resolveColumnMap((this.constructor as typeof DatabaseNotification).columnMap);\n  }\n\n  public get recipientId(): Id {\n    return this.get(this.columns.recipient);\n  }\n\n  /** Tenant scope value, or `undefined` for single-tenant models. */\n  public get tenantId(): Id | undefined {\n    const { tenant } = this.columns;\n    return tenant ? this.get(tenant) : undefined;\n  }\n\n  public get type(): string {\n    return this.get(\"type\");\n  }\n\n  public get isRead(): boolean {\n    const { isRead, readAt } = this.columns;\n\n    if (isRead) {\n      return Boolean(this.get(isRead));\n    }\n\n    return readAt ? this.get(readAt) != null : false;\n  }\n\n  public get readAt(): Date | null {\n    const { readAt } = this.columns;\n    return readAt ? (this.get(readAt) ?? null) : null;\n  }\n\n  /**\n   * Mark this row read. Sets whichever read-state column(s) the model\n   * declares — the boolean (fast unread filtering) and/or the timestamp\n   * (when it was read). Persists via `save()`.\n   */\n  public async markRead(): Promise<void> {\n    const { isRead, readAt } = this.columns;\n\n    if (isRead) {\n      this.set(isRead, true);\n    }\n\n    if (readAt) {\n      this.set(readAt, new Date());\n    }\n\n    await this.save();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAsB,uBAAtB,cAAmD,MAAsC;;;;;CAKvF,OAAc,YAAmC,CAAC;;CAGlD,IAAc,UAAyC;EACrD,OAAO,iBAAkB,KAAK,YAA4C,SAAS;CACrF;CAEA,IAAW,cAAkB;EAC3B,OAAO,KAAK,IAAI,KAAK,QAAQ,SAAS;CACxC;;CAGA,IAAW,WAA2B;EACpC,MAAM,EAAE,WAAW,KAAK;EACxB,OAAO,SAAS,KAAK,IAAI,MAAM,IAAI;CACrC;CAEA,IAAW,OAAe;EACxB,OAAO,KAAK,IAAI,MAAM;CACxB;CAEA,IAAW,SAAkB;EAC3B,MAAM,EAAE,QAAQ,WAAW,KAAK;EAEhC,IAAI,QACF,OAAO,QAAQ,KAAK,IAAI,MAAM,CAAC;EAGjC,OAAO,SAAS,KAAK,IAAI,MAAM,KAAK,OAAO;CAC7C;CAEA,IAAW,SAAsB;EAC/B,MAAM,EAAE,WAAW,KAAK;EACxB,OAAO,SAAU,KAAK,IAAI,MAAM,KAAK,OAAQ;CAC/C;;;;;;CAOA,MAAa,WAA0B;EACrC,MAAM,EAAE,QAAQ,WAAW,KAAK;EAEhC,IAAI,QACF,KAAK,IAAI,QAAQ,IAAI;EAGvB,IAAI,QACF,KAAK,IAAI,wBAAQ,IAAI,KAAK,CAAC;EAG7B,MAAM,KAAK,KAAK;CAClB;AACF"}

package/esm/in-app/in-app.d.mts

@@ -0,0 +1,56 @@
+import { DatabasePayload, Id, Notifiable } from "../types.mjs";
+import { Channel } from "../contracts/channel.contract.mjs";
+import { NotificationContract } from "../contracts/notification.contract.mjs";
+import { BaseNotificationsRepository, NotificationModelClass, NotificationsFilter } from "./base-notifications-repository.mjs";
+import { TypedRepositoryOptionsWithPages } from "@warlock.js/core";
+
+//#region ../@warlock.js/notifications/src/in-app/in-app.d.ts
+/**
+ * List options for the read methods — the repository's paginated options
+ * (`page` / `limit` / `orderBy` / filter keys). `recipientId` is always forced
+ * from the recipient argument, so passing it here has no effect.
+ */
+type NotificationsListOptions = TypedRepositoryOptionsWithPages<NotificationsFilter>;
+/**
+ * Configure options — discriminated so `model` and `repository` are mutually
+ * exclusive at the type level. Future knobs (cache / realtime / naming) slot
+ * in here without breaking the signature.
+ */
+type ConfigureOptions = {
+  model: NotificationModelClass;
+  repository?: never;
+} | {
+  repository: BaseNotificationsRepository;
+  model?: never;
+};
+declare class InApp {
+  private repo?;
+  /**
+   * Bind the in-app store AND return the `database` channel. Called once
+   * from `config/notifications.ts`. Subsequent calls REPLACE the binding.
+   */
+  configure(options: ConfigureOptions): Channel<DatabasePayload>;
+  private get repository();
+  /** General list — scoped to recipient; pass `options` for paging + filters. */
+  list(recipient: Notifiable | Id, options?: NotificationsListOptions): any;
+  /** Unread-only list — common case for badges + dashboards. */
+  listUnread(recipient: Notifiable | Id, options?: NotificationsListOptions): any;
+  /**
+   * Cached unread count — backs the badge. Auto-invalidated by the repo's
+   * model create/update events (`RepositoryManager.registerEvents`).
+   */
+  countUnread(recipient: Notifiable | Id): any;
+  /** Find one notification for a recipient — for a detail view. */
+  find(recipient: Notifiable | Id, id: Id): Promise<NotificationContract | null>;
+  /** Mark read — `id` omitted = all unread for this recipient. */
+  markAsRead(recipient: Notifiable | Id, id?: Id): Promise<number>;
+  /** Mark unread — same recipient-scoping. */
+  markAsUnread(recipient: Notifiable | Id, id?: Id): Promise<number>;
+  /** Delete/dismiss — `id` omitted = clear all for this recipient. */
+  dismiss(recipient: Notifiable | Id, id?: Id): Promise<number>;
+}
+/** Single in-app facade — bound at boot via `inApp.configure(...)`. */
+declare const inApp: InApp;
+//#endregion
+export { ConfigureOptions, NotificationsListOptions, inApp };
+//# sourceMappingURL=in-app.d.mts.map