@output.ai/core 0.5.0 → 0.5.2

package/src/interface/step.d.ts

@@ -0,0 +1,138 @@
+import type { z } from 'zod';
+import type { AnyZodSchema, TemporalActivityOptions } from './types.d.ts';
+
+/**
+ * Options for a step.
+ */
+export type StepOptions = {
+
+  /**
+   * Temporal activity options for this step.
+   */
+  activityOptions?: TemporalActivityOptions
+};
+
+/**
+ * The handler function of a step.
+ *
+ * @param input - The step input; it matches the schema defined by `inputSchema`.
+ *
+ * @returns A value matching the schema defined by `outputSchema`.
+ */
+export type StepFunction<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.infer<InputSchema> ) => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void> :
+  () => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void>;
+
+/**
+ * A wrapper around the user defined `fn` handler function.
+ *
+ * It accepts the same input and returns the same value, calling the user function inside.
+ *
+ * It adds input and output validation based on the `inputSchema`, `outputSchema`.
+ *
+ * @param input - The Step input; it matches the schema defined by `inputSchema`.
+ * @returns A value matching the schema defined by `outputSchema`.
+ */
+export type StepFunctionWrapper<StepFunction> =
+  Parameters<StepFunction> extends [infer Input] ?
+    ( input: Input ) => ReturnType<StepFunction> :
+    () => ReturnType<StepFunction>;
+
+/**
+ * Creates a step.
+ *
+ * A step is a logical unit of work that can perform I/O. It is translated to a Temporal Activity.
+ *
+ * The step logic is defined in the `fn` handler function.
+ *
+ * The schema of the input that the function receives as the first argument is defined by the `inputSchema` option.
+ *
+ * The output of the `fn` handler must match the schema defined by `outputSchema`; otherwise, a validation error is raised.
+ *
+ * @example
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async input => {
+ *     const result = await ai.call( input.value );
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without outputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   fn: async input => {
+ *     await ai.call( input.value );
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without inputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   outputSchema: z.string(),
+ *   fn: async () => {
+ *     const result = await ai.call();
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without inputSchema and outputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   fn: async () => {
+ *     await ai.call();
+ *   }
+ * } )
+ * ```
+ *
+ * @remarks
+ * - Never call another step from within a step.
+ * - Never call a workflow from within a step.
+ *
+ * @typeParam InputSchema - Zod schema of the fn's input.
+ * @typeParam OutputSchema - Zod schema of the fn's return.
+ *
+ * @throws {@link ValidationError}
+ * @throws {@link FatalError}
+ *
+ * @param params - Step parameters
+ * @param params.name - Human-readable step name (must start with a letter or underscore, followed by letters, numbers, or underscores)
+ * @param params.description - Description of the step
+ * @param params.inputSchema - Zod schema for the `fn` input
+ * @param params.outputSchema - Zod schema for the `fn` output
+ * @param params.fn - A handler function containing the step code
+ * @param params.options - Optional step options.
+ * @returns The same handler function set at `fn`
+ */
+export declare function step<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+>( params: {
+  name: string;
+  description?: string;
+  inputSchema?: InputSchema;
+  outputSchema?: OutputSchema;
+  fn: StepFunction<InputSchema, OutputSchema>;
+  options?: StepOptions;
+} ): StepFunctionWrapper<StepFunction<InputSchema, OutputSchema>>;

package/src/interface/step.js

@@ -1,3 +1,4 @@
+// THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
 import { setMetadata } from '#utils';
 import { validateStep } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';

package/src/interface/types.d.ts

