@tolinax/ayoune-interfaces 2026.47.0 → 2026.49.0

package/interfaces/INotification.d.ts

@@ -31,7 +31,49 @@ export interface INotification extends IDefaultFields {
     attachments?: INotificationAttachment[];
     /**
      * Action buttons rendered under the notification (1-3 typical), and —
-     * where the OS supports it — as native Web-Push action buttons (first two).
+     * 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/INotificationAttachment.d.ts

@@ -21,8 +21,12 @@
  * 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. */
+export type NotificationAttachmentType = "calendarentry" | "task" | "invoice" | "permissionrequest" | "supplierorder" | "document" | "consumer" | "shipping";
+/** 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. */
@@ -30,6 +34,10 @@ interface INotificationAttachmentBase {
     /** 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;
@@ -115,6 +123,57 @@ export interface ISupplierOrderPreview extends INotificationAttachmentBase {
     };
     expectedDelivery?: Date | string;
 }
+export interface IDocumentPreview extends INotificationAttachmentBase {
+    title?: string;
+    filename?: string;
+    /** Mime type — used to choose the leading icon (pdf / image / audio / video / generic). */
+    contentType?: string;
+    /** Size in bytes — rendered as a human chip `2.3 MB`. */
+    size?: number;
+    /** Direct download URL (served by the media / uploads service). */
+    url?: string;
+    /** Author / uploader — rendered small. */
+    uploadedBy?: {
+        _id?: ObjectId;
+        name?: string;
+    };
+}
+export interface IConsumerPreview extends INotificationAttachmentBase {
+    /** Short reference label (sr-number in the legacy system). */
+    sr?: string;
+    /** Display name — individual OR company. */
+    name?: string;
+    /** Company-line (used when `name` is the person). */
+    company?: string;
+    email?: string;
+    phone?: string;
+    /** Optional avatar / logo URL — separate from the generic `image`
+     *  base field which the card uses as a 40x40 thumbnail anyway. */
+    avatar?: string;
+    /** Lifecycle status — "lead", "customer", "archived", etc. */
+    status?: string;
+    /** Number of open items (tickets/tasks/deals) — rendered as a chip. */
+    openItemsCount?: number;
+}
+export interface IShippingPreview extends INotificationAttachmentBase {
+    /** Shipping identifier — internal and/or carrier tracking number. */
+    nbr?: string | number;
+    trackingNumber?: string;
+    /** Carrier slug or name — DHL, UPS, FedEx, etc. */
+    carrier?: string;
+    /** Lifecycle status — created / picked / in-transit / delivered / exception. */
+    status?: string;
+    destinationCity?: string;
+    destinationCountry?: string;
+    /** Expected / actual delivery timestamps. */
+    expectedDelivery?: Date | string;
+    deliveredAt?: Date | string;
+    /** Linked receiver (Consumer ref) — rendered as the recipient chip. */
+    receiver?: {
+        _id?: ObjectId;
+        name?: string;
+    };
+}
 export type INotificationAttachment = {
     type: "calendarentry";
     preview: ICalendarEntryPreview;
@@ -130,6 +189,15 @@ export type INotificationAttachment = {
 } | {
     type: "supplierorder";
     preview: ISupplierOrderPreview;
+} | {
+    type: "document";
+    preview: IDocumentPreview;
+} | {
+    type: "consumer";
+    preview: IConsumerPreview;
+} | {
+    type: "shipping";
+    preview: IShippingPreview;
 };
 /** Producer-side shape — accepts either a bare reference (orchestrator will
  *  enrich) or a fully-populated attachment. */

package/package.json

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