@12-apps/notifications 4.6.0 → 4.7.0

package/dist/{create-api-notifications-CgBdjfyF.d.ts → create-api-notifications-B3u6Kx3x.d.ts}

@@ -1,5 +1,5 @@
 import { N as NotificationGeneratorRegistry } from './generators-B9xt3sRh.js';
-import { b as NotificationRow, C as ChannelMatrix, a as ChannelRow, L as ListNotificationsResult, c as NotificationWireMessages } from './wire-5IRin4zH.js';
+import { b as NotificationRow, C as ChannelMatrix, a as ChannelRow, L as ListNotificationsResult, h as NotificationsCopySource, c as NotificationWireMessages } from './wire-6dzyfDE7.js';
 import { b as NotificationChannel, D as DeliveryStatus, f as NotificationLogger, i as NotificationTransport, c as NotificationContent, a as NotificationCategory, d as NotificationEvent, e as NotificationGenerator } from './types-CXLAG3UU.js';
 import { e as WebPushSubscriptionSource, D as DriverDeclarationBase, a as WebPushDriverDeclaration, c as WebPushSender } from './web-push-Cs14Wp9u.js';
 
@@ -753,6 +753,16 @@ interface NotificationsRequest {
     body?: unknown;
     /** Headers the surface reads (`user-agent`, for the device hint). */
     headers?: Record<string, string | undefined>;
+    /**
+     * The language to answer this caller in, as a language tag (`pt-BR`,
+     * `en-US`) — the same field `@12-apps/wiring`'s `WireRequest` carries.
+     *
+     * Populated by the host's adapter, which is the only layer that can
+     * negotiate one. Absent is meaningful and not an error: a host with one
+     * audience never sets it, and this surface must then answer with the words
+     * it was configured with rather than invent a language.
+     */
+    locale?: string;
 }
 /** What a handler answers with; the adapter maps it onto its response type. */
 interface NotificationsResponse {
@@ -874,8 +884,15 @@ interface NotificationsServerConfig {
     onInboxChanged?: (userId: string) => void;
     /** The host's authorization engine, for `notifyByPermission`. */
     audience?: NotificationAudienceDirectory;
-    /** User-facing copy overrides (pt-BR product copy by default). */
-    messages: NotificationWireMessages;
+    /**
+     * Every user-facing sentence this surface can produce — REQUIRED host config.
+     *
+     * A pack, or a RESOLVER for a host whose callers do not share a language.
+     * Passed to the routes UNRESOLVED: this factory runs once per process (and
+     * at least one host memoises its call), so resolving here would answer every
+     * later request in the language the process started with.
+     */
+    messages: NotificationsCopySource<NotificationWireMessages>;
     /** The host's logger. Defaults to the console. */
     logger?: NotificationLogger;
 }
@@ -901,8 +918,14 @@ interface ApiNotifications {
     registerGenerator: NotificationGeneratorRegistry['register'];
     /** The declared transports, for diagnostics and availability probes. */
     transports: TransportRegistry;
-    /** The copy in force, so a host's own screens can reuse a sentence. */
-    messages: NotificationWireMessages;
+    /**
+     * The copy source in force, so a host's own screens can reuse a sentence.
+     *
+     * The SOURCE rather than a resolved pack, for the same reason the routes get
+     * one: a host screen serving two readers must be able to ask per reader.
+     * Read it with `messagesOf({ messages }, locale)`.
+     */
+    messages: NotificationsCopySource<NotificationWireMessages>;
 }
 declare function createApiNotifications(config: NotificationsServerConfig): ApiNotifications;
 

package/dist/{create-web-notifications-Du3hTs7P.d.ts → create-web-notifications-BpNR8qH3.d.ts}

@@ -1,5 +1,5 @@
 import { JSX, ComponentType } from 'react';
-import { L as ListNotificationsResult, a as ChannelRow, I as InboxNotification, N as NotificationMessages } from './wire-5IRin4zH.js';
+import { L as ListNotificationsResult, a as ChannelRow, I as InboxNotification, N as NotificationMessages } from './wire-6dzyfDE7.js';
 import { b as NotificationChannel } from './types-CXLAG3UU.js';
 
 /**

package/dist/hono/index.d.ts

@@ -1,8 +1,8 @@
 import { Hono, Context } from 'hono';
-import { A as ApiNotifications, N as NotificationsServerConfig, a as NotificationsActor } from '../create-api-notifications-CgBdjfyF.js';
+import { A as ApiNotifications, N as NotificationsServerConfig, a as NotificationsActor } from '../create-api-notifications-B3u6Kx3x.js';
 import '../generators-B9xt3sRh.js';
 import '../types-CXLAG3UU.js';
-import '../wire-5IRin4zH.js';
+import '../wire-6dzyfDE7.js';
 import '../web-push-Cs14Wp9u.js';
 
 /**

package/dist/hono/index.js

@@ -1,10 +1,10 @@
 import {
   createApiNotifications
-} from "../chunk-ORXJH3VM.js";
-import "../chunk-AHNRSA6U.js";
+} from "../chunk-TIGTBSAQ.js";
+import "../chunk-HQU4R4SG.js";
 import {
   messagesOf
-} from "../chunk-4TTYQVPK.js";
+} from "../chunk-Y34FX24X.js";
 import {
   __name
 } from "../chunk-7QVYU63E.js";

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { D as DeliveryStatus, N as NOTIFICATION_CHANNELS, a as NotificationCategory, b as NotificationChannel, c as NotificationContent, d as NotificationEvent, e as NotificationGenerator, f as NotificationLogger, g as NotificationRecipient, h as NotificationTaxonomy, i as NotificationTransport, T as TransportRecipient, t as taxonomyOf } from './types-CXLAG3UU.js';
 export { N as NotificationGeneratorRegistry, c as createGeneratorRegistry } from './generators-B9xt3sRh.js';
-export { C as ChannelMatrix, a as ChannelRow, D as DEFAULT_CHANNEL_ROW, I as InboxNotification, L as ListNotificationsResult, N as NotificationMessages, b as NotificationRow, c as NotificationWireMessages, d as defaultChannelMatrix, e as enabledChannelsOf, i as inboxWire, m as mergeChoices, f as mergeStoredRow, g as messagesOf } from './wire-5IRin4zH.js';
+export { C as ChannelMatrix, a as ChannelRow, D as DEFAULT_CHANNEL_ROW, I as InboxNotification, L as ListNotificationsResult, N as NotificationMessages, b as NotificationRow, c as NotificationWireMessages, d as defaultChannelMatrix, e as enabledChannelsOf, i as inboxWire, m as mergeChoices, f as mergeStoredRow, g as messagesOf } from './wire-6dzyfDE7.js';
 
 /** Thrown by `notify` when no generator is registered for the event type. */
 declare class UnknownNotificationTypeError extends Error {

package/dist/index.js

@@ -9,12 +9,12 @@ import {
   mergeChoices,
   mergeStoredRow,
   normalizePhoneE164
-} from "./chunk-AHNRSA6U.js";
+} from "./chunk-HQU4R4SG.js";
 import {
   NOTIFICATION_CHANNELS,
   messagesOf,
   taxonomyOf
-} from "./chunk-4TTYQVPK.js";
+} from "./chunk-Y34FX24X.js";
 import "./chunk-7QVYU63E.js";
 export {
   DEFAULT_CHANNEL_ROW,

package/dist/{jobs-DhDjrAX5.d.ts → jobs-BDZ7aGHV.d.ts}

@@ -1,5 +1,5 @@
 import { WireJobBlueprint } from '@12-apps/wiring';
-import { A as ApiNotifications } from './create-api-notifications-CgBdjfyF.js';
+import { A as ApiNotifications } from './create-api-notifications-B3u6Kx3x.js';
 
 /**
  * The two background jobs getting a message out actually needs.

package/dist/manifest/server.d.ts

@@ -1,10 +1,10 @@
 import * as _12_apps_wiring from '@12-apps/wiring';
 import { WireRequest } from '@12-apps/wiring';
-import { N as NotificationsServerConfig, A as ApiNotifications, b as NotificationsRoute } from '../create-api-notifications-CgBdjfyF.js';
-import { N as NotificationsJobDeps } from '../jobs-DhDjrAX5.js';
+import { N as NotificationsServerConfig, A as ApiNotifications, b as NotificationsRoute } from '../create-api-notifications-B3u6Kx3x.js';
+import { N as NotificationsJobDeps } from '../jobs-BDZ7aGHV.js';
 import '../generators-B9xt3sRh.js';
 import '../types-CXLAG3UU.js';
-import '../wire-5IRin4zH.js';
+import '../wire-6dzyfDE7.js';
 import '../web-push-Cs14Wp9u.js';
 
 /** One `NotificationsRoute` as the wiring contract reads it. */

package/dist/manifest/server.js

@@ -1,11 +1,11 @@
 import {
   NOTIFICATIONS_JOBS
-} from "../chunk-WU6QJLSZ.js";
+} from "../chunk-QRAXX3GR.js";
 import {
   createApiNotifications
-} from "../chunk-ORXJH3VM.js";
-import "../chunk-AHNRSA6U.js";
-import "../chunk-4TTYQVPK.js";
+} from "../chunk-TIGTBSAQ.js";
+import "../chunk-HQU4R4SG.js";
+import "../chunk-Y34FX24X.js";
 import {
   __name
 } from "../chunk-7QVYU63E.js";

