unified-notification-core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Established the UNC (Unified Notification Core) package identity.
+- Initial Drizzle/PostgreSQL schema factory.
+- Durable multichannel delivery with callback adapters, retries, scheduling,
+  idempotency, and worker-safe claims.
+- Recipient preference overrides with topic/channel wildcard precedence.
+- Built-in in-app inbox operations.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unified Notification Core contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# UNC — Unified Notification Core
+
+A transport-neutral notification core for TypeScript applications using Drizzle
+and PostgreSQL.
+
+It is a package, not a microservice. Your application keeps its database
+connection, HTTP framework, user model, provider SDKs, and worker lifecycle.
+UNC adds durable notification records, per-channel delivery state,
+retries, scheduling, idempotency, recipient preferences, and an in-app inbox.
+
+## Why this boundary
+
+Email, SMS, and Push implementations are application-specific. One application
+may send mail through Nodemailer and Postfix, another through Resend; one may
+send SMS through an Android gateway, another through Twilio. This package does
+not choose.
+
+Instead, register callbacks:
+
+```ts
+const notificationCore = createNotificationCore<AppChannel>({
+  db,
+  adapters: {
+    email: async ({ recipientId, payload }) => {
+      const recipient = await users.findContact(recipientId);
+      const result = await sendMail({
+        to: recipient.email,
+        subject: payload.title,
+        text: payload.body,
+      });
+      return { providerMessageId: result.messageId };
+    },
+    sms: async ({ recipientId, payload }) => {
+      const recipient = await users.findContact(recipientId);
+      const result = await sendSMS({
+        to: recipient.phone,
+        text: payload.body,
+      });
+      return { providerMessageId: result.id };
+    },
+    push: async ({ recipientId, payload }) => {
+      const result = await sendPush(recipientId, payload);
+      return { metadata: { sentDevices: result.sent } };
+    },
+  },
+  defaultChannels: ["in_app", "push"],
+});
+```
+
+The adapter resolves addresses/subscriptions at delivery time. Email addresses,
+phone numbers, Push subscriptions, provider credentials, and provider-specific
+retry queues stay where they belong: in the application.
+
+## Install
+
+```sh
+npm install unified-notification-core drizzle-orm
+```
+
+The package supports Drizzle `0.45.x` with PostgreSQL-compatible drivers,
+including `node-postgres`, `postgres.js`, and PGlite.
+
+## Add the schema
+
+Export the UNC tables from the schema entrypoint already read by Drizzle Kit:
+
+```ts
+// src/db/notification-schema.ts
+import { createNotificationSchema } from "unified-notification-core/schema";
+
+export const notificationSchema = createNotificationSchema();
+
+export const {
+  notifications,
+  notificationDeliveries,
+  notificationPreferences,
+} = notificationSchema;
+```
+
+Pass the same schema object to UNC:
+
+```ts
+import { createNotificationCore } from "unified-notification-core";
+import { notificationSchema } from "./db/notification-schema.js";
+
+const notificationCore = createNotificationCore<AppChannel>({
+  db,
+  schema: notificationSchema,
+  adapters,
+});
+```
+
+The default table prefix is `unc_`. A different prefix can be selected once,
+when defining the application schema:
+
+```ts
+createNotificationSchema({ tablePrefix: "app_notification_" });
+```
+
+Run the application's normal Drizzle schema workflow after exporting the
+tables. The package never connects to or mutates a database by itself.
+
+## Define channels
+
+Channel names are plain text, not a PostgreSQL enum. Adding a future channel
+does not require a core release or enum migration:
+
+```ts
+type AppChannel =
+  | "in_app"
+  | "email"
+  | "sms"
+  | "push"
+  | "whatsapp"
+  | "slack";
+```
+
+`in_app` is built in. Every other channel must have an adapter, which makes a
+missing provider integration fail at application startup instead of silently
+dropping messages.
+
+## Publish and deliver
+
+```ts
+const result = await notificationCore.publishAndDispatch({
+  recipientIds: [userId],
+  topic: "call.incoming",
+  channels: ["in_app", "push"],
+  idempotencyKey: `call:${callId}:incoming`,
+  entityType: "call",
+  entityId: callId,
+  payload: {
+    title: "Incoming call",
+    body: "A customer is waiting.",
+    actionUrl: `/calls/${callId}`,
+    data: { callId },
+    channelData: {
+      push: { tag: `call-${callId}`, ttl: 60 },
+    },
+  },
+});
+```
+
+`publish()` only persists. `publishAndDispatch()` persists and immediately
+attempts due deliveries. Both use the same durable outbox records.
+
+For scheduled delivery or retries, call `dispatchDue()` from infrastructure the
+application already owns:
+
+```ts
+await notificationCore.dispatchDue({
+  workerId: process.env.HOSTNAME,
+  limit: 100,
+  concurrency: 10,
+});
+```
+
+This can run from a cron handler, queue consumer, scheduled function, or an
+application-owned interval. The package starts no timer and exposes no port.
+Concurrent workers claim rows with `FOR UPDATE SKIP LOCKED`; abandoned
+`processing` rows become eligible again after the configured lock timeout.
+
+## Preferences
+
+Preferences are overrides, not a copied matrix. This keeps storage small when
+new topics or channels are introduced.
+
+```ts
+await notificationCore.setPreference({
+  recipientId: userId,
+  topic: "marketing.newsletter",
+  channel: "email",
+  enabled: false,
+});
+```
+
+Wildcard overrides are supported:
+
+```ts
+import { PREFERENCE_WILDCARD } from "unified-notification-core";
+
+// Disable every SMS notification for this recipient.
+await notificationCore.setPreference({
+  recipientId: userId,
+  topic: PREFERENCE_WILDCARD,
+  channel: "sms",
+  enabled: false,
+});
+```
+
+Resolution is deterministic, from most specific to least specific:
+
+1. exact topic + exact channel;
+2. exact topic + `*`;
+3. `*` + exact channel;
+4. `*` + `*`;
+5. configured topic default;
+6. configured global channel default;
+7. `defaultPreferenceEnabled`.
+
+Configure application defaults when creating UNC:
+
+```ts
+const notificationCore = createNotificationCore<AppChannel>({
+  db,
+  adapters,
+  preferenceDefaults: {
+    "*": { in_app: true, email: true, sms: false, push: true },
+    "security.password_changed": {
+      in_app: true,
+      email: true,
+      push: true,
+    },
+  },
+});
+```
+
+Use `preferencePolicy: "ignore"` only for notifications that legally or
+operationally must be delivered regardless of opt-out:
+
+```ts
+await notificationCore.publish({
+  recipientIds: [userId],
+  topic: "security.password_changed",
+  preferencePolicy: "ignore",
+  channels: ["in_app", "email"],
+  payload,
+});
+```
+
+## In-app inbox
+
+```ts
+const page = await notificationCore.listInbox({
+  recipientId: userId,
+  limit: 30,
+});
+
+const nextPage = page.nextCursor
+  ? await notificationCore.listInbox({
+      recipientId: userId,
+      cursor: page.nextCursor,
+    })
+  : null;
+
+await notificationCore.markRead({
+  notificationId,
+  recipientId: userId,
+});
+
+await notificationCore.archive({
+  notificationId,
+  recipientId: userId,
+});
+
+const unread = await notificationCore.unreadCount(userId);
+```
+
+Inbox mutations always require the recipient id as well as the notification id,
+so a route can scope changes to its authenticated user.
+
+## Retry behavior
+
+Adapters signal a permanent provider/application rejection with
+`NotificationDeliveryError`:
+
+```ts
+import { NotificationDeliveryError } from "unified-notification-core";
+
+throw new NotificationDeliveryError(
+  "recipient_unreachable",
+  "The recipient has no verified phone number",
+  { retryable: false },
+);
+```
+
+Unknown errors are retryable. The default backoff is 1 minute, 5 minutes,
+15 minutes, 1 hour, then 6 hours. Configure `retryDelayMs` and
+`defaultMaxAttempts` for application policy. A failed delivery can be explicitly
+requeued with `requeueDelivery()`.
+
+If a provider callback already has its own durable queue, returning after a
+successful enqueue is correct. UNC then tracks acceptance by that
+queue; provider delivery events may be stored in the adapter's own tables.
+
+## Idempotency and scheduling
+
+An `idempotencyKey` is unique per recipient. Publishing the same key again
+returns the original notification and deliveries with `created: false`.
+
+`scheduledFor` delays all selected channels. `cancel(notificationId)` cancels
+pending/retrying/processing deliveries. Sent deliveries remain immutable audit
+history.
+
+## Package guarantees
+
+- No provider SDK dependencies.
+- No database connection ownership.
+- No HTTP framework coupling.
+- No background timers or service runtime.
+- No assumption that recipient ids are UUIDs.
+- No assumption that every notification is in-app.
+- Provider callbacks are invoked outside database transactions.
+- Preferences disabled at publication are recorded as `skipped` deliveries for
+  auditability.
+
+See [Architecture](./docs/architecture.md) and
+[Adoption notes](./docs/adoption-notes.md) for the design and migration boundary.

