@equinor/fusion-framework-module-services 7.2.1 → 8.0.0

package/dist/types/provider.d.ts

@@ -6,24 +6,51 @@ import { ContextApiClient } from './context';
 import BookmarksApiClient from './bookmarks/client';
 import { NotificationApiClient } from './notification';
 import { PeopleApiClient } from './people/client';
+/**
+ * Public interface for the services module provider.
+ *
+ * Exposes factory methods for creating domain-specific API clients
+ * for bookmarks, context, notification, and people services.
+ * Each factory resolves a named HTTP client, attaches response
+ * validation, and returns a typed client instance.
+ *
+ * @template TClient - The underlying HTTP client type.
+ */
 export interface IApiProvider<TClient extends IHttpClient = IHttpClient> {
     /**
-     * @param method - Version of the service to use
+     * Creates a typed client for the bookmarks API.
+     *
+     * @template TMethod - The client execution method (`'json'` or `'json$'`).
+     * @param method - The execution method to use for requests.
+     * @returns A configured {@link BookmarksApiClient} instance.
      */
     createBookmarksClient<TMethod extends keyof ClientMethod>(method: TMethod): Promise<BookmarksApiClient<TMethod, TClient>>;
     /**
-     * @param method - Version of the service to use
+     * Creates a typed client for the context API.
+     *
+     * @template TMethod - The client execution method (`'json'` or `'json$'`).
+     * @param method - The execution method to use for requests.
+     * @returns A configured {@link ContextApiClient} instance.
      */
     createContextClient<TMethod extends keyof ClientMethod>(method: TMethod): Promise<ContextApiClient<TMethod, TClient>>;
     /**
-     * @param method - Version of the service to use
+     * Creates a typed client for the notification API.
+     *
+     * @template TMethod - The client execution method (`'json'` or `'json$'`).
+     * @param method - The execution method to use for requests.
+     * @returns A configured {@link NotificationApiClient} instance.
      */
     createNotificationClient<TMethod extends keyof ClientMethod>(method: TMethod): Promise<NotificationApiClient<TMethod, TClient>>;
     /**
-     * @param method - Version of the service to use
+     * Creates a typed client for the people API.
+     *
+     * @returns A configured {@link PeopleApiClient} instance.
      */
     createPeopleClient(): Promise<PeopleApiClient<TClient>>;
 }
