@classytic/arc-notifications 0.8.0 → 0.10.0

package/llms.txt

@@ -0,0 +1,29 @@
+# @classytic/arc-notifications
+> Domain events and civil dates to multi-channel notifications on arc. Single entry `@classytic/arc-notifications`. Skill: skills/arc-notifications/SKILL.md
+
+| Need | Use |
+|---|---|
+| Event to notification | `NotifyTrigger` in `notificationsModule({ notifyOn })` |
+| Dispatch one trigger | `dispatchTrigger` |
+| Triggers owned by a bridge module | `notifyTriggerHandlers` |
+| Admin-editable trigger settings | `toNotifyTriggers`, `createCachedTriggerOverrideStore`, `resolveEffectiveSettings` |
+| Reminders relative to a record date | `createDateRuleEngine` |
+| Civil date math | `addCivilDays`, `civilDaysBetween`, `isCivilDateString`, `dueOccurrence`, `dateRuleWindow` |
+| Validate a rule schedule | `validateDateRuleSchedule` |
+| Fired-once ledger | `DateRuleLedger`, `createMemoryDateRuleLedger` |
+| In-app copy with {var} | `renderInApp`, `InAppTemplate` |
+| Feed row plus live push | `InAppChannel` |
+| Realtime-only push | `SseChannel` |
+| Feed REST | `inAppFeedResource` |
+| Unread badge cache | `createUnreadCountCache` |
+| Reconnect catch-up | `createInAppBackfill` |
+| Canonical list envelope | `feedListResult` |
+| markRead / markAllRead verbs | `FEED_ACTION_VERBS` |
+| Draftable templates | `createDbFirstResolver`, `templatesResource` |
+| Delivery evidence per rule | `createRepositoryDeliveryLog` |
+| Crash-safe bulk send | `notificationsJob` |
+| Channel names for an admin UI | `createNotificationChannelCatalog` |
+| Source-channel gating | `evaluateSourceChannel` |
+| Deterministic time in tests | `NotificationClock`, `systemNotificationClock` |
+
+Persistence for the ports (mongoose models, resources, suppression): @spinekit/core/notifications, skill spine-core-notifications.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-notifications",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Notifications module for @classytic/arc — domain events → multi-channel notifications via @classytic/notifications, with DB-draftable templates, repo-backed delivery log, and a templates resource",
   "type": "module",
   "exports": {
@@ -13,7 +13,9 @@
   "types": "./dist/index.d.mts",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "llms.txt"
   ],
   "publishConfig": {
     "access": "public"
@@ -29,10 +31,10 @@
     "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
   },
   "peerDependencies": {
-    "@classytic/arc": ">=2.40.0",
-    "@classytic/notifications": ">=2.5.0",
-    "@classytic/primitives": ">=0.27.0",
-    "@classytic/repo-core": ">=0.27.1"
+    "@classytic/arc": ">=2.46.0",
+    "@classytic/notifications": ">=2.7.0",
+    "@classytic/primitives": ">=0.34.0",
+    "@classytic/repo-core": ">=0.32.0"
   },
   "keywords": [
     "arc",

package/skills/arc-notifications/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: arc-notifications
+description: Compose notifications on arc with @classytic/arc-notifications. Event triggers, admin-editable trigger overrides, date-relative reminder rules, DB-draftable templates, in-app feed with realtime push and reconnect backfill, delivery log by rule. Use for notify, notification, reminder, bell, feed, SSE, delivery log, trigger, template.
+metadata:
+  minVersion: "0.9.0"
+---
+
+# @classytic/arc-notifications
+
+Domain events and civil dates to multi-channel notifications over `@classytic/notifications`. Single entry, no subpaths: import everything from `@classytic/arc-notifications`. Persistence stays in the host (mongokit repositories); this package owns the mechanism and the ports.
+
+## Do not hand-roll
+
+| Need | Use |
+|---|---|
+| Event to notification mapping | `NotifyTrigger` in `notificationsModule({ notifyOn })` |
+| Dispatch one trigger from a worker or test | `dispatchTrigger(service, trigger, event)` |
+| Triggers owned by a bridge module | `notifyTriggerHandlers({ name, service, triggers })` |
+| Admin-editable enabled / recipients / channels / copy | `toNotifyTriggers`, `createCachedTriggerOverrideStore`, `resolveEffectiveSettings` |
+| Reminders before / on / after a record date | `createDateRuleEngine` |
+| Civil date math (no instants, no zones) | `addCivilDays`, `civilDaysBetween`, `isCivilDateString`, `dueOccurrence`, `dateRuleWindow` |
+| Validate a rule schedule | `validateDateRuleSchedule` |
+| Fired-once ledger for a sweep | `DateRuleLedger` (host unique index), `createMemoryDateRuleLedger` (tests) |
+| `{var}` in-app copy | `renderInApp`, `InAppTemplate` |
+| Feed row plus live push in one send | `InAppChannel({ repository, port, unreadCache })` |
+| Realtime-only push | `SseChannel` |
+| Feed REST (list, unread-count, read, delete) | `inAppFeedResource` |
+| Unread badge cache | `createUnreadCountCache` |
+| Reconnect catch-up | `createInAppBackfill` |
+| Canonical list envelope for the feed | `feedListResult`, `listEnvelope: "offset"` |
+| markRead / markAllRead action verbs | `FEED_ACTION_VERBS`, `actions: true` |
+| Runtime-draftable templates | `createDbFirstResolver`, `templatesResource` |
+| Durable delivery evidence, per rule | `createRepositoryDeliveryLog`, `listByRule` |
+| Crash-safe bulk send | `notificationsJob` |
+| Channel names for an admin UI | `createNotificationChannelCatalog` |
+| Source-channel gating (web vs till) | `evaluateSourceChannel` |
+| Deterministic time in tests | `NotificationClock`, `systemNotificationClock` |
+
+## Golden path
+
+Event trigger with in-app copy, one send per recipient:
+
+```ts
+import { notificationsModule, type NotifyTrigger } from "@classytic/arc-notifications";
+
+type Assigned = { taskId: string; assigneeId: string; orgId: string };
+const assigned: NotifyTrigger = {
+  event: "task.assigned",
+  recipient: (e) => {
+    const p = e.payload as Assigned;
+    return { id: p.assigneeId, metadata: { organizationId: p.orgId } };
+  },
+  inApp: {
+    title: "New task",
+    message: "Task {taskId} is yours",
+    entityType: "task",
+    entityId: "{taskId}",
+  },
+};
+notificationsModule({ channels, notifyOn: [assigned], deliveryLog });
+```
+
+Persist and push with one channel, badge cache shared with the resource:
+
+```ts
+import {
+  InAppChannel,
+  createUnreadCountCache,
+  inAppFeedResource,
+} from "@classytic/arc-notifications";
+
+const unreadCache = createUnreadCountCache();
+const channel = new InAppChannel({ repository: feed, port, unreadCache });
+const resource = inAppFeedResource({
+  repository: feed,
+  resolveScope,
+  permissions,
+  port,
+  unreadCache,
+  listEnvelope: "offset",
+  actions: true,
+});
+```
+
+SSE reconnect: call on every stream open, pass the client cursor:
+
+```ts
+const backfill = createInAppBackfill({ repository: feed, port });
+backfill.onConnect(userId, orgId, { since: req.headers["last-event-id"] as string | undefined });
+```
+
+Delivery log with a rule column:
+
+```ts
+const log = createRepositoryDeliveryLog(repo, {
+  ruleId: (p) => /^rule\.(\w+)$/.exec(p.event)?.[1],
+});
+const rows = await log.listByRule(ruleId, { status: "failed", limit: 50 });
+```
+
+More: date rules `references/date-rules.md`, feed ports and backfill `references/feed.md`, trigger overrides and templates `references/triggers-templates.md`, delivery log and suppression `references/delivery-log.md`.
+
+## Gotchas
+
+- `InAppFeedRepository.claimUndelivered` is required by `createInAppBackfill`; it throws at construction without it. `listSince` is optional and only used when `since` is passed.
+- One `unreadCache` instance must be shared by `InAppChannel` and `inAppFeedResource`, else new rows ride the TTL.
+- The channel calls `port.push` once per recipient and event and never publishes on a bus. If your port forwards onto an event bus, give each frame its own correlation id.
+- `recipient.id` is the user and `recipient.metadata.organizationId` the tenant; without both the in-app channel skips (not fails).
+- Fan-out idempotency keys get a per-recipient suffix automatically; set `idempotencyKey` on the trigger, not per recipient.
+- A date source returns OPEN items only; resolved items stop appearing, that is how a repeating reminder ends.
+- Date rules take a civil date string; the host picks "today" in its own zone.
+- `ruleId` defaults to `payload.metadata.ruleId`; pass a resolver when it rides in the event name.
+- `feedListResult` and `listEnvelope: "offset"` are the repo-core `OffsetPaginationResult`; the default `{ data, pagination }` is the port's own page.
+- Realtime is best effort on top of the durable feed; never fail a request on a push error.
+
+## Never
+
+- Hand-roll a feed repository fan-out, unread counter, SSE replay, reminder cron per record, or delivery-log model: the ports above exist.
+- Read `node_modules` for the API; the barrel is the whole surface.
+- Deep-import `@classytic/arc-notifications/*`.
+- Store reminder state per record when the ledger gives once-per-occurrence.
+
+## References
+
+- `references/date-rules.md`: read when building reminders (sources, schedule, audience, ledger, sweep, preview, catalog, validate).
+- `references/feed.md`: read when wiring the in-app feed, realtime port, backfill, badge cache.
+- `references/triggers-templates.md`: read when adding admin-editable triggers, templates, channels.
+- `references/delivery-log.md`: read when recording or querying deliveries.
+- Spine persistence for these ports: skill `spine-core-notifications`.

package/skills/arc-notifications/references/date-rules.md

@@ -0,0 +1,55 @@
+# Date-relative rules
+
+`createDateRuleEngine` evaluates reminders before / on / after a date a host record carries, in ONE periodic sweep. A rule is data; the host owns rule persistence and the admin screen.
+
+## Shapes
+
+| Type | Fields |
+|---|---|
+| `DateRule` | `id` (stable, part of the ledger key), `enabled?`, `source`, `dateField`, `schedule`, `audience` (host type, passed to `resolveAudience`), `channels?`, `template?`, `inApp?`, `priority?`, `organizationId?` |
+| `DateRuleSchedule` | `offsetDays` (negative = before the date), `repeatEveryDays?`, `until?: { occurrences?, offsetDays? }` |
+| `DateRuleSource` | `key`, `label?`, `dateFields[{ key, label? }]`, `variables?`, `find({ dateField, from?, to, organizationId? })` returning OPEN items |
+| `DateRuleItem` | `id`, `date` (`YYYY-MM-DD`), `data` (template vars), `subject?` (`{ sourceModel, sourceId }`), `organizationId?` |
+| `DateRuleLedger` | `claim(key, info): Promise<boolean>` (true = first), `release(key)` |
+
+## Engine
+
+```ts
+import { createDateRuleEngine, createMemoryDateRuleLedger } from "@classytic/arc-notifications";
+
+const engine = createDateRuleEngine({
+  sources: [
+    {
+      key: "invoice",
+      dateFields: [{ key: "dueOn" }],
+      variables: ["number"],
+      find: ({ dateField, from, to }) => invoices.openWithDateBetween(dateField, from, to),
+    },
+  ],
+  rules: () => ruleRepo.enabledDateRules(),
+  resolveAudience: (audience, { item }) => directory.recipients(audience, item),
+  service: () => app.notifications!,
+  ledger: createMemoryDateRuleLedger(), // tests; production: unique-index ledger
+});
+const result = await engine.sweep("2026-10-22"); // { date, rules, due, fired, duplicates, noRecipients, failed }
+```
+
+| Method | Use |
+|---|---|
+| `sweep(today)` | run daily from a scheduled job; safe to re-run, replicas and restarts do not double send |
+| `preview(rule, today)` | admin "who would be told today"; no claims, no sends |
+| `catalog()` | rule editor: sources, date fields, variables |
+| `validate({ source, dateField, schedule })` | message list on rule save; empty = valid |
+
+Options: `ledger` (default in-memory, lost on restart), `graceDays` (how long after a missed day an occurrence still fires), `data(rule, item)` (extra template vars), `onError(err, { ruleId, itemId? })`.
+
+## Ledger
+
+Key is `dateRuleOccurrenceKey(ruleId, itemId, on)`. The claim happens BEFORE dispatch and is released on failure, so the next sweep retries. Production ledger = a collection with a unique index on the key (and a TTL on its creation time).
+
+## Rules of thumb
+
+- Dates are civil (`YYYY-MM-DD`); compute "today" in the operator's zone before calling `sweep`.
+- Pure helpers for tests and UIs: `dueOccurrence`, `dateRuleWindow`, `validateDateRuleSchedule`, `addCivilDays`, `civilDaysBetween`, `isCivilDateString`.
+- Dispatch reuses `dispatchTrigger`: in-app copy is rendered once, idempotency keys are per recipient, `subject` lands on the delivery log.
+- Return only open items from `find`; never filter "already reminded" in the source, the ledger does that.

package/skills/arc-notifications/references/delivery-log.md

@@ -0,0 +1,33 @@
+# Delivery log
+
+`createRepositoryDeliveryLog(repository, options)` returns a `RepositoryDeliveryLog`: the kernel `DeliveryLog` (`record`, `query`, `get`) plus `listByRule`. It works over any arc `RepositoryLike` (mongokit, sqlitekit, prismakit).
+
+| Option | Default | Use |
+|---|---|---|
+| `defaultLimit` | 100 | cap for `query` and `listByRule` |
+| `clock` | real time | source of `timestamp` |
+| `ruleId(payload)` | `payload.metadata.ruleId` | which authored rule sent it |
+| `extraFields(payload, dispatch)` | none | host-typed columns stored on `DeliveryLogDoc.extraFields` |
+
+```ts
+const log = createRepositoryDeliveryLog<{ attempt: number }>(repo, {
+  ruleId: (p) => /^rule\.(\w+)$/.exec(p.event)?.[1],
+  extraFields: (_p, d) => ({ attempt: d.sent + d.failed }),
+});
+await log.listByRule(ruleId, { status: "failed", limit: 50 }); // newest first, RuleDeliveryLogEntry[]
+```
+
+`DeliveryLogByRuleQuery`: `limit`, `status`, `after`, `before`.
+
+## Stored document (`DeliveryLogDoc`)
+
+`timestamp`, `event`, `recipientId?`, `recipientEmail?`, `channels`, `results` (per-channel `SendResult`, keep `providerMessageId`), `status` (`delivered | partial | failed | skipped`), `duration`, `metadata?`, `organizationId` (`null` = company-wide), `subject?`, `ruleId?`, `extraFields?`.
+
+## Store requirements
+
+- Indexes: `(ruleId, timestamp -1)`, `(subject.sourceModel, subject.sourceId, timestamp -1)`, `(organizationId, timestamp -1)`, `results.providerMessageId` (sparse, not unique), and a TTL on `timestamp` for retention.
+- Nothing edits or deletes rows by hand; retention is the TTL.
+
+## Suppression (persistence side)
+
+Suppression is a send-path guard, not part of this package: one row per (channel, canonical recipient), checked before the connector resolves credentials, failing OPEN on a store error, with an optional expiry for a temporary suppression. `@spinekit/core/notifications` ships it (`createSuppressionService`); see skill `spine-core-notifications`.

package/skills/arc-notifications/references/feed.md

@@ -0,0 +1,55 @@
+# In-app feed, realtime, backfill
+
+The host (or `@spinekit/core/notifications`) owns persistence. The package owns the port, channel, resource and helpers.
+
+## Port: `InAppFeedRepository`
+
+| Method | Required | Notes |
+|---|---|---|
+| `create(row)` | yes | called by `InAppChannel`; returns `{ id }` |
+| `listForUser(org, user, { page, limit, unreadOnly, type })` | yes | returns `{ data, pagination: { page, limit, total, totalPages } }` |
+| `countUnread(org, user)` | yes | badge |
+| `markRead(org, user, id)` | yes | `null` when missing or not theirs |
+| `markAllRead(org, user)` | yes | modified count |
+| `claimUndelivered(org, user, limit)` | for backfill | ATOMIC fetch-and-mark-delivered |
+| `listSince(org, user, since, limit)` | optional | rows created after `since` (Date), oldest first, no claim |
+| `markDelivered(org, user, id)` | optional | stamp a live-pushed row |
+| `delete(org, user, id)`, `deleteRead(org, user)` | optional | mounts `DELETE /:id`, `DELETE /read` |
+
+Delivered is not read: delivered = a realtime client received it (backfill axis), read = the user acted (badge axis).
+
+## Resource
+
+```ts
+inAppFeedResource({
+  repository,
+  resolveScope,
+  permissions,
+  port,
+  unreadCache, // read-sync to other tabs, cached badge
+  listEnvelope: "offset", // GET / answers OffsetPaginationResult
+  actions: true, // POST /:id/action markRead, POST /action markAllRead
+  prefix: "/notifications",
+  maxLimit: 50,
+});
+```
+
+Routes: `GET /`, `GET /unread-count`, `PATCH /:id/read`, `PATCH /read-all`, `DELETE /read`, `DELETE /:id`. `FEED_ACTION_VERBS` is `{ markRead, markAllRead }`.
+
+## Reconnect
+
+```ts
+const backfill = createInAppBackfill({ repository: feed, port, debounceMs: 2000, limit: 100 });
+backfill.onConnect(userId, orgId); // claim what was never delivered
+backfill.onConnect(userId, orgId, { since: lastEventId }); // plus replay the gap via listSince
+```
+
+One bulk event (`notification:backfill`) per connect burst; tabs opening together coalesce to the earliest cursor; a row is never in the event twice. Call `close()` on shutdown.
+
+## Clock
+
+`createUnreadCountCache({ clock })` takes a `NotificationClock` (`{ now(): Date }`). Persistence stamps (created / read / delivered) take the same clock in the host repository.
+
+## Transport stays host-owned
+
+`RealtimePushPort.push(userId, orgId, event, data)` is the only seam: SSE hub, WebSocket hub or an event bus behind it. The stream endpoint, heartbeats and connection registry are not in this package. If the port publishes onto an event bus, use a distinct correlation id per frame.

package/skills/arc-notifications/references/triggers-templates.md

@@ -0,0 +1,36 @@
+# Triggers, overrides, templates, channels
+
+## `NotifyTrigger` (runtime shape)
+
+`{ event, template?, channels?, recipient? | audience?, inApp?, priority?, data?, subject?, idempotencyKey?, enabled? }`
+
+- `recipient(event)` returns `Recipient | Recipient[] | null`; `audience(event)` plus `recipientResolver` on the module resolves a host audience instead.
+- `data(event)` defaults to the payload object. `inApp` renders once per event with `{var}` placeholders.
+- `subject(event)` stamps `{ sourceModel, sourceId }` on every delivery row.
+- Fan-out: one `service.send` per recipient, key `<base>:<recipient id | email | index>`.
+
+## Admin-editable triggers
+
+Author with `NotificationTrigger` (`event`, `template { title, message, link?, entityType? }`, `recipients` roles, `audienceType`, `priority`, extract). Convert with `toNotifyTriggers(triggers, { overrides, entityIdVars?, onDecision? })`; with `overrides` each trigger becomes one entry per channel, gated on stored settings.
+
+| Need | API |
+|---|---|
+| Per-org override rows with TTL cache | `createCachedTriggerOverrideStore(load, { ttlMs })` (`TriggerOverrideStore.forOrganization`) |
+| Effective settings of a trigger | `resolveEffectiveSettings` |
+| Gate by where the event came from | `evaluateSourceChannel`, `NotificationExtractResult.sourceChannel` |
+| Registry introspection | `getTriggersByEvent`, `getRegisteredEvents`, `getRecipientMatrix` |
+| Channel names for the editor | `createNotificationChannelCatalog(connectorChannels)` (always includes `IN_APP_CHANNEL`) |
+
+Spine ships the mongoose model and admin resource for overrides; see skill `spine-core-notifications`.
+
+## Templates
+
+`createDbFirstResolver({ store, fallback, cacheTtlMs, escape, onError })`: an active DB row wins, the code template is the safety net. `templatesResource({ repository, permissions, defaults, resolver })` is the drafting surface (CRUD, `/defaults`, `/preview`); pass the same `resolver` so a save invalidates its cache.
+
+## Module and queue
+
+```ts
+notificationsModule({ channels, notifyOn, recipientResolver, deliveryLog, idempotency, queue });
+```
+
+`queue: (f) => notificationsJob({ concurrency: 5 }).toQueueAdapter(f.jobs)` routes sends through arc's jobs plugin for crash-safe bulk sends. Provider channels (email, SMS, WhatsApp) come from `@classytic/notifications` or `@spinekit/integrations/channel`; this package adds only `InAppChannel` and `SseChannel`.