package/dist/manifest/web.d.ts

@@ -1,6 +1,6 @@
-import { c as createWebNotifications } from '../create-web-notifications-Du3hTs7P.js';
+import { c as createWebNotifications } from '../create-web-notifications-BpNR8qH3.js';
 import 'react';
-import '../wire-5IRin4zH.js';
+import '../wire-6dzyfDE7.js';
 import '../types-CXLAG3UU.js';
 
 /**

package/dist/manifest/web.js

@@ -1,7 +1,7 @@
 import {
   createWebNotifications
-} from "../chunk-YE24MDS6.js";
-import "../chunk-4TTYQVPK.js";
+} from "../chunk-6HLHQDKS.js";
+import "../chunk-Y34FX24X.js";
 import "../chunk-7QVYU63E.js";
 
 // src/manifest/web.ts

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
-import { N as NotificationsApiClient } from '../create-web-notifications-Du3hTs7P.js';
-export { B as BADGE_POLL_MS, a as BADGE_RECONCILE_MS, b as BellButtonProps, I as InboxListStatus, d as InboxState, e as InboxStore, f as NotificationsHttpError, g as NotificationsPanelProps, h as NotificationsResult, i as NotificationsSignalHook, j as NotificationsSubscribe, k as NotificationsTransport, l as NotificationsWebConfig, P as PAGE_SIZE, m as PreferencesPayload, n as PreferencesScreenProps, o as PushRegistrationPayload, W as WebNotifications, p as WebPushPlatformHint, q as WebPushSetupConfig, r as createInboxStore, s as createNotificationsApiClient, c as createWebNotifications, t as httpNotificationsTransport, u as useInboxList, v as useInboxState, w as useUnreadCount } from '../create-web-notifications-Du3hTs7P.js';
+import { N as NotificationsApiClient } from '../create-web-notifications-BpNR8qH3.js';
+export { B as BADGE_POLL_MS, a as BADGE_RECONCILE_MS, b as BellButtonProps, I as InboxListStatus, d as InboxState, e as InboxStore, f as NotificationsHttpError, g as NotificationsPanelProps, h as NotificationsResult, i as NotificationsSignalHook, j as NotificationsSubscribe, k as NotificationsTransport, l as NotificationsWebConfig, P as PAGE_SIZE, m as PreferencesPayload, n as PreferencesScreenProps, o as PushRegistrationPayload, W as WebNotifications, p as WebPushPlatformHint, q as WebPushSetupConfig, r as createInboxStore, s as createNotificationsApiClient, c as createWebNotifications, t as httpNotificationsTransport, u as useInboxList, v as useInboxState, w as useUnreadCount } from '../create-web-notifications-BpNR8qH3.js';
 import { JSX } from 'react';
-import { N as NotificationMessages } from '../wire-5IRin4zH.js';
+import { N as NotificationMessages } from '../wire-6dzyfDE7.js';
 import '../types-CXLAG3UU.js';
 
 /** Inline SVG bell (no icon-library dependency in this package). */

