@output.ai/core 0.0.7 → 0.0.9

package/README.md

@@ -1,64 +1,100 @@
 # Core
 
-Provides tools to run a workflow, which is a well defined logical unit of work.
+Provides tools to develop and run a workflow, which is a well defined logical unit of work.
 
-## step()
+## Structure
 
-Defines a step, which is a enclosed unit of work which can import external dependencies.
+Workflows are defined using core functions "workflow" and "step", separate files:
 
-```ts
-import { step } from 'flow-core';
+```
+└ workflows
+  └ example
+    ├ workflow.ts|js <- workflow entry point
+    ├ steps.ts|js <- file with each step of this workflow
+    └ prompt.prompt <- a prompt file
+  └ other-example
 
-export const aSingleStep = step( {
-  name: 'aSingleStep',
-  fn: async (): Promise<string> => {
-    // do stuff
-  }
-} );
 ```
 
-All step needs a name, and the name will be used in the context of the workflow (see below).
+Think that workflows is the orchestrator and steps are executors. So the workflow only call the steps and the steps call the IO operations, like APIs, DBs, LLMs, etc.
 
-## workflow()
+## Workflow code
 
-Defines a logical structure of step invocations. No external dependencies can be imported in the file containing the workflow.
+### workflow.js
 
-```ts
-import { workflow } from 'flow-core';
-import type { WorkflowContext } from 'flow-core';
-import type { PromptWorkflowInput, PromptWorkflowOutput } from './types';
+```js
+import { workflow } from '@output.ai/workflow';
+import { guessByName } from './steps.js';
 
 export default workflow( {
-  name: 'prompt',
-  description: 'A workflow to demonstrate the prompt feature',
-  fn: async ( input: PromptWorkflowInput, context: WorkflowContext ): Promise<PromptWorkflowOutput> => {
-    const result = await context.steps.aSingleStep();
-
-    return { result };
+  name: 'guessMyProfession',
+  description: 'Guess a person profession by its name',
+  inputSchema: {
+    type: 'object',
+    required: [ 'name' ],
+    properties: {
+      name: { type: 'string'}
+    }
+  },
+  outputSchema: {
+    type: 'object',
+    required: [ 'profession' ],
+    properties: {
+      profession: { type: 'string'}
+    }
+  },
+  fn: async input => {
+    const profession = await guessByName( input.name );
+    return { profession };
   }
-} );
+})
 ```
 
-The workflow Context has the following properties:
+### steps.js
 
-### .steps.*()
+```js
+import { api } from './api.js'
 
-Each step defined in the step file is available here as js function with the "name" it was defined there. The input arguments are the input arguments of its `fn` function.
+export const guessByName = step( {
+  name: 'guessByName',
+  inputSchema: {
+    type: 'string'
+  },
+  outputSchema: {
+    type: 'string'
+  },
+  fn: async name => {
+    const res = await api.consumer( name );
+    return res.body;
+  }
+} )
+```
 
-### .tools.webhook()
+## webhooks
 
-Provides a webhook feature where a POST is made to a given url and the workflow is stopped until another POST is made back to the workflows API:
+workflows can call webhooks that will stop their execution until an answer is given back.
 
 ```js
-const result = await context.tools.webhook( {
-  name: 'needFeedback',
-  description: 'Get a feedback',
-  url: 'http://xxx.xxx/feedback',
-  payload: { /* a given payload */ }
-} );
+import { workflow, createWebhook } from '@output.ai/workflow';
+import { guessByName } from './steps.js';
+
+export default workflow( {
+  ...
+  fn: async input => {
+    ...
+
+    const result = await createWebhook( {
+      url: 'http://xxx.xxx/feedback',
+      payload: {
+        progressSoFar: 'plenty'
+      }
+    } );
+
+  }
+})
 ```
 
-the url will receive the following payload:
+The url of the example will receive the payload, plus the workflowId:
 
 ```js
 {
@@ -67,38 +103,28 @@ the url will receive the following payload:
 }
 ```
 
