@output.ai/http 0.0.2 → 0.1.0

package/dist/config.js

@@ -6,5 +6,5 @@ export const config = {
      * Whether to log verbose HTTP information (headers and bodies)
      * Controlled by LOG_HTTP_VERBOSE environment variable
      */
-    logVerbose: ['1', 'true'].includes(process.env.TRACING_HTTP_VERBOSE)
+    logVerbose: ['1', 'true'].includes(process.env.LOG_HTTP_VERBOSE)
 };

package/dist/hooks/assign_request_id.d.ts

@@ -0,0 +1,9 @@
+import type { BeforeRequestHook } from 'ky';
+/**
+ * Assigns a unique request ID to each request via X-Request-ID header
+ * This ensures each request invocation has a unique identifier for tracing,
+ * even if the request shape (method/url/headers) is identical
+ *
+ * If X-Request-ID already exists (from upstream), it's preserved for propagation
+ */
+export declare const assignRequestId: BeforeRequestHook;

package/dist/hooks/assign_request_id.js

@@ -0,0 +1,15 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Assigns a unique request ID to each request via X-Request-ID header
+ * This ensures each request invocation has a unique identifier for tracing,
+ * even if the request shape (method/url/headers) is identical
+ *
+ * If X-Request-ID already exists (from upstream), it's preserved for propagation
+ */
+export const assignRequestId = (request) => {
+    const existingId = request.headers.get('X-Request-ID');
+    if (!existingId) {
+        const requestId = randomUUID();
+        request.headers.set('X-Request-ID', requestId);
+    }
+};

package/dist/hooks/index.d.ts

@@ -1,3 +1,4 @@
+export { assignRequestId } from './assign_request_id.js';
 export { traceRequest } from './trace_request.js';
 export { traceResponse } from './trace_response.js';
 export { traceError } from './trace_error.js';

package/dist/hooks/index.js

@@ -1,3 +1,4 @@
+export { assignRequestId } from './assign_request_id.js';
 export { traceRequest } from './trace_request.js';
 export { traceResponse } from './trace_response.js';
 export { traceError } from './trace_error.js';

package/dist/hooks/trace_error.d.ts

@@ -1,4 +1,13 @@
-import type { BeforeErrorHook } from 'ky';
+import type { BeforeErrorHook, Input } from 'ky';
+/**
+ * Wraps a fetch-like function to log and rethrow errors.
+ *
+ * This is nessesary as ky's beforeError hook does not trace non-HTTP errors.
+ * See: https://github.com/sindresorhus/ky/issues/296
+ * @param fetchFn - A fetch-compatible function (input, init) => Promise<Response>
+ * @returns A new function with the same signature that logs and rethrows errors.
+ */
+export declare function applyFetchErrorTracing(fetchFn: (input: Input, init?: RequestInit) => Promise<Response>): (input: Input, init?: RequestInit) => Promise<Response>;
 /**
  * Traces HTTP errors for observability using Output SDK tracing
  */

package/dist/hooks/trace_error.js

@@ -1,16 +1,61 @@
+import { HTTPError } from 'ky';
 import { createTraceId, redactHeaders } from '#utils/index.js';
 import { Tracing } from '@output.ai/core/tracing';
+/**
+ * Wraps a fetch-like function to log and rethrow errors.
+ *
+ * This is nessesary as ky's beforeError hook does not trace non-HTTP errors.
+ * See: https://github.com/sindresorhus/ky/issues/296
+ * @param fetchFn - A fetch-compatible function (input, init) => Promise<Response>
+ * @returns A new function with the same signature that logs and rethrows errors.
+ */
+export function applyFetchErrorTracing(fetchFn) {
+    return async (input, init) => {
+        try {
+            return await fetchFn(input, init);
+        }
+        catch (err) {
+            const isHTTPError = err instanceof HTTPError;
+            if (!isHTTPError) {
+                const traceId = createTraceId(input);
+                // Skip tracing if no X-Request-ID header is present
+                if (traceId) {
+                    const isAbortError = err instanceof DOMException && err.name === 'AbortError';
+                    const message = isAbortError ? 'Fetch aborted due to timeout or manual cancellation' : 'Unknown error occurred';
+                    Tracing.addEventError({
+                        id: traceId,
+                        details: {
+                            error: JSON.stringify(err, null, 2),
+                            message
+                        }
+                    });
+                }
+                else {
+                    console.warn('applyFetchErrorTracing: Skipping fetch error tracing - no X-Request-ID header');
+                }
+            }
+            throw err;
+        }
+    };
+}
 /**
  * Traces HTTP errors for observability using Output SDK tracing
  */
 export const traceError = (error) => {
-    Tracing.addEventError({
-        id: createTraceId(error.request),
-        details: {
-            status: error.response.status,
-            statusText: error.response.statusText,
-            headers: redactHeaders(Object.fromEntries(error.response.headers.entries()))
-        }
-    });
+    const traceId = createTraceId(error.request);
+    // Skip tracing if no X-Request-ID header is present
+    if (traceId) {
+        Tracing.addEventError({
+            id: traceId,
+            details: {
+                status: error.response.status,
+                statusText: error.response.statusText,
+                headers: redactHeaders(Object.fromEntries(error.response.headers.entries()))
+            }
+        });
+    }
+    else {
+        console.warn('traceError: Skipping HTTP error tracing - no X-Request-ID header');
+    }
     return error;
 };

