@trycourier/courier-ui-inbox 1.2.3 → 2.0.0

package/dist/datastore/datatore-events.d.ts

@@ -1,12 +1,65 @@
-import { CourierInboxFeedType } from '../types/feed-type';
 import { InboxDataSet } from '../types/inbox-data-set';
 import { InboxMessage } from '@trycourier/courier-js';
+/**
+ * Event callbacks which may be fully or partially implemented to be called when
+ * {@link CourierInboxDatastore} has updates.
+ *
+ * @public
+ */
 export declare class CourierInboxDatastoreEvents {
-    onDataSetChange?(_: InboxDataSet, __: CourierInboxFeedType): void;
-    onPageAdded?(_: InboxDataSet, __: CourierInboxFeedType): void;
-    onUnreadCountChange?(_: number): void;
-    onMessageAdd?(_: InboxMessage, __: number, ___: CourierInboxFeedType): void;
-    onMessageRemove?(_: InboxMessage, __: number, ___: CourierInboxFeedType): void;
-    onMessageUpdate?(_: InboxMessage, __: number, ___: CourierInboxFeedType): void;
-    onError?(_: Error): void;
+    /**
+     * Called when the dataset changes.
+     * @public
+     * @param _dataset - The updated inbox dataset
+     */
+    onDataSetChange?(_dataset: InboxDataSet): void;
+    /**
+     * Called when a new page is added to the dataset.
+     * @public
+     * @param _dataset - The updated inbox dataset with the new page
+     */
+    onPageAdded?(_dataset: InboxDataSet): void;
+    /**
+     * Called when the unread count changes.
+     * @public
+     * @param _unreadCount - The new unread count
+     * @param _datasetId - The dataset ID that was updated
+     */
+    onUnreadCountChange?(_unreadCount: number, _datasetId: string): void;
+    /**
+     * Called when the total unread count across all datasets changes.
+     * @public
+     * @param _totalUnreadCount - The new total unread count
+     */
+    onTotalUnreadCountChange?(_totalUnreadCount: number): void;
+    /**
+     * Called when a new message is added.
+     * @public
+     * @param _message - The added InboxMessage
+     * @param _index - The index where the message was added
+     * @param _datasetId - The dataset ID that was updated
+     */
+    onMessageAdd?(_message: InboxMessage, _index: number, _datasetId: string): void;
+    /**
+     * Called when a message is removed.
+     * @public
+     * @param _message - The InboxMessage that was removed
+     * @param _index - The index from which the message was removed
+     * @param _datasetId - The dataset ID that was updated
+     */
+    onMessageRemove?(_message: InboxMessage, _index: number, _datasetId: string): void;
+    /**
+     * Called when a message is updated.
+     * @public
+     * @param _message - The updated InboxMessage
+     * @param _index - The index where the message was updated
+     * @param _datasetId - The dataset ID that was updated
+     */
+    onMessageUpdate?(_message: InboxMessage, _index: number, _datasetId: string): void;
+    /**
+     * Called when an error occurs in the data store.
+     * @public
+     * @param _error - The error object
+     */
+    onError?(_error: Error): void;
 }

package/dist/datastore/inbox-dataset.d.ts

