@output.ai/core 0.1.18 → 0.2.1

package/src/interface/webhook.spec.js

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mocks for module aliases used by webhook.js
+vi.mock( '#consts', () => ( {
+  ACTIVITY_SEND_HTTP_REQUEST: '__internal#sendHttpRequest'
+} ) );
+
+const validateRequestPayloadMock = vi.fn();
+vi.mock( './validations/static.js', () => ( {
+  validateRequestPayload: validateRequestPayloadMock
+} ) );
+
+// Minimal, legible mock of @temporalio/workflow APIs used by webhook.js
+const activityFnMock = vi.fn();
+const proxyActivitiesMock = vi.fn( () => ( { ['__internal#sendHttpRequest']: activityFnMock } ) );
+
+const storedHandlers = new Map();
+const defineSignalMock = name => name;
+const setHandlerMock = ( signal, fn ) => {
+  storedHandlers.set( signal, fn );
+};
+
+const workflowInfoMock = vi.fn( () => ( { workflowId: 'wf-123' } ) );
+const sinks = { trace: { addEventStart: vi.fn(), addEventEnd: vi.fn() } };
+const proxySinksMock = vi.fn( async () => sinks );
+
+class TestTrigger {
+  constructor() {
+    this.resolved = false;
+    this._resolve = () => {};
+    this.promise = new Promise( res => {
+      this._resolve = res;
+    } );
+  }
+  resolve( value ) {
+    if ( !this.resolved ) {
+      this.resolved = true;
+      this._resolve( value );
+    }
+  }
+  then( onFulfilled, onRejected ) {
+    return this.promise.then( onFulfilled, onRejected );
+  }
+}
+
+vi.mock( '@temporalio/workflow', () => ( {
+  defineSignal: defineSignalMock,
+  setHandler: setHandlerMock,
+  proxyActivities: proxyActivitiesMock,
+  workflowInfo: workflowInfoMock,
+  proxySinks: proxySinksMock,
+  uuid4: () => 'uuid-mock',
+  Trigger: TestTrigger
+} ) );
+
+describe( 'interface/webhook', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    storedHandlers.clear();
+  } );
+
+  it( 'sendHttpRequest validates input and calls activity with correct options and args', async () => {
+    const { sendHttpRequest } = await import( './webhook.js' );
+
+    const fakeSerializedResponse = {
+      url: 'https://example.com',
+      status: 200,
+      statusText: 'OK',
+      ok: true,
+      headers: { 'content-type': 'application/json' },
+      body: { ok: true }
+    };
+    activityFnMock.mockResolvedValueOnce( fakeSerializedResponse );
+
+    const args = { url: 'https://example.com/api', method: 'GET' };
+    const res = await sendHttpRequest( args );
+
+    // validated
+    expect( validateRequestPayloadMock ).toHaveBeenCalledWith( { ...args, payload: undefined, headers: undefined } );
+
+    // activity proxied with specified options
+    expect( proxyActivitiesMock ).toHaveBeenCalledTimes( 1 );
+    const optionsArg = proxyActivitiesMock.mock.calls[0][0];
+    expect( optionsArg.startToCloseTimeout ).toBe( '3m' );
+    expect( optionsArg.retry ).toEqual( expect.objectContaining( {
+      initialInterval: '15s',
+      maximumAttempts: 3,
+      nonRetryableErrorTypes: expect.arrayContaining( [ 'FatalError' ] )
+    } ) );
+
+    // activity invoked with the same args
+    expect( activityFnMock ).toHaveBeenCalledWith( { ...args, payload: undefined, headers: undefined } );
+    expect( res ).toEqual( fakeSerializedResponse );
+  } );
+
+  it( 'sendPostRequestAndAwaitWebhook posts wrapped payload and resolves on resume signal', async () => {
+    const { sendPostRequestAndAwaitWebhook } = await import( './webhook.js' );
+
+    // Make the inner activity resolve (through sendHttpRequest)
+    activityFnMock.mockResolvedValueOnce( {
+      url: 'https://webhook.site',
+      status: 200,
+      statusText: 'OK',
+      ok: true,
+      headers: {},
+      body: null
+    } );
+
+    const url = 'https://webhook.site/ingest';
+    const promise = sendPostRequestAndAwaitWebhook( { url, payload: { x: 1 }, headers: { a: 'b' } } );
+
+    // The activity was called via sendHttpRequest with POST and wrapped payload
+    const callArgs = activityFnMock.mock.calls[0][0];
+    expect( callArgs.method ).toBe( 'POST' );
+    expect( callArgs.url ).toBe( url );
+    expect( callArgs.payload ).toEqual( { workflowId: 'wf-123', payload: { x: 1 } } );
+    expect( callArgs.headers ).toEqual( { a: 'b' } );
+
+    // Returns a promise (async function) for the eventual webhook result
+    expect( typeof promise.then ).toBe( 'function' );
+  } );
+} );

