@pikku/core 0.12.4 → 0.12.5

package/src/time-utils.test.ts

@@ -0,0 +1,56 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { RelativeTimeInput } from './time-utils'
+import {
+  getRelativeTimeOffset,
+  getRelativeTimeOffsetFromNow,
+} from './time-utils'
+
+const approxEqual = (a: number, b: number, delta: number = 10): boolean =>
+  Math.abs(a - b) <= delta
+
+describe('Time Utils', () => {
+  const offsetCases: Array<{ input: RelativeTimeInput; expected: number }> = [
+    { input: { value: 1, unit: 'second' }, expected: 1000 },
+    { input: { value: 2, unit: 'minute' }, expected: 120000 },
+    { input: { value: 1.5, unit: 'hour' }, expected: 5400000 },
+    { input: { value: -1, unit: 'day' }, expected: -86400000 },
+    { input: { value: 1, unit: 'week' }, expected: 604800000 },
+    {
+      input: { value: 2, unit: 'year' },
+      expected: Math.round(2 * 365.25 * 86400 * 1000),
+    },
+  ]
+
+  describe('getRelativeTimeOffset', () => {
+    for (const { input, expected } of offsetCases) {
+      test(`returns ${expected} ms for ${input.value} ${input.unit}`, () => {
+        const actual = getRelativeTimeOffset(input)
+        assert.strictEqual(actual, expected)
+      })
+    }
+  })
+
+  describe('getRelativeTimeOffsetFromNow', () => {
+    test('returns a Date ~1 minute in the future', () => {
+      const now = Date.now()
+      const result = getRelativeTimeOffsetFromNow({ value: 1, unit: 'minute' })
+      const delta = result.getTime() - now
+      assert.ok(
+        approxEqual(delta, 60000),
+        `Expected ~60000ms ahead, got ${delta}ms`
+      )
+    })
+
+    test('returns a Date ~2 hours in the past', () => {
+      const now = Date.now()
+      const result = getRelativeTimeOffsetFromNow({ value: -2, unit: 'hour' })
+      const delta = now - result.getTime()
+      assert.ok(
+        approxEqual(delta, 7200000),
+        `Expected ~7200000ms ago, got ${delta}ms`
+      )
+    })
+  })
+})

package/src/time-utils.ts

@@ -0,0 +1,107 @@
+type TimeUnit = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'year'
+
+export interface RelativeTimeInput {
+  value: number // negative = in the past
+  unit: TimeUnit
+}
+
+const multipliers: Record<TimeUnit, number> = {
+  second: 1,
+  minute: 60,
+  hour: 60 * 60,
+  day: 60 * 60 * 24,
+  week: 60 * 60 * 24 * 7,
+  year: Math.round(365.25 * 60 * 60 * 24),
+}
+
+export const getRelativeTimeOffset = ({
+  value,
+  unit,
+}: RelativeTimeInput): number => {
+  return Math.round(value * multipliers[unit]) * 1000 // convert to milliseconds
+}
+
+/**
+ * Returns a Unix timestamp (in seconds) offset from now by the given duration.
+ * e.g. value = -1 and unit = 'day' => 1 day ago => now - 86400 seconds
+ */
+export const getRelativeTimeOffsetFromNow = (
+  relativeTime: RelativeTimeInput
+): 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

