@pikku/core 0.10.1 → 0.11.0

package/dist/wirings/workflow/workflow-runner.js

@@ -0,0 +1,68 @@
+import { pikkuState } from '../../pikku-state.js';
+import { PikkuError } from '../../errors/error-handler.js';
+import { addFunction } from '../../function/function-runner.js';
+/**
+ * Exception thrown when workflow needs to pause for async step
+ */
+export class WorkflowAsyncException extends Error {
+    runId;
+    stepName;
+    constructor(runId, stepName) {
+        super(`Workflow paused at step: ${stepName}`);
+        this.runId = runId;
+        this.stepName = stepName;
+        this.name = 'WorkflowAsyncException';
+    }
+}
+/**
+ * Exception thrown when workflow is cancelled
+ */
+export class WorkflowCancelledException extends Error {
+    runId;
+    reason;
+    constructor(runId, reason) {
+        super(reason || 'Workflow cancelled');
+        this.runId = runId;
+        this.reason = reason;
+        this.name = 'WorkflowCancelledException';
+    }
+}
+/**
+ * Error class for workflow not found
+ */
+export class WorkflowNotFoundError extends PikkuError {
+    constructor(name) {
+        super(`Workflow not found: ${name}`);
+    }
+}
+/**
+ * Error class for workflow not found
+ */
+export class WorkflowRunNotFound extends PikkuError {
+    constructor(runId) {
+        super(`Workflow run not found: ${runId}`);
+    }
+}
+/**
+ * Register a workflow with the system
+ */
+export const wireWorkflow = (workflow) => {
+    // Get workflow metadata from inspector
+    const meta = pikkuState('workflows', 'meta');
+    const workflowMeta = meta[workflow.name];
+    if (!workflowMeta) {
+        throw new Error(`Workflow metadata not found for '${workflow.name}'. Make sure to run the CLI to generate metadata.`);
+    }
+    // Register the function with pikku
+    addFunction(workflowMeta.pikkuFuncName, {
+        func: workflow.func.func,
+        auth: workflow.func.auth,
+        permissions: workflow.func.permissions,
+        middleware: workflow.func.middleware,
+        tags: workflow.func.tags,
+        docs: workflow.func.docs,
+    });
+    // Store workflow definition in state
+    const registrations = pikkuState('workflows', 'registrations');
+    registrations.set(workflow.name, workflow);
+};

package/dist/wirings/workflow/workflow.types.d.ts

