@rivium/push-web 0.1.4 → 0.1.6

package/README.md

@@ -89,9 +89,30 @@ const riviumPush = new RiviumPush({
   mqttQos: 1,                              // Optional - MQTT QoS level (default: 1)
   maxReconnectAttempts: 10,                 // Optional - max reconnect attempts (default: 10)
   logLevel: RiviumPushLogLevel.ERROR,       // Optional - log level
+  appVersion: '2.0.0',                      // Optional - your app version (segment filter)
+  autoRefresh: true,                        // Optional - background re-registration (default: true)
 });
 ```
 
+### Automatic refresh
+
+With `autoRefresh` on (the default), a browser that has registered before is
+silently re-registered on page load when its registration is likely stale: 24
+hours have passed, the push subscription endpoint changed, or `appVersion`, the
+SDK version or the user ID changed. It never shows a permission prompt (it only
+runs when permission is already granted) and never throws. Calling `register()`
+yourself still always registers.
+
+### SDK version
+
+```typescript
+import { SDK_VERSION } from '@rivium/push-web';
+console.log(SDK_VERSION); // "0.1.5"
+```
+
+The SDK reports `sdkName` / `sdkVersion`, the OS and the browser (as
+`osVersion` / `deviceModel`) when registering, so they show up in the dashboard.
+
 ## Callbacks
 
 All event handlers return an unsubscribe function.
@@ -246,6 +267,40 @@ 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`).
+
+## Delivery Tracking
+
+Notifications are confirmed as `delivered` automatically: Web Push arrivals by
+the service worker, and messages received over the real-time connection on an
+open page by the SDK. No code needed.
+
 ## Browser Support
 
 - Chrome 50+ (Desktop & Android)

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

@@ -14,6 +14,11 @@
  *
  * @packageDocumentation
  */
+import { SDK_NAME, SDK_VERSION } from './version';
+import { RiviumInbox } from './inbox';
+export { SDK_NAME, SDK_VERSION };
+export { RiviumInbox } from './inbox';
+export type { InboxContent, InboxFilter, InboxMessage, InboxMessagesResponse, InboxMessageStatus, OnInboxMessageCallback, OnInboxStatusChangeCallback, OnInboxUnreadCountCallback, } from './inbox';
 /**
  * Standardized error codes for RiviumPush SDK.
  * These codes help developers identify and handle specific error scenarios.
@@ -198,6 +203,15 @@ export interface RiviumPushConfig {
      * this at init time from your build config.
      */
     appVersion?: string;
+    /**
+     * Keep the server-side registration fresh without calling register() on
+     * every page load (default: true). On startup, a browser that registered
+     * before is silently re-registered in the background when 24h have passed,
+     * the push subscription endpoint changed, or `appVersion`, the SDK version
+     * or the userId changed. Never prompts: it only runs when notification
+     * permission is already granted. Errors are logged, never thrown.
+     */
+    autoRefresh?: boolean;
 }
 /**
  * Notification action button
@@ -368,6 +382,14 @@ declare class RiviumPush {
     private onReconnectingCallback;
     private onNetworkStateCallback;
     private onAppStateCallback;
+    private registerRequested;
+    private ackedMessageIds;
+    private receivedMessageIds;
+    /**
+     * Message Inbox. Listeners can be attached immediately; network calls need
+     * a registered device.
+     */
+    readonly inbox: RiviumInbox;
     constructor(config: RiviumPushConfig);
     /**
      * Fetch MQTT and VAPID configuration from server
@@ -451,8 +473,12 @@ declare class RiviumPush {
     setUserId(userId: string): Promise<void>;
     /**
      * Clear user ID. Call this on logout.
+     *
+     * Also detaches the user on the server. Registration treats a missing
+     * userId as "keep the existing one", so clearing only local state would
+     * leave this browser receiving the logged-out user's notifications.
      */
-    clearUserId(): void;
+    clearUserId(): Promise<void>;
     /**
      * Get the currently-stored userId, if any. Survives page reloads.
      */
@@ -569,9 +595,33 @@ declare class RiviumPush {
     private disconnectFromGateway;
     private scheduleReconnect;
     private handleMqttMessage;
+    /**
+     * POST /receipts/delivered for a message received on this page. Deduped per
+     * messageId (the server is idempotent too) and retried a bounded number of
+     * times on network errors, 429 and 5xx. Never throws.
+     */
+    private reportDelivered;
+    private saveRegistrationState;
+    /**
+     * Silently re-register a browser that registered before, when the server's
+     * copy is likely stale. Never prompts for permission and never throws.
+     */
+    private maybeAutoRefresh;
     private normalizeMessage;
     private getLocalizedContent;
     private handleBadge;
+    /**
+     * Records a messageId as handed to the app. Returns false if it already was.
+     * 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;