@pikku/core 0.10.2 → 0.11.1

package/src/permissions.ts

@@ -1,8 +1,8 @@
 import {
   CoreServices,
-  CoreUserSession,
   PikkuWiringTypes,
   PermissionMetadata,
+  PikkuWire,
 } from './types/core.types.js'
 import {
   CorePermissionGroup,
@@ -16,14 +16,14 @@ import { freezeDedupe } from './utils.js'
  * This function validates permissions by iterating over permission groups and executing the corresponding permission functions. If all functions in at least one group return true, the permission is considered valid.
  * @param services - The core services required for permission validation.
  * @param data - The data to be used in the permission validation functions.
- * @param session - An optional user session for permission validation.
+ * @param wire - The wire object containing request/response context and session.
  * @returns A promise that resolves to void.
  */
-export const verifyPermissions = async (
+export const verifyPermissions = async <Out = any>(
   permissions: CorePermissionGroup,
   services: CoreServices,
   data: any,
-  session?: CoreUserSession
+  wire: PikkuWire<any, never, any, never, never, never>
 ): Promise<boolean> => {
   if (!permissions) {
     return true
@@ -38,13 +38,13 @@ export const verifyPermissions = async (
   for (const funcs of permissionGroups) {
     if (funcs instanceof Array) {
       const permissioned = await Promise.all(
-        funcs.map((func) => func(services, data, session))
+        funcs.map((func) => func(services, data, wire))
       )
       if (permissioned.every((result) => result)) {
         valid = true
       }
     } else {
-      valid = await funcs(services, data, session)
+      valid = await funcs(services, data, wire as any)
     }
     if (valid) {
       return true
@@ -190,13 +190,14 @@ const combinedPermissionsCache: Record<
   PikkuWiringTypes,
   Record<string, readonly (CorePermissionGroup | CorePikkuPermission)[]>
 > = {
-  [PikkuWiringTypes.http]: {},
-  [PikkuWiringTypes.rpc]: {},
-  [PikkuWiringTypes.channel]: {},
-  [PikkuWiringTypes.queue]: {},
-  [PikkuWiringTypes.scheduler]: {},
-  [PikkuWiringTypes.mcp]: {},
-  [PikkuWiringTypes.cli]: {},
+  http: {},
+  rpc: {},
+  channel: {},
+  queue: {},
+  scheduler: {},
+  mcp: {},
+  cli: {},
+  workflow: {},
 }
 
 /**
@@ -334,17 +335,17 @@ export const runPermissions = async (
     wirePermissions,
     funcInheritedPermissions,
     funcPermissions,
-    allServices,
+    services,
+    wire,
     data,
-    session,
   }: {
     wireInheritedPermissions?: PermissionMetadata[]
     wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
     funcInheritedPermissions?: PermissionMetadata[]
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
-    allServices: CoreServices
+    services: CoreServices
+    wire: PikkuWire<any, never, any, never, never, never>
     data: any
-    session?: CoreUserSession
   }
 ) => {
   // Combine all permissions: wireInheritedPermissions → wirePermissions → funcInheritedPermissions → funcPermissions
@@ -361,9 +362,9 @@ export const runPermissions = async (
     for (const permission of allPermissions) {
       const result = await verifyPermissions(
         typeof permission === 'function' ? { permission } : permission,
-        allServices,
+        services,
         data,
-        session
+        wire
       )
       if (result) {
         permissioned = true
@@ -371,7 +372,7 @@ export const runPermissions = async (
       }
     }
     if (!permissioned) {
-      allServices.logger.debug('Permission denied - combined permissions')
+      services.logger.debug('Permission denied - combined permissions')
       throw new ForbiddenError('Permission denied')
     }
   }

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/services/user-session-service.ts

@@ -1,18 +1,21 @@
 import { ChannelStore } from '../wirings/channel/channel-store.js'
 import { CoreUserSession } from '../types/core.types.js'
 
-export interface UserSessionService<UserSession extends CoreUserSession> {
+export interface SessionService<UserSession extends CoreUserSession> {
   sessionChanged: boolean
+  initial: UserSession | undefined
   setInitial(session: UserSession): void
+  freezeInitial(): UserSession | undefined
   set(session: UserSession): Promise<void> | void
   clear(): Promise<void> | void
-  get(): Promise<UserSession | undefined> | UserSession | undefined
+  get(): Promise<UserSession> | UserSession | undefined
 }
 
-export class PikkuUserSessionService<UserSession extends CoreUserSession>
-  implements UserSessionService<UserSession>
+export class PikkuSessionService<UserSession extends CoreUserSession>
+  implements SessionService<UserSession>
 {
   public sessionChanged = false
+  public initial: UserSession | undefined
   private session: UserSession | undefined
   constructor(
     private channelStore?: ChannelStore<unknown, unknown, UserSession>,
@@ -27,6 +30,13 @@ export class PikkuUserSessionService<UserSession extends CoreUserSession>
     this.session = session
   }
 
+  public freezeInitial() {
+    if (this.initial === undefined) {
+      this.initial = this.session
+    }
+    return this.initial
+  }
+
   public set(session: UserSession) {
     this.sessionChanged = true
     this.session = session

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

@@ -3,23 +3,30 @@ import { VariablesService } from '../services/variables-service.js'
 import { SchemaService } from '../services/schema-service.js'
 import { JWTService } from '../services/jwt-service.js'
 import { PikkuHTTP } from '../wirings/http/http.types.js'
-import { UserSessionService } from '../services/user-session-service.js'
+import { SessionService } from '../services/user-session-service.js'
 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 {
+  PikkuWorkflowWire,
+  WorkflowService,
+  WorkflowServiceConfig,
+  WorkflowStepWire,
+} from '../wirings/workflow/workflow.types.js'
+import { SchedulerService } from '../services/scheduler-service.js'
 
-export enum PikkuWiringTypes {
-  http = 'http',
-  scheduler = 'scheduler',
-  channel = 'channel',
-  rpc = 'rpc',
-  queue = 'queue',
-  mcp = 'mcp',
-  cli = 'cli',
-}
+export type PikkuWiringTypes =
+  | 'http'
+  | 'scheduler'
+  | 'channel'
+  | 'rpc'
+  | 'queue'
+  | 'mcp'
+  | 'cli'
+  | 'workflow'
 
 export interface FunctionServicesMeta {
   optimized: boolean
@@ -73,20 +80,22 @@ export type FunctionRuntimeMeta = {
   inputSchemaName: string | null
   outputSchemaName: string | null
   expose?: boolean
+  internal?: boolean
 }
 
 export type FunctionMeta = FunctionRuntimeMeta &
-  Partial<{
-    name: string
-    services: FunctionServicesMeta
-    inputs: string[] | null
-    outputs: string[] | null
-    tags: string[]
-    docs: PikkuDocs
-    isDirectFunction: boolean // true if it's pikkuFunc(fn), false if it's pikkuFunc({ func: fn })
-    middleware: MiddlewareMetadata[] // Function-level middleware
-    permissions: PermissionMetadata[] // Function-level permissions
-  }>
+  Partial<
+    {
+      name: string
+      services: FunctionServicesMeta
+      usedWires: string[]
+      inputs: string[] | null
+      outputs: string[] | null
+      middleware: MiddlewareMetadata[]
+      permissions: PermissionMetadata[]
+      isDirectFunction: boolean
+    } & CommonWireMeta
+  >
 
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
 export type FunctionsMeta = Record<string, FunctionMeta>
@@ -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,32 +169,53 @@ 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
 }
 
 /**
- * Represents different forms of interaction within Pikku and the outside world.
+ * Represents different forms of wire within Pikku and the outside world.
  */
-export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
+export type PikkuWire<
+  In = unknown,
+  Out = unknown,
+  HasInitialSession extends boolean = false,
+  UserSession extends CoreUserSession = CoreUserSession,
+  TypedRPC extends PikkuRPC = PikkuRPC,
+  IsChannel extends true | null = null,
+  MCPTools extends string | never = never,
+  TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire,
+> = Partial<{
   http: PikkuHTTP<In>
-  mcp: PikkuMCP
-  rpc: PikkuRPC
-  channel: PikkuChannel<unknown, Out>
+  mcp: PikkuMCP<MCPTools>
+  rpc: TypedRPC
+  channel: [IsChannel] extends [null]
+    ? PikkuChannel<unknown, Out>
+    : PikkuChannel<unknown, Out> | undefined
   scheduledTask: PikkuScheduledTask
   queue: PikkuQueue
   cli: PikkuCLI
+  workflow: TypedWorkflow
+  workflowStep: WorkflowStepWire
+  initialSession: HasInitialSession extends true
+    ? UserSession
+    : UserSession | undefined
+  session: SessionService<UserSession>
 }>
 
 /**
- * A function that can wrap an interaction and be called before or after
+ * A function that can wrap an wire and be called before or after
  */
 export type CorePikkuMiddleware<
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
-  services: SingletonServices & {
-    userSession: UserSessionService<UserSession>
-  },
-  interactions: PikkuInteraction,
+  services: SingletonServices,
+  wires: PikkuWire<unknown, unknown, false, UserSession>,
   next: () => Promise<void>
 ) => Promise<void>
 
@@ -235,7 +267,7 @@ export type CorePikkuMiddlewareGroup<
  * ```typescript
  * // Direct function syntax
  * export const logMiddleware = pikkuMiddleware(
- *   async ({ logger }, _interaction, next) => {
+ *   async ({ logger }, next) => {
  *     logger.info('Request started')
  *     await next()
  *   }
@@ -245,7 +277,7 @@ export type CorePikkuMiddlewareGroup<
  * export const logMiddleware = pikkuMiddleware({
  *   name: 'Request Logger',
  *   description: 'Logs request information',
- *   func: async ({ logger }, _interaction, next) => {
+ *   func: async ({ logger }, next) => {
  *     logger.info('Request started')
  *     await next()
  *   }
@@ -273,7 +305,7 @@ export const pikkuMiddleware = <
  *   message,
  *   level = 'info'
  * }) => {
- *   return pikkuMiddleware(async ({ logger }, _interaction, next) => {
+ *   return pikkuMiddleware(async ({ logger }, next) => {
  *     logger[level](message)
  *     await next()
  *   })
@@ -287,20 +319,15 @@ export const pikkuMiddlewareFactory = <In = any>(
 }
 
 /**
- * Represents the core services used by Pikku, including singleton services and the request/response interaction.
+ * Represents the core services used by Pikku, including singleton services.
  */
-export type CoreServices<
-  SingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = SingletonServices &
-  PikkuInteraction & {
-    userSession?: UserSessionService<UserSession>
-  }
+export type CoreServices<SingletonServices = CoreSingletonServices> =
+  SingletonServices
 
-export type SessionServices<
+export type WireServices<
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   Services = CoreServices<SingletonServices>,
-> = Omit<Services, keyof SingletonServices | keyof PikkuInteraction | 'session'>
+> = Omit<Services, keyof SingletonServices | 'session'>
 
 /**
  * Defines a function type for creating singleton services from the given configuration.
@@ -316,16 +343,15 @@ export type CreateSingletonServices<
 /**
  * Defines a function type for creating session-specific services.
  */
-export type CreateSessionServices<
+export type CreateWireServices<
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   Services extends
     CoreServices<SingletonServices> = CoreServices<SingletonServices>,
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
   services: SingletonServices,
-  interaction: PikkuInteraction,
-  session: UserSession | undefined
-) => Promise<SessionServices<Services, SingletonServices>>
+  wire: PikkuWire<unknown, unknown, false, UserSession>
+) => Promise<WireServices<Services, SingletonServices>>
 
 /**
  * Defines a function type for creating config.
@@ -338,9 +364,24 @@ export type CreateConfig<
 /**
  * Represents the documentation for a route, including summary, description, tags, and errors.
  */
-export type PikkuDocs = {
+export type CommonWireMeta = {
+  pikkuFuncName: string
+
+  tags?: string[]
   summary?: string
   description?: string
-  tags?: string[]
   errors?: string[]
+
+  middleware?: MiddlewareMetadata[]
+  permissions?: PermissionMetadata[]
+}
+
+/**
+ * Serialized error for storage
+ */
+export interface SerializedError {
+  message: string
+  stack?: string
+  code?: string
+  [key: string]: any
 }

package/src/utils.ts

@@ -1,14 +1,14 @@
 import { Logger } from './services/logger.js'
 
-// TODO: SessionServices probably needs it's own type
+// TODO: WireServices probably needs it's own type
 // but is an issue for the future and will be tackled
 // with dependency injection
-export const closeSessionServices = async (
+export const closeWireServices = async (
   logger: Logger,
-  sessionServices: Record<string, any>
+  wireServices: Record<string, any>
 ) => {
   await Promise.all(
-    Object.values(sessionServices).map(async (service) => {
+    Object.values(wireServices).map(async (service) => {
       if (service?.close) {
         try {
           await service.close()

package/src/wirings/channel/channel-common.ts

@@ -1,8 +1,4 @@
-import {
-  CoreServices,
-  PikkuWiringTypes,
-  CorePikkuMiddleware,
-} from '../../types/core.types.js'
+import { CoreServices, CorePikkuMiddleware } from '../../types/core.types.js'
 import { CoreChannel, ChannelMessageMeta } from './channel.types.js'
 import { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
 import { runPikkuFuncDirectly } from '../../function/function-runner.js'
@@ -49,7 +45,7 @@ export const runChannelLifecycleWithMiddleware = async ({
 
   // Use combineMiddleware to properly resolve metadata + inline middleware
   const allMiddleware = combineMiddleware(
-    PikkuWiringTypes.channel,
+    'channel',
     `${channelConfig.name}:${lifecycleType}`,
     {
       wireInheritedMiddleware: meta.middleware,
@@ -61,7 +57,8 @@ export const runChannelLifecycleWithMiddleware = async ({
   const runLifecycle = async () => {
     return await runPikkuFuncDirectly(
       meta.pikkuFuncName,
-      { ...services, channel },
+      services,
+      { channel },
       data
     )
   }