@pikku/core 0.10.2 → 0.11.1

package/src/function/functions.types.ts

@@ -1,67 +1,58 @@
-import { PikkuChannel } from '../wirings/channel/channel.types.js'
 import type {
   CoreServices,
   CoreSingletonServices,
   CoreUserSession,
-  PikkuDocs,
   CorePikkuMiddleware,
+  PikkuWire,
+  PickRequired,
 } from '../types/core.types.js'
+import { Session } from 'inspector'
 
 /**
  * Represents a core API function that performs an operation using core services and a user session.
  *
  * @template In - The input type.
  * @template Out - The output type.
- * @template ChannelData - The channel data type.
  * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
+ * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
  */
 export type CorePikkuFunction<
   In,
   Out,
-  ChannelData extends unknown | null = null,
-  Services extends CoreSingletonServices = CoreServices &
-    (ChannelData extends null
-      ? {
-          channel?: PikkuChannel<unknown, Out> | undefined
-        }
-      : {
-          channel: PikkuChannel<ChannelData, Out>
-        }),
-  Session extends CoreUserSession = CoreUserSession,
+  Services extends CoreSingletonServices = CoreServices,
+  Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>,
 > = (
   services: Services,
   data: In,
-  session: Session
-) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>
+  wire: Wire
+) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
 
 /**
  * Represents a core API function that can be used without a session.
  *
  * @template In - The input type.
  * @template Out - The output type.
- * @template ChannelData - The channel data type.
  * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
+ * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
  */
 export type CorePikkuFunctionSessionless<
   In,
   Out,
-  ChannelData extends unknown | null = null,
-  Services extends CoreSingletonServices = CoreServices &
-    (ChannelData extends null
-      ? {
-          channel?: PikkuChannel<unknown, Out> | undefined
-        }
-      : {
-          channel: PikkuChannel<ChannelData, Out>
-        }),
-  Session extends CoreUserSession = CoreUserSession,
+  Services extends CoreSingletonServices = CoreServices,
+  Wire extends PikkuWire<
+    In,
+    Out,
+    false,
+    CoreUserSession,
+    any,
+    any,
+    any
+  > = PikkuWire<In, Out, false, CoreUserSession, any, any, any>,
 > = (
   services: Services,
   data: In,
-  session?: Session
-) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>
+  wire: Wire
+) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
 
 /**
  * Represents a function that checks permissions for a given operation.
@@ -73,8 +64,16 @@ export type CorePikkuFunctionSessionless<
 export type CorePikkuPermission<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-> = (services: Services, data: In, session?: Session) => Promise<boolean>
+  Wire extends PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession,
+    any,
+    never,
+    never
+  > = PikkuWire<In, never, false, CoreUserSession, never, never, never>,
+> = (services: Services, data: In, wire: Wire) => Promise<boolean>
 
 /**
  * Configuration object for creating a permission with metadata
@@ -86,10 +85,15 @@ export type CorePikkuPermission<
 export type CorePikkuPermissionConfig<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
+  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession
+  >,
 > = {
   /** The permission function */
-  func: CorePikkuPermission<In, Services, Session>
+  func: CorePikkuPermission<In, Services, Wire>
   /** Optional human-readable name for the permission */
   name?: string
   /** Optional description of what the permission checks */
@@ -104,8 +108,9 @@ export type CorePikkuPermissionConfig<
  * ```typescript
  * // Direct function syntax
  * export const adminPermission = pikkuPermission(
- *   async ({ logger }, data, session) => {
- *     return session?.role === 'admin'
+ *   async ({ logger }, _data, { session }) => {
+ *     const currentSession = await session.get()
+ *     return currentSession?.role === 'admin'
  *   }
  * )
  *
@@ -113,8 +118,9 @@ export type CorePikkuPermissionConfig<
  * export const adminPermission = pikkuPermission({
  *   name: 'Admin Permission',
  *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, data, session) => {
- *     return session?.role === 'admin'
+ *   func: async ({ logger }, _data, { session }) => {
+ *     const currentSession = await session.get()
+ *     return currentSession?.role === 'admin'
  *   }
  * })
  * ```
