@outputai/core 0.10.1-next.fc0a41f.0 → 0.11.0

package/src/helpers/errors.spec.js

@@ -1,89 +1,189 @@
 import { describe, expect, it } from 'vitest';
-import { ApplicationFailure } from '@temporalio/common';
-import { buildApplicationFailureWithDetails } from './errors.js';
+import { inheritsFromAnyNamedType, rehydrateError } from './errors.js';
 
-class CustomFailure extends Error {}
+describe( 'inheritsFromAnyNamedType', () => {
+  class BaseFailure extends Error {}
+  class DomainFailure extends BaseFailure {}
+  class RequestFailure extends DomainFailure {}
+  class UnrelatedFailure extends Error {}
 
-describe( 'buildApplicationFailureWithDetails', () => {
-  it( 'wraps a regular error in an ApplicationFailure with appended details', () => {
-    const error = new Error( 'step failed' );
-    const info = { aggregations: { cost: { total: 1 } } };
+  it( 'matches exact, parent, and grandparent constructor names', () => {
+    const error = new RequestFailure( 'request failed' );
 
-    const failure = buildApplicationFailureWithDetails( error, info );
+    expect( inheritsFromAnyNamedType( error, [ 'RequestFailure' ] ) ).toBe( true );
+    expect( inheritsFromAnyNamedType( error, [ 'DomainFailure' ] ) ).toBe( true );
+    expect( inheritsFromAnyNamedType( error, [ 'BaseFailure' ] ) ).toBe( true );
+    expect( inheritsFromAnyNamedType( error, [ 'OtherFailure', 'BaseFailure' ] ) ).toBe( true );
+  } );
 
-    expect( failure ).toBeInstanceOf( ApplicationFailure );
-    expect( failure ).toMatchObject( {
-      message: 'step failed',
-      type: 'Error',
-      nonRetryable: false,
-      details: [ info ],
-      cause: error
-    } );
+  it( 'does not match unrelated or descendant constructor names', () => {
+    expect( inheritsFromAnyNamedType( new RequestFailure(), [ 'UnrelatedFailure' ] ) ).toBe( false );
+    expect( inheritsFromAnyNamedType( new BaseFailure(), [ 'RequestFailure' ] ) ).toBe( false );
+    expect( inheritsFromAnyNamedType( new UnrelatedFailure(), [ 'BaseFailure' ] ) ).toBe( false );
   } );
 
-  it( 'uses the original constructor name for custom errors', () => {
-    const error = new CustomFailure( 'custom failed' );
-    const info = { trace: { destinations: { local: '/tmp/trace' } } };
+  it( 'ignores a spoofed own constructor property', () => {
+    const error = new RequestFailure();
+    Object.defineProperty( error, 'constructor', {
+      value: { name: 'SpoofedFailure' }
+    } );
 
-    const failure = buildApplicationFailureWithDetails( error, info );
+    expect( inheritsFromAnyNamedType( error, [ 'SpoofedFailure' ] ) ).toBe( false );
+    expect( inheritsFromAnyNamedType( error, [ 'RequestFailure' ] ) ).toBe( true );
+  } );
 
-    expect( failure ).toMatchObject( {
-      message: 'custom failed',
-      type: 'CustomFailure',
-      details: [ info ],
-      cause: error
-    } );
+  it( 'rejects empty names and invalid values without false positives', () => {
+    const unnamedConstructor = function NamedConstructor() {};
+    Object.defineProperty( unnamedConstructor, 'name', { value: '' } );
+    const value = Object.create( { constructor: unnamedConstructor } );
+
+    expect( inheritsFromAnyNamedType( value, [ '', undefined ] ) ).toBe( false );
+    expect( inheritsFromAnyNamedType( value, [] ) ).toBe( false );
+    expect( inheritsFromAnyNamedType( null, [ 'BaseFailure' ] ) ).toBe( false );
+    expect( inheritsFromAnyNamedType( 'failure', [ 'String' ] ) ).toBe( false );
   } );
+} );
 
-  it( 'preserves existing details and appends new info without mutating the original error', () => {
-    const existingDetails = [ { domain: { reason: 'bad-input' } } ];
-    const error = new Error( 'step failed' );
-    error.details = existingDetails;
-    const info = { aggregations: { httpRequests: { total: 1 } } };
+describe( 'rehydrateError', () => {
+  it( 'returns the same Error instance when given an Error', () => {
+    const original = new Error( 'already an error' );
+    original.name = 'FatalError';
 
-    const failure = buildApplicationFailureWithDetails( error, info );
+    expect( rehydrateError( original ) ).toBe( original );
+  } );
 
-    expect( failure.details ).toEqual( [
-      { domain: { reason: 'bad-input' } },
-      info
-    ] );
-    expect( error.details ).toBe( existingDetails );
-    expect( error.details ).toEqual( [ { domain: { reason: 'bad-input' } } ] );
+  it( 'rebuilds a plain serialized error with name and message', () => {
+    const result = rehydrateError( {
+      name: 'FatalError',
+      message: 'workflow failed'
+    } );
+
+    expect( result ).toBeInstanceOf( Error );
+    expect( result.name ).toBe( 'FatalError' );
+    expect( result.message ).toBe( 'workflow failed' );
+    expect( result.stack ).toBeUndefined();
   } );
 
-  it( 'ignores non-array details on the original error', () => {
-    const error = new Error( 'step failed' );
-    error.details = { domain: { reason: 'bad-input' } };
-    const info = { aggregations: { tokens: { total: 3 } } };
+  it( 'restores stack when present on the serialized object', () => {
+    const result = rehydrateError( {
+      name: 'Error',
+      message: 'boom',
+      stack: 'Error: boom\n    at workflow.js:1:1'
+    } );
+
+    expect( result.stack ).toBe( 'Error: boom\n    at workflow.js:1:1' );
+  } );
 
-    const failure = buildApplicationFailureWithDetails( error, info );
+  it( 'copies additional enumerable properties', () => {
+    const result = rehydrateError( {
+      name: 'HTTPError',
+      message: 'bad request',
+      status: 400,
+      code: 'BAD_REQUEST'
+    } );
 
-    expect( failure.details ).toEqual( [ info ] );
+    expect( result.status ).toBe( 400 );
+    expect( result.code ).toBe( 'BAD_REQUEST' );
   } );
 
-  it( 'preserves ApplicationFailure type, nonRetryable flag, and details while avoiding self-cause', () => {
-    const original = ApplicationFailure.create( {
-      message: 'application failed',
-      type: 'DomainFailure',
-      nonRetryable: true,
-      details: [ { domain: { reason: 'bad-input' } } ]
+  it( 'recursively rehydrates a plain-object cause', () => {
+    const result = rehydrateError( {
+      name: 'ActivityFailure',
+      message: 'Activity task failed',
+      cause: {
+        name: 'ApplicationFailure',
+        message: 'root failure',
+        cause: {
+          name: 'ValidationError',
+          message: 'invalid input'
+        }
+      }
     } );
-    const info = { aggregations: { cost: { total: 2 } } };
-
-    const failure = buildApplicationFailureWithDetails( original, info );
-
-    expect( failure ).toBeInstanceOf( ApplicationFailure );
-    expect( failure ).not.toBe( original );
-    expect( failure.cause ).toBe( original );
-    expect( failure.cause ).not.toBe( failure );
-    expect( failure ).toMatchObject( {
-      message: 'application failed',
-      type: 'DomainFailure',
-      nonRetryable: true,
-      details: [
-        { domain: { reason: 'bad-input' } },
-        info
-      ]
+
+    expect( result.cause ).toBeInstanceOf( Error );
+    expect( result.cause.name ).toBe( 'ApplicationFailure' );
+    expect( result.cause.message ).toBe( 'root failure' );
+    expect( result.cause.cause ).toBeInstanceOf( Error );
+    expect( result.cause.cause.name ).toBe( 'ValidationError' );
+    expect( result.cause.cause.message ).toBe( 'invalid input' );
+  } );
+
+  it( 'leaves a non-object cause unchanged', () => {
+    const result = rehydrateError( {
+      name: 'Error',
+      message: 'outer',
+      cause: 'string cause'
     } );
+
+    expect( result.cause ).toBe( 'string cause' );
+  } );
+
+  it( 'returns an empty Error for null and undefined without throwing', () => {
+    const fromNull = rehydrateError( null );
+    const fromUndefined = rehydrateError( undefined );
+
+    expect( fromNull ).toBeInstanceOf( Error );
+    expect( fromNull.message ).toBe( '' );
+    expect( fromNull.stack ).toBeUndefined();
+
+    expect( fromUndefined ).toBeInstanceOf( Error );
+    expect( fromUndefined.message ).toBe( '' );
+    expect( fromUndefined.stack ).toBeUndefined();
+  } );
+
+  it.each( [
+    [ 'string', 'boom', 'boom' ],
+    [ 'number', 42, '42' ],
+    [ 'boolean', true, 'true' ],
+    [ 'bigint', 1n, '1' ],
+    [ 'symbol', Symbol( 'x' ), 'Symbol(x)' ],
+    [ 'named function', function named() {}, 'function named() {}' ],
+    [ 'arrow function', () => {}, '() => {}' ]
+  ] )( 'stringifies a %s into Error.message', ( _label, input, message ) => {
+    const result = rehydrateError( input );
+
+    expect( result ).toBeInstanceOf( Error );
+    expect( result.message ).toBe( message );
+    expect( result.stack ).toBeUndefined();
+  } );
+
+  it( 'copies enumerable array indexes onto an empty Error', () => {
+    const result = rehydrateError( [ 'a', 'b' ] );
+
+    expect( result ).toBeInstanceOf( Error );
+    expect( result.message ).toBe( '' );
+    expect( result.stack ).toBeUndefined();
+    expect( result[0] ).toBe( 'a' );
+    expect( result[1] ).toBe( 'b' );
+  } );
+
+  it( 'returns an empty Error for RegExp and Date (no enumerable own props)', () => {
+    const fromRegexp = rehydrateError( /foo/gi );
+    const fromDate = rehydrateError( new Date( '2020-01-01T00:00:00.000Z' ) );
+
+    expect( fromRegexp ).toBeInstanceOf( Error );
+    expect( fromRegexp.message ).toBe( '' );
+    expect( fromRegexp.stack ).toBeUndefined();
+
+    expect( fromDate ).toBeInstanceOf( Error );
+    expect( fromDate.message ).toBe( '' );
+    expect( fromDate.stack ).toBeUndefined();
+  } );
+
+  it( 'copies enumerable own props from a custom class instance', () => {
+    class Widget {
+      constructor() {
+        this.x = 1;
+        this.name = 'WidgetError';
+      }
+    }
+
+    const result = rehydrateError( new Widget() );
+
+    expect( result ).toBeInstanceOf( Error );
+    expect( result.message ).toBe( '' );
+    expect( result.stack ).toBeUndefined();
+    expect( result.x ).toBe( 1 );
+    expect( result.name ).toBe( 'WidgetError' );
   } );
 } );

package/src/helpers/fetch.js

@@ -1,42 +1,5 @@
 import { FatalError } from '#errors';
-
-/** Matches red in "hot-red-pie", but not in "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 } );
-  }, {} );
-};
+import { redactHeaders } from './redact.js';
 
 /**
  * Consume the body of a Response according it its content-type and returns it

package/src/helpers/fetch.spec.js

@@ -1,44 +1,6 @@
 import { afterEach, describe, it, expect } from 'vitest';
 import { Readable } from 'node:stream';
-import { hydrateHeaders, redactHeaders, serializeBodyAndInferContentType, serializeResponse } from './fetch.js';
-
-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( {} );
-  } );
-} );
+import { hydrateHeaders, serializeBodyAndInferContentType, serializeResponse } from './fetch.js';
 
 describe( 'hydrateHeaders', () => {
   afterEach( () => {

package/src/helpers/function.js

@@ -13,3 +13,16 @@ export const runOnce = fn => {
     return state.result;
   };
 };
+
+/**
+ * Calls a given function and in case it throws errors, returns `undefined`
+ * @param {Function} fn
+ * @returns {unknown|undefined}
+ */
+export const tryOrUndefined = fn => {
+  try {
+    return fn();
+  } catch {
+    return undefined; // eslint-disable-line consistent-return
+  }
+};

package/src/helpers/function.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { runOnce } from './function.js';
+import { runOnce, tryOrUndefined } from './function.js';
 
 describe( 'runOnce', () => {
   it( 'calls the wrapped function only once', () => {
@@ -46,3 +46,25 @@ describe( 'runOnce', () => {
     expect( fn ).toHaveBeenCalledOnce();
   } );
 } );
+
+describe( 'tryOrUndefined', () => {
+  it( 'returns the invoked function result', () => {
+    const fn = vi.fn( () => 'result' );
+
+    expect( tryOrUndefined( fn ) ).toBe( 'result' );
+    expect( fn ).toHaveBeenCalledOnce();
+  } );
+
+  it( 'returns undefined when the invoked function throws', () => {
+    const fn = vi.fn( () => {
+      throw new Error( 'unavailable' );
+    } );
+
+    expect( tryOrUndefined( fn ) ).toBeUndefined();
+    expect( fn ).toHaveBeenCalledOnce();
+  } );
+
+  it( 'preserves an explicit undefined result', () => {
+    expect( tryOrUndefined( () => undefined ) ).toBeUndefined();
+  } );
+} );

package/src/helpers/redact.js

@@ -0,0 +1,51 @@
+/**
+ * Redacts a given URL object by setting each search param, hash, username and password to '***'
+ * @param {URL|string} target
+ * @returns {string} Redacted URL as a string
+ */
+export const redactUrl = target => {
+  const url = new URL( target );
+  url.search = new URLSearchParams( url.searchParams.entries().map( ( [ p ] ) => [ p, '***' ] ) ).toString();
+  url.username = url.username.length > 0 ? '***' : '';
+  url.password = url.password.length > 0 ? '***' : '';
+  url.hash = url.hash ? '#***' : '';
+  return url.toString();
+};
+
+/** Matches red in "hot-red-pie", but not in "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 } );
+  }, {} );
+};

package/src/helpers/redact.spec.js

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { redactHeaders, redactUrl } from './redact.js';
+
+describe( 'redactUrl', () => {
+  it( 'redacts credentials, query values, and the fragment while preserving URL structure', () => {
+    const result = redactUrl( 'https://user:password@example.com/models?model=gpt-5&token=secret#debug' );
+
+    expect( result ).toBe( 'https://***:***@example.com/models?model=***&token=***#***' );
+  } );
+
+  it( 'preserves duplicate query parameters and their order', () => {
+    const result = redactUrl( 'https://example.com/search?tag=first&tag=second&empty=#results' );
+
+    expect( result ).toBe( 'https://example.com/search?tag=***&tag=***&empty=***#***' );
+  } );
+
+  it( 'returns URLs without redacted components unchanged', () => {
+    expect( redactUrl( 'https://example.com/path' ) ).toBe( 'https://example.com/path' );
+  } );
+
+  it( 'does not mutate URL instances', () => {
+    const originalValue = 'ftp://user:password@example.com/file.txt?download=true#details';
+    const url = new URL( originalValue );
+
+    expect( redactUrl( url ) ).toBe( 'ftp://***:***@example.com/file.txt?download=***#***' );
+    expect( url.toString() ).toBe( originalValue );
+  } );
+} );
+
+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( {} );
+  } );
+} );

package/src/helpers/string.js

@@ -28,3 +28,13 @@ export const toUrlSafeBase64 = uuid => {
  * @returns
  */
 export const rxEscape = v => v.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' );
+
+const URL_SCHEME_RX = /^[a-z][a-z\d+.-]*:\/\//i;
+
+/**
+ * Detects if string is an URL starting with `<protocol>://`
+ *
+ * @param {string} s
+ * @returns {boolean}
+ */
+export const isUrl = s => typeof s === 'string' && URL_SCHEME_RX.test( s.trim() ) && URL.canParse( s );

package/src/helpers/string.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { toUrlSafeBase64, rxEscape } from './string.js';
+import { isUrl, toUrlSafeBase64, rxEscape } from './string.js';
 
 describe( 'toUrlSafeBase64', () => {
   const urlSafeAlphabet = /^[A-Za-z0-9_-]+$/;
@@ -62,3 +62,38 @@ describe( 'rxEscape', () => {
     expect( rx.test( String.raw`C:\foo\bar\baz` ) ).toBe( false );
   } );
 } );
+
+describe( 'isUrl', () => {
+  it.each( [
+    'https://example.com/path?token=secret#section',
+    'ftp://user:password@example.com/file.txt',
+    'ftps://example.com/file.txt',
+    'git+ssh://example.com/repository',
+    'custom.protocol-v2://example.com/resource'
+  ] )( 'accepts a valid URL starting with a protocol: %s', value => {
+    expect( isUrl( value ) ).toBe( true );
+  } );
+
+  it.each( [
+    'Error: fetch failed',
+    'TypeError: invalid input',
+    'mailto:user@example.com',
+    'urn:isbn:978014',
+    'data:text/plain,hello'
+  ] )( 'rejects non-authority URI-like strings: %s', value => {
+    expect( isUrl( value ) ).toBe( false );
+  } );
+
+  it.each( [
+    '//example.com/path',
+    '/relative/path',
+    'https://',
+    'not a URL'
+  ] )( 'rejects malformed or relative values: %s', value => {
+    expect( isUrl( value ) ).toBe( false );
+  } );
+
+  it.each( [ undefined, null, 42, new URL( 'https://example.com' ) ] )( 'rejects non-string values', value => {
+    expect( isUrl( value ) ).toBe( false );
+  } );
+} );