@equinor/fusion-framework-module-app 8.0.2 → 8.0.3

package/dist/types/errors.d.ts

@@ -1,103 +1,6 @@
-/**
- * Discriminant for application-related errors.
- *
- * - `'not_found'` – The requested resource does not exist (HTTP 404).
- * - `'unauthorized'` – The request lacks valid credentials (HTTP 401).
- * - `'deleted'` – The resource has been removed (HTTP 410).
- * - `'unknown'` – An unexpected failure occurred.
- */
-type AppErrorType = 'not_found' | 'unauthorized' | 'unknown' | 'deleted';
-/**
- * Represents an error that occurs when loading an application manifest.
- */
-export declare class AppManifestError extends Error {
-    readonly type: AppErrorType;
-    /**
-     * Creates an instance of AppManifestError based on the HTTP response status.
-     * @param response The HTTP response.
-     * @param options Optional error options.
-     * @returns An instance of AppManifestError.
-     */
-    static fromHttpResponse(response: Response, options?: ErrorOptions): AppManifestError;
-    /**
-     * Creates an instance of AppManifestError.
-     * @param type The type of the error.
-     * @param message The error message.
-     * @param options Optional error options.
-     */
-    constructor(type: AppErrorType, message?: string, options?: ErrorOptions);
-}
-/**
- * Represents an error that occurs in the application configuration.
- */
-export declare class AppConfigError extends Error {
-    readonly type: AppErrorType;
-    /**
-     * Creates an instance of `AppConfigError` based on the HTTP response status.
-     * @param response The HTTP response.
-     * @param options Additional error options.
-     * @returns An instance of `AppConfigError` based on the HTTP response status.
-     */
-    static fromHttpResponse(response: Response, options?: ErrorOptions): AppConfigError;
-    /**
-     * Creates an instance of `AppConfigError`.
-     * @param type The type of the application error.
-     * @param message The error message.
-     * @param options Additional error options.
-     */
-    constructor(type: AppErrorType, message?: string, options?: ErrorOptions);
-}
-/**
- * Represents an error that occurs in the application build.
- */
-export declare class AppBuildError extends Error {
-    readonly type: AppErrorType;
-    /**
-     * Creates an instance of `AppBuildError` based on the HTTP response status.
-     * @param response The HTTP response.
-     * @param options Additional error options.
-     * @returns An instance of `AppBuildError` based on the HTTP response status.
-     */
-    static fromHttpResponse(response: Response, options?: ErrorOptions): AppBuildError;
-    /**
-     * Creates an instance of `AppBuildError`.
-     * @param type The type of the application error.
-     * @param message The error message.
-     * @param options Additional error options.
-     */
-    constructor(type: AppErrorType, message?: string, options?: ErrorOptions);
-}
-/**
- * Represents an error that occurs while fetching application settings.
- */
-export declare class AppSettingsError extends Error {
-    readonly type: AppErrorType;
-    /**
-     * Creates an instance of `AppSettingsError` based on the HTTP response status.
-     * @param response The HTTP response.
-     * @param options Additional error options.
-     * @returns An instance of `AppSettingsError` based on the HTTP response status.
-     */
-    static fromHttpResponse(response: Response, options?: ErrorOptions): AppSettingsError;
-    /**
-     * Creates an instance of `AppSettingsError`.
-     * @param type The type of the application error.
-     * @param message The error message.
-     * @param options Additional error options.
-     */
-    constructor(type: AppErrorType, message?: string, options?: ErrorOptions);
-}
-/**
- * Represents an error that occurs when loading the application script.
- */
-export declare class AppScriptModuleError extends Error {
-    readonly type: AppErrorType;
-    /**
-     * Creates a new instance of the AppScriptModuleError class.
-     * @param type The type of the error.
-     * @param message The error message.
-     * @param options Additional options for the error.
-     */
-    constructor(type: AppErrorType, message?: string, options?: ErrorOptions);
-}
-export {};
+export { AppManifestError } from './errors/AppManifestError';
+export { AppConfigError } from './errors/AppConfigError';
+export { AppBuildError } from './errors/AppBuildError';
+export { AppSettingsError } from './errors/AppSettingsError';
+export { AppScriptModuleError } from './errors/AppScriptModuleError';
+export type { AppErrorType } from './errors/app-error-type';

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "8.0.2";
+export declare const version = "8.0.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-app",
-  "version": "8.0.2",
+  "version": "8.0.3",
   "description": "",
   "main": "dist/esm/index.js",
   "exports": {
@@ -61,16 +61,16 @@
     "rxjs": "^7.8.1",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@equinor/fusion-query": "^7.0.1",
-    "@equinor/fusion-observable": "^9.0.1"
+    "@equinor/fusion-observable": "^9.1.1",
+    "@equinor/fusion-query": "^7.0.2"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
-    "@equinor/fusion-framework-module": "^6.0.0",
-    "@equinor/fusion-framework-module-http": "^8.0.1",
-    "@equinor/fusion-framework-module-service-discovery": "^10.0.1",
-    "@equinor/fusion-framework-module-msal": "^8.0.4",
-    "@equinor/fusion-framework-module-event": "^6.0.0"
+    "typescript": "^7.0.2",
+    "@equinor/fusion-framework-module": "^6.1.1",
+    "@equinor/fusion-framework-module-event": "^6.0.1",
+    "@equinor/fusion-framework-module-http": "^8.0.4",
+    "@equinor/fusion-framework-module-msal": "^10.0.2",
+    "@equinor/fusion-framework-module-service-discovery": "^10.0.2"
   },
   "scripts": {
     "build": "tsc -b"

package/src/AppClient.ts

@@ -20,7 +20,7 @@ import type {
   ConfigEnvironment,
 } from './types';
 import { AppBuildError, AppConfigError, AppManifestError, AppSettingsError } from './errors';
-import { AppConfigSelector } from './AppClient.Selectors';
+import { AppConfigSelector } from './AppConfigSelector';
 
 /**
  * Contract for an app service client that fetches application manifests,
@@ -102,11 +102,11 @@ const ApplicationSchema = ApiApplicationSchema.transform((x): AppManifest => {
   const { category, ...props } = x;
   return {
     ...props,
-    // TODO: remove deprecated appKey
+    // TODO(#5124): remove deprecated appKey
     get key() {
       return props.appKey;
     },
-    // TODO: remove deprecated name
+    // TODO(#5124): remove deprecated name
     get name() {
       return props.displayName;
     },
@@ -139,6 +139,10 @@ export class AppClient implements IAppClient {
   #settings: Query<AppSettings, { appKey: string; settings?: AppSettings }>;
   #client: IHttpClient;
 
+  /**
+   * Creates a new {@link AppClient} backed by the given HTTP client.
+   * @param client - The HTTP client used to communicate with the Fusion app service API.
+   */
   constructor(client: IHttpClient) {
     this.#client = client;
 
@@ -229,15 +233,26 @@ export class AppClient implements IAppClient {
     });
   }
 
