@equinor/fusion-framework-module-http 7.0.8 → 8.0.0

package/docs/selectors-and-handlers.md

@@ -0,0 +1,112 @@
+# Selectors And Handlers
+
+Selectors and handlers are related, but they solve different problems.
+
+- selectors transform a `Response` into the value your application consumes
+- request handlers shape or validate the outgoing request
+- response handlers apply transport-level response rules before selector parsing runs
+
+Use this split to keep parsing logic separate from transport policy.
+
+## Choose The Right Tool
+
+| Need | Use |
+| --- | --- |
+| Parse JSON, blobs, or SSE events | selector |
+| Add headers, normalize methods, validate request shape | request handler |
+| Reject certain responses before parsing | response handler |
+| Reuse parsing rules across multiple calls | selector |
+| Reuse transport behavior across a client configuration | handler |
+
+## Built-In Selectors
+
+| Selector | What it returns | Notes |
+| --- | --- | --- |
+| `jsonSelector` | parsed JSON or `undefined` for `204` | Throws `HttpJsonResponseError` on non-OK responses and includes parsed error payloads when possible |
+| `blobSelector` | `{ filename?, blob }` | Extracts `filename` from the `content-disposition` header when present |
+| `createSseSelector` | `Observable<ServerSentEvent<T>>` | Lower-level SSE selector used by `client.sse$()` |
+
+## Custom Selector Example
+
+```typescript
+import {
+  jsonSelector,
+  type ResponseSelector,
+} from '@equinor/fusion-framework-module-http/selectors';
+
+type User = {
+  id: string;
+  name: string;
+};
+
+const userSelector: ResponseSelector<User> = async (response) => {
+  const data = await jsonSelector<User>(response);
+  return {
+    ...data,
+    name: data.name.trim(),
+  };
+};
+```
+
+That selector can then be passed to `client.fetch('/users/42', { selector: userSelector })`.
+
+## Request And Response Handlers
+
+Handlers are sequential operator pipelines attached to each client instance.
+
+- `add(key, operator)` throws if the key already exists
+- `set(key, operator)` adds or replaces an operator
+- `remove(key)` removes an operator
+- returning `void` keeps the previous value flowing through the pipeline
+- operators run in insertion order
+
+The public handler types and utilities are exported from `@equinor/fusion-framework-module-http/operators`.
+
+## Default Request Pipeline
+
+Each created client starts with a default request pipeline containing:
+
+1. `capitalizeRequestMethodOperator()`
+2. `requestValidationOperator()`
+
+That means lowercase methods are normalized to uppercase and request options are validated in non-throwing mode by default.
+
+## Built-In Request Operators
+
+- `capitalizeRequestMethodOperator(options?)` uppercases `request.method` and can suppress warnings with `silent: true`
+- `requestValidationOperator(options?)` validates the request against the package schema and can optionally return parsed values
+
+## Example: Configure Both Parsing And Transport
+
+```typescript
+import {
+  capitalizeRequestMethodOperator,
+  requestValidationOperator,
+} from '@equinor/fusion-framework-module-http/operators';
+
+configurator.configureHttpClient('catalog', {
+  baseUri: '/api/catalog',
+  onCreate: (client) => {
+    client.requestHandler.set('validate-strict', requestValidationOperator({
+      parse: true,
+      strict: true,
+    }));
+
+    client.requestHandler.add('normalize-method', capitalizeRequestMethodOperator());
+
+    client.responseHandler.add('reject-server-errors', (response) => {
+      if (response.status >= 500) {
+        throw new Error(`Unexpected response status: ${response.status}`);
+      }
+    });
+  },
+});
+```
+
+## Rule Of Thumb
+
+- use handlers for cross-cutting transport concerns such as headers, validation, logging, token behavior, or rejecting bad responses
+- use selectors for parsing a response into a domain shape
+- use observables for orchestration and composition
+
+When a piece of logic changes how the request travels, it usually belongs in a handler. When it changes what value the caller receives, it usually belongs in a selector.

package/docs/server-sent-events.md

