@equinor/fusion-framework-module-bookmark 3.0.6 → 4.0.0

package/dist/types/BookmarkClient.d.ts

@@ -29,14 +29,24 @@ export declare class BookmarkClient implements IBookmarkClient {
     constructor(api: BookmarksApiClient<'json$'>, options?: {
         expire?: number;
     });
+    /** @inheritdoc */
     getAllBookmarks(filter?: BookmarksFilter): ObservableInput<Bookmark[]>;
+    /** @inheritdoc */
     getBookmarkById(bookmarkId: string): ObservableInput<BookmarkWithoutData>;
+    /** @inheritdoc */
     getBookmarkData<T extends BookmarkData>(bookmarkId: string): ObservableInput<T>;
+    /** @inheritdoc */
     setBookmarkData<T extends BookmarkData | null>(bookmarkId: string, data: T): ObservableInput<T>;
+    /** @inheritdoc */
     createBookmark<T extends BookmarkData>(newBookmark: BookmarkNew<T>): ObservableInput<Bookmark<T>>;
+    /** @inheritdoc */
     updateBookmark<T extends BookmarkData>(bookmarkId: string, updates: BookmarkUpdate<T>): ObservableInput<Bookmark<T>>;
+    /** @inheritdoc */
     deleteBookmark(bookmarkId: string): ObservableInput<boolean>;
+    /** @inheritdoc */
     addBookmarkToFavorites(bookmarkId: string): ObservableInput<boolean>;
+    /** @inheritdoc */
     removeBookmarkFromFavorites(bookmarkId: string): ObservableInput<boolean>;
+    /** @inheritdoc */
     isBookmarkFavorite(bookmarkId: string): ObservableInput<boolean>;
 }

package/dist/types/BookmarkConfigurator.d.ts

@@ -5,7 +5,14 @@ import type { BookmarkModule } from './bookmark-module';
 import type { BookmarkModuleConfig } from './types';
 /**
  * Configurator for the bookmark module.
- * This class provides a set of methods for configuring the bookmark module.
+ *
+ * Provides a builder-style API for setting the source system, bookmark client,
+ * context/application resolvers, filters, and parent provider before the module
+ * is initialised. Extends {@link BaseConfigBuilder} and produces a validated
+ * {@link BookmarkModuleConfig} at build time.
+ *
+ * In most cases you interact with this class through the callback provided to
+ * {@link enableBookmark} rather than instantiating it directly.
  */
 export declare class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModuleConfig> {
     #private;

package/dist/types/BookmarkProvider.actions.d.ts

@@ -83,5 +83,6 @@ export declare const bookmarkActions: {
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: BookmarkFlowError, meta: BookmarkActionMeta], BookmarkFlowError, "remove_favourite_bookmark::failure", never, BookmarkActionMeta>;
     };
 };
+/** Union type of all action objects produced by {@link bookmarkActions}. */
 export type BookmarkActions = ActionTypes<typeof bookmarkActions>;
 export {};

package/dist/types/BookmarkProvider.error.d.ts

@@ -1,9 +1,26 @@
 import type { ActionWithSuffix } from '@equinor/fusion-observable';
 import type { BookmarkActions } from './BookmarkProvider.actions';
+/**
+ * Error thrown inside bookmark store flows (side-effect pipelines) when an
+ * API call or observable chain fails.
+ *
+ * Carries a reference to the originating request action so callers can
+ * correlate errors back to specific operations.
+ */
 export declare class BookmarkFlowError extends Error {
+    /** The request action that triggered the failed flow. */
     readonly action: ActionWithSuffix<BookmarkActions, 'request'>;
-    constructor(message: string, action: ActionWithSuffix<BookmarkActions, 'request'>, options?: ErrorOptions);
+    constructor(message: string, 
+    /** The request action that triggered the failed flow. */
+    action: ActionWithSuffix<BookmarkActions, 'request'>, options?: ErrorOptions);
 }
+/**
+ * General-purpose error thrown by {@link BookmarkProvider} methods when a
+ * high-level operation (create, update, delete, set current, etc.) fails.
+ *
+ * Distinct from {@link BookmarkFlowError}, which is scoped to internal
+ * store flow pipelines.
+ */
 export declare class BookmarkProviderError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }

