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

package/src/context/query/types.ts

@@ -4,11 +4,21 @@ import { ApiVersion, type ApiContextEntity, type ClientMethod } from '..';
 
 export { ApiClientArguments, ClientMethod } from '..';
 
+/**
+ * OData filter parameters for context queries.
+ *
+ * Used to narrow results by context type or external identifier.
+ */
 export type QueryContextOdataFilter = {
   type?: string[];
   externalId?: string;
 };
 
+/**
+ * Structured OData query parameters for context search.
+ *
+ * Allows combining free-text search with type or external-ID filters.
+ */
 export type QueryContextOdataParameters = {
   search?: string;
   filter?: QueryContextOdataFilter;
@@ -26,6 +36,11 @@ type SearchContextArgTypes = {
   [ApiVersion.v2]: QueryContextArgs_v2;
 };
 
+/**
+ * Version-aware argument type for the context query endpoint.
+ *
+ * @template T - API version key.
+ */
 export type QueryContextArgs<T> = T extends keyof typeof ApiVersion
   ? SearchContextArgTypes[(typeof ApiVersion)[T]]
   : { query: { search: string } };
@@ -35,10 +50,23 @@ type QueryContextResponseTypes = {
   [ApiVersion.v2]: Array<ApiContextEntity<ApiVersion.v2>>;
 };
 
+/**
+ * Version-aware response type for the context query endpoint.
+ *
+ * @template T - API version key.
+ */
 export type QueryContextResponse<T> = T extends keyof typeof ApiVersion
   ? QueryContextResponseTypes[(typeof ApiVersion)[T]]
   : unknown;
 
+/**
+ * Function signature for the context query endpoint.
+ *
+ * @template TVersion - API version key.
+ * @template TMethod - Client execution method.
+ * @template TClient - HTTP client type.
+ * @template TResult - Expected response type.
+ */
 export type QueryContextFn<
   TVersion extends string = keyof typeof ApiVersion,
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
@@ -49,6 +77,13 @@ export type QueryContextFn<
   init?: ClientRequestInit<TClient, TResult>,
 ) => QueryContextResult<TVersion, TMethod, TResult>;
 
+/**
+ * Result type for the context query endpoint.
+ *
+ * @template TVersion - API version key.
+ * @template TMethod - Client execution method.
+ * @template TResult - Expected response type.
+ */
 export type QueryContextResult<
   TVersion extends string = keyof typeof ApiVersion,
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,

package/src/context/related/client.ts

@@ -12,7 +12,15 @@ import type {
 } from './types';
 
 /**
- * Function for querying the context service
+ * Creates a curried function that fetches contexts related to a given context.
+ *
+ * @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 relation args and returns related contexts.
  */
 export const relatedContexts =
   <

package/src/context/related/types.ts

@@ -4,15 +4,26 @@ import { ApiVersion, type ApiContextEntity, type ClientMethod } from '..';
 
 export { ApiClientArguments, ClientMethod } from '..';
 
+/**
+ * Extended context entity that includes relationship metadata.
+ *
+ * @template T - An {@link ApiVersion} member.
+ */
 export type ApiRelatedContextEntity<T extends ApiVersion> = ApiContextEntity<T> & {
   relationSource: string; // "ProjectMaster|OrgChart",
   relationType: unknown;
 };
 
+/**
+ * OData filter for narrowing related-context results by type.
+ */
 export type RelatedContextOdataFilter = {
   type?: string[];
 };
 
