suaveplan/openspec/archive/2026-05-19-add-api-plugin-notifications/specs/api-plugin-notifications/spec.md

Capability Spec Delta: api-plugin-notifications (add-api-plugin-notifications)

Package: @suaveplan/api-plugin-notifications Status: PROPOSED

Every requirement below carries a **Verified by:** line at authoring time.

ADDED Requirements

Requirement: Plugin factory and lifecycle

The package SHALL export createNotificationsPlugin(options?: NotificationsPluginConfigInput) returning a PluginDescriptor<NotificationsPluginConfig> that mounts both the /notifications and /push route groups against @suaveplan/api. The factory SHALL Zod-validate input via NotificationsPluginOptionsSchema and throw NotificationsPluginError(INVALID_CONFIG) carrying the ZodError as cause on invalid input. onInit SHALL register notificationRepository, deviceTokenRepository, and (when enablePush) apnService in the host's ServiceRegistry. onReady SHALL mount both route trees and refuse to double-mount. onClose SHALL shut down the APN transport (if any) and clear runtime state.

Verified by: src/plugin/plugin.test.ts, src/schemas/options.test.ts, src/api-plugin-notifications.spec-conformance.test.ts.

Scenario: valid options produce a descriptor

• WHEN createNotificationsPlugin({ basePath: "/v1/notifications" }) is called
• THEN the descriptor has name === "notifications", dependencies === ["database"], and defaults.basePath === "/v1/notifications"

Scenario: invalid options fail fast

• WHEN createNotificationsPlugin({ basePath: "" } as never) is called
• THEN the call throws NotificationsPluginError with code === NOTIFICATIONS_PLUGIN_CODES.INVALID_CONFIG

Scenario: onInit registers repositories

• WHEN onInit(ctx) runs with a real db service in the registry
• THEN ctx.getService("notificationRepository") and ctx.getService("deviceTokenRepository") resolve to non-null instances

Scenario: onInit fails without database service

• WHEN onInit(ctx) runs with no db service registered
• THEN it throws NotificationsPluginError(SERVICE_NOT_AVAILABLE)

Scenario: onInit registers APN when enabled

• WHEN onInit(ctx) runs with enablePush === true and a valid apn config
• THEN ctx.getService("apnService") resolves to an ApnService instance whose isInitialized() returns true

Scenario: onInit fails when enablePush without apn

• WHEN onInit(ctx) runs with enablePush === true and apn === undefined
• THEN it throws NotificationsPluginError(APN_CONFIG_MISSING)

Scenario: onReady mounts both route trees

• WHEN onReady(ctx) runs after onInit
• THEN ctx.getService("app").routes contains entries whose path begins with the configured basePath AND with the configured pushBasePath

Scenario: onReady refuses to double-mount

• WHEN onReady(ctx) is invoked twice against the same app instance
• THEN the second call throws NotificationsPluginError(ROUTE_PREFIX_COLLISION)

Scenario: onClose clears repositories

• WHEN onClose() is invoked after a successful boot
• THEN subsequent onReady invocations against a fresh app raise SERVICE_NOT_AVAILABLE because the repositories are cleared

Requirement: NotificationRepository contract

The package SHALL export a NotificationRepository class implementing INotificationRepository against the genesis SurrealAdapter. Every statement SHALL use positional placeholders ($p0, $p1, …) matching the DatabaseAdapter.query(sql, params: readonly unknown[]) surface. Twelve operations SHALL be present: create, findById, findByRecipient, getUnreadCount, update, markAsRead, markManyAsRead, markAllAsRead, dismiss, delete, findGroupedByType, deleteOldRead. Record-id normalisation SHALL accept both bare and prefixed ids; SurrealDB RecordId row shapes SHALL collapse to string ids inside transformRecord.

Verified by: src/repositories/notification-repository/notification-repository.test.ts.

Scenario: create returns transformed row

• WHEN repo.create({ type, recipient, content }) returns a fresh notification id
• THEN the returned Notification.id is a string, even when the adapter returned a { tb, id } RecordId shape

Scenario: empty adapter row raises NOTIFICATION_CREATE_FAILED

• WHEN the adapter returns [] on CREATE
• THEN the repository throws NotificationsPluginError(NOTIFICATION_CREATE_FAILED)