+/**
+ * Shape of the structured error response attached to an {@link ApiProviderError}.
+ */
 type ApiProviderErrorResponse = {
     type: ResponseType;
     status: number;
@@ -32,13 +59,51 @@ type ApiProviderErrorResponse = {
     url: string;
     data: unknown;
 };
+/**
+ * Error thrown when an API response indicates a non-OK HTTP status.
+ *
+ * Contains the full {@link ApiProviderErrorResponse} (status, headers, body)
+ * so callers can inspect the failure details.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await provider.createNotificationClient('json');
+ * } catch (err) {
+ *   if (err instanceof ApiProviderError) {
+ *     console.error(err.response.status, err.response.data);
+ *   }
+ * }
+ * ```
+ */
 export declare class ApiProviderError extends Error {
+    /** Structured HTTP response data associated with this error. */
     readonly response: ApiProviderErrorResponse;
+    /**
+     * @param msg - Human-readable error message.
+     * @param response - The parsed HTTP response details.
+     * @param options - Standard `ErrorOptions` (e.g. `cause`).
+     */
     constructor(msg: string, response: ApiProviderErrorResponse, options?: ErrorOptions);
 }
+/**
+ * Internal configuration shape for {@link ApiProvider}.
+ *
+ * @template TClient - The underlying HTTP client type.
+ */
 type ApiProviderConfig<TClient extends IHttpClient = IHttpClient> = {
     createClient: ApiClientFactory<TClient>;
 };
+/**
+ * Default implementation of {@link IApiProvider}.
+ *
+ * Manages the lifecycle of domain-specific API clients (bookmarks, context,
+ * notification, people) by resolving named HTTP clients through the
+ * configured {@link ApiClientFactory} and attaching response-validation
+ * middleware.
+ *
+ * @template TClient - The underlying HTTP client type.
+ */
 export declare class ApiProvider<TClient extends IHttpClient = IHttpClient> extends BaseModuleProvider<ApiProviderConfig<TClient>> implements IApiProvider<TClient> {
     protected _createClientFn: ApiClientFactory<TClient>;
     constructor(config: ApiProviderConfig<TClient>);

package/dist/types/types.d.ts

@@ -1,40 +1,65 @@
 import type { ClientRequestInit, IHttpClient, StreamResponse, BlobResult } from '@equinor/fusion-framework-module-http/client';
 /**
- * A factory function that creates an instance of an HTTP client.
+ * Factory function that creates a named HTTP client instance.
  *
- * @param name - The name of the HTTP client to create.
- * @returns A Promise that resolves to an instance of the HTTP client.
+ * Used by {@link ApiProvider} to resolve service-specific HTTP clients
+ * (for example, `'bookmarks'`, `'context'`, `'notification'`, `'people'`).
+ * The factory first checks registered HTTP clients, then falls back to
+ * service discovery.
+ *
+ * @template TClient - The HTTP client type to create.
+ * @param name - Logical service name used to look up or create the HTTP client.
+ * @returns A Promise that resolves to a configured HTTP client instance.
  */
 export type ApiClientFactory<TClient extends IHttpClient = IHttpClient> = (name: string) => Promise<TClient>;
 /**
- * Represents the arguments for an API client function.
+ * Tuple type representing the positional arguments passed to an HTTP client method.
+ *
+ * Used internally by endpoint generators to build the `[path, init]` pair
+ * that the HTTP client's `json()` or `json$()` method expects.
  *
- * @template TClient - The type of the HTTP client used by the API client.
- * @template TResult - The type of the result returned by the API client.
- * @param path - The path of the API endpoint.
- * @param init - Optional initialization options for the API client request.
+ * @template TClient - The HTTP client type that will execute the request.
+ * @template TResult - The expected response body type.
  */
 export type ApiClientArguments<TClient extends IHttpClient, TResult = unknown> = [
     path: string,
     init?: ClientRequestInit<TClient, TResult>
 ];
 /**
- * Execute methods on the IHttpClient
+ * Maps HTTP client execution methods to their return types.
+ *
+ * - `json` — returns a `Promise` that resolves with the parsed JSON body.
+ * - `json$` — returns an RxJS-style `StreamResponse` observable.
+ *
+ * All versioned API client methods are generic over `ClientMethod`,
+ * allowing callers to choose between promise-based and observable-based
+ * consumption.
+ *
+ * @template T - The expected deserialized response body type.
  */
 export type ClientMethod<T = unknown> = {
-    /**
-     * Fetch JSON data from a service
-     */
+    /** Fetch JSON data from a service as a promise. */
     json: Promise<T>;
-    /**
-     * Fetch JSON data from a service as observable
-     */
+    /** Fetch JSON data from a service as an observable stream. */
     json$: StreamResponse<T>;
 };
+/**
+ * Maps HTTP client binary-data execution methods to their return types.
+ *
+ * - `blob` — returns a `Promise` that resolves with the binary blob result.
+ * - `blob$` — returns an RxJS-style `StreamResponse` observable for the blob.
+ *
+ * Used by endpoints that return non-JSON data such as profile photos.
+ *
+ * @template T - The blob result type, defaults to `BlobResult`.
+ */
 export type ClientDataMethod<T extends BlobResult = BlobResult> = {
+    /** Fetch binary data from a service as a promise. */
     blob: Promise<T>;
+    /** Fetch binary data from a service as an observable stream. */
     blob$: StreamResponse<T>;
 };
+/** Union of available client method names (`'json' | 'json$'`). */
 export type ClientMethodType = keyof ClientMethod;
 /**
  * Utility type that filters the keys of an `AvailableTypes` object to only those

package/dist/types/utils.d.ts

@@ -2,17 +2,8 @@ import type { z } from 'zod';
 import { type ResponseSelector } from '@equinor/fusion-framework-module-http/selectors';
 import type { ExtractApiVersion } from './types';
 /**
- * Extracts the correct API version from the provided `apiVersions` object based on the given `version` parameter.
- *
- * @param apiVersions - An object mapping API version strings to their corresponding versions.
- * @param version - The version string to extract.
- * @returns The extracted API version, or throws an error if the version is not supported.
- */
+ * Resolves an API version string from a named key or raw version value.\n *\n * Looks up `version` as a key in `apiVersions` first; if not found,\n * searches the object values for a direct match. Throws when neither\n * lookup succeeds.\n *\n * @template TApiVersions - Record mapping version names to version strings.\n * @template TAllowedApiVersion - Allowed version constraint.\n * @template TVersion - The version string provided by the caller.\n * @param apiVersions - Map of version names to version strings.\n * @param version - Version key or raw version string to resolve.\n * @returns The resolved API version string.\n * @throws {Error} When the version is not found in `apiVersions`.\n *\n * @example\n * ```ts\n * enum ApiVersions { v1 = '1.0', v2 = '2.0' }\n * extractVersion(ApiVersions, 'v1'); // '1.0'\n * extractVersion(ApiVersions, '1.0'); // '1.0'\n * ```\n */
 export declare const extractVersion: <TApiVersions extends Record<string, string>, TAllowedApiVersion extends string, TVersion extends string>(apiVersions: TApiVersions, version: TVersion) => ExtractApiVersion<TApiVersions, TVersion, TAllowedApiVersion>;
 /**
- * Creates a response selector that parses the response body using the provided Zod schema.
- *
- * @param schema - The Zod schema to use for parsing the response body.
- * @returns A response selector function that parses the response body using the provided schema.
- */
+ * Creates a response selector that parses the HTTP response body with a Zod schema.\n *\n * Combines the built-in `jsonSelector` with Zod validation, ensuring the\n * response body matches the expected shape at runtime.\n *\n * @template Output - The validated output type produced by the schema.\n * @param schema - The Zod schema used to parse and validate the response body.\n * @returns A `ResponseSelector` that extracts JSON and runs it through `schema.parse`.\n *\n * @example\n * ```ts\n * import { z } from 'zod';\n * const UserSchema = z.object({ id: z.string(), name: z.string() });\n * const selector = schemaSelector(UserSchema);\n * ```\n */
 export declare const schemaSelector: <Output>(schema: z.ZodSchema<Output>) => ResponseSelector<Output>;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.2.1";
+export declare const version = "8.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-services",
-  "version": "7.2.1",
+  "version": "8.0.0",
   "description": "",
   "sideEffects": false,
   "main": "dist/esm/index.js",
@@ -137,20 +137,20 @@
   },
   "dependencies": {
     "odata-query": "^8.0.4",
-    "zod": "^4.1.8"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.1.0",
     "msw": "^2.7.3",
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4",
-    "@equinor/fusion-framework-module": "^5.0.6",
-    "@equinor/fusion-framework-module-service-discovery": "^9.1.1",
-    "@equinor/fusion-framework-module-http": "^7.0.8"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-framework-module-http": "^8.0.0",
+    "@equinor/fusion-framework-module-service-discovery": "^10.0.0"
   },
   "peerDependencies": {
-    "odata-query": "^8.0.4",
-    "@equinor/fusion-framework-module": "^5.0.6"
+    "odata-query": "^8.0.0",
+    "@equinor/fusion-framework-module": "^6.0.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/bookmarks/api-version.ts

@@ -1,4 +1,7 @@
+/** Supported API versions for the bookmarks service. */
 export enum ApiVersion {
+  /** Bookmarks API version 1.0. */
   v1 = '1.0',
+  /** Bookmarks API version 2.0. */
   v2 = '2.0',
 }

package/src/bookmarks/index.ts

@@ -1,3 +1,17 @@
+/**
+ * @packageDocumentation
+ *
+ * Bookmarks API client and types.
+ *
+ * Provides {@link BookmarksApiClient} for CRUD operations on bookmarks
+ * and favourite management, with versioned endpoints (`v1`, `v2`).
+ *
+ * @example
+ * ```ts
+ * import { BookmarksApiClient } from '@equinor/fusion-framework-module-services/bookmarks';
+ * ```
+ */
+
 export { BookmarksApiClient, default } from './client';
 export { ApiVersion } from './api-version';
 export * from './schemas';

package/src/bookmarks/schemas.ts

@@ -2,11 +2,13 @@ import { ApiVersion } from './api-version';
 
 import { z } from 'zod';
 
+/** Zod schema that parses an ISO-8601 datetime string into a `Date` object. */
 export const ApiDateSchema = z
   .string()
   .datetime({ offset: true })
   .transform((x) => new Date(x));
 
+/** Zod schema for a person reference in a bookmark response. */
 export const ApiPersonSchema = {
   [ApiVersion.v1]: z.object({
     azureUniqueId: z.string(),
@@ -19,6 +21,7 @@ export const ApiPersonSchema = {
   }),
 };
 
+/** Zod schema for the source system of a bookmark. */
 export const ApiSourceSystem = {
   [ApiVersion.v1]: z.object({
     identifier: z.string(),
@@ -27,6 +30,7 @@ export const ApiSourceSystem = {
   }),
 };
 
+/** Zod schema for a Fusion context reference attached to a bookmark. */
 export const ApiFusionContext = {
   [ApiVersion.v1]: z.object({
     id: z.string(),
@@ -61,6 +65,12 @@ export const ApiBookmarkSchema = {
   },
 };
 
+/**
+ * Zod schema for the bookmark payload.
+ *
+ * Accepts a record of key-value pairs, a JSON string, or `undefined`.
+ * JSON strings are automatically parsed into objects.
+ */
 export const ApiBookmarkPayload = {
   get [ApiVersion.v1]() {
     return z

package/src/bookmarks/types.ts

@@ -1,3 +1,9 @@
+/**
+ * Re-exported shared types scoped for the bookmarks service.
+ *
+ * @packageDocumentation
+ */
+
 import type {
   FilterAllowedApiVersions as FilterAllowApiVersionsBase,
   ExtractApiVersion as ExtractApiVersionBase,
@@ -7,9 +13,21 @@ import type { ApiVersion } from './api-version';
 
 export { ClientMethodType, ClientMethod, ApiClientArguments } from '../types';
 
+/**
+ * Union of allowed version keys and values for the bookmarks API.
+ *
+ * @template TAllowed - Subset of `ApiVersion` keys to include.
+ */
 export type FilterAllowedApiVersions<TAllowed extends string = keyof typeof ApiVersion> =
   FilterAllowApiVersionsBase<typeof ApiVersion, TAllowed>;
 
+/**
+ * Extracts the concrete version string from a key-or-value version identifier
+ * for the bookmarks API.
+ *
+ * @template TVersion - The version string to resolve.
+ * @template TAllowed - Constraint on allowed versions.
+ */
 export type ExtractApiVersion<
   TVersion extends string,
   TAllowed extends string = FilterAllowedApiVersions,

package/src/configurator.ts

@@ -1,8 +1,22 @@
 import type { ApiClientFactory } from './types';
 
+/**
+ * Configuration interface for the services module.
+ *
+ * Consumers can set `createClient` to override how HTTP clients are resolved
+ * for each backend service. When left `undefined`, the module automatically
+ * resolves clients through the HTTP module and service-discovery module.
+ */
 export interface IApiConfigurator {
-  /** Method for creating IHttpClients */
+  /** Optional factory for creating named HTTP clients. */
   createClient?: ApiClientFactory;
 }
 
+/**
+ * Default configurator for the services module.
+ *
+ * Implements {@link IApiConfigurator} with an initially empty configuration.
+ * The module initialization step populates `createClient` if it was not
+ * provided during configuration.
+ */
 export class ApiConfigurator implements IApiConfigurator {}

package/src/context/api-models.ts

@@ -1,5 +1,6 @@
 import { ApiVersion } from './static';
 
+/** Context entity returned by the v1 context API. */
 type ApiContextEntity_v1 = {
   id: string;
   externalId: string | null;
@@ -13,6 +14,7 @@ type ApiContextEntity_v1 = {
   updated: string | null;
 };
 
+/** Placeholder for the v2 context entity (not yet defined). */
 type ApiContextEntity_v2 = unknown;
 
 type ApiContextEntityTypes = {
@@ -20,18 +22,27 @@ type ApiContextEntityTypes = {
   [ApiVersion.v2]: ApiContextEntity_v2;
 };
 
+/**
+ * Version-aware context entity type.
+ *
+ * Resolves to the concrete entity shape for a given {@link ApiVersion}.
+ *
+ * @template T - An `ApiVersion` member (e.g. `ApiVersion.v1`).
+ */
 export type ApiContextEntity<T extends string = ApiVersion> = T extends ApiVersion
   ? ApiContextEntityTypes[T]
   : unknown;
 
 /** === types === */
 
+/** Context type metadata returned by the v1 context API. */
 type ApiContextType_v1 = {
   id: string;
   isChildType: boolean;
   parentTypeIds: string[] | null;
 };
 
+/** Placeholder for the v2 context type (not yet defined). */
 type ApiContextType_v2 = unknown;
 
 type ApiContextTypeTypes = {
@@ -39,4 +50,9 @@ type ApiContextTypeTypes = {
   [ApiVersion.v2]: ApiContextType_v2;
 };
 
+/**
+ * Version-aware context type metadata.
+ *
+ * @template T - An `ApiVersion` member.
+ */
 export type ApiContextType<T extends ApiVersion> = ApiContextTypeTypes[T];

package/src/context/client.ts

@@ -24,22 +24,40 @@ import {
   relatedContexts,
 } from './related';
 
+/**
+ * Typed API client for the Fusion context service.
+ *
+ * Delegates to versioned endpoint implementations for fetching a single context,
+ * querying contexts by search criteria, and listing related contexts.
+ *
+ * @template TMethod - The client execution method (`'json'` or `'json$'`).
+ * @template TClient - The underlying HTTP client type.
+ */
 export class ContextApiClient<
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
   TClient extends IHttpClient = IHttpClient,
 > {
+  /** Returns the {@link ApiVersion} enum for version-constant access. */
   get Version(): typeof ApiVersion {
     return ApiVersion;
   }
 
+  /**
+   * @param _client - The HTTP client used to execute requests.
+   * @param _method - The execution method (`'json'` or `'json$'`).
+   */
   constructor(
     protected _client: TClient,
     protected _method: TMethod,
   ) {}
 
   /**
-   * Fetch context by id
-   * @see {@link get/client}
+   * Fetch a single context entity by its identifier.
+   *
+   * @template TVersion - The API version key (e.g. `'v1'`).
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns The context entity matching the provided arguments.
    */
   public get<
     TVersion extends string = keyof typeof ApiVersion,
@@ -53,8 +71,12 @@ export class ContextApiClient<
   }
 
   /**
-   * Query context service
-   * @see {@link query/client}
+   * Query the context service with search criteria.
+   *
+   * @template TVersion - The API version key (e.g. `'v1'`).
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns An array of context entities matching the query.
    */
   public query<
     TVersion extends string = keyof typeof ApiVersion,
@@ -68,8 +90,12 @@ export class ContextApiClient<
   }
 
   /**
-   * Query context service
-   * @see {@link query/client}
+   * List contexts related to a specific context entity.
+   *
+   * @template TVersion - The API version key (e.g. `'v1'`).
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns An array of related context entities.
    */
   public related<
     TVersion extends string = keyof typeof ApiVersion,

package/src/context/get/client.ts

@@ -7,10 +7,15 @@ import { generateParameters } from './generate-parameters';
 import type { ClientMethod, GetContextArgs, GetContextResponse, GetContextResult } from './types';
 
 /**
- * Method for fetching context item from context service
- * @param client - client for execution of request
- * @param version - version of API to call
- * @param method - client method to call
+ * Creates a curried function that fetches a single context entity by ID.
+ *
+ * @template TVersion - The API version key (e.g. `'v1'`).
+ * @template TMethod - The client execution method (`'json'` or `'json$'`).
+ * @template TClient - The underlying HTTP client type.
+ * @param client - HTTP client used to execute the request.
+ * @param version - API version to call.
+ * @param method - Client method to use (defaults to `'json'`).
+ * @returns A function that accepts context args and returns the result.
  */
 export const getContext =
   <

package/src/context/get/types.ts

@@ -4,7 +4,9 @@ import { ApiVersion, type ApiContextEntity, type ClientMethod } from '..';
 
 export { ApiClientArguments, ClientMethod } from '..';
 
+/** Arguments for fetching a single context in API v1. */
 type GetContextArgs_v1 = {
+  /** The unique context identifier. */
   id: string;
 };
 
@@ -15,6 +17,11 @@ type GetContextArgsTypes = {
   [ApiVersion.v2]: GetContextArgs_v2;
 };
 
+/**
+ * Version-aware argument type for the get-context endpoint.
+ *
+ * @template T - API version key.
+ */
 export type GetContextArgs<T extends string> = T extends keyof typeof ApiVersion
   ? GetContextArgsTypes[(typeof ApiVersion)[T]]
   : unknown;
@@ -24,10 +31,23 @@ type GetContextResponseTypes = {
   [ApiVersion.v2]: ApiContextEntity<ApiVersion.v2>;
 };
 
+/**
+ * Version-aware response type for the get-context endpoint.
+ *
+ * @template T - API version key.
+ */
 export type GetContextResponse<T> = T extends keyof typeof ApiVersion
   ? GetContextResponseTypes[(typeof ApiVersion)[T]]
   : unknown;
 
+/**
+ * Function signature for the get-context endpoint.
+ *
+ * @template TVersion - API version key.
+ * @template TMethod - Client execution method.
+ * @template TClient - HTTP client type.
+ * @template TResult - Expected response type.
+ */
 export type GetContextFn<
   TVersion extends string = keyof typeof ApiVersion,
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
@@ -38,6 +58,13 @@ export type GetContextFn<
   init?: ClientRequestInit<TClient, TResult>,
 ) => GetContextResult<TVersion, TMethod, TResult>;
 
+/**
+ * Result type for the get-context endpoint, derived from `ClientMethod`.
+ *
+ * @template TVersion - API version key.
+ * @template TMethod - Client execution method.
+ * @template TResult - Expected response type.
+ */
 export type GetContextResult<
   TVersion extends string = keyof typeof ApiVersion,
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,

package/src/context/index.ts

@@ -1,3 +1,17 @@
+/**
+ * @packageDocumentation
+ *
+ * Context API client and types.
+ *
+ * Provides {@link ContextApiClient} for fetching, querying, and listing
+ * related contexts, with versioned endpoints (`v1`, `v2`).
+ *
+ * @example
+ * ```ts
+ * import { ContextApiClient } from '@equinor/fusion-framework-module-services/context';
+ * ```
+ */
+
 export { ContextApiClient, default } from './client';
 
 export { ApiVersion } from './static';

package/src/context/query/client.ts

@@ -12,7 +12,15 @@ import type {
 } from './types';
 
 /**
- * Function for querying the context service
+ * Creates a curried function that queries the context service.
+ *
+ * @template TVersion - The API version key.
+ * @template TMethod - The client execution method.
+ * @template TClient - The underlying HTTP client type.
+ * @param client - HTTP client used to execute the request.
+ * @param version - API version to call.
+ * @param method - Client method to use (defaults to `'json'`).
+ * @returns A function that accepts query args and returns context results.
  */
 export const queryContext =
   <