@@ -0,0 +1,27 @@
+import type { z } from 'zod';
+import type { ActivityOptions } from '@temporalio/workflow';
+/**
+ * Similar to `Partial<T>` but applies to nested properties recursively, creating a deep optional variant of `T`:
+ * - Objects: All properties become optional, recursively.
+ * - Functions: Preserved as‑is (only the property itself becomes optional).
+ * - Primitives: Returned unchanged.
+ * Useful for config overrides with strong IntelliSense on nested fields and methods.
+ */
+export type DeepPartial<T> =
+  T extends ( ...args: any[] ) => unknown ? T : // eslint-disable-line @typescript-eslint/no-explicit-any
+    T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } :
+      T;
+
+/**
+ * Type alias for any Zod schema type.
+ */
+export type AnyZodSchema = z.ZodType<any, any, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+/**
+ * Native Temporal configurations for activities.
+ *
+ * All native options are accepted except 'versioningIntent', 'taskQueue', 'allowEagerDispatch'.
+ *
+ * @see {@link https://typescript.temporal.io/api/interfaces/common.ActivityOptions}
+ */
+export type TemporalActivityOptions = Omit<ActivityOptions, 'versioningIntent' | 'taskQueue' | 'allowEagerDispatch'>;

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/workflow.d.ts

