feat(fs-http)!: remove DOM coupling from download/preview (0.3.0)

Closes #59. fs-http should be HTTP transport, not browser download
UX. The previous downloadRequest/previewRequest methods constructed
Blobs, created `<a>` elements, dispatched clicks, and managed object
URL lifecycles — coupling that bled into every consumer's tests as
fragile global stubs (vi.stubGlobal of `Blob`/`document`/`window.URL`),
exposed to vitest 4's class-mock requirement and oxfmt's arrow-function
collapse. Three territories independently rediscovered the mitigation.

Reshape both methods to pure transport: `(endpoint, options?) →
Promise<AxiosResponse<Blob>>`. The DOM-side download dance moves to
`@script-development/fs-helpers` ≥ 0.1.2 as `triggerDownload(blob,
filename)`. Object-URL lifecycle for previews is now the consumer's
concern (one `URL.createObjectURL` line, plus revocation on cleanup).

BREAKING CHANGES (fs-http 0.2.0 → 0.3.0):

- downloadRequest(endpoint, documentName, type?) → AxiosResponse
  becomes downloadRequest(endpoint, options?) → AxiosResponse<Blob>.
- previewRequest(endpoint) → string (object URL)
  becomes previewRequest(endpoint, options?) → AxiosResponse<Blob>.
- Removed HEADERS_TO_TYPE map (one-entry OOXML lookup, did not earn
  its place in transport-layer code; consumers can supply their own
  if needed).

Cascade workspace bumps to keep the lock coherent:

- fs-helpers 0.1.1 → 0.1.2 (additive: triggerDownload export +
  happy-dom devDep).
