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

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

@@ -7,6 +7,12 @@ import type {
   ApiProjectMaster,
 } from './api-models';
 
+/**
+ * Map of expandable properties available on a v4 person entity.
+ *
+ * Use the `expand` parameter in API requests to include these
+ * nested collections alongside the core person data.
+ */
 export type ApiPersonExpandMap_v4 = {
   roles: Array<ApiPersonRole_v4>;
   positions: Array<ApiPersonPosition_v4>;
@@ -15,8 +21,18 @@ export type ApiPersonExpandMap_v4 = {
   companies: Array<ApiCompanyInfo_v4>;
 };
 
+/** Union of valid expand property keys for the v4 person entity. */
 export type ApiPersonExpandProps_v4 = keyof ApiPersonExpandMap_v4;
 
+/**
+ * Person entity returned by the v4 people API.
+ *
+ * Includes only the expanded properties specified by `TExpand`.
+ * Non-expanded properties from {@link ApiPersonExpandMap_v4} remain
+ * `Partial` (i.e. `undefined` at runtime).
+ *
+ * @template TExpand - Array of expand property keys to include.
+ */
 export type ApiPerson_v4<TExpand extends Array<ApiPersonExpandProps_v4> = []> = {
   azureUniqueId: string;
   mail?: string;
@@ -46,11 +62,13 @@ export type ApiPerson_v4<TExpand extends Array<ApiPersonExpandProps_v4> = []> =
     [K in TExpand[number]]: ApiPersonExpandMap_v4[K];
   };
 
+/** Company information associated with a v4 person entity. */
 export type ApiCompanyInfo_v4 = {
   id: string;
   name?: string;
 };
 
+/** Role assigned to a person in the v4 API. */
 export type ApiPersonRole_v4 = {
   name?: string;
   displayName?: string;
@@ -62,12 +80,14 @@ export type ApiPersonRole_v4 = {
   scopes?: Array<ApiPersonRoleScope_v4>;
 };
 
+/** Scope constraint on a person role. */
 export type ApiPersonRoleScope_v4 = {
   type?: string;
   values?: string[];
   valueType?: string;
 };
 
+/** Position instance held by a person in the v4 API. */
 export type ApiPersonPosition_v4 = {
   positionId: string;
   positionExternalId?: string;
@@ -83,6 +103,7 @@ export type ApiPersonPosition_v4 = {
   workload?: number;
 };
 
+/** Base position reference for a person position. */
 export type ApiPersonBasePosition_v4 = {
   id: string;
   name?: string;
@@ -90,6 +111,7 @@ export type ApiPersonBasePosition_v4 = {
   discipline?: string;
 };
 
+/** Project reference for a person position or contract. */
 export type ApiPersonProject_v4 = {
   id: string;
   name?: string;
@@ -97,6 +119,7 @@ export type ApiPersonProject_v4 = {
   type?: string;
 };
 
+/** Contract associated with a person in the v4 API. */
 export type ApiPersonContract_v4 = {
   id: string;
   name?: string;
@@ -108,6 +131,7 @@ export type ApiPersonContract_v4 = {
   positions: Array<ApiPersonPosition_v4>;
 };
 
+/** @deprecated Use {@link ApiCompanyInfo_v4} instead. */
 export type ApiCompanyInfoV4 = {
   id: string;
   name?: string;

package/src/people/client.ts

@@ -39,18 +39,39 @@ import {
   type ApiResult as PersonResolveResult,
 } from './resolve';
 
+/**
+ * Typed API client for the Fusion people service.
+ *
+ * Provides methods for fetching person details, querying persons,
+ * retrieving profile photos, getting suggestions, and resolving
+ * person identifiers.
+ *
+ * @template TClient - The underlying HTTP client type.
+ */
 export class PeopleApiClient<
   // 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 people requests. */
   constructor(protected _client: TClient) {}
 
   /**
-   * Fetch person by id
+   * Fetch detailed information about a person by their Azure unique ID.
+   *
+   * @template TVersion - The API version key (e.g. `'v4'`).
+   * @template TArgs - Request argument type.
+   * @template TResult - Expected response type.
+   * @template TMethod - Client execution method (`'json'` or `'json$'`).
+   * @param version - API version to use.
+   * @param method - Client execution method.
+   * @param args - Request arguments including `azureId`.
+   * @param init - Optional request init overrides.
+   * @returns The person details.
    */
   public get<
     TVersion extends PersonDetailSupportedApiVersion,
@@ -68,7 +89,17 @@ export class PeopleApiClient<
   }
 
   /**
-   * Query person service
+   * Search for persons matching query criteria.
+   *
+   * @template TVersion - The API version key (e.g. `'v2'`).
+   * @template TArgs - Request argument type.
+   * @template TResult - Expected response type.
+   * @template TMethod - Client execution method.
+   * @param version - API version to use.
+   * @param method - Client execution method.
+   * @param args - Request arguments including `search` string.
+   * @param init - Optional request init overrides.
+   * @returns An array of matching person entities.
    */
   public query<
     TVersion extends PersonQuerySupportedApiVersion,
@@ -86,7 +117,17 @@ export class PeopleApiClient<
   }
 
   /**
-   * Photo person service
+   * Fetch a person's profile photo as binary blob data.
+   *
+   * @template TVersion - The API version key (e.g. `'v2'`).
+   * @template TArgs - Request argument type.
+   * @template TResult - Expected response type.
+   * @template TMethod - Client execution method (`'blob'` or `'blob$'`).
+   * @param version - API version to use.
+   * @param method - Client execution method.
+   * @param args - Request arguments including `azureId`.
+   * @param init - Optional request init overrides.
+   * @returns The person's photo as a blob.
    */
   public photo<
     TVersion extends PersonPhotoSupportedApiVersion,
@@ -104,7 +145,13 @@ export class PeopleApiClient<
   }
 
   /**
-   * Suggest person service
+   * Fetch person suggestions (type-ahead / autocomplete).
+   *
+   * @template TResult - Expected response type.
+   * @template TMethod - Client execution method.
+   * @param method - Client execution method.
+   * @param init - Optional request init overrides.
+   * @returns Paginated suggestion results.
    */
   public suggest<
     TResult = PersonSuggestApiResponse,
@@ -118,7 +165,13 @@ export class PeopleApiClient<
   }
 
   /**
-   * Resolve person service
+   * Resolve person identifiers to account information.
+   *
+   * @template TResult - Expected response type.
+   * @template TMethod - Client execution method.
+   * @param method - Client execution method.
+   * @param init - Optional request init overrides.
+   * @returns Array of resolved person results.
    */
   public resolve<
     TResult = PersonResolveApiResponse,

package/src/people/index.ts

@@ -1,3 +1,17 @@
+/**
+ * @packageDocumentation
+ *
+ * People API client and types.
+ *
+ * Provides {@link PeopleApiClient} for person lookups, search, photo retrieval,
+ * suggestions, and identifier resolution, with versioned endpoints (`v2`, `v4`).
+ *
+ * @example
+ * ```ts
+ * import { PeopleApiClient } from '@equinor/fusion-framework-module-services/people';
+ * ```
+ */
+
 export { PeopleApiClient, default } from './client';
 
 export { ApiVersion } from './static';

package/src/people/person-details/client.ts

@@ -6,10 +6,16 @@ import type { ClientMethod } from '../../types';
 import type { ApiResponse, ApiResult, ApiRequestArgs, SupportedApiVersion } 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 detailed person information.
+ *
+ * @template TVersion - Supported API version (e.g. `'v4'`).
+ * @template TMethod - Client execution method (`'json'` or `'json$'`).
+ * @template TClient - The underlying HTTP client type.
+ * @template TArgs - Request argument 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 person detail args and returns the result.
  */
 export const client =
   <

package/src/people/person-details/types.ts

@@ -2,6 +2,7 @@ import { ApiVersion } from '../static';
 import type { ApiPerson_v4, ApiPersonExpandProps_v4 } from '../api-models.v4';
 import type { ClientMethod } from '../../types';
 
+/** API versions that support the person-details endpoint. */
 export type SupportedApiVersion = Extract<keyof typeof ApiVersion, 'v4'>;
 
 type ApiRequestArgsMap = {
@@ -11,8 +12,14 @@ type ApiRequestArgsMap = {
   };
 };
 
+/** Union of all valid request argument shapes across supported versions. */
 export type AllowedArgs = ApiRequestArgsMap[keyof ApiRequestArgsMap];
 
+/**
+ * Version-aware request argument type for the person-details endpoint.
+ *
+ * @template T - Supported API version key.
+ */
 export type ApiRequestArgs<T extends SupportedApiVersion> =
   ApiRequestArgsMap[(typeof ApiVersion)[T]];
 
@@ -20,11 +27,25 @@ type ApiResponseTypes<TArgs extends AllowedArgs> = {
   [ApiVersion.v4]: ApiPerson_v4<TArgs['expand'] extends [] ? TArgs['expand'] : []>;
 };
 
+/**
+ * Version-aware response type for the person-details endpoint.
+ *
+ * @template T - Supported API version key.
+ * @template TArgs - Request argument type.
+ */
 export type ApiResponse<
   T extends SupportedApiVersion,
   TArgs extends AllowedArgs,
 > = ApiResponseTypes<TArgs>[(typeof ApiVersion)[T]];
 
+/**
+ * Result type for the person-details endpoint.
+ *
+ * @template TVersion - Supported API version key.
+ * @template TArgs - Request argument type.
+ * @template TMethod - Client execution method.
+ * @template TResult - Expected response type.
+ */
 export type ApiResult<
   TVersion extends SupportedApiVersion,
   TArgs extends ApiRequestArgs<TVersion>,

package/src/people/person-photo/client.ts

@@ -6,10 +6,16 @@ import type { ClientDataMethod } from '../../types';
 import type { ApiResponse, ApiRequestArgs, SupportedApiVersion } 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 person's profile photo.
+ *
+ * @template TVersion - Supported API version (e.g. `'v2'`).
+ * @template TMethod - Client execution method (`'blob'` or `'blob$'`).
+ * @template TClient - The underlying HTTP client type.
+ * @template TArgs - Request argument type.
+ * @param client - HTTP client used to execute the request.
+ * @param version - API version to call.
+ * @param method - Client method to use (defaults to `'blob'`).
+ * @returns A function that accepts photo args and returns blob data.
  */
 export const client =
   <

package/src/people/person-photo/types.ts

@@ -2,6 +2,7 @@ import type { BlobResult } from '@equinor/fusion-framework-module-http/client';
 import { ApiVersion } from '../static';
 import type { ClientDataMethod } from '../../types';
 
+/** API versions that support the person photo endpoint. */
 export type SupportedApiVersion = Extract<keyof typeof ApiVersion, 'v2'>;
 
 type ApiRequestArgsMap = {
@@ -10,8 +11,14 @@ type ApiRequestArgsMap = {
   };
 };
 
+/** Union of all valid request argument shapes across supported versions. */
 export type AllowedArgs = ApiRequestArgsMap[keyof ApiRequestArgsMap];
 
+/**
+ * Version-aware request argument type for the person photo endpoint.
+ *
+ * @template T - Supported API version key.
+ */
 export type ApiRequestArgs<T extends SupportedApiVersion> =
   ApiRequestArgsMap[(typeof ApiVersion)[T]];
 
@@ -19,7 +26,17 @@ type ApiResponseTypes = {
   [ApiVersion.v2]: BlobResult;
 };
 
+/**
+ * Version-aware response type for the person photo endpoint.
+ *
+ * @template T - Supported API version key.
+ */
 export type ApiResponse<T extends SupportedApiVersion> = ApiResponseTypes[(typeof ApiVersion)[T]];
 
+/**
+ * Result type for the person photo endpoint.
+ *
+ * @template TMethod - Client execution method (`'blob'` or `'blob$'`).
+ */
 export type ApiResult<TMethod extends keyof ClientDataMethod = keyof ClientDataMethod> =
   ClientDataMethod[TMethod];

package/src/people/query/client.ts

@@ -6,10 +6,16 @@ import type { ClientMethod } from '../../types';
 import type { ApiResponse, ApiResult, ApiRequestArgs, SupportedApiVersion } 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 queries the people service.
+ *
+ * @template TVersion - Supported API version (e.g. `'v2'`).
+ * @template TMethod - Client execution method.
+ * @template TClient - The underlying HTTP client type.
+ * @template TArgs - Request argument 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 person results.
  */
 export const client =
   <

package/src/people/query/types.ts

@@ -2,6 +2,7 @@ import { ApiVersion } from '../static';
 import type { ApiPerson_v2 } from '../api-models.v2';
 import type { ClientMethod } from '../../types';
 
+/** API versions that support the people query endpoint. */
 export type SupportedApiVersion = Extract<keyof typeof ApiVersion, 'v2'>;
 
 type ApiRequestArgsMap = {
@@ -10,8 +11,14 @@ type ApiRequestArgsMap = {
   };
 };
 
+/** Union of all valid request argument shapes across supported versions. */
 export type AllowedArgs = ApiRequestArgsMap[keyof ApiRequestArgsMap];
 
+/**
+ * Version-aware request argument type for the people query endpoint.
+ *
+ * @template T - Supported API version key.
+ */
 export type ApiRequestArgs<T extends SupportedApiVersion> =
   ApiRequestArgsMap[(typeof ApiVersion)[T]];
 
@@ -19,8 +26,20 @@ type ApiResponseTypes = {
   [ApiVersion.v2]: Array<ApiPerson_v2>;
 };
 
+/**
+ * Version-aware response type for the people query endpoint.
+ *
+ * @template T - Supported API version key.
+ */
 export type ApiResponse<T extends SupportedApiVersion> = ApiResponseTypes[(typeof ApiVersion)[T]];
 
+/**
+ * Result type for the people query endpoint.
+ *
+ * @template TVersion - Supported API version key.
+ * @template TMethod - Client execution method.
+ * @template TResult - Expected response type.
+ */
 export type ApiResult<
   TVersion extends SupportedApiVersion,
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,

package/src/people/resolve/types.ts

@@ -1,8 +1,15 @@
 import type { ApiResolved } from '../api-models';
 import type { ClientMethod } from '../../types';
 
+/** Response type for the people resolve endpoint. */
 export type ApiResponse = ApiResolved;
 
+/**
+ * Result type for the people resolve endpoint.
+ *
+ * @template TMethod - Client execution method.
+ * @template TResult - Expected response type.
+ */
 export type ApiResult<
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
   TResult = ApiResponse,

package/src/people/static.ts

@@ -1,4 +1,7 @@
+/** Supported API versions for the people service. */
 export enum ApiVersion {
+  /** People API version 2.0. */
   v2 = '2.0',
+  /** People API version 4.0. */
   v4 = '4.0',
 }

package/src/people/suggest/types.ts

@@ -1,8 +1,15 @@
 import type { ApiSuggestions } from '../api-models';
 import type { ClientMethod } from '../../types';
 
+/** Response type for the people suggest endpoint. */
 export type ApiResponse = ApiSuggestions;
 
+/**
+ * Result type for the people suggest endpoint.
+ *
+ * @template TMethod - Client execution method.
+ * @template TResult - Expected response type.
+ */
 export type ApiResult<
   TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
   TResult = ApiResponse,

package/src/people/utils.ts

@@ -14,6 +14,25 @@ const requiredApiPersonAttributes = {
   ] satisfies Array<keyof ApiPerson<'v4'>>,
 };
 
+/**
+ * Creates a type-guard function that validates whether a value conforms
+ * to the {@link ApiPerson} shape for a given API version.
+ *
+ * The guard checks that the value contains all required attributes
+ * defined for the specified version.
+ *
+ * @template V - API version key (e.g. `'v2'` or `'v4'`).
+ * @param version - The API version to validate against.
+ * @returns A type-guard function that narrows `T` to `ApiPerson<V>`.
+ *
+ * @example
+ * ```ts
+ * const isV4Person = isApiPerson('v4');
+ * if (isV4Person(data)) {
+ *   console.log(data.azureUniqueId);
+ * }
+ * ```
+ */
 export const isApiPerson = <V extends keyof typeof ApiVersion>(version: V) => {
   /** todo add options for more strict check */
   return <T>(value: T): value is T extends ApiPerson<V> ? T : never => {

package/src/provider.ts

@@ -10,38 +10,69 @@ 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>>;
 }
 
+/**
+ * Constructor arguments for {@link ApiProvider}.
+ *
+ * @template TClient - The underlying HTTP client type.
+ */
 type ApiProviderCtorArgs<TClient extends IHttpClient = IHttpClient> = {
-  /** method for creating IHttpClients for api clients */
+  /** Factory function for creating named HTTP clients used by API sub-clients. */
   createClient: ApiClientFactory<TClient>;
 };
 
-// TODO move to own file
+/**
+ * Shape of the structured error response attached to an {@link ApiProviderError}.
+ */
 type ApiProviderErrorResponse = {
   type: ResponseType;
   status: number;
@@ -51,10 +82,32 @@ type ApiProviderErrorResponse = {
   data: unknown;
 };
 
-// TODO move to own file
+/**
+ * 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 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) {
     super(msg, options);
     this.response = response;
@@ -62,7 +115,10 @@ export class ApiProviderError extends Error {
   }
 }
 
-// TODO move to own file
+/**
+ * Validates that an HTTP response has an OK status.
+ * Throws an {@link ApiProviderError} with parsed body data when the response is not OK.
+ */
 const validateResponse = async (response: Response) => {
   if (!response.ok) {
     const { headers, status, statusText, type, url, bodyUsed } = response;
@@ -79,10 +135,25 @@ const validateResponse = async (response: Response) => {
   }
 };
 
+/**
+ * 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 class ApiProvider<TClient extends IHttpClient = IHttpClient>
   extends BaseModuleProvider<ApiProviderConfig<TClient>>
   implements IApiProvider<TClient>