@@ -0,0 +1,110 @@
+import { InboxMessage } from '@trycourier/courier-js';
+import { CourierInboxDatasetFilter, InboxDataSet } from '../types/inbox-data-set';
+import { CourierGetInboxMessagesQueryFilter } from '@trycourier/courier-js/dist/types/inbox';
+import { CourierInboxDataStoreListener } from './datastore-listener';
+export declare class CourierInboxDataset {
+    /** The unique ID for this dataset, provided by the consumer to later identify this set of messages. */
+    private _id;
+    /** The set of messages in this dataset. */
+    private _messages;
+    /**
+     * True if the first fetch of messages has completed successfully.
+     *
+     * This marker is used to distinguish if _messages can be returned when cached messages
+     * are acceptable, since an empty array of messages could indicate they weren't
+     * ever fetched or that they were fetched but there are currently none in the dataset.
+     */
+    private _firstFetchComplete;
+    /** True if the fetched dataset sets hasNextPage to true. */
+    private _hasNextPage;
+    /**
+     * The pagination cursor to pass to subsequent fetch requests
+     * or null if this is the first request or a response has indicated
+     * there is no next page.
+     */
+    private _lastPaginationCursor?;
+    private readonly _filter;
+    private readonly _datastoreListeners;
+    /**
+     * The total unread count loaded before messages are fetched.
+     * Used to show unread badge counts on tabs before the user clicks into them.
+     *
+     * Total unread count is maintained manually (rather than derived from _messages) because:
+     *
+     * 1. We load unread counts for all tabs in view before their messages are loaded.
+     * 2. The set of loaded messages may not fully reflect the unread count for a tab.
+     *    Messages are paginated, so unread messages may be present on the server but
+     *    but not on the client.
+     */
+    private _totalUnreadCount;
+    constructor(id: string, filter: CourierInboxDatasetFilter);
+    /** Get the current total unread count. */
+    get totalUnreadCount(): number;
+    /** Private setter for unread count. */
+    private set totalUnreadCount(value);
+    /**
+     * Set the unread count explicitly.
+     * Used for batch loading unread counts for all datasets before messages are fetched.
+     */
+    setUnreadCount(count: number): void;
+    /**
+     * Get the filter configuration for this dataset.
+     * Used for batch loading unread counts.
+     */
+    getFilter(): CourierGetInboxMessagesQueryFilter;
+    /**
+     * Add a message to the dataset if it qualifies based on the dataset's filters.
+     *
+     * @param message the message to add
+     * @returns true if the message was added, otherwise false
+     */
+    addMessage(message: InboxMessage, insertIndex?: number): boolean;
+    /**
+     * Update the messages and unread count for the dataset based on a change in a message.
+     *
+     * Based on a message's change (unread -> read, archived -> unarchived, etc) this method
+     * inserts, updates, removes, or excludes it from the dataset. Given the before/existing
+     * and after states, it updates the unread count.
+     *
+     * The before state identifies messages that would qualify for the dataset
+     * before the dataset (or a particular message in the dataset) has been loaded.
+     * These messages may not be explicitly removed from the dataset since they aren't
+     * yet present, but may have an effect on the unread count.
+     *
+     * @param beforeMessage the message before the change
+     * @param afterMessage the message after the change
+     * @returns true if afterMessage qualifies for the dataset and was inserted or updated, false if the message was removed
+     */
+    updateWithMessageChange(beforeMessage: InboxMessage, afterMessage: InboxMessage): boolean;
+    private calculateUnreadChange;
+    /**
+     * Remove the specified message from this dataset, if it's present.
+     *
+     * @param message the message to remove from this dataset
+     * @returns true if the message was removed, else false
+     */
+    removeMessage(message: InboxMessage): boolean;
+    getMessage(messageId: string): InboxMessage | undefined;
+    loadDataset(canUseCache: boolean): Promise<void>;
+    fetchNextPageOfMessages(): Promise<InboxDataSet | null>;
+    addDatastoreListener(listener: CourierInboxDataStoreListener): void;
+    removeDatastoreListener(listener: CourierInboxDataStoreListener): void;
+    toInboxDataset(): InboxDataSet;
+    private fetchMessages;
+    private indexOfMessage;
+    /**
+     * Find the insert index for a new message in a data set
+     * @param newMessage - The new message to insert
+     * @param dataSet - The data set to insert the message into
+     * @returns The index to insert the message at
+     */
+    private findInsertIndex;
+    private messageQualifiesForDataset;
+    /**
+     * Restore this dataset from a snapshot.
+     *
+     * Note: _firstFetchComplete does not need to be restored
+     * as it indicates specific lifecycle stages for the dataset.
+     */
+    restoreFromSnapshot(snapshot: InboxDataSet): void;
+}

package/dist/datastore/inbox-datastore.d.ts

