@equinor/fusion-framework-module-app 8.1.0 → 8.1.1

package/src/enable-app-module.ts

@@ -1,40 +0,0 @@
-import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
-import { module } from './module';
-import type { AppConfigurator } from './AppConfigurator';
-
-/**
- * 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 const enableAppModule = (
-  // biome-ignore lint/suspicious/noExplicitAny: `IModulesConfigurator<any, any>` widens to accept a configurator for any concrete module set — `unknown` would break assignability of a real configurator instance to this parameter
-  configurator: IModulesConfigurator<any, any>,
-  callback?: (builder: AppConfigurator) => void | Promise<void>,
-): void => {
-  configurator.addConfig({
-    module,
-    configure: async (configurator) => {
-      // apply the caller's configuration overrides, if provided
-      if (callback) {
-        Promise.resolve(callback(configurator));
-      }
-    },
-  });
-};

package/src/errors/AppBuildError.ts

@@ -1,47 +0,0 @@
-import type { AppErrorType } from './app-error-type';
-
-/**
- * Represents an error that occurs in the application build.
- */
-export class AppBuildError extends Error {
-  /**
-   * 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 {
-    // map well-known HTTP statuses to a specific error type
-    switch (response.status) {
-      case 401:
-        return new AppBuildError(
-          'unauthorized',
-          'failed to load application build metadata, request not authorized',
-          options,
-        );
-      case 404:
-        return new AppBuildError('not_found', 'application build metadata not found', options);
-      case 410:
-        return new AppBuildError('deleted', 'application build deleted', options);
-    }
-    return new AppBuildError(
-      'unknown',
-      `failed to load application build, status code ${response.status}`,
-      options,
-    );
-  }
-
-  /**
-   * Creates an instance of `AppBuildError`.
-   * @param type The type of the application error.
-   * @param message The error message.
-   * @param options Additional error options.
-   */
-  constructor(
-    public readonly type: AppErrorType,
-    message?: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options);
-  }
-}

package/src/errors/AppConfigError.ts

@@ -1,47 +0,0 @@
-import type { AppErrorType } from './app-error-type';
-
-/**
- * Represents an error that occurs in the application configuration.
- */
-export class AppConfigError extends Error {
-  /**
-   * 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 {
-    // map well-known HTTP statuses to a specific error type
-    switch (response.status) {
-      case 401:
-        return new AppConfigError(
-          'unauthorized',
-          'failed to load application config, request not authorized',
-          options,
-        );
-      case 404:
-        return new AppConfigError('not_found', 'application config not found', options);
-      case 410:
-        return new AppConfigError('deleted', 'application config deleted', options);
-    }
-    return new AppConfigError(
-      'unknown',
-      `failed to load application config, status code ${response.status}`,
-      options,
-    );
-  }
-
-  /**
-   * Creates an instance of `AppConfigError`.
-   * @param type The type of the application error.
-   * @param message The error message.
-   * @param options Additional error options.
-   */
-  constructor(
-    public readonly type: AppErrorType,
-    message?: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options);
-  }
-}

package/src/errors/AppManifestError.ts

@@ -1,47 +0,0 @@
-import type { AppErrorType } from './app-error-type';
-
-/**
- * Represents an error that occurs when loading an application manifest.
- */
-export class AppManifestError extends Error {
-  /**
-   * 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) {
-    // map well-known HTTP statuses to a specific error type
-    switch (response.status) {
-      case 401:
-        return new AppManifestError(
-          'unauthorized',
-          'failed to load application manifest, request not authorized',
-          options,
-        );
-      case 404:
-        return new AppManifestError('not_found', 'application manifest not found', options);
-      case 410:
-        return new AppManifestError('deleted', 'application manifest deleted', options);
-    }
-    return new AppManifestError(
-      'unknown',
-      `failed to load application manifest, status code ${response.status}`,
-      options,
-    );
-  }
-
-  /**
-   * Creates an instance of AppManifestError.
-   * @param type The type of the error.
-   * @param message The error message.
-   * @param options Optional error options.
-   */
-  constructor(
-    public readonly type: AppErrorType,
-    message?: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options);
-  }
-}

package/src/errors/AppScriptModuleError.ts

