add-api-plugin-notifications

Package: @suaveplan/api-plugin-notifications Status: PROPOSED Type: new-package Design: (none — straightforward migration; see this proposal + spec delta) Spec delta: ./specs/api-plugin-notifications/spec.md

Why

Genesis ships the foundational pieces of @suaveplan/api (database, search, events, auth, site, etc.) but is missing the notifications plugin — in-app notification CRUD, device-token registration, and APN push delivery. Without this plugin, downstream apps that need lock-screen pushes or in-app notification feeds have to hand-roll the surface. Upstream enterprise/api-plugin-notifications.md documents the audit (4 *.test.ts files, two .spec.ts Playwright integration files, the APN mock smell, the mock middleware no-op, and the autoCleanOldDays abandoned config flag).

This change brings the package across at full functional parity, adapted to the genesis @suaveplan/api plugin shape (PluginDescriptor, ctx.getService(...)), the genesis DatabaseAdapter positional-param surface, and the ctx.eventBus cross-plugin emission pattern. The local-emitter wart and the APN mock are both replaced — the APN service now shapes payloads against a pluggable transport interface (ApnTransport) so the plugin never depends on a concrete APN client library. Production hosts inject a node-apn adapter; the plugin ships a deterministic MemoryApnTransport that records every send for hermetic tests.

What changes

ADDED: createNotificationsPlugin(options?) — factory returning a PluginDescriptor<NotificationsPluginConfig> for @suaveplan/api.
ADDED: NotificationsPluginOptionsSchema / NotificationsPluginConfig / NotificationsPluginConfigInput — Zod-validated config (basePath, pushBasePath, enablePush, apn, autoCleanOldDays, maxBulkRecipients).
ADDED: ApnConfigSchema / ApnConfig — Zod validation of the APN config bundle (cert/key/pfx/token + topic + production + network knobs).
ADDED: NotificationRepository + INotificationRepository — SurrealDB-backed notification CRUD repository over the genesis SurrealAdapter service slot.
ADDED: DeviceTokenRepository + IDeviceTokenRepository — SurrealDB-backed device-token CRUD repository.
ADDED: createNotificationsRoutes — Hono OpenAPI route module with 11 endpoints (list / unread-count / create / get / patch / read / read-many / read-all / dismiss / delete / grouped collapses into list).
ADDED: createPushRoutes — Hono OpenAPI route module with 5 endpoints (register / unregister / list tokens / send / send-bulk).
ADDED: ApnService + createApnService — APN delivery service with a pluggable transport.
ADDED: MemoryApnTransport + createMemoryApnTransport + ApnTransport / ApnTransportNotification / ApnTransportResponse / ApnTransportFactory — the transport contract and a deterministic default implementation.
ADDED: NOTIFICATIONS_PLUGIN_CODES registry + NotificationsPluginError class — 18 stable codes spanning configuration, lifecycle, repository, device-token, route, and APN failure modes.
ADDED: OTel instruments — 6 counters (notificationsCreatedTotal, notificationsReadTotal, notificationsDeletedTotal, pushSentTotal{platform}, pushFailedTotal{reason}, deviceTokensRegisteredTotal{platform}).
ADDED: ServiceRegistry augmentation — notificationRepository, deviceTokenRepository, apnService slots become available to downstream plugins via typed ctx.getService(...).
ADDED: Local Zod schemas for notification and push surfaces (NotificationSchema, CreateNotificationSchema, UpdateNotificationSchema, NotificationQuerySchema, NotificationListResponseSchema, MarkManyAsReadSchema, DeviceTokenSchema, RegisterDeviceTokenSchema, SendPushNotificationSchema, SendBulkPushNotificationSchema, etc.) — @suaveplan/api-schemas on genesis does not yet ship a notification subpath, so the plugin owns the boundary schemas.
ADDED: surql/tables/notification.surql + surql/tables/device_token.surql — slimmed migrations covering only the columns the repositories read/write. The upstream cross-plugin permission rules, stored helper functions (fn::notification::*, fn::device::token::*, fn::push::queue::*, fn::push::history::*), bitwise-typed notification-type constants, and push_notification_queue / push_notification_history tables are excluded (see below).
ADDED: NotificationsPluginEvents event-map keys — notifications:initialized, notifications:ready, notification:created, notification:read, notification:dismissed, notification:deleted, notification:push:sent, notification:push:failed, notification:device:registered, notification:device:unregistered.

