110 lines
9.9 KiB
Markdown
110 lines
9.9 KiB
Markdown
# @suaveplan/api-plugin-notifications - Notifications plugin for @suaveplan/api. Ships SurrealDB-backed NotificationRepository + DeviceTokenRepository, /notifications and /push Hono OpenAPI route groups, an APN service with injectable transport (no hardcoded network library), an event-bus integration via ctx.eventBus, 18 NOTIFICATIONS_PLUGIN_* error codes, and 6 OTel counters. Server-tier — runs in Bun and Node.
|
|
|
|
SurrealDB-backed notifications + push plugin for `@suaveplan/api`.
|
|
Ships a `NotificationRepository` + `DeviceTokenRepository` pair, an
|
|
`ApnService` with a pluggable transport contract (no hardcoded
|
|
`@parse/node-apn` dependency), eleven `/notifications/*` Hono OpenAPI
|
|
routes, five `/push/*` routes, an opt-in multi-channel
|
|
`NotificationDispatcher` (`apn` + `email`) wired on top of
|
|
`@suaveplan/notification-channel`, `@suaveplan/emailer`, and
|
|
`@suaveplan/delivery-tracking`, twenty-two `NOTIFICATIONS_PLUGIN_*`
|
|
error codes, and eight OTel counters.
|
|
|
|
Server-tier — runs in Bun and Node.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [apn-channel](./src/channels/apn-channel/apn-channel.md) — Adapts the in-package `ApnService` to the `@suaveplan/notification-channel` `DeliveryChannel` interface so `Notificatio…
|
|
- [apn-channel](./src/channels/apn-channel/apn-channel.md) — Adapts the in-package `ApnService` to the `@suaveplan/notification-channel` `DeliveryChannel` interface so `Notificatio…
|
|
- [email-channel](./src/channels/email-channel/email-channel.md) — Adapts `@suaveplan/emailer`'s `EmailService` to the `@suaveplan/notification-channel` `DeliveryChannel` interface so `N…
|
|
- [email-channel](./src/channels/email-channel/email-channel.md) — Adapts `@suaveplan/emailer`'s `EmailService` to the `@suaveplan/notification-channel` `DeliveryChannel` interface so `N…
|
|
- [idempotency-adapter](./src/dispatcher/idempotency-adapter/idempotency-adapter.md) — Defines the narrow contract that lets `NotificationDispatcher` delegate per-call deduplication to a caller-supplied imp…
|
|
- [idempotency-adapter](./src/dispatcher/idempotency-adapter/idempotency-adapter.md) — Defines the narrow contract that lets `NotificationDispatcher` delegate per-call deduplication to a caller-supplied imp…
|
|
- [notification-dispatcher](./src/dispatcher/notification-dispatcher/notification-dispatcher.md) — Top-level orchestrator that lets callers send one notification through whichever delivery channel they pick (APN, email…
|
|
- [notification-dispatcher](./src/dispatcher/notification-dispatcher/notification-dispatcher.md) — Top-level orchestrator that lets callers send one notification through whichever delivery channel they pick (APN, email…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/api-plugin-notifications`. The module exports a frozen `NOTIFICATIONS_PLUGIN…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/api-plugin-notifications`. The module exports a frozen `NOTIFICATIONS_PLUGIN…
|
|
- [otel](./src/otel/instruments.md) — OpenTelemetry instrument bundle for `@suaveplan/api-plugin-notifications`. The module exposes a lazy, memoised factory…
|
|
- [instruments](./src/otel/instruments.md) — OpenTelemetry instrument bundle for `@suaveplan/api-plugin-notifications`. The module exposes a lazy, memoised factory…
|
|
- [plugin](./src/plugin/plugin.md) — Plugin descriptor factory for `@suaveplan/api-plugin-notifications`. Composes everything in the package — Zod-validated…
|
|
- [plugin](./src/plugin/plugin.md) — Plugin descriptor factory for `@suaveplan/api-plugin-notifications`. Composes everything in the package — Zod-validated…
|
|
- [device-token-repository](./src/repositories/device-token-repository/device-token-repository.md) — SurrealDB-backed repository for the `device_token` table. Owns every SurrealQL statement the plugin issues against devi…
|
|
- [device-token-repository](./src/repositories/device-token-repository/device-token-repository.md) — SurrealDB-backed repository for the `device_token` table. Owns every SurrealQL statement the plugin issues against devi…
|
|
- [notification-repository](./src/repositories/notification-repository/notification-repository.md) — SurrealDB-backed repository for the `notification` table. Owns every SurrealQL statement the plugin issues against noti…
|
|
- [notification-repository](./src/repositories/notification-repository/notification-repository.md) — SurrealDB-backed repository for the `notification` table. Owns every SurrealQL statement the plugin issues against noti…
|
|
- [notifications-routes](./src/routes/notifications-routes/notifications-routes.md) — Hono OpenAPI route module exposing the `/notifications/*` surface. Eleven endpoints cover list / unread-count / create…
|
|
- [notifications-routes](./src/routes/notifications-routes/notifications-routes.md) — Hono OpenAPI route module exposing the `/notifications/*` surface. Eleven endpoints cover list / unread-count / create…
|
|
- [push-routes](./src/routes/push-routes/push-routes.md) — Hono OpenAPI route module exposing the `/push/*` surface for device- token registration and APN delivery. Five endpoint…
|
|
- [push-routes](./src/routes/push-routes/push-routes.md) — Hono OpenAPI route module exposing the `/push/*` surface for device- token registration and APN delivery. Five endpoint…
|
|
- [dispatch-schemas](./src/schemas/dispatch-schemas.md) — Defines the Zod boundary for the `NotificationDispatcher` surface. The dispatcher fans a single call out to whichever d…
|
|
- [notification-schemas](./src/schemas/notification-schemas.md) — Zod boundary schemas for the notification entity and every wire surface the plugin exposes — list / get / create / upda…
|
|
- [options](./src/schemas/options.md) — Zod schema for plugin options accepted by `createNotificationsPlugin()` plus the nested APN configuration shape (`ApnCo…
|
|
- [push-schemas](./src/schemas/push-schemas.md) — Zod boundary schemas for the `/push/*` route group and the device-token entity stored in SurrealDB. Schemas describe bo…
|
|
- [services](./src/services/registry-augmentation.md) — Module-augmentation file that declares three new service slots on `@suaveplan/api-plugin/service-registry`'s `ServiceRe…
|
|
- [apn-service](./src/services/apn-service/apn-service.md) — Apple Push Notification delivery service. Validates an `ApnConfig` at construction-time, builds a pluggable `ApnTranspo…
|
|
- [apn-service](./src/services/apn-service/apn-service.md) — Apple Push Notification delivery service. Validates an `ApnConfig` at construction-time, builds a pluggable `ApnTranspo…
|
|
- [registry-augmentation](./src/services/registry-augmentation.md) — Module-augmentation file that declares three new service slots on `@suaveplan/api-plugin/service-registry`'s `ServiceRe…
|
|
- [apn-transport](./src/transport/apn-transport/apn-transport.md) — Pluggable transport contract for Apple Push Notification delivery. The plugin never depends on a concrete APN client li…
|
|
- [apn-transport](./src/transport/apn-transport/apn-transport.md) — Pluggable transport contract for Apple Push Notification delivery. The plugin never depends on a concrete APN client li…
|
|
- [types](./src/types/types.md) — Public type aliases for cross-module wiring: the typed event-bus payload map (`NotificationsPluginEvents`), the discrim…
|
|
- [types](./src/types/types.md) — Public type aliases for cross-module wiring: the typed event-bus payload map (`NotificationsPluginEvents`), the discrim…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Modules
|
|
|
|
- [`src/error-codes/error-codes.md`](src/error-codes/error-codes.md)
|
|
- [`src/otel/instruments.md`](src/otel/instruments.md)
|
|
- [`src/plugin/plugin.md`](src/plugin/plugin.md)
|
|
- [`src/repositories/notification-repository/notification-repository.md`](src/repositories/notification-repository/notification-repository.md)
|
|
- [`src/repositories/device-token-repository/device-token-repository.md`](src/repositories/device-token-repository/device-token-repository.md)
|
|
- [`src/routes/notifications-routes/notifications-routes.md`](src/routes/notifications-routes/notifications-routes.md)
|
|
- [`src/routes/push-routes/push-routes.md`](src/routes/push-routes/push-routes.md)
|
|
- [`src/schemas/options.md`](src/schemas/options.md)
|
|
- [`src/schemas/notification-schemas.md`](src/schemas/notification-schemas.md)
|
|
- [`src/schemas/push-schemas.md`](src/schemas/push-schemas.md)
|
|
- [`src/services/apn-service/apn-service.md`](src/services/apn-service/apn-service.md)
|
|
- [`src/services/registry-augmentation.md`](src/services/registry-augmentation.md)
|
|
- [`src/transport/apn-transport/apn-transport.md`](src/transport/apn-transport/apn-transport.md)
|
|
- [`src/types/types.md`](src/types/types.md)
|
|
- [`src/channels/apn-channel/apn-channel.md`](src/channels/apn-channel/apn-channel.md)
|
|
- [`src/channels/email-channel/email-channel.md`](src/channels/email-channel/email-channel.md)
|
|
- [`src/dispatcher/notification-dispatcher/notification-dispatcher.md`](src/dispatcher/notification-dispatcher/notification-dispatcher.md)
|
|
- [`src/dispatcher/idempotency-adapter/idempotency-adapter.md`](src/dispatcher/idempotency-adapter/idempotency-adapter.md)
|
|
- [`src/schemas/dispatch-schemas.md`](src/schemas/dispatch-schemas.md)
|
|
|
|
## Usage
|
|
|
|
```ts
|
|
import { createNotificationsPlugin } from "@suaveplan/api-plugin-notifications";
|
|
|
|
await api.loadPlugin(
|
|
createNotificationsPlugin({
|
|
basePath: "/v1/notifications",
|
|
pushBasePath: "/v1/push",
|
|
enablePush: true,
|
|
apn: {
|
|
token: { key: "/keys/AuthKey.p8", keyId: "K", teamId: "T" },
|
|
defaultTopic: "com.example.app",
|
|
production: true,
|
|
},
|
|
})
|
|
);
|
|
```
|
|
|
|
## Pluggable APN transport
|
|
|
|
Production hosts inject a `node-apn`-backed `ApnTransport`; tests use
|
|
the deterministic `MemoryApnTransport`:
|
|
|
|
```ts
|
|
import { ApnService, type ApnTransport } from "@suaveplan/api-plugin-notifications";
|
|
|
|
const transport: ApnTransport = makeNodeApnTransport(provider);
|
|
const service = new ApnService({ config, transport });
|
|
```
|
|
|
|
See `src/transport/apn-transport/apn-transport.md` for the full
|
|
contract.
|
|
|