unified-notification-core 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.1
+
+- Made delivery claims unique per row and attempt, with durable attempt counts
+  incremented before adapter invocation and exhausted stale claims closed.
+- Made cancellation races truthful: current-claim provider success is `sent`,
+  failure remains `canceled`, and stale callbacks report durable state without
+  mutating it.
+- Restricted requeueing to failed deliveries on active notifications and made
+  attempt-budget/reset semantics explicit.
+- Normalized recipient/topic/channel keys across publish, preference APIs, the
+  public resolver, and configured defaults; canonical default collisions now
+  fail fast. Oversized delivery error codes are rejected before persistence.
+- Preserved `0.1.0` whitespace preference rows without a migration, with
+  deterministic opt-out-wins conflict handling and atomic consolidation on
+  writes/clears.
+- Matched legacy SQL key normalization to the complete ECMAScript trim set,
+  batched preference reads into exact plus one legacy fallback query, and added
+  the corresponding functional recipient index to the schema factory.
+- Hardened adapters, defaults, attempt limits, channel payloads, and inbox keys
+  against prototype-name collisions and runtime-invalid values.
+- Prevented provider dispatch through transaction-scoped cores. Transactional
+  `publish()` remains supported, while `publishAndDispatch()` and `dispatchDue()`
+  fail before publication, claiming, or adapter invocation.
+
 ## 0.1.0
 
 - Established the UNC (Unified Notification Core) package identity.

package/README.md

@@ -100,6 +100,12 @@ 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.
 
+Upgrading an existing `0.1.0` database to `0.1.1` adds a functional recipient
+preference index used by legacy-key fallback reads. Generate and apply that
+schema diff through the application's normal reviewed migration workflow. UNC
+does not create the index at runtime; correctness is preserved before the index
+is applied, but legacy fallback reads can be slower.
+
 ## Define channels
 
 Channel names are plain text, not a PostgreSQL enum. Adding a future channel
@@ -144,6 +150,12 @@ const result = await notificationCore.publishAndDispatch({
 `publish()` only persists. `publishAndDispatch()` persists and immediately
 attempts due deliveries. Both use the same durable outbox records.
 
+A core constructed with a Drizzle `PgTransaction` is publish-only. This lets an
+application commit its own row and `publish()` atomically. Do not call
+`publishAndDispatch()` or `dispatchDue()` on that core: both fail before writing
+or invoking an adapter. After the outer transaction commits, dispatch with a
+core constructed from the top-level `PgDatabase`.
+
 For scheduled delivery or retries, call `dispatchDue()` from infrastructure the
 application already owns:
 
@@ -159,6 +171,9 @@ 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.
+`workerId` is diagnostic (maximum 154 characters). Every claimed delivery gets
+a separate claim token, so two attempts from the same worker cannot finalize
+each other's rows.
 
 ## Preferences
 
@@ -215,6 +230,23 @@ const notificationCore = createNotificationCore<AppChannel>({
 });
 ```
 
+Recipient, topic, and channel keys are trimmed at the public boundary, including
+`resolvePreference()` and configured defaults. Keys that become empty are
+rejected. Configuration also fails fast when two raw default keys normalize to
+the same topic or channel, rather than silently choosing one.
+
+Reads remain compatible with `0.1.0` preference rows whose stored keys contain
+surrounding whitespace. If multiple stored rows collapse to one canonical
+override, opt-out wins: any `enabled: false` row disables that topic/channel.
+Writing or clearing that override atomically consolidates its legacy duplicates.
+Channel-keyed configuration is copied into own-key registries, so names such as
+`toString`, `constructor`, and `__proto__` have no inherited behavior and work
+only when explicitly configured.
+
+Batch publication loads preferences in one exact indexed query plus at most one
+legacy canonical fallback query for the whole recipient batch. It does not scan
+preferences once per recipient.
+
 Use `preferencePolicy: "ignore"` only for notifications that legally or
 operationally must be delivered regardless of opt-out:
 
@@ -257,7 +289,8 @@ 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.
+so a route can scope changes to its authenticated user. Inbox recipient ids use
+the same trim-and-reject-empty normalization as publication and preferences.
 
 ## Retry behavior
 
@@ -277,7 +310,11 @@ throw new NotificationDeliveryError(
 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()`.
+requeued with `requeueDelivery()`. Attempts are durably incremented when a row
+is claimed, before the adapter runs. `requeueDelivery()` preserves that counter
+by default and therefore requires remaining attempt capacity; pass a larger
+`maxAttempts`, or set `resetAttempts: true` to start a new attempt budget.
+Only a `failed` delivery whose notification is not canceled can be requeued.
 
 If a provider callback already has its own durable queue, returning after a
 successful enqueue is correct. UNC then tracks acceptance by that
@@ -289,8 +326,11 @@ 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.
+pending/retrying/processing deliveries. A provider callback already in flight
+cannot be recalled: success from its current claim is persisted as `sent`
+(`sent` is immutable audit history), while failure stays `canceled` and is not
+retried. A stale callback never overwrites the state written by a newer claim,
+and its `DispatchResult` reports the durable state it observed.
 
 ## Package guarantees
 
@@ -300,7 +340,8 @@ history.
 - 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.
+- Provider callbacks are invoked only by a top-level-database core, after the
+  claim transaction commits.
 - Preferences disabled at publication are recorded as `skipped` deliveries for
   auditability.
 

package/dist/core.d.ts

@@ -1,4 +1,4 @@
-import type { PgDatabase } from "drizzle-orm/pg-core";
+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>;

package/dist/core.d.ts.map

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