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

package/src/AppClient.ts

@@ -1,409 +0,0 @@
-import { catchError, map, type Observable, type ObservableInput, tap } from 'rxjs';
-
-import { Query } from '@equinor/fusion-query';
-import { queryValue } from '@equinor/fusion-query/operators';
-
-import {
-  HttpJsonResponseError,
-  HttpResponseError,
-  type IHttpClient,
-} from '@equinor/fusion-framework-module-http';
-import { jsonSelector } from '@equinor/fusion-framework-module-http/selectors';
-
-import { ApiApplicationBuildSchema, ApiApplicationSchema } from './schemas';
-
-import type {
-  AppBuildManifest,
-  AppConfig,
-  AppManifest,
-  AppSettings,
-  ConfigEnvironment,
-} from './types';
-import { AppBuildError, AppConfigError, AppManifestError, AppSettingsError } from './errors';
-import { AppConfigSelector } from './AppConfigSelector';
-
-/**
- * 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 {
-  /**
-   * 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>;
-
-  /**
-   * 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>;
-
-  /**
-   * 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[]>;
-
-  /**
-   * 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>>;
-
-  /**
-   * 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>;
-
-  /**
-   * 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;
-    settings: AppSettings;
-  }) => ObservableInput<AppSettings>;
-}
-
-/**
- * Transforms a raw API application response into an {@link AppManifest},
- * adding backwards-compatible `key` and `name` getters.
- *
- * @returns An object conforming to the AppManifest interface.
- */
-const ApplicationSchema = ApiApplicationSchema.transform((x): AppManifest => {
-  const { category, ...props } = x;
-  return {
-    ...props,
-    // TODO(#5124): remove deprecated appKey
-    get key() {
-      return props.appKey;
-    },
-    // TODO(#5124): remove deprecated name
-    get name() {
-      return props.displayName;
-    },
-    categoryId: category?.id,
-    category,
-  } as AppManifest;
-});
-
-/**
- * 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 class AppClient implements IAppClient {
-  #manifest: Query<AppManifest, { appKey: string }>;
-  #manifests: Query<AppManifest[], { filterByCurrentUser?: boolean } | undefined>;
-  #config: Query<AppConfig, { appKey: string; tag?: string }>;
-  #build: Query<AppBuildManifest, { appKey: string; tag?: string }>;
-  #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;
-
-    const expire = 1 * 60 * 1000;
-
-    this.#build = new Query<AppBuildManifest, { appKey: string; tag?: string }>({
-      client: {
-        fn: ({ appKey, tag }) => {
-          return client.json(`/apps/${appKey}/builds/${tag}`, {
-            headers: {
-              'Api-Version': '1.0',
-            },
-            selector: async (res: Response) =>
-              ApiApplicationBuildSchema.parse(await jsonSelector(res)) as AppBuildManifest,
-          });
-        },
-      },
-      queueOperator: 'merge',
-      key: ({ appKey, tag }) => `${appKey}@${tag}`,
-      expire,
-    });
-
-    this.#manifest = new Query<AppManifest, { appKey: string; tag?: string }>({
-      client: {
-        fn: ({ appKey, tag }) => {
-          return client.json$(tag ? `/apps/${appKey}@${tag}` : `/persons/me/apps/${appKey}`, {
-            headers: {
-              'Api-Version': '1.0',
-            },
-            selector: async (res: Response) => ApplicationSchema.parse(await jsonSelector(res)),
-          });
-        },
-      },
-      queueOperator: 'merge',
-      key: ({ appKey }) => appKey,
-      expire,
-    });
-
-    this.#manifests = new Query<AppManifest[], { filterByCurrentUser?: boolean } | undefined>({
-      client: {
-        fn: (filter) => {
-          const path = filter?.filterByCurrentUser
-            ? '/persons/me/apps'
-            : '/apps?=$expand=category,admins,owners,keywords';
-          return client.json(path, {
-            headers: {
-              'Api-Version': '1.0',
-            },
-            selector: async (res: Response) => {
-              const response = (await jsonSelector(res)) as { value: AppManifest[] };
-              return ApplicationSchema.array().parse(response.value);
-            },
-          });
-        },
-      },
-      key: (filter) => (filter?.filterByCurrentUser ? 'currentUser' : 'all'),
-      expire,
-    });
-
-    this.#config = new Query<AppConfig, { appKey: string; tag?: string }>({
-      client: {
-        fn: ({ appKey, tag = 'latest' }) => {
-          return client.json(`/apps/${appKey}/builds/${tag}/config`, {
-            selector: AppConfigSelector,
-            headers: {
-              'Api-Version': '1.0',
-            },
-          });
-        },
-      },
-      queueOperator: 'merge',
-      key: (args) => JSON.stringify(args),
-      expire,
-    });
-
-    this.#settings = new Query<AppSettings, { appKey: string }>({
-      client: {
-        fn: ({ appKey }) => {
-          return client.json<AppSettings>(`/persons/me/apps/${appKey}/settings`, {
-            headers: {
-              'Api-Version': '1.0',
-            },
-          });
-        },
-      },
-      key: (args) => args.appKey,
-      expire,
-    });
-  }
-
-  /**
-   * 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 });
-        }
-        throw new AppBuildError('unknown', 'failed to load build', { cause });
-      }),
-    );
-  }
-
-  /**
-   * 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 });
-        }
-
-        throw new AppManifestError('unknown', 'failed to load manifest', { cause });
-      }),
-    );
-  }
-
-  /**
-   * 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 });
-        }
-        throw new AppConfigError('unknown', 'failed to load config', { cause });
-      }),
-    );
-  }
-
-  /**
-   * 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 });
-        }
-        throw new AppSettingsError('unknown', 'failed to load settings', { cause });
-      }),
-    );
-  }
-
-  /**
-   * 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
-        .json$<AppSettings>(`/persons/me/apps/${appKey}/settings`, {
-          method: 'PUT',
-          body: settings,
-          headers: {
-            'Api-Version': '1.0',
-          },
-        })
-        // update the settings cache with the persisted value
-        .pipe(
-          tap((value) => {
-            // update cache with new settings
-            this.#settings.mutate(
-              { appKey },
-              {
-                value,
-                updated: Date.now(),
-              },
-            );
-          }),
-        )
-    );
-  }
-
-  /**
-   * Disposes of the client, completing all internal query streams.
-   */
-  [Symbol.dispose]() {
-    console.warn('AppClient disposed');
-    this.#manifest.complete();
-    this.#manifests.complete();
-    this.#config.complete();
-    this.#settings.complete();
-    this.#build.complete();
-  }
-}
-
-export default AppClient;

