@pikku/core 0.11.2 → 0.12.0

package/src/function/function-runner.ts

@@ -1,4 +1,8 @@
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js'
+import {
+  combineChannelMiddleware,
+  wrapChannelWithMiddleware,
+} from '../wirings/channel/channel-middleware-runner.js'
 import { runPermissions } from '../permissions.js'
 import { pikkuState } from '../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
@@ -14,12 +18,17 @@ import {
   CreateWireServices,
   CoreConfig,
 } from '../types/core.types.js'
+import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
 import {
   CorePermissionGroup,
   CorePikkuFunctionConfig,
   CorePikkuPermission,
 } from './functions.types.js'
-import { SessionService } from '../services/user-session-service.js'
+import { parseVersionedId } from '../version.js'
+import {
+  SessionService,
+  createFunctionSessionWireProps,
+} from '../services/user-session-service.js'
 import { ForbiddenError } from '../errors/errors.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
@@ -75,6 +84,30 @@ export const addFunction = (
   pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig)
 }
 
+export const getFunctionNames = (
+  packageName: string | null = null
+): string[] => {
+  const functionsMeta = pikkuState(packageName, 'function', 'meta')
+  return Object.keys(functionsMeta)
+}
+
+export const getAllFunctionNames = (): string[] => {
+  const functions: string[] = []
+
+  const mainFunctionsMeta = pikkuState(null, 'function', 'meta')
+  functions.push(...Object.keys(mainFunctionsMeta))
+
+  const externalPackages = pikkuState(null, 'rpc', 'externalPackages')
+  for (const [namespace, config] of externalPackages) {
+    const packageFunctionsMeta = pikkuState(config.package, 'function', 'meta')
+    for (const funcName of Object.keys(packageFunctionsMeta)) {
+      functions.push(`${namespace}:${funcName}`)
+    }
+  }
+
+  return functions
+}
+
 export const runPikkuFuncDirectly = async <In, Out>(
   funcName: string,
   allServices: CoreServices,
@@ -89,10 +122,9 @@ export const runPikkuFuncDirectly = async <In, Out>(
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
-  // Inject session into wire
   const wireWithSession = {
     ...wire,
-    session: userSession,
+    ...(userSession && createFunctionSessionWireProps(userSession)),
   }
   return (await funcConfig.func(allServices, data, wireWithSession)) as Out
 }
@@ -108,11 +140,14 @@ export const runPikkuFunc = async <In = any, Out = any>(
     auth: wiringAuth,
     inheritedMiddleware,
     wireMiddleware,
+    inheritedChannelMiddleware,
+    wireChannelMiddleware,
     inheritedPermissions,
     wirePermissions,
     coerceDataFromSchema,
     tags = [],
     wire,
+    sessionService,
     packageName = null,
   }: {
     singletonServices: CoreSingletonServices
@@ -121,22 +156,44 @@ export const runPikkuFunc = async <In = any, Out = any>(
     auth?: boolean
     inheritedMiddleware?: MiddlewareMetadata[]
     wireMiddleware?: CorePikkuMiddleware[]
+    inheritedChannelMiddleware?: MiddlewareMetadata[]
+    wireChannelMiddleware?: CorePikkuChannelMiddleware[]
     inheritedPermissions?: PermissionMetadata[]
     wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
     coerceDataFromSchema?: boolean
     tags?: string[]
     wire: PikkuWire
+    sessionService?: SessionService<CoreUserSession>
     packageName?: string | null
   }
 ): Promise<Out> => {
-  const funcConfig = pikkuState(packageName, 'function', 'functions').get(
-    funcName
-  )
+  wire = {
+    ...wire,
+    wireType: wire.wireType ?? wireType,
+    wireId: wire.wireId ?? wireId,
+  }
+
+  const funcMap = pikkuState(packageName, 'function', 'functions')
+  let funcConfig = funcMap.get(funcName)
+  const allMeta = pikkuState(packageName, 'function', 'meta')
+  let funcMeta = allMeta[funcName]
+
+  if (!funcConfig || !funcMeta) {
+    const { baseName, version } = parseVersionedId(funcName)
+    if (version !== null) {
+      funcConfig = funcConfig || funcMap.get(baseName)
+      funcMeta = funcMeta || allMeta[baseName]
+      if (funcConfig && funcMeta) {
+        singletonServices.logger.warn(
+          `Version '${funcName}' not registered, resolved to '${baseName}'`
+        )
+      }
+    }
+  }
+
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
-  const allMeta = pikkuState(packageName, 'function', 'meta')
-  const funcMeta = allMeta[funcName]
   if (!funcMeta) {
     throw new Error(`Function meta not found: ${funcName}`)
   }
@@ -155,6 +212,21 @@ export const runPikkuFunc = async <In = any, Out = any>(
     }
   }
 
+  const allChannelMiddleware = combineChannelMiddleware(wireType, wireId, {
+    wireInheritedChannelMiddleware: inheritedChannelMiddleware,
+    wireChannelMiddleware,
+    packageName,
+  })
+
+  const resolvedWire =
+    allChannelMiddleware.length > 0 && wire.channel
+      ? wrapChannelWithMiddleware(
+          wire,
+          resolvedSingletonServices,
+          allChannelMiddleware
+        )
+      : wire
+
   // Convert tags to PermissionMetadata and merge with inheritedPermissions
   const mergedInheritedPermissions: PermissionMetadata[] = [
     ...(inheritedPermissions || []),
@@ -163,24 +235,38 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   // Helper function to run permissions and execute the function
   const executeFunction = async () => {
-    const initialSession = wire.session?.freezeInitial()
+    const functionWireProps = sessionService
+      ? createFunctionSessionWireProps(sessionService)
+      : undefined
 
-    const wireWithInitialSession: PikkuWire = {
-      ...wire,
-      initialSession,
+    const wireWithSession: PikkuWire = {
+      ...resolvedWire,
+      ...functionWireProps,
     }
 
-    if (wiringAuth === true || funcConfig.auth === true) {
-      // This means it was explicitly enabled in either wiring or function and has to be respected
-      if (!initialSession) {
+    const session = wireWithSession.session
+
+    if (funcMeta.sessionless) {
+      if (wiringAuth === true || funcConfig.auth === true) {
+        if (!session) {
+          throw new ForbiddenError('Authentication required')
+        }
+      }
+    } else if (funcMeta.sessionless === false) {
+      if (wiringAuth === false || funcConfig.auth === false) {
+        resolvedSingletonServices.logger.warn(
+          `Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`
+        )
+      } else if (!session) {
         throw new ForbiddenError('Authentication required')
       }
-    }
-    if (wiringAuth === undefined && funcConfig.auth === undefined) {
-      // We always default to requiring auth unless explicitly disabled
-      if (!initialSession) {
-        // TODO: Critical, we need to figure out how to make this work with different wirings
-        // throw new ForbiddenError('Authentication required')
+    } else {
+      // TODO: Remove after a couple of releases — backward compat for
+      // generated metadata that doesn't include the `sessionless` field yet.
+      if (wiringAuth === true || funcConfig.auth === true) {
+        if (!session) {
+          throw new ForbiddenError('Authentication required')
+        }
       }
     }
 
@@ -210,23 +296,22 @@ export const runPikkuFunc = async <In = any, Out = any>(
       funcInheritedPermissions: funcMeta.permissions,
       funcPermissions: funcConfig.permissions,
       services: resolvedSingletonServices,
-      wire: { ...wireWithInitialSession, rpc: undefined } as any,
+      wire: { ...wireWithSession, rpc: undefined } as any,
       data: actualData,
       packageName,
     })
 
     const wireServices = await resolvedCreateWireServices?.(
       resolvedSingletonServices,
-      wireWithInitialSession
+      wireWithSession
     )
     try {
       const services = { ...resolvedSingletonServices, ...wireServices }
-      const rpc = rpcService.getContextRPCService(
-        services,
-        wireWithInitialSession
-      )
+      const rpc = rpcService.getContextRPCService(services, wireWithSession, {
+        sessionService,
+      })
       return await funcConfig.func(services, actualData, {
-        ...wireWithInitialSession,
+        ...wireWithSession,
         rpc,
       })
     } finally {
@@ -247,7 +332,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
   if (allMiddleware.length > 0) {
     return (await runMiddleware<CorePikkuMiddleware>(
       resolvedSingletonServices,
-      wire,
+      resolvedWire,
       allMiddleware,
       executeFunction
     )) as Out

package/src/function/functions.types.ts

@@ -6,7 +6,14 @@ import type {
   PikkuWire,
   PickRequired,
 } from '../types/core.types.js'
-import { Session } from 'inspector'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { CoreNodeConfig } from '../wirings/node/node.types.js'
+
+/**
+ * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
+ * This alias exists only for backward compatibility with generated code.
+ */
+export type ZodLike<T = any> = StandardSchemaV1<T, T>
 
 /**
  * Represents a core API function that performs an operation using core services and a user session.
@@ -20,6 +27,7 @@ export type CorePikkuFunction<
   In,
   Out,
   Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
   Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>,
 > = (
   services: Services,
@@ -39,15 +47,16 @@ export type CorePikkuFunctionSessionless<
   In,
   Out,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<
+  Session extends CoreUserSession = CoreUserSession,
+  Wire extends PikkuWire<In, Out, false, Session, any, any, any> = PikkuWire<
     In,
     Out,
     false,
-    CoreUserSession,
+    Session,
     any,
     any,
     any
-  > = PikkuWire<In, Out, false, CoreUserSession, any, any, any>,
+  >,
 > = (
   services: Services,
   data: In,
@@ -94,8 +103,8 @@ export type CorePikkuPermissionConfig<
 > = {
   /** The permission function */
   func: CorePikkuPermission<In, Services, Wire>
-  /** Optional human-readable title for the permission */
-  title?: string
+  /** Optional human-readable name for the permission */
+  name?: string
   /** Optional description of what the permission checks */
   description?: string
 }
@@ -108,18 +117,18 @@ export type CorePikkuPermissionConfig<
  * ```typescript
  * // Direct function syntax
  * export const adminPermission = pikkuPermission(
- *   async ({ logger }, _data, { session }) => {
- *     const currentSession = await session.get()
+ *   async ({ logger }, _data, { getSession }) => {
+ *     const currentSession = await getSession()
  *     return currentSession?.role === 'admin'
  *   }
  * )
  *
  * // Configuration object syntax with metadata
  * export const adminPermission = pikkuPermission({
- *   title: 'Admin Permission',
+ *   name: 'Admin Permission',
  *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, _data, { session }) => {
- *     const currentSession = await session.get()
+ *   func: async ({ logger }, _data, { getSession }) => {
+ *     const currentSession = await getSession()
  *     return currentSession?.role === 'admin'
  *   }
  * })
@@ -168,8 +177,8 @@ export type CorePikkuPermissionFactory<
  * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
  *   role
  * }) => {
- *   return pikkuPermission(async ({ logger }, data, { session }) => {
- *      const currentSession = await session.get()
+ *   return pikkuPermission(async ({ logger }, data, { getSession }) => {
+ *      const currentSession = await getSession()
  *     if (!currentSession || currentSession.role !== role) {
  *       logger.warn(`Permission denied: required role '${role}'`)
  *       return false
@@ -185,23 +194,45 @@ export const pikkuPermissionFactory = <In = any>(
   return factory
 }
 
+export type CorePikkuAuth<
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = (services: Services, session: Session) => Promise<boolean> | boolean
+
+export type CorePikkuAuthConfig<
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = {
+  func: CorePikkuAuth<Services, Session>
+  name?: string
+  description?: string
+}
+
+export const pikkuAuth = <
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+>(
+  auth:
+    | CorePikkuAuth<Services, Session>
+    | CorePikkuAuthConfig<Services, Session>
+): CorePikkuPermission<any, Services, any> => {
+  const fn = typeof auth === 'function' ? auth : auth.func
+  const wrapper = async (services: Services, _data: any, wire: any) => {
+    const session = wire.session
+    if (!session) return false
+    return fn(services, session as Session)
+  }
+  return wrapper as any
+}
+
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
   | Record<string, PikkuPermission | PikkuPermission[]>
   | undefined
 
-/**
- * Zod schema type - matches z.ZodType shape for type inference
- * This avoids requiring zod as a dependency while allowing schema inference
- */
-export type ZodLike<T = any> = {
-  _input: T
-  _output: T
-}
-
 export type CorePikkuFunctionConfig<
   PikkuFunction extends
-    | CorePikkuFunction<any, any, any, any>
-    | CorePikkuFunctionSessionless<any, any, any, any>,
+    | CorePikkuFunction<any, any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any, any>,
   PikkuPermission extends CorePikkuPermission<
     any,
     any,
@@ -211,126 +242,25 @@ export type CorePikkuFunctionConfig<
     any,
     any
   >,
-  InputSchema extends ZodLike | undefined = undefined,
-  OutputSchema extends ZodLike | undefined = undefined,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
 > = {
   /** Optional human-readable title for the function */
   title?: string
   /** Optional description of what the function does */
   description?: string
   override?: string
+  version?: number
   tags?: string[]
   expose?: boolean
-  internal?: boolean
+  remote?: boolean
+  mcp?: boolean
+  requiresApproval?: boolean
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>
   middleware?: PikkuMiddleware[]
   input?: InputSchema
   output?: OutputSchema
-}
-
-/**
- * A trigger function that sets up a subscription and returns a teardown function.
- * The trigger is fired via wire.trigger.trigger(data).
- *
- * @template TConfig - Configuration type (hardcoded when wired)
- * @template TOutput - Output type produced when trigger fires
- * @template Services - Services available to the trigger
- */
-export type CorePikkuTriggerFunction<
-  TConfig = unknown,
-  TOutput = unknown,
-  Services extends CoreSingletonServices = CoreSingletonServices,
-> = (
-  services: Services,
-  config: TConfig,
-  wire: { trigger: { trigger: (data: TOutput) => void } }
-) => Promise<() => void | Promise<void>>
-
-/**
- * Configuration object for creating a trigger function with metadata
- */
-export type CorePikkuTriggerFunctionConfig<
-  TConfig = unknown,
-  TOutput = unknown,
-  Services extends CoreSingletonServices = CoreSingletonServices,
-  ConfigSchema extends ZodLike | undefined = undefined,
-  OutputSchema extends ZodLike | undefined = undefined,
-> = {
-  /** Optional human-readable title for the trigger */
-  title?: string
-  /** Optional description of what the trigger does */
-  description?: string
-  /** Optional tags for categorization */
-  tags?: string[]
-  /** The trigger function */
-  func: CorePikkuTriggerFunction<TConfig, TOutput, Services>
-  /** Optional Zod schema for config validation */
-  config?: ConfigSchema
-  /** Optional Zod schema for output validation */
-  output?: OutputSchema
-}
-
-/**
- * Factory function for creating trigger functions
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const redisSubscribeTrigger = pikkuTriggerFunc<
- *   { channel: string },
- *   { message: string }
- * >(async ({ redis }, { channel }, { trigger }) => {
- *   const subscriber = redis.duplicate()
- *   await subscriber.subscribe(channel, (msg) => {
- *     trigger.trigger({ message: msg })
- *   })
- *   return () => subscriber.unsubscribe()
- * })
- *
- * // Configuration object syntax with metadata
- * export const redisSubscribeTrigger = pikkuTriggerFunc({
- *   title: 'Redis Subscribe Trigger',
- *   description: 'Listens to Redis pub/sub channel',
- *   config: z.object({ channel: z.string() }),
- *   output: z.object({ message: z.string() }),
- *   func: async ({ redis }, { channel }, { trigger }) => {
- *     const subscriber = redis.duplicate()
- *     await subscriber.subscribe(channel, (msg) => {
- *       trigger.trigger({ message: msg })
- *     })
- *     return () => subscriber.unsubscribe()
- *   }
- * })
- * ```
- */
-export const pikkuTriggerFunc = <
-  TConfig = unknown,
-  TOutput = unknown,
-  Services extends CoreSingletonServices = CoreSingletonServices,
-  ConfigSchema extends ZodLike | undefined = undefined,
-  OutputSchema extends ZodLike | undefined = undefined,
->(
-  triggerOrConfig:
-    | CorePikkuTriggerFunction<TConfig, TOutput, Services>
-    | CorePikkuTriggerFunctionConfig<
-        TConfig,
-        TOutput,
-        Services,
-        ConfigSchema,
-        OutputSchema
-      >
-): CorePikkuTriggerFunctionConfig<
-  TConfig,
-  TOutput,
-  Services,
-  ConfigSchema,
-  OutputSchema
-> => {
-  if (typeof triggerOrConfig === 'function') {
-    return { func: triggerOrConfig }
-  }
-  return triggerOrConfig
+  node?: CoreNodeConfig
 }

package/src/function/index.ts

@@ -1,2 +1,5 @@
-export * from './function-runner.js'
-export * from './functions.types.js'
+export { addFunction, getAllFunctionNames } from './function-runner.js'
+export type {
+  CorePikkuFunction,
+  CorePikkuFunctionSessionless,
+} from './functions.types.js'

package/src/handle-error.ts

@@ -57,17 +57,9 @@ export const handleHTTPError = (
     }
   }
 
-  // Handle 404 errors specifically
-  if (e instanceof NotFoundError) {
-    // TODO
-    // http?.response?.end()
-  }
-
-  // Either bubble up or end the response
   if (bubbleError) {
     throw e
-  } else {
-    // TODO
-    // http?.response?.end()
   }
+
+  http?.response?.close?.()
 }

package/src/index.ts

@@ -1,37 +1,111 @@
 /**
  * @module @pikku/core
  */
-export * from './types/core.types.js'
-export * from './function/index.js'
-export * from './pikku-request.js'
-export * from './pikku-response.js'
-export * from './services/logger.js'
-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/workflow/graph/index.js'
-export * from './wirings/mcp/index.js'
-export * from './wirings/cli/index.js'
-export * from './wirings/forge-node/index.js'
-export * from './wirings/trigger/index.js'
-export * from './errors/index.js'
-export * from './middleware/index.js'
-export * from './utils.js'
-export * from './time-utils.js'
+export type {
+  CommonWireMeta,
+  CoreConfig,
+  CorePikkuMiddleware,
+  CorePikkuMiddlewareConfig,
+  CorePikkuMiddlewareFactory,
+  CorePikkuMiddlewareGroup,
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateConfig,
+  CreateSingletonServices,
+  CreateWireServices,
+  FunctionMeta,
+  FunctionRuntimeMeta,
+  FunctionServicesMeta,
+  FunctionWiresMeta,
+  FunctionsMeta,
+  FunctionsRuntimeMeta,
+  JSONPrimitive,
+  JSONValue,
+  MakeRequired,
+  MiddlewareMetadata,
+  PermissionMetadata,
+  PickOptional,
+  PickRequired,
+  PikkuAIMiddlewareHooks,
+  PikkuWire,
+  PikkuWiringTypes,
+  RequireAtLeastOne,
+  SerializedError,
+  WireServices,
+} from './types/core.types.js'
+export {
+  pikkuAIMiddleware,
+  pikkuChannelMiddleware,
+  pikkuChannelMiddlewareFactory,
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './types/core.types.js'
+export type {
+  CorePikkuAuth,
+  CorePikkuAuthConfig,
+  CorePikkuFunction,
+  CorePikkuFunctionConfig,
+  CorePikkuPermission,
+  CorePikkuPermissionConfig,
+  CorePikkuPermissionFactory,
+  CorePermissionGroup,
+  ZodLike,
+} from './function/functions.types.js'
+export {
+  pikkuAuth,
+  pikkuPermission,
+  pikkuPermissionFactory,
+} from './function/functions.types.js'
+export { addFunction, getAllFunctionNames } from './function/index.js'
+export { PikkuRequest } from './pikku-request.js'
+export {
+  getRelativeTimeOffsetFromNow,
+  parseDurationString,
+} from './time-utils.js'
+export type { RelativeTimeInput } from './time-utils.js'
+export {
+  formatVersionedId,
+  isVersionedId,
+  parseVersionedId,
+} from './version.js'
 export {
   pikkuState,
   initializePikkuState,
   resetPikkuState,
   addPackageServiceFactories,
+  getPikkuMetaDir,
 } from './pikku-state.js'
+export { runPikkuFunc } from './function/function-runner.js'
+export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js'
+export { fetch } from './wirings/http/http-runner.js'
+export {
+  runMCPTool,
+  runMCPResource,
+  runMCPPrompt,
+} from './wirings/mcp/mcp-runner.js'
+export type {
+  MCPToolResponse,
+  MCPResourceResponse,
+  MCPPromptResponse,
+} from './wirings/mcp/mcp.types.js'
+export { runQueueJob } from './wirings/queue/queue-runner.js'
+export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js'
+export { NotFoundError } from './errors/errors.js'
+export type { EventHubService } from './wirings/channel/eventhub-service.js'
+export type { QueueService } from './wirings/queue/queue.types.js'
+export type { JWTService } from './services/jwt-service.js'
+export type { HTTPMethod } from './wirings/http/http.types.js'
+export type { GraphNodeConfig } from './wirings/workflow/graph/workflow-graph.types.js'
+export { createGraph } from './wirings/workflow/graph/graph-node.js'
+export { workflow as wireWorkflow } from './wirings/workflow/workflow-helpers.js'
 export type { PikkuPackageState } from './types/state.types.js'
 export { runMiddleware, addMiddleware } from './middleware-runner.js'
 export { addPermission } from './permissions.js'
+export { isSerializable, stopSingletonServices } from './utils.js'
+export {
+  type ScheduledTaskInfo,
+  type ScheduledTaskSummary,
+  type SchedulerRuntimeHandlers,
+} from './services/scheduler-service.js'
+export { SchedulerService } from './services/scheduler-service.js'