Fusion Framework HTTP Module

@equinor/fusion-framework-module-http is the HTTP layer for Fusion Framework applications and modules. It gives you a fetch-style client factory with framework-aware configuration, MSAL-aware requests, RxJS observables, and reusable request/response pipelines.

If you only remember one thing about this package, make it this: you configure clients once, and you create fresh client instances when you use them.

If you are new to Fusion Framework or just want to call an API, start with configureHttpClient(...), createClient(...), and json().

If you are building more advanced workflows, this package also supports RxJS observable composition, request and response stream inspection, custom selectors, request and response operators, MSAL-aware requests, and server-sent events.

What This Package Gives You

• Named HTTP client configurations for each backend you talk to.
• Fresh client instances so headers and handlers from one usage do not leak into the next.
• Promise and Observable APIs on top of the same request pipeline.
• Built-in support for JSON, blobs, and server-sent events.
• Request and response handlers for cross-cutting behavior.
• MSAL scope support when the auth module is available.

Mental Model

Think of the HTTP module as a client factory, not a singleton HTTP client.

1. Configure a named client during app or module setup.
2. Call createClient(name) when you need to make requests.
3. Use fetch, json, blob, or sse$ on that client instance.
4. Add shared behavior in onCreate, requestHandler, and responseHandler.

Each request goes through the same high-level flow:

1. Resolve baseUri and request path into a full URL.
2. Run request handlers.
3. Emit the request on request$.
4. Execute the fetch call.
5. Run response handlers.
6. Emit the response on response$.
7. Apply an optional selector.

Start Here If You Are New

The simplest useful path looks like this:

1. Register a named client for one backend.
2. Create a client from that name where you need it.
3. Call json() for normal API calls.

That gives you:

• consistent base URLs
• shared auth scope configuration
• shared headers or guards through onCreate
• one fresh client instance per usage

If you are unsure whether to use promises or observables, start with json(). Move to json$() when you need RxJS operators, cancellation by unsubscribe, or stream composition.

When To Use Which API

Install

pnpm add @equinor/fusion-framework-module-http

Quick Start

Configure a named client during setup:

configurator.configureHttpClient('catalog', {
  baseUri: '/api/catalog',
  defaultScopes: ['api://catalog-api/.default'],
  onCreate: (client) => {
    client.requestHandler.setHeader('X-App-Name', 'portal');
  },
});

Use the configured client after the framework is initialized:

type CatalogItem = {
  id: string;
  title: string;
};

const client = framework.modules.http.createClient('catalog');
const items = await client.json<CatalogItem[]>('/items');

What is happening here:

• catalog is a named configuration, not a long-lived shared client instance.
• createClient('catalog') creates a fresh client with the configured base URI, handlers, and default scopes.
• json() runs the request pipeline and returns parsed JSON.

Public Entry Points

For most teams, the top-level package plus the selectors or operators subpaths are enough.

Configuring Clients

Use named clients when you want a stable configuration for a backend: a base URL, default MSAL scopes, shared headers, and request or response policies.

The HTTP module supports three common configuration styles:

• named clients with configureHttpClient(name, options)
• lower-level module configuration with configureHttp(...)
• ad-hoc clients with createClient({ baseUri }) or createClient('https://...')

MSAL scope behavior is part of client configuration:

• defaultScopes belong to the configured client
• per-request scopes are appended to defaultScopes
• token acquisition only happens when the auth module is available and the final scope list is non-empty

See Client Configuration for configuration options, onCreate, direct module integration, custom client classes, ad-hoc clients, and ClientNotFoundException behavior.

Core API

Each call to createClient() returns a fresh instance with its own handler state.

Deprecated aliases still exist, but new code should prefer fetch() and json() over fetchAsync() and jsonAsync().

Promise Or Observable?

• Use promise methods when you just want the result of a single request.
• Use observable methods when you want RxJS composition, cancellation by unsubscribe, or stream-based integration.
• Observable methods are cold. Nothing is sent until you subscribe.
• Promise methods are implemented with firstValueFrom(...) on the corresponding observable method.
• request$ and response$ let you observe outgoing requests and incoming responses for that client instance.

In practical terms:

• json('/items') is the simplest choice for page load or command-style calls.
• json$('/items') is the better choice when the request depends on another stream such as route params, user selections, debounced search terms, refresh triggers, or SSE event handling.

See Observable Patterns for RxJS composition, cancellation, request and response inspection, and selector reuse.

Selectors And Handlers

Selectors and handlers solve different problems:

• selectors shape the response value your application consumes
• request handlers shape outgoing transport behavior
• response handlers enforce response policies before selector parsing runs

Built-in selectors include jsonSelector, blobSelector, and createSseSelector. The default request pipeline includes capitalizeRequestMethodOperator() and requestValidationOperator().

See Selectors and Handlers for guidance on when to use each API, how to add reusable operators, and how to keep transport concerns separate from response parsing.

Server-Sent Events

Use client.sse$() when the endpoint returns text/event-stream and you want parsed event objects instead of manually reading the stream. For lower-level composition, use createSseSelector or sseMap.

See Server-Sent Events for sse$() usage, event filtering, heartbeat handling, abort behavior, lower-level SSE helpers, and ServerSentEventResponseError handling.

Error Types

Native fetch errors can still surface as well, including abort and network failures.

Testing

Register a short-circuiting middleware through configurator.http.addMiddleware(...) to answer requests without touching the network — no separate mock client or configurator is needed. createOpenApiMockMiddleware (@equinor/fusion-framework-module-http/mock) adapts an @equinor/fusion-openapi-mock instance into one for faking an entire OpenAPI document.

See Testing for the middleware contract and createOpenApiMockMiddleware.

Advanced Guides

• Client Configuration: named clients, configureHttpClient, configureHttp, onCreate, custom client classes, and ad-hoc clients
• Observable Patterns: fetch$, json$, request$, response$, cancellation, and RxJS composition
• Selectors and Handlers: jsonSelector, blobSelector, request handlers, response handlers, and built-in operators
• Server-Sent Events: sse$, createSseSelector, sseMap, event filtering, heartbeats, and abort behavior
• Testing: the middleware contract, addMiddleware, and createOpenApiMockMiddleware

Things To Remember

• createClient(name) throws ClientNotFoundException for unknown client keys.
• hasClient(name) is useful when a client configuration may be optional.
• json() and json$() stringify object bodies with JSON.stringify(...) and append JSON request headers.
• fetch() and fetch$() leave the response untouched unless you provide a selector.
• execute() currently supports fetch, fetch$, json, and json$ only.
• If you configure a client through config.http.configureClient(name, callback), that callback is stored as onCreate and runs every time a new client instance is created.