package/src/internal_activities/index.js

@@ -1,45 +1,67 @@
 import { FatalError } from '#errors';
-import { setMetadata, isStringboolTrue } from '#utils';
+import { fetch } from 'undici';
+import { setMetadata, isStringboolTrue, serializeFetchResponse, serializeBodyAndInferContentType } from '#utils';
 import { ComponentType } from '#consts';
 import * as localProcessor from '../tracing/processors/local/index.js';
 import * as s3Processor from '../tracing/processors/s3/index.js';
 
 /**
- * Send a post to a given URL
+ * Send a HTTP request.
  *
  * @param {object} options
  * @param {string} options.url - The target url
- * @param {string} options.workflowId - The current workflow id
- * @param {any} options.payload - The payload to send url
+ * @param {string} options.method - The HTTP method
+ * @param {unknown} [options.payload] - The payload to send url
+ * @param {object} [options.headers] - The headers for the request
+ * @param {number} [options.timeout] - The timeout for the request (default 30s)
+ * @returns {object} The serialized HTTP response
  * @throws {FatalError}
  */
-export const sendWebhook = async ( { url, workflowId, payload } ) => {
-  const request = fetch( url, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify( { workflowId, payload } ),
-    signal: AbortSignal.timeout( 5000 )
-  } );
-
-  const res = await ( async () => {
+export const sendHttpRequest = async ( { url, method, payload = undefined, headers = undefined, timeout = 30_000 } ) => {
+  const args = {
+    method,
+    headers: new Headers( headers ?? {} ),
+    signal: AbortSignal.timeout( timeout )
+  };
+
+  const methodsWithBody = [ 'DELETE', 'PATCH', 'POST', 'PUT', 'OPTIONS' ];
+  const hasBodyPayload = ![ undefined, null ].includes( payload );
+  if ( methodsWithBody.includes( method ) && hasBodyPayload ) {
+    const { body, contentType } = serializeBodyAndInferContentType( payload );
+    if ( contentType && !args.headers.has( 'content-type' ) ) {
+      args.headers.set( 'Content-Type', contentType );
+    }
+    Object.assign( args, { body } );
+  };
+
+  const response = await ( async () => {
     try {
-      return await request;
-    } catch {
-      throw new FatalError( 'Webhook fail: timeout' );
+      return await fetch( url, args );
+    } catch ( e ) {
+      throw new FatalError( `${method} ${url} ${e.cause ?? e.message}` );
     }
   } )();
 
-  console.log( '[Core.SendWebhook]', res.status, res.statusText );
+  console.log( '[Core.sendHttpRequest]', response.status, response.statusText );
 
-  if ( !res.ok ) {
-    throw new FatalError( `Webhook fail: ${res.status}` );
+  if ( !response.ok ) {
+    throw new FatalError( `${method} ${url} ${response.status}` );
   }
+
+  return serializeFetchResponse( response );
 };
 
-setMetadata( sendWebhook, { type: ComponentType.INTERNAL_STEP } );
+setMetadata( sendHttpRequest, { type: ComponentType.INTERNAL_STEP } );
 
+/**
+ * Resolve and return all possible trace destinations based on env var flags
+ *
+ * @param {Object} options
+ * @param {Date} startTime - Workflow startTime
+ * @param {string} workflowId
+ * @param {string} workflowName
+ * @returns {object} Information about enabled workflows
+ */
 export const getTraceDestinations = ( { startTime, workflowId, workflowName } ) => ( {
   local: isStringboolTrue( process.env.TRACE_LOCAL_ON ) ? localProcessor.getDestination( { startTime, workflowId, workflowName } ) : null,
   remote: isStringboolTrue( process.env.TRACE_REMOTE_ON ) ? s3Processor.getDestination( { startTime, workflowId, workflowName } ) : null

package/src/internal_activities/index.spec.js

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { MockAgent, setGlobalDispatcher } from 'undici';
+import { FatalError } from '#errors';
+import { serializeBodyAndInferContentType, serializeFetchResponse } from '#utils';
+import { sendHttpRequest } from './index.js';
+
+vi.mock( '#utils', () => {
+  return {
+    setMetadata: vi.fn(),
+    isStringboolTrue: vi.fn( () => false ),
+    serializeBodyAndInferContentType: vi.fn(),
+    serializeFetchResponse: vi.fn()
+  };
+} );
+
+const mockAgent = new MockAgent();
+mockAgent.disableNetConnect();
+
+setGlobalDispatcher( mockAgent );
+
+const url = 'https://growthx.ai';
+const method = 'GET';
+
+describe( 'internal_activities/sendHttpRequest', () => {
+  beforeEach( async () => {
+    vi.restoreAllMocks();
+    vi.clearAllMocks();
+  } );
+
+  it( 'succeeds and returns serialized JSON response', async () => {
+    const payload = { a: 1 };
+    const method = 'POST';
+
+    mockAgent.get( url ).intercept( { path: '/', method } )
+      .reply( 200, JSON.stringify( { ok: true, value: 42 } ), {
+        headers: { 'content-type': 'application/json' }
+      } );
+
+    // mock utils
+    serializeBodyAndInferContentType.mockReturnValueOnce( {
+      body: JSON.stringify( payload ),
+      contentType: 'application/json; charset=UTF-8'
+    } );
+    const fakeSerialized = { sentinel: true };
+    serializeFetchResponse.mockResolvedValueOnce( fakeSerialized );
+
+    const result = await sendHttpRequest( { url, method, payload } );
+
+    // utils mocked: verify calls and returned value
+    expect( serializeBodyAndInferContentType ).toHaveBeenCalledTimes( 1 );
+    expect( serializeBodyAndInferContentType ).toHaveBeenCalledWith( payload );
+    expect( serializeFetchResponse ).toHaveBeenCalledTimes( 1 );
+    const respArg = serializeFetchResponse.mock.calls[0][0];
+    expect( respArg && typeof respArg.text ).toBe( 'function' );
+    expect( respArg.status ).toBe( 200 );
+    expect( respArg.headers.get( 'content-type' ) ).toContain( 'application/json' );
+    expect( result ).toBe( fakeSerialized );
+  } );
+
+  it( 'throws FatalError when response.ok is false', async () => {
+    mockAgent.get( url ).intercept( { path: '/', method } ).reply( 500, 'Internal error' );
+
+    await expect( sendHttpRequest( { url, method } ) ).rejects
+      .toThrow( new FatalError( 'GET https://growthx.ai 500' ) );
+    expect( serializeFetchResponse ).not.toHaveBeenCalled();
+    expect( serializeBodyAndInferContentType ).not.toHaveBeenCalled();
+  } );
+
+  it( 'throws FatalError on timeout failure', async () => {
+    mockAgent.get( url ).intercept( { path: '/', method } )
+      .reply( 200, 'ok', { headers: { 'content-type': 'text/plain' } } )
+      .delay( 10_000 );
+
+    await expect( sendHttpRequest( { url, method, timeout: 250 } ) ).rejects
+      .toThrow( new FatalError( 'GET https://growthx.ai The operation was aborted due to timeout' ) );
+    expect( serializeFetchResponse ).not.toHaveBeenCalled();
+    expect( serializeBodyAndInferContentType ).not.toHaveBeenCalled();
+  } );
+
+  it( 'wraps DNS resolution errors (ENOTFOUND) preserving cause message', async () => {
+    mockAgent.get( url ).intercept( { path: '/', method } )
+      .replyWithError( new Error( 'getaddrinfo ENOTFOUND nonexistent.example.test' ) );
+
+    await expect( sendHttpRequest( { url, method } ) ).rejects
+      .toThrow( new FatalError( 'GET https://growthx.ai Error: getaddrinfo ENOTFOUND nonexistent.example.test' ) );
+    expect( serializeFetchResponse ).not.toHaveBeenCalled();
+    expect( serializeBodyAndInferContentType ).not.toHaveBeenCalled();
+  } );
+
+  it( 'wraps TCP connection errors (ECONNREFUSED) preserving cause message', async () => {
+    mockAgent.get( url ).intercept( { path: '/', method } )
+      .replyWithError( new Error( 'connect ECONNREFUSED 127.0.0.1:65500' ) );
+
+    await expect( sendHttpRequest( { url, method } ) ).rejects
+      .toThrow( new FatalError( 'GET https://growthx.ai Error: connect ECONNREFUSED 127.0.0.1:65500' ) );
+    expect( serializeFetchResponse ).not.toHaveBeenCalled();
+    expect( serializeBodyAndInferContentType ).not.toHaveBeenCalled();
+  } );
+} );

package/src/tracing/index.d.ts

@@ -6,42 +6,42 @@
 */
 
 /**
- * The public namespace for tracing
+ * Public tracing API for recording event phases on the default trace of the current workflow.
  *
  * @namespace
  */
 export declare const Tracing: {
 
   /**
-   * Adds the start phase of a new event at the default trace for the current workflow.
+   * Record the start of an event on the default trace for the current workflow.
    *
-   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
-   * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
-   * @param {string} name - The human friendly name of the Event: query, request, create.
-   * @param {any} details - All details attached to this Event Phase. DB queried records, HTTP response body.
-   * @returns {void}
+   * @param args - Event information
+   * @param args.id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param args.kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+   * @param args.name - The human friendly name of the Event: query, request, create.
+   * @param args.details - Arbitrary metadata associated with this phase (e.g., payloads, summaries).
    */
-  addEventStart( args: { id: string; kind: string; name: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+  addEventStart( args: { id: string; kind: string; name: string; details: unknown } ): void;
 
   /**
-   * Adds the end phase at an event at the default trace for the current workflow.
+   * Record the end of an event on the default trace for the current workflow.
    *
-   * It needs to use the same id of the start phase.
+   * Use the same id as the start phase to correlate phases.
    *
-   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
-   * @param {any} details - All details attached to this Event Phase. DB queried records, HTTP response body.
-   * @returns {void}
+   * @param args - Event information
+   * @param args.id - Identifier matching the event's start phase.
+   * @param args.details - Arbitrary metadata associated with this phase (e.g., results, response body).
    */
-  addEventEnd( args: { id: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+  addEventEnd( args: { id: string; details: unknown } ): void;
 
   /**
-   * Adds the error phase at an event as error at the default trace for the current workflow.
+   * Record an error for an event on the default trace for the current workflow.
    *
-   * It needs to use the same id of the start phase.
+   * Use the same id as the start phase to correlate phases.
    *
-   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
-   * @param {any} details - All details attached to this Event Phase. DB queried records, HTTP response body.
-   * @returns {void}
+   * @param args - Event metadata for the error phase.
+   * @param args.id - Identifier matching the event's start phase.
+   * @param args.details - Arbitrary metadata associated with this phase, possible error info.
    */
-  addEventError( args: { id: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+  addEventError( args: { id: string; details: unknown } ): void;
 };

package/src/utils/index.d.ts

@@ -1,30 +1,37 @@
 /**
- * Return the directory of the file invoking the code that called this function
- * Excludes `@output.ai/core`, node, and other internal paths
+ * Return the first immediate directory of the file invoking the code that called this function.
+ *
+ * Excludes `@output.ai/core`, node, and other internal paths.
  */
 export function resolveInvocationDir(): string;
 
 /**
- * Node safe clone implementation that doesn't use global structuredClone()
- * @param {object} v
- * @returns {object}
+ * Node safe clone implementation that doesn't use global structuredClone().
+ *
+ * Returns a cloned version of the object.
+ *
+ * Only clones static properties. Getters become static properties.
+ *
+ * @param object
  */
-export function clone( v: object ): object;
+export function clone( object: object ): object;
 
 /**
- * Throw given error
- * @param {Error} e
- * @throws {e}
+ * Receives an error as argument and throws it.
+ *
+ * @param error
+ * @throws {Error}
  */
-export function throws( e: Error ): void;
+export function throws( error: Error ): void;
 
 /**
- * Add metadata "values" property to a given object
- * @param {object} target
- * @param {object} values
+ * Attach given value to an object with the METADATA_ACCESS_SYMBOL symbol as key.
+ *
+ * @param target
+ * @param value
  * @returns
  */
-export function setMetadata( target: object, values: object ): void;
+export function setMetadata( target: object, value: object ): void;
 
 /**
  * Merge two temporal activity options
@@ -33,3 +40,41 @@ export function mergeActivityOptions(
   base?: import( '@temporalio/workflow' ).ActivityOptions,
   ext?: import( '@temporalio/workflow' ).ActivityOptions
 ): import( '@temporalio/workflow' ).ActivityOptions;
+
+/** Represents a {Response} serialized to plain object  */
+export type SerializedFetchResponse = {
+  /** The response url */
+  url: string,
+
+  /** The response status code */
+  status: number,
+
+  /** The response status text */
+  statusText: string,
+
+  /** Flag indicating if the request succeeded */
+  ok: boolean,
+
+  /** Object with response headers */
+  headers: Record<string, string>,
+
+  /** Response body, either JSON, text or arrayBuffer converter to base64 */
+  body: object | string
+};
+
+/**
+ * Consumes and HTTP Response and serialize it to a plain object
+ */
+export function serializeFetchResponse( response: Response ): SerializedFetchResponse;
+
+export type SerializedBodyAndContentType = {
+  /** The body parsed to string if possible or kept as the types allowed in fetch's POST body */
+  body: string | unknown,
+  /** The inferred content-type */
+  contentType: string | undefined
+};
+
+/**
+ * Based on the type of a payload, serialized it to be send as the body of a fetch POST request and also infer its Content Type.
+ */
+export function serializeBodyAndInferContentType( body: unknown ): SerializedBodyAndContentType;

package/src/utils/utils.js

@@ -42,3 +42,110 @@ export const mergeActivityOptions = ( base = {}, ext = {} ) =>
  * @returns
  */
 export const isStringboolTrue = v => [ '1', 'true', 'on' ].includes( v );
+
+/**
+ * Consume Fetch's HTTP Response and return a serialized version of it;
+ *
+ * @param {Response} response
+ * @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
+  };
+};
+
+/**
+ * Duck-typing to detect a Node Readable (Stream) without importing anything
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+const isReadable = v =>
+  typeof v === 'object' &&
+  typeof v?.read === 'function' &&
+  typeof v?.on === 'function' &&
+  typeof v?.pipe === 'function' &&
+  v?.readable !== false;
+
+/**
+ * Based on the type of a payload, serialized it to be send as the body of a fetch POST request and also infer its Content Type.
+ *
+ * Non serializable types versus Content-Type reference (for Node)
+ *
+ * |Type|Is self-describing)|Inferred type by fetch|Defined mime type|
+ * |-|-|-|-}
+ * |Blob|yes|`blob.type`||
+ * |File|yes|`file.type`||
+ * |FormData|yes|"multipart/form-data; boundary=..."||
+ * |URLSearchParams|yes|"application/x-www-form-urlencoded;charset=UTF-8"||
+ * |ArrayBuffer|no||"application/octet-stream"|
+ * |TypedArray (Uint8Array,Uint16Array)||"application/octet-stream"||
+ * |DataView|no||"application/octet-stream"|
+ * |ReadableStream, Readable, AsyncIterator|no||Can't, because stream must be read|
+ *
+ * If payload is none of the above types, test it:
+ * If the it is an object, serialize using JSON.stringify and set content-type to `application/json`;
+ * Else, it is a JS primitive, serialize using JSON.stringify and set content-type to `text/plain`;
+ *
+ * This implementation is overkill for temporal workflows since the only types available there will be:
+ * - URLSearchParams
+ * - ArrayBuffer
+ * - TypedArrays
+ * - DataView
+ * - asyncGenerator
+ * The others are non deterministic and are not available at runtime, but this function was build to be flexible
+ *
+ * @see {@link https://fetch.spec.whatwg.org/#bodyinit}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch}
+ *
+ * @param {unknown} payload
+ * @returns {object} An object with the serialized body and inferred content-type
+ */
+export const serializeBodyAndInferContentType = payload => {
+  const dataTypes = [ Blob, File, URLSearchParams, FormData ];
+
+  // empty body
+  if ( [ null, undefined ].includes( payload ) ) {
+    return { body: undefined, contentType: undefined };
+  }
+
+  // Buffer types, covers ArrayBuffer, TypedArrays and DataView
+  if ( payload instanceof ArrayBuffer || ArrayBuffer.isView( payload ) ) {
+    return { body: payload, contentType: 'application/octet-stream' };
+  }
+
+  // These data types auto assigned mime types
+  if ( dataTypes.some( t => payload instanceof t ) ) {
+    return { body: payload, contentType: undefined };
+  }
+
+  // ReadableStream, Readable and Async Iterator mimes cant be determined without reading it
+  if ( payload instanceof ReadableStream || typeof payload[Symbol.asyncIterator] === 'function' || isReadable( payload ) ) {
+    return { body: payload, contentType: undefined };
+  }
+
+  if ( typeof payload === 'object' ) {
+    return { body: JSON.stringify( payload ), contentType: 'application/json; charset=UTF-8' };
+  }
+
+  return { body: String( payload ), contentType: 'text/plain; charset=UTF-8' };
+};