@@ -0,0 +1,217 @@
+import { InboxMessage } from '@trycourier/courier-js';
+import { CourierInboxFeed, InboxDataSet } from '../types/inbox-data-set';
+import { CourierInboxDataStoreListener } from './datastore-listener';
+/**
+ * Shared datastore for Inbox components.
+ *
+ * CourierInboxDatastore is a singleton. Use `CourierInboxDatastore.shared`
+ * to access the shared instance.
+ *
+ * @public
+ */
+export declare class CourierInboxDatastore {
+    private static readonly TAG;
+    private static instance;
+    private _datasets;
+    private _listeners;
+    private _removeMessageEventListener?;
+    /**
+     * Global message store is a map of Message ID to Message for all messages
+     * that have been loaded.
+     *
+     * This acts as the source of truth to apply messages mutations to a message
+     * given its ID and propagate those mutations to individual datasets.
+     */
+    private _globalMessages;
+    /** Access CourierInboxDatastore through {@link CourierInboxDatastore.shared} */
+    private constructor();
+    /**
+     * Instantiate the datastore with the feeds specified.
+     *
+     * Feeds are added to the datastore as datasets. Each feed has a respective
+     * dataset. Existing datasets will be cleared before the feeds specified are added.
+     *
+     * @param feeds - The feeds with which to instantiate the datastore
+     */
+    registerFeeds(feeds: CourierInboxFeed[]): void;
+    private createDatasetsFromFilters;
+    /**
+     * Add a message to the datastore.
+     *
+     * The message will be added to any datasets for which it qualifies.
+     *
+     * @param message - The message to add
+     */
+    addMessage(message: InboxMessage): void;
+    private updateDatasetsWithMessageChange;
+    /**
+     * Listen for real-time message updates from the Courier backend.
+     *
+     * If an existing WebSocket connection is open, it will be re-used. If not,
+     * a new connection will be opened.
+     */
+    listenForUpdates(): Promise<void>;
+    /**
+     * Load unread counts for multiple tabs in a single GraphQL query.
+     * This populates tab badges without loading messages.
+     * @param tabIds - Array of tab IDs to load counts for
+     */
+    loadUnreadCountsForTabs(tabIds: string[]): Promise<void>;
+    /**
+     * Add a datastore listener, whose callbacks will be called in response to various message events.
+     * @param listener - The listener instance to add
+     */
+    addDataStoreListener(listener: CourierInboxDataStoreListener): void;
+    /**
+     * Remove a datastore listener.
+     * @param listener - The listener instance to remove
+     */
+    removeDataStoreListener(listener: CourierInboxDataStoreListener): void;
+    /**
+     * Mark a message as read.
+     * @param message - The message to mark as read
+     */
+    readMessage({ message }: {
+        message: InboxMessage;
+    }): Promise<void>;
+    /**
+     * Mark a message as unread.
+     * @param message - The message to mark as unread
+     */
+    unreadMessage({ message }: {
+        message: InboxMessage;
+    }): Promise<void>;
+    /**
+     * Mark a message as opened.
+     * @param message - The message to mark as opened
+     */
+    openMessage({ message }: {
+        message: InboxMessage;
+    }): Promise<void>;
+    /**
+     * Unarchive a message.
+     * @param message - The message to unarchive
+     */
+    unarchiveMessage({ message }: {
+        message: InboxMessage;
+    }): Promise<void>;
+    /**
+     * Archive a message.
+     * @param message - The message to archive
+     */
+    archiveMessage({ message }: {
+        message: InboxMessage;
+    }): Promise<void>;
+    /**
+     * Track a click event for a message.
+     * @param message - The message that was clicked
+     */
+    clickMessage({ message }: {
+        message: InboxMessage;
+    }): Promise<void>;
+    /**
+     * Archive all messages for the specified dataset.
+     */
+    archiveAllMessages(): Promise<void>;
+    /**
+     * Mark all messages read across all datasets.
+     */
+    readAllMessages(): Promise<void>;
+    /**
+     * Archive all read messages for the specified dataset.
+     */
+    archiveReadMessages(): Promise<void>;
+    /**
+     * Load datasets from the backend.
+     *
+     * Props:
+     *  - canUseCache: If true and the dataset has already been loaded once, this will return the dataset from memory.
+     *  - datasetIds: Optional: The set of dataset IDs to load. If unset, all known datasets will be loaded.
+     *
+     * @param props - Options to load datasets, see method documentation
+     */
+    load(props?: {
+        canUseCache: boolean;
+        datasetIds?: string[];
+    }): Promise<void>;
+    private loadDatasets;
+    /**
+     * Sync messages from a dataset to the global message store.
+     * This is called after datasets load messages to ensure the global store has all messages.
+     */
+    private syncDatasetMessagesToGlobalStore;
+    /**
+     * Fetch the next page of messages for the specified feed or datasetId.
+     *
+     * feedType is deprecated and will be removed in the next major release.
+     * Please migrate to pass the same identifier as datasetId.
+     * While both options are present, exactly one is required.
+     *
+     * @param props - Options to fetch the next page of messages, see method documetation
+     */
+    fetchNextPageOfMessages(props: {
+        feedType?: string;
+        datasetId?: string;
+    }): Promise<InboxDataSet | null>;
+    /**
+     * Get the {@link InboxDataSet} representation of the dataset ID specified.
+     * @param datasetId - The dataset ID to get
+     */
+    getDatasetById(datasetId: string): InboxDataSet | undefined;
+    /**
+     * Get datasets currently in the datastore.
+     * @returns A record mapping dataset IDs to their InboxDataSet representations
+     */
+    getDatasets(): Record<string, InboxDataSet>;
+    /**
+     * Get the total unread count across all datasets.
+     */
+    get totalUnreadCount(): number;
+    private fetchNextPageForDataset;
+    private handleMessageEvent;
+    /**
+     * Update all messages across all datasets from an InboxMessageEvent.
+     * This only handles InboxMessageEvents that do not specify a messageId
+     * and mutate all messages.
+     *
+     * Related: {@link CourierInboxDatastore.updateMessage}
+     */
+    private updateAllMessages;
+    /**
+     * Update a single message across all datasets from an InboxMessageEvent.
+     * This only handles InboxMessageEvents that specify a messageId.
+     *
+     * Related: {@link CourierInboxDatastore.updateAllMessages}
+     */
+    private updateMessage;
+    private clearDatasets;
+    private static getISONow;
+    /**
+     * Create a snapshot of all datasets and global messages for rollback purposes.
+     * This captures the current state of all messages and metadata.
+     */
+    private createDatastoreSnapshot;
+    /**
+     * Restore all datasets and global messages from a snapshot, reverting any mutations.
+     * This is used for rollback when API calls or updates to downstream datasets fail.
+     */
+    private restoreDatastoreSnapshot;
+    /**
+     * Execute an operation with automatic rollback on failure.
+     * Snapshots all datasets before the operation and restores them if the operation throws.
+     *
+     * Note: Errors are caught and logged, but not re-thrown to match the behavior
+     * for backwards compatibility with the legacy (inbox/archive) datastore implementation.
+     *
+     * Note: This method exists at the datastore level (rather than dataset) to handle
+     * errors from API calls.
+     */
+    private executeWithRollback;
+    /**
+     * Get the shared instance of CourierInboxDatastore.
+     *
+     * CourierInboxDatastore is a singleton. Instance methods should be accessed
+     * through this `shared` static accessor.
+     */
+    static get shared(): CourierInboxDatastore;
+}

package/dist/index.d.ts

@@ -5,11 +5,11 @@ export * from './components/courier-inbox-list-item';
 export * from './components/courier-inbox-popup-menu';
 export * from './utils/extensions';
 export * from './types/factories';
-export * from './types/feed-type';
 export * from './types/courier-inbox-theme';
 export * from './types/courier-inbox-theme-manager';
 export * from './types/inbox-data-set';
-export * from './datastore/datastore';
+export * from './types/inbox-defaults';
+export * from './datastore/inbox-datastore';
 export * from './datastore/datastore-listener';
 export * from './datastore/datatore-events';
 export { Courier };