# 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, services?: NotificationsPluginServices)` returning a `PluginDescriptor` 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`. When the caller supplies `services.emailService`, `onInit` SHALL register it under the `emailService` slot. When the config has `enableDispatcher: true`, `onInit` SHALL construct a `NotificationDispatcher` wired with every available channel (`apn` if `apnService` is registered, `email` if `emailService` is registered) and register it under `notificationDispatcher`; the dispatcher SHALL refuse to construct when zero channels are available (`NotificationsPluginError(DISPATCH_CHANNEL_UNAVAILABLE)`). `onReady` SHALL mount both route trees and refuse to double-mount. `onClose` SHALL shut down the APN transport (if any), null the dispatcher reference, 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: onInit registers notificationDispatcher when enableDispatcher is on - **WHEN** `onInit(ctx)` runs with `enableDispatcher: true`, `enablePush: true`, and a valid APN config - **THEN** `ctx.getService("notificationDispatcher")` resolves to a `NotificationDispatcher` whose `dispatch({ channel: "apn", … })` succeeds #### Scenario: onInit refuses dispatcher with zero channels - **WHEN** `onInit(ctx)` runs with `enableDispatcher: true`, `enablePush: false`, and no `emailService` injected - **THEN** it throws `NotificationsPluginError(DISPATCH_CHANNEL_UNAVAILABLE)` #### 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 AND dispatcher - **WHEN** `onClose()` is invoked after a successful boot with `enableDispatcher: true` - **THEN** the dispatcher reference is nulled and subsequent `onReady` invocations against a fresh app raise `SERVICE_NOT_AVAILABLE` ### 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: }] }` — 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.` 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 ### Requirement: NotificationDispatcher orchestrator The package SHALL export a `NotificationDispatcher` class that resolves `@suaveplan/notification-channel`'s `DeliveryChannel` instances by the dispatcher-facing channel name and exposes a `dispatch(input: DispatchInput): Promise` surface. The dispatcher SHALL fan a single input out to one of the registered delivery channels (defaulting to the configured `defaultChannel`), record an OTel counter increment per dispatch (`notificationsDispatchedTotal` on success, `notificationsDispatchFailedTotal` on failure), and forward a `delivery:sent` or `delivery:bounced` event through the configured `DeliveryEventStore` (when one is supplied). Channel selection failures SHALL surface as `NotificationsPluginError(DISPATCH_CHANNEL_UNAVAILABLE)`. Underlying transport failures returned by the channel as `success === false` SHALL surface as `NotificationsPluginError(DISPATCH_FAILED)` carrying the channel error as `cause`. Per-dispatch idempotency SHALL be applied through an injected `DispatcherIdempotencyAdapter` whose default implementation (`NoopIdempotencyAdapter`) is the identity. **Verified by:** `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch routes to the default channel"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch routes to an explicit channel"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch raises DISPATCH_CHANNEL_UNAVAILABLE for an unknown channel"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch raises DISPATCH_FAILED when the channel returns failed"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch records delivery:sent through the configured store"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch records delivery:bounced when the channel fails"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch emits notificationsDispatchedTotal on success"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch emits notificationsDispatchFailedTotal on failure"`. #### Scenario: dispatch routes to the default channel when channel is unspecified - **WHEN** `dispatcher.dispatch({ recipient, body })` is called and `defaultChannel === "apn"` - **THEN** the registered APN `DeliveryChannel` receives `send(notification)` and the result `channel === "apn"` #### Scenario: dispatch routes to an explicit channel when provided - **WHEN** `dispatcher.dispatch({ recipient, body, channel: "email" })` is called against a dispatcher with both `apn` and `email` channels registered - **THEN** only the email channel receives `send`, and the result `channel === "email"` #### Scenario: unknown channel raises DISPATCH_CHANNEL_UNAVAILABLE - **WHEN** `dispatcher.dispatch({ channel: "sms", … })` is called and no `sms` channel is registered - **THEN** the call rejects with `NotificationsPluginError(DISPATCH_CHANNEL_UNAVAILABLE)` #### Scenario: channel-returned failure raises DISPATCH_FAILED - **WHEN** the underlying channel's `send` returns `{ success: false, error: "transport failed" }` - **THEN** `dispatch` rejects with `NotificationsPluginError(DISPATCH_FAILED)` whose `context.channelError === "transport failed"` #### Scenario: delivery-tracking sees a delivery:sent event on success - **WHEN** `dispatch` succeeds and a `DeliveryEventStore` is configured - **THEN** the store records a `DeliveryEvent` with `eventType === "sent"`, the dispatcher's tenantId, and `messageId === dispatchResult.id` #### Scenario: delivery-tracking sees a delivery:bounced event on failure - **WHEN** `dispatch` fails through a channel failure and a `DeliveryEventStore` is configured - **THEN** the store records a `DeliveryEvent` with `eventType === "bounced"` #### Scenario: idempotency adapter dedupes repeated dispatches - **WHEN** the dispatcher is configured with an adapter that caches by key and `dispatch` is invoked twice with the same key - **THEN** the underlying channel's `send` is called only once ### Requirement: ApnDeliveryChannel adapter The package SHALL export an `ApnDeliveryChannel` class implementing `@suaveplan/notification-channel`'s `DeliveryChannel` interface against the in-package `ApnService`. The channel SHALL be registered under `name === "apn"` and SHALL accept the device token via `Notification.metadata.deviceToken` (string) or `Notification.metadata.deviceTokens` (string array, for fan-out). Missing-token inputs SHALL return `{ success: false, error: "deviceToken metadata required" }`. APN per-device failures SHALL fold into a single `DeliveryResult` whose `success` reflects whether at least one delivery succeeded. **Verified by:** `src/channels/apn-channel/apn-channel.test.ts::"sends through ApnService for a single deviceToken"`, `src/channels/apn-channel/apn-channel.test.ts::"fans out to multiple deviceTokens via metadata.deviceTokens"`, `src/channels/apn-channel/apn-channel.test.ts::"returns success false when deviceToken metadata is missing"`, `src/channels/apn-channel/apn-channel.test.ts::"folds APN per-device failures into the DeliveryResult"`, `src/channels/apn-channel/apn-channel.test.ts::"reports canSend true only for push channel notifications"`. #### Scenario: single deviceToken in metadata - **WHEN** `apnChannel.send({ channel: "push", metadata: { deviceToken: "tok" }, body: "hi", … })` is called - **THEN** `ApnService.sendNotification` is invoked with `payload.deviceToken === "tok"` and the returned `DeliveryResult.success === true` #### Scenario: deviceTokens array fans out - **WHEN** `apnChannel.send({ channel: "push", metadata: { deviceTokens: ["a","b"] }, body: "hi", … })` is called - **THEN** `ApnService.sendBulkNotifications` is invoked with the two-element array and the returned `DeliveryResult.success === true` #### Scenario: missing deviceToken metadata - **WHEN** `apnChannel.send` is called with no `deviceToken` and no `deviceTokens` - **THEN** the call resolves with `{ success: false, channel: "apn", error: "deviceToken metadata required" }` #### Scenario: APN per-device failure surfaces as DeliveryResult.error - **WHEN** the underlying `ApnService.sendNotification` returns `{ sent: 0, failed: 1, errors: [{ error: "Unregistered" }] }` - **THEN** `apnChannel.send` resolves with `success: false` and `error: "Unregistered"` #### Scenario: canSend gates on channel - **WHEN** `apnChannel.canSend(notification)` is called - **THEN** the result is `true` iff `notification.channel === "push"` ### Requirement: EmailDeliveryChannel adapter The package SHALL export an `EmailDeliveryChannel` class implementing `@suaveplan/notification-channel`'s `DeliveryChannel` interface against `@suaveplan/emailer`'s `EmailService`. The channel SHALL be registered under `name === "email"` and SHALL map `Notification.recipient` → `EmailMessage.to`, `Notification.subject` → `EmailMessage.subject` (defaulting to the configured `defaultSubject` when missing), `Notification.body` → `EmailMessage.text` (or `html` when `metadata.html === true`). Transport failures returned by `EmailService.send` SHALL surface as `{ success: false, error: }`. The channel SHALL throw `NotificationsPluginError(EMAIL_SERVICE_UNAVAILABLE)` at construction when `emailService` is `null`. **Verified by:** `src/channels/email-channel/email-channel.test.ts::"sends through EmailService with subject + text"`, `src/channels/email-channel/email-channel.test.ts::"falls back to defaultSubject when notification has no subject"`, `src/channels/email-channel/email-channel.test.ts::"sends HTML body when metadata.html is true"`, `src/channels/email-channel/email-channel.test.ts::"folds transport failure into DeliveryResult.error"`, `src/channels/email-channel/email-channel.test.ts::"throws EMAIL_SERVICE_UNAVAILABLE when constructed with null service"`, `src/channels/email-channel/email-channel.test.ts::"canSend gates on channel === email"`. #### Scenario: success path with explicit subject - **WHEN** `emailChannel.send({ channel: "email", recipient: "x@y.z", subject: "S", body: "B", … })` is called - **THEN** `EmailService.send` receives `{ to: "x@y.z", subject: "S", text: "B" }` and the channel returns `{ success: true, channel: "email" }` #### Scenario: default subject fallback - **WHEN** the notification has no `subject` and the channel was constructed with `defaultSubject: "Notification"` - **THEN** `EmailService.send` receives `subject: "Notification"` #### Scenario: HTML body via metadata - **WHEN** `emailChannel.send({ channel: "email", metadata: { html: true }, body: "