+/**
+ * Structured OData query parameters for related-context lookups.
+ */
 export type RelatedContextOdataParameters = {
   search?: string;
   filter?: RelatedContextOdataFilter;
@@ -31,6 +42,11 @@ type RelatedContextArgTypes = {
   [ApiVersion.v2]: RelatedContextArgs_v2;
 };
 
+/**
+ * Version-aware argument type for the related-contexts endpoint.
+ *
+ * @template T - API version key.
+ */
 export type RelatedContextArgs<T> = T extends keyof typeof ApiVersion
   ? RelatedContextArgTypes[(typeof ApiVersion)[T]]
   : { id: string };
@@ -40,10 +56,23 @@ type RelatedContextResponseTypes = {
   [ApiVersion.v2]: Array<ApiRelatedContextEntity<ApiVersion.v2>>;
 };
 
+/**
+ * Version-aware response type for the related-contexts endpoint.
+ *
+ * @template T - API version key.
+ */
 export type RelatedContextResponse<T> = T extends keyof typeof ApiVersion
   ? RelatedContextResponseTypes[(typeof ApiVersion)[T]]
   : unknown;
 
+/**
+ * Function signature for the related-contexts endpoint.
+ *
+ * @template TVersion - API version key.
+ * @template TMethod - Client execution method.
+ * @template TClient - HTTP client type.
+ * @template TResult - Expected response type.
+ */
 export type RelatedContextFn<
   TVersion extends string = keyof typeof ApiVersion,
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
@@ -54,6 +83,13 @@ export type RelatedContextFn<
   init?: ClientRequestInit<TClient, TResult>,
 ) => RelatedContextResult<TVersion, TMethod, TResult>;
 
+/**
+ * Result type for the related-contexts endpoint.
+ *
+ * @template TVersion - API version key.
+ * @template TMethod - Client execution method.
+ * @template TResult - Expected response type.
+ */
 export type RelatedContextResult<
   TVersion extends string = keyof typeof ApiVersion,
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,

package/src/context/static.ts

@@ -1,6 +1,7 @@
-/** index of api versions of context service */
+/** Supported API versions for the context service. */
 export enum ApiVersion {
+  /** Context API version 1.0. */
   v1 = '1.0',
-  /** not in use atm */
+  /** Context API version 2.0 (not currently in use). */
   v2 = '2.0',
 }

package/src/errors.ts