+  /**
+   * Fetches the build metadata for an application.
+   * @param args - Object containing the `appKey` and an optional version `tag`.
+   * @returns An observable that emits the resolved {@link AppBuildManifest}.
+   * @throws {AppBuildError} When the build metadata cannot be loaded.
+   */
   getAppBuild(args: { appKey: string; tag?: string }): Observable<AppBuildManifest> {
+    // unwrap the build manifest and map errors to a typed AppBuildError
     return this.#build.query(args).pipe(
+      // unwrap the query result into the build manifest
       map((res) => res.value as AppBuildManifest),
+      // map http/unknown errors into a typed AppBuildError
       catchError((err) => {
         const cause = err?.cause || err;
 
+        // rethrow already-typed errors as-is
         if (cause instanceof AppBuildError) {
           throw cause;
         }
+        // map http errors to a typed AppBuildError
         if (cause instanceof HttpJsonResponseError || cause instanceof HttpResponseError) {
           throw AppBuildError.fromHttpResponse(cause.response, { cause });
         }
@@ -246,16 +261,26 @@ export class AppClient implements IAppClient {
     );
   }
 
+  /**
+   * Fetches the manifest for a single application.
+   * @param args - Object containing the `appKey` and an optional version `tag`.
+   * @returns An observable that emits the resolved {@link AppManifest}.
+   * @throws {AppManifestError} When the manifest cannot be loaded.
+   */
   getAppManifest(args: { appKey: string; tag?: string }): Observable<AppManifest> {
+    // unwrap the manifest and map errors to a typed AppManifestError
     return this.#manifest.query(args).pipe(
       queryValue,
+      // map http/unknown errors into a typed AppManifestError
       catchError((err) => {
         const cause = err?.cause || err;
 
+        // rethrow already-typed errors as-is
         if (cause instanceof AppManifestError) {
           throw cause;
         }
 
+        // map http errors to a typed AppManifestError
         if (cause instanceof HttpJsonResponseError || cause instanceof HttpResponseError) {
           throw AppManifestError.fromHttpResponse(cause.response, { cause });
         }
@@ -265,23 +290,41 @@ export class AppClient implements IAppClient {
     );
   }
 
+  /**
+   * Fetches manifests for all registered applications.
+   * @param args - Optional filter; set `filterByCurrentUser` to `true` to return only apps the authenticated user has access to.
+   * @returns An observable that emits an array of {@link AppManifest} objects.
+   */
   getAppManifests(args: { filterByCurrentUser?: boolean } | undefined): Observable<AppManifest[]> {
+    // unwrap the query result into the manifest array
     return this.#manifests.query(args).pipe(queryValue);
   }
 
+  /**
+   * Fetches the runtime configuration for an application.
+   * @template TType - Shape of the `environment` record in the returned config.
+   * @param args - Object containing the `appKey` and an optional version `tag`.
+   * @returns An observable that emits the resolved {@link AppConfig}.
+   * @throws {AppConfigError} When the configuration cannot be loaded.
+   */
   getAppConfig<TType extends ConfigEnvironment = ConfigEnvironment>(args: {
     appKey: string;
     tag?: string;
   }): Observable<AppConfig<TType>> {
+    // unwrap the config and map errors to a typed AppConfigError
     return this.#config.query(args).pipe(
+      // unwrap the query result into the config
       map((res) => res.value as AppConfig<TType>),
+      // map http/unknown errors into a typed AppConfigError
       catchError((err) => {
         /** handle both direct errors and errors wrapped in a `cause` property */
         const cause = err?.cause || err;
 
+        // rethrow already-typed errors as-is
         if (cause instanceof AppConfigError) {
           throw cause;
         }
+        // map http errors to a typed AppConfigError
         if (cause instanceof HttpJsonResponseError || cause instanceof HttpResponseError) {
           throw AppConfigError.fromHttpResponse(cause.response, { cause });
         }
@@ -290,16 +333,26 @@ export class AppClient implements IAppClient {
     );
   }
 
+  /**
+   * Fetches per-user settings for an application.
+   * @param args - Object containing the `appKey`.
+   * @returns An observable that emits the {@link AppSettings} record.
+   * @throws {AppSettingsError} When settings cannot be loaded.
+   */
   getAppSettings(args: { appKey: string }): Observable<AppSettings> {
+    // unwrap the settings and map errors to a typed AppSettingsError
     return this.#settings.query(args).pipe(
       queryValue,
+      // map http/unknown errors into a typed AppSettingsError
       catchError((err) => {
         /** handle both direct errors and errors wrapped in a `cause` property */
         const cause = err?.cause || err;
 
+        // rethrow already-typed errors as-is
         if (cause instanceof AppSettingsError) {
           throw cause;
         }
+        // map http errors to a typed AppSettingsError
         if (cause instanceof HttpJsonResponseError || cause instanceof HttpResponseError) {
           throw AppSettingsError.fromHttpResponse(cause.response, { cause });
         }
@@ -308,11 +361,15 @@ export class AppClient implements IAppClient {
     );
   }
 
+  /**
+   * Persists updated per-user settings for an application via PUT.
+   * @param args - Object containing the `appKey` and the `settings` payload to save.
+   * @returns An observable that emits the persisted {@link AppSettings}.
+   */
   updateAppSettings(args: { appKey: string; settings: AppSettings }): Observable<AppSettings> {
     const { appKey, settings } = args;
     return (
       this.#client
-        // execute PUT request to update settings
         .json$<AppSettings>(`/persons/me/apps/${appKey}/settings`, {
           method: 'PUT',
           body: settings,
@@ -320,6 +377,7 @@ export class AppClient implements IAppClient {
             'Api-Version': '1.0',
           },
         })
+        // update the settings cache with the persisted value
         .pipe(
           tap((value) => {
             // update cache with new settings
@@ -335,6 +393,9 @@ export class AppClient implements IAppClient {
     );
   }
 
+  /**
+   * Disposes of the client, completing all internal query streams.
+   */
   [Symbol.dispose]() {
     console.warn('AppClient disposed');
     this.#manifest.complete();

package/src/AppConfig.ts

@@ -6,7 +6,9 @@
  * @returns The same object, deeply frozen.
  */
 const deepFreeze = <T extends Record<string, unknown>>(obj: T): T => {
+  // recursively freeze any nested, unfrozen object properties
   for (const property of Object.keys(obj)) {
+    // only descend into unfrozen object properties
     if (
       typeof obj[property] === 'object' &&
       obj[property] !== null &&
@@ -59,18 +61,24 @@ export class AppConfig<TEnvironment extends ConfigEnvironment = ConfigEnvironmen
 
   /**
    * The environment configuration for the application.
+   * @returns The frozen environment configuration.
    */
   get environment(): TEnvironment {
     return this.#environment;
   }
 
   /**
-   * The configuration endpoints for the application,.
+   * The configuration endpoints for the application.
+   * @returns The frozen map of configuration endpoints.
    */
   get endpoints(): Record<string, ConfigEndPoint> {
     return this.#endpoints;
   }
 
+  /**
+   * Creates a new {@link AppConfig}, deep-freezing the provided environment and endpoints.
+   * @param config - The environment and endpoints to initialize the configuration with.
+   */
   constructor(config: {
     environment?: TEnvironment | null;
     endpoints?: Record<string, ConfigEndPoint>;

package/src/AppConfigurator.ts

@@ -6,8 +6,6 @@ import {
 import type { HttpModule, IHttpClient } from '@equinor/fusion-framework-module-http';
 import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
 
-import { moduleKey } from './module';
-
 import AppClient, { type IAppClient } from './AppClient';
 
 /**
@@ -64,7 +62,13 @@ export class AppConfigurator
   defaultExpireTime = 1 * 60 * 1000;
 
   /**
+   * Creates the default HTTP client for the app service, preferring a pre-configured
+   * client from the http module and falling back to service discovery.
+   *
    * WARNING: this function will be remove in future
+   *
+   * @param init - Module initializer args providing access to the http and service discovery modules.
+   * @returns A promise resolving to the {@link IHttpClient} used to communicate with the app service.
    */
   protected async _createHttpClient(
     init: ModuleInitializerArgs<IAppConfigurator, [HttpModule, ServiceDiscoveryModule]>,
@@ -79,11 +83,16 @@ export class AppConfigurator
     /** load service discovery module */
     const serviceDiscovery = await init.requireInstance('serviceDiscovery');
 
-    // TODO - remove when refactor portal service!
+    // TODO(#5125) - remove when refactor portal service!
     /** resolve and create a client from discovery */
     return await serviceDiscovery.createClient(serviceName);
   }
 
+  /**
+   * Sets the app service client used to fetch manifests, configs, and settings.
+   * @param client_or_cb - A promise resolving to an {@link IAppClient}, or a callback
+   *   that receives module initializer args and returns one.
+   */
   public setClient(
     client_or_cb:
       | Promise<AppModuleConfig['client']>
@@ -93,16 +102,30 @@ export class AppConfigurator
     this._set('client', cb);
   }
 
-  // TODO - explain why, used in import of resources aka proxy url
+  /**
+   * Sets the base URI used to proxy-load application script bundles.
+   *
+   * TODO(#5132) - explain why, used in import of resources aka proxy url
+   *
+   * @param base_or_cb - A static URI string or a callback returning one.
+   */
   public setAssetUri(base_or_cb: string | ConfigBuilderCallback<string>) {
     const cb = typeof base_or_cb === 'string' ? async () => base_or_cb : base_or_cb;
     this._set('assetUri', cb);
   }
 
+  /**
+   * Builds the resolved {@link AppModuleConfig}, applying default client and asset URI
+   * when they haven't been explicitly configured.
+   * @param init - Module initializer args used to build the default client.
+   * @param initial - Optional initial partial configuration.
+   * @returns The resolved module config.
+   */
   protected _createConfig(
     init: ModuleInitializerArgs<IAppConfigurator, [HttpModule, ServiceDiscoveryModule]>,
     initial?: Partial<AppModuleConfig>,
   ) {
+    // fall back to a default client created via the http/service discovery modules
     if (!this._has('client')) {
       this.setClient(async () => {
         const httpClient = await this._createHttpClient(init);
@@ -111,6 +134,7 @@ export class AppConfigurator
       });
     }
 
+    // fall back to the default proxy asset uri
     if (!this._has('assetUri')) {
       this.setAssetUri('/apps-proxy');
     }

package/src/AppModuleProvider.ts

@@ -45,6 +45,7 @@ export class AppModuleProvider {
   /**
    * Shallow-compares two app manifests by JSON serialization.
    *
+   * @template T - The manifest type being compared.
    * @param a - First manifest to compare.
    * @param b - Second manifest to compare.
    * @returns `true` if the serialized manifests are identical.
@@ -65,6 +66,7 @@ export class AppModuleProvider {
 
   /**
    * Get module version
+   * @returns The module's semantic version.
    */
   get version(): SemanticVersion {
     return new SemanticVersion(version);
@@ -76,6 +78,8 @@ export class AppModuleProvider {
    * - `undefined` – no application has been set yet.
    * - `null` – the current application was explicitly cleared.
    * - `App` – an active application instance.
+   *
+   * @returns The current active application, `null` if cleared, or `undefined` if never set.
    */
   get current(): CurrentApp | null | undefined {
     return this.#current$.value;
@@ -86,10 +90,14 @@ export class AppModuleProvider {
    *
    * Emits are deduplicated by `appKey`; re-setting the same app does not trigger
    * a new emission.
+   *
+   * @returns An observable of the current active application.
    */
   get current$(): Observable<CurrentApp | null> {
+    // dedupe emissions when the current app's key is unchanged
     return this.#current$.pipe(
       distinctUntilChanged((prev, next) => {
+        // compare by appKey when both are set, otherwise fall back to reference equality
         if (prev && next) {
           return prev.appKey === next.appKey;
         }
@@ -116,6 +124,7 @@ export class AppModuleProvider {
 
     this.#subscription.add(
       this.current$
+        // dispatch a lifecycle event whenever the current app changes
         .pipe(
           pairwise(),
           takeWhile(() => !!event),
@@ -130,6 +139,7 @@ export class AppModuleProvider {
 
     this.#subscription.add(
       this.#current$
+        // dispose the previous app once it has been replaced
         .pipe(
           pairwise(),
           map(([previous]) => previous),
@@ -164,6 +174,7 @@ export class AppModuleProvider {
   /**
    * fetch all applications
    * @deprecated use `getAppManifests` instead
+   * @returns An observable that emits an array of {@link AppManifest} objects.
    */
   public getAllAppManifests(): Observable<AppManifest[]> {
     return this.getAppManifests();
@@ -214,12 +225,14 @@ export class AppModuleProvider {
    * @param appKeyOrApp - Application key, app reference, or an existing `IApp` instance.
    */
   public setCurrentApp(appKeyOrApp: string | IApp | AppReference): void {
+    // a plain string is treated as an appKey to create a new App from
     if (typeof appKeyOrApp === 'string') {
       const newApp = new App({ appKey: appKeyOrApp }, { provider: this, event: this.#event });
       this.#current$.next(newApp as CurrentApp);
       return;
     }
 
+    // an object with appKey and tag is treated as an AppReference to create a new App from
     if (appKeyOrApp.appKey && 'tag' in appKeyOrApp) {
       const newApp = new App(
         { appKey: appKeyOrApp.appKey, tag: appKeyOrApp.tag },
@@ -242,6 +255,7 @@ export class AppModuleProvider {
 
   /**
    * Base URI used for proxying application script imports.
+   * @returns The configured asset base URI.
    */
   public get assetUri(): string {
     return this.#appBaseUri;
@@ -250,6 +264,8 @@ export class AppModuleProvider {
   /**
    * This should not be used, only for legacy creation backdoor
    * @deprecated
+   * @param value - The initial app bundle state to construct the app from.
+   * @returns The newly created {@link App} instance.
    */
   public createApp(value: AppBundleStateInitial): App {
     console.warn('AppModuleProvider.createApp is deprecated and should not be used.');