@equinor/fusion-framework-module-http 8.1.0-next.0 → 8.1.1

package/docs/client-configuration.md

@@ -1,175 +0,0 @@
-# Configure HTTP Clients
-
-Use HTTP client configuration when your application talks to the same backend more than once and you want one place to define base URLs, MSAL scopes, headers, and transport behavior.
-
-The main configuration APIs are:
-
-- `configureHttpClient(name, options)` for one named client
-- `configureHttp(...)` for lower-level module configuration
-- `createClient(name)` to create a fresh client instance from a named configuration
-- `createCustomClient<T>(name)` to create a custom client class with the same configuration
-
-## Named Clients vs Ad-Hoc Clients
-
-| Use case | API | Why |
-| --- | --- | --- |
-| One backend used throughout the app | `configureHttpClient(name, options)` | Keeps base URL, scopes, and shared behavior in one place |
-| Several clients configured together | `configureHttp(...)` | Useful when a module or setup step owns multiple backends |
-| One-off call to a specific base URL | `createClient({ baseUri })` | Useful for inline or temporary configuration |
-| One-off call to an absolute URL | `createClient('https://api.example.com')` | Useful when the URL itself is the configuration |
-
-> **Fusion app developers:** Higher-level frameworks like `@equinor/fusion-framework-app` can auto-register named clients from other sources (e.g. application config endpoints or service discovery) before your code runs. See the [`@equinor/fusion-framework-app` README](../../app/README.md) for details on how clients are registered at the app level and which source takes priority.
-
-## Quick Start
-
-```typescript
-configurator.configureHttpClient('catalog', {
-  baseUri: '/api/catalog',
-  defaultScopes: ['api://catalog-api/.default'],
-  onCreate: (client) => {
-    client.requestHandler.setHeader('X-App-Name', 'portal');
-  },
-});
-
-const client = framework.modules.http.createClient('catalog');
-const items = await client.json('/items');
-```
-
-This pattern is the normal entry point for application code.
-
-## Configuration Options
-
-| Option | What it controls |
-| --- | --- |
-| `baseUri` | Base URL used to resolve request paths. Relative values are resolved against `window.location.origin`. |
-| `defaultScopes` | Default MSAL scopes used by `HttpClientMsal` requests. |
-| `ctor` | Custom client constructor when you want domain-specific client methods. |
-| `onCreate` | Callback that runs for every newly created client instance. |
-| `requestHandler` | Initial request handler pipeline cloned into created clients. |
-| `responseHandler` | Initial response handler pipeline passed into created clients. |
-
-## Use `onCreate` For Shared Client Behavior
-
-`onCreate` is the main place to attach behavior that every fresh client instance should start with.
-
-```typescript
-configurator.configureHttpClient('catalog', {
-  baseUri: '/api/catalog',
-  onCreate: (client) => {
-    client.requestHandler.setHeader('X-Feature', 'catalog');
-    client.responseHandler.add('reject-unauthorized', (response) => {
-      if (response.status === 401) {
-        throw new Error('Unauthorized');
-      }
-    });
-  },
-});
-```
-
-Use this for headers, logging, validation, transport guards, and response policies.
-
-## MSAL Scope Behavior
-
-When the auth module is available, the HTTP module can acquire an access token before sending the request.
-
-- `defaultScopes` come from the configured client
-- per-request `scopes` are appended to `defaultScopes`
-- token acquisition only happens when the final scope list is non-empty
-
-```typescript
-await client.json('/items', {
-  scopes: ['api://catalog-admin/.default'],
-});
-```
-
-That request uses both the configured `defaultScopes` and the request-specific scopes.
-
-## Direct Module Integration
-
-If you are configuring modules directly instead of using higher-level framework helpers, use the package exports.
-
-```typescript
-import {
-  configureHttp,
-  configureHttpClient,
-} from '@equinor/fusion-framework-module-http';
-
-configurator.addConfig(configureHttpClient('catalog', {
-  baseUri: '/api/catalog',
-}));
-
-configurator.addConfig(configureHttp((http) => {
-  http.configureClient('search', {
-    baseUri: '/api/search',
-  });
-}));
-```
-
-Use `configureHttpClient(...)` when you only need one named client. Use `configureHttp(...)` when a module setup step owns several client registrations.
-
-## Ad-Hoc Clients
-
-The provider also supports one-off client creation without a named configuration.
-
-```typescript
-const inlineClient = framework.modules.http.createClient({
-  baseUri: '/api/search',
-});
-
-const urlClient = framework.modules.http.createClient('https://api.example.com');
-```
-
-If the string passed to `createClient()` is not a configured key but is an absolute `http:` or `https:` URL, the provider treats it as a `baseUri`.
-
-## Custom Client Classes
-
-Use `ctor` when you want to wrap the shared transport behavior in domain-specific methods.
-
-```typescript
-import { HttpClient } from '@equinor/fusion-framework-module-http/client';
-
-class ApiClient extends HttpClient {
-  getHealth(): Promise<{ status: string }> {
-    return this.json('/health');
-  }
-}
-
-configurator.configureHttpClient('api', {
-  baseUri: '/api',
-  ctor: ApiClient,
-});
-
-const client = framework.modules.http.createCustomClient<ApiClient>('api');
-const health = await client.getHealth();
-```
-
-## What `createClient()` Does
-
-Each call to `createClient()` creates a fresh client instance.
-
-- the client starts with its configured `baseUri`
-- `defaultScopes` are assigned to the client instance
-- `requestHandler` and `responseHandler` configuration is applied to that instance
-- `onCreate` runs for that specific instance
-
-This matters because headers and handlers added to one created client do not leak into the next created client from the same named configuration.
-
-## Missing Clients And Safe Lookup
-
-Use `hasClient(name)` when a client configuration may be optional.
-
-```typescript
-if (framework.modules.http.hasClient('catalog')) {
-  const client = framework.modules.http.createClient('catalog');
-  await client.json('/items');
-}
-```
-
-If you call `createClient(name)` with an unknown key, the provider throws `ClientNotFoundException`.
-
-## Rule Of Thumb
-
-- use named clients for stable backends
-- use `onCreate` for shared transport behavior
-- use `ctor` when you want domain-specific methods
-- use ad-hoc clients only when the configuration is truly local