package/dist/types/BookmarkProvider.interface.d.ts

@@ -3,10 +3,37 @@ import type { Bookmark, BookmarkData, BookmarkWithoutData } from './types';
 import type { BookmarkNew, BookmarkUpdate } from './BookmarkClient.interface';
 import type { BookmarkProviderEventMap } from './BookmarkProvider.events';
 import type { BookmarkState } from './BookmarkProvider.store';
+/**
+ * Arguments for creating a bookmark via {@link IBookmarkProvider.createBookmark}.
+ *
+ * Omits fields that the provider resolves automatically (`appKey`, `contextId`, `sourceSystem`),
+ * but allows the caller to override `appKey` if needed.
+ *
+ * @template T - The type of payload data stored in the bookmark.
+ */
 export type BookmarkCreateArgs<T extends BookmarkData = any> = Omit<BookmarkNew<T>, 'appKey' | 'contextId' | 'sourceSystem'> & Partial<Pick<BookmarkNew<T>, 'appKey'>>;
+/**
+ * Options that control how {@link IBookmarkProvider.updateBookmark} processes an update.
+ *
+ * @property excludePayloadGeneration - When `true`, skip running registered payload generators
+ *   and send the update payload as-is. Useful when the caller has already computed the full payload.
+ */
 export type BookmarkUpdateOptions = {
     excludePayloadGeneration?: boolean;
 };
+/**
+ * Callback registered with {@link IBookmarkProvider.addPayloadGenerator} that participates
+ * in building or transforming bookmark payload data during create and update operations.
+ *
+ * The `payload` argument is an Immer draft — mutate it in place rather than returning a new
+ * object. If the generator returns a value it will be used, but this is discouraged.
+ * Return `null` to signal that the bookmark payload should be cleared.
+ *
+ * @template TData - Shape of the bookmark payload.
+ * @param payload - The accumulated payload draft from previous generators (mutable).
+ * @param initial - The original payload before any generators ran (read-only reference).
+ * @returns A partial payload, `void` (when mutating the draft), or `null` to clear.
+ */
 export type BookmarkPayloadGenerator<TData extends BookmarkData = any> = (payload?: Partial<TData> | null, initial?: Partial<TData> | null) => Promise<Partial<TData> | void> | Partial<TData> | void;
 /**
  * Interface representing a Bookmark Provider.
@@ -95,6 +122,16 @@ export interface IBookmarkProvider {
      * @returns {ObservableInput<boolean>} An observable input indicating whether the bookmark is in the favorites.
      */
     isBookmarkInFavorites(bookmarkId: string): ObservableInput<boolean>;