@@ -0,0 +1,125 @@
+# Server-Sent Events
+
+Use `client.sse$()` when an endpoint returns `text/event-stream` and you want parsed `ServerSentEvent<T>` objects instead of manually reading the response body.
+
+This is the highest-level SSE API in the package. If you need lower-level composition, use `createSseSelector` or `sseMap`.
+
+## Quick Start
+
+```typescript
+const events$ = client.sse$<{ message: string }>('/events', undefined, {
+  eventFilter: 'message',
+  skipHeartbeats: true,
+});
+```
+
+Subscribe to the result the same way you would any other observable HTTP call.
+
+## `sse$()` Inputs
+
+| Input | Where it goes | Purpose |
+| --- | --- | --- |
+| request init | second argument to `sse$()` | HTTP method, body, headers, and `signal` |
+| SSE selector options | third argument to `sse$()` | `eventFilter`, `skipHeartbeats`, and custom parsing |
+
+`client.sse$()` uses the request `signal` as the abort signal for the underlying SSE reader.
+
+## SSE Options
+
+| Option | Type | What it does |
+| --- | --- | --- |
+| `eventFilter` | `string | string[]` | Emits only matching named SSE events |
+| `skipHeartbeats` | `boolean` | Skips empty heartbeat events and named `heartbeat` or `ping` events |
+| `dataParser` | `(data: string) => T` | Overrides the default parser for the `data:` field |
+
+By default, the parser tries `JSON.parse(...)` first and falls back to the raw string when parsing fails.
+
+## What `sse$()` Does For You
+
+- adds `Accept: text/event-stream`
+- adds `Content-Type: text/event-stream`
+- adds `Cache-Control: no-cache` and `Connection: keep-alive`
+- validates that the response is a readable `text/event-stream`
+- parses `data:` fields into `ServerSentEvent<T>` objects
+- honors `retry:` directives by delaying before continuing to read
+- stops reading when the observable is unsubscribed or the abort signal fires
+
+## Abort Behavior
+
+Pass an `AbortSignal` through the request init when you need explicit cancellation.
+
+```typescript
+const abortController = new AbortController();
+
+const events$ = client.sse$<{ message: string }>(
+  '/events',
+  { signal: abortController.signal },
+  { skipHeartbeats: true },
+);
+
+abortController.abort();
+```
+
+Unsubscribing from the observable also stops the underlying stream.
+
+## Lower-Level SSE APIs
+
+### `createSseSelector`
+
+Use `createSseSelector` when you want to compose SSE handling with `fetch()` or `fetch$()` yourself.
+
+Unlike `client.sse$()`, the lower-level SSE APIs do not add SSE request headers for you. Add the headers your endpoint expects, especially `Accept: text/event-stream`.
+
+```typescript
+import { createSseSelector } from '@equinor/fusion-framework-module-http/selectors';
+
+const selector = createSseSelector<{ message: string }>({
+  eventFilter: ['message', 'update'],
+  skipHeartbeats: true,
+});
+
+const events$ = client.fetch$('/events', {
+  headers: {
+    Accept: 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  },
+  selector,
+});
+```
+
+### `sseMap`
+
+Use `sseMap` when you already have a response observable and want to transform that stream into SSE events.
+
+```typescript
+import { sseMap } from '@equinor/fusion-framework-module-http/operators';
+
+const events$ = client.fetch$('/events', {
+  headers: {
+    Accept: 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  },
+}).pipe(
+  sseMap<{ message: string }>({
+    skipHeartbeats: true,
+  }),
+);
+```
+
+## Error Handling
+
+The SSE APIs throw `ServerSentEventResponseError` when:
+
+- the response is not OK
+- the response body is not readable
+- the response does not advertise `text/event-stream`
+
+Handle SSE errors the same way you handle any other observable request error.
+
+## Rule Of Thumb
+
+- use `sse$()` for normal application code
+- use `createSseSelector` when you want selector-level control
+- use `sseMap` when you already have a response observable pipeline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-http",
-  "version": "7.0.8",
+  "version": "8.0.0",
   "description": "",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -58,13 +58,13 @@
   },
   "dependencies": {
     "rxjs": "^7.8.1",
-    "zod": "^4.1.8",
-    "@equinor/fusion-framework-module": "^5.0.6",
-    "@equinor/fusion-framework-module-msal": "^7.3.1"
+    "zod": "^4.3.6",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-framework-module-msal": "^8.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/configurator.ts

@@ -11,10 +11,13 @@ import type { IHttpRequestHandler, IHttpResponseHandler } from './lib/operators'
  * Represents the options for constructing an `IHttpClient` instance.
  *
  * @template TInit - The type of the initial request object used by the `IHttpClient` instance.
+ * @template TResponse - The type of the response object used by the `IHttpClient` instance.
  * @property {IHttpRequestHandler<TInit>} requestHandler - The request handler to be used by the `IHttpClient` instance.
+ * @property {IHttpResponseHandler<TResponse>} [responseHandler] - The response handler to be used by the `IHttpClient` instance.
  */
-interface HttpClientConstructorOptions<TInit extends FetchRequest> {
+interface HttpClientConstructorOptions<TInit extends FetchRequest, TResponse = Response> {
   requestHandler: IHttpRequestHandler<TInit>;
+  responseHandler?: IHttpResponseHandler<TResponse>;
 }
 
 /**
@@ -28,14 +31,20 @@ interface HttpClientConstructorOptions<TInit extends FetchRequest> {
 interface HttpClientConstructor<TClient extends IHttpClient> {
   new (
     uri: string,
-    options: HttpClientConstructorOptions<HttpClientRequestInitType<TClient>>,
+    options: HttpClientConstructorOptions<
+      HttpClientRequestInitType<TClient>,
+      HttpClientResponseType<TClient>
+    >,
   ): TClient;
 }
 
 /**
- * Represents the options for configuring an `IHttpClient` instance.
+ * Configures how the provider creates a named `IHttpClient` instance.
  *
- * @template TClient - The type of the `IHttpClient` instance to be configured.
+ * Use these options to define a base URL, MSAL scopes, shared request or response handlers,
+ * a custom client constructor, or per-instance setup through `onCreate`.
+ *
+ * @template TClient - The client type created from this configuration.
  */
 export interface HttpClientOptions<TClient extends IHttpClient = IHttpClient> {
   /** The base URI for the `IHttpClient` instance. */
@@ -54,7 +63,7 @@ export interface HttpClientOptions<TClient extends IHttpClient = IHttpClient> {
   requestHandler?: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
 
   /** The response handler to be used by the `IHttpClient` instance. */
-  responseHandler?: IHttpResponseHandler<HttpClientRequestInitType<TClient>>;
+  responseHandler?: IHttpResponseHandler<HttpClientResponseType<TClient>>;
 }
 
 /**
@@ -68,8 +77,21 @@ export type HttpClientRequestInitType<T extends IHttpClient> =
   T extends IHttpClient<infer U> ? U : never;
 
 /**
- * Instance for configuring http client
- * @template TClient base type of client that the provider will create
+ * Utility type that extracts the response type from an `IHttpClient` implementation.
+ * This is useful for ensuring type safety when configuring response handlers for an `IHttpClient` instance.
+ *
+ * @template T - The type of the `IHttpClient` implementation.
+ * @returns The response type for the `IHttpClient` implementation.
+ */
+export type HttpClientResponseType<T extends IHttpClient> =
+  T extends IHttpClient<infer _TRequest, infer TResponse> ? TResponse : never;
+
+/**
+ * Registers and looks up named HTTP client configurations for the HTTP module.
+ *
+ * Each named configuration can later be turned into a fresh client instance by the provider.
+ *
+ * @template TClient - The base client type the provider creates.
  */
 export interface IHttpClientConfigurator<TClient extends IHttpClient = IHttpClient> {
   readonly clients: Record<string, HttpClientOptions<TClient>>;
@@ -77,14 +99,15 @@ export interface IHttpClientConfigurator<TClient extends IHttpClient = IHttpClie
   readonly defaultHttpRequestHandler: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
 
   /**
-   * Configure a client with arguments
-   * @param name name of the client
-   * @param args option that are used cor creating a client
+   * Registers or updates a named client configuration.
+   * @param name - The client key used later with `createClient(name)`.
+   * @param args - The configuration used when creating a client instance.
+   * @returns The configurator so registrations can be chained.
    * @example
    * ```ts
-   * configurator.http.configureClient('foo',{
-   *   baseUri: 'https://foo.bar',
-   *   defaultScopes: ['foobar/.default']
+   * configurator.http.configureClient('catalog', {
+   *   baseUri: 'https://api.example.com',
+   *   defaultScopes: ['api://catalog-api/.default'],
    * });
    * ```
    */
@@ -94,18 +117,21 @@ export interface IHttpClientConfigurator<TClient extends IHttpClient = IHttpClie
   ): IHttpClientConfigurator<TClient>;
 
   /**
-   * Configure a simple client by name to an endpoint
-   * @param name name of the client
-   * @param uri base endpoint for the client
+   * Registers a named client with only a base URI.
+   * @param name - The client key used later with `createClient(name)`.
+   * @param uri - The base endpoint for the client.
+   * @returns The configurator so registrations can be chained.
    */
   configureClient(name: string, uri: string): IHttpClientConfigurator<TClient>;
 
   /**
-   * Creates a client with callback configuration
-   * @param name name of the client
-   * @param onCreate callback when a client is created
+   * Registers a named client using only an `onCreate` callback.
+   * @param name - The client key used later with `createClient(name)`.
+   * @param onCreate - The callback that runs for every created client instance.
+   * @returns The configurator so registrations can be chained.
+   * @example
    * ```ts
-   * configurator.http.configureClient('foo',(client) => {
+   * configurator.http.configureClient('catalog', (client) => {
    *   client.requestHandler.add('logger', (request) => console.log(request));
    * });
    * ```
@@ -116,7 +142,9 @@ export interface IHttpClientConfigurator<TClient extends IHttpClient = IHttpClie
   ): HttpClientConfigurator<TClient>;
 
   /**
-   * Check if there is a configuration for provided name
+   * Checks whether a named client configuration exists.
+   * @param name - The client key to check.
+   * @returns `true` when a configuration exists for the key.
    */
   hasClient(name: string): boolean;
 }
@@ -127,15 +155,15 @@ export class HttpClientConfigurator<TClient extends IHttpClient>
 {
   protected _clients: Record<string, HttpClientOptions<TClient>> = {};
 
-  /** Get a clone of all configured clients */
+  /** Gets a shallow clone of all named client configurations. */
   public get clients(): Record<string, HttpClientOptions<TClient>> {
     return { ...this._clients };
   }
 
-  /** default class for creation of http clients */
+  /** Default constructor used when a client configuration does not provide `ctor`. */
   readonly defaultHttpClientCtor: HttpClientConstructor<TClient>;
 
-  /** default request handler for http clients, applied on creation */
+  /** Default request handler pipeline cloned into each created client instance. */
   readonly defaultHttpRequestHandler = new HttpRequestHandler<HttpClientRequestInitType<TClient>>({
     // convert all request methods to uppercase
     'capitalize-method': capitalizeRequestMethodOperator(),
@@ -144,8 +172,8 @@ export class HttpClientConfigurator<TClient extends IHttpClient>
   });
 
   /**
-   * Create a instance of http configuration
-   * @param client defaultHttpRequestHandler
+   * Creates a configurator with the default client constructor.
+   * @param client - The default client constructor used when `ctor` is not configured per client.
    */
   constructor(client: HttpClientConstructor<TClient>) {
     this.defaultHttpClientCtor = client;

package/src/lib/client/client-msal.ts

@@ -67,9 +67,10 @@ export class HttpClientMsal<
      * Merges the default scopes defined in the `HttpClientMsal` class with the scopes provided in the `init` parameter, if any.
      * This ensures that the request includes the necessary scopes for MSAL authentication.
      */
-    const args = Object.assign(init || {}, {
+    const args = {
+      ...init,
       scopes: this.defaultScopes.concat(init?.scopes || []),
-    }) as FetchRequestInit<T, TRequest, TResponse>;
+    } as FetchRequestInit<T, TRequest, TResponse>;
 
     return super._fetch$(path, args);
   }

package/src/lib/client/client.ts

@@ -14,14 +14,12 @@ import type {
   FetchResponse,
   IHttpClient,
   JsonRequest,
-  ResponseSelector,
   StreamResponse,
 } from './types';
 
 import { HttpResponseError } from '../../errors';
 import {
   createSseSelector,
-  SseSelector,
   type ServerSentEvent,
   type SseSelectorOptions,
 } from '../selectors/sse-selector';
@@ -240,15 +238,15 @@ export class HttpClient<
    * @returns A `StreamResponse` that emits `ServerSentEvent<T>` objects as they are received from the server.
    *
    * @example
-   * const sse$ = httpClient.sse(
-   *  '/events',
-   *  { method: 'POST', body: JSON.stringify({ prompt: 'tell me a joke' }) },
-   *  { eventFilter: ['message'] }
+   * const sse$ = httpClient.sse$(
+   *   '/events',
+   *   { method: 'POST', body: JSON.stringify({ prompt: 'tell me a joke' }) },
+   *   { eventFilter: ['message'] },
    * );
    * sse$.subscribe({
-   *  next: (event) => console.log(event),
-   *  error: (err) => console.error(err),
-   *  complete: () => console.log('Completed'),
+   *   next: (event) => console.log(event),
+   *   error: (err) => console.error(err),
+   *   complete: () => console.log('Completed'),
    * });
    */
   public sse$<T = unknown>(
@@ -329,6 +327,7 @@ export class HttpClient<
     const { selector, ...options } = args || {};
     const response$ = of({
       ...options,
+      path,
       uri: this._resolveUrl(path),
     } as TRequest).pipe(
       /** prepare request, allow extensions to modify request  */

package/src/lib/operators/index.ts

@@ -3,5 +3,6 @@ export { HttpResponseHandler } from './http-response-handler';
 export { ProcessOperators } from './process-operators';
 export { capitalizeRequestMethodOperator } from './capitalize-request-method.operator';
 export { requestValidationOperator } from './request-validation.operator';
+export { sseMap } from './sse.operator';
 
 export * from './types';

package/src/lib/selectors/index.ts

@@ -1,4 +1,11 @@
 export { jsonSelector } from './json-selector';
 export { blobSelector } from './blob-selector';
+export { createSseSelector } from './sse-selector';
 
 export type { ResponseSelector } from '../client/types';
+export type {
+  DataParser,
+  ServerSentEvent,
+  SseSelector,
+  SseSelectorOptions,
+} from './sse-selector';

package/src/module.ts

@@ -40,7 +40,11 @@ export type HttpMsalModule = Module<
 >;
 
 /**
- * HTTP module with MSAL authentication.
+ * Default HTTP module definition for Fusion Framework applications.
+ *
+ * The module uses `HttpClientMsal` as the default client implementation and,
+ * when the auth module is available, installs a request handler that can acquire
+ * bearer tokens for scoped requests.
  */
 export const module: HttpMsalModule = {
   name: 'http',
@@ -95,7 +99,13 @@ export const module: HttpMsalModule = {
 };
 
 /**
- * Configures the HTTP module with MSAL authentication.
+ * Creates a module configurator for the HTTP module.
+ *
+ * Use this when you need lower-level access to the module configuration callback,
+ * for example when registering several named clients in one setup step.
+ *
+ * @param configure - The callback that receives the HTTP module configuration.
+ * @returns A module configurator for the HTTP module.
  */
 export const configureHttp = <TRef = unknown>(
   configure: (config: ModuleConfigType<HttpMsalModule>, ref?: TRef) => void,
@@ -105,15 +115,14 @@ export const configureHttp = <TRef = unknown>(
 });
 
 /**
- * Configures the HTTP client with MSAL authentication.
+ * Creates a module configurator that registers one named HTTP client.
  *
- * This function creates a module configurator that can be used to configure the HTTP module
- * with MSAL authentication. The configurator takes a name and a set of HTTP client options,
- * and returns a module configurator that can be used to configure the HTTP module.
+ * This is the convenience API for the common case where a setup step only needs to
+ * register one client with `baseUri`, `defaultScopes`, handlers, or a custom constructor.
  *
- * @param name - The name of the HTTP client configuration.
- * @param args - The HTTP client options, including the MSAL configuration.
- * @returns A module configurator that can be used to configure the HTTP module.
+ * @param name - The client key used later with `createClient(name)`.
+ * @param args - The named client configuration.
+ * @returns A module configurator that registers the named client.
  */
 export const configureHttpClient = <TRef = unknown>(
   name: string,