package/docs/observable-patterns.md

@@ -1,103 +0,0 @@
-# Observable Patterns
-
-The observable API exposes the same HTTP transport pipeline as the promise API, but in a form that composes naturally with RxJS.
-
-Use `fetch$()`, `json$()`, `blob$()`, and `sse$()` when your request depends on other streams, needs cancellation by unsubscribe, or should participate in a larger RxJS workflow.
-
-## Promise Methods vs Observable Methods
-
-| Need | Recommended API |
-| --- | --- |
-| One request and one result | `fetch()` or `json()` |
-| RxJS composition | `fetch$()` or `json$()` |
-| Automatic cancellation when input changes | `fetch$()` or `json$()` with `switchMap` |
-| Observing transport activity | `request$`, `response$`, and the observable request methods |
-| Streaming server events | `sse$()` |
-
-Promise methods are implemented with `firstValueFrom(...)` on the corresponding observable method. That means both forms share the same underlying request pipeline.
-
-## Core Observable Behavior
-
-- observable request methods are cold
-- nothing is sent until you subscribe
-- unsubscribing aborts the underlying fetch
-- `client.abort()` cancels every in-flight request started by that client instance
-- `request$` and `response$` are per-client streams, not global streams
-
-## Pattern: Request From Another Stream
-
-Use `switchMap` when a new upstream value should replace the previous in-flight request.
-
-```typescript
-import { switchMap } from 'rxjs/operators';
-
-const item$ = selectedId$.pipe(
-  switchMap((id) => client.json$(`/items/${id}`)),
-);
-```
-
-This pattern works well for route parameters, selected rows, debounced search terms, and refresh triggers.
-
-## Pattern: Observe Transport Activity
-
-Each client instance exposes `request$` and `response$` so you can observe transport behavior alongside your result stream.
-
-```typescript
-const requestLog = client.request$.subscribe((request) => {
-  console.debug('request', request.method, request.uri);
-});
-
-const responseLog = client.response$.subscribe((response) => {
-  console.debug('response', response.status, response.url);
-});
-```
-
-Use these streams for diagnostics, telemetry, debugging operators, or building test helpers.
-
-## Pattern: Cancel By Unsubscribing
-
-Observable requests are a good fit for component and service lifecycles because cancellation is built in.
-
-```typescript
-const subscription = client.json$('/items').subscribe({
-  next: console.log,
-  error: console.error,
-});
-
-subscription.unsubscribe();
-```
-
-After unsubscribe, the client aborts the underlying fetch.
-
-## Pattern: Reuse Parsing With Selectors
-
-Selectors work well with observable request methods because they separate transport from parsing.
-
-```typescript
-const user$ = client.fetch$('/users/42', {
-  selector: userSelector,
-});
-```
-
-This lets you keep parsing logic reusable while still composing the request with RxJS operators.
-
-## Pattern: Use The Right Layer For The Job
-
-For most advanced flows, the HTTP module works best when each layer has one responsibility.
-
-- use `fetch$()` or `json$()` for transport
-- use selectors for response parsing
-- use request and response handlers for cross-cutting transport behavior
-- use RxJS operators for orchestration and composition
-
-## Common Observable Workflows
-
-- a route parameter stream drives `json$()` with `switchMap`
-- a user action stream triggers `fetch$()` and `catchError`
-- a request is observed through `request$` for telemetry
-- a response is observed through `response$` for diagnostics
-- an SSE endpoint uses `sse$()` for incremental updates
-
-## Rule Of Thumb
-
-Start with `json()` if you just need the result of one request. Move to `json$()` or `fetch$()` when the request is part of a reactive workflow.

