@outputai/core 0.1.0

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

@@ -0,0 +1,366 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import {
+  validateStep,
+  validateWorkflow,
+  validateRequestPayload,
+  validateEvaluator,
+  validateExecuteInParallel,
+  StaticValidationError
+} from './static.js';
+
+const validArgs = Object.freeze( {
+  name: 'valid_name',
+  description: 'desc',
+  inputSchema: z.object( {} ),
+  outputSchema: z.object( {} ),
+  fn: () => {}
+} );
+
+describe( 'interface/validator', () => {
+  describe( 'validateStep', () => {
+    it( 'passes for valid args', () => {
+      expect( () => validateStep( { ...validArgs } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing name', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received undefined\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: undefined } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-string name', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received number\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: 123 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid name pattern', () => {
+      const error = new StaticValidationError( '✖ Invalid string: must match pattern /^[a-z_][a-z0-9_]*$/i\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: '-bad' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-string description', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received number\n  → at description' );
+      expect( () => validateStep( { ...validArgs, description: 10 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-Zod inputSchema', () => {
+      const error = new StaticValidationError( '✖ Schema must be a Zod schema\n  → at inputSchema' );
+      expect( () => validateStep( { ...validArgs, inputSchema: 'not-a-zod-schema' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects JSON Schema inputSchema', () => {
+      const error = new StaticValidationError( '✖ Schema must be a Zod schema\n  → at inputSchema' );
+      expect( () => validateStep( { ...validArgs, inputSchema: { type: 'object' } } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-Zod outputSchema', () => {
+      const error = new StaticValidationError( '✖ Schema must be a Zod schema\n  → at outputSchema' );
+      expect( () => validateStep( { ...validArgs, outputSchema: 10 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects JSON Schema outputSchema', () => {
+      const error = new StaticValidationError( '✖ Schema must be a Zod schema\n  → at outputSchema' );
+      expect( () => validateStep( { ...validArgs, outputSchema: { type: 'string' } } ) ).toThrow( error );
+    } );
+
+    it( 'rejects missing fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received undefined\n  → at fn' );
+      expect( () => validateStep( { ...validArgs, fn: undefined } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-function fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at fn' );
+      expect( () => validateStep( { ...validArgs, fn: 'not-fn' } ) ).toThrow( error );
+    } );
+
+    it( 'passes with options.activityOptions.retry (second-level options)', () => {
+      const args = {
+        ...validArgs,
+        options: {
+          activityOptions: {
+            retry: {
+              initialInterval: '1s',
+              backoffCoefficient: 2,
+              maximumInterval: '10s',
+              maximumAttempts: 3,
+              nonRetryableErrorTypes: [ 'SomeError' ]
+            }
+          }
+        }
+      };
+      expect( () => validateStep( args ) ).not.toThrow();
+    } );
+
+    it( 'passes with options.activityOptions.activityId as string', () => {
+      expect( () => validateStep( { ...validArgs, options: { activityOptions: { activityId: 'act-123' } } } ) ).not.toThrow();
+    } );
+
+    it( 'rejects non-string options.activityOptions.activityId', () => {
+      expect( () => validateStep( { ...validArgs, options: { activityOptions: { activityId: 123 } } } ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'passes with valid options.activityOptions.cancellationType values', () => {
+      for ( const v of [ 'TRY_CANCEL', 'WAIT_CANCELLATION_COMPLETED', 'ABANDON' ] ) {
+        expect( () => validateStep( { ...validArgs, options: { activityOptions: { cancellationType: v } } } ) ).not.toThrow();
+      }
+    } );
+
+    it( 'rejects invalid options.activityOptions.cancellationType', () => {
+      const args = { ...validArgs, options: { activityOptions: { cancellationType: 'INVALID' } } };
+      expect( () => validateStep( args ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'accepts duration fields in options.activityOptions', () => {
+      const options = {
+        activityOptions: {
+          heartbeatTimeout: '1s',
+          scheduleToCloseTimeout: '2m',
+          scheduleToStartTimeout: '3m',
+          startToCloseTimeout: '4m'
+        }
+      };
+      expect( () => validateStep( { ...validArgs, options } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid duration string in options.activityOptions.heartbeatTimeout', () => {
+      expect( () => validateStep( { ...validArgs, options: { activityOptions: { heartbeatTimeout: '5x' } } } ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'passes with options.activityOptions.summary string', () => {
+      expect( () => validateStep( { ...validArgs, options: { activityOptions: { summary: 'brief' } } } ) ).not.toThrow();
+    } );
+
+    it( 'rejects non-string options.activityOptions.summary', () => {
+      expect( () => validateStep( { ...validArgs, options: { activityOptions: { summary: 42 } } } ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'passes with options.activityOptions.priority valid payload', () => {
+      const options = {
+        activityOptions: {
+          priority: {
+            fairnessKey: 'user-1',
+            fairnessWeight: 1.5,
+            priorityKey: 10
+          }
+        }
+      };
+      expect( () => validateStep( { ...validArgs, options } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid options.activityOptions.priority values', () => {
+      const options = { activityOptions: { priority: { fairnessWeight: 0, priorityKey: 0 } } };
+      expect( () => validateStep( { ...validArgs, options } ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'rejects invalid options.activityOptions.retry values', () => {
+      const options = { activityOptions: { retry: { backoffCoefficient: 0.5, maximumAttempts: 0, nonRetryableErrorTypes: [ 1 ] } } };
+      expect( () => validateStep( { ...validArgs, options } ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'rejects unknown keys inside options.activityOptions due to strictObject', () => {
+      expect( () => validateStep( { ...validArgs, options: { activityOptions: { unknownKey: true } } } ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'rejects unknown top-level keys due to strictObject', () => {
+      expect( () => validateStep( { ...validArgs, extra: 123 } ) ).toThrow( StaticValidationError );
+    } );
+  } );
+
+  describe( 'validateWorkflow', () => {
+    it( 'passes for valid args', () => {
+      expect( () => validateWorkflow( { ...validArgs } ) ).not.toThrow();
+    } );
+
+    it( 'passes with options.disableTrace true', () => {
+      expect( () => validateWorkflow( { ...validArgs, options: { disableTrace: true } } ) ).not.toThrow();
+    } );
+
+    it( 'passes with options.disableTrace false', () => {
+      expect( () => validateWorkflow( { ...validArgs, options: { disableTrace: false } } ) ).not.toThrow();
+    } );
+
+    it( 'passes with options.activityOptions and options.disableTrace', () => {
+      expect( () => validateWorkflow( {
+        ...validArgs,
+        options: { activityOptions: { activityId: 'wf-1' }, disableTrace: true }
+      } ) ).not.toThrow();
+    } );
+
+    it( 'rejects non-boolean options.disableTrace', () => {
+      expect( () => validateWorkflow( { ...validArgs, options: { disableTrace: 'yes' } } ) ).toThrow( StaticValidationError );
+    } );
+  } );
+
+  describe( 'validateEvaluator', () => {
+    const base = Object.freeze( {
+      name: 'valid_name',
+      description: 'desc',
+      inputSchema: z.object( {} ),
+      fn: () => {}
+    } );
+
+    it( 'passes for valid args (no outputSchema)', () => {
+      expect( () => validateEvaluator( { ...base } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid name pattern', () => {
+      const error = new StaticValidationError( '✖ Invalid string: must match pattern /^[a-z_][a-z0-9_]*$/i\n  → at name' );
+      expect( () => validateEvaluator( { ...base, name: '-bad' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-Zod inputSchema', () => {
+      const error = new StaticValidationError( '✖ Schema must be a Zod schema\n  → at inputSchema' );
+      expect( () => validateEvaluator( { ...base, inputSchema: 'not-a-zod-schema' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects missing fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received undefined\n  → at fn' );
+      expect( () => validateEvaluator( { ...base, fn: undefined } ) ).toThrow( error );
+    } );
+  } );
+
+  describe( 'validate request', () => {
+    it( 'passes with valid http url', () => {
+      expect( () => validateRequestPayload( { url: 'http://example.com', method: 'GET' } ) ).not.toThrow();
+    } );
+
+    it( 'passes with valid https url', () => {
+      expect( () => validateRequestPayload( { url: 'https://example.com/path?q=1', method: 'GET' } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing url', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received undefined\n  → at url' );
+      expect( () => validateRequestPayload( { method: 'GET' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid scheme', () => {
+      const error = new StaticValidationError( '✖ Invalid URL\n  → at url' );
+      expect( () => validateRequestPayload( { url: 'ftp://example.com', method: 'GET' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects malformed url', () => {
+      const error = new StaticValidationError( '✖ Invalid URL\n  → at url' );
+      expect( () => validateRequestPayload( { url: 'http:////', method: 'GET' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects missing method', () => {
+      expect( () => validateRequestPayload( { url: 'https://example.com' } ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'passes with headers as string map', () => {
+      const request = {
+        url: 'https://example.com',
+        method: 'GET',
+        headers: { 'x-api-key': 'abc', accept: 'application/json' }
+      };
+      expect( () => validateRequestPayload( request ) ).not.toThrow();
+    } );
+
+    it( 'rejects non-object headers', () => {
+      const request = {
+        url: 'https://example.com',
+        method: 'GET',
+        headers: 5
+      };
+      expect( () => validateRequestPayload( request ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'rejects headers with non-string values', () => {
+      const request = {
+        url: 'https://example.com',
+        method: 'GET',
+        headers: { 'x-num': 123 }
+      };
+      expect( () => validateRequestPayload( request ) ).toThrow( StaticValidationError );
+    } );
+
+    it( 'passes with payload object', () => {
+      const request = {
+        url: 'https://example.com/api',
+        method: 'POST',
+        payload: { a: 1, b: 'two' }
+      };
+      expect( () => validateRequestPayload( request ) ).not.toThrow();
+    } );
+
+    it( 'passes with payload string', () => {
+      const request = {
+        url: 'https://example.com/upload',
+        method: 'POST',
+        payload: 'raw-body'
+      };
+      expect( () => validateRequestPayload( request ) ).not.toThrow();
+    } );
+  } );
+
+  describe( 'validateExecuteInParallel', () => {
+    const validArgs = Object.freeze( {
+      jobs: [ () => {}, () => {} ],
+      concurrency: 5
+    } );
+
+    it( 'passes for valid args', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing concurrency', () => {
+      const error = new StaticValidationError( '✖ Invalid input\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs } ) ).toThrow( error );
+    } );
+
+    it( 'passes with onJobCompleted callback', () => {
+      const args = {
+        ...validArgs,
+        onJobCompleted: () => {}
+      };
+      expect( () => validateExecuteInParallel( args ) ).not.toThrow();
+    } );
+
+    it( 'passes with concurrency 1', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: 1 } ) ).not.toThrow();
+    } );
+
+    it( 'passes with concurrency Infinity', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: Infinity } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing jobs', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected array, received undefined\n  → at jobs' );
+      expect( () => validateExecuteInParallel( { concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-array jobs', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected array, received string\n  → at jobs' );
+      expect( () => validateExecuteInParallel( { jobs: 'not-array', concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'passes with empty jobs array', () => {
+      expect( () => validateExecuteInParallel( { jobs: [], concurrency: 5 } ) ).not.toThrow();
+    } );
+
+    it( 'rejects jobs array with non-function', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at jobs[1]' );
+      expect( () => validateExecuteInParallel( { jobs: [ () => {}, 'not-function' ], concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-number concurrency', () => {
+      const error = new StaticValidationError( '✖ Invalid input\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs, concurrency: '5' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects zero concurrency', () => {
+      const error = new StaticValidationError( '✖ Too small: expected number to be >=1\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs, concurrency: 0 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects negative concurrency', () => {
+      const error = new StaticValidationError( '✖ Too small: expected number to be >=1\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: -1 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-function onJobCompleted', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at onJobCompleted' );
+      expect( () => validateExecuteInParallel( { ...validArgs, onJobCompleted: 'not-function' } ) ).toThrow( error );
+    } );
+  } );
+} );

package/src/interface/webhook.d.ts

@@ -0,0 +1,84 @@
+import type { SerializedFetchResponse } from '../utils/index.d.ts';
+
+/**
+ * Allowed HTTP methods for request helpers.
+ */
+export type HttpMethod = 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+/**
+ * Send an POST HTTP request to a URL, optionally with a payload, then wait for a webhook response.
+ *
+ * The "Content-Type" is inferred from the payload type and can be overridden via the `headers` argument.
+ *
+ * If the body is not a type natively accepted by the Fetch API, it is serialized to a string: `JSON.stringify()` for objects, or `String()` for primitives.
+ *
+ * When a body is sent, the payload is wrapped together with the `workflowId` and sent as:
+ * @example
+ * ```js
+ * const finalPayload = {
+ *   workflowId,
+ *   payload
+ * }
+ * ```
+ *
+ * After dispatching the request, the workflow pauses and waits for a POST to `/workflow/:id/feedback` (where `:id` is the `workflowId`). When the API receives that request, its body is delivered back to the workflow and execution resumes.
+ *
+ * @example
+ * ```js
+ * const response = await sendPostRequestAndAwaitWebhook( {
+ *   url: 'https://example.com/integration',
+ *   payload: {
+ *   }
+ * } );
+ *
+ * assert( response, 'the value sent back via the api' );
+ * ```
+ *
+ * @remarks
+ * - Only callable from within a workflow function; do not use in steps or evaluators.
+ * - Steps and evaluators are activity-based and are not designed to be paused.
+ * - If used within steps or evaluators, a compilation error will be raised.
+ * - Uses a Temporal Activity to dispatch the HTTP request, working around the runtime limitation for workflows.
+ * - Uses a Temporal Trigger to pause the workflow.
+ * - Uses a Temporal Signal to resume the workflow when the API responds.
+ *
+ * @param params - Parameters object
+ * @param params.url - Request URL
+ * @param params.payload - Request payload
+ * @param params.headers - Headers for the request
+ * @returns Resolves with the payload received by the webhook
+ */
+export declare function sendPostRequestAndAwaitWebhook( params: {
+  url: string;
+  payload?: object;
+  headers?: Record<string, string>;
+} ): Promise<unknown>;
+
+/**
+ * Send an HTTP request to a URL.
+ *
+ * For POST or PUT requests, an optional payload can be sent as the body.
+ *
+ * The "Content-Type" is inferred from the payload type and can be overridden via the `headers` argument.
+ *
+ * If the body is not a type natively accepted by the Fetch API, it is serialized to a string: `JSON.stringify()` for objects, or `String()` for primitives.
+ *
+ * @remarks
+ * - Intended for use within workflow functions; do not use in steps or evaluators.
+ * - Steps and evaluators are activity-based and can perform HTTP requests directly.
+ * - If used within steps or evaluators, a compilation error will be raised.
+ * - Uses a Temporal Activity to dispatch the HTTP request, working around the runtime limitation for workflows.
+ *
+ * @param params - Parameters object
+ * @param params.url - Request URL
+ * @param params.method - The HTTP method (default: 'GET')
+ * @param params.payload - Request payload (only for POST/PUT)
+ * @param params.headers - Headers for the request
+ * @returns Resolves with an HTTP response serialized to a plain object
+ */
+export declare function sendHttpRequest( params: {
+  url: string;
+  method?: HttpMethod;
+  payload?: object;
+  headers?: Record<string, string>;
+} ): Promise<SerializedFetchResponse>;

package/src/interface/webhook.js

@@ -0,0 +1,64 @@
+// THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
+import { defineSignal, setHandler, proxyActivities, workflowInfo, proxySinks, uuid4, Trigger } from '@temporalio/workflow';
+import { ACTIVITY_SEND_HTTP_REQUEST } from '#consts';
+import { FatalError } from '#errors';
+import { validateRequestPayload } from './validations/static.js';
+
+/**
+ * Call the internal activity to make a HTTP request and returns its response.
+ *
+ * @param {Object} parameters
+ * @param {string} url
+ * @param {string} method
+ * @param {unknown} [payload]
+ * @param {object} [headers]
+ * @returns {Promise<object>} The serialized HTTP response
+ */
+export async function sendHttpRequest( { url, method = 'GET', payload = undefined, headers = undefined } ) {
+  validateRequestPayload( { method, url, payload, headers } );
+  const res = await proxyActivities( {
+    startToCloseTimeout: '3m',
+    retry: {
+      initialInterval: '15s',
+      maximumAttempts: 3,
+      nonRetryableErrorTypes: [ FatalError.name ]
+    }
+  } )[ACTIVITY_SEND_HTTP_REQUEST]( { method, url, payload, headers } );
+  return res;
+};
+
+/**
+ * Call the internal activity to make a POST request sending a payload to a given url.
+ *
+ * After the request succeeds, pause the code using Trigger and wait for a Signal to un-pause it.
+ *
+ * The signal will be sent by the API when a response is sent to its webhook url.
+ *
+ * @param {Object} parameters
+ * @param {string} url
+ * @param {unknown} [payload]
+ * @param {object} [headers]
+ * @returns {Promise<unknown>} The response received by the webhook
+ */
+export async function sendPostRequestAndAwaitWebhook( { url, payload = undefined, headers = undefined } ) {
+  const { workflowId } = workflowInfo();
+  const wrappedPayload = { workflowId, payload };
+
+  await sendHttpRequest( { method: 'POST', url, payload: wrappedPayload, headers } );
+
+  const sinks = await proxySinks();
+  const resumeTrigger = new Trigger();
+  const resumeSignal = defineSignal( 'resume' );
+
+  const traceId = `${workflowId}-${url}-${uuid4()}`;
+  sinks.trace.start( { id: traceId, name: 'resume', kind: 'webhook' } );
+
+  setHandler( resumeSignal, webhookPayload => {
+    if ( !resumeTrigger.resolved ) {
+      sinks.trace.end( { id: traceId, details: webhookPayload } );
+      resumeTrigger.resolve( webhookPayload );
+    }
+  } );
+
+  return resumeTrigger;
+};

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: { start: vi.fn(), end: 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' );
+  } );
+} );