@equinor/fusion-framework-module-app 7.4.1 → 8.0.0

package/dist/types/AppClient.d.ts

@@ -1,44 +1,74 @@
 import { type Observable, type ObservableInput } from 'rxjs';
 import { type IHttpClient } from '@equinor/fusion-framework-module-http';
 import type { AppBuildManifest, AppConfig, AppManifest, AppSettings, ConfigEnvironment } from './types';
+/**
+ * Contract for an app service client that fetches application manifests,
+ * build metadata, configurations, and per-user settings from the Fusion apps API.
+ *
+ * All methods return `ObservableInput` so consumers can use either `Observable`
+ * or `Promise`-based consumption patterns.
+ */
 export interface IAppClient extends Disposable {
     /**
-     * Fetch app manifest by appKey and tag
+     * 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 (404, 401, 410, or unknown).
      */
     getAppManifest: (args: {
         appKey: string;
         tag?: string;
     }) => ObservableInput<AppManifest>;
     /**
-     * Fetch app build manifest by appKey and tag
+     * Fetches the build metadata (entry point, version, asset path) 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;
     }) => ObservableInput<AppBuildManifest>;
     /**
-     * Fetch all app manifests
+     * 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;
     }) => ObservableInput<AppManifest[]>;
     /**
-     * Fetch app config by appKey and tag
+     * Fetches the runtime configuration (environment variables and endpoints) 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;
     }) => ObservableInput<AppConfig<TType>>;
     /**
-     * Fetch app settings by appKey
+     * 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;
     }) => ObservableInput<AppSettings>;
     /**
-     * Set app settings by appKey
-     * @param args - Object with appKey and settings
-     * @returns ObservableInput<AppSettings>
+     * 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}.
+     * @throws {AppSettingsError} When the update request fails.
      */
     updateAppSettings: (args: {
         appKey: string;
@@ -46,8 +76,20 @@ export interface IAppClient extends Disposable {
     }) => ObservableInput<AppSettings>;
 }
 /**
- * The `AppClient` class implements the `IAppClient` interface and provides methods to query
- * application manifests and configurations from a backend service.
+ * Default implementation of {@link IAppClient} that communicates with the
+ * Fusion app service API over HTTP.
+ *
+ * Uses {@link Query} internally for request deduplication and caching
+ * (1-minute expiry by default). Responses are validated against Zod schemas
+ * ({@link ApiApplicationSchema}, {@link ApiApplicationBuildSchema}) and
+ * HTTP errors are mapped to typed error classes.
+ *
+ * @example
+ * ```ts
+ * const httpClient = await http.createClient('apps');
+ * const appClient = new AppClient(httpClient);
+ * appClient.getAppManifest({ appKey: 'my-app' }).subscribe(console.log);
+ * ```
  */
 export declare class AppClient implements IAppClient {
     #private;

package/dist/types/AppConfig.d.ts

@@ -1,4 +1,12 @@
+/**
+ * Arbitrary key-value record representing environment-specific variables
+ * injected into an application's runtime configuration.
+ */
 export type ConfigEnvironment = Record<string, unknown>;
+/**
+ * A named endpoint from the application configuration, containing a URL
+ * and the OAuth scopes required to call it.
+ */
 export type ConfigEndPoint = {
     url: string;
     scopes: string[];

package/dist/types/AppConfigurator.d.ts

@@ -2,14 +2,46 @@ import { BaseConfigBuilder, type ConfigBuilderCallback, type ModuleInitializerAr
 import type { HttpModule, IHttpClient } from '@equinor/fusion-framework-module-http';
 import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
 import { type IAppClient } from './AppClient';
+/**
+ * Resolved configuration for the app module.
+ *
+ * Produced by {@link AppConfigurator} during module initialization and consumed
+ * by {@link AppModuleProvider} at runtime.
+ */
 export interface AppModuleConfig {
+    /** HTTP client used to communicate with the Fusion app service API. */
     client: IAppClient;
+    /** Base URI for fetching application script bundles (e.g., `'/apps-proxy'`). */
     assetUri?: string;
 }
+/**
+ * Public interface for configuring the app module before initialization.
+ *
+ * Consumers use this interface (via the callback in {@link enableAppModule}) to
+ * override the default HTTP client or asset URI.
+ */
 export interface IAppConfigurator {
+    /**
+     * 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.
+     */
     setClient: (client_or_cb: Promise<AppModuleConfig['client']> | ConfigBuilderCallback<AppModuleConfig['client']>) => void;
+    /**
+     * Sets the base URI used to proxy-load application script bundles.
+     *
+     * @param base_or_cb - A static URI string or a callback returning one.
+     */
     setAssetUri: (base_or_cb: string | ConfigBuilderCallback<string>) => void;
 }
+/**
+ * Configuration builder for the app module.
+ *
+ * Extends {@link BaseConfigBuilder} to assemble an {@link AppModuleConfig} during
+ * framework initialization. If no explicit client is set, a default one is created
+ * via service discovery. The default `assetUri` is `'/apps-proxy'`.
+ */
 export declare class AppConfigurator extends BaseConfigBuilder<AppModuleConfig> implements IAppConfigurator {
     defaultExpireTime: number;
     /**

package/dist/types/AppModuleProvider.d.ts

@@ -6,32 +6,73 @@ import { App, type IApp } from './app/App';
 import type { AppModuleConfig } from './AppConfigurator';
 import type { AppBundleStateInitial } from './app/types';
 import { SemanticVersion } from '@equinor/fusion-framework-module';
+/**
+ * Runtime provider for the app module.
+ *
+ * Exposes methods for fetching application manifests, configurations, and user
+ * settings, and for setting or clearing the current active application. When an
+ * {@link EventModule} is available, lifecycle events are dispatched as the
+ * current app changes.
+ *
+ * @remarks
+ * Only one application can be active (`current`) at a time. Setting a new current
+ * app automatically disposes the previous one. Subscribe to {@link current$} for
+ * reactive updates.
+ */
 export declare class AppModuleProvider {
     #private;
+    /**
+     * Shallow-compares two app manifests by JSON serialization.
+     *
+     * @param a - First manifest to compare.
+     * @param b - Second manifest to compare.
+     * @returns `true` if the serialized manifests are identical.
+     */
     static compareAppManifest<T extends AppManifest>(a?: T, b?: T): boolean;
     /**
      * Get module version
      */
     get version(): SemanticVersion;
     /**
-     * fetch an application by key
-     * @param appKey - application key
-     * @remarks
-     * - null when current app is cleared
-     * - undefined if application never set
+     * The current active application instance.
+     *
+     * - `undefined` – no application has been set yet.
+     * - `null` – the current application was explicitly cleared.
+     * - `App` – an active application instance.
      */
     get current(): CurrentApp | null | undefined;
+    /**
+     * Observable that emits when the current application changes.
+     *
+     * Emits are deduplicated by `appKey`; re-setting the same app does not trigger
+     * a new emission.
+     */
     get current$(): Observable<CurrentApp | null>;
+    /**
+     * Creates the app module provider.
+     *
+     * @param args - Object containing the resolved {@link AppModuleConfig} and an
+     *   optional {@link EventModule} instance for dispatching lifecycle events.
+     */
     constructor(args: {
         config: AppModuleConfig;
         event?: ModuleType<EventModule>;
     });
     /**
-     * fetch an application by key
-     * @param appKey - application key
-     * @param tag - application tag (optional)
+     * Fetches the manifest for a single application by key.
+     *
+     * @param appKey - Unique application identifier.
+     * @param tag - Optional version tag (defaults to latest).
+     * @returns An observable that emits the resolved {@link AppManifest}.
      */
     getAppManifest(appKey: string, tag?: string): Observable<AppManifest>;
+    /**
+     * Fetches manifests for all registered applications.
+     *
+     * @param filter - Optional filter; set `filterByCurrentUser` to `true` to scope
+     *   results to apps accessible by the authenticated user.
+     * @returns An observable that emits an array of {@link AppManifest} objects.
+     */
     getAppManifests(filter?: {
         filterByCurrentUser: boolean;
     }): Observable<AppManifest[]>;
@@ -41,33 +82,55 @@ export declare class AppModuleProvider {
      */
     getAllAppManifests(): Observable<AppManifest[]>;
     /**
-     * fetch configuration for an application
-     * @param appKey - application key
+     * Fetches the runtime configuration for an application.
+     *
+     * @template TType - Shape of the `environment` record in the returned config.
+     * @param appKey - Unique application identifier.
+     * @param tag - Optional version tag.
+     * @returns An observable that emits the resolved {@link AppConfig}.
      */
     getAppConfig<TType extends ConfigEnvironment = ConfigEnvironment>(appKey: string, tag?: string): Observable<AppConfig<TType>>;
     /**
-     * fetch user settings for an application
-     * @param appKey - application key
+     * Fetches per-user settings for an application.
+     *
+     * @param appKey - Unique application identifier.
+     * @returns An observable that emits the {@link AppSettings} record.
      */
     getAppSettings(appKey: string): Observable<AppSettings>;
     /**
-     * Put user settings for an application
-     * @param appKey - application key
-     * @param settings - The settings to add save
+     * Persists updated per-user settings for an application.
+     *
+     * @param appKey - Unique application identifier.
+     * @param settings - The settings record to save.
+     * @returns An observable that emits the persisted {@link AppSettings}.
      */
     updateAppSettings(appKey: string, settings: AppSettings): Observable<AppSettings>;
     /**
-     * set the current application, will internally resolve manifest
-     * @param appKey - application key
+     * Sets the current active application.
+     *
+     * Accepts an app key string, an {@link IApp} instance, or an {@link AppReference}
+     * with both `appKey` and `tag`. Setting a new app disposes the previous one.
+     *
+     * @param appKeyOrApp - Application key, app reference, or an existing `IApp` instance.
      */
     setCurrentApp(appKeyOrApp: string | IApp | AppReference): void;
+    /**
+     * Clears the current application, disposing its resources and emitting `null`
+     * on {@link current$}.
+     */
     clearCurrentApp(): void;
+    /**
+     * Base URI used for proxying application script imports.
+     */
     get assetUri(): string;
     /**
      * This should not be used, only for legacy creation backdoor
      * @deprecated
      */
     createApp(value: AppBundleStateInitial): App;
+    /**
+     * Tears down the provider, unsubscribing from all internal observables.
+     */
     dispose(): void;
 }
 export default AppModuleProvider;

package/dist/types/app/App.d.ts

@@ -6,11 +6,22 @@ import type { EventModule } from '@equinor/fusion-framework-module-event';
 import type { AnyModule, ModuleType } from '@equinor/fusion-framework-module';
 import type { AppBundleState, AppBundleStateInitial } from './types';
 import './events';
+/**
+ * RxJS operator that filters out `null` and `undefined` emissions.
+ *
+ * @template T - The non-nullable value type.
+ * @returns An operator that only passes through non-nullable values.
+ */
 export declare function filterEmpty<T>(): OperatorFunction<T | null | undefined, T>;
 /**
- * Represents an application in the framework.
- * @template TEnv The type of the environment.
- * @template TModules The type of the app modules.
+ * Public interface for a single loaded Fusion application.
+ *
+ * Provides reactive observables and imperative methods for accessing the
+ * application's manifest, configuration, per-user settings, script module,
+ * and initialized module instance.
+ *
+ * @template TEnv - Shape of the environment configuration record.
+ * @template TModules - Additional framework modules the app depends on.
  */
 export interface IApp<TEnv extends ConfigEnvironment = ConfigEnvironment, TModules extends Array<AnyModule> | unknown = unknown> {
     /**
@@ -181,11 +192,25 @@ export interface IApp<TEnv extends ConfigEnvironment = ConfigEnvironment, TModul
      */
     getAppModuleAsync(allow_cache?: boolean): Promise<AppScriptModule>;
 }
+/**
+ * Result emitted by {@link IApp.initialize}, containing the resolved manifest,
+ * imported script module, and runtime configuration.
+ */
 export type AppInitializeResult = {
     manifest: AppManifest;
     script: AppScriptModule;
     config: AppConfig;
 };
+/**
+ * Concrete implementation of {@link IApp}.
+ *
+ * Manages an internal reactive state machine ({@link FlowSubject}) that orchestrates
+ * manifest fetching, config loading, settings management, and script import. Dispatches
+ * lifecycle events through the {@link EventModule} when available.
+ *
+ * @template TEnv - Shape of the environment configuration record.
+ * @template TModules - Additional framework modules the app depends on.
+ */
 export declare class App<TEnv extends ConfigEnvironment = ConfigEnvironment, TModules extends Array<AnyModule> | unknown = unknown> implements IApp<TEnv, TModules> {
     #private;
     get manifest$(): Observable<AppManifest>;

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

@@ -1,5 +1,17 @@
 import { type ActionInstanceMap, type ActionTypes } from '@equinor/fusion-observable';
 import type { AppConfig, AppManifest, AppModulesInstance, AppScriptModule, AppSettings } from '../types';
+/**
+ * Factory function that creates all action creators used by the {@link App}
+ * state machine.
+ *
+ * Actions are grouped by domain:
+ * - **Manifest** – `setManifest`, `fetchManifest` (async)
+ * - **Config** – `setConfig`, `fetchConfig` (async)
+ * - **Settings** – `setSettings`, `fetchSettings` (async), `updateSettings` (async)
+ * - **Script module** – `setModule`, `importApp` (async)
+ * - **Instance** – `setInstance`
+ * - **Lifecycle** – `initialize` (async)
+ */
 declare const createActions: () => {
     /** Manifest loading */
     setManifest: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[manifest: AppManifest, update?: boolean | undefined], AppManifest, "set_manifest", never, {
@@ -51,6 +63,7 @@ declare const createActions: () => {
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "initialize_app::failure", never, never>;
     };
 };
+/** Singleton action creator map used by the app state machine. */
 export declare const actions: {
     /** Manifest loading */
     setManifest: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[manifest: AppManifest, update?: boolean | undefined], AppManifest, "set_manifest", never, {
@@ -102,7 +115,10 @@ export declare const actions: {
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "initialize_app::failure", never, never>;
     };
 };
+/** Record mapping action names to their creator functions. */
 export type ActionBuilder = ReturnType<typeof createActions>;
+/** Map of action names to their instantiated action shapes. */
 export type ActionMap = ActionInstanceMap<ActionBuilder>;
+/** Union of all action types dispatched by the app state machine. */
 export type Actions = ActionTypes<typeof actions>;
 export {};

package/dist/types/app/create-reducer.d.ts

@@ -1,4 +1,13 @@
 import type { AppBundleState, AppBundleStateInitial } from './types';
+/**
+ * Creates the Immer-powered reducer for the {@link App} state machine.
+ *
+ * Handles synchronous state updates (set manifest, config, settings, module, instance)
+ * and tracks in-progress async operations via a `status` set.
+ *
+ * @param value - Initial state values (appKey, tag, and any pre-loaded data).
+ * @returns A reducer function compatible with {@link FlowSubject}.
+ */
 export declare const createReducer: (value: AppBundleStateInitial) => import("@equinor/fusion-observable").ReducerWithInitialState<AppBundleState, import("@equinor/fusion-observable").PayloadAction<import("..").AppManifest, "set_manifest", {
     created: number;
     update: boolean | undefined;

package/dist/types/app/create-state.d.ts

@@ -2,4 +2,15 @@ import { FlowSubject } from '@equinor/fusion-observable';
 import type { Actions } from './actions';
 import type { AppBundleState, AppBundleStateInitial } from './types';
 import type { AppModuleProvider } from '../AppModuleProvider';
+/**
+ * Creates and configures the reactive state machine ({@link FlowSubject}) for
+ * an {@link App} instance.
+ *
+ * Registers flows for fetching manifests, configs, settings, and importing
+ * the application script module.
+ *
+ * @param value - Initial state values (appKey, tag, and any pre-loaded data).
+ * @param provider - The {@link AppModuleProvider} used by flows to fetch data.
+ * @returns A configured `FlowSubject` ready for use by the App class.
+ */
 export declare const createState: (value: AppBundleStateInitial, provider: AppModuleProvider) => FlowSubject<AppBundleState, Actions>;

package/dist/types/app/events.d.ts

@@ -1,7 +1,14 @@
 import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framework-module-event';
 import type { App } from './App';
 import type { AppConfig, AppManifest, AppModulesInstance, AppScriptModule, AppSettings } from '../types';
-/** base event type for applications */
+/**
+ * Base event initialization type for application lifecycle events.
+ *
+ * Extends {@link FrameworkEventInit} with a mandatory `appKey` field and
+ * the {@link App} as the event source.
+ *
+ * @template TDetail - Additional detail properties carried by the event.
+ */
 export type AppEventEventInit<TDetail extends Record<string, unknown> | unknown = unknown> = FrameworkEventInit<
 /** additional event details and key of target event */
 TDetail & {
@@ -9,7 +16,16 @@ TDetail & {
 }, 
 /** source of the event */
 App>;
+/**
+ * Framework event carrying application-scoped detail and an {@link App} source.
+ *
+ * @template TDetail - Additional detail properties carried by the event.
+ */
 export type AppEvent<TDetail extends Record<string, unknown> | unknown = unknown> = FrameworkEvent<AppEventEventInit<TDetail>>;
+/**
+ * Framework event emitted when an application lifecycle operation fails.
+ * The `error` detail carries the underlying failure.
+ */
 export type AppEventFailure = FrameworkEvent<AppEventEventInit<{
     error: AppConfig;
 }>>;

package/dist/types/app/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Re-exports for the app sub-module.
+ *
+ * - {@link App} – Concrete application class managing reactive state.
+ * - {@link IApp} – Public interface for an application instance.
+ * - {@link AppInitializeResult} – Shape emitted by `App.initialize()`.
+ */
 export { App, IApp, type AppInitializeResult } from './App';
 export { default } from './App';

package/dist/types/enable-app-module.d.ts

@@ -1,7 +1,24 @@
 import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
 import type { AppConfigurator } from './AppConfigurator';
 /**
- * Method for enabling the Service module
- * @param configurator - configuration object
+ * Registers the app module with a framework configurator.
+ *
+ * Call this during framework setup to enable application loading, manifest fetching,
+ * configuration resolution, and per-user settings management.
+ *
+ * @param configurator - The framework modules configurator to register the app module with.
+ * @param callback - Optional callback to customize the {@link AppConfigurator} before initialization
+ *   (e.g., override the HTTP client or set a custom asset URI).
+ *
+ * @example
+ * ```ts
+ * import { enableAppModule } from '@equinor/fusion-framework-module-app';
+ *
+ * export const configure = async (configurator: FrameworkConfigurator) => {
+ *   enableAppModule(configurator, (builder) => {
+ *     builder.setAssetUri('/custom-proxy');
+ *   });
+ * };
+ * ```
  */
 export declare const enableAppModule: (configurator: IModulesConfigurator<any, any>, callback?: (builder: AppConfigurator) => void | Promise<void>) => void;

package/dist/types/errors.d.ts

@@ -1,3 +1,11 @@
+/**
+ * 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.

package/dist/types/index.d.ts

@@ -1,3 +1,21 @@
+/**
+ * @packageDocumentation
+ *
+ * Framework module for loading, configuring, and managing Fusion applications at runtime.
+ *
+ * Use {@link enableAppModule} to register the module with a framework configurator.
+ * Once initialized, {@link AppModuleProvider} exposes methods for fetching app manifests,
+ * configurations, user settings, and for setting the current active application.
+ *
+ * @example
+ * ```ts
+ * import { enableAppModule } from '@equinor/fusion-framework-module-app';
+ *
+ * export const configure = async (configurator: FrameworkConfigurator) => {
+ *   enableAppModule(configurator);
+ * };
+ * ```
+ */
 export { AppModuleConfig, AppConfigurator, IAppConfigurator, type AppModuleConfig as IAppModuleConfig, } from './AppConfigurator';
 export { AppClient, type IAppClient } from './AppClient';
 export { AppModuleProvider } from './AppModuleProvider';

package/dist/types/module.d.ts

@@ -2,7 +2,13 @@ import type { Module } from '@equinor/fusion-framework-module';
 import type { ModuleDeps } from './types';
 import { AppConfigurator } from './AppConfigurator';
 import { AppModuleProvider } from './AppModuleProvider';
+/** Module key used to register and look up the app module in the framework. */
 export declare const moduleKey = "app";
+/**
+ * Type alias for the app module definition, binding the module key,
+ * provider type ({@link AppModuleProvider}), configurator type
+ * ({@link AppConfigurator}), and required module dependencies.
+ */
 export type AppModule = Module<typeof moduleKey, AppModuleProvider, AppConfigurator, ModuleDeps>;
 /**
  * Represents a module for handling applications.