@equinor/fusion-framework-app 13.1.0 → 13.1.2

package/docs/bookmarks.md

@@ -1,18 +0,0 @@
-# Enable Bookmarks
-
-The bookmark module allows applications to save and restore application state.
-
-> **Important:** Import `enableBookmark` from the app-level package, not from
-> `@equinor/fusion-framework-module-bookmark` directly.
-
-```ts
-import { configureModules } from '@equinor/fusion-framework-app';
-import { enableBookmark } from '@equinor/fusion-framework-app/enable-bookmark';
-
-const initialize = configureModules((configurator) => {
-  enableBookmark(configurator);
-});
-```
-
-Payload generators registered through the bookmark module are automatically
-cleaned up when the module is disposed.

package/docs/http-clients.md

@@ -1,121 +0,0 @@
-# Configure HTTP Clients
-
-The `AppConfigurator` can register named HTTP clients from several sources.
-You retrieve a client at runtime with `framework.modules.http.createClient(name)`.
-
-## From Application Config (auto-registration)
-
-Endpoints defined in `app.config.<env>.ts` are **automatically registered as
-named HTTP clients** when the `AppConfigurator` is created — no extra code
-needed in `config.ts`.
-
-```ts
-// app.config.ts
-import { defineAppConfig } from '@equinor/fusion-framework-cli/app';
-
-export default defineAppConfig(() => ({
-  endpoints: {
-    schedule: {
-      url: 'https://schedule-api.example.com',
-      scopes: ['api://schedule-id/.default'],
-    },
-  },
-}));
-```
-
-After initialization, use the client directly:
-
-```ts
-const client = framework.modules.http.createClient('schedule');
-const data = await client.json('/items');
-```
-
-### Mock an application-config endpoint locally
-
-Use a direct-only executable service when an app-owned endpoint needs a local OpenAPI mock but
-must not appear in service discovery:
-
-```ts
-// mocks/my-api.mock.ts
-import schema from './my-api.openapi.json' with { type: 'json' };
-import { defineService } from '@equinor/fusion-openapi-mock-server/discovery';
-
-export default defineService({
-  key: 'my-api',
-  serviceDiscovery: false,
-  schema,
-});
-```
-
-Point the development environment at the service's `<key>.localhost` origin:
-
-```ts
-// app.config.local.ts
-import { defineAppConfig } from '@equinor/fusion-framework-cli/app';
-
-export default defineAppConfig(() => ({
-  endpoints: {
-    'my-api': {
-      url: 'http://my-api.localhost:4010',
-    },
-  },
-}));
-```
-
-Start both foreground processes:
-
-```sh
-ffc mock-server
-ffc app dev
-```
-
-`serviceDiscovery: false` keeps `my-api` out of discovery while the mock server continues serving
-it directly. The mock server handles browser CORS for these per-service origins, so this workflow
-does not require an `/@fusion-api` proxy route or handwritten `dev-server.config.ts` middleware.
-Restart `ffc app dev` after changing `app.config.<env>.ts`; application config files are resolved at
-startup rather than watched for changes.
-
-The `--mock` flag is optional here. It changes where service discovery comes from, but the
-app-owned `endpoints` entry remains explicit in application config. See
-[Develop with mock services](../../dev-server/docs/mocking.md) for discovery modes and isolated
-mock development.
-
-## Via Service Discovery
-
-```ts
-const initialize = configureModules((configurator) => {
-  configurator.useFrameworkServiceClient('people');
-});
-```
-
-## Explicit Registration
-
-Use `configureHttpClient` in `config.ts` when the endpoint is **not** in
-`app.config.ts`, or when you need custom transport behavior such as headers,
-response guards, or a custom client class.
-
-```ts
-configurator.configureHttpClient('custom-api', {
-  baseUri: 'https://custom.api.example.com',
-  defaultScopes: ['api://custom-id/.default'],
-  onCreate: (client) => {
-    client.requestHandler.setHeader('X-Source', 'portal');
-  },
-});
-```
-
-## Resolution Priority
-
-When the same client name is configured in more than one place, the
-highest-priority source wins:
-
-| Priority | Source | Example |
-|----------|--------|---------|
-| 1 (highest) | **Session overrides** | User-specific URL / scopes set at runtime via `sessionStorage` |
-| 2 | **Application config endpoints** | `endpoints` in `app.config.ts` |
-| 3 | **Service-discovery registry** | Resolved via `useFrameworkServiceClient` |
-| 4 (lowest) | **Explicit registration** | `configureHttpClient(name, options)` in `config.ts` |
-
-This means an endpoint defined in `app.config.ts` will override a
-`configureHttpClient` call for the same name, and a session override will
-override both.

