@pikku/core 0.11.0 → 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,14 +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]: {},
-  [PikkuWiringTypes.workflow]: {},
+  http: {},
+  rpc: {},
+  channel: {},
+  queue: {},
+  scheduler: {},
+  mcp: {},
+  cli: {},
+  workflow: {},
 }
 
 /**
@@ -335,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
@@ -362,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
@@ -372,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/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/types/core.types.ts

@@ -3,7 +3,7 @@ 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'
@@ -11,23 +11,22 @@ import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
 import { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js'
 import { PikkuCLI } from '../wirings/cli/cli.types.js'
 import {
-  PikkuWorkflowInteraction,
+  PikkuWorkflowWire,
   WorkflowService,
   WorkflowServiceConfig,
-  WorkflowStepInteraction,
+  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',
-  workflow = 'workflow',
-}
+export type PikkuWiringTypes =
+  | 'http'
+  | 'scheduler'
+  | 'channel'
+  | 'rpc'
+  | 'queue'
+  | 'mcp'
+  | 'cli'
+  | 'workflow'
 
 export interface FunctionServicesMeta {
   optimized: boolean
@@ -85,17 +84,18 @@ export type FunctionRuntimeMeta = {
 }
 
 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>
@@ -178,31 +178,44 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
 }
 
 /**
- * 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: PikkuWorkflowInteraction
-  workflowStep: WorkflowStepInteraction
+  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>
 
@@ -254,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()
  *   }
@@ -264,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()
  *   }
@@ -292,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()
  *   })
@@ -306,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.
@@ -335,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.
@@ -357,11 +364,16 @@ 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[]
 }
 
 /**

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
     )
   }

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

@@ -2,7 +2,6 @@ import {
   CoreServices,
   JSONValue,
   CoreUserSession,
-  PikkuWiringTypes,
 } from '../../types/core.types.js'
 import {
   ChannelMessageMeta,
@@ -11,6 +10,7 @@ import {
 } from './channel.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
+import { SessionService } from '../../services/user-session-service.js'
 
 const getRouteMeta = (
   channelName: string,
@@ -62,7 +62,8 @@ const validateAuth = (
 export const processMessageHandlers = (
   services: CoreServices,
   channelConfig: CoreChannel<any, any>,
-  channelHandler: PikkuChannelHandler
+  channelHandler: PikkuChannelHandler,
+  userSession?: SessionService<CoreUserSession>
 ) => {
   const logger = services.logger
   const requiresSession = channelConfig.auth !== false
@@ -121,26 +122,19 @@ export const processMessageHandlers = (
       ? `${channelConfig.name}:${routingProperty}:${routerValue}`
       : `${channelConfig.name}:default`
 
-    return await runPikkuFunc(
-      PikkuWiringTypes.channel,
-      cacheKey,
-      pikkuFuncName,
-      {
-        singletonServices: services,
-        getAllServices: () => ({
-          ...services,
-          channel: channelHandler.getChannel(),
-        }),
-        data: () => data,
-        userSession: services.userSession,
-        inheritedMiddleware,
-        wireMiddleware,
-        inheritedPermissions,
-        wirePermissions,
-        tags: channelConfig.tags,
-        interaction: { channel: channelHandler.getChannel() },
-      }
-    )
+    return await runPikkuFunc('channel', cacheKey, pikkuFuncName, {
+      singletonServices: services,
+      data: () => data,
+      inheritedMiddleware,
+      wireMiddleware,
+      inheritedPermissions,
+      wirePermissions,
+      tags: channelConfig.tags,
+      wire: {
+        channel: channelHandler.getChannel(),
+        session: userSession,
+      },
+    })
   }
 
   return async (rawData): Promise<unknown> => {

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

@@ -3,7 +3,7 @@ import { addFunction } from '../../function/function-runner.js'
 import { CorePikkuPermission } from '../../function/functions.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
-import { UserSessionService } from '../../services/user-session-service.js'
+import { SessionService } from '../../services/user-session-service.js'
 import { CorePikkuMiddleware } from '../../types/core.types.js'
 import { httpRouter } from '../http/routers/http-router.js'
 import {
@@ -128,7 +128,7 @@ export const openChannel = async ({
   request,
 }: Pick<CoreChannel<unknown, string>, 'route'> &
   RunChannelParams<unknown> & {
-    userSession: UserSessionService<any>
+    userSession: SessionService<any>
   } & RunChannelOptions): Promise<{
   openingData: unknown
   channelConfig: CoreChannel<unknown, any>

package/src/wirings/channel/channel.types.ts

@@ -5,9 +5,8 @@ import {
   PikkuHTTPResponse,
 } from '../http/http.types.js'
 import {
-  PikkuDocs,
   CoreSingletonServices,
-  CreateSessionServices,
+  CreateWireServices,
   CorePikkuMiddleware,
   MiddlewareMetadata,
   PermissionMetadata,
@@ -33,12 +32,15 @@ export type RunChannelParams<ChannelData> = {
   singletonServices: CoreSingletonServices
   request?: PikkuHTTPRequest<ChannelData>
   response?: PikkuHTTPResponse
-  createSessionServices?: CreateSessionServices
+  createWireServices?: CreateWireServices
 }
 
 export interface ChannelMessageMeta {
   pikkuFuncName: string
-  docs?: PikkuDocs
+  summary?: string
+  description?: string
+  errors?: string[]
+  tags?: string[]
   middleware?: MiddlewareMetadata[]
   permissions?: PermissionMetadata[]
 }
@@ -54,7 +56,9 @@ export interface ChannelMeta {
   disconnect: ChannelMessageMeta | null
   message: ChannelMessageMeta | null
   messageWirings: Record<string, Record<string, ChannelMessageMeta>>
-  docs?: PikkuDocs
+  summary?: string
+  description?: string
+  errors?: string[]
   tags?: string[]
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
   permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
@@ -66,20 +70,19 @@ export type CoreChannel<
   ChannelData,
   Channel extends string,
   ChannelConnect = CorePikkuFunctionConfig<
-    | CorePikkuFunction<void, unknown, ChannelData>
-    | CorePikkuFunctionSessionless<void, unknown, ChannelData>,
+    | CorePikkuFunction<void, unknown>
+    | CorePikkuFunctionSessionless<void, unknown>,
     CorePikkuPermission<void>,
     CorePikkuMiddleware
   >,
   ChannelDisconnect = CorePikkuFunctionConfig<
-    | CorePikkuFunction<void, void, ChannelData>
-    | CorePikkuFunctionSessionless<void, void, ChannelData>,
+    CorePikkuFunction<void, void> | CorePikkuFunctionSessionless<void, void>,
     CorePikkuPermission<void>,
     CorePikkuMiddleware
   >,
   ChannelFunctionMessage = CorePikkuFunctionConfig<
-    | CorePikkuFunction<unknown, unknown, ChannelData>
-    | CorePikkuFunctionSessionless<unknown, unknown, ChannelData>,
+    | CorePikkuFunction<unknown, unknown>
+    | CorePikkuFunctionSessionless<unknown, unknown>,
     CorePikkuPermission<unknown>,
     CorePikkuMiddleware
   >,

package/src/wirings/channel/local/local-channel-runner.test.ts

@@ -95,7 +95,9 @@ export class PikkuMockResponse implements PikkuHTTPResponse {
   }
 }
 
-const mockCreateSessionServices = async () => ({ sessionServiceMock: true })
+const mockCreateWireServices = async () => ({
+  wireServiceMock: true,
+})
 
 beforeEach(() => {
   resetPikkuState()
@@ -113,7 +115,7 @@ test('runChannel should return undefined and 404 if no matching channel is found
     channelId: 'test-channel-id',
     request: new PikkuMockRequest('/non-existent-channel', 'get'),
     response: mockResponse,
-    createSessionServices: mockCreateSessionServices,
+    createWireServices: mockCreateWireServices,
   })
 
   assert.equal(
@@ -149,7 +151,7 @@ test('runChannel should return a channel handler if channel matches and no auth
     request: new PikkuMockRequest('/test-channel', 'get'),
     response: new PikkuMockResponse(),
     route: '/test-channel',
-    createSessionServices: mockCreateSessionServices,
+    createWireServices: mockCreateWireServices,
   })
 
   assert.ok(result, 'Should return a PikkuChannelHandler instance')