@@ -0,0 +1,247 @@
+import { PikkuDocs, MiddlewareMetadata, SerializedError, CoreSingletonServices, CreateSessionServices, CoreConfig } from '../../types/core.types.js';
+import { CorePikkuFunctionConfig } from '../../function/functions.types.js';
+export interface WorkflowServiceConfig {
+    retries: number;
+    retryDelay: number;
+    orchestratorQueueName: string;
+    stepWorkerQueueName: string;
+    sleeperRPCName: string;
+}
+/**
+ * Workflow run status
+ */
+export type WorkflowStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Workflow step status
+ */
+export type StepStatus = 'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed';
+/**
+ * Workflow run representation
+ */
+export interface WorkflowRun {
+    /** Unique run ID */
+    id: string;
+    /** Workflow name */
+    workflow: string;
+    /** Current status */
+    status: WorkflowStatus;
+    /** Input data */
+    input: any;
+    /** Output data (if completed) */
+    output?: any;
+    /** Error (if failed) */
+    error?: SerializedError;
+    /** Creation timestamp */
+    createdAt: Date;
+    /** Last update timestamp */
+    updatedAt: Date;
+}
+/**
+ * Step state representation
+ */
+export interface StepState {
+    /** Unique step ID */
+    stepId: string;
+    /** Step status */
+    status: StepStatus;
+    /** Step result (if done) */
+    result?: any;
+    /** Step error (if error) */
+    error?: SerializedError;
+    /** Number of attempts made (starts at 1) */
+    attemptCount: number;
+    /** Maximum retry attempts allowed */
+    retries?: number;
+    /** Delay between retries */
+    retryDelay?: string | number;
+    /** Creation timestamp */
+    createdAt: Date;
+    /** Last update timestamp */
+    updatedAt: Date;
+    /** Timestamp when step started running */
+    runningAt?: Date;
+    /** Timestamp when step was scheduled */
+    scheduledAt?: Date;
+    /** Timestamp when step succeeded */
+    succeededAt?: Date;
+    /** Timestamp when step failed */
+    failedAt?: Date;
+}
+/**
+ * Core workflow definition
+ */
+export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
+    /** Unique workflow name */
+    name: string;
+    /** Description of the workflow */
+    description?: string;
+    /** The workflow function */
+    func: PikkuFunctionConfig;
+    /** Middleware chain for this workflow */
+    middleware?: PikkuFunctionConfig['middleware'];
+    /** Permission requirements */
+    permissions?: PikkuFunctionConfig['permissions'];
+    /** Tags for organization and filtering */
+    tags?: string[];
+    /** Documentation metadata */
+    docs?: PikkuDocs;
+};
+/**
+ * Workflow step options
+ */
+export interface WorkflowStepOptions {
+    /** Display name for logs/UI (optional, doesn't affect execution) */
+    description?: string;
+    /** Number of retry attempts for failed steps (only applies to local execution) */
+    retries?: number;
+    /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
+    retryDelay?: string | number;
+}
+/**
+ * Type signature for workflow.do() RPC form - used by inspector
+ */
+export type WorkflowInteractionDoRPC = <TOutput = any, TInput = any>(stepName: string, rpcName: string, data: TInput, options?: WorkflowStepOptions) => Promise<TOutput>;
+/**
+ * Type signature for workflow.do() inline form - used by inspector
+ */
+export type WorkflowInteractionDoInline = <T>(stepName: string, fn: () => Promise<T> | T, options?: WorkflowStepOptions) => Promise<T>;
+/**
+ * Type signature for workflow.sleep() - used by inspector
+ */
+export type WorkflowInteractionSleep = (stepName: string, duration: string) => Promise<void>;
+/**
+ * Workflow step metadata (extracted by inspector)
+ */
+export type WorkflowStepMeta = {
+    /** RPC form - generates queue worker */
+    type: 'rpc';
+    /** Cache key (stepName from workflow.do) */
+    stepName: string;
+    /** RPC to invoke */
+    rpcName: string;
+    /** Display name */
+    description?: string;
+    /** Step options */
+    options?: WorkflowStepOptions;
+} | {
+    /** Inline form - local execution */
+    type: 'inline';
+    /** Cache key (stepName from workflow.do) */
+    stepName: string;
+    /** Display name */
+    description?: string;
+    /** Step options */
+    options?: WorkflowStepOptions;
+} | {
+    /** Sleep step */
+    type: 'sleep';
+    /** Cache key (stepName from workflow.sleep) */
+    stepName: string;
+    /** Sleep duration */
+    duration: string | number;
+};
+/**
+ * Workflow step interaction context for RPC functions
+ * Provides step-level metadata including retry attempt tracking
+ */
+export interface WorkflowStepInteraction {
+    /** The workflow run ID */
+    runId: string;
+    /** The unique step ID */
+    stepId: string;
+    /** Current attempt number (1-indexed, increments on retry) */
+    attemptCount: number;
+}
+/**
+ * Workflow interaction object for middleware
+ * Provides workflow-specific capabilities to function execution
+ */
+export interface PikkuWorkflowInteraction {
+    /** The workflow name */
+    workflowName: string;
+    /** The current run ID */
+    runId: string;
+    /** Get the current workflow run */
+    getRun: () => Promise<WorkflowRun>;
+    /** Execute a workflow step (overloaded - RPC or inline form) */
+    do: WorkflowInteractionDoRPC & WorkflowInteractionDoInline;
+    /** Sleep for a duration */
+    sleep: WorkflowInteractionSleep;
+    /** Cancel the current workflow run */
+    cancel: (reason?: string) => Promise<void>;
+}
+/**
+ * Workflow client interface
+ */
+export interface PikkuWorkflow {
+    /** Start a new workflow run */
+    start: <I>(input: I) => Promise<{
+        runId: string;
+    }>;
+    /** Get a workflow run by ID */
+    getRun: (runId: string) => Promise<WorkflowRun>;
+    /** Cancel a running workflow */
+    cancelRun: (runId: string) => Promise<void>;
+}
+/**
+ * Workflows metadata for inspector/CLI
+ */
+export type WorkflowsMeta = Record<string, {
+    pikkuFuncName: string;
+    workflowName: string;
+    description?: string;
+    session?: undefined;
+    docs?: PikkuDocs;
+    tags?: string[];
+    middleware?: MiddlewareMetadata[];
+    steps: WorkflowStepMeta[];
+}>;
+/**
+ * Interface for workflow orchestration
+ * Handles workflow execution, replay, orchestration logic, and run-level state
+ */
+export interface WorkflowService {
+    createRun(workflowName: string, input: any): Promise<string>;
+    getRun(id: string): Promise<WorkflowRun | null>;
+    getRunHistory(runId: string): Promise<Array<StepState & {
+        stepName: string;
+    }>>;
+    updateRunStatus(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    resumeWorkflow(runId: string): Promise<void>;
+    setServices(singletonServices: CoreSingletonServices, createSessionServices: CreateSessionServices, config: CoreConfig): void;
+    startWorkflow<I>(name: string, input: I, rpcService: any): Promise<{
+        runId: string;
+    }>;
+    runWorkflowJob(runId: string, rpcService: any): Promise<void>;
+    orchestrateWorkflow(runId: string, rpcService: any): Promise<void>;
+    executeWorkflowSleep(runId: string, stepId: string): Promise<void>;
+    insertStepState(runId: string, stepName: string, rpcName: string, data: any, stepOptions?: {
+        retries?: number;
+        retryDelay?: string | number;
+    }): Promise<StepState>;
+    getStepState(runId: string, stepName: string): Promise<StepState>;
+    setStepRunning(stepId: string): Promise<void>;
+    setStepScheduled(stepId: string): Promise<void>;
+    setStepResult(stepId: string, result: any): Promise<void>;
+    setStepError(stepId: string, error: Error): Promise<void>;
+    createRetryAttempt(stepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    executeWorkflowStep(runId: string, stepName: string, rpcName: string | null, data: any, rpcService: any): Promise<void>;
+}
+/**
+ * Worker input types for generated queue workers
+ */
+export type WorkflowStepInput = {
+    runId: string;
+    stepName: string;
+    rpcName: string;
+    data: any;
+};
+export type WorkflowOrchestratorInput = {
+    runId: string;
+};
+export type WorkflowSleeperInput = {
+    runId: string;
+    stepId: string;
+};

package/dist/wirings/workflow/workflow.types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -20,6 +20,7 @@
     "./middleware": "./dist/middleware/index.js",
     "./function": "./dist/function/index.js",
     "./channel": "./dist/wirings/channel/index.js",
+    "./workflow": "./dist/wirings/workflow/index.js",
     "./channel/local": "./dist/wirings/channel/local/index.js",
     "./channel/serverless": "./dist/wirings/channel/serverless/index.js",
     "./http": "./dist/wirings/http/index.js",
@@ -36,8 +37,6 @@
     "./types": "./dist/types/index.d.ts"
   },
   "dependencies": {
-    "@types/cookie": "^1.0.0",
-    "@types/uuid": "^11.0.0",
     "cookie": "^1.0.2",
     "path-to-regexp": "^8.3.0",
     "picoquery": "^2.5.0"

package/src/function/function-runner.ts

@@ -91,7 +91,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   // Helper function to run permissions and execute the function
   const executeFunction = async () => {
-    const session = userSession?.get()
+    const session = await userSession?.get()
     if (wiringAuth === true || funcConfig.auth === true) {
       // This means it was explicitly enabled in either wiring or function and has to be respected
       if (!session) {
@@ -101,7 +101,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     if (wiringAuth === undefined && funcConfig.auth === undefined) {
       // We always default to requiring auth unless explicitly disabled
       if (!session) {
-        throw new ForbiddenError('Authentication required')
+        // throw new ForbiddenError('Authentication required')
       }
     }
 

package/src/function/functions.types.ts

@@ -187,6 +187,7 @@ export type CorePikkuFunctionConfig<
 > = {
   name?: string
   expose?: boolean
+  internal?: boolean
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>

package/src/index.ts

@@ -10,11 +10,13 @@ export * from './services/schema-service.js'
 export * from './services/jwt-service.js'
 export * from './services/secret-service.js'
 export * from './services/user-session-service.js'
+export * from './services/scheduler-service.js'
 export * from './wirings/http/index.js'
 export * from './wirings/channel/index.js'
 export * from './wirings/scheduler/index.js'
 export * from './wirings/rpc/index.js'
 export * from './wirings/queue/index.js'
+export * from './wirings/workflow/index.js'
 export * from './wirings/mcp/index.js'
 export * from './wirings/cli/index.js'
 export * from './errors/index.js'

package/src/middleware-runner.ts

@@ -122,6 +122,7 @@ const middlewareCache: Record<
   [PikkuWiringTypes.scheduler]: {},
   [PikkuWiringTypes.mcp]: {},
   [PikkuWiringTypes.cli]: {},
+  [PikkuWiringTypes.workflow]: {},
 }
 
 /**

package/src/permissions.ts

@@ -197,6 +197,7 @@ const combinedPermissionsCache: Record<
   [PikkuWiringTypes.scheduler]: {},
   [PikkuWiringTypes.mcp]: {},
   [PikkuWiringTypes.cli]: {},
+  [PikkuWiringTypes.workflow]: {},
 }
 
 /**

package/src/pikku-state.ts

@@ -21,7 +21,7 @@ import {
   CorePikkuPermission,
 } from './function/functions.types.js'
 import {
-  queueWorkersMeta,
+  QueueWorkersMeta,
   CoreQueueWorker,
 } from './wirings/queue/queue.types.js'
 import {
@@ -33,6 +33,10 @@ import {
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
 import { CLIMeta, CLIProgramState } from './wirings/cli/cli.types.js'
+import {
+  CoreWorkflow,
+  WorkflowsMeta,
+} from './wirings/workflow/workflow.types.js'
 
 interface PikkuState {
   function: {
@@ -65,7 +69,11 @@ interface PikkuState {
   }
   queue: {
     registrations: Map<string, CoreQueueWorker>
-    meta: queueWorkersMeta
+    meta: QueueWorkersMeta
+  }
+  workflows: {
+    registrations: Map<string, CoreWorkflow>
+    meta: WorkflowsMeta
   }
   mcp: {
     resources: Map<string, CoreMCPResource>
@@ -166,6 +174,10 @@ export const resetPikkuState = () => {
       registrations: new Map(),
       meta: {},
     },
+    workflows: {
+      registrations: new Map(),
+      meta: {},
+    },
     mcp: {
       resources: new Map(),
       resourcesMeta: {} as MCPResourceMeta,

package/src/services/index.ts

@@ -10,6 +10,7 @@ export * from './secret-service.js'
 export * from './variables-service.js'
 export * from './schema-service.js'
 export * from './user-session-service.js'
+export * from './scheduler-service.js'
 
 // Local implementations
 export * from './local-secrets.js'

package/src/services/scheduler-service.ts

@@ -0,0 +1,76 @@
+import { CoreUserSession } from '../types/core.types.js'
+
+/**
+ * Minimal metadata for listing scheduled tasks
+ */
+export interface ScheduledTaskSummary {
+  /** Unique task ID */
+  taskId: string
+  /** RPC function name to invoke */
+  rpcName: string
+  /** Scheduled execution time */
+  scheduledFor: Date
+}
+
+/**
+ * Full metadata for a scheduled task retrieved from the queue
+ */
+export interface ScheduledTaskInfo extends ScheduledTaskSummary {
+  /** Data to pass to the RPC function */
+  data?: any
+  /** User session */
+  session?: CoreUserSession
+  /** Task status */
+  status?: 'scheduled' | 'active' | 'completed' | 'failed'
+}
+
+/**
+ * Abstract scheduler service for persistent scheduled task management
+ * Implementations use queue backends (pg-boss, BullMQ) for distributed scheduling
+ */
+export abstract class SchedulerService {
+  /**
+   * Initialize the scheduler service
+   */
+  abstract init(): Promise<void>
+
+  /**
+   * Schedule a one-off delayed RPC call
+   * @param delay - Delay before execution (number in milliseconds or duration string like "5h", "30m")
+   * @param rpcName - RPC function name to invoke
+   * @param data - Data to pass to the RPC function
+   * @param session - Optional user session
+   * @returns Task ID
+   */
+  abstract scheduleRPC(
+    delay: number | string,
+    rpcName: string,
+    data?: any,
+    session?: CoreUserSession
+  ): Promise<string>
+
+  /**
+   * Unschedule a task by ID
+   * @param taskId - Task ID
+   * @returns Success status
+   */
+  abstract unschedule(taskId: string): Promise<boolean>
+
+  /**
+   * Get a scheduled task by ID with full details
+   * @param taskId - Task ID
+   * @returns Task info or null if not found
+   */
+  abstract getTask(taskId: string): Promise<ScheduledTaskInfo | null>
+
+  /**
+   * Get all scheduled tasks with minimal info
+   * @returns Array of task summaries with taskId, rpcName, and schedule
+   */
+  abstract getAllTasks(): Promise<ScheduledTaskSummary[]>
+
+  /**
+   * Close any open connections
+   */
+  abstract close(): Promise<void>
+}

package/src/time-utils.ts

@@ -30,3 +30,78 @@ export const getRelativeTimeOffsetFromNow = (
 ): Date => {
   return new Date(Date.now() + getRelativeTimeOffset(relativeTime))
 }
+
+/**
+ * Get duration in milliseconds from a string or number
+ * @param duration
+ * @returns
+ */
+export const getDurationInMilliseconds = (
+  duration: string | number
+): number => {
+  if (typeof duration === 'number') {
+    return duration
+  }
+  return parseDurationString(duration)
+}
+
+/**
+ * Parse a duration string to milliseconds
+ * Supports formats like: '2s', '5s', '5sec', '5seconds', '5m', '5min', '5minutes', '1h', '1hour', '2d', '2day', '1w', '1week'
+ *
+ * @param duration - Duration string (e.g., '2s', '5min', '2hours', '1day')
+ * @returns Duration in milliseconds
+ */
+export const parseDurationString = (duration: string): number => {
+  const match = duration.match(
+    /^(\d+)(ms|milliseconds?|s|sec|seconds?|m|min|minutes?|h|hour|hours?|d|day|days?|w|week|weeks?|y|year|years?)$/
+  )
+
+  if (!match) {
+    throw new Error(
+      `Invalid duration format: ${duration}. Use formats like '2s', '5s', '5min', '1hour', '2days', '1week'`
+    )
+  }
+
+  const value = parseInt(match[1], 10)
+  const unitStr = match[2]
+
+  // Handle milliseconds specially
+  if (
+    unitStr === 'ms' ||
+    unitStr === 'millisecond' ||
+    unitStr === 'milliseconds'
+  ) {
+    return value
+  }
+
+  // Map string variations to TimeUnit
+  let unit: TimeUnit
+  if (
+    unitStr === 's' ||
+    unitStr === 'sec' ||
+    unitStr === 'second' ||
+    unitStr === 'seconds'
+  ) {
+    unit = 'second'
+  } else if (
+    unitStr === 'm' ||
+    unitStr === 'min' ||
+    unitStr === 'minute' ||
+    unitStr === 'minutes'
+  ) {
+    unit = 'minute'
+  } else if (unitStr === 'h' || unitStr === 'hour' || unitStr === 'hours') {
+    unit = 'hour'
+  } else if (unitStr === 'd' || unitStr === 'day' || unitStr === 'days') {
+    unit = 'day'
+  } else if (unitStr === 'w' || unitStr === 'week' || unitStr === 'weeks') {
+    unit = 'week'
+  } else if (unitStr === 'y' || unitStr === 'year' || unitStr === 'years') {
+    unit = 'year'
+  } else {
+    throw new Error(`Unknown time unit: ${unitStr}`)
+  }
+
+  return getRelativeTimeOffset({ value, unit })
+}

package/src/types/core.types.ts

@@ -8,8 +8,15 @@ import { PikkuChannel } from '../wirings/channel/channel.types.js'
 import { PikkuRPC } from '../wirings/rpc/rpc-types.js'
 import { PikkuMCP } from '../wirings/mcp/mcp.types.js'
 import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
-import { PikkuQueue } from '../wirings/queue/queue.types.js'
+import { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js'
 import { PikkuCLI } from '../wirings/cli/cli.types.js'
+import {
+  PikkuWorkflowInteraction,
+  WorkflowService,
+  WorkflowServiceConfig,
+  WorkflowStepInteraction,
+} from '../wirings/workflow/workflow.types.js'
+import { SchedulerService } from '../services/scheduler-service.js'
 
 export enum PikkuWiringTypes {
   http = 'http',
@@ -19,6 +26,7 @@ export enum PikkuWiringTypes {
   queue = 'queue',
   mcp = 'mcp',
   cli = 'cli',
+  workflow = 'workflow',
 }
 
 export interface FunctionServicesMeta {
@@ -73,6 +81,7 @@ export type FunctionRuntimeMeta = {
   inputSchemaName: string | null
   outputSchemaName: string | null
   expose?: boolean
+  internal?: boolean
 }
 
 export type FunctionMeta = FunctionRuntimeMeta &
@@ -137,6 +146,8 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
   logLevel?: LogLevel
   /** Secrets used by the application (optional). */
   secrets?: {}
+
+  workflow?: WorkflowServiceConfig
 } & Config
 
 /**
@@ -158,6 +169,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   logger: Logger
   /** The variable service to be used */
   variables: VariablesService
+  /** The workflow orchestrator service */
+  workflowService?: WorkflowService
+  /** The queue service */
+  queueService?: QueueService
+  /** The scheduler service */
+  schedulerService?: SchedulerService
 }
 
 /**
@@ -171,6 +188,8 @@ export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
   scheduledTask: PikkuScheduledTask
   queue: PikkuQueue
   cli: PikkuCLI
+  workflow: PikkuWorkflowInteraction
+  workflowStep: WorkflowStepInteraction
 }>
 
 /**
@@ -344,3 +363,13 @@ export type PikkuDocs = {
   tags?: string[]
   errors?: string[]
 }
+
+/**
+ * Serialized error for storage
+ */
+export interface SerializedError {
+  message: string
+  stack?: string
+  code?: string
+  [key: string]: any
+}