@opencxh/domain 1.186.0 → 1.188.0

package/dist/platform/notification.d.ts

@@ -0,0 +1,139 @@
+import { LocaleBundle } from '../entities/analytics/dashboard';
+/**
+ * Role group of an app that declares its own notification kinds.
+ *
+ * A constant and not a literal at both ends: `Bridge.providers.list` answers an unknown group
+ * with an empty list, so a typo would read as "no app sends notifications". Same reason
+ * `ONBOARDING_SOURCE_PROVIDER_GROUP` is a constant.
+ */
+export declare const NOTIFICATION_SOURCE_PROVIDER_GROUP = "notification-source";
+/**
+ * Text a reader renders without the sender knowing what it says: an i18n key from the declaring
+ * app's own bundle, plus values for `{name}` placeholders.
+ *
+ * Not a rendered string, because one notification is read on a laptop in Dutch and pushed to a
+ * phone in English. Not a bare key either: half of these lines carry data ("Vincent mentioned you")
+ * and a key per person does not exist.
+ *
+ * Sources write **bare** keys; the hub stamps the namespace (see `qualifyText` in platform-api).
+ */
+export interface NotificationText {
+    key: string;
+    vars?: Record<string, string | number>;
+}
+/**
+ * One switchable kind of notification, declared by the app that sends it.
+ *
+ * Declared rather than listed centrally, because only the owning app knows that "you were
+ * mentioned" and "a task was assigned to you" are different questions to a reader. A hard-coded
+ * list breaks at app N+1 — the map it replaces is `DEFAULT_KIND_ENABLED` in comms' push dispatch.
+ */
+export interface NotificationKindDef {
+    /** Bare in the describe (`"mentioned"`); the hub stamps it to `"communication:mentioned"`. */
+    id: string;
+    title: NotificationText;
+    description?: NotificationText;
+    /** What holds until the user touches a switch. Per transport, because they differ in practice. */
+    defaults: {
+        inApp: boolean;
+        push: boolean;
+    };
+    /** `true` = the user may not switch it off (an incoming call). Absent = they may. */
+    mandatory?: boolean;
+    /**
+     * Lucide icon name for the toast tile (`"at-sign"`, `"user-check"`). Declared with the kind
+     * because the icon is part of what the kind *is* — the reader tells a mention from an
+     * assignment by its shape before reading a word. Absent falls back to the toast type icon.
+     */
+    icon?: string;
+    /** Sort hint within an app. Ties break on id, so the settings screen stays stable. */
+    order?: number;
+}
+/**
+ * Payload of `GET /provider/notification/describe`.
+ *
+ * Bare, not wrapped in `ResponseFactory` — that is how the fan-out reads it, same as
+ * `analytics-source` and `onboarding-source`.
+ */
+export interface NotificationSourceDescribe {
+    /** The declaring app (== manifest name == `req.source.app`). */
+    source: string;
+    kinds: NotificationKindDef[];
+    /** Texts for every key above, in every language this app ships. `flattenLocales()` helps. */
+    locales?: LocaleBundle;
+}
+/** Where clicking a notification takes you. App-relative, like an onboarding route link. */
+export interface NotificationLink {
+    app: string;
+    path: string;
+}
+/**
+ * The person (or assistant) whose action caused this.
+ *
+ * Carried as a plain name and not a userId: a notification is read long after it was written, and
+ * a lookup per row means the panel cannot render until every actor resolves. Initials and the
+ * avatar colour are derived from the name by `Avatar` with `tone="identity"`, so the same person
+ * keeps one colour on every surface without this ever storing one.
+ */
+export interface NotificationActor {
+    name: string;
+    avatarUrl?: string;
+}
+export interface Notification {
+    id: string;
+    organizationId: string;
+    userId: string;
+    /** The app that sent it. Derived from the caller, never from the body. */
+    source: string;
+    /** Namespaced: `"communication:mentioned"`. */
+    kind: string;
+    /** What happened, without the actor's name in it — the panel renders the name in front. */
+    title: NotificationText;
+    /** The quoted line: the comment text, the task name. */
+    body?: NotificationText;
+    /** Where it happened ("RE: EYLO / Leufgens"), shown with the timestamp on the third line. */
+    context?: NotificationText;
+    actor?: NotificationActor;
+    link?: NotificationLink;
+    /** Free-form; travels untouched into the push payload. */
+    data?: Record<string, unknown>;
+    createdAt: number;
+    readAt?: number;
+}
+/** Body of `POST notification/send`. The only thing that crosses an app boundary. */
+export interface NotifyRequest {
+    to: {
+        userIds: string[];
+    } | {
+        userId: string;
+    };
+    /** Bare; stamped with the calling app's name server-side. */
+    kind: string;
+    title: NotificationText;
+    body?: NotificationText;
+    context?: NotificationText;
+    actor?: NotificationActor;
+    link?: NotificationLink;
+    data?: Record<string, unknown>;
+    /**
+     * Wake the devices without leaving a row behind. For a signal that is meaningless once it is
+     * over — an incoming call you already missed is not something to catch up on. Default `false`.
+     */
+    transient?: boolean;
+    /** Passed straight to push; a newer envelope with the same key replaces an undelivered one. */
+    collapseKey?: string;
+}
+export interface NotifyResult {
+    /** Rows written. `0` for a transient notification, and for a send nobody had switched on. */
+    created: number;
+}
+/** Result of the kinds fan-out, as the settings screen reads it. */
+export interface NotificationCatalog {
+    kinds: NotificationKindDef[];
+    locales: LocaleBundle;
+    /** Sources that did not answer, so the screen can say who is missing instead of silently thinning. */
+    degradedApps: string[];
+}
+/** Per-device preference keys. Two transports, two keys — see `docs/` and the settings screen. */
+export type NotificationPrefTransport = "inapp" | "push";
+export declare const notificationPrefKey: (transport: NotificationPrefTransport, kind: string) => string;

package/dist/platform/push.d.ts

@@ -16,7 +16,13 @@ export interface PushSubscription {
     createdAt: number;
     lastSeenAt: number;
 }
-export type PushKind = "wake" | "incoming-call" | "message" | "presence" | "notification" | "custom";
+/**
+ * The platform's own kinds, plus whatever a `notification-source` app declares
+ * (`"communication:mentioned"`). Open like {@link ExtensionContext}: the closed union kept
+ * autocomplete but made an app-declared kind unexpressible, and per-kind device preferences
+ * are exactly what apps must be able to declare.
+ */
+export type PushKind = "wake" | "incoming-call" | "message" | "presence" | "notification" | "custom" | (string & {});
 export interface PushDisplay {
     title: string;
     body?: string;

package/dist/platform/ui.d.ts

@@ -113,6 +113,13 @@ export interface ToastConfig {
      * combine with `persistent: true` so it can't be auto- or hand-dismissed.
      */
     closable?: boolean;
+    /**
+     * Lucide icon name for the leading tile, overriding the one implied by `type`.
+     *
+     * A notification says what kind of attention it wants (a mention, an assignment) and `type` only
+     * says how loud it is, so the two cannot be the same field.
+     */
+    icon?: string;
     actions?: {
         label: string;
         onClick: () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.186.0",
+  "version": "1.188.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",