package/src/AppConfig.ts

@@ -1,99 +0,0 @@
-/**
- * Recursively freezes an object and all of its nested properties.
- *
- * @template T - Object type being frozen.
- * @param obj - The object to deep-freeze.
- * @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 &&
-      !Object.isFrozen(obj[property])
-    ) {
-      deepFreeze(obj[property] as Record<string, unknown>);
-    }
-  }
-  return Object.freeze(obj);
-};
-
-/**
- * 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[];
-};
-
-/**
- * Class representing the application configuration.
- *
- * @template TEnvironment - The type of the environment configuration, extending `ConfigEnvironment`.
- *
- * @remarks
- * The `AppConfig` class provides a way to manage application configuration, including environment settings and endpoints.
- *
- * @example
- * ```typescript
- * const config = new AppConfig({
- *   environment: { ... },
- *   endpoints: {
- *     api: { url: 'https://api.example.com' }
- *   }
- * });
- *
- * console.log(config.getEndpoint('api')); // { url: 'https://api.example.com' }
- * ```
- */
-export class AppConfig<TEnvironment extends ConfigEnvironment = ConfigEnvironment> {
-  #endpoints: Record<string, ConfigEndPoint>;
-  #environment: TEnvironment;
-
-  /**
-   * The environment configuration for the application.
-   * @returns The frozen environment configuration.
-   */
-  get environment(): TEnvironment {
-    return this.#environment;
-  }
-
-  /**
-   * 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>;
-  }) {
-    this.#environment = deepFreeze(config.environment ?? {}) as TEnvironment;
-    this.#endpoints = deepFreeze(config.endpoints ?? {});
-  }
-
-  /**
-   * Retrieves the configuration endpoint associated with the given key.
-   *
-   * @param key - The key corresponding to the desired configuration endpoint.
-   * @returns The configuration endpoint if found, otherwise `undefined`.
-   */
-  getEndpoint(key: string): ConfigEndPoint | undefined {
-    return this.#endpoints[key];
-  }
-}

package/src/AppConfigSelector.ts

@@ -1,25 +0,0 @@
-import {
-  jsonSelector,
-  type ResponseSelector,
-} from '@equinor/fusion-framework-module-http/selectors';
-
-import { AppConfig } from './AppConfig';
-import { ApiAppConfigSchema } from './schemas';
-
-/**
- * Asynchronously selects and parses the application configuration from the given response.
- *
- * @param response - The response object to select and parse the application configuration from.
- * @returns A promise that resolves to an instance of `AppConfig` containing the parsed configuration data.
- *
- * @throws Will throw an error if the response cannot be parsed or does not conform to the expected schema.
- */
-export const AppConfigSelector: ResponseSelector<AppConfig> = async (response) => {
-  // Select the JSON data from the response
-  const raw = await jsonSelector(response);
-
-  // Parse the JSON data using the API application configuration schema
-  const data = ApiAppConfigSchema.parse(raw);
-
-  return new AppConfig(data);
-};

package/src/AppConfigurator.ts

@@ -1,145 +0,0 @@
-import {
-  BaseConfigBuilder,
-  type ConfigBuilderCallback,
-  type ModuleInitializerArgs,
-} from '@equinor/fusion-framework-module';
-import type { HttpModule, IHttpClient } from '@equinor/fusion-framework-module-http';
-import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
-
-import AppClient, { 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 class AppConfigurator
-  extends BaseConfigBuilder<AppModuleConfig>
-  implements IAppConfigurator
-{
-  /** Default cache expiration time, in milliseconds, for the app service client. */
-  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]>,
-  ): Promise<IHttpClient> {
-    const http = await init.requireInstance('http');
-    const serviceName = 'apps';
-    /** check if the http provider has configure a client */
-    if (http.hasClient(serviceName)) {
-      return http.createClient(serviceName);
-    }
-
-    /** load service discovery module */
-    const serviceDiscovery = await init.requireInstance('serviceDiscovery');
-
-    // 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']>
-      | ConfigBuilderCallback<AppModuleConfig['client']>,
-  ) {
-    const cb = typeof client_or_cb === 'object' ? () => client_or_cb : client_or_cb;
-    this._set('client', cb);
-  }
-
-  /**
-   * 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);
-        const appClient = new AppClient(httpClient);
-        return appClient;
-      });
-    }
-
-    // fall back to the default proxy asset uri
-    if (!this._has('assetUri')) {
-      this.setAssetUri('/apps-proxy');
-    }
-
-    return super._createConfig(init, initial);
-  }
-}