Scenario: findByRecipient builds the SurrealQL filter

• WHEN findByRecipient(userId, siteId, opts) is called with every option
• THEN the SurQL string contains WHERE recipient = type::thing('user', $p0), AND site = type::thing('site', $p…), AND read = false, AND type = $p…, AND created_at > $p…, LIMIT $p…, and START $p…

Scenario: deleteOldRead rejects negative input

• WHEN deleteOldRead(-1) is invoked
• THEN the repository throws NotificationsPluginError(INVALID_CONFIG)

Requirement: DeviceTokenRepository contract

The package SHALL export a DeviceTokenRepository class implementing IDeviceTokenRepository. Eight operations SHALL be present: register, findById, findByToken, findActiveForUser, deactivate, deactivateByToken, touchLastUsed, cleanup. Duplicate-token detection SHALL fold the SurrealDB UNIQUE-index violation into DEVICE_TOKEN_DUPLICATE. Other adapter failures SHALL fold into DEVICE_TOKEN_CREATE_FAILED.

Verified by: src/repositories/device-token-repository/device-token-repository.test.ts.

Scenario: duplicate token raises DEVICE_TOKEN_DUPLICATE

• WHEN the adapter throws an error mentioning token on CREATE
• THEN the repository throws NotificationsPluginError(DEVICE_TOKEN_DUPLICATE)

Scenario: generic create failure raises DEVICE_TOKEN_CREATE_FAILED

• WHEN the adapter throws an unrelated error on CREATE
• THEN the repository throws NotificationsPluginError(DEVICE_TOKEN_CREATE_FAILED)

Scenario: cleanup rejects negative daysOld

• WHEN cleanup(-1) is invoked
• THEN the repository throws NotificationsPluginError(INVALID_CONFIG)

Requirement: ApnService with pluggable transport

The package SHALL export an ApnService class that validates its config, builds an ApnTransport (default: createMemoryApnTransport), and exposes initialize / sendNotification / sendBulkNotifications / shutdown / isInitialized. Per-device failures SHALL appear inside the returned PushNotificationResult.errors array; the service SHALL NOT throw for per-device delivery failures. Transport-init errors SHALL fold into APN_TRANSPORT_INIT_FAILED; transport-shutdown errors fold into APN_TRANSPORT_SHUTDOWN_FAILED. The MemoryApnTransport ships as the deterministic default; hosts inject their own transport for production @parse/node-apn delivery.

Verified by: src/services/apn-service/apn-service.test.ts, src/transport/apn-transport/apn-transport.test.ts.

Scenario: missing auth material raises APN_CONFIG_MISSING

• WHEN initialize() runs with no cert, key, pfx, or token
• THEN the service throws NotificationsPluginError(APN_CONFIG_MISSING)

Scenario: incomplete token raises APN_CONFIG_INVALID

• WHEN initialize() runs with token: { key, keyId: "", teamId }
• THEN the service throws NotificationsPluginError(APN_CONFIG_INVALID)

Scenario: per-device failure surfaces in the result

• WHEN sendNotification is called against a transport whose failurePlan maps bad → { status: 410, reason: "Unregistered" }
• THEN the call resolves with { sent: 0, failed: 1, errors: [{ status: 410, reason: "Unregistered" }] } — no throw

Scenario: transport-thrown error folds into a synthetic failure

• WHEN sendNotification is called against a transport whose send throws
• THEN the call resolves with { sent: 0, failed: 1, errors: [{ error: <message> }] } — no throw

Scenario: bulk send empty list returns 0/0

• WHEN sendBulkNotifications([], payload) is invoked
• THEN the call resolves with { sent: 0, failed: 0 } without contacting the transport

Requirement: Hono OpenAPI route groups