package/dist/react/index.js

@@ -16,8 +16,8 @@ import {
   useInboxList,
   useInboxState,
   useUnreadCount
-} from "../chunk-YE24MDS6.js";
-import "../chunk-4TTYQVPK.js";
+} from "../chunk-6HLHQDKS.js";
+import "../chunk-Y34FX24X.js";
 import "../chunk-7QVYU63E.js";
 export {
   BADGE_POLL_MS,

package/dist/server/index.d.ts

@@ -1,11 +1,11 @@
-import { A as ApiNotifications } from '../create-api-notifications-CgBdjfyF.js';
-export { C as CommittedNotification, E as EMAIL_DRIVERS, c as EmailDriver, d as EmailDriverDeclaration, e as EmailMessage, f as ExtraDrivers, L as ListNotificationsInput, g as NotificationAudienceDirectory, h as NotificationChannelPolicy, i as NotificationCommittedListener, j as NotificationContactDirectory, k as NotificationCreateData, l as NotificationDelegate, m as NotificationDeliveryDelegate, n as NotificationDeliveryRow, o as NotificationDeliveryWhere, p as NotificationDispatchScheduler, q as NotificationInboxStore, r as NotificationPageAfter, s as NotificationPreferenceDelegate, t as NotificationPreferenceRow, u as NotificationPreferenceStore, v as NotificationRouter, w as NotificationWhere, a as NotificationsActor, x as NotificationsApiError, y as NotificationsDb, z as NotificationsDbClient, B as NotificationsDbProvider, D as NotificationsRequest, F as NotificationsResponse, b as NotificationsRoute, N as NotificationsServerConfig, G as NotifyByPermission, H as NotifyOptions, I as NotifyResult, P as PermissionNotificationResult, J as PermissionNotificationSkip, K as PushSubscriptionDelegate, M as PushSubscriptionInput, O as PushSubscriptionRow, Q as PushSubscriptionStore, S as SMS_DRIVERS, R as SmsDriver, T as SmsDriverDeclaration, U as SmsMessage, V as TransportDeclaration, W as TransportRegistry, X as WHATSAPP_DRIVERS, Y as WhatsAppDriver, Z as WhatsAppDriverDeclaration, _ as WhatsAppMessage, $ as createApiNotifications, a0 as createTransportRegistry, a1 as emailTransport, a2 as foldApiError, a3 as formatEmail, a4 as formatSms, a5 as formatWhatsApp, a6 as ok, a7 as smsTransport, a8 as whatsAppTransport } from '../create-api-notifications-CgBdjfyF.js';
+import { A as ApiNotifications } from '../create-api-notifications-B3u6Kx3x.js';
+export { C as CommittedNotification, E as EMAIL_DRIVERS, c as EmailDriver, d as EmailDriverDeclaration, e as EmailMessage, f as ExtraDrivers, L as ListNotificationsInput, g as NotificationAudienceDirectory, h as NotificationChannelPolicy, i as NotificationCommittedListener, j as NotificationContactDirectory, k as NotificationCreateData, l as NotificationDelegate, m as NotificationDeliveryDelegate, n as NotificationDeliveryRow, o as NotificationDeliveryWhere, p as NotificationDispatchScheduler, q as NotificationInboxStore, r as NotificationPageAfter, s as NotificationPreferenceDelegate, t as NotificationPreferenceRow, u as NotificationPreferenceStore, v as NotificationRouter, w as NotificationWhere, a as NotificationsActor, x as NotificationsApiError, y as NotificationsDb, z as NotificationsDbClient, B as NotificationsDbProvider, D as NotificationsRequest, F as NotificationsResponse, b as NotificationsRoute, N as NotificationsServerConfig, G as NotifyByPermission, H as NotifyOptions, I as NotifyResult, P as PermissionNotificationResult, J as PermissionNotificationSkip, K as PushSubscriptionDelegate, M as PushSubscriptionInput, O as PushSubscriptionRow, Q as PushSubscriptionStore, S as SMS_DRIVERS, R as SmsDriver, T as SmsDriverDeclaration, U as SmsMessage, V as TransportDeclaration, W as TransportRegistry, X as WHATSAPP_DRIVERS, Y as WhatsAppDriver, Z as WhatsAppDriverDeclaration, _ as WhatsAppMessage, $ as createApiNotifications, a0 as createTransportRegistry, a1 as emailTransport, a2 as foldApiError, a3 as formatEmail, a4 as formatSms, a5 as formatWhatsApp, a6 as ok, a7 as smsTransport, a8 as whatsAppTransport } from '../create-api-notifications-B3u6Kx3x.js';
 export { D as DriverDeclarationBase, F as FetchImpl, N as NotificationProviderError, W as WEB_PUSH_DRIVERS, a as WebPushDriverDeclaration, b as WebPushMessage, c as WebPushSender, d as WebPushSubscription, e as WebPushSubscriptionSource, f as absoluteLink, g as formatWebPush, w as webPushTransport } from '../web-push-Cs14Wp9u.js';
 import { NotifyPort } from '@12-apps/wiring/ports';
-export { a as NOTIFICATIONS_DRAIN_CRON, b as NOTIFICATIONS_DRAIN_LEASE_MS, c as NOTIFICATIONS_JOBS, d as NOTIFICATIONS_SWEEP_QUEUE, N as NotificationsJobDeps } from '../jobs-DhDjrAX5.js';
+export { a as NOTIFICATIONS_DRAIN_CRON, b as NOTIFICATIONS_DRAIN_LEASE_MS, c as NOTIFICATIONS_JOBS, d as NOTIFICATIONS_SWEEP_QUEUE, N as NotificationsJobDeps } from '../jobs-BDZ7aGHV.js';
 import '../generators-B9xt3sRh.js';
 import '../types-CXLAG3UU.js';
-import '../wire-5IRin4zH.js';
+import '../wire-6dzyfDE7.js';
 import '@12-apps/wiring';
 
 /**

package/dist/server/index.js

@@ -4,7 +4,7 @@ import {
   NOTIFICATIONS_JOBS,
   NOTIFICATIONS_SWEEP_QUEUE,
   wireNotifyPort
-} from "../chunk-WU6QJLSZ.js";
+} from "../chunk-QRAXX3GR.js";
 import {
   EMAIL_DRIVERS,
   NotificationProviderError,
@@ -25,9 +25,9 @@ import {
   smsTransport,
   webPushTransport,
   whatsAppTransport
-} from "../chunk-ORXJH3VM.js";
-import "../chunk-AHNRSA6U.js";
-import "../chunk-4TTYQVPK.js";
+} from "../chunk-TIGTBSAQ.js";
+import "../chunk-HQU4R4SG.js";
+import "../chunk-Y34FX24X.js";
 import "../chunk-7QVYU63E.js";
 export {
   EMAIL_DRIVERS,

package/dist/{wire-5IRin4zH.d.ts → wire-6dzyfDE7.d.ts}

@@ -83,7 +83,20 @@ interface NotificationMessages extends NotificationWireMessages {
     devicePushEnabling: string;
 }
 /**
- * The messages in force.
+ * What a copy field takes once its words can follow a reader.
+ *
+ * Declared here rather than imported from `@12-apps/i18n`: this package must
+ * stay liftable into a repo that has never heard of it, so the two agree
+ * STRUCTURALLY and nothing forces the dependency. The context is deliberately
+ * loose — a raw tag off the wire, unnarrowed — because matching it is the host
+ * resolver's job, not this package's.
+ */
+type NotificationsCopyResolver<T> = (context: {
+    readonly locale?: string | null;
+}) => T;
+type NotificationsCopySource<T> = T | NotificationsCopyResolver<T>;
+/**
+ * The messages in force, for ONE reader.
  *
  * A pass-through rather than a merge: there is nothing left to merge WITH, and
  * that is the point of the change. The old version spread the host's table over
@@ -94,11 +107,24 @@ interface NotificationMessages extends NotificationWireMessages {
  * the same screen.
  *
  * Kept as a function because all three mounts read it off a config object, and
- * because a later rule (a blank-string refusal, say) belongs in one place.
+ * because a later rule (a blank-string refusal, say) belongs in one place —
+ * which is exactly what made it the right place to put the RESOLUTION when the
+ * field learned to take a resolver.
+ *
+ * **Call it where the sentence is used.** `createApiNotifications` runs once
+ * per process, and at least one host memoises its call behind an `if
+ * (assembled) return assembled;`, so a value read there answers every later
+ * request in the language the process started with — and a single-locale host
+ * cannot tell the difference. The route handlers call it per request; the
+ * parsers below them keep taking a plain pack, so one request resolves exactly
+ * once and no helper can disagree with another about the language.
+ *
+ * The generic survives the widening: a host whose pack carries extra keys of
+ * its own still gets them back, resolver or not.
  */
 declare function messagesOf<T extends NotificationWireMessages>(config: {
-    messages: T;
-}): T;
+    messages: NotificationsCopySource<T>;
+}, locale?: string): T;
 
 /**
  * The preference POLICY, with no storage in it (12-15): which channels a
@@ -194,4 +220,4 @@ interface NotificationRow {
 /** Row → wire. Dates become ISO strings; a null `data` becomes `{}`. */
 declare function inboxWire(row: NotificationRow): InboxNotification;
 