Excluded from this migration

These items from enterprise/api-plugin-notifications.md "Required enterprise-quality improvements" and "Feature-rich enhancements" are deferred because each requires cross-package deps that don't yet exist on genesis (the same scope-out pattern that add-api-plugin-events used for fn::notification, fn::bitwise, fn::group references):

Real @parse/node-apn integration in the production codepath — the catalog deliberately omits @parse/node-apn. The migration ships an ApnTransport injection contract instead; production hosts add the library to their application dependencies and inject a node-apn-backed transport. The deterministic MemoryApnTransport ships with the plugin and is the default in tests + dev.
FCM / Web Push / Email / SMS / Slack channels — depend on @suaveplan/notification-channel, @suaveplan/emailer, @suaveplan/sms-providers, @suaveplan/slack-client which are not yet on genesis. Deferred to add-api-plugin-notifications-channels.
autoCleanOldDays scheduled cleanup — deleteOldRead(daysOld) is shipped on the repository and is callable; wiring it through @suaveplan/job-scheduler on onReady waits for the job-scheduler plugin (concurrent migration). Deferred to add-api-plugin-notifications-cleanup-job.
Preference center, quiet hours, templates, suppression lists, delivery tracking, batching+backoff queue, rich media, digests, in-app SSE/WS — every one of these requires a sibling plugin that doesn't exist on genesis yet (@suaveplan/templates, @suaveplan/suppression, @suaveplan/delivery-tracking, @suaveplan/queue, @suaveplan/api-plugin-sse, @suaveplan/websocket-gateway, @suaveplan/datetime, @suaveplan/i18n). Each lands in its own follow-up change.
Auth gating via @suaveplan/api-plugin-auth — this plugin reads c.get("user") (set by the host's auth middleware) and raises UNAUTHENTICATED when missing; explicit requireAuth() composition is a host-level concern.
Audit-log emission, idempotency, rate-limit — depend on @suaveplan/api-plugin-audit, @suaveplan/idempotency, @suaveplan/api-plugin-rate-limit (concurrent migrations); will be composed at the host level once they land.
Upstream push_notification_queue / push_notification_history tables, fn::push::queue::*, fn::push::history::*, fn::notification::create / should_create / friend_request / post_like / comment SurrealQL helpers — all reference record<site> / record<post> / record<comment> / record<group> types and call fn::bitwise::has_bits / fn::settings::get / fn::session::is_root which only exist inside sibling plugins (api-plugin-site, api-plugin-bitwise, api-plugin-groups). To avoid hand-rolling four downstream plugins as a side-quest, the migration ships a slimmer schema covering only the columns the repositories read / write; queue + history + helper functions migrate when their dependent plugins land.

Source mapping

This change derives from ../suaveplan/enterprise/api-plugin-notifications.md and the upstream source at ../suaveplan/packages/server/api-plugin-notifications/.

Requirement	Source lines	Notes
Plugin factory `createNotificationsPlugin(config?)`	enterprise.md L17-L29; src/index.ts L64-L130	reworded — genesis uses `PluginDescriptor` not `Plugin<NotificationConfig>`
Config schema (basePath, pushBasePath, enablePush, apn, autoCleanOldDays)	enterprise.md L13, L27-L56; src/index.ts L27-L56	extended with `pushBasePath` and `maxBulkRecipients` for genesis route-mount + bulk cap
Plugin dependencies: `["database"]`	enterprise.md L18; src/index.ts L75	verbatim
`migrationsPath` removed in genesis	enterprise.md L86; src/index.ts L86	the database plugin owns migration application in genesis
NotificationRepository: create/findById/findByRecipient/getUnreadCount/update/markAsRead/markManyAsRead/markAllAsRead/dismiss/delete/findGroupedByType/deleteOldRead	src/repository/notification.repository/notification.repository.ts	reworded — typed `db.create/select/update/delete` replaced by positional SurQL (api-plugin-events Path-A pattern); upstream `getById` → `findById`, `getByRecipient` → `findByRecipient`, `getGroupedByType` → `findGroupedByType`, `deleteOldNotifications` → `deleteOldRead`
DeviceTokenRepository: register/findById/findByToken/findActiveForUser/deactivate/deactivateByToken/touchLastUsed/cleanup	upstream surql/tables/device_token.surql helpers	new — upstream put device-token CRUD in stored functions; genesis pulls them up into a TS repository so the plugin can run without the surql helpers
createNotificationsRoutes (11 endpoints)	src/routes/notifications/notifications.ts	verbatim — `ctx.eventBus` replaces local `EventEmitter`; `grouped` collapses into list filter
createPushRoutes (5 endpoints)	src/routes/push/push.ts	reworded — `device_registration` table folded into `device_token`; bulk send capped by `maxBulkRecipients` schema bound
APNService (initialize/sendNotification/sendBulkNotifications/shutdown/isInitialized)	src/services/apn/apn.service.ts	reworded — `apn.Provider` swapped for an injectable `ApnTransport`; same payload shape, same `validateConfig` rules, same `mapResponse` semantics
MemoryApnTransport (deterministic in-memory delivery)	n/a (genesis-original)	required because the genesis catalog omits `@parse/node-apn`
`notification` SurrealQL table	upstream surql/tables/notification.surql	slimmed — see `## Excluded from this migration`
`device_token` SurrealQL table	upstream surql/tables/device_token.surql	slimmed

Requirements with no source line

Requirement	Justification
100% test / branch / function / line coverage	Genesis-wide policy (CLAUDE.md "Quality", AGENTS.md §7).
`defineCodes("NOTIFICATIONS_PLUGIN", [...])` namespace	Genesis convention; avoids collision with `EVENTS` (`@suaveplan/events`) and `EVENTS_PLUGIN` (`@suaveplan/api-plugin-events`).
OTel instruments via `metrics.getMeter("@suaveplan/api-plugin-notifications")`	Genesis-wide observability policy; emitted from production paths and asserted with a real in-memory `MeterProvider` (AGENTS.md §13).
Use `ctx.eventBus` from `@suaveplan/api-plugin` context, not a local `EventEmitter`	Fixes the upstream smell where notifications fired into a private `EventEmitter` invisible to siblings.
Subpath exports per feature module	AGENTS.md §6 — required so consumers can tree-shake.
Schemas owned locally	`@suaveplan/api-schemas` on genesis lacks a `notification` subpath; the plugin's schemas live inside `src/schemas/` until upstream is augmented.
Positional `$p0`-style params instead of named `$id`	Genesis `DatabaseAdapter.query(sql, params: readonly unknown[])` wraps params as `{p0: …, p1: …}`. Path-A escape valve documented in CLAUDE.md.
Injectable `ApnTransport`	Genesis catalog omits `@parse/node-apn` (network-touching libraries are injected by the host). Matches the genesis convention for transport adapters and means the plugin's test suite is hermetic.

Verification approach

src/error-codes/error-codes.test.ts — pins every code is reachable from a real call site.
src/otel/instruments.test.ts — real MeterProvider, asserts instrument shape + emission.
src/schemas/notification-schemas.test.ts + src/schemas/push-schemas.test.ts + src/schemas/options.test.ts — Zod boundary tests.
src/repositories/notification-repository/notification-repository.test.ts — full repository surface against a stub SurrealAdapter.
src/repositories/device-token-repository/device-token-repository.test.ts — same coverage shape for device-tokens.
src/transport/apn-transport/apn-transport.test.ts — MemoryApnTransport behaviour including failure plans.
src/services/apn-service/apn-service.test.ts — full APN service surface, every error branch, transport-injection and factory pathways.
src/routes/notifications-routes/notifications-routes.test.ts — every route, every status code, ownership check, auth guard, event-bus emission, OTel emission.
src/routes/push-routes/push-routes.test.ts — register / unregister / list / send / send-bulk against an in-memory APN service.
src/plugin/plugin.test.ts — lifecycle: onInit registers repos + APN, double-mount guard, missing-dep failure, emits initialized/ready.
src/api-plugin-notifications.spec-conformance.test.ts — pins every public symbol re-exported by the package root.
tests/integration/full-boot.test.ts — real SurrealDB testcontainer, applies the two surql migrations, then full plugin boot + CRUD roundtrip on both repositories.

Migration impact

None — additive only. This is a brand-new package on genesis. Consumers will opt-in via createNotificationsPlugin() once they need notification routes.

Impact

Affected dependents

None on genesis today — package is additive. Downstream apps that previously had no notifications capability gain access.

14 KiB Raw Permalink Blame History