@@ -0,0 +1,478 @@
+import type { Logger, LogLevel } from '../services/logger.js'
+import type { VariablesService } from '../services/variables-service.js'
+import type { SecretService } from '../services/secret-service.js'
+import type { SchemaService } from '../services/schema-service.js'
+import type { JWTService } from '../services/jwt-service.js'
+import type { PikkuHTTP } from '../wirings/http/http.types.js'
+import type {
+  PikkuChannel,
+  CorePikkuChannelMiddleware,
+  CorePikkuChannelMiddlewareFactory,
+} from '../wirings/channel/channel.types.js'
+import type { PikkuRPC } from '../wirings/rpc/rpc-types.js'
+import type { PikkuMCP } from '../wirings/mcp/mcp.types.js'
+import type { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
+import type { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js'
+import type { PikkuCLI } from '../wirings/cli/cli.types.js'
+import type {
+  PikkuWorkflowWire,
+  WorkflowService,
+  WorkflowServiceConfig,
+  WorkflowStepWire,
+} from '../wirings/workflow/workflow.types.js'
+import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js'
+import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js'
+import type { PikkuGateway } from '../wirings/gateway/gateway.types.js'
+import type { SchedulerService } from '../services/scheduler-service.js'
+import type { DeploymentService } from '../services/deployment-service.js'
+import type { AIStorageService } from '../services/ai-storage-service.js'
+
+import type { ContentService } from '../services/content-service.js'
+import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js'
+import type { AIRunStateService } from '../services/ai-run-state-service.js'
+import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js'
+import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
+import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
+
+export type PikkuWiringTypes =
+  | 'http'
+  | 'scheduler'
+  | 'trigger'
+  | 'channel'
+  | 'rpc'
+  | 'queue'
+  | 'mcp'
+  | 'cli'
+  | 'workflow'
+  | 'agent'
+  | 'gateway'
+
+export interface FunctionServicesMeta {
+  optimized: boolean
+  services: string[]
+}
+
+export interface FunctionWiresMeta {
+  optimized: boolean
+  wires: string[]
+}
+
+/**
+ * Metadata for middleware at any level
+ * - type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)
+ * - type: 'tag' = Tag-based middleware group (references tagGroup in pikkuState)
+ * - type: 'wire' = Wire-level individual middleware
+ */
+export type MiddlewareMetadata =
+  | {
+      type: 'http'
+      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
+    }
+  | {
+      type: 'tag'
+      tag: string // Tag name
+    }
+  | {
+      type: 'wire'
+      name: string
+      inline?: boolean // true if inline middleware
+    }
+
+/**
+ * Metadata for permissions at any level
+ * - type: 'http' = HTTP route permission group (references httpGroup in pikkuState)
+ * - type: 'tag' = Tag-based permission group (references tagGroup in pikkuState)
+ * - type: 'wire' = Wire-level individual permission
+ */
+export type PermissionMetadata =
+  | {
+      type: 'http'
+      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
+    }
+  | {
+      type: 'tag'
+      tag: string // Tag name
+    }
+  | {
+      type: 'wire'
+      name: string
+      inline?: boolean // true if inline permission
+    }
+
+export type FunctionRuntimeMeta = {
+  pikkuFuncId: string
+  inputSchemaName: string | null
+  outputSchemaName: string | null
+  expose?: boolean
+  remote?: boolean
+  mcp?: boolean
+  readonly?: boolean
+  sessionless?: boolean
+  version?: number
+  approvalRequired?: boolean
+  approvalDescription?: string
+  contractHash?: string
+  inputHash?: string
+  outputHash?: string
+}
+
+export type FunctionMeta = FunctionRuntimeMeta &
+  Partial<
+    {
+      name: string
+      functionType: 'user' | 'inline' | 'helper'
+      funcWrapper: string
+      services: FunctionServicesMeta
+      wires: FunctionWiresMeta
+      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>
+
+// Optimized runtime metadata with only essential fields
+
+export type MakeRequired<T, K extends keyof T> = Omit<T, K> &
+  Required<Pick<T, K>>
+
+/**
+ * Represents a JSON primitive type which can be a string, number, boolean, null, or undefined.
+ */
+export type JSONPrimitive = string | number | boolean | null | undefined
+
+/**
+ * Represents a JSON value which can be a primitive, an array, or an object.
+ */
+export type JSONValue =
+  | JSONPrimitive
+  | JSONValue[]
+  | {
+      [key: string]: JSONValue
+    }
+
+/**
+ * Utility type for making certain keys required and leaving the rest as optional.
+ */
+export type PickRequired<T, K extends keyof T> = Required<Pick<T, K>> &
+  Partial<T>
+
+/**
+ * Utility type for making certain keys optional while keeping the rest required.
+ */
+export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>
+
+/**
+ * Utility type that ensures at least one key in the given type `T` is required.
+ */
+export type RequireAtLeastOne<T> = {
+  [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
+}[keyof T]
+
+/**
+ * Interface for the core configuration settings of Pikku.
+ */
+export type CoreConfig<Config extends Record<string, unknown> = {}> = {
+  /** The log level for the application. */
+  logLevel?: LogLevel
+  /** Secrets used by the application (optional). */
+  secrets?: {}
+
+  workflow?: WorkflowServiceConfig
+} & Config
+
+/**
+ * Represents a core user session, which can be extended for more specific session information.
+ */
+export interface CoreUserSession {}
+
+/**
+ * Interface for core singleton services provided by Pikku.
+ */
+export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
+  /** The schema library used to validate data */
+  schema?: SchemaService
+  /** The JWT service used to encode and decode tokens */
+  jwt?: JWTService
+  /** The core configuration for the application. */
+  config: Config
+  /** The logger used by the application. */
+  logger: Logger
+  /** The variable service to be used */
+  variables: VariablesService
+  /** The secrets service to retrieve secrets */
+  secrets: SecretService
+  /** The workflow orchestrator service */
+  workflowService?: WorkflowService
+  /** The queue service */
+  queueService?: QueueService
+  /** The scheduler service */
+  schedulerService?: SchedulerService
+  /** The deployment service for service discovery */
+  deploymentService?: DeploymentService
+  /** AI agent storage service (threads, messages, working memory) */
+  aiStorage?: AIStorageService
+
+  /** Content service for file storage and retrieval */
+  content?: ContentService
+  /** AI agent runner service (model calls + tool loop) */
+  aiAgentRunner?: AIAgentRunnerService
+  /** AI run state service (run lifecycle + approval persistence) */
+  aiRunState?: AIRunStateService
+  /** Agent run service (listing threads, runs, steps) */
+  agentRunService?: AgentRunService
+  /** Workflow run service (listing workflow runs) */
+  workflowRunService?: WorkflowRunService
+}
+
+/**
+ * Represents different forms of wire within Pikku and the outside world.
+ */
+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,
+  TriggerOutput = unknown,
+> = Partial<{
+  wireType: PikkuWiringTypes
+  wireId: string
+  http: PikkuHTTP<In>
+  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
+  graph: PikkuGraphWire
+  trigger: PikkuTrigger<TriggerOutput>
+  gateway: PikkuGateway
+  session: HasInitialSession extends true
+    ? UserSession
+    : UserSession | undefined
+  /** Update and persist the current session */
+  setSession: (session: CoreUserSession) => Promise<void> | void
+  /** Clear and persist the current session */
+  clearSession: () => Promise<void> | void
+  /** Fetch the latest session (may read from backing store) */
+  getSession: () => Promise<UserSession> | UserSession | undefined
+  /** Whether the session was modified during this run */
+  hasSessionChanged: () => boolean
+}>
+
+/**
+ * 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,
+  wires: PikkuWire<unknown, unknown, false, UserSession>,
+  next: () => Promise<void>
+) => Promise<void>
+
+/**
+ * Configuration object for creating middleware with metadata
+ *
+ * @template SingletonServices - The singleton services type
+ * @template UserSession - The user session type
+ */
+export type CorePikkuMiddlewareConfig<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = {
+  /** The middleware function */
+  func: CorePikkuMiddleware<SingletonServices, UserSession>
+  /** Optional human-readable name for the middleware */
+  name?: string
+  /** Optional description of what the middleware does */
+  description?: string
+}
+
+/**
+ * A factory function that takes input and returns middleware
+ * Used when middleware needs configuration/input parameters
+ */
+export type CorePikkuMiddlewareFactory<
+  In = any,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>
+
+/**
+ * A group of middleware (combination of regular middleware and factories)
+ * Used with addMiddleware() and addHTTPMiddleware() to group related middleware together
+ */
+export type CorePikkuMiddlewareGroup<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = Array<
+  | CorePikkuMiddleware<SingletonServices, UserSession>
+  | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>
+>
+
+/**
+ * Factory function for creating middleware with tree-shaking support
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const logMiddleware = pikkuMiddleware(
+ *   async ({ logger }, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * )
+ *
+ * // Configuration object syntax with metadata
+ * export const logMiddleware = pikkuMiddleware({
+ *   name: 'Request Logger',
+ *   description: 'Logs request information',
+ *   func: async ({ logger }, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * })
+ * ```
+ */
+export const pikkuMiddleware = <
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+>(
+  middleware:
+    | CorePikkuMiddleware<SingletonServices, UserSession>
+    | CorePikkuMiddlewareConfig<SingletonServices, UserSession>
+): CorePikkuMiddleware<SingletonServices, UserSession> => {
+  return typeof middleware === 'function' ? middleware : middleware.func
+}
+
+/**
+ * Factory function for creating middleware factories
+ * Use this when your middleware needs configuration/input parameters
+ *
+ * @example
+ * ```typescript
+ * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
+ *   message,
+ *   level = 'info'
+ * }) => {
+ *   return pikkuMiddleware(async ({ logger }, next) => {
+ *     logger[level](message)
+ *     await next()
+ *   })
+ * })
+ * ```
+ */
+export const pikkuMiddlewareFactory = <In = any>(
+  factory: CorePikkuMiddlewareFactory<In>
+): CorePikkuMiddlewareFactory<In> => {
+  return factory
+}
+
+export const pikkuChannelMiddleware = <
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  Event = unknown,
+>(
+  middleware: CorePikkuChannelMiddleware<SingletonServices, Event>
+): CorePikkuChannelMiddleware<SingletonServices, Event> => {
+  return middleware
+}
+
+export const pikkuChannelMiddlewareFactory = <In = any>(
+  factory: CorePikkuChannelMiddlewareFactory<In>
+): CorePikkuChannelMiddlewareFactory<In> => {
+  return factory
+}
+
+export type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
+
+export const pikkuAIMiddleware = <
+  State extends Record<string, unknown> = Record<string, unknown>,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+>(
+  hooks: PikkuAIMiddlewareHooks<State, SingletonServices>
+): PikkuAIMiddlewareHooks<State, SingletonServices> => hooks
+
+/**
+ * Represents the core services used by Pikku, including singleton services.
+ */
+export type CoreServices<SingletonServices = CoreSingletonServices> =
+  SingletonServices
+
+export type WireServices<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  Services = CoreServices<SingletonServices>,
+> = Omit<Services, keyof SingletonServices | 'session'>
+
+/**
+ * Defines a function type for creating singleton services from the given configuration.
+ */
+export type CreateSingletonServices<
+  Config extends CoreConfig,
+  SingletonServices extends CoreSingletonServices,
+> = (
+  config: Config,
+  existingServices?: Partial<SingletonServices>
+) => Promise<SingletonServices>
+
+/**
+ * Defines a function type for creating session-specific services.
+ */
+export type CreateWireServices<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  Services extends
+    CoreServices<SingletonServices> = CoreServices<SingletonServices>,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (
+  services: SingletonServices,
+  wire: PikkuWire<unknown, unknown, false, UserSession>
+) => Promise<WireServices<Services, SingletonServices>>
+
+/**
+ * Defines a function type for creating config.
+ */
+export type CreateConfig<
+  Config extends CoreConfig,
+  RemainingArgs extends any[] = unknown[],
+> = (variables?: VariablesService, ...args: RemainingArgs) => Promise<Config>
+
+/**
+ * Represents the documentation for a route, including summary, description, tags, and errors.
+ */
+export type CommonWireMeta = {
+  pikkuFuncId: string
+  packageName?: string
+
+  title?: string
+  tags?: string[]
+  summary?: string
+  description?: string
+  errors?: string[]
+
+  middleware?: MiddlewareMetadata[]
+  permissions?: PermissionMetadata[]
+}
+
+/**
+ * Serialized error for storage
+ */
+export interface SerializedError {
+  message: string
+  stack?: string
+  code?: string
+  [key: string]: any
+}