@@ -122,12 +128,15 @@ export type CorePikkuPermissionConfig<
 export const pikkuPermission = <
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
+  Wire extends PickRequired<
+    PikkuWire<In, never, false, CoreUserSession>,
+    'session'
+  > = PickRequired<PikkuWire<In, never, false, CoreUserSession>, 'session'>,
 >(
   permission:
-    | CorePikkuPermission<In, Services, Session>
-    | CorePikkuPermissionConfig<In, Services, Session>
-): CorePikkuPermission<In, Services, Session> => {
+    | CorePikkuPermission<In, Services, Wire>
+    | CorePikkuPermissionConfig<In, Services, Wire>
+): CorePikkuPermission<In, Services, Wire> => {
   return typeof permission === 'function' ? permission : permission.func
 }
 
@@ -142,8 +151,13 @@ export const pikkuPermission = <
 export type CorePikkuPermissionFactory<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-> = (input: In) => CorePikkuPermission<any, Services, Session>
+  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession
+  >,
+> = (input: In) => CorePikkuPermission<any, Services, Wire>
 
 /**
  * Factory function for creating permission factories
@@ -154,8 +168,9 @@ export type CorePikkuPermissionFactory<
  * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
  *   role
  * }) => {
- *   return pikkuPermission(async ({ logger }, data, session) => {
- *     if (!session || session.role !== role) {
+ *   return pikkuPermission(async ({ logger }, data, { session }) => {
+ *      const currentSession = await session.get()
+ *     if (!currentSession || currentSession.role !== role) {
  *       logger.warn(`Permission denied: required role '${role}'`)
  *       return false
  *     }
@@ -176,21 +191,24 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
 
 export type CorePikkuFunctionConfig<
   PikkuFunction extends
-    | CorePikkuFunction<any, any, any, any, any>
-    | CorePikkuFunctionSessionless<any, any, any, any, any>,
+    | CorePikkuFunction<any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any>,
   PikkuPermission extends CorePikkuPermission<
     any,
     any,
     any
   > = CorePikkuPermission<any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
 > = {
   name?: string
+  tags?: string[]
   expose?: boolean
+  internal?: boolean
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>
   middleware?: PikkuMiddleware[]
-  tags?: string[]
-  docs?: PikkuDocs
 }

package/src/handle-error.ts

@@ -7,7 +7,7 @@ import { PikkuHTTP } from './wirings/http/http.types.js'
  * Handle errors that occur during route processing
  *
  * @param {any} e - The error that occurred
- * @param {PikkuHTTP | undefined} http - HTTP interaction object
+ * @param {PikkuHTTP | undefined} http - HTTP wire object
  * @param {string} trackerId - Unique ID for tracking this error
  * @param {Logger} logger - Logger service
  * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings

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/auth-apikey.test.ts

@@ -0,0 +1,360 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { authAPIKey } from './auth-apikey.js'
+import { resetPikkuState } from '../pikku-state.js'
+import { CoreUserSession } from '../types/core.types.js'
+import { PikkuSessionService } from '../services/user-session-service.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const createMockHTTPRequest = (
+  headers: Record<string, string> = {},
+  query: Record<string, string> = {}
+) => ({
+  header: (name: string) => headers[name.toLowerCase()] || null,
+  query: () => query,
+})
+
+const createMockHTTPResponse = () => ({
+  cookie: () => {},
+})
+
+describe('authAPIKey middleware', () => {
+  test('should extract API key from x-api-key header when source is "header"', async () => {
+    const mockUserSession: CoreUserSession = { userId: 'user123' }
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async (token: string) => {
+        assert.equal(token, 'my-api-key')
+        return mockUserSession
+      },
+    }
+
+    const middleware = authAPIKey({ source: 'header' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({ 'x-api-key': 'my-api-key' }),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.deepEqual(SessionService.get(), mockUserSession)
+  })
+
+  test('should extract API key from query parameter when source is "query"', async () => {
+    const mockUserSession: CoreUserSession = { userId: 'user456' }
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async (token: string) => {
+        assert.equal(token, 'query-api-key')
+        return mockUserSession
+      },
+    }
+
+    const middleware = authAPIKey({ source: 'query' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({}, { apiKey: 'query-api-key' }),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.deepEqual(SessionService.get(), mockUserSession)
+  })
+
+  test('should prefer header over query when source is "all" and both are present', async () => {
+    const mockUserSession: CoreUserSession = { userId: 'user789' }
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async (token: string) => {
+        // Should use header value, not query value
+        assert.equal(token, 'header-key')
+        return mockUserSession
+      },
+    }
+
+    const middleware = authAPIKey({ source: 'all' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest(
+            { 'x-api-key': 'header-key' },
+            { apiKey: 'query-key' }
+          ),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.deepEqual(SessionService.get(), mockUserSession)
+  })
+
+  test('should fallback to query when header is missing and source is "all"', async () => {
+    const mockUserSession: CoreUserSession = { userId: 'user999' }
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async (token: string) => {
+        assert.equal(token, 'query-fallback')
+        return mockUserSession
+      },
+    }
+
+    const middleware = authAPIKey({ source: 'all' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({}, { apiKey: 'query-fallback' }),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.deepEqual(SessionService.get(), mockUserSession)
+  })
+
+  test('should not set session when API key is not found', async () => {
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async () => null,
+    }
+
+    const middleware = authAPIKey({ source: 'header' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({}),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.equal(SessionService.get(), undefined)
+  })
+
+  test('should not set session when JWT decode returns null', async () => {
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async () => null,
+    }
+
+    const middleware = authAPIKey({ source: 'header' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({ 'x-api-key': 'invalid-key' }),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.equal(SessionService.get(), undefined)
+  })
+
+  test('should skip middleware when session already exists', async () => {
+    const existingSession: CoreUserSession = { userId: 'existing' }
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    SessionService.setInitial(existingSession)
+
+    let decodeCalled = false
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async () => {
+        decodeCalled = true
+        return { userId: 'new' }
+      },
+    }
+
+    const middleware = authAPIKey({ source: 'header' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({ 'x-api-key': 'some-key' }),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.equal(decodeCalled, false)
+    assert.deepEqual(SessionService.get(), existingSession)
+  })
+
+  test('should skip middleware when http.request is not available', async () => {
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async () => ({ userId: 'test' }),
+    }
+
+    const middleware = authAPIKey({ source: 'header' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      { session: SessionService } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.equal(SessionService.get(), undefined)
+  })
+
+  test('should not decode when jwtService is not available', async () => {
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+
+    const middleware = authAPIKey({ source: 'header' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: undefined } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({ 'x-api-key': 'some-key' }),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.equal(SessionService.get(), undefined)
+  })
+
+  test('should not look in query when source is "header" even if header is missing', async () => {
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    let decodeCalled = false
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async () => {
+        decodeCalled = true
+        return { userId: 'test' }
+      },
+    }
+
+    const middleware = authAPIKey({ source: 'header' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({}, { apiKey: 'query-key' }),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.equal(decodeCalled, false)
+    assert.equal(SessionService.get(), undefined)
+  })
+
+  test('should not look in header when source is "query" even if query is missing', async () => {
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    let decodeCalled = false
+    const jwtService = {
+      encode: async () => 'token',
+      decode: async () => {
+        decodeCalled = true
+        return { userId: 'test' }
+      },
+    }
+
+    const middleware = authAPIKey({ source: 'query' })
+    let nextCalled = false
+
+    await middleware(
+      { jwt: jwtService } as any,
+      {
+        http: {
+          request: createMockHTTPRequest({ 'x-api-key': 'header-key' }),
+          response: createMockHTTPResponse(),
+        },
+        session: SessionService,
+      } as any,
+      async () => {
+        nextCalled = true
+      }
+    )
+
+    assert.equal(nextCalled, true)
+    assert.equal(decodeCalled, false)
+    assert.equal(SessionService.get(), undefined)
+  })
+})

package/src/middleware/auth-apikey.ts

@@ -21,12 +21,8 @@ export const authAPIKey = pikkuMiddlewareFactory<{
   source: 'header' | 'query' | 'all'
 }>(({ source }) =>
   pikkuMiddleware(
-    async (
-      { userSession: userSessionService, jwt: jwtService },
-      { http },
-      next
-    ) => {
-      if (!http?.request || userSessionService.get()) {
+    async ({ jwt: jwtService }, { http, session: SessionService }, next) => {
+      if (!http?.request || !SessionService || SessionService.get()) {
         return next()
       }
 
@@ -41,7 +37,7 @@ export const authAPIKey = pikkuMiddlewareFactory<{
       if (apiKey && jwtService) {
         const userSession = await jwtService.decode(apiKey)
         if (userSession) {
-          userSessionService.setInitial(userSession)
+          SessionService.setInitial(userSession)
         }
       }