@pikku/core 0.11.2 → 0.12.1

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,26 @@ 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
+  readonly?: 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.test.ts

@@ -0,0 +1,361 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { handleHTTPError } from './handle-error.js'
+import { addError } from './errors/error-handler.js'
+import {
+  NotFoundError,
+  BadRequestError,
+  ForbiddenError,
+} from './errors/errors.js'
+import { resetPikkuState } from './pikku-state.js'
+
+const createMockLogger = () => {
+  const logs: { level: string; args: any[] }[] = []
+  return {
+    info: (...args: any[]) => logs.push({ level: 'info', args }),
+    warn: (...args: any[]) => logs.push({ level: 'warn', args }),
+    error: (...args: any[]) => logs.push({ level: 'error', args }),
+    debug: (...args: any[]) => logs.push({ level: 'debug', args }),
+    _logs: logs,
+  }
+}
+
+const createMockHTTP = () => {
+  const state = {
+    statusCode: undefined as number | undefined,
+    jsonBody: undefined as any,
+    closed: false,
+  }
+  return {
+    request: {},
+    response: {
+      status: (code: number) => {
+        state.statusCode = code
+        return {
+          json: (body: any) => {
+            state.jsonBody = body
+          },
+        }
+      },
+      json: (body: any) => {
+        state.jsonBody = body
+      },
+      close: () => {
+        state.closed = true
+      },
+    },
+    _state: state,
+  }
+}
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+describe('handleHTTPError', () => {
+  test('should skip NotFoundError when respondWith404 is false', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new NotFoundError()
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-1',
+      logger as any,
+      [],
+      false,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, undefined)
+    assert.strictEqual(http._state.jsonBody, undefined)
+  })
+
+  test('should handle NotFoundError when respondWith404 is true', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new NotFoundError()
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-1',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 404)
+    assert.deepStrictEqual(http._state.jsonBody, {
+      message: 'The server cannot find the requested resource.',
+      payload: undefined,
+      traceId: 'tracker-1',
+    })
+  })
+
+  test('should set correct status and message for known errors', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('Invalid input')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-2',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 400)
+    assert.ok(http._state.jsonBody.message.includes('client error'))
+    assert.strictEqual(http._state.jsonBody.traceId, 'tracker-2')
+  })
+
+  test('should set status 403 for ForbiddenError', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new ForbiddenError()
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-3',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 403)
+  })
+
+  test('should log warning when status code is in logWarningsForStatusCodes', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-4',
+      logger as any,
+      [400],
+      true,
+      false
+    )
+
+    const warns = logger._logs.filter((l) => l.level === 'warn')
+    assert.ok(warns.length >= 1)
+    assert.ok(warns.some((w) => w.args[0].includes('tracker-4')))
+  })
+
+  test('should not log warning when status code is not in logWarningsForStatusCodes', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-5',
+      logger as any,
+      [500],
+      true,
+      false
+    )
+
+    const warns = logger._logs.filter((l) => l.level === 'warn')
+    assert.strictEqual(warns.length, 0)
+  })
+
+  test('should handle unknown errors with 500 status', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new Error('something unexpected')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-6',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.deepStrictEqual(http._state.jsonBody, { errorId: 'tracker-6' })
+  })
+
+  test('should log unknown errors with error level', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new Error('unexpected')
+
+    handleHTTPError(
+      error,
+      http as any,
+      undefined,
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    const errors = logger._logs.filter((l) => l.level === 'error')
+    assert.ok(errors.length >= 1)
+    assert.ok(errors.some((e) => e.args[0] === 'unexpected'))
+  })
+
+  test('should not include errorId in response when trackerId is undefined for unknown errors', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new Error('unexpected')
+
+    handleHTTPError(
+      error,
+      http as any,
+      undefined,
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.strictEqual(http._state.jsonBody, undefined)
+  })
+
+  test('should bubble error when bubbleError is true', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    assert.throws(
+      () =>
+        handleHTTPError(
+          error,
+          http as any,
+          'tracker',
+          logger as any,
+          [],
+          true,
+          true
+        ),
+      (e: any) => e === error
+    )
+  })
+
+  test('should not bubble error when bubbleError is false', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker',
+      logger as any,
+      [],
+      true,
+      false
+    )
+    // Should not throw
+  })
+
+  test('should call response.close when available', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.closed, true)
+  })
+
+  test('should handle undefined http gracefully', () => {
+    const logger = createMockLogger()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(error, undefined, 'tracker', logger as any, [], true, false)
+    // Should not throw
+  })
+
+  test('should include payload from error in known error response', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad') as any
+    error.payload = { field: 'email', reason: 'invalid' }
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.deepStrictEqual(http._state.jsonBody.payload, {
+      field: 'email',
+      reason: 'invalid',
+    })
+  })
+
+  test('should handle non-Error objects as errors', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = 'just a string error'
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    const errors = logger._logs.filter((l) => l.level === 'error')
+    assert.ok(errors.some((e) => e.args[0] === 'just a string error'))
+  })
+
+  test('should handle warning log without trackerId', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      undefined,
+      logger as any,
+      [400],
+      true,
+      false
+    )
+
+    const warns = logger._logs.filter((l) => l.level === 'warn')
+    assert.ok(warns.length >= 1)
+    assert.ok(
+      !warns.some(
+        (w) => typeof w.args[0] === 'string' && w.args[0].includes('Warning id')
+      )
+    )
+  })
+})

package/src/handle-error.ts

@@ -1,7 +1,7 @@
 import { getErrorResponse } from './errors/error-handler.js'
 import { NotFoundError } from './errors/errors.js'
-import { Logger } from './services/logger.js'
-import { PikkuHTTP } from './wirings/http/http.types.js'
+import type { Logger } from './services/logger.js'
+import type { PikkuHTTP } from './wirings/http/http.types.js'
 
 /**
  * Handle errors that occur during route processing
@@ -44,11 +44,11 @@ export const handleHTTPError = (
       if (trackerId) {
         logger.warn(`Warning id: ${trackerId}`)
       }
-      logger.warn(e)
+      logger.warn(e instanceof Error ? e.message : e)
     }
   } else {
     // Handle unexpected errors
-    logger.error(e)
+    logger.error(e instanceof Error ? e.message : e)
     http?.response?.status(500)
 
     if (trackerId) {
@@ -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?.()
 }