The package SHALL export createNotificationsRoutes(config) and createPushRoutes(config) that return OpenAPIHono route bundles. Notifications routes SHALL cover 11 endpoints (list, unread-count, create, get, patch, mark-read, mark-many, mark-all, dismiss, delete, grouped-by-type). Push routes SHALL cover 5 endpoints (register token, unregister token, list tokens, send single, send bulk). Every route SHALL require auth via c.get("user") and return 401 { error, code: NOTIFICATIONS_PLUGIN.UNAUTHENTICATED } when missing. Mutating routes SHALL verify the notification belongs to the authenticated user; mismatches return 403 { code: FORBIDDEN }. Delivery endpoints SHALL return 503 when apnService === null (i.e. enablePush === false). Every successful mutation SHALL forward a NotificationsRouteEvent to the host's ctx.eventBus through the injected emitEvent callback.

Verified by: src/routes/notifications-routes/notifications-routes.test.ts, src/routes/push-routes/push-routes.test.ts.

Scenario: missing user returns 401

• WHEN any route is hit without c.get("user") set
• THEN the response is 401 with body { error: "Authentication required", code: "NOTIFICATIONS_PLUGIN.UNAUTHENTICATED" }

Scenario: ownership mismatch returns 403

• WHEN PATCH /notifications/{id} is invoked by a user whose id does not match the notification's recipient
• THEN the response is 403 with code: NOTIFICATIONS_PLUGIN.FORBIDDEN

Scenario: delivery without APN returns 503

• WHEN POST /push/send is invoked with apnService === null in the route config
• THEN the response is 503 with code: NOTIFICATIONS_PLUGIN.APN_SERVICE_UNAVAILABLE

Scenario: successful create forwards event-bus event

• WHEN POST /notifications succeeds
• THEN the injected emitEvent callback receives { type: "notification:created", payload: { notificationId, recipientId, type } }

Scenario: duplicate device token returns 409

• WHEN POST /push/tokens is invoked with a token that triggers DEVICE_TOKEN_DUPLICATE
• THEN the response is 409 with code: NOTIFICATIONS_PLUGIN.DEVICE_TOKEN_DUPLICATE

Scenario: bulk send caps recipients at maxBulkRecipients

• WHEN POST /push/send-bulk is invoked with userIds longer than maxBulkRecipients
• THEN the route processes only the first maxBulkRecipients entries; totalUsers reflects the cap

Requirement: Error-code registry

The package SHALL export NOTIFICATIONS_PLUGIN_CODES (frozen record built by defineCodes("NOTIFICATIONS_PLUGIN", [...])) and a NotificationsPluginError class extending SuaveplanError. Every code SHALL be reachable from at least one production source file; the spec-conformance test SHALL grep the source tree to assert reachability.

Verified by: src/error-codes/error-codes.test.ts.

Scenario: namespace literal is NOTIFICATIONS_PLUGIN

• WHEN every value of NOTIFICATIONS_PLUGIN_CODES is inspected
• THEN each value starts with "NOTIFICATIONS_PLUGIN."

Scenario: every code reachable from src/

• WHEN the spec test concatenates every non-test .ts under src/
• THEN the concatenation contains NOTIFICATIONS_PLUGIN_CODES.<KEY> for every key

Requirement: OpenTelemetry instruments

The package SHALL expose getNotificationsInstruments() / resetNotificationsInstruments() returning six counters (notificationsCreatedTotal, notificationsReadTotal, notificationsDeletedTotal, pushSentTotal, pushFailedTotal, deviceTokensRegisteredTotal). Each counter SHALL be emitted from at least one production code path and SHALL be observable through an InMemoryMetricExporter in the test suite.

Verified by: src/otel/instruments.test.ts.

Scenario: bundle is memoised

• WHEN getNotificationsInstruments() is called twice without a reset
• THEN both calls return the same object reference

Scenario: counters emit on flush

• WHEN counters are incremented and flushTestMetrics() is called
• THEN the exporter snapshot contains every counter name

Requirement: Service-registry augmentation

The package SHALL augment @suaveplan/api-plugin/service-registry's ServiceRegistry interface with three slots: notificationRepository (INotificationRepository), deviceTokenRepository (IDeviceTokenRepository), and apnService (ApnService). The package barrel SHALL side-effect import the augmentation so consumers that import any public symbol pick up the type widening automatically.

Verified by: src/api-plugin-notifications.spec-conformance.test.ts.

Scenario: registry slots typed

• WHEN a downstream consumer calls ctx.getService("notificationRepository") against the augmented registry
• THEN the result type narrows to INotificationRepository | undefined without a cast