- fs-adapter-store 0.1.5 → 0.1.6 (peer range widened to include
  ^0.3.0 — not a behavior change; doesn't depend on download/preview).
- fs-loading 0.1.1 → 0.1.2 (same widening; same rationale).

Out of scope (separate dispositions):

- streamRequest's `document.cookie` XSRF read remains. It's the only
  remaining DOM touch in fs-http; cleanup would require either a
  required `xsrfHeader` option or a cookie-reader middleware shipped
  alongside, both bigger migrations than #59 covers.
- Consumer territory upgrades. Land this PR after #60, then run a
  post-publish migration campaign across kendo, ublgenie, emmie,
  entreezuil, and BIO (5 download/preview call sites in production
  code; ~50 in test mocks).

Verified locally:

- 19 test files / 430 tests pass (was 18/430; +2 fs-helpers, -2 net
  fs-http after dropping obsolete DOM-orchestration tests).
- 100% coverage maintained on fs-http and fs-helpers.
- mutation: fs-http 97.30% (up from 95.74%; less surface to mutate),
  fs-helpers 100% (including the new dom-download.ts).
- All 8 CI gates locally green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Goosterhof

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@script-development/fs-adapter-store",
-    "version": "0.1.5",
+    "version": "0.1.6",
     "description": "Reactive adapter-store pattern with domain state management and CRUD resource adapters",
     "homepage": "https://packages.script.nl/packages/adapter-store",
     "license": "MIT",
@@ -42,15 +42,15 @@
     },
     "devDependencies": {
         "@script-development/fs-helpers": "^0.1.0",
-        "@script-development/fs-http": "^0.1.0 || ^0.2.0",
+        "@script-development/fs-http": "^0.1.0 || ^0.2.0 || ^0.3.0",
         "@script-development/fs-loading": "^0.1.0",
         "@script-development/fs-storage": "^0.1.0",
         "happy-dom": "^20.9.0",
         "vue": "^3.5.33"
     },
     "peerDependencies": {
         "@script-development/fs-helpers": "^0.1.0",
-        "@script-development/fs-http": "^0.1.0 || ^0.2.0",
+        "@script-development/fs-http": "^0.1.0 || ^0.2.0 || ^0.3.0",
         "@script-development/fs-loading": "^0.1.0",
         "@script-development/fs-storage": "^0.1.0",
         "vue": "^3.5.33"

packages/adapter-store/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@script-development/fs-helpers",
-    "version": "0.1.1",
-    "description": "Tree-shakeable shared utility helpers: deep copy, type guards, and case conversion",
+    "version": "0.1.2",
+    "description": "Tree-shakeable shared utility helpers: deep copy, type guards, case conversion, and browser download",
     "homepage": "https://packages.script.nl/packages/helpers",
     "license": "MIT",
     "repository": {
@@ -43,6 +43,9 @@
     "dependencies": {
         "string-ts": "^2.3.1"
     },
+    "devDependencies": {
+        "happy-dom": "^20.9.0"
+    },
     "engines": {
         "node": ">=24.0.0"
     }

packages/helpers/package.json

@@ -0,0 +1,18 @@
+/**
+ * Triggers a browser download for a Blob.
+ *
+ * Creates a transient `<a>` element pointing at an object URL, dispatches a
+ * click, then revokes the URL. The browser's download UI captures its own
+ * reference during click(), so revoking immediately does not interrupt the
+ * in-flight download — it simply releases the blob reference held by the URL.
+ *
+ * Lives in `fs-helpers` rather than `fs-http` so the HTTP factory remains a
+ * transport-only library with no DOM coupling (fs-packages issue #59).
+ */
+export const triggerDownload = (blob: Blob, filename: string): void => {
+    const link = document.createElement('a');
+    link.href = URL.createObjectURL(blob);
+    link.download = filename;
+    link.click();
+    URL.revokeObjectURL(link.href);
+};

packages/helpers/src/dom-download.ts

@@ -4,3 +4,5 @@ export type {Writable} from './deep-copy';
 export {isExisting} from './type-guards';
 
 export {toCamelCaseTyped, deepCamelKeys, deepSnakeKeys} from './case-conversion';
+
+export {triggerDownload} from './dom-download';

packages/helpers/src/index.ts

@@ -0,0 +1,62 @@
+// @vitest-environment happy-dom
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {triggerDownload} from '../src';
+
+describe('triggerDownload', () => {
+    let createObjectURL: ReturnType<typeof vi.fn>;
+    let revokeObjectURL: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+        createObjectURL = vi.fn(() => 'blob:https://test/fake-object-url');
+        revokeObjectURL = vi.fn();
+        vi.stubGlobal('URL', {createObjectURL, revokeObjectURL});
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+    });
+
+    it('creates an anchor with the object URL and download filename, clicks, then revokes', () => {
+        // Arrange
+        const blob = new Blob(['file-content'], {type: 'application/pdf'});
+        const link = document.createElement('a');
+        const clickSpy = vi.spyOn(link, 'click').mockImplementation(() => {});
+        const createElementSpy = vi.spyOn(document, 'createElement').mockReturnValue(link);
+
+        // Act
+        triggerDownload(blob, 'report.pdf');
+
+        // Assert — anchor created with the right shape and clicked
+        expect(createElementSpy).toHaveBeenCalledWith('a');
+        expect(createObjectURL).toHaveBeenCalledWith(blob);
+        expect(link.href).toBe('blob:https://test/fake-object-url');
+        expect(link.download).toBe('report.pdf');
+        expect(clickSpy).toHaveBeenCalledTimes(1);
+
+        // Assert — revoked with the same URL that was assigned to href
+        expect(revokeObjectURL).toHaveBeenCalledTimes(1);
+        expect(revokeObjectURL).toHaveBeenCalledWith('blob:https://test/fake-object-url');
+    });
+
+    it('revokes after click so the browser can release the blob reference', () => {
+        // Arrange — record the order of click vs revoke
+        const callOrder: string[] = [];
+        const blob = new Blob(['data']);
+        const link = document.createElement('a');
+        vi.spyOn(link, 'click').mockImplementation(() => {
+            callOrder.push('click');
+        });
+        vi.spyOn(document, 'createElement').mockReturnValue(link);
+        revokeObjectURL.mockImplementation(() => {
+            callOrder.push('revoke');
+        });
+
+        // Act
+        triggerDownload(blob, 'file.bin');
+
+        // Assert — click fires before revoke (the in-flight download captures its own ref)
+        expect(callOrder).toEqual(['click', 'revoke']);
+    });
+});