@@ -0,0 +1,273 @@
+import type { z } from 'zod';
+import type { DeepPartial, AnyZodSchema, TemporalActivityOptions } from './types.d.ts';
+
+/**
+ * The second argument passed to the workflow's `fn` function.
+ */
+export type WorkflowContext<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = {
+
+  /**
+   * Functions that allow fine control over the underlying Temporal workflows
+   */
+  control: {
+    /**
+     * Closes the current workflow execution successfully and creates a new workflow execution.
+     *
+     * The new workflow execution is in the same chain as the previous workflow, but it generates another trace file.
+     *
+     * It acts as a checkpoint when the workflow gets too long or approaches certain scaling limits.
+     *
+     * It accepts input with the same schema as the parent workflow function (`inputSchema`).
+     *
+     * Calling this function must be the last statement in the workflow, accompanied by a `return`:
+     *
+     * @example
+     * ```js
+     *   return control.continueAsNew();
+     * ```
+     * Upon returning, the parent workflow execution closes without any output, and the new execution takes its place.
+     *
+     * The function's return type matches `outputSchema`; although no value is returned, the execution is replaced.
+     *
+     * @see {@link https://docs.temporal.io/develop/typescript/continue-as-new}
+     *
+     * @param input - The input for the new run. Omit when the workflow has no input schema.
+     * @returns The workflow output type for type-checking; never returns at runtime.
+     */
+    continueAsNew: InputSchema extends AnyZodSchema ?
+      ( input: z.infer<InputSchema> ) => ( OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void ) :
+      () => ( OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void ),
+
+    /**
+     * Indicates whether the Temporal runtime suggests continuing this workflow as new.
+     *
+     * Use this to decide whether to `continueAsNew` before long waits or at loop boundaries.
+     * Prefer returning the `continueAsNew(...)` call immediately when this becomes `true`.
+     *
+     * @see {@link https://docs.temporal.io/develop/typescript/continue-as-new#how-to-test}
+     *
+     * @returns True if a continue-as-new is suggested for the current run; otherwise false.
+     */
+    isContinueAsNewSuggested: () => boolean
+  },
+
+  /**
+   * Information about the workflow execution
+   */
+  info: {
+    /**
+     * Internal Temporal workflow id.
+     *
+     * @see {@link https://docs.temporal.io/workflow-execution/workflowid-runid#workflow-id}
+     */
+    workflowId: string
+  }
+};
+
+/**
+ * Configuration for workflow invocations.
+ *
+ * Allows overriding Temporal Activity options for this workflow.
+ */
+export type WorkflowInvocationConfiguration<Context extends WorkflowContext = WorkflowContext> = {
+
+  /**
+   * Temporal activity options for this invocation (overrides the workflow's default activity options).
+   */
+  options?: TemporalActivityOptions,
+
+  /**
+   * Configures whether this workflow runs detached.
+   * Detached workflows called without explicitly awaiting the result are "fire-and-forget" and may outlive the parent.
+   */
+  detached?: boolean,
+
+  /**
+   * Allow to overwrite properties of the "context" of workflows when called in tests environments.
+   */
+  context?: DeepPartial<Context>
+};
+
+/**
+ * Options for a workflow.
+ */
+export type WorkflowOptions = {
+
+  /**
+   * Temporal activity options for activities invoked by this workflow.
+   */
+  activityOptions?: TemporalActivityOptions,
+
+  /**
+   * When `true`, disables trace file generation for this workflow. Only has effect when tracing is enabled.
+   */
+  disableTrace?: boolean
+};
+
+/**
+ * The handler function of a workflow.
+ *
+ * @param input - The workflow input; it matches the schema defined by `inputSchema`.
+ * @param context - A context object with tools and information.
+ *
+ * @returns A value matching the schema defined by `outputSchema`.
+ */
+export type WorkflowFunction<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.infer<InputSchema>, context: WorkflowContext<InputSchema, OutputSchema> ) =>
+  Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void> :
+  ( input?: undefined | null, context: WorkflowContext<InputSchema, OutputSchema> ) =>
+  Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void>;
+
+/**
+ * A wrapper around the user defined `fn` handler function.
+ *
+ * It accepts the same input and returns the same value, calling the user function inside.
+ *
+ * The second argument is a WorkflowInvocationConfiguration object, allowing workflows configuration overwrite.
+ *
+ * It adds input and output validation based on the `inputSchema`, `outputSchema`.
+ *
+ * @param input - The workflow input; it matches the schema defined by `inputSchema`.
+ * @param config - Additional configuration for the invocation.
+ * @returns A value matching the schema defined by `outputSchema`.
+ */
+export type WorkflowFunctionWrapper<WorkflowFunction> =
+  [Parameters<WorkflowFunction>[0]] extends [undefined | null] ?
+    ( input?: undefined | null, config?: WorkflowInvocationConfiguration<Parameters<WorkflowFunction>[1]> ) =>
+    ReturnType<WorkflowFunction> :
+    ( input: Parameters<WorkflowFunction>[0], config?: WorkflowInvocationConfiguration<Parameters<WorkflowFunction>[1]> ) =>
+    ReturnType<WorkflowFunction>;
+
+/**
+ * Creates a workflow.
+ *
+ * A workflow is an orchestration of one or more steps. It is translated to a Temporal Workflow.
+ *
+ * The workflow logic is defined in the `fn` handler function.
+ *
+ * The schema of the input that the function receives as the first argument is defined by `inputSchema`.
+ *
+ * The output of the `fn` handler must match `outputSchema`; otherwise, a validation error is raised.
+ *
+ * @remarks
+ * - Workflows should respect the same limitations as Temporal workflows.
+ * - Workflows can invoke steps or evaluators and cannot perform I/O directly.
+ * - The workflow `name` needs to be unique across all workflows in the project.
+ *
+ * @example
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async input => {
+ *     const result = await step( input.value );
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without outputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   fn: async input => {
+ *     await step( input.value );
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without inputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   outputSchema: z.string(),
+ *   fn: async () => {
+ *     const result = await step();
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without inputSchema and outputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   fn: async () => {
+ *     await step();
+ *   }
+ * } )
+ * ```
+ *
+ * @example Using continueAsNew
+ * The function `continueAsNew` (same as Temporal) can be used to create a new workflow with the same ID and pass different input.
+ *
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async ( input, context ) => {
+ *     const result = await step( input.value );
+ *     if ( context.control.isContinueAsNewSuggested() ) {
+ *       return context.control.continueAsNew( input );
+ *     }
+ *
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ * @typeParam InputSchema - Zod schema of the fn's input.
+ * @typeParam OutputSchema - Zod schema of the fn's return.
+ *
+ * @throws {@link ValidationError}
+ * @throws {@link FatalError}
+ *
+ * @param params - Workflow parameters
+ * @param params.name - Human-readable workflow name (must start with a letter or underscore, followed by letters, numbers, or underscores).
+ * @param params.description - Description of the workflow
+ * @param params.inputSchema - Zod schema for workflow input
+ * @param params.outputSchema - Zod schema for workflow output
+ * @param params.fn - A function containing the workflow code
+ * @param params.options - Optional workflow options.
+ * @returns The same handler function set at `fn` with a different signature
+ */
+export declare function workflow<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+>( params: {
+  name: string;
+  description?: string;
+  inputSchema?: InputSchema;
+  outputSchema?: OutputSchema;
+  fn: WorkflowFunction<InputSchema, OutputSchema>;
+  options?: WorkflowOptions;
+} ): WorkflowFunctionWrapper<WorkflowFunction<InputSchema, OutputSchema>>;