package/docs/testing.md

@@ -1,105 +0,0 @@
-# Testing
-
-`@equinor/fusion-framework-app/mock` runs an application's real module pipeline in
-tests — the real `event`/`http`/`msal` modules, the real `AppConfigurator`
-configuration pipeline, and real lifecycle — while only the boundaries that reach
-outside the process (network access, credentials, a running parent portal) are
-substituted with deterministic fakes. This entry point has no dependency on
-Vitest or any other test runner.
-
-```ts
-import { mockAppModules } from '@equinor/fusion-framework-app/mock';
-
-const manifest = { appKey: 'my-app', displayName: 'My App', description: 'My app', type: 'standalone' } as const;
-const modules = await mockAppModules(undefined, { manifest });
-```
-
-## `mockAppModules(cb, env, fusion?)`
-
-Runs the same pipeline `configureModules` produces, against a mocked parent.
-`cb` receives an `AppMockConfigurator` — which *is* an `AppConfigurator`, so
-`useFrameworkServiceClient`, `configureHttpClient`, and any callback written for
-a real app work against it unchanged.
-
-- `cb` — configuration callback, or `undefined` to skip it.
-- `env` — the application environment (`manifest`, `config`, `basename`).
-- `fusion` — optional parent Fusion instance. Defaults to a fresh `mockFramework`
-  instance with `app` already enabled and this app's own manifest and config
-  served (see `enableAppManifestMock` below).
-
-```ts
-const manifest = { appKey: 'my-app', displayName: 'My App', description: 'My app', type: 'standalone' } as const;
-
-const modules = await mockAppModules(
-  (configurator) => {
-    configurator.useFrameworkServiceClient('portal-api');
-    configurator.http.addMiddleware(async (uri, init, next) =>
-      uri === 'https://portal-api.fusion.test/items' ? Response.json([{ id: 1 }]) : next(uri, init),
-    );
-  },
-  { manifest },
-);
-
-const items = await modules.http.createClient('portal-api').json('/items');
-```
-
-The default parent's own `app` module (not `mockAppModules`'s returned `modules`)
-only resolves `env.manifest`/`env.config` locally for `env.manifest.appKey` —
-setting the current app to any other key falls through to whatever the parent's
-real `app` module would do (a real service-discovery-resolved request, or
-nothing if `serviceDiscovery` was never pointed anywhere):
-
-```ts
-import type { Fusion } from '@equinor/fusion-framework';
-import type { AppModule } from '@equinor/fusion-framework-module-app';
-
-await mockAppModules(async (_configurator, { fusion }) => {
-  // the default parent always has `app` enabled; cast narrows the module set
-  // for callers that pass in a parent without it
-  const { app } = (fusion as Fusion<[AppModule]>).modules;
-
-  app.setCurrentApp(env.manifest.appKey);
-  await app.current?.getManifestAsync(); // resolves with env.manifest
-
-  app.setCurrentApp('some-other-app');
-  await app.current?.getManifestAsync(); // rejects — not this app's own manifest
-}, env);
-```
-
-## `enableAppManifestMock(configurator, env)`
-
-Registers the `app` module on a parent `mockFramework` configurator, serving
-`env.manifest` and `env.config` for this app's own `appKey` while delegating
-every other request — other app keys, tagged requests, builds, settings — to
-whatever client service discovery (or a pre-configured http client) would really
-resolve. `mockAppModules` uses this to build its zero-config default parent;
-call it directly when a test needs to customize `serviceDiscovery` (e.g. point
-it at a real local mock server) while keeping this app's own manifest and
-config servable.
-
-```ts
-import { mockFramework } from '@equinor/fusion-framework/mock';
-import type { AppModule } from '@equinor/fusion-framework-module-app';
-import { enableAppManifestMock, mockAppModules } from '@equinor/fusion-framework-app/mock';
-
-const env = { manifest: { appKey: 'my-app', displayName: 'My App', description: 'My app', type: 'standalone' } as const };
-
-const fusion = await mockFramework<[AppModule]>((configurator) => {
-  configurator.serviceDiscovery.setBaseUri('http://localhost:9999');
-  enableAppManifestMock(configurator, env);
-});
-
-const modules = await mockAppModules(undefined, env, fusion);
-```
-
-## `AppMockConfigurator`
-
-The configurator type passed to `mockAppModules`'s `cb`. It extends the real
-`AppConfigurator`, so any configuration code written against a real app — named
-HTTP clients, service-discovery clients, bookmark setup — works unchanged
-against it in a test.
-
-## Related
-
-- [`@equinor/fusion-framework/mock`](../../framework/docs/testing.md) — mock every framework boundary at once, for building a custom parent `fusion` instance.
-- [`@equinor/fusion-framework-module-app/mock`](../../modules/app/README.md) — the lower-level `MockAppClient` this package's mock wiring is built on.

