@rivium/push-web 0.1.5 → 0.1.7

package/README.md

@@ -267,6 +267,75 @@ await riviumPush.unregister();
 </html>
 ```
 
+## Message Inbox
+
+Inbox messages are stored server-side and stay available until the user reads,
+archives or deletes them. `riviumPush.inbox` needs a registered device.
+
+```typescript
+// Live updates (an inbox message never shows a notification)
+riviumPush.inbox.onMessage((message) => console.log(message.content.title));
+riviumPush.inbox.onUnreadCountChange((count) => setBadge(count));
+
+// Read
+const { messages, total, unreadCount } = await riviumPush.inbox.getMessages({
+  status: 'unread',
+  limit: 20,
+});
+const cached = riviumPush.inbox.getCachedMessages(); // instant, no network
+
+// Write
+await riviumPush.inbox.markAsRead(messages[0].id);
+await riviumPush.inbox.archiveMessage(messages[0].id);
+await riviumPush.inbox.deleteMessage(messages[0].id);
+await riviumPush.inbox.markMultiple(['id-1', 'id-2'], 'read');
+await riviumPush.inbox.markAllAsRead();
+```
+
+Messages are cached per device and restored on the next page load. The cache is
+dropped when the user changes (`setUserId` / `clearUserId`).
+
+## In-App Messages
+
+In-app messages are campaigns shown inside your page — a modal, banner,
+fullscreen takeover or card — when a trigger fires. `riviumPush.inApp` needs a
+registered device.
+
+```typescript
+const riviumPush = new RiviumPush({
+  apiKey: 'rv_live_your_api_key',
+  inApp: {
+    display: 'auto',        // 'manual' to render your own UI
+    autoTrigger: false,     // true fires session-start + app-open on page load
+    bannerPosition: 'top',
+  },
+});
+
+riviumPush.inApp.onMessageReady((message) => console.log(message.name));
+riviumPush.inApp.onButtonClicked((message, button) => {
+  if (button.action === 'custom') doSomething(button.value);
+});
+riviumPush.inApp.onDismissed((message) => console.log('closed', message.id));
+
+await riviumPush.inApp.triggerOnAppOpen();
+await riviumPush.inApp.triggerEvent('purchase_completed', { plan: 'pro' });
+```
+
+The built-in UI renders into a **shadow DOM** root, so your page's CSS can never
+break it and the SDK's CSS never leaks into your page. Modals and fullscreen
+messages are dialogs (`role="dialog"`, `aria-modal`, focus trap, focus restored
+on close, dismissible with Escape or a backdrop click); banners and cards are
+polite live regions. Reduced-motion preferences are respected.
+
+With `display: 'manual'` nothing is inserted into the page: you get
+`onMessageReady` and render the message yourself, then call
+`riviumPush.inApp.recordImpression(id, 'button_click', buttonId)` and
+`riviumPush.inApp.dismissCurrentMessage()` as the user interacts.
+
+Eligible messages are cached per device for 5 minutes, and impression counts,
+schedules and `minSessionCount` are enforced locally as well as on the server.
+The cache is dropped when the user changes (`setUserId` / `clearUserId`).
+
 ## Delivery Tracking
 
 Notifications are confirmed as `delivered` automatically: Web Push arrivals by

package/dist/in-app.d.ts

@@ -0,0 +1,262 @@
+/**
+ * In-App Messages for the RiviumPush Web SDK.
+ *
+ * An in-app message is a campaign the server keeps for a device and the SDK
+ * shows inside the page — a modal, a banner, a fullscreen takeover or a card —
+ * when a trigger fires (app open, session start or a custom event).
+ *
+ * Reachable as `push.inApp` once the SDK is constructed; network calls need
+ * a registered device (`register()`).
+ *
+ * The built-in UI renders into a shadow DOM root, so the host page's CSS can
+ * never break it and the SDK's CSS never leaks into the page. Apps that want
+ * to render their own UI set `display: 'manual'` and use `onMessageReady`.
+ *
+ * @packageDocumentation
+ */
+/** How a message is presented. */
+export type InAppMessageType = 'modal' | 'banner' | 'fullscreen' | 'card';
+/** What makes a message eligible to show. */
+export type InAppTriggerType = 'on_app_open' | 'on_event' | 'on_session_start' | 'scheduled' | 'manual';
+/** What a button does when clicked. */
+export type InAppButtonAction = 'dismiss' | 'deep_link' | 'url' | 'custom';
+/** Visual weight of a button. */
+export type InAppButtonStyle = 'primary' | 'secondary' | 'text' | 'destructive';
+/** Interaction reported to the server. */
+export type InAppImpressionAction = 'impression' | 'click' | 'dismiss' | 'button_click';
+/** Where a banner is anchored. */
+export type InAppBannerPosition = 'top' | 'bottom';
+/** An action button on an in-app message. */
+export interface InAppButton {
+    /** Button id, reported with the click */
+    id: string;
+    /** Button label */
+    text: string;
+    /** What the button does */
+    action: InAppButtonAction;
+    /** URL or deep link for the `url` / `deep_link` actions */
+    value?: string;
+    /** Visual style (default: `primary`) */
+    style?: InAppButtonStyle;
+}
+/** Content of an in-app message, in one locale. */
+export interface InAppMessageContent {
+    /** Message title */
+    title: string;
+    /** Message body */
+    body: string;
+    /** Large image URL */
+    imageUrl?: string;
+    /** Background colour, e.g. "#FFFFFF" */
+    backgroundColor?: string;
+    /** Text colour, e.g. "#111111" */
+    textColor?: string;
+    /** Action buttons */
+    buttons?: InAppButton[];
+    /** Banner anchor; falls back to the `inApp.bannerPosition` config */
+    position?: InAppBannerPosition;
+}
+/** Content for one locale. */
+export interface InAppLocalization {
+    /** Locale tag, e.g. "fr" or "fr-CA" */
+    locale: string;
+    /** Content for that locale */
+    content: InAppMessageContent;
+}
+/** A single in-app message campaign. */
+export interface InAppMessage {
+    /** Server-side message id */
+    id: string;
+    /** Internal campaign name */
+    name: string;
+    /** How the message is presented */
+    type: InAppMessageType;
+    /** Default content */
+    content: InAppMessageContent;
+    /** Per-locale content, when configured */
+    localizations?: InAppLocalization[];
+    /** What makes the message eligible */
+    triggerType: InAppTriggerType;
+    /** Event name for the `on_event` trigger */
+    triggerEvent?: string | null;
+    /** Extra trigger conditions */
+    triggerConditions?: Record<string, any> | null;
+    /** ISO date before which the message is not shown */
+    startDate?: string | null;
+    /** ISO date after which the message is not shown */
+    endDate?: string | null;
+    /** How many times this device may see the message */
+    maxImpressions: number;
+    /** Sessions required before the message may show */
+    minSessionCount: number;
+    /** Delay between the trigger and the display */
+    delaySeconds: number;
+    /** Higher priority wins when several messages qualify */
+    priority: number;
+}
+/** Options for {@link InAppMessages.fetchMessages}. */
+export interface InAppFilter {
+    /** Only messages with this trigger */
+    trigger?: InAppTriggerType;
+    /** Only messages bound to this event name */
+    event?: string;
+    /** Preferred locale for localized content, e.g. "fr" */
+    locale?: string;
+}
+/** Configuration for the in-app module (`RiviumPushConfig.inApp`). */
+export interface InAppConfig {
+    /** Turn in-app messages off entirely (default: true) */
+    enabled?: boolean;
+    /**
+     * `auto` renders the built-in shadow-DOM UI (default).
+     * `manual` renders nothing and only fires `onMessageReady`, so the app can
+     * draw its own UI. It still reports the impression.
+     */
+    display?: 'auto' | 'manual';
+    /**
+     * Fire `on_session_start` and `on_app_open` automatically on page load
+     * (default: false — call `triggerOnAppOpen()` when your app is ready).
+     */
+    autoTrigger?: boolean;
+    /** Where banners are anchored when the content does not say (default: top) */
+    bannerPosition?: InAppBannerPosition;
+    /** Locale used to pick localized content (default: the browser locale) */
+    locale?: string;
+}
+/** Called when a message is ready to be displayed. */
+export type OnInAppMessageReadyCallback = (message: InAppMessage) => void;
+/** Called when a button on a message is clicked. */
+export type OnInAppButtonClickedCallback = (message: InAppMessage, button: InAppButton) => void;
+/** Called when a message is dismissed. */
+export type OnInAppDismissedCallback = (message: InAppMessage) => void;
+/**
+ * Wiring the SDK passes to the in-app module. Not part of the public API.
+ * @internal
+ */
+export interface InAppDependencies {
+    serverUrl: string;
+    getApiKey: () => string;
+    getDeviceId: () => string | null;
+    getUserId: () => string | null;
+    log: (level: number, message: string, ...args: any[]) => void;
+    config?: InAppConfig;
+}
+/** Inputs the eligibility rules are evaluated against. */
+export interface InAppEligibilityContext {
+    /** Trigger being evaluated */
+    trigger: InAppTriggerType;
+    /** Event name, for the `on_event` trigger */
+    event?: string;
+    /** Sessions this device has started */
+    sessionCount: number;
+    /** Impressions this device already had, per message id */
+    impressions: Record<string, number>;
+    /** Evaluation time in epoch milliseconds */
+    now: number;
+}
+/**
+ * Whether a message may be shown for this trigger. Pure, so the frequency and
+ * schedule rules can be reasoned about (and tested) on their own.
+ */
+export declare function isInAppMessageEligible(message: InAppMessage, context: InAppEligibilityContext): boolean;
+/** Eligible messages for a trigger, highest priority first. */
+export declare function selectInAppMessages(messages: InAppMessage[], context: InAppEligibilityContext): InAppMessage[];
+/**
+ * In-App Messages client.
+ *
+ * ```typescript
+ * push.inApp.onButtonClicked((message, button) => console.log(button.id));
+ * await push.inApp.triggerOnAppOpen();
+ * await push.inApp.triggerEvent('purchase_completed');
+ * ```
+ */
+export declare class InAppMessages {
+    private readonly deps;
+    private cachedMessages;
+    private impressions;
+    private sessionCount;
+    private lastFetch;
+    /** Device the in-memory cache was loaded for, so identity changes reload. */
+    private loadedKey;
+    private onMessageReadyCallback;
+    private onButtonClickedCallback;
+    private onDismissedCallback;
+    private presentation;
+    private showing;
+    private pendingTimer;
+    /** @internal */
+    constructor(deps: InAppDependencies);
+    /**
+     * Listen for a message becoming ready to display. Fires for the built-in UI
+     * too; with `display: 'manual'` it is the only signal you get.
+     * Returns a function that removes the listener.
+     */
+    onMessageReady(callback: OnInAppMessageReadyCallback): () => void;
+    /**
+     * Listen for button clicks. `custom` buttons do nothing on their own —
+     * handle them here.
+     * Returns a function that removes the listener.
+     */
+    onButtonClicked(callback: OnInAppButtonClickedCallback): () => void;
+    /**
+     * Listen for a message being dismissed (close button, backdrop, Escape or
+     * a `dismiss` button).
+     * Returns a function that removes the listener.
+     */
+    onDismissed(callback: OnInAppDismissedCallback): () => void;
+    /**
+     * Fetch the messages this device is eligible for and cache them. Messages
+     * are filtered again locally before anything is shown.
+     */
+    fetchMessages(filter?: InAppFilter): Promise<InAppMessage[]>;
+    /** Messages cached locally — available immediately, no network call. */
+    getCachedMessages(): InAppMessage[];
+    /** Sessions this device has started. */
+    getSessionCount(): number;
+    /** Evaluate `on_app_open` messages and show the best match. */
+    triggerOnAppOpen(): Promise<void>;
+    /**
+     * Evaluate `on_event` messages bound to `name`. `properties` are matched
+     * against a message's `triggerConditions` when both are present.
+     */
+    triggerEvent(name: string, properties?: Record<string, any>): Promise<void>;
+    /** Count a new session and evaluate `on_session_start` messages. */
+    triggerSessionStart(): Promise<void>;
+    /**
+     * Start a session on page load: counts the session and, when
+     * `inApp.autoTrigger` is on, fires `on_session_start` then `on_app_open`.
+     * @internal
+     */
+    startSession(): void;
+    /** Show a cached message by id, ignoring its trigger. */
+    showMessage(messageId: string): Promise<void>;
+    /** Close the message currently on screen, if any. */
+    dismissCurrentMessage(): void;
+    /**
+     * Report an interaction. Called for you by the built-in UI; call it yourself
+     * when you render messages with `display: 'manual'`. Never throws.
+     */
+    recordImpression(messageId: string, action: InAppImpressionAction, buttonId?: string): Promise<void>;
+    /** Drop cached messages, impression counts and the session count. */
+    clearCache(): void;
+    /**
+     * Point the module at a new identity. Campaign eligibility and impression
+     * counts belong to the previous user, so they are dropped.
+     * @internal
+     */
+    onIdentityChanged(): void;
+    private trigger;
+    /** Shows a message: reports the impression once, then renders or delegates. */
+    private present;
+    private handleButtonClick;
+    /** Tears the UI down once, reports the dismissal once. */
+    private finishPresentation;
+    private incrementSessionCount;
+    private locale;
+    private storageKey;
+    /** Restores the persisted state the first time it is needed per device. */
+    private ensureLoaded;
+    private persist;
+}
+/** Exact locale match first, then the language part, then the default content. */
+export declare function localizedContent(message: InAppMessage, locale: string): InAppMessageContent;

package/dist/inbox.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Message Inbox for the RiviumPush Web SDK.
+ *
+ * An inbox message is a message that is stored server-side and stays
+ * available to the app until the user reads, archives or deletes it —
+ * independent of whether a notification was ever displayed.
+ *
+ * Reachable as `push.inbox` once the SDK is constructed; network calls need
+ * a registered device (`register()`).
+ *
+ * @packageDocumentation
+ */
+/** Status of an inbox message. */
+export type InboxMessageStatus = 'unread' | 'read' | 'archived' | 'deleted';
+/** Content of an inbox message. */
+export interface InboxContent {
+    /** Message title */
+    title: string;
+    /** Message body */
+    body: string;
+    /** Large image URL */
+    imageUrl?: string;
+    /** Icon/avatar URL */
+    iconUrl?: string;
+    /** Deep link URL */
+    deepLink?: string;
+    /** Custom data payload */
+    data?: Record<string, any>;
+}
+/** A single inbox message. */
+export interface InboxMessage {
+    /** Server-side message id */
+    id: string;
+    /** User this message belongs to, when addressed by user */
+    userId?: string | null;
+    /** Device this message belongs to, when addressed by device */
+    deviceId?: string | null;
+    /** Message content */
+    content: InboxContent;
+    /** Current status (defaults to `unread`) */
+    status: InboxMessageStatus;
+    /** Optional category, e.g. "promotions" */
+    category?: string | null;
+    /** ISO date after which the message is no longer returned */
+    expiresAt?: string | null;
+    /** ISO date the message was marked read */
+    readAt?: string | null;
+    /** ISO date the message was created */
+    createdAt: string;
+    /** ISO date the message was last updated */
+    updatedAt?: string | null;
+}
+/** Filter options for {@link RiviumInbox.getMessages}. */
+export interface InboxFilter {
+    /** Only messages with this status */
+    status?: InboxMessageStatus;
+    /** Only messages in this category */
+    category?: string;
+    /** Page size (default: 50) */
+    limit?: number;
+    /** Page offset (default: 0) */
+    offset?: number;
+    /** Preferred locale for localized content, e.g. "fr" */
+    locale?: string;
+}
+/** Response of {@link RiviumInbox.getMessages}. */
+export interface InboxMessagesResponse {
+    /** The messages for this page */
+    messages: InboxMessage[];
+    /** Total number of messages matching the filter */
+    total: number;
+    /** Number of unread messages */
+    unreadCount: number;
+}
+/** Called when a new inbox message arrives in real time. */
+export type OnInboxMessageCallback = (message: InboxMessage) => void;
+/** Called when the status of a message changes. */
+export type OnInboxStatusChangeCallback = (messageId: string, status: InboxMessageStatus) => void;
+/** Called whenever the unread count changes. */
+export type OnInboxUnreadCountCallback = (count: number) => void;
+/**
+ * Wiring the SDK passes to the inbox. Not part of the public API.
+ * @internal
+ */
+export interface InboxDependencies {
+    serverUrl: string;
+    getApiKey: () => string;
+    getDeviceId: () => string | null;
+    getUserId: () => string | null;
+    log: (level: number, message: string, ...args: any[]) => void;
+    createError: (kind: 'network' | 'server' | 'notRegistered', details: string) => Error;
+}
+/**
+ * Message Inbox client.
+ *
+ * ```typescript
+ * push.inbox.onMessage((message) => render(message));
+ * const { messages, unreadCount } = await push.inbox.getMessages({ status: 'unread' });
+ * await push.inbox.markAsRead(messages[0].id);
+ * ```
+ */
+export declare class RiviumInbox {
+    private readonly deps;
+    private cachedMessages;
+    private unreadCount;
+    /** Device the in-memory cache was loaded for, so identity changes reload. */
+    private loadedKey;
+    private onMessageCallback;
+    private onStatusChangeCallback;
+    private onUnreadCountCallback;
+    /** Real-time updates can arrive twice (socket + service worker). */
+    private handledIncomingIds;
+    /** @internal */
+    constructor(deps: InboxDependencies);
+    /**
+     * Listen for inbox messages arriving in real time.
+     * Returns a function that removes the listener.
+     */
+    onMessage(callback: OnInboxMessageCallback): () => void;
+    /**
+     * Listen for status changes (read, archived, deleted).
+     * Returns a function that removes the listener.
+     */
+    onStatusChange(callback: OnInboxStatusChangeCallback): () => void;
+    /**
+     * Listen for unread-count changes — useful to drive a badge.
+     * Returns a function that removes the listener.
+     */
+    onUnreadCountChange(callback: OnInboxUnreadCountCallback): () => void;
+    /**
+     * Fetch inbox messages from the server. Messages are addressed by userId
+     * when one is set, otherwise by deviceId. The result is cached locally.
+     */
+    getMessages(filter?: InboxFilter): Promise<InboxMessagesResponse>;
+    /** Fetch a single message by id. */
+    getMessage(messageId: string): Promise<InboxMessage>;
+    /** Messages cached locally — available immediately, no network call. */
+    getCachedMessages(): InboxMessage[];
+    /** The last known unread count, without a network call. */
+    getUnreadCount(): number;
+    /** Ask the server for the current unread count. */
+    fetchUnreadCount(): Promise<number>;
+    /** Mark a message as read. */
+    markAsRead(messageId: string): Promise<void>;
+    /** Archive a message. */
+    archiveMessage(messageId: string): Promise<void>;
+    /** Delete a message. */
+    deleteMessage(messageId: string): Promise<void>;
+    /** Apply a status to several messages at once. */
+    markMultiple(messageIds: string[], status: InboxMessageStatus): Promise<void>;
+    /** Mark every message in this inbox as read. */
+    markAllAsRead(): Promise<void>;
+    /** Drop the local cache (in memory and in storage). */
+    clearCache(): void;
+    /**
+     * Add a message that arrived in real time to the cache and notify listeners.
+     * Called by the SDK for `inbox_update` payloads; safe to call directly.
+     */
+    handleIncomingMessage(message: InboxMessage): void;
+    /**
+     * Turn a raw `inbox_update` payload into an InboxMessage and handle it.
+     * @internal
+     */
+    handleIncomingPayload(payload: Record<string, any>): void;
+    /**
+     * Point the inbox at a new identity. The cache belongs to the previous
+     * user, so it is dropped and listeners see an unread count of 0.
+     * @internal
+     */
+    onIdentityChanged(): void;
+    private updateStatus;
+    /** Messages are addressed by user when one is known, by device otherwise. */
+    private identity;
+    private request;
+    private setUnreadCount;
+    private storageKey;
+    /** Restores the persisted cache the first time it is needed per device. */
+    private ensureLoaded;
+    private persist;
+}

package/dist/index.d.ts

@@ -15,7 +15,13 @@
  * @packageDocumentation
  */
 import { SDK_NAME, SDK_VERSION } from './version';
+import { RiviumInbox } from './inbox';
+import { InAppMessages, type InAppConfig } from './in-app';
 export { SDK_NAME, SDK_VERSION };
+export { RiviumInbox } from './inbox';
+export type { InboxContent, InboxFilter, InboxMessage, InboxMessagesResponse, InboxMessageStatus, OnInboxMessageCallback, OnInboxStatusChangeCallback, OnInboxUnreadCountCallback, } from './inbox';
+export { InAppMessages, isInAppMessageEligible, selectInAppMessages, localizedContent } from './in-app';
+export type { InAppBannerPosition, InAppButton, InAppButtonAction, InAppButtonStyle, InAppConfig, InAppEligibilityContext, InAppFilter, InAppImpressionAction, InAppLocalization, InAppMessage, InAppMessageContent, InAppMessageType, InAppTriggerType, OnInAppButtonClickedCallback, OnInAppDismissedCallback, OnInAppMessageReadyCallback, } from './in-app';
 /**
  * Standardized error codes for RiviumPush SDK.
  * These codes help developers identify and handle specific error scenarios.
@@ -209,6 +215,12 @@ export interface RiviumPushConfig {
      * permission is already granted. Errors are logged, never thrown.
      */
     autoRefresh?: boolean;
+    /**
+     * In-App Messages options. Omit it to keep the defaults: the built-in
+     * shadow-DOM UI, triggered by your calls to `inApp.triggerOnAppOpen()` /
+     * `inApp.triggerEvent()`.
+     */
+    inApp?: InAppConfig;
 }
 /**
  * Notification action button
@@ -382,6 +394,16 @@ declare class RiviumPush {
     private registerRequested;
     private ackedMessageIds;
     private receivedMessageIds;
+    /**
+     * Message Inbox. Listeners can be attached immediately; network calls need
+     * a registered device.
+     */
+    readonly inbox: RiviumInbox;
+    /**
+     * In-App Messages. Listeners can be attached immediately; network calls
+     * need a registered device.
+     */
+    readonly inApp: InAppMessages;
     constructor(config: RiviumPushConfig);
     /**
      * Fetch MQTT and VAPID configuration from server
@@ -607,6 +629,13 @@ declare class RiviumPush {
      * Messages without an id can't be deduped and always pass.
      */
     private markReceived;
+    /**
+     * `inbox_update` payloads update the Message Inbox instead of being shown
+     * as a notification. Deduped by message id like delivery acks, so a payload
+     * arriving over both the real-time channel and the service worker counts
+     * once. Returns true when the payload was an inbox update.
+     */
+    private routeInboxUpdate;
     private handleServiceWorkerMessage;
     private showRichNotification;
     private updateFaviconBadge;