ai-workflows 2.1.3 → 2.3.0

package/src/types.ts

@@ -2,12 +2,14 @@
  * Types for ai-workflows
  */
 
+import type { WorkflowContextType } from '@org.ai/types'
+
 /**
  * Handler function with source code for remote execution
  */
 export interface HandlerFunction<T = unknown> {
   /** The actual function */
-  fn: (...args: any[]) => void | Promise<void>
+  fn: (...args: unknown[]) => void | Promise<void>
   /** Source code string for remote execution */
   source: string
   /** Handler name (for debugging) */
@@ -21,6 +23,9 @@ export interface HandlerFunction<T = unknown> {
  * Generic order follows Promise<T> convention:
  * - TOutput (first) is what the handler returns
  * - TInput (second) is what the handler receives
+ *
+ * Note: Uses WorkflowContext (extends WorkflowContextType from @org.ai/types)
+ * for workflow-specific features like OnProxy, EveryProxy, getState, log.
  */
 export type EventHandler<TOutput = unknown, TInput = unknown> = (
   data: TInput,
@@ -30,19 +35,25 @@ export type EventHandler<TOutput = unknown, TInput = unknown> = (
 /**
  * Schedule handler function type
  */
-export type ScheduleHandler = (
-  $: WorkflowContext
-) => void | Promise<void>
+export type ScheduleHandler = ($: WorkflowContext) => void | Promise<void>
 
 /**
- * Workflow context ($) passed to handlers
+ * Workflow context ($) passed to handlers.
+ * Extends WorkflowContextType from @org.ai/types with workflow-specific features.
  */
-export interface WorkflowContext {
+export interface WorkflowContext extends WorkflowContextType {
   /**
-   * Send an event (fire and forget, durable)
-   * Confirms receipt but doesn't wait for result
+   * Track an event (fire and forget)
+   * Best effort, no confirmation, swallows errors
+   * Use for telemetry and non-critical events
    */
-  send: <T = unknown>(event: string, data: T) => Promise<void>
+  track: (event: string, data: unknown) => void
+
+  /**
+   * Send an event (durable)
+   * Guaranteed delivery, returns trackable EventId
+   */
+  send: <T = unknown>(event: string, data: T) => string
 
   /**
    * Do an action (durable, waits for result)
@@ -245,7 +256,10 @@ export type EveryProxy = {
   weeks: (value: number) => (handler: ScheduleHandler) => void
 
   // Index signature for dynamic patterns
-  [key: string]: ((handler: ScheduleHandler) => void) | ((value: number) => (handler: ScheduleHandler) => void) | DayScheduleProxy
+  [key: string]:
+    | ((handler: ScheduleHandler) => void)
+    | ((value: number) => (handler: ScheduleHandler) => void)
+    | DayScheduleProxy
 }
 
 /**
@@ -267,7 +281,10 @@ export interface OnProxyHandler extends ProxyHandler<Record<string, NounEventPro
 /**
  * ProxyHandler type for the inner noun level (event accessors)
  */
-export interface NounEventProxyHandler extends ProxyHandler<Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>> {
+export interface NounEventProxyHandler
+  extends ProxyHandler<
+    Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>
+  > {
   get(
     target: Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>,
     event: string,
@@ -294,11 +311,7 @@ export interface DayScheduleProxyHandler extends ProxyHandler<(handler: Schedule
     timeKey: string,
     receiver: unknown
   ): ((handler: ScheduleHandler) => void) | undefined
-  apply(
-    target: (handler: ScheduleHandler) => void,
-    thisArg: unknown,
-    args: [ScheduleHandler]
-  ): void
+  apply(target: (handler: ScheduleHandler) => void, thisArg: unknown, args: [ScheduleHandler]): void
 }
 
 /**
@@ -395,7 +408,9 @@ export type PluralUnitKey = keyof PluralUnitMapping
  * Type guard to check if a string is a valid plural unit key
  */
 export function isPluralUnitKey(key: string): key is PluralUnitKey {
-  return key === 'seconds' || key === 'minutes' || key === 'hours' || key === 'days' || key === 'weeks'
+  return (
+    key === 'seconds' || key === 'minutes' || key === 'hours' || key === 'days' || key === 'weeks'
+  )
 }
 
 /**