package/src/AppConfigurator.ts

@@ -1,280 +0,0 @@
-import type { FusionModulesInstance } from '@equinor/fusion-framework';
-
-import {
-  type AnyModule,
-  type IModulesConfigurator,
-  ModulesConfigurator,
-} from '@equinor/fusion-framework-module';
-
-import event from '@equinor/fusion-framework-module-event';
-
-import http, {
-  configureHttpClient,
-  configureHttp,
-  type HttpClientOptions,
-} from '@equinor/fusion-framework-module-http';
-
-import auth from '@equinor/fusion-framework-module-msal';
-
-import type { AppEnv, AppModules } from './types';
-import { AppModulesConfiguredEvent } from './AppModulesConfiguredEvent';
-import { AppConfiguratorError } from './AppConfiguratorError';
-import { deepClone, deepFreeze, type DeepImmutable } from './utils';
-
-/**
- * Type definition for AppConfigurator constructor
- */
-export type AppConfiguratorConstructor<
-  TModules extends readonly AnyModule[] = [],
-  TRef extends FusionModulesInstance = FusionModulesInstance,
-  TEnv extends AppEnv = AppEnv,
-> = {
-  new (env: TEnv, ref?: TRef): IAppConfigurator<TModules, TRef>;
-};
-
-/**
- * Contract for configuring Fusion application modules.
- *
- * `IAppConfigurator` extends the base module configurator with application-specific
- * methods for setting up HTTP clients and integrating with Fusion service discovery.
- * Use this interface when typing configuration callbacks that receive the configurator.
- *
- * @template TModules - Additional application-specific modules to register beyond the defaults.
- * @template TRef - The resolved Fusion modules instance used as a reference during initialization.
- *
- * @example
- * ```ts
- * import type { IAppConfigurator } from '@equinor/fusion-framework-app';
- *
- * const configure = (configurator: IAppConfigurator) => {
- *   configurator.configureHttpClient('myApi', {
- *     baseUri: 'https://api.example.com',
- *     defaultScopes: ['api://client-id/.default'],
- *   });
- * };
- * ```
- */
-export interface IAppConfigurator<
-  TModules extends Array<AnyModule> | unknown = unknown,
-  TRef extends FusionModulesInstance = FusionModulesInstance,
-> extends IModulesConfigurator<AppModules<TModules>, TRef> {
-  readonly manifest: DeepImmutable<AppEnv['manifest']>;
-
-  /**
-   * Configure the HTTP module with custom settings.
-   *
-   * Delegates to the framework `configureHttp` helper. Use this when you need
-   * low-level control over the HTTP module configuration. For most applications,
-   * prefer {@link IAppConfigurator.configureHttpClient | configureHttpClient} instead.
-   *
-   * @param args - Arguments forwarded to the framework `configureHttp` function.
-   */
-  configureHttp(...args: Parameters<typeof configureHttp>): void;
-
-  /**
-   * Register a named HTTP client with explicit base URI and authentication scopes.
-   *
-   * Use this method when the application needs to call a specific API endpoint
-   * that is not provided through Fusion service discovery.
-   *
-   * @param args - Arguments forwarded to the framework `configureHttpClient` function.
-   *
-   * @example
-   * ```ts
-   * configurator.configureHttpClient('myClient', {
-   *   baseUri: 'https://foo.bar',
-   *   defaultScopes: ['api://client-id/.default'],
-   * });
-   * ```
-   */
-  configureHttpClient(...args: Parameters<typeof configureHttpClient>): void;
-
-  /**
-   * Register a named HTTP client resolved through Fusion service discovery.
-   *
-   * The `serviceName` is looked up in the portal’s service-discovery registry at
-   * initialization time. Base URI and default scopes are resolved automatically.
-   * Use this instead of {@link IAppConfigurator.configureHttpClient | configureHttpClient}
-   * when the service is registered with the Fusion portal.
-   *
-   * @param serviceName - Registered name of the service in Fusion service discovery.
-   * @param options - Optional HTTP client overrides (headers, interceptors, etc.).
-   *                  `baseUri` and `defaultScopes` are excluded because they are
-   *                  resolved from service discovery.
-   */
-  // TODO(#5060): rename
-  useFrameworkServiceClient(
-    serviceName: string,
-    // biome-ignore lint/suspicious/noExplicitAny: `HttpClientOptions<any>` widens to accept options for any request payload type
-    options?: Omit<HttpClientOptions<any>, 'baseUri' | 'defaultScopes'>,
-  ): void;
-}
-
-/**
- * Configurator that bootstraps default Fusion application modules and provides
- * helper methods for HTTP client and service-discovery setup.
- *
- * `AppConfigurator` is created internally by {@link configureModules}. It registers
- * the `event`, `http`, and `msal` (auth) modules by default and reads any HTTP
- * endpoints declared in the application's environment config.
- *
- * @template TModules - Additional application-specific modules beyond the defaults.
- * @template TRef - The resolved Fusion modules instance used as an initialization reference.
- * @template TEnv - The application environment descriptor (manifest, config, basename).
- *
- * @example
- * ```ts
- * // Typically used indirectly via configureModules:
- * import { configureModules } from '@equinor/fusion-framework-app';
- *
- * const initialize = configureModules((configurator) => {
- *   configurator.useFrameworkServiceClient('my-service');
- * });
- * ```
- */
-export class AppConfigurator<
-    TModules extends Array<AnyModule> | unknown = unknown,
-    TRef extends FusionModulesInstance = FusionModulesInstance,
-    TEnv extends AppEnv = AppEnv,
-  >
-  extends ModulesConfigurator<AppModules<TModules>, TRef>
-  implements IAppConfigurator<TModules, TRef>
-{
-  /**
-   * The class name used for event naming. This static property ensures
-   * the name is preserved through compilation and minification.
-   */
-  static readonly className: string = 'AppConfigurator';
-
-  #manifest: DeepImmutable<AppEnv['manifest']>;
-
-  /**
-   * Create an application configurator with default modules and environment.
-   *
-   * Registers the `event`, `http`, and `msal` modules and pre-configures any
-   * HTTP clients declared in `env.config.endpoints`.
-   *
-   * @param env - The application environment containing manifest, config, and optional basename.
-   * @param ref - Optional reference to the Fusion modules instance, used for event dispatching.
-   */
-  constructor(
-    public readonly env: TEnv,
-    ref?: TRef,
-  ) {
-    super([event, http, auth]);
-    this.#manifest = deepFreeze(deepClone(env.manifest));
-    this._configureHttpClientsFromAppConfig();
-
-    this.onConfigured((configs) => {
-      const configuredEvent = new AppModulesConfiguredEvent<TModules>({
-        detail: {
-          appKey: this.#manifest.appKey,
-          configs,
-        },
-      });
-      ref?.event.dispatchEvent(configuredEvent);
-    });
-  }
-
-  /**
-   * The immutable application manifest.
-   *
-   * Deeply frozen at construction time to prevent accidental mutations.
-   *
-   * @returns The deeply immutable application manifest.
-   */
-  get manifest(): DeepImmutable<AppEnv['manifest']> {
-    return this.#manifest;
-  }
-
-  /**
-   * Read HTTP endpoint definitions from the application config and register each
-   * one as a named HTTP client.
-   *
-   * Iterates over `env.config.endpoints` and calls
-   * {@link IAppConfigurator.configureHttpClient | configureHttpClient} for each entry.
-   */
-  protected _configureHttpClientsFromAppConfig() {
-    const { endpoints = {} } = this.env.config ?? {};
-    // Register an HTTP client for each endpoint defined in the app configuration.
-    for (const [key, { url, scopes }] of Object.entries(endpoints)) {
-      this.configureHttpClient(key, {
-        baseUri: url,
-        defaultScopes: scopes,
-      });
-    }
-  }
-
-  /** {@inheritDoc IAppConfigurator.configureHttp} */
-  public configureHttp(...args: Parameters<typeof configureHttp>): void {
-    this.addConfig(configureHttp(...args));
-  }
-
-  /** {@inheritDoc IAppConfigurator.configureHttpClient} */
-  public configureHttpClient(...args: Parameters<typeof configureHttpClient>): void {
-    this.addConfig(configureHttpClient(...args));
-  }
-
-  /**
-   * Register a named HTTP client whose base URI and scopes are resolved via
-   * Fusion service discovery.
-   *
-   * Resolution priority (highest wins):
-   * 1. Session overrides (user-specific URL / scopes)
-   * 2. Application config (`env.config.endpoints`)
-   * 3. Service-discovery registry
-   *
-   * If a client with the same `serviceName` is already registered (e.g. from
-   * app config) and the service has **not** been overridden at session level,
-   * a warning is logged and the existing configuration is kept.
-   *
-   * @param serviceName - Registered name of the service in Fusion service discovery.
-   * @param options - Optional HTTP client overrides. `baseUri` and `defaultScopes`
-   *                  are excluded because they come from service discovery.
-   * @throws {Error} When the service cannot be resolved from service discovery.
-   *
-   * @example
-   * ```ts
-   * configurator.useFrameworkServiceClient('my-backend-service');
-   * ```
-   */
-  public useFrameworkServiceClient(
-    serviceName: string,
-    // biome-ignore lint/suspicious/noExplicitAny: `HttpClientOptions<any>` widens to accept options for any request payload type
-    options?: Omit<HttpClientOptions<any>, 'baseUri' | 'defaultScopes'>,
-  ): void {
-    this.addConfig({
-      module: http,
-      configure: async (config, ref) => {
-        // Service from serviceDiscovery with potential session override.
-        const service = await ref?.serviceDiscovery.resolveService(serviceName);
-        // Guard: service must resolve before the HTTP client can be configured.
-        if (!service) {
-          throw new AppConfiguratorError(
-            `Unable to resolve service [${serviceName}] during configuration.`,
-            'configuration',
-          );
-        }
-
-        // Check if serviceName is already configured (potentially with app-config)
-        // If the service is session overridden - we need the configuration to run
-        // as normal (the uri already updated).
-        if (config.hasClient(serviceName) && !service.overridden) {
-          console.warn(
-            `${serviceName} is already configured, possibly by app.config.[ENV].ts.
-             Overriding configurations may lead to unintended behaviour and should
-             be reviewed carefully.`,
-          );
-          return;
-        }
-        config.configureClient(serviceName, {
-          ...options,
-          baseUri: service.uri,
-          defaultScopes: service.defaultScopes,
-        });
-      },
-    });
-  }
-}
-
-export default AppConfigurator;