+    /**
+     * Registers a payload generator that runs during bookmark create and update operations.
+     *
+     * Multiple generators can be registered and they execute sequentially, each receiving
+     * the accumulated payload from previous generators.
+     *
+     * @template TData - Shape of the bookmark payload.
+     * @param generator - The generator callback to register.
+     * @returns A disposal function that unregisters the generator when called.
+     */
     addPayloadGenerator<TData extends BookmarkData>(generator: BookmarkPayloadGenerator<TData>): VoidFunction;
     /**
      * Registers an event listener for bookmark provider events.

package/dist/types/BookmarkProvider.selectors.d.ts

@@ -2,20 +2,27 @@ import type { BookmarkFlowError } from './BookmarkProvider.error';
 import type { BookmarkState } from './BookmarkProvider.store';
 import type { Bookmark, BookmarkData } from './types';
 /**
- * Selects all bookmarks from the application state.
+ * Selects all bookmarks from the store state as an array.
+ *
+ * @param state - The current bookmark store state.
+ * @returns An array of all bookmarks.
  */
 export declare const bookmarksSelector: (state: BookmarkState) => Bookmark[];
 /**
- * Retrieves a bookmark from the state by its ID.
+ * Retrieves a single bookmark from the store state by its ID.
+ *
+ * @template T - The bookmark payload data shape.
+ * @param state - The current bookmark store state.
+ * @param id - The bookmark identifier to look up.
+ * @returns The matching bookmark, or `undefined` if not found.
  */
 export declare const bookmarkSelector: <T extends BookmarkData>(state: BookmarkState, id: string) => Bookmark<T> | undefined;
 /**
- * Selects the active bookmark from the bookmark state.
- *
- * if there is an active bookmark, the function returns the bookmark data.
+ * Selects the currently active bookmark from the store state.
  *
- * if there is no active bookmark, the function returns null.
- * if the active bookmark was never set, the function returns undefined.
+ * @template T - The bookmark payload data shape.
+ * @param state - The current bookmark store state.
+ * @returns The active bookmark, `null` if explicitly cleared, or `undefined` if never set.
  */
 export declare const activeBookmarkSelector: <T extends BookmarkData>(state: BookmarkState) => Bookmark<T> | null | undefined;
 /**

package/dist/types/BookmarkProvider.store.d.ts

@@ -4,7 +4,12 @@ import type { BookmarkFlowError } from './BookmarkProvider.error';
 import type { IBookmarkClient } from './BookmarkClient.interface';
 import type { Bookmark, BookmarkWithoutData } from './types';
 /**
- * Represents the state of the BookmarkProvider store.
+ * Internal state shape managed by the bookmark store.
+ *
+ * @property status - Set of base action types currently in-flight (used for loading indicators).
+ * @property errors - Map from base action type to the most recent error for that action.
+ * @property currentBookmark - The active bookmark, `null` when explicitly cleared, `undefined` before first set.
+ * @property bookmarks - Normalised record of bookmarks keyed by ID.
  */
 export type BookmarkState = {
     status: Set<ActionBaseType<BookmarkActions>>;
@@ -13,16 +18,20 @@ export type BookmarkState = {
     bookmarks: Record<string, BookmarkWithoutData>;
 };
 /**
- * Represents the store for bookmarks, which is a flow subject that manages the state and actions for bookmarks.
+ * A {@link FlowSubject} specialised for bookmark state and actions.
+ *
+ * Combines a Redux-style reducer with RxJS side-effect flows to manage
+ * bookmark CRUD operations, favourites, and current-bookmark selection.
  */
 export type BookmarkStore = FlowSubject<BookmarkState, BookmarkActions>;
 /**
- * Creates a new BookmarkStore instance with the provided initial state and client.
+ * Creates and returns a new {@link BookmarkStore} wired with the bookmark
+ * reducer and all API side-effect flows.
  *
- * @param args - An object containing the initial state and client for the bookmark store.
- * @param args.initial - The initial state for the bookmark store.
- * @param args.client - The IBookmarkClient instance to bookmark store flows.
- * @returns A new BookmarkStore instance.
+ * @param args - Initialisation options.
+ * @param args.initial - Optional partial state merged over the reducer defaults.
+ * @param args.client - The {@link IBookmarkClient} used by store flows for API calls.
+ * @returns A fully configured bookmark store.
  */
 export declare const createBookmarkStore: (args: {
     initial?: Partial<BookmarkState>;

package/dist/types/bookmark-config.schema.d.ts

@@ -4,6 +4,12 @@ import type { IEventModuleProvider } from '@equinor/fusion-framework-module-even
 import type { IBookmarkProvider } from './BookmarkProvider.interface';
 import type { IBookmarkClient } from './BookmarkClient.interface';
 import type { BookmarkModuleConfig } from './types';
+/**
+ * Zod schema that validates the full {@link BookmarkModuleConfig} object.
+ *
+ * Used internally by {@link BookmarkModuleConfigurator} to verify the resolved
+ * configuration before the bookmark module is initialised.
+ */
 export declare const bookmarkConfigSchema: z.ZodObject<{
     log: z.ZodOptional<z.ZodCustom<ILogger, ILogger>>;
     logLevel: z.ZodOptional<z.ZodEnum<typeof LogLevel>>;
@@ -24,4 +30,11 @@ export declare const bookmarkConfigSchema: z.ZodObject<{
         application: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
+/**
+ * Parses an unknown configuration object against {@link bookmarkConfigSchema}.
+ *
+ * @param config - The raw config value to validate.
+ * @returns A validated {@link BookmarkModuleConfig}.
+ * @throws {ZodError} When validation fails.
+ */
 export declare const parseBookmarkConfig: (config: unknown) => BookmarkModuleConfig;

package/dist/types/bookmark-module.d.ts

@@ -5,14 +5,37 @@ import type { AppModule } from '@equinor/fusion-framework-module-app';
 import type { ContextModule } from '@equinor/fusion-framework-module-context';
 import { BookmarkModuleConfigurator } from './BookmarkConfigurator';
 import type { IBookmarkProvider } from './BookmarkProvider.interface';
+/** String literal key used to register the bookmark module in the framework. */
 export type BookmarkModuleKey = 'bookmark';
+/** The module key constant used to identify the bookmark module at runtime. */
 export declare const moduleKey: BookmarkModuleKey;
+/**
+ * Type definition for the bookmark framework module.
+ *
+ * Declares the module key, provider interface, configurator class,
+ * and optional peer dependencies (event, services, app, context modules).
+ */
 export type BookmarkModule = Module<BookmarkModuleKey, IBookmarkProvider, BookmarkModuleConfigurator, [
     EventModule,
     ServicesModule,
     AppModule,
     ContextModule
 ]>;
+/**
+ * Bookmark module definition for the Fusion Framework.
+ *
+ * Handles configuration, initialization (creating a {@link BookmarkProvider}),
+ * and disposal of the bookmark module lifecycle.
+ *
+ * @example
+ * ```ts
+ * import { enableBookmark } from '@equinor/fusion-framework-module-bookmark';
+ *
+ * const configure = (configurator) => {
+ *   enableBookmark(configurator);
+ * };
+ * ```
+ */
 export declare const module: BookmarkModule;
 declare module '@equinor/fusion-framework-module' {
     interface Modules {

package/dist/types/bookmark.schemas.d.ts

@@ -1,20 +1,24 @@
 import * as z from 'zod';
 import type { Bookmark, BookmarkData } from './types';
+/** Zod schema for validating {@link BookmarkUser} objects. */
 export declare const bookmarkUserSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     mail: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** Zod schema for validating {@link SourceSystem} objects on a bookmark. */
 export declare const bookmarkSourceSystemSchema: z.ZodObject<{
     identifier: z.ZodString;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     subSystem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
+/** Zod schema for validating {@link BookmarkContext} objects. */
 export declare const bookmarkContextSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** Zod schema for validating a {@link BookmarkWithoutData} (no payload). */
 export declare const bookmarkSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -44,6 +48,7 @@ export declare const bookmarkSchema: z.ZodObject<{
         subSystem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
+/** Zod schema for validating an array of bookmarks. */
 export declare const bookmarksSchema: z.ZodArray<z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -73,6 +78,15 @@ export declare const bookmarksSchema: z.ZodArray<z.ZodObject<{
         subSystem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>>;
+/**
+ * Creates a Zod schema for a {@link Bookmark} that includes a typed payload field.
+ *
+ * @template T - The bookmark payload data shape.
+ * @template S - Zod schema type for the payload.
+ * @param schema - Optional Zod schema to validate the payload. Defaults to
+ *   `z.record(z.string(), z.unknown()).or(z.string()).optional()`.
+ * @returns A Zod object schema extending {@link bookmarkSchema} with a `payload` property.
+ */
 export declare const bookmarkWithDataSchema: <T extends BookmarkData = BookmarkData, S extends z.ZodSchema<T> = z.ZodSchema<T>>(schema?: S) => z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -103,4 +117,12 @@ export declare const bookmarkWithDataSchema: <T extends BookmarkData = BookmarkD
     }, z.core.$strip>>>;
     payload: S;
 }, z.core.$strip>;
+/**
+ * Parses an unknown value into a typed {@link Bookmark} using {@link bookmarkWithDataSchema}.
+ *
+ * @template T - The bookmark payload data shape.
+ * @param value - The raw value to parse.
+ * @returns The parsed bookmark object.
+ * @throws {ZodError} When validation fails.
+ */
 export declare const parseBookmark: <T extends BookmarkData>(value: unknown) => Bookmark<T>;

package/dist/types/enable-bookmark.d.ts

@@ -1,9 +1,27 @@
 import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
 import type { BookmarkModuleConfigurator } from './BookmarkConfigurator';
 /**
- * Enables the Bookmark module
+ * Enables the bookmark module on a Fusion Framework module configurator.
  *
- * @param configurator - The configuration object for the modules.
- * @param callback - An optional callback function that receives the `BookmarkModuleConfigurator` instance, allowing for further configuration.
+ * This is the primary entry point for adding bookmark support to an application.
+ * Call it during the application’s configure phase to register the module.
+ * An optional callback allows further customisation of the bookmark configurator
+ * (source system, filters, custom client, etc.).
+ *
+ * @param configurator - The application’s module configurator instance.
+ * @param callback - Optional callback that receives the {@link BookmarkModuleConfigurator}
+ *   for additional setup such as setting source system, filters, or a custom client.
+ *
+ * @example
+ * ```ts
+ * import { enableBookmark } from '@equinor/fusion-framework-module-bookmark';
+ *
+ * const configure = (configurator) => {
+ *   enableBookmark(configurator, (builder) => {
+ *     builder.setSourceSystem({ identifier: 'my-app', name: 'My App' });
+ *     builder.setFilter('application', true);
+ *   });
+ * };
+ * ```
  */
 export declare const enableBookmark: (configurator: IModulesConfigurator<any>, callback?: (builder: BookmarkModuleConfigurator) => void | Promise<void>) => void;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.6";
+export declare const version = "4.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-bookmark",
-  "version": "3.0.6",
+  "version": "4.0.0",
   "description": "",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -41,20 +41,19 @@
     "immer": "^11.0.0",
     "rxjs": "^7.8.1",
     "uuid": "^13.0.0",
-    "@equinor/fusion-framework-module": "^5.0.6",
-    "@equinor/fusion-log": "^1.1.8",
-    "@equinor/fusion-observable": "^8.5.8",
-    "@equinor/fusion-query": "^6.0.4"
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-observable": "^9.0.0",
+    "@equinor/fusion-query": "^7.0.0",
+    "@equinor/fusion-log": "^2.0.0"
   },
   "devDependencies": {
-    "@types/uuid": "^11.0.0",
-    "typescript": "^5.8.2",
-    "zod": "^4.1.8",
-    "@equinor/fusion-framework-module-context": "^7.0.3",
-    "@equinor/fusion-framework-module-app": "^7.4.1",
-    "@equinor/fusion-framework-module-event": "^5.0.1",
-    "@equinor/fusion-framework-module-services": "^7.2.1",
-    "@equinor/fusion-framework-module-http": "^7.0.8"
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6",
+    "@equinor/fusion-framework-module-context": "^8.0.0",
+    "@equinor/fusion-framework-module-event": "^6.0.0",
+    "@equinor/fusion-framework-module-services": "^8.0.0",
+    "@equinor/fusion-framework-module-app": "^8.0.0",
+    "@equinor/fusion-framework-module-http": "^8.0.0"
   },
   "scripts": {
     "build": "tsc -b"

package/src/BookmarkClient.ts

@@ -128,18 +128,22 @@ export class BookmarkClient implements IBookmarkClient {
     });
   }
 
+  /** @inheritdoc */
   public getAllBookmarks(filter?: BookmarksFilter): ObservableInput<Bookmark[]> {
     return this.#queryBookmarks.query(filter).pipe(map((res) => res.value as Bookmark[]));
   }
 
+  /** @inheritdoc */
   public getBookmarkById(bookmarkId: string): ObservableInput<BookmarkWithoutData> {
     return this.#queryBookmark.query({ bookmarkId }).pipe(map((res) => res.value));
   }
 
+  /** @inheritdoc */
   public getBookmarkData<T extends BookmarkData>(bookmarkId: string): ObservableInput<T> {
     return this.#queryBookmarkData.query({ bookmarkId }).pipe(map((res): T => res.value as T));
   }
 
+  /** @inheritdoc */
   public setBookmarkData<T extends BookmarkData | null>(
     bookmarkId: string,
     data: T,
@@ -158,6 +162,7 @@ export class BookmarkClient implements IBookmarkClient {
     );
   }
 
+  /** @inheritdoc */
   public createBookmark<T extends BookmarkData>(
     newBookmark: BookmarkNew<T>,
   ): ObservableInput<Bookmark<T>> {
@@ -184,6 +189,7 @@ export class BookmarkClient implements IBookmarkClient {
     );
   }
 
+  /** @inheritdoc */
   public updateBookmark<T extends BookmarkData>(
     bookmarkId: string,
     updates: BookmarkUpdate<T>,
@@ -240,22 +246,26 @@ export class BookmarkClient implements IBookmarkClient {
     });
   }
 
+  /** @inheritdoc */
   public deleteBookmark(bookmarkId: string): ObservableInput<boolean> {
     return this.#api.delete('v1', { bookmarkId });
   }
 
+  /** @inheritdoc */
   public addBookmarkToFavorites(bookmarkId: string): ObservableInput<boolean> {
     return this.#api
       .addFavourite('v1', { bookmarkId })
       .pipe(tap(() => this.#queryBookmarks.invalidate()));
   }
 
+  /** @inheritdoc */
   public removeBookmarkFromFavorites(bookmarkId: string): ObservableInput<boolean> {
     return this.#api
       .removeFavourite('v1', { bookmarkId })
       .pipe(tap(() => this.#queryBookmarks.invalidate()));
   }
 
+  /** @inheritdoc */
   public isBookmarkFavorite(bookmarkId: string): ObservableInput<boolean> {
     return this.#api.isFavorite('v1', { bookmarkId });
   }

package/src/BookmarkConfigurator.ts

@@ -32,7 +32,14 @@ const parseInitialBookmarkConfigConfig = (initial?: unknown): BookmarkModuleConf
 
 /**
  * Configurator for the bookmark module.
- * This class provides a set of methods for configuring the bookmark module.
+ *
+ * Provides a builder-style API for setting the source system, bookmark client,
+ * context/application resolvers, filters, and parent provider before the module
+ * is initialised. Extends {@link BaseConfigBuilder} and produces a validated
+ * {@link BookmarkModuleConfig} at build time.
+ *
+ * In most cases you interact with this class through the callback provided to
+ * {@link enableBookmark} rather than instantiating it directly.
  */
 export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModuleConfig> {
   #log?: ILogger;

package/src/BookmarkProvider.actions.ts

@@ -128,4 +128,5 @@ export const bookmarkActions = {
   ),
 };
 
+/** Union type of all action objects produced by {@link bookmarkActions}. */
 export type BookmarkActions = ActionTypes<typeof bookmarkActions>;

package/src/BookmarkProvider.error.ts

@@ -2,9 +2,17 @@ import type { ActionWithSuffix } from '@equinor/fusion-observable';
 
 import type { BookmarkActions } from './BookmarkProvider.actions';
 
+/**
+ * Error thrown inside bookmark store flows (side-effect pipelines) when an
+ * API call or observable chain fails.
+ *
+ * Carries a reference to the originating request action so callers can
+ * correlate errors back to specific operations.
+ */
 export class BookmarkFlowError extends Error {
   constructor(
     message: string,
+    /** The request action that triggered the failed flow. */
     public readonly action: ActionWithSuffix<BookmarkActions, 'request'>,
     options?: ErrorOptions,
   ) {
@@ -13,6 +21,13 @@ export class BookmarkFlowError extends Error {
   }
 }
 
+/**
+ * General-purpose error thrown by {@link BookmarkProvider} methods when a
+ * high-level operation (create, update, delete, set current, etc.) fails.
+ *
+ * Distinct from {@link BookmarkFlowError}, which is scoped to internal
+ * store flow pipelines.
+ */
 export class BookmarkProviderError extends Error {
   constructor(message: string, options?: ErrorOptions) {
     super(message, options);

package/src/BookmarkProvider.interface.ts

@@ -5,16 +5,43 @@ import type { BookmarkNew, BookmarkUpdate } from './BookmarkClient.interface';
 import type { BookmarkProviderEventMap } from './BookmarkProvider.events';
 import type { BookmarkState } from './BookmarkProvider.store';
 
+/**
+ * Arguments for creating a bookmark via {@link IBookmarkProvider.createBookmark}.
+ *
+ * Omits fields that the provider resolves automatically (`appKey`, `contextId`, `sourceSystem`),
+ * but allows the caller to override `appKey` if needed.
+ *
+ * @template T - The type of payload data stored in the bookmark.
+ */
 export type BookmarkCreateArgs<T extends BookmarkData = any> = Omit<
   BookmarkNew<T>,
   'appKey' | 'contextId' | 'sourceSystem'
 > &
   Partial<Pick<BookmarkNew<T>, 'appKey'>>;
 
+/**
+ * Options that control how {@link IBookmarkProvider.updateBookmark} processes an update.
+ *
+ * @property excludePayloadGeneration - When `true`, skip running registered payload generators
+ *   and send the update payload as-is. Useful when the caller has already computed the full payload.
+ */
 export type BookmarkUpdateOptions = {
   excludePayloadGeneration?: boolean;
 };
 
+/**
+ * Callback registered with {@link IBookmarkProvider.addPayloadGenerator} that participates
+ * in building or transforming bookmark payload data during create and update operations.
+ *
+ * The `payload` argument is an Immer draft — mutate it in place rather than returning a new
+ * object. If the generator returns a value it will be used, but this is discouraged.
+ * Return `null` to signal that the bookmark payload should be cleared.
+ *
+ * @template TData - Shape of the bookmark payload.
+ * @param payload - The accumulated payload draft from previous generators (mutable).
+ * @param initial - The original payload before any generators ran (read-only reference).
+ * @returns A partial payload, `void` (when mutating the draft), or `null` to clear.
+ */
 export type BookmarkPayloadGenerator<TData extends BookmarkData = any> = (
   payload?: Partial<TData> | null,
   initial?: Partial<TData> | null,
@@ -124,6 +151,16 @@ export interface IBookmarkProvider {
    */
   isBookmarkInFavorites(bookmarkId: string): ObservableInput<boolean>;
 
+  /**
+   * Registers a payload generator that runs during bookmark create and update operations.
+   *
+   * Multiple generators can be registered and they execute sequentially, each receiving
+   * the accumulated payload from previous generators.
+   *
+   * @template TData - Shape of the bookmark payload.
+   * @param generator - The generator callback to register.
+   * @returns A disposal function that unregisters the generator when called.
+   */
   addPayloadGenerator<TData extends BookmarkData>(
     generator: BookmarkPayloadGenerator<TData>,
   ): VoidFunction;

package/src/BookmarkProvider.selectors.ts

@@ -3,14 +3,22 @@ import type { BookmarkState } from './BookmarkProvider.store';
 import type { Bookmark, BookmarkData } from './types';
 
 /**
- * Selects all bookmarks from the application state.
+ * Selects all bookmarks from the store state as an array.
+ *
+ * @param state - The current bookmark store state.
+ * @returns An array of all bookmarks.
  */
 export const bookmarksSelector = (state: BookmarkState): Bookmark[] => {
   return Object.values(state.bookmarks) as Bookmark[];
 };
 
 /**
- * Retrieves a bookmark from the state by its ID.
+ * Retrieves a single bookmark from the store state by its ID.
+ *
+ * @template T - The bookmark payload data shape.
+ * @param state - The current bookmark store state.
+ * @param id - The bookmark identifier to look up.
+ * @returns The matching bookmark, or `undefined` if not found.
  */
 export const bookmarkSelector = <T extends BookmarkData>(
   state: BookmarkState,
@@ -20,12 +28,11 @@ export const bookmarkSelector = <T extends BookmarkData>(
 };
 
 /**
- * Selects the active bookmark from the bookmark state.
- *
- * if there is an active bookmark, the function returns the bookmark data.
+ * Selects the currently active bookmark from the store state.
  *
- * if there is no active bookmark, the function returns null.
- * if the active bookmark was never set, the function returns undefined.
+ * @template T - The bookmark payload data shape.
+ * @param state - The current bookmark store state.
+ * @returns The active bookmark, `null` if explicitly cleared, or `undefined` if never set.
  */
 export const activeBookmarkSelector = <T extends BookmarkData>(
   state: BookmarkState,