packages/helpers/tests/dom-download.spec.ts

@@ -1,5 +1,39 @@
 # @script-development/fs-http
 
+## 0.3.0 — 2026-04-30
+
+### Breaking Changes
+
+- **`downloadRequest` no longer touches the DOM.** Signature changes from `(endpoint, documentName, type?) → Promise<AxiosResponse>` to `(endpoint, options?) → Promise<AxiosResponse<Blob>>`. The browser download dance (`Blob` construction, `<a>` element, `link.click`, object URL lifecycle) moves to consumer code. Use `triggerDownload(blob, filename)` from `@script-development/fs-helpers` ≥ 0.1.2 to reproduce the prior behavior in one call.
+- **`previewRequest` no longer touches the DOM.** Signature changes from `(endpoint) → Promise<string>` (object URL) to `(endpoint, options?) → Promise<AxiosResponse<Blob>>` (response with the raw Blob). Consumers manage object-URL lifecycle: `URL.createObjectURL(response.data)` to render and `URL.revokeObjectURL(...)` on cleanup.
+- **Removed:** `HEADERS_TO_TYPE` map (was used internally to resolve OOXML to xlsx). Consumers that need MIME mapping can supply their own table; the prior table was a one-entry lookup that did not earn its place in transport-layer code.
+
+### Why
+
+`fs-http` should be HTTP transport. Coupling to `Blob`, `document.createElement`, and `URL.createObjectURL`/`revokeObjectURL` made every consumer's tests responsible for stubbing browser globals — fragile under formatters (oxfmt collapsed `function () { return obj }` into arrow-functions, breaking constructor-mock patterns across kendo and ublgenie in April 2026), exposed to vitest 4's class-mock requirement, and a coupling smell between library and test environment. Closes [#59](https://github.com/script-development/fs-packages/issues/59).
+
+### Migration
+
+```ts
+// before (0.2.x)
+await http.downloadRequest('/files/123/download', 'report.pdf');
+
+// after (0.3.x)
+import {triggerDownload} from '@script-development/fs-helpers';
+const {data} = await http.downloadRequest('/files/123/download');
+triggerDownload(data, 'report.pdf');
+```
+
+```ts
+// before (0.2.x)
+const blobUrl = await http.previewRequest('/files/123/preview');
+
+// after (0.3.x)
+const {data} = await http.previewRequest('/files/123/preview');
+const blobUrl = URL.createObjectURL(data);
+// remember to revoke on cleanup: URL.revokeObjectURL(blobUrl)
+```
+
 ## 0.2.0 — 2026-04-30
 
 ### Minor Changes

packages/http/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
     "name": "@script-development/fs-http",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Framework-agnostic HTTP service factory with middleware architecture",
     "homepage": "https://packages.script.nl/packages/http",
     "license": "MIT",

packages/http/package.json

@@ -14,10 +14,6 @@ import type {
 
 import {isAxiosError} from './utils';
 
-const HEADERS_TO_TYPE: Record<string, string> = {
-    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'application/xlsx',
-};
-
 /**
  * Default request timeout in milliseconds (30s). Applied when
  * `HttpServiceOptions.timeout` is unset. Per Doctrine #8 (library-author
@@ -27,12 +23,6 @@ const HEADERS_TO_TYPE: Record<string, string> = {
  */
 export const DEFAULT_TIMEOUT_MS = 30_000;
 
-// axios 1.15+ types `response.headers[key]` as `AxiosHeaderValue | undefined`
-// (string | string[] | number | boolean | null | AxiosHeaders | undefined). For
-// content-type handling we only honor a real string; any other shape falls back
-// to undefined so the consumer's default applies.
-const asString = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined);
-
 const unregister = <T>(array: T[], item: T): UnregisterMiddleware => {
     return () => {
         const index = array.indexOf(item);
@@ -103,40 +93,17 @@ export const createHttpService = (baseURL: string, options?: HttpServiceOptions)
     const deleteRequest = <T = unknown>(endpoint: string, options?: AxiosRequestConfig) =>
         http.delete<T>(endpoint, options);
 
-    // Browser-dependent methods
-
-    const getContentType = (headerContentType?: string, type?: string): string => {
-        if (type) return type;
-        if (headerContentType) return HEADERS_TO_TYPE[headerContentType] || headerContentType;
-        throw new Error('No content type found');
-    };
-
-    const downloadRequest = async (endpoint: string, documentName: string, type?: string) => {
-        const response = await http.get(endpoint, {responseType: 'blob'});
-        const {data, headers} = response;
+    // Blob-returning request methods. Identical transport (responseType: 'blob');
+    // separate names communicate intent to consumers (download = save-to-disk,
+    // preview = inline-display). Neither touches the DOM — orchestration of the
+    // download dance and object-URL lifecycle lives with the consumer (see
+    // `triggerDownload` in `@script-development/fs-helpers`).
 
-        const actualType = getContentType(asString(headers['content-type']), type);
+    const downloadRequest = (endpoint: string, options?: AxiosRequestConfig) =>
+        http.get<Blob>(endpoint, {...options, responseType: 'blob'});
 
-        const blob = new Blob([data], {type: actualType});
-        const link = document.createElement('a');
-        link.href = window.URL.createObjectURL(blob);
-        link.download = documentName;
-        link.click();
-        // Revoke the object URL after the click so the browser can release the
-        // blob reference. The download itself captures its own reference during
-        // link.click(), so revoking here does not interrupt it.
-        window.URL.revokeObjectURL(link.href);
-
-        return response;
-    };
-
-    const previewRequest = async (endpoint: string): Promise<string> => {
-        const response = await http.get(endpoint, {responseType: 'blob'});
-        const contentType = asString(response.headers['content-type']) ?? 'application/octet-stream';
-        const blob = new Blob([response.data], {type: contentType});
-
-        return window.URL.createObjectURL(blob);
-    };
+    const previewRequest = (endpoint: string, options?: AxiosRequestConfig) =>
+        http.get<Blob>(endpoint, {...options, responseType: 'blob'});
 
     const streamRequest = (endpoint: string, data: unknown, signal?: AbortSignal): Promise<Response> => {
         const headers: Record<string, string> = {'content-type': 'application/json', accept: 'application/json'};

packages/http/src/http.ts

@@ -40,8 +40,22 @@ export type HttpService = {
         options?: AxiosRequestConfig,
     ) => Promise<AxiosResponse<T>>;
     deleteRequest: <T = unknown>(endpoint: string, options?: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
-    downloadRequest: (endpoint: string, documentName: string, type?: string) => Promise<AxiosResponse>;
-    previewRequest: (endpoint: string) => Promise<string>;
+    /**
+     * GET an endpoint as a Blob, intended for save-to-disk flows. Returns the
+     * full AxiosResponse so callers can read headers (e.g. content-type) before
+     * handing off to a download utility such as `fs-helpers`' `triggerDownload`.
+     *
+     * No DOM side effects — fs-http is transport-only (fs-packages issue #59).
+     */
+    downloadRequest: (endpoint: string, options?: AxiosRequestConfig) => Promise<AxiosResponse<Blob>>;
+    /**
+     * GET an endpoint as a Blob, intended for inline-display flows. Identical
+     * transport to `downloadRequest`; the separate name communicates intent.
+     *
+     * Callers manage object-URL lifecycle: `URL.createObjectURL(response.data)`
+     * to render and `URL.revokeObjectURL(...)` on cleanup.
+     */
+    previewRequest: (endpoint: string, options?: AxiosRequestConfig) => Promise<AxiosResponse<Blob>>;
     streamRequest: (endpoint: string, data: unknown, signal?: AbortSignal) => Promise<Response>;
     registerRequestMiddleware: (fn: RequestMiddlewareFunc) => UnregisterMiddleware;
     registerResponseMiddleware: (fn: ResponseMiddlewareFunc) => UnregisterMiddleware;