package/src/AppConfiguratorError.ts

@@ -1,34 +0,0 @@
-/**
- * Custom error class for application configurator errors.
- *
- * Provides error context to help developers debug configuration and initialization issues.
- *
- * @example
- * ```ts
- * try {
- *   const modules = await initialize({ fusion, env });
- * } catch (error) {
- *   if (error instanceof AppConfiguratorError) {
- *     console.log(`Error in ${error.phase}: ${error.message}`);
- *   }
- * }
- * ```
- */
-export class AppConfiguratorError extends Error {
-  /**
-   * @param message - Human-readable error description
-   * @param phase - The phase where the error occurred
-   * @param cause - The underlying error that caused this failure
-   */
-  constructor(
-    message: string,
-    public readonly phase: 'configuration' | 'initialization',
-    cause?: unknown,
-  ) {
-    super(message);
-    this.name = 'AppConfiguratorError';
-    this.cause = cause;
-  }
-}
-
-export default AppConfiguratorError;

package/src/AppModulesConfiguredEvent.ts

@@ -1,43 +0,0 @@
-import type { ModulesConfigType, AnyModule } from '@equinor/fusion-framework-module';
-import type { AppModules } from '@equinor/fusion-framework-module-app';
-import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-import type { AppModulesInitializedEvent } from './AppModulesInitializedEvent';
-
-/**
- * Represents the initialization data for an event indicating that application modules have been configured.
- *
- * @template T - Array of additional modules configured in the application.
- * @extends FrameworkEventInit
- * @property {string} appKey - The unique key identifying the application.
- * @property {ModulesConfigType<AppModules<T>>} configs - The configuration objects for the specified application modules.
- */
-type AppModulesConfiguredEventInit<T extends AnyModule[] | unknown = unknown> = FrameworkEventInit<{
-  appKey: string;
-  configs: ModulesConfigType<AppModules<T>>;
-}>;
-
-/**
- * Event emitted when application modules have been configured.
- *
- * @template T - An array of additional modules configured in the application.
- * @extends FrameworkEvent<AppModulesConfiguredEventInit<T>>
- */
-export class AppModulesConfiguredEvent<
-  T extends AnyModule[] | unknown = unknown,
-> extends FrameworkEvent<AppModulesConfiguredEventInit<T>> {
-  /**
-   * Create an event describing configured application modules.
-   *
-   * @param init - Event initialization data containing the application key and module configs.
-   */
-  constructor(init: AppModulesConfiguredEventInit<T>) {
-    super('onAppModulesConfigured', init);
-  }
-}
-
-declare module '@equinor/fusion-framework-module-event' {
-  interface FrameworkEventMap {
-    onAppModulesConfigured: AppModulesConfiguredEvent;
-    onAppModulesInitialized: AppModulesInitializedEvent;
-  }
-}