package/src/interface/workflow.js

@@ -3,40 +3,9 @@ import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4,
 import { validateWorkflow } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
 import { SHARED_STEP_PREFIX, ACTIVITY_GET_TRACE_DESTINATIONS, METADATA_ACCESS_SYMBOL } from '#consts';
-import { deepMerge, mergeActivityOptions, setMetadata, toUrlSafeBase64 } from '#utils';
+import { deepMerge, setMetadata, toUrlSafeBase64 } from '#utils';
 import { FatalError, ValidationError } from '#errors';
-
-/**
- * Context instance builder
- */
-class Context {
-
-  /**
-   * Builds a new context instance
-   * @param {object} options - Arguments to build a new context instance
-   * @param {string} workflowId
-   * @param {function} continueAsNew
-   * @param {function} isContinueAsNewSuggested
-   * @returns {object} context
-   */
-  static build( { workflowId, continueAsNew, isContinueAsNewSuggested } ) {
-    return {
-      /**
-       * Control namespace: This object adds functions to interact with Temporal flow mechanisms
-       */
-      control: {
-        continueAsNew,
-        isContinueAsNewSuggested
-      },
-      /**
-       * Info namespace: abstracts workflowInfo()
-       */
-      info: {
-        workflowId
-      }
-    };
-  }
-};
+import { Context } from './workflow_context.js';
 
 const defaultOptions = {
   activityOptions: {
@@ -53,10 +22,10 @@ const defaultOptions = {
   disableTrace: false
 };
 
-export function workflow( { name, description, inputSchema, outputSchema, fn, options } ) {
+export function workflow( { name, description, inputSchema, outputSchema, fn, options = {} } ) {
   validateWorkflow( { name, description, inputSchema, outputSchema, fn, options } );
 
-  const activityOptions = mergeActivityOptions( defaultOptions.activityOptions, options?.activityOptions );
+  const { disableTrace, activityOptions } = deepMerge( defaultOptions, options );
   const steps = proxyActivities( activityOptions );
 
   /**
@@ -71,7 +40,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
     if ( !inWorkflowContext() ) {
       validateWithSchema( inputSchema, input, `Workflow ${name} input` );
       const context = Context.build( { workflowId: 'test-workflow', continueAsNew: async () => {}, isContinueAsNewSuggested: () => false } );
-      const output = await fn( input, deepMerge( context, extra.context ?? {} ) );
+      const output = await fn( input, deepMerge( context, extra.context ) );
       validateWithSchema( outputSchema, output, `Workflow ${name} output` );
       return output;
     }
@@ -89,7 +58,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
     const executionContext = memo.executionContext ?? {
       workflowId,
       workflowName: name,
-      disableTrace: options.disableTrace,
+      disableTrace,
       startTime: startTime.getTime()
     };
 
@@ -131,7 +100,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
               executionContext,
               parentId: workflowId,
               // new configuration for activities of the child workflow, this will be omitted so it will use what that workflow have defined
-              ...( extra?.options?.activityOptions && { activityOptions: mergeActivityOptions( activityOptions, extra.options.activityOptions ) } )
+              ...( extra?.options?.activityOptions && { activityOptions: deepMerge( activityOptions, extra.options.activityOptions ) } )
             }
           } )
       }, input, context );