package/dist/core.d.ts

@@ -0,0 +1,72 @@
+import type { PgDatabase } from "drizzle-orm/pg-core";
+import { type NotificationSchema } from "./schema.js";
+import { PREFERENCE_WILDCARD, type DeliveryAdapters, type DispatchResult, type NotificationLogger, type InboxCursor, type InboxPage, type JsonObject, type PreferenceDefaults, type PreferenceOverride, type PublishInput, type PublishedNotification, type ResolvedPreference } from "./types.js";
+type AnyPgDatabase = PgDatabase<any, any, any>;
+export type NotificationCoreConfig<TChannel extends string, TData extends JsonObject = JsonObject> = {
+    db: AnyPgDatabase;
+    schema?: NotificationSchema;
+    adapters?: DeliveryAdapters<TChannel, TData>;
+    defaultChannels?: readonly TChannel[];
+    preferenceDefaults?: PreferenceDefaults<TChannel>;
+    defaultPreferenceEnabled?: boolean;
+    defaultMaxAttempts?: number;
+    retryDelayMs?: (attempt: number, error: unknown) => number;
+    lockTimeoutMs?: number;
+    now?: () => Date;
+    logger?: NotificationLogger;
+};
+export declare class UnifiedNotificationCore<TChannel extends string, TData extends JsonObject = JsonObject> {
+    #private;
+    constructor(config: NotificationCoreConfig<TChannel, TData>);
+    publish(input: PublishInput<TChannel, TData>): Promise<Array<PublishedNotification<TChannel>>>;
+    publishAndDispatch(input: PublishInput<TChannel, TData>, options?: {
+        workerId?: string;
+        concurrency?: number;
+    }): Promise<{
+        published: Array<PublishedNotification<TChannel>>;
+        dispatched: Array<DispatchResult<TChannel>>;
+    }>;
+    dispatchDue(options?: {
+        limit?: number;
+        workerId?: string;
+        concurrency?: number;
+    }): Promise<Array<DispatchResult<TChannel>>>;
+    setPreference(preference: PreferenceOverride<TChannel>): Promise<void>;
+    setPreferences(recipientId: string, preferences: ReadonlyArray<Omit<PreferenceOverride<TChannel>, "recipientId">>): Promise<void>;
+    clearPreference(input: {
+        recipientId: string;
+        topic: string;
+        channel: TChannel | typeof PREFERENCE_WILDCARD;
+    }): Promise<boolean>;
+    getPreferences(input: {
+        recipientId: string;
+        topics: readonly string[];
+        channels: readonly TChannel[];
+    }): Promise<Array<ResolvedPreference<TChannel>>>;
+    listInbox(input: {
+        recipientId: string;
+        limit?: number;
+        cursor?: InboxCursor;
+        includeArchived?: boolean;
+    }): Promise<InboxPage<TData>>;
+    unreadCount(recipientId: string): Promise<number>;
+    markRead(input: {
+        notificationId: string;
+        recipientId: string;
+        read?: boolean;
+    }): Promise<boolean>;
+    archive(input: {
+        notificationId: string;
+        recipientId: string;
+        archived?: boolean;
+    }): Promise<boolean>;
+    cancel(notificationId: string): Promise<boolean>;
+    requeueDelivery(input: {
+        deliveryId: string;
+        resetAttempts?: boolean;
+        maxAttempts?: number;
+    }): Promise<boolean>;
+}
+export declare function createNotificationCore<TChannel extends string, TData extends JsonObject = JsonObject>(config: NotificationCoreConfig<TChannel, TData>): UnifiedNotificationCore<TChannel, TData>;
+export {};
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}