feat(fs-http): add timeout option with 30000ms default (Doctrine #8 library-author extension)

Closes 3-spy convergent finding 2026-04-30 on fs-http timeout surface absence.
Default 30000ms applies when unset; override via options.timeout or per-call
AxiosRequestConfig. Pass timeout: 0 to disable (consumer accepts Doctrine #8).

Bumps fs-http to 0.2.0 (minor — observable behavior change on previously-unset
timeouts).

Refs: campaigns/fs-packages/2026-04-30-multi-spy-refresh-wave.md

Author: Goosterhof

packages/http/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @script-development/fs-http
 
+## 0.2.0 — 2026-04-30
+
+### Minor Changes
+
+- **fs-http**: Adds `timeout?: number` to `HttpServiceOptions` with a 30000ms default. Pass `timeout: 0` to disable (consumer accepts Doctrine #8 responsibility). Behavior change: previously-unset timeouts no longer hang indefinitely. Closes 3-spy convergent finding 2026-04-30.
+
 ## 0.1.0
 
 ### Minor Changes

packages/http/README.md

@@ -40,6 +40,35 @@ Creates a new HTTP service instance.
 - `withCredentials` — Send cookies cross-origin (default: `true`)
 - `withXSRFToken` — Include XSRF token header (default: `false`)
 - `smartCredentials` — Auto-toggle `withCredentials` based on request host matching base URL host (default: `false`)
+- `timeout` — Request timeout in milliseconds (default: `30000`). Pass `0` to disable; pass any positive number to override.
+
+### Timeout
+
+The factory applies a **30000ms (30s) default timeout** to every request. This default is the Armory's compliance posture for the war-room **Doctrine #8 library-author extension** (CLAUDE.md, 2026-04-22):
+
+> Library-author extension (2026-04-22) — Shared HTTP factory packages (e.g., `@script-development/fs-http`) must expose a compliant timeout surface: a default, a required option, or a documented contract plus consumer-level enforcement. Inheriting framework defaults at the library layer silently propagates the violation to every consumer territory.
+
+To override the service-wide default, pass `timeout` in the options:
+
+```typescript
+// Tighten for a fast-API service
+const http = createHttpService('https://api.example.com', {timeout: 5_000});
+```
+
+To disable the default and accept Doctrine #8 responsibility at the consumer layer (e.g., AI streaming endpoints with their own timeout discipline), pass `timeout: 0`:
+
+```typescript
+const http = createHttpService('https://ai.example.com', {timeout: 0});
+```
+
+Per-request overrides remain available via the existing `AxiosRequestConfig.timeout` parameter on each method:
+
+```typescript
+// Service default (30000ms) for most calls; per-call override for the long one
+await http.postRequest('/generate-report', payload, {timeout: 120_000});
+```
+
+The constant is also exported as `DEFAULT_TIMEOUT_MS` for consumers that want to reference it explicitly.
 
 ### Request Methods
 

packages/http/package.json

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

packages/http/src/http.ts

@@ -18,6 +18,15 @@ 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
+ * extension, 2026-04-22) — a shared HTTP factory must expose a compliant
+ * timeout surface so consumer territories cannot silently inherit
+ * indefinite hangs.
+ */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
 const unregister = <T>(array: T[], item: T): UnregisterMiddleware => {
     return () => {
         const index = array.indexOf(item);
@@ -33,6 +42,7 @@ export const createHttpService = (baseURL: string, options?: HttpServiceOptions)
         withCredentials: options?.withCredentials ?? true,
         withXSRFToken: options?.withXSRFToken ?? false,
         headers: {Accept: 'application/json', ...options?.headers},
+        timeout: options?.timeout ?? DEFAULT_TIMEOUT_MS,
     });
 
     // Middleware stacks

packages/http/src/index.ts

@@ -1,4 +1,4 @@
-export {createHttpService} from './http';
+export {DEFAULT_TIMEOUT_MS, createHttpService} from './http';
 export type {
     HttpService,
     HttpServiceOptions,

packages/http/src/types.ts

@@ -13,6 +13,13 @@ export type HttpServiceOptions = {
     withCredentials?: boolean;
     withXSRFToken?: boolean;
     smartCredentials?: boolean;
+    /**
+     * Request timeout in milliseconds. Defaults to 30_000 (30s).
+     * Set 0 to disable (caller takes responsibility per Doctrine #8).
+     * Per-request override available via the `AxiosRequestConfig.timeout`
+     * parameter on each method.
+     */
+    timeout?: number;
 };
 
 export type HttpService = {

packages/http/tests/http.spec.ts

@@ -2,7 +2,7 @@ import axios from 'axios';
 import MockAdapter from 'axios-mock-adapter';
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 
-import {createHttpService, isAxiosError} from '../src/index';
+import {DEFAULT_TIMEOUT_MS, createHttpService, isAxiosError} from '../src/index';
 
 const BASE_URL = 'https://api.example.com';
 
@@ -73,6 +73,20 @@ describe('createHttpService', () => {
             expect(response.config.withXSRFToken).toBe(false);
             expect(response.config.headers.Accept).toBe('application/json');
         });
+
+        it('applies the 30000ms default timeout when timeout option is unset', async () => {
+            // Arrange — Doctrine #8 library-author extension: factory must default to
+            // a compliant timeout so consumers cannot silently inherit indefinite hangs.
+            mock.onGet(/.*/).reply(200, {});
+            const service = createHttpService(BASE_URL);
+
+            // Act
+            const response = await service.getRequest('/test');
+
+            // Assert
+            expect(DEFAULT_TIMEOUT_MS).toBe(30_000);
+            expect(response.config.timeout).toBe(30_000);
+        });
     });
 
     describe('custom options', () => {
@@ -112,6 +126,33 @@ describe('createHttpService', () => {
             // Assert
             expect(response.config.withXSRFToken).toBe(true);
         });
+
+        it('overrides the default timeout when timeout option is provided', async () => {
+            // Arrange
+            mock.onGet(/.*/).reply(200, {});
+            const service = createHttpService(BASE_URL, {timeout: 5_000});
+
+            // Act
+            const response = await service.getRequest('/test');
+
+            // Assert
+            expect(response.config.timeout).toBe(5_000);
+        });
+
+        it('disables the timeout when timeout: 0 is provided (kills ?? -> || mutation)', async () => {
+            // Arrange — `0` is falsy but explicitly defined. With `??` the caller's 0 is
+            // honored (timeout disabled, consumer accepts Doctrine #8 responsibility).
+            // With `||` the 0 would be coerced back to DEFAULT_TIMEOUT_MS — this test
+            // discriminates the two and kills the operator-swap mutation.
+            mock.onGet(/.*/).reply(200, {});
+            const service = createHttpService(BASE_URL, {timeout: 0});
+
+            // Act
+            const response = await service.getRequest('/test');
+
+            // Assert
+            expect(response.config.timeout).toBe(0);
+        });
     });
 
     describe('standard request methods', () => {