@warlock.js/notifications 5.24.0 → 5.26.0

package/skills/send-ad-hoc/SKILL.md

@@ -1,95 +1,95 @@
----
-name: send-ad-hoc
-description: 'Ad-hoc per-channel send via the `notify.<channel>(to, payload, options?)` Proxy facade. Works for any channel registered in `NotificationChannels` (built-in or custom). `to` accepts a `Notifiable` model OR a raw route string (`"x@y.com"`); `payload` is typed per channel via the registry; `options` is the standard `SendOptions`. `notify.channel(name).send(...)` is the runtime escape when the channel name is not a compile-time literal. Type-based preference gating applies when a type is known — explicit via `options.type` OR auto-detected from a database payload''s `type` field. For multi-channel sends use `defineNotification` instead — there is no inline `notify(to, { via, ... })` form on purpose. Triggers: `notify.<channel>`, `notify.channel(name)`, `notify.mail`, `notify.database`, "send a one-off notification", "ad-hoc notification", "send an email without defining a notification", "raw email target", "dynamic channel name"; typical import `import { notify } from "@warlock.js/notifications"`. Skip: reusable multi-channel notifications — `@warlock.js/notifications/define-notification/SKILL.md`; configuring channels — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
----
-
-# `notify.<channel>` — ad-hoc, per-channel sends
-
-When you don't need a reusable definition — fire one channel, one recipient.
-
-```ts
-import { notify } from "@warlock.js/notifications";
-
-await notify.mail(user, { subject: "Welcome", html: "<p>Hi!</p>" });
-await notify.database(user, { type: "welcome", title: "Welcome!" });
-```
-
-For **multi-channel** sends, use [`defineNotification`](../define-notification/SKILL.md) — that's the reusable pattern and the only mental model for "send through several channels at once" (no inline multi-channel overload).
-
-## Shape
-
-```ts
-notify.<channel>(
-  to:      Notifiable | string,           // model OR raw route
-  payload: NotificationChannels[channel], // typed per channel
-  options?: SendOptions,
-): Promise<void>
-```
-
-## Raw target — no model
-
-Pass a string instead of a model to use the string as the route directly:
-
-```ts
-await notify.mail("guest@example.com", { subject: "Receipt", html: "<p>…</p>" });
-await notify.whatsapp("+201234567890", { body: "Promo: 20% off!" });  // Phase 2
-```
-
-When the recipient isn't a model, `PreferenceProvider` and `RateLimiter` are skipped — there's no `Notifiable` to consult.
-
-## Runtime-dynamic channel name
-
-When the channel isn't a literal, use `notify.channel(name).send(...)`:
-
-```ts
-const channelName = await chooseChannelForUser(user);
-await notify.channel(channelName).send(user, payload);
-```
-
-This is the only path with `unknown`-typed payloads — prefer the literal `notify.<channel>` when you can. `to` is still what decides the recipient: even for the `database` channel, a `recipientId`-shaped key on `payload` (or the model's physical recipient column name) is stripped before the row is built, so an untyped payload assembled from request JSON can't redirect the write to another recipient — see [`use-in-app/SKILL.md`](../use-in-app/SKILL.md#createfor-write-side--no-idor-either-since-4150).
-
-## Opt into preference/rate-limit gating
-
-Ad-hoc sends bypass the preference gate unless a notification `type` is known. Two ways to provide it:
-
-```ts
-// 1. Explicit — wins regardless of payload.
-await notify.mail(user, payload, { type: "marketing.weekly" });
-
-// 2. Auto-detected — database payloads carry their own `type` field.
-await notify.database(user, { type: "welcome", title: "Welcome!" });
-//                            ^^^^^^^^^^^^^^^ used for gating
-```
-
-`SendOptions.force === true` bypasses preferences. `RateLimiter` is consulted whenever a type is known (regardless of `force`).
-
-## Custom channels
-
-After registering a custom channel (see [`define-channel`](../define-channel/SKILL.md)), it's first-class:
-
-```ts
-await notify.discord(user, { content: "Build finished 🎉" });
-await notify.slack(staff, { text: "Deploy starting" });
-```
-
-## SendOptions (3rd arg)
-
-| Field | Effect |
-|---|---|
-| `delay` | Reserved for `.queue` paths; not used by `notify.<channel>` (sync). |
-| `locale` | Forwarded to the channel's `send({ options })`. |
-| `meta` | Forwarded to the channel + included in every observability event. |
-| `idempotencyKey` | Injected into the database payload (dedupe). |
-| `force` | Bypass `PreferenceProvider`. Does NOT bypass `RateLimiter`. |
-| `type` | Notification type for gating (ad-hoc only). |
-
-## Failure surfaces
-
-`notify.<channel>` rejects on configuration errors (`ChannelNotFoundError`) — those are loud, immediate, and don't fire a `failed` event. Channel-level send failures rethrow AND fire a `failed` event with the channel + error.
-
-## See also
-
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — front door + mental model.
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel.
-- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — register a custom channel.
-- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — `sending` / `sent` / `failed` / `skipped` events.
+---
+name: send-ad-hoc
+description: 'Ad-hoc per-channel send via the `notify.<channel>(to, payload, options?)` Proxy facade. Works for any channel registered in `NotificationChannels` (built-in or custom). `to` accepts a `Notifiable` model OR a raw route string (`"x@y.com"`); `payload` is typed per channel via the registry; `options` is the standard `SendOptions`. `notify.channel(name).send(...)` is the runtime escape when the channel name is not a compile-time literal. Type-based preference gating applies when a type is known — explicit via `options.type` OR auto-detected from a database payload''s `type` field. For multi-channel sends use `defineNotification` instead — there is no inline `notify(to, { via, ... })` form on purpose. Triggers: `notify.<channel>`, `notify.channel(name)`, `notify.mail`, `notify.database`, "send a one-off notification", "ad-hoc notification", "send an email without defining a notification", "raw email target", "dynamic channel name"; typical import `import { notify } from "@warlock.js/notifications"`. Skip: reusable multi-channel notifications — `@warlock.js/notifications/define-notification/SKILL.md`; configuring channels — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
+---
+
+# `notify.<channel>` — ad-hoc, per-channel sends
+
+When you don't need a reusable definition — fire one channel, one recipient.
+
+```ts
+import { notify } from "@warlock.js/notifications";
+
+await notify.mail(user, { subject: "Welcome", html: "<p>Hi!</p>" });
+await notify.database(user, { type: "welcome", title: "Welcome!" });
+```
+
+For **multi-channel** sends, use [`defineNotification`](../define-notification/SKILL.md) — that's the reusable pattern and the only mental model for "send through several channels at once" (no inline multi-channel overload).
+
+## Shape
+
+```ts
+notify.<channel>(
+  to:      Notifiable | string,           // model OR raw route
+  payload: NotificationChannels[channel], // typed per channel
+  options?: SendOptions,
+): Promise<void>
+```
+
+## Raw target — no model
+
+Pass a string instead of a model to use the string as the route directly:
+
+```ts
+await notify.mail("guest@example.com", { subject: "Receipt", html: "<p>…</p>" });
+await notify.whatsapp("+201234567890", { body: "Promo: 20% off!" });  // Phase 2
+```
+
+When the recipient isn't a model, `PreferenceProvider` and `RateLimiter` are skipped — there's no `Notifiable` to consult.
+
+## Runtime-dynamic channel name
+
+When the channel isn't a literal, use `notify.channel(name).send(...)`:
+
+```ts
+const channelName = await chooseChannelForUser(user);
+await notify.channel(channelName).send(user, payload);
+```
+
+This is the only path with `unknown`-typed payloads — prefer the literal `notify.<channel>` when you can. `to` is still what decides the recipient: even for the `database` channel, a `recipientId`-shaped key on `payload` (or the model's physical recipient column name) is stripped before the row is built, so an untyped payload assembled from request JSON can't redirect the write to another recipient — see [`use-in-app/SKILL.md`](../use-in-app/SKILL.md#createfor-write-side--no-idor-either-since-4150).
+
+## Opt into preference/rate-limit gating
+
+Ad-hoc sends bypass the preference gate unless a notification `type` is known. Two ways to provide it:
+
+```ts
+// 1. Explicit — wins regardless of payload.
+await notify.mail(user, payload, { type: "marketing.weekly" });
+
+// 2. Auto-detected — database payloads carry their own `type` field.
+await notify.database(user, { type: "welcome", title: "Welcome!" });
+//                            ^^^^^^^^^^^^^^^ used for gating
+```
+
+`SendOptions.force === true` bypasses preferences. `RateLimiter` is consulted whenever a type is known (regardless of `force`).
+
+## Custom channels
+
+After registering a custom channel (see [`define-channel`](../define-channel/SKILL.md)), it's first-class:
+
+```ts
+await notify.discord(user, { content: "Build finished 🎉" });
+await notify.slack(staff, { text: "Deploy starting" });
+```
+
+## SendOptions (3rd arg)
+
+| Field | Effect |
+|---|---|
+| `delay` | Reserved for `.queue` paths; not used by `notify.<channel>` (sync). |
+| `locale` | Forwarded to the channel's `send({ options })`. |
+| `meta` | Forwarded to the channel + included in every observability event. |
+| `idempotencyKey` | Injected into the database payload (dedupe). |
+| `force` | Bypass `PreferenceProvider`. Does NOT bypass `RateLimiter`. |
+| `type` | Notification type for gating (ad-hoc only). |
+
+## Failure surfaces
+
+`notify.<channel>` rejects on configuration errors (`ChannelNotFoundError`) — those are loud, immediate, and don't fire a `failed` event. Channel-level send failures rethrow AND fire a `failed` event with the channel + error.
+
+## See also
+
+- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — front door + mental model.
+- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel.
+- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — register a custom channel.
+- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — `sending` / `sent` / `failed` / `skipped` events.

package/skills/use-in-app/SKILL.md

@@ -1,172 +1,172 @@
----
-name: use-in-app
-description: 'Use the `inApp` facade for the in-app/database channel''s READ side: `inApp.configure({ model: Notification })` or `{ repository: myRepo }` binds the store AND returns the channel; `inApp.list / listUnread / countUnread / markAsRead / markAsUnread` are RECIPIENT-SCOPED by construction (no IDOR — `markAsRead(user, id)` cannot flip another user''s row even with a foreign id). `countUnread` uses `RepositoryManager.countCached` for the badge fast-path. Triggers: `inApp.configure`, `inApp.list`, `inApp.listUnread`, `inApp.countUnread`, `inApp.markAsRead`, `inApp.markAsUnread`, `BaseNotificationsRepository`, `DatabaseNotification`, `NotificationsFilter`, "in-app notifications", "mark notification as read", "unread count", "notification badge", "IDOR-safe markAsRead"; typical import `import { inApp } from "@warlock.js/notifications"`. Skip: writing notifications (use `defineNotification` or `notify.database`) — `@warlock.js/notifications/define-notification/SKILL.md`; the migration columns — `@warlock.js/notifications/write-notification-migration/SKILL.md`; wiring it into config — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
----
-
-# `inApp` — in-app notification read API
-
-The in-app database channel has two sides:
-
-- **Write side** — `notify.database(user, {...})` and the database channel inside `defineNotification` create rows.
-- **Read side** — `inApp.list` / `listUnread` / `countUnread` / `markAsRead` / `markAsUnread` query and mutate.
-
-`inApp.configure({ model | repository })` binds the same repository for both sides, so cache invalidation just works.
-
-## Configure (once, in `config/notifications.ts`)
-
-```ts
-// 90% case — pass the model class; default repo built internally.
-database: inApp.configure({ model: Notification }),
-
-// 10% case — pass a custom repo.
-database: inApp.configure({ repository: notificationsRepository }),
-```
-
-## Reads
-
-```ts
-import { inApp } from "@warlock.js/notifications";
-
-// all rows for this recipient (paginated via the repo's standard `list`)
-const all = await inApp.list(user);
-
-// unread-only — pass `filter` to add type/etc. constraints
-const unread = await inApp.listUnread(user, { type: "order.shipped" });
-
-// cached unread count — backs the badge
-const badge = await inApp.countUnread(user);
-
-// one notification — for a detail view (recipient-scoped)
-const one = await inApp.find(user, "ntf_123");
-```
-
-All read methods accept a cascade `Notifiable` model OR a raw `id` (string | number) — convenient when you only have an id without fetching the user.
-
-```ts
-await inApp.list("user_42");
-await inApp.countUnread(123);
-```
-
-## Writes (recipient-scoped → no IDOR)
-
-```ts
-// mark ALL unread rows for this recipient as read
-await inApp.markAsRead(user);
-
-// mark ONE specific row — STILL scoped to this recipient
-await inApp.markAsRead(user, "ntf_123");
-
-// inverse
-await inApp.markAsUnread(user, "ntf_123");
-
-// delete / dismiss — one row, or clear all for this recipient
-await inApp.dismiss(user, "ntf_123");
-await inApp.dismiss(user);
-```
-
-The recipient-id is forced into the `where` clause. A controller that receives an `id` from the request and naively calls `inApp.markAsRead(currentUser, id)` cannot accidentally flip another user's row — even if the request contains a forged id. The mutation will simply update 0 rows.
-
-## Behind the scenes — `columnMap` drives everything
-
-The model declares its physical columns ONCE via `static columnMap`. The
-shipped `DatabaseNotification` accessors and `BaseNotificationsRepository`
-(read filter + write mapping) both derive from it, so they can never drift:
-
-```ts
-abstract class DatabaseNotification extends Model implements NotificationContract {
-  public static columnMap: NotificationColumnMap = {};
-  // recipientId / tenantId / isRead / readAt / markRead all read `columnMap`.
-}
-
-class BaseNotificationsRepository extends RepositoryManager {
-  // constructor resolves the model's columnMap → builds `filterBy` +
-  // createFor / markRead / markUnread / deleteFor from it.
-  public createFor(recipientId, input, tenantId?)   { /* one insert, starts unread */ }
-}
-```
-
-### `createFor` write side — no IDOR either (since 4.15.0)
-
-`recipientId` is always the trusted argument, applied **after** the payload — `createFor`/`createManyFor` strip server-owned keys (`id`, `recipientId`, `tenant`, `readAt`, `isRead`, and their resolved `columnMap` physical column names) off `input` before merging. Before this, a caller passing an untyped payload straight through (request JSON, a channel's `send` args) could smuggle its own `recipientId` — or the raw physical column name — and write the notification into someone else's inbox. `type` / `title` / `body` / `payload` / `idempotencyKey` are untouched; you don't need to sanitize `input` yourself.
-
-### `columnMap` — map logical roles → your columns
-
-```ts
-export type NotificationColumnMap = {
-  recipient?: string; // recipient FK. Default "user_id"
-  tenant?: string;    // multi-tenant scope, written from the recipient. Omit → single-tenant
-  readAt?: string;    // read-timestamp column
-  isRead?: string;    // read-flag column (indexed)
-};
-```
-
-**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 filter flag, `read_at` records WHEN.
-
-Declare neither and you get the `readAt`-only default — so a model can omit
-`columnMap` entirely. `unread` is the mode-agnostic read filter on `inApp` /
-the repo; there is no `isRead` filter key to remember.
-
-## Your model — declare `table`, `schema`, and `columnMap`
-
-```ts title="src/app/notifications/notification.model.ts"
-import { RegisterModel } from "@warlock.js/cascade";
-import { v } from "@warlock.js/seal";
-import { DatabaseNotification, type NotificationColumnMap } from "@warlock.js/notifications";
-
-// Mirrors the migration columns; cascade validates + casts every write.
-const notificationSchema = v.object({
-  user_id: v.string(),
-  type: v.string(),
-  title: v.string(),
-  body: v.string().nullish(),
-  payload: v.record(v.any()).nullish(),
-  read_at: v.date().nullish(),
-  idempotency_key: v.string().nullish(),
-});
-
-@RegisterModel()
-export class Notification extends DatabaseNotification {
-  public static table = "notifications";
-  public static schema = notificationSchema;
-  // read_at-only, single-tenant. Add `tenant: "organization_id"` for multi-tenant,
-  // swap to `isRead: "is_read"` (or add it) to change the read-state representation.
-  public static columnMap: NotificationColumnMap = { readAt: "read_at" };
-}
-```
-
-To change columns, edit `columnMap` — the migration (`notificationColumns`), the
-repo filter, and the accessors all follow. For a different driver's naming
-(e.g. MongoDB camelCase), name the columns in `columnMap`
-(`{ recipient: "userId", readAt: "readAt" }`).
-
-## Custom repository (advanced, optional)
-
-`columnMap` already covers column naming. Subclass only for EXTRA query methods:
-
-```ts title="src/app/notifications/notifications.repository.ts"
-import { BaseNotificationsRepository } from "@warlock.js/notifications";
-import { Notification } from "./notification.model";
-
-export class NotificationsRepository extends BaseNotificationsRepository<Notification> {
-  public source = Notification; // its columnMap still drives filter + write mapping
-  // …extra methods specific to your app
-}
-export const notificationsRepository = new NotificationsRepository();
-```
-
-Then swap config:
-
-```ts
-database: inApp.configure({ repository: notificationsRepository }),
-```
-
-## See also
-
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire `inApp.configure` into the config.
-- [`write-notification-migration/SKILL.md`](../write-notification-migration/SKILL.md) — `notificationColumns(Notification)`, named from `columnMap`.
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — create rows via the database channel.
+---
+name: use-in-app
+description: 'Use the `inApp` facade for the in-app/database channel''s READ side: `inApp.configure({ model: Notification })` or `{ repository: myRepo }` binds the store AND returns the channel; `inApp.list / listUnread / countUnread / markAsRead / markAsUnread` are RECIPIENT-SCOPED by construction (no IDOR — `markAsRead(user, id)` cannot flip another user''s row even with a foreign id). `countUnread` uses `RepositoryManager.countCached` for the badge fast-path. Triggers: `inApp.configure`, `inApp.list`, `inApp.listUnread`, `inApp.countUnread`, `inApp.markAsRead`, `inApp.markAsUnread`, `BaseNotificationsRepository`, `DatabaseNotification`, `NotificationsFilter`, "in-app notifications", "mark notification as read", "unread count", "notification badge", "IDOR-safe markAsRead"; typical import `import { inApp } from "@warlock.js/notifications"`. Skip: writing notifications (use `defineNotification` or `notify.database`) — `@warlock.js/notifications/define-notification/SKILL.md`; the migration columns — `@warlock.js/notifications/write-notification-migration/SKILL.md`; wiring it into config — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
+---
+
+# `inApp` — in-app notification read API
+
+The in-app database channel has two sides:
+
+- **Write side** — `notify.database(user, {...})` and the database channel inside `defineNotification` create rows.
+- **Read side** — `inApp.list` / `listUnread` / `countUnread` / `markAsRead` / `markAsUnread` query and mutate.
+
+`inApp.configure({ model | repository })` binds the same repository for both sides, so cache invalidation just works.
+
+## Configure (once, in `config/notifications.ts`)
+
+```ts
+// 90% case — pass the model class; default repo built internally.
+database: inApp.configure({ model: Notification }),
+
+// 10% case — pass a custom repo.
+database: inApp.configure({ repository: notificationsRepository }),
+```
+
+## Reads
+
+```ts
+import { inApp } from "@warlock.js/notifications";
+
+// all rows for this recipient (paginated via the repo's standard `list`)
+const all = await inApp.list(user);
+
+// unread-only — pass `filter` to add type/etc. constraints
+const unread = await inApp.listUnread(user, { type: "order.shipped" });
+
+// cached unread count — backs the badge
+const badge = await inApp.countUnread(user);
+
+// one notification — for a detail view (recipient-scoped)
+const one = await inApp.find(user, "ntf_123");
+```
+
+All read methods accept a cascade `Notifiable` model OR a raw `id` (string | number) — convenient when you only have an id without fetching the user.
+
+```ts
+await inApp.list("user_42");
+await inApp.countUnread(123);
+```
+
+## Writes (recipient-scoped → no IDOR)
+
+```ts
+// mark ALL unread rows for this recipient as read
+await inApp.markAsRead(user);
+
+// mark ONE specific row — STILL scoped to this recipient
+await inApp.markAsRead(user, "ntf_123");
+
+// inverse
+await inApp.markAsUnread(user, "ntf_123");
+
+// delete / dismiss — one row, or clear all for this recipient
+await inApp.dismiss(user, "ntf_123");
+await inApp.dismiss(user);
+```
+
+The recipient-id is forced into the `where` clause. A controller that receives an `id` from the request and naively calls `inApp.markAsRead(currentUser, id)` cannot accidentally flip another user's row — even if the request contains a forged id. The mutation will simply update 0 rows.
+
+## Behind the scenes — `columnMap` drives everything
+
+The model declares its physical columns ONCE via `static columnMap`. The
+shipped `DatabaseNotification` accessors and `BaseNotificationsRepository`
+(read filter + write mapping) both derive from it, so they can never drift:
+
+```ts
+abstract class DatabaseNotification extends Model implements NotificationContract {
+  public static columnMap: NotificationColumnMap = {};
+  // recipientId / tenantId / isRead / readAt / markRead all read `columnMap`.
+}
+
+class BaseNotificationsRepository extends RepositoryManager {
+  // constructor resolves the model's columnMap → builds `filterBy` +
+  // createFor / markRead / markUnread / deleteFor from it.
+  public createFor(recipientId, input, tenantId?)   { /* one insert, starts unread */ }
+}
+```
+
+### `createFor` write side — no IDOR either (since 4.15.0)
+
+`recipientId` is always the trusted argument, applied **after** the payload — `createFor`/`createManyFor` strip server-owned keys (`id`, `recipientId`, `tenant`, `readAt`, `isRead`, and their resolved `columnMap` physical column names) off `input` before merging. Before this, a caller passing an untyped payload straight through (request JSON, a channel's `send` args) could smuggle its own `recipientId` — or the raw physical column name — and write the notification into someone else's inbox. `type` / `title` / `body` / `payload` / `idempotencyKey` are untouched; you don't need to sanitize `input` yourself.
+
+### `columnMap` — map logical roles → your columns
+
+```ts
+export type NotificationColumnMap = {
+  recipient?: string; // recipient FK. Default "user_id"
+  tenant?: string;    // multi-tenant scope, written from the recipient. Omit → single-tenant
+  readAt?: string;    // read-timestamp column
+  isRead?: string;    // read-flag column (indexed)
+};
+```
+
+**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 filter flag, `read_at` records WHEN.
+
+Declare neither and you get the `readAt`-only default — so a model can omit
+`columnMap` entirely. `unread` is the mode-agnostic read filter on `inApp` /
+the repo; there is no `isRead` filter key to remember.
+
+## Your model — declare `table`, `schema`, and `columnMap`
+
+```ts title="src/app/notifications/notification.model.ts"
+import { RegisterModel } from "@warlock.js/cascade";
+import { v } from "@warlock.js/seal";
+import { DatabaseNotification, type NotificationColumnMap } from "@warlock.js/notifications";
+
+// Mirrors the migration columns; cascade validates + casts every write.
+const notificationSchema = v.object({
+  user_id: v.string(),
+  type: v.string(),
+  title: v.string(),
+  body: v.string().nullish(),
+  payload: v.record(v.any()).nullish(),
+  read_at: v.date().nullish(),
+  idempotency_key: v.string().nullish(),
+});
+
+@RegisterModel()
+export class Notification extends DatabaseNotification {
+  public static table = "notifications";
+  public static schema = notificationSchema;
+  // read_at-only, single-tenant. Add `tenant: "organization_id"` for multi-tenant,
+  // swap to `isRead: "is_read"` (or add it) to change the read-state representation.
+  public static columnMap: NotificationColumnMap = { readAt: "read_at" };
+}
+```
+
+To change columns, edit `columnMap` — the migration (`notificationColumns`), the
+repo filter, and the accessors all follow. For a different driver's naming
+(e.g. MongoDB camelCase), name the columns in `columnMap`
+(`{ recipient: "userId", readAt: "readAt" }`).
+
+## Custom repository (advanced, optional)
+
+`columnMap` already covers column naming. Subclass only for EXTRA query methods:
+
+```ts title="src/app/notifications/notifications.repository.ts"
+import { BaseNotificationsRepository } from "@warlock.js/notifications";
+import { Notification } from "./notification.model";
+
+export class NotificationsRepository extends BaseNotificationsRepository<Notification> {
+  public source = Notification; // its columnMap still drives filter + write mapping
+  // …extra methods specific to your app
+}
+export const notificationsRepository = new NotificationsRepository();
+```
+
+Then swap config:
+
+```ts
+database: inApp.configure({ repository: notificationsRepository }),
+```
+
+## See also
+
+- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
+- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire `inApp.configure` into the config.
+- [`write-notification-migration/SKILL.md`](../write-notification-migration/SKILL.md) — `notificationColumns(Notification)`, named from `columnMap`.
+- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — create rows via the database channel.