-export { type ChannelMatrix as C, DEFAULT_CHANNEL_ROW as D, type InboxNotification as I, type ListNotificationsResult as L, type NotificationMessages as N, type ChannelRow as a, type NotificationRow as b, type NotificationWireMessages as c, defaultChannelMatrix as d, enabledChannelsOf as e, mergeStoredRow as f, messagesOf as g, inboxWire as i, mergeChoices as m };
+export { type ChannelMatrix as C, DEFAULT_CHANNEL_ROW as D, type InboxNotification as I, type ListNotificationsResult as L, type NotificationMessages as N, type ChannelRow as a, type NotificationRow as b, type NotificationWireMessages as c, defaultChannelMatrix as d, enabledChannelsOf as e, mergeStoredRow as f, messagesOf as g, type NotificationsCopySource as h, inboxWire as i, mergeChoices as m };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/notifications",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "type": "module",
   "sideEffects": false,
   "description": "Plug-and-play notification system (12-15): an always-on in-app inbox, per-user × per-category channel preferences, and email / SMS / WhatsApp / web-push transports behind vendor DRIVERS so a second provider is a config entry. Framework-free core (.), host-mounted backend surface (./server: inbox / preferences / push-subscription endpoints, the channel router with delivery records + retry sweep, the permission fan-out, duck-typed Prisma seam), Hono adapter (./hono), React surface (./react: bell + badge, inbox drawer, preferences screen), VAPID sender (./web-push) and the package-owned Prisma partial + migrations. Standardized adoption contract in ADOPTING.md.",
