@outputai/core 0.9.3-next.5289bca.0 → 0.9.3-next.67c8141.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.9.3-next.5289bca.0",
+  "version": "0.9.3-next.67c8141.0",
   "description": "The core module of the output framework",
   "type": "module",
   "engines": {

package/src/helpers/fetch.js

@@ -1,32 +1,79 @@
+import { FatalError } from '#errors';
+
+/** Matches red int "hot-red-pie", but not int "redact" */
+const wordMatcher = term => new RegExp( `(?<![a-z\\d])${term}(?![a-z\\d])`, 'i' );
+
+/** Matches red in "acquired", but not in "redact" */
+const wordEndMatcher = term => new RegExp( `${term}(?![a-z\\d])`, 'i' );
+
+/**
+ * Redacts sensitive headers
+ * @param {object} headers
+ * @returns {object} The redacted headers
+ */
+export const redactHeaders = headers => {
+  /** Header names that look sensitive by substring rules but are not secret material. */
+  const ignoreHeaders = new Set( [
+    'x-csrf-token',
+    'public-key-pins'
+  ] );
+
+  /** * Sensitive header patterns for redaction (case-insensitive). */
+  const sensitiveHeadersPatterns = [
+    // matches headers that contain these exact words
+    wordMatcher( 'authorization' ),
+    wordMatcher( 'token' ),
+    wordMatcher( 'secret' ),
+    wordMatcher( 'password' ),
+    wordMatcher( 'pwd' ),
+    wordMatcher( 'cookie' ),
+    // matches header that contain words ending with these sequences
+    wordEndMatcher( 'key' )
+  ];
+
+  return Object.entries( headers ).reduce( ( redacted, [ key, value ] ) => {
+    const lowKey = key.toLowerCase();
+    const isSensitive = !ignoreHeaders.has( lowKey ) && sensitiveHeadersPatterns.some( rx => rx.test( lowKey ) );
+    return Object.assign( redacted, { [key]: isSensitive ? '[REDACTED]' : value } );
+  }, {} );
+};
+
+/**
+ * Consume the body of a Response according it its content-type and returns it
+ * @param {Response} response
+ * @returns {string|object|undefined|null} The response body content
+ */
+const consumeBody = async response => {
+  const headers = Object.fromEntries( response.headers ) ?? {};
+  const contentType = ( headers['content-type'] ?? '' ).trim().toLowerCase();
+  const jsonMatcher = /^application\/(?:json|[^;\s]+?\+json)(?:\s*;.*)?$/i;
+  if ( jsonMatcher.test( contentType ) ) {
+    return response.json();
+  }
+  if ( contentType.startsWith( 'text/' ) ) {
+    return response.text();
+  }
+  return response.arrayBuffer().then( buf => Buffer.from( buf ).toString( 'base64' ) );
+};
+
 /**
  * Consume Fetch's HTTP Response and return a serialized version of it;
  *
  * @param {Response} response
+ * @param {options} responseOptions
+ * @param {boolean} responseOptions.includeBody - If the body must be included in the response (default false)
+ * @param {boolean} responseOptions.includeHeaders - If the redacted headers must be included in the response - headers are always redacted (default false)
  * @returns {object} Serialized response
  */
-export const serializeFetchResponse = async response => {
-  const headers = Object.fromEntries( response.headers );
-  const contentType = headers['content-type'] || '';
-
-  const body = await ( async () => {
-    if ( contentType.includes( 'application/json' ) ) {
-      return response.json();
-    }
-    if ( contentType.startsWith( 'text/' ) ) {
-      return response.text();
-    }
-    return response.arrayBuffer().then( buf => Buffer.from( buf ).toString( 'base64' ) );
-  } )();
-
-  return {
-    url: response.url,
-    status: response.status,
-    statusText: response.statusText,
-    ok: response.ok,
-    headers,
-    body
-  };
-};
+export const serializeResponse = async ( response, { includeHeaders = false, includeBody = false } = {} ) => ( {
+  url: response.url,
+  status: response.status,
+  statusText: response.statusText,
+  ok: response.ok,
+  ...( includeHeaders && { headers: redactHeaders( Object.fromEntries( response.headers ) ) } ),
+  ...( includeBody && { body: await consumeBody( response ) } )
+} );
+
 /**
  * Duck-typing to detect a Node Readable (Stream) without importing anything
  *
@@ -103,3 +150,21 @@ export const serializeBodyAndInferContentType = payload => {
 
   return { body: String( payload ), contentType: 'text/plain; charset=UTF-8' };
 };
+
+const getSecretFromEnv = varName => {
+  const value = process.env[varName];
+  if ( value === undefined ) {
+    throw new FatalError( `Missing environment variable "${varName}" while hydrating headers.` );
+  }
+  return value;
+};
+
+/**
+ * Replaces $VAR_NAME tokens in header values
+ * @param {object} headers
+ * @returns {object} Hydrated headers
+ */
+export const hydrateHeaders = headers =>
+  Object.entries( headers ?? {} ).reduce( ( o, [ key, value ] ) =>
+    Object.assign( o, { [key]: ( '' + value ).replace( /\$([A-Z_][A-Z0-9_]*)/g, ( _, _var ) => getSecretFromEnv( _var ) ) } )
+  , {} );

package/src/helpers/fetch.spec.js

@@ -1,9 +1,136 @@
-import { describe, it, expect } from 'vitest';
+import { afterEach, describe, it, expect } from 'vitest';
 import { Readable } from 'node:stream';
-import { serializeBodyAndInferContentType, serializeFetchResponse } from './fetch.js';
+import { hydrateHeaders, redactHeaders, serializeBodyAndInferContentType, serializeResponse } from './fetch.js';
 
-describe( 'serializeFetchResponse', () => {
-  it( 'serializes JSON response body and flattens headers', async () => {
+describe( 'redactHeaders', () => {
+  it( 'redacts sensitive header names', () => {
+    const result = redactHeaders( {
+      Authorization: 'Bearer token',
+      'X-Api-Key': 'api-key',
+      Cookie: 'session=id',
+      'x-client-secret': 'secret'
+    } );
+
+    expect( result ).toEqual( {
+      Authorization: '[REDACTED]',
+      'X-Api-Key': '[REDACTED]',
+      Cookie: '[REDACTED]',
+      'x-client-secret': '[REDACTED]'
+    } );
+  } );
+
+  it( 'preserves non-sensitive header names and ignored false positives', () => {
+    const result = redactHeaders( {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'x-csrf-token': 'csrf-token',
+      'public-key-pins': 'pin'
+    } );
+
+    expect( result ).toEqual( {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'x-csrf-token': 'csrf-token',
+      'public-key-pins': 'pin'
+    } );
+  } );
+
+  it( 'handles empty headers', () => {
+    expect( redactHeaders( {} ) ).toEqual( {} );
+  } );
+} );
+
+describe( 'hydrateHeaders', () => {
+  afterEach( () => {
+    delete process.env.TOKEN;
+    delete process.env.API_KEY;
+  } );
+
+  it( 'replaces environment variable tokens in header values', () => {
+    process.env.TOKEN = 'secret-token';
+
+    expect( hydrateHeaders( {
+      Authorization: 'Bearer $TOKEN'
+    } ) ).toEqual( {
+      Authorization: 'Bearer secret-token'
+    } );
+  } );
+
+  it( 'replaces repeated and multiple environment variable tokens', () => {
+    process.env.TOKEN = 'secret-token';
+    process.env.API_KEY = 'api-key';
+
+    expect( hydrateHeaders( {
+      Authorization: 'Bearer $TOKEN',
+      'X-Composite': '$TOKEN:$API_KEY:$TOKEN'
+    } ) ).toEqual( {
+      Authorization: 'Bearer secret-token',
+      'X-Composite': 'secret-token:api-key:secret-token'
+    } );
+  } );
+
+  it( 'preserves headers without environment variable tokens', () => {
+    expect( hydrateHeaders( {
+      Accept: 'application/json',
+      'Content-Type': 'application/json'
+    } ) ).toEqual( {
+      Accept: 'application/json',
+      'Content-Type': 'application/json'
+    } );
+  } );
+
+  it( 'handles missing headers', () => {
+    expect( hydrateHeaders() ).toEqual( {} );
+  } );
+
+  it( 'throws when an environment variable token is missing', () => {
+    expect( () => hydrateHeaders( {
+      Authorization: 'Bearer $TOKEN'
+    } ) ).toThrow( 'Missing environment variable "TOKEN" while hydrating headers.' );
+  } );
+} );
+
+describe( 'serializeResponse', () => {
+  it( 'serializes response metadata by default', async () => {
+    const response = new Response( '{not json', {
+      status: 200,
+      statusText: 'OK',
+      headers: { 'content-type': 'application/json' }
+    } );
+
+    await expect( serializeResponse( response ) ).resolves.toEqual( {
+      url: '',
+      status: 200,
+      statusText: 'OK',
+      ok: true
+    } );
+  } );
+
+  it( 'includes redacted headers when requested', async () => {
+    const response = new Response( null, {
+      status: 204,
+      statusText: 'No Content',
+      headers: {
+        authorization: 'Bearer token',
+        'content-type': 'application/json'
+      }
+    } );
+
+    const result = await serializeResponse( response, { includeHeaders: true } );
+
+    expect( result ).toEqual( {
+      url: '',
+      status: 204,
+      statusText: 'No Content',
+      ok: true,
+      headers: {
+        authorization: '[REDACTED]',
+        'content-type': 'application/json'
+      }
+    } );
+  } );
+
+  it( 'includes JSON body when requested', async () => {
     const payload = { a: 1, b: 'two' };
     const response = new Response( JSON.stringify( payload ), {
       status: 200,
@@ -11,32 +138,39 @@ describe( 'serializeFetchResponse', () => {
       headers: { 'content-type': 'application/json' }
     } );
 
-    const result = await serializeFetchResponse( response );
-    expect( result.status ).toBe( 200 );
-    expect( result.ok ).toBe( true );
-    expect( result.statusText ).toBe( 'OK' );
-    expect( result.headers['content-type'] ).toContain( 'application/json' );
+    const result = await serializeResponse( response, { includeBody: true } );
+
+    expect( result.body ).toEqual( payload );
+  } );
+
+  it( 'includes structured syntax JSON body when requested', async () => {
+    const payload = { error: 'Invalid input' };
+    const response = new Response( JSON.stringify( payload ), {
+      status: 400,
+      statusText: 'Bad Request',
+      headers: { 'content-type': 'application/problem+json; charset=utf-8' }
+    } );
+
+    const result = await serializeResponse( response, { includeBody: true } );
+
     expect( result.body ).toEqual( payload );
   } );
 
-  it( 'serializes text/* response via text()', async () => {
+  it( 'includes text body when requested', async () => {
     const bodyText = 'hello world';
     const response = new Response( bodyText, {
       status: 201,
       statusText: 'Created',
-      headers: { 'content-type': 'text/plain; charset=utf-8' }
+      headers: { 'content-type': 'Text/Plain; charset=utf-8' }
     } );
 
-    const result = await serializeFetchResponse( response );
-    expect( result.status ).toBe( 201 );
-    expect( result.ok ).toBe( true );
-    expect( result.statusText ).toBe( 'Created' );
-    expect( result.headers['content-type'] ).toContain( 'text/plain' );
+    const result = await serializeResponse( response, { includeBody: true } );
+
     expect( result.body ).toBe( bodyText );
   } );
 
   if ( typeof ReadableStream !== 'undefined' ) {
-    it( 'serializes ReadableStream body for text/* via text()', async () => {
+    it( 'includes ReadableStream text body when requested', async () => {
       const encoder = new TextEncoder();
       const chunk = encoder.encode( 'streamed text' );
       const stream = new ReadableStream( {
@@ -51,16 +185,13 @@ describe( 'serializeFetchResponse', () => {
         headers: { 'content-type': 'text/plain; charset=utf-8' }
       } );
 
-      const result = await serializeFetchResponse( response );
-      expect( result.status ).toBe( 200 );
-      expect( result.ok ).toBe( true );
-      expect( result.statusText ).toBe( 'OK' );
-      expect( result.headers['content-type'] ).toContain( 'text/plain' );
+      const result = await serializeResponse( response, { includeBody: true } );
+
       expect( result.body ).toBe( 'streamed text' );
     } );
   }
 
-  it( 'serializes non-text/non-json response as base64 from arrayBuffer()', async () => {
+  it( 'includes non-text non-json response as base64 when requested', async () => {
     const bytes = Uint8Array.from( [ 0, 1, 2, 3 ] );
     const response = new Response( bytes, {
       status: 200,
@@ -68,21 +199,17 @@ describe( 'serializeFetchResponse', () => {
       headers: { 'content-type': 'application/octet-stream' }
     } );
 
-    const result = await serializeFetchResponse( response );
-    expect( result.status ).toBe( 200 );
-    expect( result.ok ).toBe( true );
-    expect( result.statusText ).toBe( 'OK' );
-    expect( result.headers['content-type'] ).toBe( 'application/octet-stream' );
+    const result = await serializeResponse( response, { includeBody: true } );
+
     expect( result.body ).toBe( Buffer.from( bytes ).toString( 'base64' ) );
   } );
 
-  it( 'defaults to base64 when content-type header is missing', async () => {
+  it( 'defaults to base64 body when content-type header is missing and body is requested', async () => {
     const bytes = Uint8Array.from( [ 0, 1, 2, 3 ] );
     const response = new Response( bytes, { status: 200 } );
-    // No headers set; content-type resolves to ''
 
-    const result = await serializeFetchResponse( response );
-    expect( result.headers['content-type'] ?? '' ).toBe( '' );
+    const result = await serializeResponse( response, { includeBody: true } );
+
     expect( result.body ).toBe( Buffer.from( bytes ).toString( 'base64' ) );
   } );
 } );

package/src/helpers/trace_info.js

@@ -4,18 +4,15 @@ export class TraceInfo {
 
   /**
    * Builds the trace information propagated through workflow memo and activity headers.
-   * @param {object} options - Arguments to build trace information
-   * @param {boolean} options.disableTrace - Whether trace event emission should be disabled
    * @returns {object} trace information
    */
-  static build( { disableTrace } ) {
+  static build() {
     const info = inWorkflowContext() ? workflowInfo() : {};
     return {
       workflowId: info.workflowId,
       workflowType: info.workflowType,
       runId: info.runId,
-      startTime: info.startTime?.getTime(),
-      disableTrace
+      startTime: info.startTime?.getTime()
     };
   };
 }

package/src/helpers/trace_info.spec.js

@@ -23,24 +23,22 @@ describe( 'TraceInfo', () => {
       startTime: new Date( '2026-06-02T09:00:00.000Z' )
     } );
 
-    expect( TraceInfo.build( { disableTrace: false } ) ).toEqual( {
+    expect( TraceInfo.build() ).toEqual( {
       workflowId: 'workflow-id',
       workflowType: 'workflow-type',
       runId: 'run-id',
-      startTime: Date.parse( '2026-06-02T09:00:00.000Z' ),
-      disableTrace: false
+      startTime: Date.parse( '2026-06-02T09:00:00.000Z' )
     } );
   } );
 
   it( 'builds trace info without Temporal fields outside workflow context', () => {
     inWorkflowContextMock.mockReturnValue( false );
 
-    expect( TraceInfo.build( { disableTrace: true } ) ).toEqual( {
+    expect( TraceInfo.build() ).toEqual( {
       workflowId: undefined,
       workflowType: undefined,
       runId: undefined,
-      startTime: undefined,
-      disableTrace: true
+      startTime: undefined
     } );
     expect( workflowInfoMock ).not.toHaveBeenCalled();
   } );

package/src/interface/validations/index.spec.js

@@ -141,7 +141,8 @@ describe( 'interface validators', () => {
         url: 'https://example.com',
         method: 'POST',
         payload: { ok: true },
-        headers: { authorization: 'Bearer token' }
+        headers: { authorization: 'Bearer token' },
+        responseOptions: { includeHeaders: true, includeBody: true }
       } ) ).not.toThrow();
     } );
 
@@ -155,6 +156,12 @@ describe( 'interface validators', () => {
         url: 'https://example.com',
         method: 'OPTIONS'
       } ) ).toThrow( ValidationError );
+
+      expect( () => validateRequestPayload( {
+        url: 'https://example.com',
+        method: 'GET',
+        responseOptions: { includeHeaders: 'yes' }
+      } ) ).toThrow( ValidationError );
     } );
   } );
 

package/src/interface/validations/schemas.js

@@ -88,7 +88,11 @@ export const httpRequestSchema = z.object( {
   url: z.url( { protocol: /^https?$/ } ),
   method: z.enum( [ 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE' ] ),
   payload: z.any().optional(),
-  headers: z.record( z.string(), z.string() ).optional()
+  headers: z.record( z.string(), z.string() ).optional(),
+  responseOptions: z.strictObject( {
+    includeHeaders: z.boolean().optional().default( false ),
+    includeBody: z.boolean().optional().default( false )
+  } ).optional()
 } );
 
 export const workflowInvocationOptionsSchema = z.strictObject( {

package/src/interface/validations/schemas.spec.js

@@ -143,11 +143,26 @@ describe( 'validation schemas', () => {
         url: 'https://example.com',
         method: 'POST',
         payload: { ok: true },
-        headers: { authorization: 'Bearer token' }
+        headers: { authorization: 'Bearer token' },
+        responseOptions: { includeHeaders: true, includeBody: true }
       } ).success ).toBe( true );
     } );
 
-    it( 'rejects invalid URL protocols, methods, and header values', () => {
+    it( 'defaults omitted response options to false', () => {
+      const result = httpRequestSchema.safeParse( {
+        url: 'https://example.com',
+        method: 'GET',
+        responseOptions: {}
+      } );
+
+      expect( result.success ).toBe( true );
+      expect( result.data.responseOptions ).toEqual( {
+        includeHeaders: false,
+        includeBody: false
+      } );
+    } );
+
+    it( 'rejects invalid URL protocols, methods, header values, and response options', () => {
       expect( httpRequestSchema.safeParse( { url: 'ftp://example.com', method: 'GET' } ).success ).toBe( false );
       expect( httpRequestSchema.safeParse( { url: 'https://example.com', method: 'OPTIONS' } ).success ).toBe( false );
       expect( httpRequestSchema.safeParse( {
@@ -155,6 +170,11 @@ describe( 'validation schemas', () => {
         method: 'GET',
         headers: { count: 1 }
       } ).success ).toBe( false );
+      expect( httpRequestSchema.safeParse( {
+        url: 'https://example.com',
+        method: 'GET',
+        responseOptions: { includeBody: 'yes' }
+      } ).success ).toBe( false );
     } );
   } );
 

package/src/interface/webhook.d.ts

@@ -3,6 +3,17 @@
  */
 export type HttpMethod = 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 
+/**
+ * Controls which response fields are included in the serialized HTTP response.
+ */
+export type ResponseOptions = {
+  /** Include redacted response headers in the returned value. */
+  includeHeaders?: boolean,
+
+  /** Include the response body in the returned value. */
+  includeBody?: boolean
+};
+
 /** Represents a {Response} serialized to plain object */
 export type SerializedFetchResponse = {
   /** The response url */
@@ -18,10 +29,10 @@ export type SerializedFetchResponse = {
   ok: boolean,
 
   /** Object with response headers */
-  headers: Record<string, string>,
+  headers?: Record<string, string>,
 
   /** Response body, either JSON, text, or an arrayBuffer converted to base64 */
-  body: object | string
+  body?: unknown
 };
 
 /**
@@ -93,6 +104,7 @@ export declare function sendPostRequestAndAwaitWebhook( params: {
  * @param params.method - The HTTP method (default: 'GET')
  * @param params.payload - Request payload (only for POST/PUT)
  * @param params.headers - Headers for the request
+ * @param params.responseOptions - Controls which response fields are included
  * @returns Resolves with an HTTP response serialized to a plain object
  */
 export declare function sendHttpRequest( params: {
@@ -100,4 +112,5 @@ export declare function sendHttpRequest( params: {
   method?: HttpMethod;
   payload?: object;
   headers?: Record<string, string>;
+  responseOptions?: ResponseOptions;
 } ): Promise<SerializedFetchResponse>;

package/src/interface/webhook.js

@@ -12,10 +12,13 @@ import { validateRequestPayload } from './validations/index.js';
  * @param {string} method
  * @param {unknown} [payload]
  * @param {object} [headers]
+ * @param {object} [options.responseOptions] - Response options
+ * @param {boolean} [options.responseOptions.includeHeaders] - If the response will include the headers - Headers are always redacted (default false)
+ * @param {boolean} [options.responseOptions.includeBody] - If the response will include the body (default false)
  * @returns {Promise<object>} The serialized HTTP response
  */
-export async function sendHttpRequest( { url, method = 'GET', payload = undefined, headers = undefined } ) {
-  validateRequestPayload( { method, url, payload, headers } );
+export async function sendHttpRequest( { url, method = 'GET', payload = undefined, headers = undefined, responseOptions = {} } ) {
+  validateRequestPayload( { method, url, payload, headers, responseOptions } );
   const res = await proxyActivities( {
     startToCloseTimeout: '3m',
     retry: {
@@ -23,7 +26,7 @@ export async function sendHttpRequest( { url, method = 'GET', payload = undefine
       maximumAttempts: 3,
       nonRetryableErrorTypes: [ FatalError.name ]
     }
-  } )[ACTIVITY_SEND_HTTP_REQUEST]( { method, url, payload, headers } );
+  } )[ACTIVITY_SEND_HTTP_REQUEST]( { method, url, payload, headers, responseOptions } );
   return res.output;
 };
 

package/src/interface/webhook.spec.js

@@ -82,7 +82,12 @@ describe( 'interface/webhook', () => {
     const res = await sendHttpRequest( args );
 
     // validated
-    expect( validateRequestPayloadMock ).toHaveBeenCalledWith( { ...args, payload: undefined, headers: undefined } );
+    expect( validateRequestPayloadMock ).toHaveBeenCalledWith( {
+      ...args,
+      payload: undefined,
+      headers: undefined,
+      responseOptions: {}
+    } );
 
     // activity proxied with specified options
     expect( proxyActivitiesMock ).toHaveBeenCalledTimes( 1 );
@@ -95,10 +100,40 @@ describe( 'interface/webhook', () => {
     } ) );
 
     // activity invoked with the same args
-    expect( activityFnMock ).toHaveBeenCalledWith( { ...args, payload: undefined, headers: undefined } );
+    expect( activityFnMock ).toHaveBeenCalledWith( {
+      ...args,
+      payload: undefined,
+      headers: undefined,
+      responseOptions: {}
+    } );
     expect( res ).toEqual( fakeSerializedResponse );
   } );
 
+  it( 'sendHttpRequest forwards response options', async () => {
+    const { sendHttpRequest } = await import( './webhook.js' );
+
+    activityFnMock.mockResolvedValueOnce( activityEnvelope( { ok: true } ) );
+
+    const args = {
+      url: 'https://example.com/api',
+      method: 'GET',
+      responseOptions: { includeHeaders: true, includeBody: true }
+    };
+
+    await sendHttpRequest( args );
+
+    expect( validateRequestPayloadMock ).toHaveBeenCalledWith( {
+      ...args,
+      payload: undefined,
+      headers: undefined
+    } );
+    expect( activityFnMock ).toHaveBeenCalledWith( {
+      ...args,
+      payload: undefined,
+      headers: undefined
+    } );
+  } );
+
   it( 'sendPostRequestAndAwaitWebhook posts wrapped payload and resolves on resume signal', async () => {
     const { sendPostRequestAndAwaitWebhook } = await import( './webhook.js' );
 
@@ -121,6 +156,7 @@ describe( 'interface/webhook', () => {
     expect( callArgs.url ).toBe( url );
     expect( callArgs.payload ).toEqual( { workflowId: 'wf-123', payload: { x: 1 } } );
     expect( callArgs.headers ).toEqual( { a: 'b' } );
+    expect( callArgs.responseOptions ).toEqual( {} );
 
     // Returns a promise (async function) for the eventual webhook result
     expect( typeof promise.then ).toBe( 'function' );