package/dist/hooks/trace_request.js

@@ -6,6 +6,12 @@ import { config } from '#config.js';
  * Respects LOG_HTTP_VERBOSE environment variable for detailed logging
  */
 export const traceRequest = async (request, _options) => {
+    const traceId = createTraceId(request);
+    // Skip tracing if no X-Request-ID header is present
+    if (!traceId) {
+        console.warn('traceRequest: Skipping request tracing - no X-Request-ID header');
+        return;
+    }
     const details = {
         method: request.method,
         url: request.url
@@ -15,5 +21,5 @@ export const traceRequest = async (request, _options) => {
         details.headers = redactHeaders(headers);
         details.body = await parseRequestBody(request);
     }
-    Tracing.addEventStart({ id: createTraceId(request), kind: 'http', name: 'request', details });
+    Tracing.addEventStart({ id: traceId, kind: 'http', name: 'request', details });
 };

package/dist/hooks/trace_response.js

@@ -1,12 +1,17 @@
 import { Tracing } from '@output.ai/core/tracing';
 import { redactHeaders, createTraceId, parseResponseBody } from '#utils/index.js';
-;
 import { config } from '#config.js';
 /**
  * Traces HTTP response for observability using Output SDK tracing
  * Respects LOG_HTTP_VERBOSE environment variable for detailed logging
  */
 export const traceResponse = async (request, _options, response) => {
+    const traceId = createTraceId(request);
+    // Skip tracing if no X-Request-ID header is present
+    if (!traceId) {
+        console.warn('traceResponse: Skipping response tracing - no X-Request-ID header');
+        return response;
+    }
     const details = {
         status: response.status,
         statusText: response.statusText
@@ -16,6 +21,6 @@ export const traceResponse = async (request, _options, response) => {
         details.headers = redactHeaders(responseHeaders);
         details.body = await parseResponseBody(response);
     }
-    Tracing.addEventEnd({ id: createTraceId(request), details });
+    Tracing.addEventEnd({ id: traceId, details });
     return response;
 };

package/dist/index.integration.test.js

@@ -1,8 +1,30 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import ky from 'ky';
 import { httpClient } from './index.js';
+import { Tracing } from '@output.ai/core/tracing';
+import createTraceId from './utils/create_trace_id.js';
+import { traceRequest, traceResponse, traceError } from './hooks/index.js';
+import { applyFetchErrorTracing } from './hooks/trace_error.js';
+// Helper function for trace ID format validation
+const isUuidFormat = (traceId) => {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(traceId);
+};
+vi.mock('@output.ai/core/tracing', () => ({
+    Tracing: {
+        addEventStart: vi.fn(),
+        addEventEnd: vi.fn(),
+        addEventError: vi.fn()
+    }
+}));
+const mockedTracing = vi.mocked(Tracing, true);
+// Helper to get header value (httpbingo returns arrays)
+const getHeader = (headers, key) => {
+    const value = headers[key];
+    return Array.isArray(value) ? value[0] : value;
+};
 describe('HTTP Client Authentication Integration', () => {
     const httpBinClient = httpClient({
-        prefixUrl: 'https://httpbin.org',
+        prefixUrl: 'https://httpbingo.org',
         timeout: 5000
     });
     const clientsClient = httpBinClient.extend({
@@ -19,15 +41,16 @@ describe('HTTP Client Authentication Integration', () => {
         it('should include API key for clients endpoints', async () => {
             const response = await clientsClient.get('anything/clients');
             const data = await response.json();
-            expect(data.headers['X-Api-Key']).toBe('demo-api-key-12345');
+            expect(getHeader(data.headers, 'X-Api-Key')).toBe('demo-api-key-12345');
             expect(data.url).toContain('/anything/clients');
             expect(data.method).toBe('GET');
         }, 10000);
         it('should include Basic auth for contracts endpoints', async () => {
             const response = await contractsClient.get('anything/contracts');
             const data = await response.json();
-            expect(data.headers['Authorization']).toMatch(/^Basic /);
-            expect(data.headers['Authorization']).toBe(`Basic ${Buffer.from('demo-user:demo-pass').toString('base64')}`);
+            const authHeader = getHeader(data.headers, 'Authorization');
+            expect(authHeader).toMatch(/^Basic /);
+            expect(authHeader).toBe(`Basic ${Buffer.from('demo-user:demo-pass').toString('base64')}`);
             expect(data.url).toContain('/anything/contracts');
         }, 10000);
         it('should remove auth headers when overridden with undefined', async () => {
@@ -35,14 +58,14 @@ describe('HTTP Client Authentication Integration', () => {
                 headers: { 'X-API-Key': undefined }
             });
             const data = await response.json();
-            expect(data.headers['X-Api-Key']).toBeUndefined();
+            expect(getHeader(data.headers, 'X-Api-Key')).toBeUndefined();
             expect(data.url).toContain('/anything/clients/export');
         }, 10000);
         it('should properly handle POST with JSON data and authentication', async () => {
             const testData = { name: 'Test Client', email: 'test@example.com' };
             const response = await clientsClient.post('anything/clients', { json: testData });
             const data = await response.json();
-            expect(data.headers['X-Api-Key']).toBe('demo-api-key-12345');
+            expect(getHeader(data.headers, 'X-Api-Key')).toBe('demo-api-key-12345');
             expect(data.json).toEqual(testData);
             expect(data.method).toBe('POST');
         }, 10000);
@@ -75,7 +98,7 @@ describe('HTTP Client Authentication Integration', () => {
                 }
             });
             const data = await response.json();
-            expect(data.headers['X-Api-Key']).toBe('different-key-456');
+            expect(getHeader(data.headers, 'X-Api-Key')).toBe('different-key-456');
         }, 10000);
         it('should support multiple authentication methods', async () => {
             const response = await contractsClient.get('anything/contracts/special', {
@@ -85,33 +108,282 @@ describe('HTTP Client Authentication Integration', () => {
                 }
             });
             const data = await response.json();
-            expect(data.headers['Authorization']).toMatch(/^Basic /);
-            expect(data.headers['X-Special-Token']).toBe('special-value');
-            expect(data.headers['X-Client-Id']).toBe('client-123');
+            expect(getHeader(data.headers, 'Authorization')).toMatch(/^Basic /);
+            expect(getHeader(data.headers, 'X-Special-Token')).toBe('special-value');
+            expect(getHeader(data.headers, 'X-Client-Id')).toBe('client-123');
         }, 10000);
     });
     describe('Real API Client Pattern', () => {
         it('should demonstrate the complete authentication pattern', async () => {
             const clientsResponse = await clientsClient.get('anything/clients');
             const clientsData = await clientsResponse.json();
-            expect(clientsData.headers['X-Api-Key']).toBe('demo-api-key-12345');
+            expect(getHeader(clientsData.headers, 'X-Api-Key')).toBe('demo-api-key-12345');
             const createResponse = await clientsClient.post('anything/clients', {
                 json: { name: 'Test Client', email: 'test@example.com' }
             });
             const createData = await createResponse.json();
-            expect(createData.headers['X-Api-Key']).toBe('demo-api-key-12345');
+            expect(getHeader(createData.headers, 'X-Api-Key')).toBe('demo-api-key-12345');
             const exportResponse = await clientsClient.get('anything/clients/export', { headers: { 'X-API-Key': undefined } });
             const exportData = await exportResponse.json();
-            expect(exportData.headers['X-Api-Key']).toBeUndefined();
+            expect(getHeader(exportData.headers, 'X-Api-Key')).toBeUndefined();
             const contractsResponse = await contractsClient.get('anything/contracts');
             const contractsResponseData = await contractsResponse.json();
-            expect(contractsResponseData.headers['Authorization']).toMatch(/^Basic /);
+            expect(getHeader(contractsResponseData.headers, 'Authorization')).toMatch(/^Basic /);
             const contractCreateResponse = await contractsClient.post('anything/contracts', {
                 json: { clientId: '123', title: 'Service Agreement', value: 10000 }
             });
             const contractCreateData = await contractCreateResponse.json();
-            expect(contractCreateData.headers['Authorization']).toMatch(/^Basic /);
-            console.log('✅ All authentication patterns working correctly');
+            expect(getHeader(contractCreateData.headers, 'Authorization')).toMatch(/^Basic /);
         }, 15000);
     });
+    describe('Error Tracing', () => {
+        beforeEach(() => {
+            mockedTracing.addEventStart.mockClear();
+            mockedTracing.addEventEnd.mockClear();
+            mockedTracing.addEventError.mockClear();
+        });
+        it('should trace timeout errors exactly once (no double-tracing)', async () => {
+            const timeoutClient = httpClient({
+                prefixUrl: 'https://httpbingo.org',
+                timeout: 1 // 1ms timeout will definitely fail on /delay/5
+            });
+            // Timeout will throw either TimeoutError or DOMException (AbortError)
+            await expect(timeoutClient.get('delay/5')).rejects.toThrow();
+            // Timeout errors should be traced by the wrapped fetch exactly once
+            expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+            const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+            expect(errorCall).toHaveProperty('id');
+            expect(errorCall).toHaveProperty('details');
+            // In real execution, ky's timeout throws a DOMException (AbortError)
+            expect(errorCall.details).toHaveProperty('message');
+            expect(errorCall.details.message).toMatch(/Fetch aborted|Unknown error/);
+        }, 10000);
+    });
+    describe('Trace ID Lifecycle', () => {
+        beforeEach(() => {
+            mockedTracing.addEventStart.mockClear();
+            mockedTracing.addEventEnd.mockClear();
+            mockedTracing.addEventError.mockClear();
+        });
+        it('should use same UUID trace ID for addEventStart and addEventEnd on successful requests', async () => {
+            const response = await httpBinClient.get('anything/success-trace');
+            expect(response.status).toBe(200);
+            expect(mockedTracing.addEventStart).toHaveBeenCalledTimes(1);
+            expect(mockedTracing.addEventEnd).toHaveBeenCalledTimes(1);
+            const startCall = mockedTracing.addEventStart.mock.calls[0][0];
+            const endCall = mockedTracing.addEventEnd.mock.calls[0][0];
+            expect(isUuidFormat(startCall.id)).toBe(true);
+            expect(isUuidFormat(endCall.id)).toBe(true);
+            expect(startCall.id).toBe(endCall.id);
+        }, 10000);
+        it('should use same UUID trace ID for addEventStart and addEventError on HTTP errors', async () => {
+            const noRetryClient = httpBinClient.extend({
+                retry: { limit: 0 }
+            });
+            await expect(noRetryClient.get('status/500')).rejects.toThrow();
+            expect(mockedTracing.addEventStart).toHaveBeenCalledTimes(1);
+            expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+            const startCall = mockedTracing.addEventStart.mock.calls[0][0];
+            const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+            expect(isUuidFormat(startCall.id)).toBe(true);
+            expect(isUuidFormat(errorCall.id)).toBe(true);
+            expect(startCall.id).toBe(errorCall.id);
+        }, 10000);
+        it('should use same UUID trace ID for addEventStart and addEventError on timeout errors', async () => {
+            const timeoutClient = httpClient({
+                prefixUrl: 'https://httpbingo.org',
+                timeout: 50
+            });
+            await expect(timeoutClient.get('delay/2')).rejects.toThrow();
+            expect(mockedTracing.addEventStart).toHaveBeenCalledTimes(1);
+            expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+            const startCall = mockedTracing.addEventStart.mock.calls[0][0];
+            const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+            expect(isUuidFormat(startCall.id)).toBe(true);
+            expect(isUuidFormat(errorCall.id)).toBe(true);
+            expect(startCall.id).toBe(errorCall.id);
+        }, 10000);
+        it('should maintain trace ID consistency between ky hooks and wrapped fetch', async () => {
+            const errorClient = httpClient({
+                prefixUrl: 'https://httpbingo.org',
+                timeout: 1,
+                retry: { limit: 0 }
+            });
+            try {
+                await errorClient.get('delay/5');
+                expect.fail('Should have thrown timeout error');
+            }
+            catch {
+                // Expected timeout error
+            }
+            expect(mockedTracing.addEventStart).toHaveBeenCalledTimes(1);
+            expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+            const startCall = mockedTracing.addEventStart.mock.calls[0][0];
+            const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+            expect(isUuidFormat(startCall.id)).toBe(true);
+            expect(isUuidFormat(errorCall.id)).toBe(true);
+            expect(startCall.id).toBe(errorCall.id);
+        }, 10000);
+        it('should always use UUID format when assignRequestId hook is present', async () => {
+            const scenarios = [
+                { method: 'GET', url: 'anything/test-1' },
+                { method: 'POST', url: 'anything/test-2', body: { data: 'test' } },
+                { method: 'PUT', url: 'anything/test-3', body: { update: true } },
+                { method: 'DELETE', url: 'anything/test-4' }
+            ];
+            for (const scenario of scenarios) {
+                mockedTracing.addEventStart.mockClear();
+                mockedTracing.addEventEnd.mockClear();
+                if (scenario.method === 'GET') {
+                    await httpBinClient.get(scenario.url);
+                }
+                else if (scenario.method === 'POST') {
+                    await httpBinClient.post(scenario.url, { json: scenario.body });
+                }
+                else if (scenario.method === 'PUT') {
+                    await httpBinClient.put(scenario.url, { json: scenario.body });
+                }
+                else if (scenario.method === 'DELETE') {
+                    await httpBinClient.delete(scenario.url);
+                }
+                const startCall = mockedTracing.addEventStart.mock.calls[0][0];
+                const endCall = mockedTracing.addEventEnd.mock.calls[0][0];
+                expect(isUuidFormat(startCall.id)).toBe(true);
+                expect(isUuidFormat(endCall.id)).toBe(true);
+                expect(startCall.id).toBe(endCall.id);
+            }
+        }, 15000);
+    });
+    describe('No Tracing Without X-Request-ID', () => {
+        beforeEach(() => {
+            mockedTracing.addEventStart.mockClear();
+            mockedTracing.addEventEnd.mockClear();
+            mockedTracing.addEventError.mockClear();
+            vi.spyOn(console, 'warn').mockImplementation(() => { });
+        });
+        afterEach(() => {
+            vi.restoreAllMocks();
+        });
+        it('should skip tracing when assignRequestId hook is not present', async () => {
+            const noUuidClient = ky.create({
+                prefixUrl: 'https://httpbingo.org',
+                hooks: {
+                    beforeRequest: [
+                        traceRequest
+                    ],
+                    afterResponse: [
+                        traceResponse
+                    ],
+                    beforeError: [
+                        traceError
+                    ]
+                }
+            });
+            const wrappedNoUuidClient = noUuidClient.extend({
+                fetch: applyFetchErrorTracing(globalThis.fetch)
+            });
+            const response = await wrappedNoUuidClient.get('anything/no-trace-test');
+            expect(response.status).toBe(200);
+            // No tracing should occur without X-Request-ID
+            expect(mockedTracing.addEventStart).not.toHaveBeenCalled();
+            expect(mockedTracing.addEventEnd).not.toHaveBeenCalled();
+            // Warning should be logged
+            expect(console.warn).toHaveBeenCalledWith('createTraceId: X-Request-ID header not found. Tracing will be skipped for this request.');
+        }, 10000);
+        it('should skip tracing for errors when X-Request-ID is missing', async () => {
+            const noUuidClient = ky.create({
+                prefixUrl: 'https://httpbingo.org',
+                hooks: {
+                    beforeRequest: [traceRequest],
+                    afterResponse: [traceResponse],
+                    beforeError: [traceError]
+                },
+                retry: { limit: 0 }
+            }).extend({
+                fetch: applyFetchErrorTracing(globalThis.fetch)
+            });
+            await expect(noUuidClient.get('status/500')).rejects.toThrow();
+            // No error tracing should occur without X-Request-ID
+            expect(mockedTracing.addEventStart).not.toHaveBeenCalled();
+            expect(mockedTracing.addEventError).not.toHaveBeenCalled();
+            // Warning should be logged
+            expect(console.warn).toHaveBeenCalled();
+        }, 10000);
+    });
+    describe('Trace ID Generation - Request Object Validation', () => {
+        beforeEach(() => {
+            mockedTracing.addEventStart.mockClear();
+            mockedTracing.addEventEnd.mockClear();
+            mockedTracing.addEventError.mockClear();
+        });
+        it('should pass a valid Request object to createTraceId', async () => {
+            const response = await httpBinClient.get('anything/trace-validation');
+            expect(response.status).toBe(200);
+            expect(mockedTracing.addEventStart).toHaveBeenCalled();
+            const startCall = mockedTracing.addEventStart.mock.calls[0][0];
+            const traceId = startCall.id;
+            // Trace ID should be a UUID from X-Request-ID header
+            expect(isUuidFormat(traceId)).toBe(true);
+            // An empty object would return null (no X-Request-ID header)
+            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            const emptyObjectResult = createTraceId({});
+            expect(emptyObjectResult).toBeNull();
+            warnSpy.mockRestore();
+        }, 10000);
+        it('should produce different trace IDs for GET vs POST to same endpoint', async () => {
+            mockedTracing.addEventStart.mockClear();
+            // Make GET request to specific endpoint
+            const getResponse = await httpBinClient.get('anything/trace-same-endpoint');
+            expect(getResponse.status).toBe(200);
+            expect(mockedTracing.addEventStart).toHaveBeenCalled();
+            const getTraceId = mockedTracing.addEventStart.mock.calls[0][0].id;
+            mockedTracing.addEventStart.mockClear();
+            // Make POST request to SAME endpoint
+            const postResponse = await httpBinClient.post('anything/trace-same-endpoint', { json: { data: 'test' } });
+            expect(postResponse.status).toBe(200);
+            expect(mockedTracing.addEventStart).toHaveBeenCalled();
+            const postTraceId = mockedTracing.addEventStart.mock.calls[0][0].id;
+            expect(getTraceId).not.toBe(postTraceId);
+            expect(isUuidFormat(getTraceId)).toBe(true);
+            expect(isUuidFormat(postTraceId)).toBe(true);
+        }, 10000);
+        it('should generate unique trace IDs for identical requests', async () => {
+            mockedTracing.addEventStart.mockClear();
+            const response1 = await httpBinClient.get('anything/unique-requests-1');
+            expect(response1.status).toBe(200);
+            expect(mockedTracing.addEventStart).toHaveBeenCalled();
+            const traceId1 = mockedTracing.addEventStart.mock.calls[0][0].id;
+            mockedTracing.addEventStart.mockClear();
+            const response2 = await httpBinClient.get('anything/unique-requests-1');
+            expect(response2.status).toBe(200);
+            expect(mockedTracing.addEventStart).toHaveBeenCalled();
+            const traceId2 = mockedTracing.addEventStart.mock.calls[0][0].id;
+            expect(isUuidFormat(traceId1)).toBe(true);
+            expect(isUuidFormat(traceId2)).toBe(true);
+            expect(traceId1).not.toBe(traceId2);
+        }, 10000);
+        it('should maintain trace ID consistency during timeout errors', async () => {
+            const timeoutClient = httpClient({
+                prefixUrl: 'https://httpbingo.org',
+                timeout: 300
+            });
+            mockedTracing.addEventStart.mockClear();
+            mockedTracing.addEventError.mockClear();
+            try {
+                await timeoutClient.get('delay/3');
+                expect.fail('Should have thrown timeout error');
+            }
+            catch {
+                expect(mockedTracing.addEventStart).toHaveBeenCalled();
+                const startCall = mockedTracing.addEventStart.mock.calls[0][0];
+                const requestTraceId = startCall.id;
+                expect(mockedTracing.addEventError).toHaveBeenCalled();
+                const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+                const errorTraceId = errorCall.id;
+                expect(isUuidFormat(requestTraceId)).toBe(true);
+                expect(isUuidFormat(errorTraceId)).toBe(true);
+                expect(requestTraceId).toBe(errorTraceId);
+            }
+        }, 10000);
+    });
 });

package/dist/index.js

@@ -1,9 +1,11 @@
 import ky from 'ky';
-import { traceRequest, traceResponse, traceError } from './hooks/index.js';
+import { assignRequestId, traceRequest, traceResponse, traceError } from './hooks/index.js';
+import { applyFetchErrorTracing } from '#hooks/trace_error.js';
 // Create base HTTP client with standard Output SDK tracing hooks
 const baseHttpClient = ky.create({
     hooks: {
         beforeRequest: [
+            assignRequestId,
             traceRequest
         ],
         afterResponse: [
@@ -14,6 +16,14 @@ const baseHttpClient = ky.create({
         ]
     }
 });
+const applyDefaultOptions = (userOptions) => (parentOptions) => {
+    const kyFetch = parentOptions.fetch || globalThis.fetch.bind(globalThis);
+    const patchedFetch = applyFetchErrorTracing(kyFetch);
+    return {
+        fetch: patchedFetch,
+        ...userOptions
+    };
+};
 /**
  * Creates an HTTP client with Output SDK tracing
  *
@@ -35,6 +45,6 @@ const baseHttpClient = ky.create({
  * ```
  */
 export function httpClient(options = {}) {
-    return baseHttpClient.extend(options);
+    return baseHttpClient.extend(applyDefaultOptions(options));
 }
 export { HTTPError, TimeoutError } from 'ky';

package/dist/index.spec.js

@@ -20,12 +20,80 @@ vi.mock('ky', () => {
         status: 200,
         headers: { 'content-type': 'application/json' }
     });
+    // Mock error types that match ky's actual error classes
+    // IMPORTANT: These must be the same instances exported by the mock
+    // so that instanceof checks work correctly
+    class MockHTTPError extends Error {
+        response;
+        request;
+        options;
+        constructor(response, request, options) {
+            super(`${response.status} ${response.statusText}`);
+            this.name = 'HTTPError';
+            this.response = response;
+            this.request = request;
+            this.options = options;
+        }
+    }
+    class MockTimeoutError extends Error {
+        request;
+        constructor(request) {
+            super('Request timed out');
+            this.name = 'TimeoutError';
+            this.request = request;
+        }
+    }
+    // Helper to extract URL string from various input types
+    const getUrlString = (input) => {
+        if (typeof input === 'string') {
+            return input;
+        }
+        if (input instanceof Request) {
+            return input.url;
+        }
+        return input.toString();
+    };
+    // Default mock fetch implementation
+    const defaultMockFetch = (input, init) => {
+        const urlStr = getUrlString(input);
+        const request = input instanceof Request ? input : new Request(urlStr, init);
+        // Simulate timeout error (bypass hooks, thrown at fetch level)
+        if (urlStr.includes('/timeout')) {
+            throw new MockTimeoutError(request);
+        }
+        // Simulate network error (bypass hooks, thrown at fetch level)
+        if (urlStr.includes('/network-error')) {
+            throw new TypeError('Failed to fetch');
+        }
+        // Simulate HTTP 500 error (goes through hooks)
+        if (urlStr.includes('/500')) {
+            return Promise.resolve(new Response('Internal Server Error', {
+                status: 500,
+                statusText: 'Internal Server Error'
+            }));
+        }
+        // Simulate HTTP 404 error (goes through hooks)
+        if (urlStr.includes('/404')) {
+            return Promise.resolve(new Response('Not Found', {
+                status: 404,
+                statusText: 'Not Found'
+            }));
+        }
+        return Promise.resolve(createMockResponse());
+    };
     class MockKy {
         hooks = {};
         options = {};
+        customFetch;
         constructor(options = {}) {
             this.hooks = options.hooks || {};
-            this.options = options;
+            // Use provided fetch or default mock fetch
+            this.customFetch = options.fetch || defaultMockFetch;
+            // Store options with fetch function included
+            this.options = {
+                ...options,
+                fetch: this.customFetch
+            };
         }
         async runHooks(hookType, ...args) {
             const hooks = this.hooks[hookType] || [];
@@ -54,16 +122,33 @@ vi.mock('ky', () => {
             const request = new Request(fullUrl, { method });
             // Run beforeRequest hooks
             await this.runHooks('beforeRequest', request);
-            const response = createMockResponse();
-            // Run afterResponse hooks
+            // Use the custom fetch (which may be wrapped by applyFetchErrorTracing)
+            // Fetch-level errors (timeout, network) bypass hooks entirely and will throw
+            const response = await this.customFetch(request, { method });
+            // Check for HTTP errors (non-2xx status codes)
+            if (!response.ok) {
+                const httpError = new MockHTTPError(response, request, options);
+                // Run beforeError hooks for HTTP errors
+                try {
+                    await this.runHooks('beforeError', httpError);
+                }
+                catch (hookErr) {
+                    // Hooks can transform the error
+                    throw hookErr;
+                }
+                throw httpError;
+            }
+            // Run afterResponse hooks for successful responses
             await this.runHooks('afterResponse', request, options, response);
             return response;
         }
         extend(options = {}) {
-            const mergedOptions = { ...this.options, ...options };
+            // Handle function-based options (like applyDefaultOptions returns)
+            const resolvedOptions = typeof options === 'function' ? options(this.options) : options;
+            const mergedOptions = { ...this.options, ...resolvedOptions };
             const mergedHooks = { ...this.hooks };
-            if (options.hooks) {
-                Object.entries(options.hooks).forEach(([hookType, hookArray]) => {
+            if (resolvedOptions.hooks) {
+                Object.entries(resolvedOptions.hooks).forEach(([hookType, hookArray]) => {
                     mergedHooks[hookType] = [
                         ...(this.hooks[hookType] || []),
                         ...(Array.isArray(hookArray) ? hookArray : [])
@@ -80,18 +165,8 @@ vi.mock('ky', () => {
     return {
         default: new MockKy(),
         create: (options) => new MockKy(options),
-        HTTPError: class HTTPError extends Error {
-            constructor(message) {
-                super(message);
-                this.name = 'HTTPError';
-            }
-        },
-        TimeoutError: class TimeoutError extends Error {
-            constructor(message) {
-                super(message);
-                this.name = 'TimeoutError';
-            }
-        }
+        HTTPError: MockHTTPError,
+        TimeoutError: MockTimeoutError
     };
 });
 const mockedTracing = vi.mocked(Tracing, true);
@@ -182,7 +257,7 @@ describe('HTTP Client', () => {
                         }
                     ],
                     afterResponse: [
-                        async (request, options, response) => {
+                        async (_request, _options, response) => {
                             customAfterResponseCalled();
                             return response;
                         }
@@ -225,4 +300,92 @@ describe('HTTP Client', () => {
             expect(postData.success).toBe(true);
         });
     });
+    describe('Error Tracing', () => {
+        describe('Fetch-Level Errors (should be traced by wrapped fetch)', () => {
+            it('should trace timeout errors that bypass ky hooks', async () => {
+                const client = httpClient({
+                    prefixUrl: 'https://api.example.com'
+                });
+                await expect(client.get('users/timeout')).rejects.toThrow(TimeoutError);
+                // Timeout errors should be traced by the wrapped fetch
+                expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+                const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+                expect(errorCall).toHaveProperty('id');
+                expect(errorCall).toHaveProperty('details');
+                expect(errorCall.details).toHaveProperty('message');
+                expect(errorCall.details).toHaveProperty('error');
+            });
+            it('should trace network errors that bypass ky hooks', async () => {
+                const client = httpClient({
+                    prefixUrl: 'https://api.example.com'
+                });
+                await expect(client.get('users/network-error')).rejects.toThrow(TypeError);
+                // Network errors should be traced by the wrapped fetch
+                expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+                const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+                expect(errorCall).toHaveProperty('id');
+                expect(errorCall).toHaveProperty('details');
+                expect(errorCall.details).toHaveProperty('message');
+                expect(errorCall.details.message).toBe('Unknown error occurred');
+                expect(errorCall.details).toHaveProperty('error');
+            });
+        });
+        describe('HTTP Errors (should be traced by beforeError hook only)', () => {
+            it('should trace HTTP 500 errors via beforeError hook, not fetch wrapper', async () => {
+                const client = httpClient({
+                    prefixUrl: 'https://api.example.com'
+                });
+                await expect(client.get('users/500')).rejects.toThrow(HTTPError);
+                // HTTP errors should be traced by the beforeError hook (traceError)
+                // The wrapped fetch should NOT trace it (to prevent double-tracing)
+                expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+                const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+                expect(errorCall).toHaveProperty('id');
+                expect(errorCall).toHaveProperty('details');
+                expect(errorCall.details).toHaveProperty('status', 500);
+                expect(errorCall.details).toHaveProperty('statusText', 'Internal Server Error');
+            });
+            it('should trace HTTP 404 errors via beforeError hook, not fetch wrapper', async () => {
+                const client = httpClient({
+                    prefixUrl: 'https://api.example.com'
+                });
+                await expect(client.get('users/404')).rejects.toThrow(HTTPError);
+                // HTTP errors should be traced by the beforeError hook (traceError)
+                expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+                const errorCall = mockedTracing.addEventError.mock.calls[0][0];
+                expect(errorCall).toHaveProperty('id');
+                expect(errorCall).toHaveProperty('details');
+                expect(errorCall.details).toHaveProperty('status', 404);
+                expect(errorCall.details).toHaveProperty('statusText', 'Not Found');
+            });
+            it('should not double-trace HTTP errors', async () => {
+                const client = httpClient({
+                    prefixUrl: 'https://api.example.com'
+                });
+                await expect(client.get('users/500')).rejects.toThrow(HTTPError);
+                // Should only be traced once (by beforeError hook)
+                expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+            });
+        });
+        describe('Error Type Differentiation', () => {
+            it('should handle timeout and HTTP errors differently in the same client', async () => {
+                const client = httpClient({
+                    prefixUrl: 'https://api.example.com'
+                });
+                // Test timeout error
+                mockedTracing.addEventError.mockClear();
+                await expect(client.get('users/timeout')).rejects.toThrow(TimeoutError);
+                expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+                const timeoutCall = mockedTracing.addEventError.mock.calls[0][0];
+                expect(timeoutCall.details).toHaveProperty('message');
+                expect(timeoutCall.details).toHaveProperty('error');
+                // Test HTTP error
+                mockedTracing.addEventError.mockClear();
+                await expect(client.get('users/500')).rejects.toThrow(HTTPError);
+                expect(mockedTracing.addEventError).toHaveBeenCalledTimes(1);
+                const httpCall = mockedTracing.addEventError.mock.calls[0][0];
+                expect(httpCall.details).toHaveProperty('status', 500);
+            });
+        });
+    });
 });

package/dist/utils/create_trace_id.d.ts

@@ -1,8 +1,13 @@
-import type { KyRequest } from 'ky';
 /**
- * Created an trace id based on the KyRequest
+ * Create a trace ID from the X-Request-ID header
  *
- * @param {KyRequest} request
- * @returns {string} A unique trace id
+ * Returns the X-Request-ID header value if present, otherwise returns null.
+ * When null is returned, tracing should be skipped entirely.
+ *
+ * The X-Request-ID header is assigned by the assignRequestId hook,
+ * ensuring each request invocation has a unique identifier for tracing.
+ *
+ * @param {Request} request - The fetch API request object
+ * @returns {string | null} The X-Request-ID value or null if not present
  */
-export default function createTraceId(request: KyRequest): string;
+export default function createTraceId(request: Request): string | null;

package/dist/utils/create_trace_id.js

@@ -1,10 +1,20 @@
-import { createHash } from 'node:crypto';
 /**
- * Created an trace id based on the KyRequest
+ * Create a trace ID from the X-Request-ID header
  *
- * @param {KyRequest} request
- * @returns {string} A unique trace id
+ * Returns the X-Request-ID header value if present, otherwise returns null.
+ * When null is returned, tracing should be skipped entirely.
+ *
+ * The X-Request-ID header is assigned by the assignRequestId hook,
+ * ensuring each request invocation has a unique identifier for tracing.
+ *
+ * @param {Request} request - The fetch API request object
+ * @returns {string | null} The X-Request-ID value or null if not present
  */
 export default function createTraceId(request) {
-    return createHash('md5').update(JSON.stringify(request)).digest('hex');
+    const requestId = request.headers?.get('X-Request-ID');
+    if (!requestId) {
+        console.warn('createTraceId: X-Request-ID header not found. Tracing will be skipped for this request.');
+        return null;
+    }
+    return requestId;
 }

package/dist/utils/create_trace_id.spec.js

@@ -1,12 +1,20 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import createTraceId from './create_trace_id.js';
 describe('utils/create_trace_id', () => {
-    it('creates a deterministic md5 hash id from request', () => {
+    it('returns the X-Request-ID header when present', () => {
+        const req = new Request('https://ex.com/users/1', {
+            method: 'GET',
+            headers: { 'X-Request-ID': 'test-uuid-123' }
+        });
+        const id = createTraceId(req);
+        expect(id).toBe('test-uuid-123');
+    });
+    it('returns null and logs warning when X-Request-ID header is missing', () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
         const req = new Request('https://ex.com/users/1', { method: 'GET' });
-        const id1 = createTraceId(req);
-        const id2 = createTraceId(req);
-        expect(typeof id1).toBe('string');
-        expect(id1).toHaveLength(32);
-        expect(id1).toBe(id2);
+        const id = createTraceId(req);
+        expect(id).toBeNull();
+        expect(warnSpy).toHaveBeenCalledWith('createTraceId: X-Request-ID header not found. Tracing will be skipped for this request.');
+        warnSpy.mockRestore();
     });
 });

package/dist/utils/parse_request_body.d.ts

@@ -1,8 +1,7 @@
-import type { KyRequest } from 'ky';
 /**
  * Safely parses request body as JSON, falling back to string if parsing fails
  *
- * @param {KyRequest} request
+ * @param {Request} request - The fetch API request object
  * @returns {object|string|null} The parsed response
  */
-export default function parseRequestBody(request: KyRequest): Promise<object | string | null>;
+export default function parseRequestBody(request: Request): Promise<object | string | null>;

package/dist/utils/parse_request_body.js

@@ -1,7 +1,7 @@
 /**
  * Safely parses request body as JSON, falling back to string if parsing fails
  *
- * @param {KyRequest} request
+ * @param {Request} request - The fetch API request object
  * @returns {object|string|null} The parsed response
  */
 export default async function parseRequestBody(request) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/http",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Framework abstraction to make HTTP calls with tracing",
   "type": "module",
   "main": "dist/index.js",