import { Observable } from 'rxjs'; import { type FrameworkEventInitType } from '@equinor/fusion-framework-module-event'; import { SemanticVersion } from '@equinor/fusion-framework-module'; import type { Bookmark, BookmarkData, BookmarkWithoutData, Bookmarks, BookmarkModuleConfig } from './types'; import type { BookmarkUpdate, IBookmarkClient } from './BookmarkClient.interface'; import { type BookmarkActions } from './bookmark-actions'; import { type BookmarkState } from './create-bookmark-store'; import { type BookmarkFlowError } from './BookmarkFlowError'; import type { BookmarkProviderEventMap } from './BookmarkProvider.events'; import type { BookmarkCreateArgs, BookmarkPayloadGenerator, BookmarkUpdateOptions, IBookmarkProvider } from './BookmarkProvider.interface'; /** * The `BookmarkProvider` class is responsible for managing bookmarks in the application. * It provides methods for creating, updating, and removing bookmarks, as well as managing the current bookmark and the list of bookmarks. * * The `BookmarkProvider` uses a `BookmarkStore` to manage the state of the bookmarks, and an `IBookmarkClient` to interact with the backend API. * * The `BookmarkProvider` also supports event listeners for various bookmark-related events, such as when the current bookmark changes or when a bookmark is created, updated, or removed. */ export declare class BookmarkProvider implements IBookmarkProvider { #private; /** * @deprecated * this will be removed as soon as applications have been migrated to use the bookmark provider */ get config(): { getCurrentAppIdentification(): any; }; /** * @deprecated * this will be removed as soon as applications have been migrated to use the bookmark provider * @param fn - The payload generator callback to register. * @template T - The bookmark data type produced by the generator. * @returns A function that unregisters the payload generator when called. */ addStateCreator(fn: BookmarkPayloadGenerator): VoidFunction; /** * @deprecated * this will be removed as soon as applications have been migrated to use the bookmark provider * @param id - The ID of the bookmark to delete. */ deleteBookmarkByIdAsync(id: string): Promise; /** * @deprecated * this will be removed as soon as applications have been migrated to use the bookmark provider * @param id - The ID of the bookmark to add as a favorite. * @returns The updated bookmark, or undefined if it could not be found. */ addBookmarkFavoriteAsync(id: string): Promise; /** * @deprecated * this will be removed as soon as applications have been migrated to use the bookmark provider * @param id - The ID of the bookmark to remove as a favorite. */ removeBookmarkFavoriteAsync(id: string): Promise; /** * @deprecated * this will be removed as soon as applications have been migrated to use the bookmark provider * @param id - The ID of the bookmark to get. * @returns The bookmark, or null if it could not be found. */ getBookmarkById(id: string): Promise; /** * Gets the semantic version of the bookmark provider. * @returns The semantic version of the bookmark provider. */ get version(): SemanticVersion; /** @returns The configured bookmark filters. */ get filters(): BookmarkModuleConfig['filters']; /** * Gets the `IBookmarkClient` instance used by this `BookmarkProvider`. * @returns The `IBookmarkClient` instance. */ get client(): IBookmarkClient; /** * Gets the currently active bookmark (if any). * @returns An observable of the currently active bookmark. */ get currentBookmark$(): Observable; /** * Gets an observable that emits the current list of bookmarks. * @returns An observable of the current list of bookmarks. */ get bookmarks$(): Observable>; /** * Gets the current list of bookmarks. * @returns The current list of bookmarks. */ get bookmarks(): Array; /** * Gets the currently active bookmark. * @returns The currently active bookmark, or null/undefined if there is none. */ get currentBookmark(): Bookmark | null | undefined; /** * Represents an observable stream of the bookmark status. * @returns An observable of the bookmark status. */ get status$(): Observable; /** * Gets an observable that emits the current list of bookmark errors. * @returns An observable of the current list of bookmark errors. */ get errors$(): Observable>; /** * Determines whether there are any bookmark creators configured. * @returns `true` if there are any bookmark creators configured, `false` otherwise. */ get canCreateBookmarks(): boolean; /** * Gets the source system value from the configuration. * @returns The source system value. */ get sourceSystem(): BookmarkModuleConfig['sourceSystem']; /** * Gets the resolved application from the bookmark module configuration. * @returns The resolved application resolver. */ get resolvedApplication(): BookmarkModuleConfig['resolve']['application']; /** * Gets the resolved context from the bookmark module configuration. * @returns The resolved context resolver. */ get resolvedContext(): BookmarkModuleConfig['resolve']['context']; /** * configured logger instance. * @returns The configured logger. */ protected get _log(): BookmarkModuleConfig['log']; /** * configured resolvers * @returns The configured resolvers. */ protected get _resolve(): BookmarkModuleConfig['resolve']; /** * configured event provider. * @returns The configured event provider. */ protected get _event(): BookmarkModuleConfig['eventProvider']; /** * configured parent bookmark provider * @returns The configured parent bookmark provider. */ protected get _parent(): BookmarkModuleConfig['parent']; /** * Constructs a new `BookmarkProvider` instance. * * @param config - The configuration for the bookmark module, including the client, initial state, and optional parent provider. */ constructor(config: BookmarkModuleConfig); /** * Registers an event listener for the specified event on the BookmarkProvider. * * @template TType - The key of the `BookmarkProviderEventMap` identifying the event. * @param eventName - The name of the event to listen for. Must be a key of the `BookmarkProviderEventMap` type. * @param callback - The callback function to be invoked when the event is triggered. * The callback will receive the event object as its parameter, which will be of the type corresponding to the `eventName`. * @returns A function that can be called to remove the event listener. */ on(eventName: TType, callback: (event: BookmarkProviderEventMap[TType]) => void): VoidFunction; /** * Adds a new payload generator function to the BookmarkProvider. * The payload generator function will be used to generate the payload for a bookmark-related action. * * @template T - The type of the bookmark data the payload generator produces. * @param fn - The payload generator function to add. It should be of type `PayloadGenerator`, where `T` is the type of the bookmark data. * @returns A function that can be called to remove the added payload generator. */ addPayloadGenerator(fn: BookmarkPayloadGenerator): VoidFunction; /** * Generates a payload by applying registered generator functions to an accumulator object. * * @param initial - The initial value of the accumulator object. * @returns An observable that emits the generated payload. * @template T - The type of the generated payload. */ generatePayload(initial?: Partial | null): Observable; /** * Produces a payload using the provided generator function. * * @template T - The type of the bookmark data. * @param value - The partial value to be used as the base for the payload. * @param generator - The function that generates the payload. * @param initial - An optional initial value to be passed to the generator. * @returns The produced payload or null if the generator wishes to clear the bookmark data. * * @remarks * The generator function should not return a value, as the data is an immer draft object. * If the generator returns a value, a warning will be logged. * If the generator returns null, an info message will be logged indicating that the bookmark data should be cleared. */ protected _producePayload(value: Partial, generator: BookmarkPayloadGenerator, initial?: Partial | null): Promise; /** * Retrieves a bookmark with the specified bookmarkId and returns an observable that emits the combined result of fetching the bookmark and bookmark data. * @template T The type of the bookmark payload. * @param bookmarkId The unique identifier of the bookmark. * @param options An optional object that allows excluding the bookmark payload from the result. * @returns An observable that emits the combined result of fetching the bookmark and bookmark data. * @throws The error encountered while fetching the bookmark or its data, after logging it. */ getBookmark(bookmarkId: string, options?: { excludePayload?: boolean; }): Observable>; /** * Retrieves a bookmark asynchronously. * * @template T - The type of the bookmark payload. * @param id - The ID of the bookmark to retrieve. * @param options - Optional parameters for the retrieval. * @param options.excludePayload - Specifies whether to exclude the payload from the bookmark. * @returns A promise that resolves to the retrieved bookmark, or null if the bookmark is not found. */ getBookmarkAsync(id: string, options?: { excludePayload?: boolean; }): Promise | null>; /** * Retrieves all bookmarks from the store as an Observable stream. * * This method implements a complex flow that: * 1. Resolves filter parameters (sourceSystem, appKey, contextId) based on configuration * 2. Dispatches a fetch action to the store with resolved filters * 3. Monitors store actions for success/failure responses * 4. Returns the bookmarks data or throws appropriate errors * * @remarks * The method uses a reactive pattern where filter resolution and store actions are * handled asynchronously. If filtering is enabled, it will resolve the current * application and context to filter bookmarks accordingly. * * @example * ```ts * // Basic usage * bookmarkProvider.getAllBookmarks().subscribe({ * next: (bookmarks) => console.log('Retrieved bookmarks:', bookmarks), * error: (err) => console.error('Failed to fetch bookmarks:', err) * }); * * // With filtering enabled in config * const config = { * filters: { context: true, application: true } * }; * // Will automatically filter by current context and application * ``` * * @returns An Observable that emits the array of bookmarks when successfully retrieved * @throws {BookmarkProviderError} When filter resolution fails or store operations fail * @throws {BookmarkProviderError} When a timeout occurs during the fetch operation */ getAllBookmarks(): Observable; /** * Asynchronously retrieves all bookmarks from the store. * * @returns A Promise that resolves to the Bookmarks object containing all bookmarks. */ getAllBookmarksAsync(): Promise; /** * Sets the current bookmark to the specified bookmark or ID. * If the bookmark is already the current bookmark, it returns the bookmark directly. * Otherwise, it emits the next bookmark or null through an observable. * * By proving `null` as the bookmark_or_id, the current bookmark will be cleared. * * @param bookmark_or_id - The bookmark or ID to set as the current bookmark. * @returns An observable that emits the next bookmark or null. * @template T - The type of the bookmark data. * @throws {BookmarkProviderError} If the onCurrentBookmarkChange event is canceled by a listener, or resolving the bookmark fails. */ setCurrentBookmark(bookmark_or_id: Bookmark | string | null): Observable | null>; /** * Sets the current bookmark asynchronously. * * @template T - The type of the bookmark data. * @param bookmark_or_id - The bookmark or ID to set as the current bookmark. * @returns A promise that resolves to the next bookmark or null. */ setCurrentBookmarkAsync(bookmark_or_id: Bookmark | string | null): Promise | null>; /** * Creates a new bookmark with the provided bookmark data. * The creation executes immediately when this method is called. * @template T - The type of bookmark data. * @param {BookmarkCreateArgs} newBookmarkData - The data for creating the bookmark. * @returns {Observable>} - An observable that emits the created bookmark. * @throws {BookmarkProviderError} If resolving the bookmark data fails, the onBookmarkCreate event is canceled, the create request fails, or the request times out. */ createBookmark(newBookmarkData: BookmarkCreateArgs): Observable>; /** * Asynchronously creates a new bookmark. * * @template T - The type of bookmark data. * @param args - The data for creating the bookmark. * @returns A promise that resolves to the created bookmark with its associated data. */ createBookmarkAsync(args: BookmarkCreateArgs): Promise>; /** * Updates a bookmark with the specified bookmarkId and bookmarkUpdates. * The update executes immediately when this method is called. * * @template T - The type of the bookmark data. * @param {string} bookmarkId - The identifier of the bookmark to update. * @param {BookmarkUpdate} [bookmarkUpdates] - The updates to apply to the bookmark. * @param {BookmarkUpdateOptions} [options] - The options for updating the bookmark. * @returns {Observable>} - An observable that emits the updated bookmark. * @throws {BookmarkProviderError} If bookmarkUpdates is omitted while excludePayloadGeneration is set, generating the payload fails, the onBookmarkUpdate event is canceled, the update request fails, or the request times out. */ updateBookmark(bookmarkId: string, bookmarkUpdates?: BookmarkUpdate, options?: BookmarkUpdateOptions): Observable>; /** * Updates a bookmark asynchronously. * * @todo TODO(#5140) - remove the deprecated overload accepting a full bookmark in the next major version * * @template T - The type of the bookmark data. * @param id_or_bookmark - The ID of the bookmark to update, or (deprecated) the full bookmark object. * @param updates_or_options - The updates to apply, or (deprecated) the update options when using the bookmark overload. * @param options - The options for updating the bookmark. * @returns A promise that resolves to the updated bookmark with its associated data. */ updateBookmarkAsync(id_or_bookmark: string | Bookmark, updates_or_options?: BookmarkUpdate | BookmarkUpdateOptions, options?: BookmarkUpdateOptions): Promise>; /** * Deletes a bookmark with the specified bookmarkId. * The deletion executes immediately when this method is called. * * @param bookmarkId - The unique identifier of the bookmark to be deleted. * @returns An Observable that emits when the bookmark is successfully deleted. * @throws {BookmarkProviderError} If there is an error deleting the bookmark. */ deleteBookmark(bookmarkId: string): Observable; /** * Deletes a bookmark asynchronously. * * @param bookmarkId - The ID of the bookmark to delete. * @returns A Promise that resolves when the bookmark is deleted. */ deleteBookmarkAsync(bookmarkId: string): Promise; /** * Adds a bookmark to favorites. * * @param bookmarkId - The ID of the bookmark to add. * @returns An observable that emits the added bookmark, or undefined if it could not be resolved. * @throws {BookmarkProviderError} If the onBookmarkFavouriteAdd event is canceled, the add request fails, or the request times out. */ addBookmarkToFavorites(bookmarkId: string): Observable; /** * Asynchronously adds a bookmark to the user's favorites. * * @param bookmarkId - The ID of the bookmark to add to the user's favorites. * @returns A Promise that resolves to the added Bookmark, or null if the operation failed. */ addBookmarkToFavoritesAsync(bookmarkId: string): Promise; /** * Removes a bookmark as a favorite. * * @param bookmarkId - The ID of the bookmark to remove as a favorite. * @returns A Promise that resolves when the bookmark is successfully removed as a favorite. * @throws {BookmarkProviderError} If the event is canceled or if there is a failure in removing the bookmark as a favorite. */ removeBookmarkAsFavorite(bookmarkId: string): Observable; /** * Removes a bookmark as a favorite asynchronously. * * @param bookmarkId - The ID of the bookmark to remove as a favorite. * @returns A Promise that resolves when the bookmark is successfully removed as a favorite. */ removeBookmarkAsFavoriteAsync(bookmarkId: string): Promise; /** * Checks if a bookmark is in the favorites. * @param bookmarkId - The ID of the bookmark to check. * @returns An observable that emits a boolean indicating whether the bookmark is in the favorites. * @throws {BookmarkProviderError} If checking the favorite status fails. */ isBookmarkInFavorites(bookmarkId: string): Observable; /** * Checks if the specified bookmark is in the user's favorites. * * @param bookmarkId - The ID of the bookmark to check. * @returns A Promise that resolves to a boolean indicating whether the bookmark is in the user's favorites. */ isBookmarkInFavoritesAsync(bookmarkId: string): Promise; /** * Fetches a single bookmark's metadata (without payload) via the store. * * @param bookmarkId - The unique identifier of the bookmark to fetch. * @param options - Optional settings, including a custom `timeout` in milliseconds. * @returns An observable that emits the bookmark's metadata once fetched. * @throws {BookmarkProviderError} If the fetch fails or times out. */ protected _getBookmarkInfo(bookmarkId: string, options?: { timeout?: number; }): Observable; /** * Fetches a single bookmark's payload data via the store. * * @template T - The type of the bookmark payload. * @param bookmarkId - The unique identifier of the bookmark whose data to fetch. * @param options - Optional settings, including a custom `timeout` in milliseconds. * @returns An observable that emits the bookmark's payload data once fetched. * @throws {BookmarkProviderError} If the fetch fails or times out. */ protected _getBookmarkData(bookmarkId: string, options?: { timeout?: number; }): Observable; /** * Dispatches an event of the specified type with the provided arguments. * * @template TType - The specific event type key being dispatched. * @param type - The type of the event to dispatch. * @param args - The arguments to pass to the event. * @returns A promise that resolves with the result of the event dispatch. */ protected _dispatchEvent(type: TType, args: FrameworkEventInitType]>): Promise]>; /** * Creates a scoped action reference and a filtered action stream containing only * actions tagged with that reference (or the provided `ref`, if given). * * @template TAction - The specific action type emitted on the scoped stream. * @param ref - An existing reference to scope actions to; a new GUID is generated when omitted. * @returns An object containing the resolved `ref` and the `action$` stream filtered to it. */ protected _useScopedActions(ref?: string): { ref: string; action$: Observable; }; /** * Disposes the BookmarkProvider. */ dispose(): void; /** * Disposes the BookmarkProvider via the `Symbol.dispose` protocol. */ [Symbol.dispose](): void; }