x

", … })` is called - **THEN** `EmailService.send` receives `{ html: "

x

" }` instead of `text` #### Scenario: transport failure - **WHEN** the underlying `EmailService.send` returns `{ success: false, error: new Error("smtp dead"), … }` - **THEN** the channel returns `{ success: false, error: "smtp dead" }` #### Scenario: null service refused at construction - **WHEN** `new EmailDeliveryChannel({ emailService: null, … })` is invoked - **THEN** the constructor throws `NotificationsPluginError(EMAIL_SERVICE_UNAVAILABLE)` #### Scenario: canSend gating - **WHEN** `emailChannel.canSend({ channel: "email", … })` versus `{ channel: "push", … }` - **THEN** the first returns `true`, the second returns `false` ### Requirement: DispatcherIdempotencyAdapter contract The package SHALL export a `DispatcherIdempotencyAdapter` interface exposing exactly one method `execute(key: string, fn: () => Promise): Promise` and a default `NoopIdempotencyAdapter` class that simply calls `fn()`. Callers SHALL be able to plug `@suaveplan/idempotency`'s `IdempotencyGuard` (whose `execute(key, fn, opts?)` signature is structurally compatible) without the package importing the guard at runtime. The dispatcher SHALL call `adapter.execute(key, () => underlyingDispatch())` when a `key` is derivable from the input, short-circuiting duplicate dispatches with the adapter's cached return value. **Verified by:** `src/dispatcher/idempotency-adapter/idempotency-adapter.test.ts::"NoopIdempotencyAdapter calls fn exactly once"`, `src/dispatcher/idempotency-adapter/idempotency-adapter.test.ts::"a caching adapter dedupes repeated executions"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"idempotency adapter dedupes repeated dispatches"`. #### Scenario: noop adapter is the identity - **WHEN** `new NoopIdempotencyAdapter().execute("k", fn)` is invoked - **THEN** `fn()` is called exactly once and its result is returned #### Scenario: caching adapter dedupes - **WHEN** the same `key` is passed twice and the adapter caches by key - **THEN** the underlying `fn` is invoked only once and both calls return the same result ### Requirement: Dispatch input/result schemas The package SHALL export `DispatchInputSchema` and `DispatchResultSchema` (Zod) plus matching `DispatchInput` / `DispatchResult` types. `DispatchInputSchema` SHALL accept `recipient` (non-empty string), `body` (non-empty string), optional `channel` (one of the `notification-channel` channel literals), optional `subject`, optional `metadata` (record), optional `priority`, and an optional `idempotencyKey`. Invalid input SHALL produce `NotificationsPluginError(DISPATCH_INPUT_INVALID)` carrying the `ZodError` as `cause`. **Verified by:** `src/schemas/dispatch-schemas.test.ts::"DispatchInputSchema rejects empty recipient"`, `src/schemas/dispatch-schemas.test.ts::"DispatchInputSchema rejects empty body"`, `src/schemas/dispatch-schemas.test.ts::"DispatchInputSchema accepts a minimal payload"`, `src/schemas/dispatch-schemas.test.ts::"DispatchInputSchema accepts idempotencyKey"`, `src/schemas/dispatch-schemas.test.ts::"DispatchResultSchema accepts canonical shape"`. #### Scenario: empty recipient rejected - **WHEN** `DispatchInputSchema.safeParse({ recipient: "", body: "x" })` is invoked - **THEN** the result `success === false` #### Scenario: minimal payload accepted - **WHEN** `DispatchInputSchema.safeParse({ recipient: "u", body: "b" })` is invoked - **THEN** the result `success === true` ### Requirement: Dispatcher error codes wired into production paths The registry SHALL include `DISPATCH_FAILED`, `DISPATCH_CHANNEL_UNAVAILABLE`, `DISPATCH_INPUT_INVALID`, and `EMAIL_SERVICE_UNAVAILABLE` codes, and every one SHALL be thrown from at least one production source under `src/`. The `error-codes.test.ts` reachability scan SHALL include all four codes. **Verified by:** `src/error-codes/error-codes.test.ts::"every NOTIFICATIONS_PLUGIN_CODES value is referenced by src/"`. #### Scenario: registry exposes the four dispatcher codes - **WHEN** `Object.values(NOTIFICATIONS_PLUGIN_CODES)` is inspected - **THEN** the array contains `NOTIFICATIONS_PLUGIN.DISPATCH_FAILED`, `NOTIFICATIONS_PLUGIN.DISPATCH_CHANNEL_UNAVAILABLE`, `NOTIFICATIONS_PLUGIN.DISPATCH_INPUT_INVALID`, and `NOTIFICATIONS_PLUGIN.EMAIL_SERVICE_UNAVAILABLE` #### Scenario: every dispatcher code reachable from src - **WHEN** the spec-conformance scan concatenates every non-test `.ts` under `src/` - **THEN** the concatenation contains `NOTIFICATIONS_PLUGIN_CODES.DISPATCH_FAILED`, `…DISPATCH_CHANNEL_UNAVAILABLE`, `…DISPATCH_INPUT_INVALID`, and `…EMAIL_SERVICE_UNAVAILABLE` ### Requirement: Dispatcher OTel counters `getNotificationsInstruments()` SHALL expose two additional counters beyond the original six: `notificationsDispatchedTotal` (incremented by `NotificationDispatcher` on a successful dispatch, with `channel` attribute) and `notificationsDispatchFailedTotal` (incremented on a failed dispatch, with `channel` + `reason` attributes). Both SHALL be observable through an `InMemoryMetricExporter` in the OTel test. **Verified by:** `src/otel/instruments.test.ts::"exposes dispatcher counters"`, `src/otel/instruments.test.ts::"dispatcher counters emit on flush"`. #### Scenario: instrument bundle exposes the two new counters - **WHEN** `getNotificationsInstruments()` is called - **THEN** the returned object has `notificationsDispatchedTotal` and `notificationsDispatchFailedTotal` properties #### Scenario: counters appear in the exporter snapshot - **WHEN** both counters are incremented and `flushTestMetrics()` is called - **THEN** the exporter snapshot includes both metric names ### Requirement: Dispatcher service-registry slots The package SHALL extend the existing `ServiceRegistry` module augmentation with two optional slots: `notificationDispatcher` (`NotificationDispatcher`) and `emailService` (`EmailService` from `@suaveplan/emailer`). The slots SHALL only be populated when the plugin's `enableDispatcher` option is `true` (dispatcher) or when the host injects an `EmailService` (email). **Verified by:** `src/api-plugin-notifications.spec-conformance.test.ts::"registry slots include dispatcher and emailService"`, `src/plugin/plugin.test.ts::"onInit registers notificationDispatcher when enableDispatcher is on"`. #### Scenario: dispatcher slot populated when enabled - **WHEN** `onInit` runs with `enableDispatcher: true` - **THEN** `ctx.getService("notificationDispatcher")` resolves to a `NotificationDispatcher` instance #### Scenario: emailService slot populated when injected - **WHEN** the host calls `createNotificationsPlugin({}, { emailService })` and `onInit` runs - **THEN** `ctx.getService("emailService")` resolves to the same `EmailService` instance