package/docs/selectors-and-handlers.md

@@ -1,112 +0,0 @@
-# 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

@@ -1,125 +0,0 @@
-# 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/docs/testing.md

@@ -1,78 +0,0 @@
-# Testing
-
-There is no separate mock client or configurator — register a short-circuiting middleware
-through `configurator.http.addMiddleware(...)` on the real configurator instead. The real
-configurator API — `configureClient`, `baseUri`, `defaultScopes`, `requestHandler`, `onCreate`
-— all still applies; a middleware only wraps the network call itself.
-
-## Quick Start
-
-```typescript
-configurator.configureHttpClient('catalog', { baseUri: 'https://api.example.com' });
-configurator.http.addMiddleware(async (uri, init, next) =>
-  uri === 'https://api.example.com/items' ? Response.json([{ id: 1 }]) : next(uri, init),
-);
-
-const items = await fusion.modules.http.createClient('catalog').json('/items');
-```
-
-## The Middleware Contract
-
-```typescript
-type HttpMiddleware = (
-  uri: string,
-  init: RequestInit,
-  next: (uri: string, init: RequestInit) => Promise<Response>,
-) => Response | Promise<Response> | Observable<Response>;
-```
-
-- **A middleware decides for itself whether to answer or fall through** — return a `Response` to
-  handle the request, or call and return `next(uri, init)` to continue to whichever middleware
-  (or the real network call) is registered next. There is no separate "declined" return value —
-  unlike a router, this is an onion-style chain, so a middleware can also inspect what `next(...)`
-  resolves to and decide based on that (a retry, for example).
-- **Registration order is outermost-first.** The first middleware registered via `addMiddleware`
-  wraps every other one, including the real network call — so it sees the request first and the
-  response last.
-- **A test middleware composes with real app config unchanged** — `addMiddleware` wraps
-  `_performFetch` rather than replacing it, so the exact same client and configuration a real
-  app registers is what a test exercises; only the boundary that would reach the network is
-  short-circuited.
-
-## Faking An Entire OpenAPI Document
-
-`createOpenApiMockMiddleware` (`@equinor/fusion-framework-module-http/mock`) adapts an
-[`@equinor/fusion-openapi-mock`](../../utils/openapi-mock) instance into an `HttpMiddleware`,
-so a real `openapi.json`/`openapi.yaml` fakes every response until a specific operation needs
-overriding:
-
-```typescript
-import { createOpenApiMock } from '@equinor/fusion-openapi-mock';
-import { createOpenApiMockMiddleware } from '@equinor/fusion-framework-module-http/mock';
-
-const openApiMock = createOpenApiMock(openApiDocument, { seed: 42 });
-
-configurator.configureHttpClient('catalog', { baseUri: 'https://api.example.com' });
-configurator.http.addMiddleware(createOpenApiMockMiddleware(openApiMock));
-```
-
-A request that matches no operation in the document falls through to `next`, so this composes
-with other middleware, or the real network call, registered around it.
-
-## Asserting Calls With `vi.fn`
-
-A middleware is a plain function, so a `vi.fn` spy works as one directly:
-
-```typescript
-const middleware = vi.fn(async () => Response.json({ ok: true }));
-configurator.http.addMiddleware(middleware);
-
-await client.json('/items');
-
-expect(middleware).toHaveBeenCalledOnce();
-const [uri, init] = middleware.mock.calls[0];
-expect(init.method ?? 'GET').toBe('GET');
-```
-
-See [`@equinor/fusion-framework/mock`](../../../framework/docs/testing-extending.md) to mock every
-framework boundary at once.