@@ -51,7 +51,7 @@
     "prisma:sync:check": "node scripts/sync-notifications-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/ui": "^6.10.0"
+    "@12-apps/ui": "^6.11.0"
   },
   "peerDependencies": {
     "@12-apps/wiring": ">=1.3.0",

package/src/messages.ts

@@ -85,7 +85,21 @@ export interface NotificationMessages extends NotificationWireMessages {
 }
 
 /**
- * The messages in force.
+ * What a copy field takes once its words can follow a reader.
+ *
+ * Declared here rather than imported from `@12-apps/i18n`: this package must
+ * stay liftable into a repo that has never heard of it, so the two agree
+ * STRUCTURALLY and nothing forces the dependency. The context is deliberately
+ * loose — a raw tag off the wire, unnarrowed — because matching it is the host
+ * resolver's job, not this package's.
+ */
+export type NotificationsCopyResolver<T> = (context: {
+  readonly locale?: string | null;
+}) => T;
+export type NotificationsCopySource<T> = T | NotificationsCopyResolver<T>;
+
+/**
+ * The messages in force, for ONE reader.
  *
  * A pass-through rather than a merge: there is nothing left to merge WITH, and
  * that is the point of the change. The old version spread the host's table over
@@ -96,8 +110,27 @@ export interface NotificationMessages extends NotificationWireMessages {
  * the same screen.
  *
  * Kept as a function because all three mounts read it off a config object, and
- * because a later rule (a blank-string refusal, say) belongs in one place.
+ * because a later rule (a blank-string refusal, say) belongs in one place —
+ * which is exactly what made it the right place to put the RESOLUTION when the
+ * field learned to take a resolver.
+ *
+ * **Call it where the sentence is used.** `createApiNotifications` runs once
+ * per process, and at least one host memoises its call behind an `if
+ * (assembled) return assembled;`, so a value read there answers every later
+ * request in the language the process started with — and a single-locale host
+ * cannot tell the difference. The route handlers call it per request; the
+ * parsers below them keep taking a plain pack, so one request resolves exactly
+ * once and no helper can disagree with another about the language.
+ *
+ * The generic survives the widening: a host whose pack carries extra keys of
+ * its own still gets them back, resolver or not.
  */
-export function messagesOf<T extends NotificationWireMessages>(config: { messages: T }): T {
-  return config.messages;
+export function messagesOf<T extends NotificationWireMessages>(
+  config: { messages: NotificationsCopySource<T> },
+  locale?: string,
+): T {
+  const source = config.messages;
+  return typeof source === 'function'
+    ? (source as NotificationsCopyResolver<T>)({ locale })
+    : source;
 }

package/src/server/context.ts

@@ -32,6 +32,16 @@ export interface NotificationsRequest {
   body?: unknown;
   /** Headers the surface reads (`user-agent`, for the device hint). */
   headers?: Record<string, string | undefined>;
+  /**
+   * The language to answer this caller in, as a language tag (`pt-BR`,
+   * `en-US`) — the same field `@12-apps/wiring`'s `WireRequest` carries.
+   *
+   * Populated by the host's adapter, which is the only layer that can
+   * negotiate one. Absent is meaningful and not an error: a host with one
+   * audience never sets it, and this surface must then answer with the words
+   * it was configured with rather than invent a language.
+   */
+  locale?: string;
 }
 
 /** What a handler answers with; the adapter maps it onto its response type. */

package/src/server/create-api-notifications.ts

@@ -1,5 +1,8 @@
 import { createGeneratorRegistry, type NotificationGeneratorRegistry } from '../generators';
-import { messagesOf, type NotificationWireMessages } from '../messages';
+import type {
+  NotificationsCopySource,
+  NotificationWireMessages,
+} from '../messages';
 import type { ChannelRow } from '../preferences-core';
 import {
   taxonomyOf,
@@ -104,8 +107,15 @@ export interface NotificationsServerConfig {
   onInboxChanged?: (userId: string) => void;
   /** The host's authorization engine, for `notifyByPermission`. */
   audience?: NotificationAudienceDirectory;
-  /** User-facing copy overrides (pt-BR product copy by default). */
-  messages: NotificationWireMessages;
+  /**
+   * Every user-facing sentence this surface can produce — REQUIRED host config.
+   *
+   * A pack, or a RESOLVER for a host whose callers do not share a language.
+   * Passed to the routes UNRESOLVED: this factory runs once per process (and
+   * at least one host memoises its call), so resolving here would answer every
+   * later request in the language the process started with.
+   */
+  messages: NotificationsCopySource<NotificationWireMessages>;
   /** The host's logger. Defaults to the console. */
   logger?: NotificationLogger;
 }
@@ -132,8 +142,14 @@ export interface ApiNotifications {
   registerGenerator: NotificationGeneratorRegistry['register'];
   /** The declared transports, for diagnostics and availability probes. */
   transports: TransportRegistry;
-  /** The copy in force, so a host's own screens can reuse a sentence. */
-  messages: NotificationWireMessages;
+  /**
+   * The copy source in force, so a host's own screens can reuse a sentence.
+   *
+   * The SOURCE rather than a resolved pack, for the same reason the routes get
+   * one: a host screen serving two readers must be able to ask per reader.
+   * Read it with `messagesOf({ messages }, locale)`.
+   */
+  messages: NotificationsCopySource<NotificationWireMessages>;
 }
 
 /** Drop the keys the host left unset, so an absent seam stays absent. */
@@ -150,7 +166,15 @@ const consoleLogger: NotificationLogger = {
 };
 
 export function createApiNotifications(config: NotificationsServerConfig): ApiNotifications {
-  const messages = messagesOf(config);
+  /**
+   * The SOURCE travels; nothing is resolved here.
+   *
+   * This factory runs once per process — and at least one host memoises its
+   * call behind an `if (assembled) return assembled;` — so a `messagesOf(config)`
+   * on this line would word every later request in the language the process
+   * started with. The handlers resolve per request instead.
+   */
+  const messages = config.messages;
   const taxonomy = taxonomyOf(config);
   const logger = config.logger ?? consoleLogger;
 

package/src/server/routes.ts

@@ -1,4 +1,8 @@
-import type { NotificationWireMessages } from '../messages';
+import {
+  messagesOf,
+  type NotificationsCopySource,
+  type NotificationWireMessages,
+} from '../messages';
 import { NOTIFICATION_CHANNELS, type NotificationChannel } from '../types';
 
 import {
@@ -40,7 +44,11 @@ interface NotificationRoutesDeps {
   transports: TransportRegistry;
   contacts: NotificationContactDirectory;
   categories: readonly string[];
-  messages: NotificationWireMessages;
+  /**
+   * The SOURCE, not a resolved pack — the route table is built once per
+   * process and every handler below runs per request.
+   */
+  messages: NotificationsCopySource<NotificationWireMessages>;
   /** Told when a write actually changed something (for a realtime hint). */
   onInboxChanged?: (userId: string) => void;
 }
@@ -98,8 +106,13 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
     {
       method: 'GET',
       path: '/notifications',
-      handle: guarded(async ({ actor, query }) =>
-        ok(await deps.inbox.list(actor.userId, parseListQuery(query, deps.messages))),
+      handle: guarded(async ({ actor, query, locale }) =>
+        ok(
+          await deps.inbox.list(
+            actor.userId,
+            parseListQuery(query, messagesOf(deps, locale)),
+          ),
+        ),
       ),
     },
     {
@@ -113,8 +126,8 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
     {
       method: 'POST',
       path: '/notifications/mark-read',
-      handle: guarded(async ({ actor, body }) => {
-        const target = parseMarkReadBody(body, deps.messages);
+      handle: guarded(async ({ actor, body, locale }) => {
+        const target = parseMarkReadBody(body, messagesOf(deps, locale));
         const updated =
           'all' in target
             ? await deps.inbox.markAllRead(actor.userId)
@@ -131,10 +144,10 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
       method: 'POST',
       // POST, not DELETE, because the ids travel in a JSON body.
       path: '/notifications/delete',
-      handle: guarded(async ({ actor, body }) => {
+      handle: guarded(async ({ actor, body, locale }) => {
         const deleted = await deps.inbox.softDelete(
           actor.userId,
-          parseDeleteBody(body, deps.messages),
+          parseDeleteBody(body, messagesOf(deps, locale)),
         );
         // Same rule as mark-read. A delete can move the badge too — an UNREAD
         // row that is removed takes its place in the count with it.
@@ -155,10 +168,13 @@ function preferenceRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
     {
       method: 'PUT',
       path: '/notification-preferences',
-      handle: guarded(async ({ actor, body }) => {
+      handle: guarded(async ({ actor, body, locale }) => {
         // The dispatch pipeline reads these on every emit, so a save takes
         // effect immediately — no cache to invalidate.
-        await deps.preferences.save(actor.userId, parsePreferencesBody(body, deps.messages));
+        await deps.preferences.save(
+          actor.userId,
+          parsePreferencesBody(body, messagesOf(deps, locale)),
+        );
         return ok(await preferencesPayload(deps, actor.userId));
       }),
     },
@@ -170,8 +186,8 @@ function pushRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
     {
       method: 'GET',
       path: '/push-subscriptions',
-      handle: guarded(async ({ actor, query }) => {
-        const endpoint = parsePushEndpointQuery(query, deps.messages);
+      handle: guarded(async ({ actor, query, locale }) => {
+        const endpoint = parsePushEndpointQuery(query, messagesOf(deps, locale));
         return ok({
           // null = web push is not configured on this deployment.
           vapidPublicKey: deps.transports.webPushPublicKey(),
@@ -188,8 +204,8 @@ function pushRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
     {
       method: 'POST',
       path: '/push-subscriptions',
-      handle: guarded(async ({ actor, body, headers }) => {
-        const input = parsePushSubscriptionBody(body, deps.messages);
+      handle: guarded(async ({ actor, body, headers, locale }) => {
+        const input = parsePushSubscriptionBody(body, messagesOf(deps, locale));
         const userAgent = headers?.['user-agent'];
         await deps.pushSubscriptions.save(actor.userId, {
           ...input,
@@ -202,10 +218,10 @@ function pushRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
       method: 'DELETE',
       // The endpoint is a long opaque URL, unusable as a path param.
       path: '/push-subscriptions',
-      handle: guarded(async ({ actor, body }) => {
+      handle: guarded(async ({ actor, body, locale }) => {
         await deps.pushSubscriptions.remove(
           actor.userId,
-          parsePushEndpointBody(body, deps.messages),
+          parsePushEndpointBody(body, messagesOf(deps, locale)),
         );
         return ok({ count: await deps.pushSubscriptions.count(actor.userId) });
       }),