@tolinax/ayoune-interfaces 2026.46.0 → 2026.48.0

package/interfaces/INotification.d.ts

@@ -1,4 +1,6 @@
 import { IDefaultFields } from "./IDefaultFields";
+import { INotificationAction } from "./INotificationAction";
+import { INotificationAttachment, INotificationSender } from "./INotificationAttachment";
 export interface INotification extends IDefaultFields {
     _customerID: ObjectId;
     _clientID?: ObjectId[];
@@ -14,4 +16,64 @@ export interface INotification extends IDefaultFields {
     obj?: string;
     view?: string;
     params?: object;
+    /**
+     * Who triggered the notification. Optional — system events pass `null`
+     * and the consumer falls back to a generic `aYOUne` header.
+     */
+    sender?: INotificationSender;
+    /**
+     * Typed rich-content attachments — calendar entries, tasks, invoices,
+     * orders, etc. — rendered as inline preview cards in the notifications
+     * panel. See `INotificationAttachment` for the supported types and
+     * the enrichment contract (producer may provide `{ type, _id }` and the
+     * orchestrator fills `preview` via model lookup).
+     */
+    attachments?: INotificationAttachment[];
+    /**
+     * Action buttons rendered under the notification (1-3 typical), and —
+     * where the OS supports it — as native Web-Push action buttons (first
+     * three on modern Android Chrome / Edge / Samsung Internet).
+     */
+    actions?: INotificationAction[];
+    /**
+     * Hero image shown in the expanded native push notification (Android).
+     * Rendered as a 16:9 banner above the body. Great for order thumbnails,
+     * product photos, meeting cover images, customer logos, illustrative
+     * GIFs (animated GIFs render as stills on most push stacks — keep
+     * static / use first-frame if animated).
+     *
+     * When absent, the adapter falls back to the first `attachments[*].preview.image`
+     * so entity-bearing notifications automatically get a thumbnail.
+     */
+    image?: string;
+    /**
+     * Monochrome status-bar badge (Android). 24x24 SVG or PNG. Customer-
+     * branding goes here — renders as the tiny icon next to the clock.
+     * Falls back to the platform-default badge when absent.
+     */
+    badge?: string;
+    /**
+     * Grouping / dedupe key. Two notifications with the same `tag` replace
+     * each other on the device instead of stacking. Used for live-update
+     * flows (order status, approval decisions, running job progress) where
+     * only the latest state should be visible.
+     *
+     * When absent, the adapter auto-derives `${entityType}:${entity._id || Date.now()}`
+     * so repeated notifications about the same entity naturally group.
+     */
+    tag?: string;
+    /**
+     * Re-alert (sound + vibration) when a notification with the same `tag`
+     * arrives. Default true — users expect "your order is now OUT FOR
+     * DELIVERY" to buzz even if the previous "being prepared" is still on
+     * screen. Set false for silent status updates (progress bars, typing
+     * indicators).
+     */
+    renotify?: boolean;
+    /**
+     * Keep the notification on screen until the user explicitly dismisses
+     * it (Android > 7). Use for approval requests, critical alerts, or
+     * anything that must not scroll out of awareness. Default false.
+     */
+    requireInteraction?: boolean;
 }

package/interfaces/INotificationAction.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Action buttons attached to a notification. Rendered both as inline buttons
+ * in the in-app notifications panel and (up to two primary actions) as native
+ * Web-Push action buttons on supporting platforms.
+ *
+ * Four dispatch modes:
+ *   - `link`       — internal router navigation (`href` relative to the app)
+ *   - `api`        — `fetch()` call to an absolute endpoint, optionally with
+ *                    a confirm prompt; the service-worker can execute this
+ *                    without the PWA being open (Bearer-token attached).
+ *   - `reply`      — native browser reply text field (if supported) OR a
+ *                    dialog in the PWA; the text is POSTed to `endpoint`.
+ *   - `ai-copilot` — opens the Comm-Sidebar Copilot panel with
+ *                    `copilotContext` pre-populated as the first user message.
+ */
+export type NotificationActionType = "link" | "api" | "reply" | "ai-copilot";
+/** Visual weight of the action button. */
+export type NotificationActionStyle = "primary" | "secondary" | "danger";
+export interface INotificationAction {
+    /** Stable identifier per notification — used as the Web-Push `action` id. */
+    id: string;
+    /** Button label. May be a literal or an i18n key. */
+    label: string;
+    type: NotificationActionType;
+    style?: NotificationActionStyle;
+    /** Material icon name rendered before the label. */
+    icon?: string;
+    /** For `type: "link"` — absolute or app-relative route. */
+    href?: string;
+    /** For `type: "api"` or `type: "reply"` — absolute endpoint (service-worker
+     *  executable). POST is the default for mutation-ish actions. */
+    endpoint?: string;
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Static payload merged with dynamic input (reply text, notification id). */
+    body?: Record<string, unknown>;
+    /** Confirmation prompt before firing (useful for destructive actions). */
+    confirmLabel?: string;
+    /** For `type: "ai-copilot"` — the prompt pre-populated into the Copilot
+     *  panel when the user taps this action. Supports `{{variable}}` tokens
+     *  that are rendered against the notification's `data` context before
+     *  being inserted into the input. */
+    copilotContext?: string;
+    /** Should this action close/dismiss the notification after firing? */
+    dismissOnComplete?: boolean;
+}

package/interfaces/INotificationAction.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/interfaces/INotificationAttachment.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Structured rich-content attachments for notifications (and — in phase 4 —
+ * chat messages). Mirrors the legacy AngularJS attachment system documented
+ * in `archive/legacy-angular1/pug/chatsidebar.pug:248-334`, where chat
+ * messages carried typed entity references (`type` + `content` + `preview`)
+ * that the renderer switched over to display inline entity cards.
+ *
+ * Producer contract:
+ *   1. The caller of `POST /notifications/send` may provide either:
+ *      - a bare reference: `{ type, _id }` — the orchestrator enriches it by
+ *        looking up the entity and projecting the relevant fields into
+ *        `preview`, OR
+ *      - a fully-formed attachment with `preview` already populated — skips
+ *        the lookup (use when the caller already has the data loaded).
+ *   2. Consumers (comm-sidebar notifications-panel, mobile-app PWA) dispatch
+ *      on `type` and render a type-specific preview component, falling back
+ *      to a generic card for unknown types.
+ *
+ * Phase 1 ships 5 core types. Subsequent phases add the remaining 12+
+ * types from the legacy chat system (document, consumer, contract,
+ * shipping, productionorder, creditnote, internalorder, offer, assignment,
+ * question, snippet, media).
+ */
+export type NotificationAttachmentType = "calendarentry" | "task" | "invoice" | "permissionrequest" | "supplierorder";
+/** Shared shape — all previews carry an optional deep-link override and
+ *  an optional thumbnail image. The image is used both by the in-app
+ *  preview card (rendered as a left-aligned thumbnail beside the metadata)
+ *  and by the native push adapter (the first attachment with an image
+ *  becomes the notification's hero banner on Android). */
+interface INotificationAttachmentBase {
+    /** Reference to the source entity (the document `_id`). Required for
+     *  enrichment and deep-linking. */
+    _id: ObjectId;
+    /** Optional router path used when the user taps the preview card.
+     *  When absent, the consumer falls back to `/{type}/{_id}`. */
+    href?: string;
+    /** Optional image URL — product thumbnail, supplier logo, meeting
+     *  cover, customer branding. Absolute URL (served from media CDN or
+     *  customer-meta). */
+    image?: string;
+}
+export interface ICalendarEntryPreview extends INotificationAttachmentBase {
+    summary?: string;
+    description?: string;
+    start?: Date | string;
+    end?: Date | string;
+    typ?: string;
+    status?: string;
+    location?: string;
+    allDay?: boolean;
+    organizer?: {
+        _id?: ObjectId;
+        name?: string;
+        email?: string;
+    };
+    attendees?: Array<{
+        _id?: ObjectId;
+        name?: string;
+        email?: string;
+        rsvp?: "accepted" | "declined" | "tentative" | "pending";
+    }>;
+}
+export interface ITaskPreview extends INotificationAttachmentBase {
+    title?: string;
+    ticketIdentifier?: string;
+    status?: string;
+    priority?: string;
+    type?: string;
+    due?: Date | string;
+    assignee?: {
+        _id?: ObjectId;
+        name?: string;
+        avatar?: string;
+    };
+    project?: {
+        _id?: ObjectId;
+        name?: string;
+    };
+    points?: number;
+}
+export interface IInvoicePreview extends INotificationAttachmentBase {
+    nbr?: number;
+    referenceNumber?: string;
+    title?: string;
+    total?: number;
+    currency?: string;
+    dueDate?: Date | string;
+    paid?: boolean;
+    status?: string;
+    receiver?: {
+        _id?: ObjectId;
+        name?: string;
+    };
+}
+export interface IPermissionRequestPreview extends INotificationAttachmentBase {
+    reason?: string;
+    permissionName?: string;
+    askedOn?: Date | string;
+    fromUser?: {
+        _id?: ObjectId;
+        name?: string;
+        avatar?: string;
+    };
+    valid_from?: Date | string;
+    valid_till?: Date | string;
+    approved?: boolean;
+    declined?: boolean;
+    temporary?: boolean;
+}
+export interface ISupplierOrderPreview extends INotificationAttachmentBase {
+    nbr?: string | number;
+    shopOrderNbr?: string;
+    title?: string;
+    total?: number;
+    currency?: string;
+    confirmed?: boolean;
+    needsInternalApproval?: string;
+    internalApproved?: boolean;
+    internalDeclined?: boolean;
+    supplier?: {
+        _id?: ObjectId;
+        name?: string;
+    };
+    expectedDelivery?: Date | string;
+}
+export type INotificationAttachment = {
+    type: "calendarentry";
+    preview: ICalendarEntryPreview;
+} | {
+    type: "task";
+    preview: ITaskPreview;
+} | {
+    type: "invoice";
+    preview: IInvoicePreview;
+} | {
+    type: "permissionrequest";
+    preview: IPermissionRequestPreview;
+} | {
+    type: "supplierorder";
+    preview: ISupplierOrderPreview;
+};
+/** Producer-side shape — accepts either a bare reference (orchestrator will
+ *  enrich) or a fully-populated attachment. */
+export type INotificationAttachmentInput = {
+    type: NotificationAttachmentType;
+    _id: ObjectId;
+} | INotificationAttachment;
+/** Sender metadata carried on the notification document so the in-app panel
+ *  can show "Alice assigned you a task" with the avatar of the triggering
+ *  actor rather than a faceless system row. */
+export interface INotificationSender {
+    _userId?: ObjectId;
+    name?: string;
+    avatar?: string;
+    email?: string;
+}
+export {};

package/interfaces/INotificationAttachment.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Structured rich-content attachments for notifications (and — in phase 4 —
+ * chat messages). Mirrors the legacy AngularJS attachment system documented
+ * in `archive/legacy-angular1/pug/chatsidebar.pug:248-334`, where chat
+ * messages carried typed entity references (`type` + `content` + `preview`)
+ * that the renderer switched over to display inline entity cards.
+ *
+ * Producer contract:
+ *   1. The caller of `POST /notifications/send` may provide either:
+ *      - a bare reference: `{ type, _id }` — the orchestrator enriches it by
+ *        looking up the entity and projecting the relevant fields into
+ *        `preview`, OR
+ *      - a fully-formed attachment with `preview` already populated — skips
+ *        the lookup (use when the caller already has the data loaded).
+ *   2. Consumers (comm-sidebar notifications-panel, mobile-app PWA) dispatch
+ *      on `type` and render a type-specific preview component, falling back
+ *      to a generic card for unknown types.
+ *
+ * Phase 1 ships 5 core types. Subsequent phases add the remaining 12+
+ * types from the legacy chat system (document, consumer, contract,
+ * shipping, productionorder, creditnote, internalorder, offer, assignment,
+ * question, snippet, media).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/interfaces/index.d.ts

@@ -462,6 +462,8 @@ export * from "./INewsletterType";
 export * from "./INewsSource";
 export * from "./INormalizedSerp";
 export * from "./INotification";
+export * from "./INotificationAction";
+export * from "./INotificationAttachment";
 export * from "./INotificationPolicy";
 export * from "./INotificationPreference";
 export * from "./IOffer";

package/interfaces/index.js

@@ -478,6 +478,8 @@ __exportStar(require("./INewsletterType"), exports);
 __exportStar(require("./INewsSource"), exports);
 __exportStar(require("./INormalizedSerp"), exports);
 __exportStar(require("./INotification"), exports);
+__exportStar(require("./INotificationAction"), exports);
+__exportStar(require("./INotificationAttachment"), exports);
 __exportStar(require("./INotificationPolicy"), exports);
 __exportStar(require("./INotificationPreference"), exports);
 __exportStar(require("./IOffer"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolinax/ayoune-interfaces",
-  "version": "2026.46.0",
+  "version": "2026.48.0",
   "description": "Houses TypeScript interfaces for aYOUne",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",