package/src/AppModulesInitializedEvent.ts

@@ -1,40 +0,0 @@
-import type { AnyModule } from '@equinor/fusion-framework-module';
-import type { AppModulesInstance } from '@equinor/fusion-framework-module-app';
-import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-
-/**
- * Event initialization type for the "AppModulesInitialized" event.
- *
- * @template T - An array of module types extending `AnyModule`. Defaults to an empty array.
- * @property appKey - The unique key identifying the application.
- * @property modules - The instance containing all initialized application modules.
- */
-type AppModulesInitializedEventInit<T extends AnyModule[] | unknown = unknown> =
-  FrameworkEventInit<{
-    appKey: string;
-    modules: AppModulesInstance<T>;
-  }>;
-
-/**
- * Event triggered when application modules have been initialized.
- *
- * @template T - An array of modules extending `AnyModule`. Defaults to an empty array.
- * @extends FrameworkEvent<AppModulesInitializedEventInit<T>>
- *
- * @example
- * ```typescript
- * const event = new AppModulesInitializedEvent({ modules: [...] });
- * ```
- */
-export class AppModulesInitializedEvent<
-  T extends AnyModule[] | unknown = unknown,
-> extends FrameworkEvent<AppModulesInitializedEventInit<T>> {
-  /**
-   * Create an event describing initialized application modules.
-   *
-   * @param init - Event initialization data containing the application key and module instance.
-   */
-  constructor(init: AppModulesInitializedEventInit<T>) {
-    super('onAppModulesInitialized', init);
-  }
-}