@@ -1,20 +0,0 @@
-import type { AppErrorType } from './app-error-type';
-
-/**
- * Represents an error that occurs when loading the application script.
- */
-export class AppScriptModuleError extends Error {
-  /**
-   * 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(
-    public readonly type: AppErrorType,
-    message?: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options);
-  }
-}

package/src/errors/AppSettingsError.ts

@@ -1,47 +0,0 @@
-import type { AppErrorType } from './app-error-type';
-
-/**
- * Represents an error that occurs while fetching application settings.
- */
-export class AppSettingsError extends Error {
-  /**
-   * 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 {
-    // map well-known HTTP statuses to a specific error type
-    switch (response.status) {
-      case 401:
-        return new AppSettingsError(
-          'unauthorized',
-          'failed to load application settings, request not authorized',
-          options,
-        );
-      case 404:
-        return new AppSettingsError('not_found', 'application not found', options);
-      case 410:
-        return new AppSettingsError('deleted', 'application settings deleted', options);
-    }
-    return new AppSettingsError(
-      'unknown',
-      `failed to load application settings, status code ${response.status}`,
-      options,
-    );
-  }
-
-  /**
-   * Creates an instance of `AppSettingsError`.
-   * @param type The type of the application error.
-   * @param message The error message.
-   * @param options Additional error options.
-   */
-  constructor(
-    public readonly type: AppErrorType,
-    message?: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options);
-  }
-}

package/src/errors/app-error-type.ts

@@ -1,9 +0,0 @@
-/**
- * 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.
- */
-export type AppErrorType = 'not_found' | 'unauthorized' | 'unknown' | 'deleted';

package/src/errors.ts

@@ -1,6 +0,0 @@
-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/src/events.ts

@@ -1,18 +0,0 @@
-import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-import type { App } from './app/App';
-
-import './app/events';
-
-declare module '@equinor/fusion-framework-module-event' {
-  interface FrameworkEventMap {
-    /** fired when the current selected application changes */
-    onCurrentAppChanged: FrameworkEvent<
-      FrameworkEventInit<{
-        /** current application  */
-        next?: App;
-        /** previous application */
-        previous?: App;
-      }>
-    >;
-  }
-}

package/src/index.ts