-To resume the workflow, a POST has to be made to a given url, with a response payload and the workflowId.
+To resume the workflow, a POST has to be made with a response payload and the workflowId.
 
-The host is localhost:3001 if running locally, there is not remote host yet.
+- Production: `https://output-api-production.onrender.com/workflow/feedback`
+- Staging: `https://output-api-staging.onrender.com/workflow/feedback`
+- Local: `http://localhost:3001/workflow/feedback`
 
-The format is:
-```
-POST https://locahost:3001/workflow/feedback
+Example:
+
+```bash
+POST http://locahost:3001/workflow/feedback
   {
     workflowId,
     payload: {}
   }
 ```
 
-## Folder structure:
-
-```
-└ workflows
-  └ my workflow
-    ├ index.ts // contains the workflow()
-    ├ types.ts // contains input, output types, and other misc types
-    └ steps.ts // contains all steps
-```
+## Developing
 
-## Booting
+To develop workflows you need the code, which will be called the worker, the API and the engine (Temporal).
 
-The project with workflows will be a "worker", meaning its workflows can be invoked individually by their names. To do so it has to be started using a npx command.
+After having the API and the engine running, to start the worker just run:
 
-_package.json_
 ```js
-...
-  "scripts": {
-    "start": "npx flow-worker"
-  },
-...
+`outputai`
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "The core module of the output framework",
   "type": "module",
   "main": "src/index.js",
@@ -13,20 +13,27 @@
     "worker": "node ./src/worker/index.js"
   },
   "bin": {
-    "flow-worker": "./bin/worker.sh"
+    "flow-worker": "./bin/worker.sh",
+    "outputai": "./bin/worker.sh"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/growthxai/flow-sdk"
   },
   "dependencies": {
+    "@babel/generator": "7.26.5",
+    "@babel/parser": "7.26.7",
+    "@babel/traverse": "7.25.9",
+    "@babel/types": "7.26.7",
     "@temporalio/worker": "1.13.0",
     "@temporalio/workflow": "1.13.0",
-    "undici": "7.15.0"
+    "ajv": "8.17.1",
+    "zod": "4.1.9"
   },
   "imports": {
     "#consts": "./src/consts.js",
     "#configs": "./src/configs.js",
+    "#errors": "./src/errors.js",
     "#internal_activities": "./src/internal_activities/index.js"
   }
 }

package/src/configs.js