@@ -1,4 +1,18 @@
+/**
+ * Error thrown when an API endpoint is called with a version string
+ * that does not match any supported API version.
+ *
+ * @example
+ * ```ts
+ * throw new UnsupportedApiVersion('3.0');
+ * // Error: unsupported version 3.0
+ * ```
+ */
 export class UnsupportedApiVersion extends Error {
+  /**
+   * @param version - The unsupported version value that was requested.
+   * @param cause - Optional underlying error or context.
+   */
   constructor(
     public readonly version: string | number,
     cause?: unknown,

package/src/index.ts

@@ -1,3 +1,18 @@
+/**
+ * @packageDocumentation
+ *
+ * Typed API service clients for the Fusion Framework.\
+ * Provides factory-based access to bookmarks, context, notification, and
+ * people APIs with versioned endpoints, response validation, and support
+ * for both promise (`json`) and observable (`json$`) consumption patterns.
+ *
+ * @example
+ * ```ts
+ * import { enableServices } from '@equinor/fusion-framework-module-services';
+ * configurator.addConfig(enableServices);
+ * ```
+ */
+
 export * from './types';
 export type { ServicesModule, ServicesModuleKey } from './module';
 

package/src/module.ts

@@ -14,10 +14,19 @@ import { type IApiProvider, ApiProvider } from './provider';
 
 import type { ApiClientFactory } from './types';
 
+/** String literal type for the services module registration key. */
 export type ServicesModuleKey = 'services';
 
+/** Module registration key used to identify the services module. */
 export const moduleKey: ServicesModuleKey = 'services';
 
+/**
+ * Module definition for the services module.
+ *
+ * Declares the module key, provider type ({@link IApiProvider}),
+ * configurator type ({@link IApiConfigurator}), and required
+ * dependency modules (HTTP and service-discovery).
+ */
 export type ServicesModule = Module<
   ServicesModuleKey,
   IApiProvider,
@@ -26,7 +35,12 @@ export type ServicesModule = Module<
 >;
 
 /**
- * Method to trying to resolve method for creating an IHttpClient
+ * Creates the default {@link ApiClientFactory} by attempting named HTTP clients
+ * first, then falling back to service-discovery.
+ *
+ * @param http - The HTTP client provider from the `http` module.
+ * @param serviceDiscovery - Optional service-discovery provider for automatic client resolution.
+ * @returns A factory function that creates named HTTP clients.
  */
 const createDefaultClient =
   (http: IHttpClientProvider, serviceDiscovery?: ServiceDiscoveryProvider): ApiClientFactory =>
@@ -41,7 +55,11 @@ const createDefaultClient =
   };
 
 /**
- *  Configure http-client
+ * Services module definition.
+ *
+ * Registers the `'services'` module, wires up the {@link ApiConfigurator},
+ * and initializes the {@link ApiProvider} with an HTTP client factory
+ * resolved from the `http` and optional `serviceDiscovery` modules.
  */
 export const module: ServicesModule = {
   name: moduleKey,
@@ -66,8 +84,18 @@ export const module: ServicesModule = {
 };
 
 /**
- * Method for enabling the Service module
- * @param config - configuration object
+ * Registers the services module with the framework configurator.
+ *
+ * Call this during app configuration to make the services module
+ * available at runtime.
+ *
+ * @param config - The framework modules configurator.
+ *
+ * @example
+ * ```ts
+ * import { enableServices } from '@equinor/fusion-framework-module-services';
+ * configurator.addConfig(enableServices);
+ * ```
  */
 export const enableServices = (
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -77,12 +105,24 @@ export const enableServices = (
 };
 
 /**
+ * Creates a module configuration object for the services module
+ * with a custom configuration callback.
+ *
+ * Use this when you need to customise the services module (for example,
+ * supplying a custom `createClient` factory).
+ *
+ * @param configure - Callback that receives the {@link IApiConfigurator} for customisation.
+ * @returns A module configurator object that can be passed to `addConfig`.
+ *
  * @example
  * ```ts
- * config.addConfig(x => x.createClient(...));
+ * import { configureServices } from '@equinor/fusion-framework-module-services';
+ * configurator.addConfig(
+ *   configureServices((cfg) => {
+ *     cfg.createClient = myCustomClientFactory;
+ *   }),
+ * );
  * ```
- * @param configure - Callback for configuring the module
- * @returns Configuration object
  */
 export const configureServices = (
   configure: (configurator: IApiConfigurator) => void,

package/src/notification/api-models.ts

@@ -1,5 +1,6 @@
 import { ApiVersion } from './static';
 
+/** Notification entity returned by the v1 notification API. */
 type ApiNotificationEntity_v1 = {
   id: string;
   appKey: string;
@@ -16,17 +17,20 @@ type ApiNotificationEntity_v1 = {
   sourceSystem: SourceSystem_v1;
 };
 
+/** Source system metadata for a notification. */
 type SourceSystem_v1 = {
   name: string;
   subSystem: string;
   identifier: string;
 };
 
+/** Application that created the notification. */
 type CreatedByApplication_v1 = {
   id: string;
   title: string;
 };
 
+/** Person who created the notification. */
 type CreatedBy_v1 = {
   id: string;
   name: string;
@@ -35,6 +39,7 @@ type CreatedBy_v1 = {
   accountType: string;
 };
 
+/** Placeholder for the v2 notification entity (not yet defined). */
 type ApiNotificationEntity_v2 = unknown;
 
 type ApiNotificationEntityTypes = {
@@ -42,22 +47,31 @@ type ApiNotificationEntityTypes = {
   [ApiVersion.v2]: ApiNotificationEntity_v2;
 };
 
+/**
+ * Version-aware notification entity type.
+ *
+ * Resolves to the concrete entity shape for a given {@link ApiVersion}.
+ *
+ * @template T - An `ApiVersion` member string.
+ */
 export type ApiNotificationEntity<T extends string = ApiVersion> = T extends ApiVersion
   ? ApiNotificationEntityTypes[T]
   : unknown;
 
-/**User notification Settings */
+/** User notification settings entity for API v1. */
 type ApiNotificationSettingsEntity_v1 = {
   email: boolean;
   delayInMinutes: number;
   appConfig: AppConfig_v1[];
 };
 
+/** Per-application notification toggle within user settings. */
 type AppConfig_v1 = {
   appKey: string;
   enabled: boolean;
 };
 
+/** Placeholder for the v2 notification settings entity (not yet defined). */
 type ApiNotificationSettingsEntity_v2 = unknown;
 
 type ApiNotificationSettingEntityTypes = {
@@ -65,6 +79,11 @@ type ApiNotificationSettingEntityTypes = {
   [ApiVersion.v2]: ApiNotificationSettingsEntity_v2;
 };
 
+/**
+ * Version-aware notification settings entity type.
+ *
+ * @template T - An `ApiVersion` member string.
+ */
 export type ApiNotificationSettingsEntity<T extends string = ApiVersion> = T extends ApiVersion
   ? ApiNotificationSettingEntityTypes[T]
   : unknown;

package/src/notification/client.ts

@@ -22,22 +22,40 @@ import getUserNotificationSettings, {
   type GetUserNotificationsSettingsResult,
 } from './settings/get';
 
+/**
+ * Typed API client for the Fusion notification service.
+ *
+ * Provides methods for notification CRUD operations, marking notifications
+ * as seen, and managing user notification settings.
+ *
+ * @template TMethod - The client execution method (`'json'` or `'json$'`).
+ * @template TClient - The underlying HTTP client type.
+ */
 export class NotificationApiClient<
   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 all notifications
-   * @see {@link getAll/client}
+   * Fetch all notifications for the current user.
+   *
+   * @template TVersion - The API version key.
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns All notifications matching the query.
    */
   public getAll<
     TVersion extends string = keyof typeof ApiVersion,
@@ -51,8 +69,12 @@ export class NotificationApiClient<
   }
 
   /**
-   * Fetch notification by id
-   * @see {@link getById/client}
+   * Fetch a single notification by its identifier.
+   *
+   * @template TVersion - The API version key.
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns The notification with the specified ID.
    */
   public getById<
     TVersion extends string = keyof typeof ApiVersion,
@@ -66,8 +88,12 @@ export class NotificationApiClient<
   }
 
   /**
-   * Set notification seen by user
-   * @see {@link setSeenByUser/client}
+   * Mark a notification as seen by the current user.
+   *
+   * @template TVersion - The API version key.
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns The updated notification.
    */
   public setSeenByUser<
     TVersion extends string = keyof typeof ApiVersion,
@@ -81,8 +107,12 @@ export class NotificationApiClient<
   }
 
   /**
-   * Create a notification
-   * @see {@link create/client}
+   * Create a new notification.
+   *
+   * @template TVersion - The API version key.
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns The created notification.
    */
   public create<
     TVersion extends string = keyof typeof ApiVersion,
@@ -96,8 +126,12 @@ export class NotificationApiClient<
   }
 
   /**
-   * Delete a notification
-   * @see {@link delete/client}
+   * Delete a notification by its identifier.
+   *
+   * @template TVersion - The API version key.
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns The deletion result.
    */
   public delete<
     TVersion extends string = keyof typeof ApiVersion,
@@ -110,8 +144,12 @@ export class NotificationApiClient<
     return fn<TResult>(...args);
   }
   /**
-   * Get users notification settings
-   * @see {@link getSettings/client}
+   * Retrieve the current user's notification settings.
+   *
+   * @template TVersion - The API version key.
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns The user's notification settings.
    */
   public getSettings<
     TVersion extends string = keyof typeof ApiVersion,
@@ -128,8 +166,12 @@ export class NotificationApiClient<
     return fn<TResult>(...args);
   }
   /**
-   * Update user notification settings
-   * @see {@link updateSettings/client}
+   * Update the current user's notification settings.
+   *
+   * @template TVersion - The API version key.
+   * @template TResult - The expected response type.
+   * @param version - API version to use.
+   * @returns The updated notification settings.
    */
   public updateSettings<
     TVersion extends string = keyof typeof ApiVersion,

package/src/notification/index.ts

@@ -1,3 +1,18 @@
+/**
+ * @packageDocumentation
+ *
+ * Notification API client and types.
+ *
+ * Provides {@link NotificationApiClient} for creating, fetching, deleting
+ * notifications, marking them as seen, and managing user notification
+ * settings, with versioned endpoints (`v1`, `v2`).
+ *
+ * @example
+ * ```ts
+ * import { NotificationApiClient } from '@equinor/fusion-framework-module-services/notification';
+ * ```
+ */
+
 export { NotificationApiClient, default } from './client';
 
 export { ApiVersion } from './static';

package/src/notification/static.ts

@@ -1,6 +1,7 @@
-/** index of api versions of context service */
+/** Supported API versions for the notification service. */
 export enum ApiVersion {
+  /** Notification API version 1.0. */
   v1 = '1.0',
-  /** not in use atm */
+  /** Notification API version 2.0 (not currently in use). */
   v2 = '2.0',
 }

package/src/people/api-models.ts

@@ -2,11 +2,13 @@ import type { ApiPerson_v2 } from './api-models.v2';
 import type { ApiPerson_v4 } from './api-models.v4';
 import { ApiVersion } from './static';
 
+/** Project master reference attached to a person's contract. */
 export type ApiProjectMaster = {
   id: string;
   name?: string;
 };
 
+/** Manager information with contact details and classification. */
 export type ApiManager = {
   azureUniqueId: string;
   name?: string;
@@ -19,8 +21,10 @@ export type ApiManager = {
   accountClassification: ApiAccountClassification;
 };
 
+/** Invitation status for a person's account. */
 export type ApiInvitationStatus = 'Accepted' | 'Pending' | 'NotSent';
 
+/** Account type classification for a person profile. */
 export type ApiProfileAccountType =
   | 'Employee'
   | 'Consultant'
@@ -28,9 +32,10 @@ export type ApiProfileAccountType =
   | 'External'
   | 'External Hire';
 
-// TODO what are these?
+/** Account classification tier for access control. */
 export type ApiAccountClassification = 'Unclassified' | 'Internal' | 'External';
 
+/** Linked account reference for a person profile. */
 export type ApiProfileAccountLink = {
   azureUniqueId: string;
   mail?: string;
@@ -40,17 +45,32 @@ export type ApiProfileAccountLink = {
   upn?: string;
 };
 
+/**
+ * Map from API version to the corresponding person entity type.
+ *
+ * @see {@link ApiPerson_v2}
+ * @see {@link ApiPerson_v4}
+ */
 export type ApiPersonMap = {
   [ApiVersion.v2]: ApiPerson_v2;
   [ApiVersion.v4]: ApiPerson_v4;
 };
 
+/**
+ * Version-aware person entity type.
+ *
+ * Resolves to the concrete person shape for a given {@link ApiVersion}
+ * key or value.
+ *
+ * @template T - An `ApiVersion` key or value.
+ */
 export type ApiPerson<T extends keyof typeof ApiVersion | ApiVersion> = T extends ApiVersion
   ? ApiPersonMap[T]
   : T extends keyof typeof ApiVersion
     ? ApiPersonMap[(typeof ApiVersion)[T]]
     : unknown;
 
+/** Person suggestion result with account type and department detail. */
 export type ApiSuggestionPerson = {
   accountType?:
     | 'Unknown'
@@ -73,12 +93,14 @@ export type ApiSuggestionPerson = {
   mobilePhone?: string;
 };
 
+/** Application entity in a person suggestion result. */
 export type ApiSuggestionApplication = {
   applicationId: string;
   applicationName?: string;
   servicePrincipalType: 'Application' | 'ManagedIdentity' | 'ServicePrincipal';
 };
 
+/** Single suggestion value representing a person or system account. */
 export type ApiSuggestionValue = {
   azureUniqueId: string;
   name?: string;
@@ -91,6 +113,7 @@ export type ApiSuggestionValue = {
   isExpired: boolean;
 };
 
+/** Paginated suggestion response from the people suggest endpoint. */
 export type ApiSuggestions = {
   totalCount: number;
   count: number;
@@ -98,6 +121,7 @@ export type ApiSuggestions = {
   value: Array<ApiSuggestionValue>;
 };
 
+/** Single resolved item from the people resolve endpoint. */
 export type ApiResolveItem = {
   success: boolean;
   statusCode: number;
@@ -106,4 +130,5 @@ export type ApiResolveItem = {
   account: ApiSuggestionValue | null;
 };
 
+/** Array of resolved person lookup results. */
 export type ApiResolved = Array<ApiResolveItem>;

package/src/people/api-models.v2.ts

@@ -5,6 +5,7 @@ import type {
   ApiProfileAccountType,
 } from './api-models';
 
+/** Person entity returned by the v2 people API. */
 export type ApiPerson_v2 = {
   fusionPersonId?: string;
   azureUniqueId: string;