@@ -1,40 +0,0 @@
-/**
- * @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 { AppConfig } from './AppConfig';
-
-export { AppModuleProvider } from './AppModuleProvider';
-
-export { IApp } from './app/App';
-
-export * from './events';
-export * from './types';
-
-export { enableAppModule } from './enable-app-module';
-
-export { default, AppModule, module, moduleKey } from './module';

package/src/mock/MockAppClient.ts

@@ -1,77 +0,0 @@
-import type { Observable } from 'rxjs';
-import { of } from 'rxjs';
-
-import type { IHttpClient } from '@equinor/fusion-framework-module-http';
-
-import { AppClient } from '../AppClient.js';
-import type { AppConfig, AppManifest, ConfigEnvironment } from '../types.js';
-
-/**
- * An {@link AppClient} that answers `getAppManifest` and `getAppConfig` for one
- * known app locally, delegating everything else — other app keys, tagged
- * requests, builds, settings — to the real client it wraps.
- *
- * @remarks
- * Whatever `client` was resolved to (a pre-configured http client, or one created
- * through service discovery) still backs every method this class doesn't
- * override, so pointing service discovery at a different registry or a real
- * local mock server keeps working unchanged.
- *
- * @example
- * ```ts
- * builder.setClient(async ({ requireInstance }) => {
- *   const http = await requireInstance('http');
- *   return new MockAppClient(http.createClient('apps'), manifest, config);
- * });
- * ```
- */
-export class MockAppClient extends AppClient {
-  #manifest: AppManifest;
-  #config?: AppConfig;
-
-  /**
-   * @param client - The real {@link IHttpClient} to delegate all other requests to.
-   * @param manifest - The manifest to return for `getAppManifest({ appKey: manifest.appKey })`.
-   * @param config - The config to return for `getAppConfig({ appKey: manifest.appKey })`, if any.
-   */
-  constructor(client: IHttpClient, manifest: AppManifest, config?: AppConfig) {
-    super(client);
-    this.#manifest = manifest;
-    this.#config = config;
-  }
-
-  /**
-   * Answers with the manifest passed to the constructor when `args` matches
-   * this client's own app key and no tag; otherwise delegates to the real client.
-   *
-   * @param args - The app key and optional tag to resolve a manifest for.
-   * @returns An observable of the resolved {@link AppManifest}.
-   */
-  override getAppManifest(args: { appKey: string; tag?: string }): Observable<AppManifest> {
-    return args.appKey === this.#manifest.appKey && args.tag === undefined
-      ? of(this.#manifest)
-      : super.getAppManifest(args);
-  }
-
-  /**
-   * Answers with the config passed to the constructor when `args` matches this
-   * client's own app key and tag; otherwise delegates to the real client.
-   *
-   * @template TType - The shape of the config's `environment` data.
-   * @param args - The app key and optional tag to resolve config for.
-   * @returns An observable of the resolved {@link AppConfig}.
-   */
-  override getAppConfig<TType extends ConfigEnvironment = ConfigEnvironment>(args: {
-    appKey: string;
-    tag?: string;
-  }): Observable<AppConfig<TType>> {
-    // config is fetched against the manifest's own build version, not an explicit override tag,
-    // so a matching tag is treated the same as an absent one -- an explicit empty string is not
-    const isOwnTag = args.tag === undefined || args.tag === this.#manifest.build?.version;
-    return args.appKey === this.#manifest.appKey && isOwnTag && this.#config
-      ? of(this.#config as AppConfig<TType>)
-      : super.getAppConfig(args);
-  }
-}
-
-export default MockAppClient;

package/src/mock/index.ts

@@ -1,13 +0,0 @@
-/**
- * Test doubles for the app module.
- *
- * @remarks
- * Imported from `@equinor/fusion-framework-module-app/mock`, so the mock ships
- * and versions with the implementation it stands in for.
- *
- * This entry point has no dependency on any test runner.
- *
- * @packageDocumentation
- */
-
-export { MockAppClient } from './MockAppClient.js';

package/src/module.ts

@@ -1,59 +0,0 @@
-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 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.
- * Responsible for loading applications, configurations and manifests.
- * @public
- */
-export const module: AppModule = {
-  /**
-   * The name of the module.
-   */
-  name: moduleKey,
-  /**
-   * Configures the module.
-   * @returns An instance of AppConfigurator.
-   */
-  configure: () => new AppConfigurator(),
-  /**
-   * Initializes the module.
-   * @param args - The initialization arguments.
-   * @returns A new instance of AppModuleProvider.
-   */
-  initialize: async (args) => {
-    const config = await args.config.createConfigAsync(args);
-    const event = await args.requireInstance('event').catch(() => undefined);
-    return new AppModuleProvider({ config, event });
-  },
-  /**
-   * Disposes the module.
-   * @param args - The disposal arguments.
-   */
-  dispose: (args) => {
-    // `args.instance` is typed as the generic module instance, but the module descriptor
-    // guarantees it was created as an `AppModuleProvider` — safe to cast for disposal.
-    (args.instance as unknown as AppModuleProvider).dispose();
-  },
-};
-
-export default module;
-
-declare module '@equinor/fusion-framework-module' {
-  interface Modules {
-    app: AppModule;
-  }
-}

package/src/schemas.ts

@@ -1,181 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Schema for the API application configuration.
- *
- * This schema validates the structure of the configuration object used for the API application.
- *
- * Properties:
- * - `environment` (optional): A record of key-value pairs where the value can be of any type. Defaults to an empty object.
- * - `endpoints` (optional): A record where each key maps to an object containing:
- *   - `url`: A string representing the endpoint URL.
- *   - `scopes` (optional): An array of strings representing the scopes. Defaults to an empty array.
- */
-export const ApiAppConfigSchema = z.object({
-  environment: z.record(z.string(), z.any()).optional().default({}),
-  endpoints: z
-    .record(
-      z.string(),
-      z.object({
-        url: z.string(),
-        scopes: z.array(z.string()).optional().default([]),
-      }),
-    )
-    .optional(),
-});
-
-export type ApiAppConfig = z.infer<typeof ApiAppConfigSchema>;
-
-/**
- * Schema for validating an API application person object.
- *
- * Properties:
- * - `azureUniqueId` (string): The unique identifier for the person in Azure.
- * - `displayName` (string): The display name of the person.
- * - `mail` (string | nullish): The email address of the person, which can be null or undefined.
- * - `upn` (string | nullish): The User Principal Name (UPN) of the person, which can be null or undefined.
- * - `accountType` (string): The type of account the person has.
- * - `accountClassification` (string | nullish): The classification of the account, which can be null or undefined.
- * - `isExpired` (boolean | nullish): Indicates whether the account is expired, which can be null or undefined.
- */
-const ApiApplicationPersonSchema = z.object({
-  azureUniqueId: z.string({ message: 'The unique identifier for the person in Azure.' }),
-  displayName: z.string({ message: 'The display name of the person.' }),
-  mail: z
-    .string({ message: 'The email address of the person, which can be null or undefined.' })
-    .nullish(),
-  upn: z
-    .string({
-      message: 'The User Principal Name (UPN) of the person, which can be null or undefined.',
-    })
-    .nullish(),
-  accountType: z.string({ message: 'The type of account the person has.' }),
-  accountClassification: z
-    .string({ message: 'The classification of the account, which can be null or undefined.' })
-    .nullish(),
-  isExpired: z
-    .boolean({
-      message: 'Indicates whether the account is expired, which can be null or undefined.',
-    })
-    .nullish(),
-});
-
-/**
- * Schema for validating the options object on application builds.
- *
- * Known properties:
- * - `contextRouting` (optional): Routing strategy for context — `'path'` or `'query'`.
- *
- * The schema uses `.catchall(z.unknown())` to permit additional properties
- * at runtime without requiring them to be declared here. Add known properties
- * to this schema as they are introduced.
- */
-// Deliberately co-located with ApiApplicationBuildSchema, which depends on it
-// fusion-lint-disable-next-line single-export-per-file
-export const FrameworkOptionsSchema = z
-  .object({
-    contextRouting: z
-      .enum(['path', 'query'], {
-        message: "The routing strategy for context, which can be either 'path' or 'query'.",
-      })
-      .nullish(),
-  })
-  .catchall(z.unknown());
-
-/**
- * Schema for validating the structure of an API application build.
- *
- * Properties:
- * - `version`: The version of the application build.
- * - `entryPoint`: The entry point of the application.
- * - `tags`: An optional array of tags associated with the build.
- * - `tag`: An optional tag indicating the build type (can be any string, commonly 'latest' or 'preview').
- * - `assetPath`: An optional path to the build assets.
- * - `configUrl`: An optional URL to the build configuration.
- * - `timestamp`: An optional timestamp of the build.
- * - `commitSha`: An optional commit SHA of the build.
- * - `githubRepo`: An optional GitHub repository associated with the build.
- * - `projectPage`: An optional project page URL.
- * - `allowedExtensions`: An optional array of allowed extensions for the build.
- * - `options`: An optional record of additional build options, where the key is a string and the value can be of any type.
- * - `uploadedBy`: An optional schema for the person who uploaded the build.
- */
-// Deliberately co-located with ApiApplicationPersonSchema, which it depends on
-// fusion-lint-disable-next-line single-export-per-file
-export const ApiApplicationBuildSchema = z.object({
-  version: z.string(),
-  entryPoint: z.string(),
-  tags: z.array(z.string()).nullish(),
-  tag: z.string().nullish(),
-  assetPath: z.string().nullish(),
-  configUrl: z.string().nullish(),
-  timestamp: z.string().nullish(),
-  commitSha: z.string().nullish(),
-  githubRepo: z.string().nullish(),
-  projectPage: z.string().nullish(),
-  options: FrameworkOptionsSchema.nullish().default({
-    contextRouting: 'path',
-  }),
-  allowedExtensions: z.array(z.string()).nullish(),
-  uploadedBy: ApiApplicationPersonSchema.nullish(),
-});
-
-/**
- * Schema for validating API application data.
- *
- * Properties:
- * - `appKey` (string): Unique key for the application.
- * - `displayName` (string): Display name of the application.
- * - `description` (string): Description of the application.
- * - `type` (string): Type of the application.
- * - `isPinned` (boolean | nullish): Indicates if the application is pinned.
- * - `templateSource` (string | nullish): Source template of the application.
- * - `category` (object | nullish): Category details of the application.
- *   - `id` (string): Unique identifier for the category.
- *   - `name` (string): Name of the category.
- *   - `displayName` (string): Display name of the category.
- *   - `color` (string): Color associated with the category.
- *   - `defaultIcon` (string): Default icon for the category.
- *   - `sortOrder` (number): Sort order for the category.
- * - `visualization` (object | nullish): Visualization details of the application.
- *   - `color` (string | nullish): Color for visualization.
- *   - `icon` (string | nullish): Icon for visualization.
- *   - `sortOrder` (number): Sort order for visualization.
- * - `keywords` (array of strings | nullish): Keywords associated with the application.
- * - `admins` (array of ApiApplicationPersonSchema | nullish): List of admin users for the application.
- * - `owners` (array of ApiApplicationPersonSchema | nullish): List of owner users for the application.
- * - `build` (ApiApplicationBuildSchema | nullish): Build details of the application.
- */
-// Deliberately co-located with ApiApplicationPersonSchema and ApiApplicationBuildSchema, which it depends on
-// fusion-lint-disable-next-line single-export-per-file
-export const ApiApplicationSchema = z.object({
-  appKey: z.string(),
-  displayName: z.string(),
-  description: z.string(),
-  type: z.string(),
-  isPinned: z.boolean().nullish(),
-  templateSource: z.string().nullish(),
-  category: z
-    .object({
-      id: z.string(),
-      name: z.string(),
-      displayName: z.string(),
-      color: z.string(),
-      defaultIcon: z.string(),
-      sortOrder: z.number(),
-    })
-    .nullish(),
-  visualization: z
-    .object({
-      color: z.string().nullish(),
-      icon: z.string().nullish(),
-      sortOrder: z.number(),
-    })
-    .nullish(),
-  keywords: z.array(z.string()).nullish(),
-  admins: z.array(ApiApplicationPersonSchema).nullish(),
-  owners: z.array(ApiApplicationPersonSchema).nullish(),
-  build: ApiApplicationBuildSchema.nullish(),
-});
-
-export type ApiApplication = z.infer<typeof ApiApplicationSchema>;