@@ -5,7 +5,7 @@ export const worker = {
   maxActivities: 100,
   maxWorkflows: 100,
   namespace: process.env.TEMPORAL_NAMESPACE ?? 'default',
-  taskQueue: process.env.TEMPORAL_TASK_QUEUE ?? 'main'
+  taskQueue: process.env.TEMPORAL_TASK_QUEUE
 };
 
 export const api = {

package/src/consts.js

@@ -1,3 +1,4 @@
-export const nameSymbol = Symbol( '__name' );
-export const sendWebhookPostName = '__internal#sendWebhookPost';
-export const workflowsIndexFileName = '__workflows_entrypoint.js';
+export const SEND_WEBHOOK_ACTIVITY_NAME = '__internal#sendWebhookPost';
+export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
+export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
+export const THIS_LIB_NAME = 'core';

package/src/errors.js

@@ -1,3 +1,14 @@
+/**
+ * These are errors exposed as tools for the user to break their flow
+ * They work in both steps and workflows
+ */
+
+/**
+ * Any generic fatal errors
+ */
 export class FatalError extends Error { }
 
+/**
+ * Any validation error
+ */
 export class ValidationError extends Error { }

package/src/index.d.ts

@@ -1,38 +1,310 @@
-export interface StepDefinition<TInput = unknown, TOutput = unknown> {
+// JSON Schema → TypeScript type mapping (subset sufficient for IntelliSense)
+type Simplify<T> = { [K in keyof T]: T[K] };
+type EnumValues = readonly ( string | number | boolean | null )[];
+
+type JSONSchema = {
+  type?: 'string' | 'number' | 'integer' | 'boolean' | 'null' | 'object' | 'array';
+  enum?: EnumValues;
+  const?: string | number | boolean | null;
+  anyOf?: readonly JSONSchema[];
+  oneOf?: readonly JSONSchema[];
+  allOf?: readonly JSONSchema[];
+  // object
+  properties?: { [key: string]: JSONSchema };
+  required?: readonly string[];
+  additionalProperties?: boolean | JSONSchema;
+  // array
+  items?: JSONSchema | readonly JSONSchema[];
+  // ignore $ref & others for typing purposes
+  $ref?: string;
+} & Record<string, unknown>;
+
+type UnionToIntersection<U> = ( U extends unknown ? ( k: U ) => void : never ) extends ( k: infer I ) => void ? I : never;
+
+type FromEnum<S> = S extends { enum: infer E extends EnumValues } ? E[number] : never;
+type FromConst<S> = S extends { const: infer C } ? C : never;
+
+type FromPrimitive<S> =
+  S extends { type: 'string' } ? string :
+  S extends { type: 'number' | 'integer' } ? number :
+  S extends { type: 'boolean' } ? boolean :
+  S extends { type: 'null' } ? null :
+  never;
+
+type ObjectProps<S extends JSONSchema> = S extends { properties: infer P extends Record<string, JSONSchema> }
+  ? { [K in keyof P]: FromSchema<P[K]> }
+  : Record<never, never>;
+
+type ObjectRequiredKeys<S extends JSONSchema> = S extends { required: readonly ( infer R )[] }
+  ? Extract<R & string, keyof ObjectProps<S>>
+  : never;
+
+type ObjectFrom<S extends JSONSchema> = Simplify<
+  Pick<ObjectProps<S>, ObjectRequiredKeys<S>> &
+  Partial<Omit<ObjectProps<S>, ObjectRequiredKeys<S>>>
+>;
+
+type ArrayFrom<S extends JSONSchema> = S extends { items: infer I }
+  ? I extends readonly unknown[]
+    ? FromSchema<I[number]>[]
+    : FromSchema<I>[]
+  : unknown[];
+
+export type FromSchema<S extends JSONSchema> =
+  // combinators first
+  S extends { anyOf: infer A extends readonly JSONSchema[] } ? FromSchema<A[number]> :
+  S extends { oneOf: infer A extends readonly JSONSchema[] } ? FromSchema<A[number]> :
+  S extends { allOf: infer A extends readonly JSONSchema[] } ? UnionToIntersection<FromSchema<A[number]>> :
+  // enum/const
+  FromEnum<S> extends never ? ( FromConst<S> extends never ? (
+    // object (explicit or by presence of properties)
+    S extends { type: 'object' } | { properties: Record<string, JSONSchema> } ? ObjectFrom<S> :
+    // array
+    S extends { type: 'array' } ? ArrayFrom<S> :
+    // primitives
+    FromPrimitive<S> extends never ? unknown : FromPrimitive<S>
+  ) : FromConst<S> ) : FromEnum<S>;
+
+export type OutputFrom<O extends JSONSchema> = FromSchema<O>;
+
+// Utility to strip readonly from inferred types
+/** Recursively removes readonly modifiers from object and array types. */
+type DeepMutable<T> =
+  T extends readonly ( infer U )[] ? DeepMutable<U>[] :
+  T extends object ? { -readonly [K in keyof T]: DeepMutable<T[K]> } :
+  T;
+
+/*
+ * There is 4 overrides of the "step" function"
+ * - with fn receiving input and returning output;
+ * - with fn receiving input and returning void;
+ * - with fn receiving void and returning outout;
+ * - with fn receiving void and returning void;
+ */
+
+/**
+ * @callback StepFn
+ * @param {any} input - The input, defined by the inputSchema
+ * @returns {any} The output defined by the outputSchema
+ */
+
+/**
+ * Creates logical unit of work, called "step", which will be invoked from workflows.
+ *
+ * @param {object} options - Step options
+ * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
+ * @param {string} [options.description] - Description of the step
+ * @param {JSONSchema} options.inputSchema - JSON Schema for the fn input, will infer a TS type
+ * @param {JSONSchema} options.outputSchema - JSON Schema for the fn output, will infer a TS type
+ * @param {StepFn} options.fn - The function logic
+ * @returns {StepFn} The options.fn function
+ */
+export async function step<
+  const InputSchema extends JSONSchema,
+  const OutputSchema extends JSONSchema
+>( options: {
+  name: string;
+  description?: string;
+  inputSchema: InputSchema;
+  outputSchema: OutputSchema;
+  fn: ( input: DeepMutable<FromSchema<InputSchema>> ) => Promise<DeepMutable<FromSchema<OutputSchema>>>;
+} ): ( input: DeepMutable<FromSchema<InputSchema>> ) => Promise<DeepMutable<FromSchema<OutputSchema>>>;
+
+/**
+ * @callback InputOnlyStepFn
+ * @param {any} input - The input, defined by the inputSchema
+ */
+
+/**
+ * Creates logical unit of work, called "step", which will be invoked from workflows.
+ *
+ * @param {object} options - Step options
+ * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
+ * @param {string} [options.description] - Description of the step
+ * @param {JSONSchema} options.inputSchema - JSON Schema for the fn input, will infer a TS type
+ * @param {InputOnlyStepFn} options.fn - The function logic
+ * @returns {InputOnlyStepFn} The options.fn function
+ */
+export async function step<
+  const InputSchema extends JSONSchema
+>( options: {
+  name: string;
+  description?: string;
+  inputSchema: InputSchema;
+  fn: ( input: DeepMutable<FromSchema<InputSchema>> ) => Promise<void>;
+} ): ( input: DeepMutable<FromSchema<InputSchema>> ) => Promise<void>;
+
+/**
+ * @callback OutputOnlyStepFn
+ * @returns {any} The output defined by the outputSchema
+ */
+
+/**
+ * Creates logical unit of work, called "step", which will be invoked from workflows.
+ *
+ * @param {object} options - Step options
+ * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
+ * @param {string} [options.description] - Description of the step
+ * @param {JSONSchema} options.outputSchema - JSON Schema for the fn output, will infer a TS type
+ * @param {OutputOnlyStepFn} options.fn - The function logic
+ * @returns {OutputOnlyStepFn} The options.fn function
+ */
+export async function step<
+  const OutputSchema extends JSONSchema
+>( options: {
   name: string;
   description?: string;
-  fn: ( input: TInput ) => Promise<TOutput>;
-}
-
-export interface WorkflowContext {
-  steps: {
-    [stepName: string]: ( input?: unknown ) => Promise<unknown>;
-  };
-  workflowId: string | null;
-  tools: {
-    webhook: ( options: {
-      name: string;
-      description?: string;
-      url: string;
-      payload: object;
-    } ) => Promise<unknown>;
-  };
-}
-
-export interface WorkflowDefinition<TInput = unknown, TOutput = unknown> {
+  outputSchema: OutputSchema;
+  fn: () => Promise<DeepMutable<FromSchema<OutputSchema>>>;
+} ): () => Promise<DeepMutable<FromSchema<OutputSchema>>>;
+
+/**
+ * @callback VoidStepFn
+ */
+
+/**
+ * Creates logical unit of work, called "step", which will be invoked from workflows.
+ *
+ * @param {object} options - Step options
+ * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
+ * @param {string} [options.description] - Description of the step
+ * @param {VoidStepFn} options.fn - The function logic
+ * @returns {VoidStepFn} The options.fn function
+ */
+export async function step( options: {
   name: string;
   description?: string;
-  fn: ( input: TInput, context: WorkflowContext ) => Promise<TOutput>;
-}
+  fn: () => Promise<void>;
+} ): () => Promise<void>;
+
+/*
+ * There is 4 overrides of the "workflow" function"
+ * - with fn receiving input and returning output;
+ * - with fn receiving input and returning void;
+ * - with fn receiving void and returning outout;
+ * - with fn receiving void and returning void;
+ */
+
+/**
+ * @callback WorkflowFn
+ * @param {any} input - The input, defined by the inputSchema
+ * @returns {any} The output defined by the outputSchema
+ */
+
+/**
+ * Creates a workflow orchestrator which can invoke steps.
+ *
+ * @param {object} options - Workflow options
+ * @param {string} options.name - Unique workflow name
+ * @param {string} [options.description] - Description of the workflow
+ * @param {JSONSchema} [options.inputSchema] - JSON Schema for workflow input
+ * @param {JSONSchema} [options.outputSchema] - JSON Schema for workflow output
+ * @param {WorkflowFn} options.fn - Workflow logic
+ * @returns {WorkflowFn} Callable workflow function
+ */
+export function workflow<
+  const InputSchema extends JSONSchema,
+  const OutputSchema extends JSONSchema
+>( options : {
+  name: string,
+  description?: string,
+  inputSchema: InputSchema,
+  outputSchema: OutputSchema,
+  fn: ( input: DeepMutable<FromSchema<InputSchema>> ) => Promise<DeepMutable<FromSchema<OutputSchema>>>
+} ): ( input: DeepMutable<FromSchema<InputSchema>> ) => Promise<DeepMutable<FromSchema<OutputSchema>>>;
+
+/**
+ * @callback InputOnlyWorkflowFn
+ * @param {any} input - The input, defined by the inputSchema
+ */
+
+/**
+ * Creates a workflow orchestrator which can invoke steps.
+ *
+ * @param {object} options - Workflow options
+ * @param {string} options.name - Unique workflow name
+ * @param {string} [options.description] - Description of the workflow
+ * @param {JSONSchema} [options.inputSchema] - JSON Schema for workflow input
+ * @param {InputOnlyWorkflowFn} options.fn - Workflow logic
+ * @returns {InputOnlyWorkflowFn} Callable workflow function
+ */
+export function workflow<
+  const InputSchema extends JSONSchema
+>( options : {
+  name: string,
+  description?: string,
+  inputSchema: InputSchema,
+  fn: ( input: DeepMutable<FromSchema<InputSchema>> ) => Promise<void>
+} ): ( input: DeepMutable<FromSchema<InputSchema>> ) => Promise<void>;
+
+/**
+ * @callback OutputOnlyWorkflowFn
+ * @returns {any} The output defined by the outputSchema
+ */
+
+/**
+ * Creates a workflow orchestrator which can invoke steps.
+ *
+ * @param {object} options - Workflow options
+ * @param {string} options.name - Unique workflow name
+ * @param {string} [options.description] - Description of the workflow
+ * @param {JSONSchema} [options.outputSchema] - JSON Schema for workflow output
+ * @param {OutputOnlyWorkflowFn} options.fn - Workflow logic
+ * @returns {OutputOnlyWorkflowFn} Callable workflow function
+ */
+export function workflow<
+  const OutputSchema extends JSONSchema
+>( options : {
+  name: string,
+  description?: string,
+  outputSchema: OutputSchema,
+  fn: () => Promise<DeepMutable<FromSchema<OutputSchema>>>
+} ): () => Promise<DeepMutable<FromSchema<OutputSchema>>>;
+
+/**
+ * @callback VoidWorkflowFn
+ * @param {any} input - The input, defined by the inputSchema
+ * @returns {any} The output defined by the outputSchema
+ */
 
-export function step<TInput = unknown, TOutput = unknown>(
-  definition: StepDefinition<TInput, TOutput>
-): ( input: TInput ) => Promise<TOutput>;
+/**
+ * Creates a workflow orchestrator which can invoke steps.
+ *
+ * @param {object} options - Workflow options
+ * @param {string} options.name - Unique workflow name
+ * @param {string} [options.description] - Description of the workflow
+ * @param {VoidWorkflowFn} options.fn - Workflow logic
+ * @returns {VoidWorkflowFn} Callable workflow function
+ */
+export function workflow( options : {
+  name: string,
+  description?: string,
+  fn: () => Promise<void>
+} ): () => Promise<void>;
 
-export function workflow<TInput = unknown, TOutput = unknown>(
-  definition: WorkflowDefinition<TInput, TOutput>
-): ( input: TInput ) => Promise<TOutput>;
+/**
+ * Create a webhook call that pauses the workflow until resumed via signal.
+ *
+ * Sends a request via an activity; the workflow will await a corresponding
+ * resume signal to continue and return the response payload.
+ *
+ * @param {object} options - Webhook request options
+ * @param {string} options.url - Webhook request url (POST)
+ * @param {object} [options.payload] - Webhook request payload
+ * @returns {Promise<object>} Resolves with the response payload when resumed
+ */
+export function createWebhook( options: { url: string; payload?: object } ): Promise<object>;
 
-export function startWorkflow<TOutput = unknown>( name: string, options?: { input?: TInput } ): Promise<TOutput>;
+/**
+ * Error indicating a non-recoverable failure.
+ *
+ * Use for failures that should not be retried by the workflow runtime.
+ */
+export class FatalError extends Error {}
 
-export { FatalError, ValidationError } from './errors.js';
+/**
+ * Error indicating invalid input or schema validation issues.
+ *
+ * Use for problems detected during input validation or contract checks.
+ */
+export class ValidationError extends Error {}

package/src/index.js

@@ -1,5 +1,6 @@
 import { step } from './interface/step.js';
-import { startWorkflow, workflow } from './interface/workflow.js';
+import { workflow } from './interface/workflow.js';
+import { createWebhook } from './interface/webhook.js';
 import { FatalError, ValidationError } from './errors.js';
 
-export { step, startWorkflow, workflow, FatalError, ValidationError };
+export { step, workflow, createWebhook, FatalError, ValidationError };

package/src/interface/metadata.js

@@ -1,4 +1,4 @@
-import { nameSymbol } from '#consts';
+import { METADATA_ACCESS_SYMBOL } from '#consts';
 
-export const setName = ( target, name ) =>
-  Object.defineProperty( target, nameSymbol, { value: name, writable: false, enumerable: false, configurable: false } );
+export const setMetadata = ( target, values ) =>
+  Object.defineProperty( target, METADATA_ACCESS_SYMBOL, { value: values, writable: false, enumerable: false, configurable: false } );

package/src/interface/step.js

@@ -1,6 +1,20 @@
-import { setName } from './metadata.js';
+import { setMetadata } from './metadata.js';
+import { validateStep } from './validations/static.js';
+import { validateStepInput, validateStepOutput } from './validations/runtime.js';
+import { invokeFnAndValidateOutputPreservingExecutionModel } from './utils.js';
 
-export function step( { name, description: _description, fn } ) {
-  setName( fn, name );
-  return fn;
+export function step( { name, description, inputSchema, outputSchema, fn } ) {
+  validateStep( { name, description, inputSchema, outputSchema, fn } );
+  const wrapper = input => {
+    if ( inputSchema ) {
+      validateStepInput( name, inputSchema, input );
+    }
+    if ( !outputSchema ) {
+      return fn( input );
+    }
+    return invokeFnAndValidateOutputPreservingExecutionModel( fn, input, validateStepOutput.bind( null, name, outputSchema ) );
+  };
+
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema } );
+  return wrapper;
 };