@pikku/core 0.12.0 → 0.12.2

package/dist/wirings/scheduler/scheduler.types.d.ts

@@ -1,5 +1,5 @@
-import { CoreUserSession, CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
-import { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
+import type { CoreUserSession, CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
+import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 /**
  * Represents metadata for scheduled tasks, including title, schedule, and documentation.
  */

package/dist/wirings/trigger/pikku-trigger-service.d.ts

@@ -1,6 +1,5 @@
-import { CoreSingletonServices, CreateWireServices, CoreServices, CoreUserSession } from '../../types/core.types.js';
-import { TriggerInstance } from './trigger.types.js';
-import { TriggerService } from '../../services/trigger-service.js';
+import type { TriggerInstance } from './trigger.types.js';
+import type { TriggerService } from '../../services/trigger-service.js';
 export type TriggerTarget = {
     targetType: 'rpc' | 'workflow';
     targetName: string;
@@ -12,9 +11,6 @@ export type TriggerSourceInfo = {
 };
 export declare abstract class PikkuTriggerService implements TriggerService {
     protected activeTriggers: Map<string, TriggerInstance>;
-    protected singletonServices?: CoreSingletonServices;
-    protected createWireServices?: CreateWireServices<CoreSingletonServices, CoreServices, CoreUserSession>;
-    setServices(singletonServices: CoreSingletonServices, createWireServices?: CreateWireServices<CoreSingletonServices, CoreServices, CoreUserSession>): void;
     abstract start(): Promise<void>;
     stop(): Promise<void>;
     protected getTriggerTargets(): Map<string, TriggerTarget[]>;

package/dist/wirings/trigger/pikku-trigger-service.js

@@ -1,22 +1,17 @@
 import { rpcService } from '../rpc/rpc-runner.js';
 import { setupTrigger } from './trigger-runner.js';
-import { pikkuState } from '../../pikku-state.js';
+import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 export class PikkuTriggerService {
     activeTriggers = new Map();
-    singletonServices;
-    createWireServices;
-    setServices(singletonServices, createWireServices) {
-        this.singletonServices = singletonServices;
-        this.createWireServices = createWireServices;
-    }
     async stop() {
+        const singletonServices = getSingletonServices();
         for (const [name, instance] of this.activeTriggers) {
             try {
                 await instance.teardown();
-                this.singletonServices.logger.info(`Stopped trigger: ${name}`);
+                singletonServices.logger.info(`Stopped trigger: ${name}`);
             }
             catch (error) {
-                this.singletonServices.logger.error(`Error stopping trigger ${name}: ${error}`);
+                singletonServices.logger.error(`Error stopping trigger ${name}: ${error}`);
             }
         }
         this.activeTriggers.clear();
@@ -44,15 +39,15 @@ export class PikkuTriggerService {
     async setupTriggerInstance(name, input, onTrigger) {
         return setupTrigger({
             name,
-            singletonServices: this.singletonServices,
-            createWireServices: this.createWireServices,
             input,
             onTrigger,
         });
     }
     async onTriggerFire(triggerName, targets, data) {
-        const wireServices = await this.createWireServices?.(this.singletonServices, {});
-        const services = { ...this.singletonServices, ...wireServices };
+        const singletonServices = getSingletonServices();
+        const createWireServices = getCreateWireServices();
+        const wireServices = await createWireServices?.(singletonServices, {});
+        const services = { ...singletonServices, ...wireServices };
         const rpc = rpcService.getContextRPCService(services, {}, false);
         for (const target of targets) {
             try {
@@ -60,15 +55,15 @@ export class PikkuTriggerService {
                     await rpc.startWorkflow(target.targetName, data, {
                         startNode: target.startNode,
                     });
-                    this.singletonServices.logger.info(`Trigger '${triggerName}' started workflow '${target.targetName}'`);
+                    singletonServices.logger.info(`Trigger '${triggerName}' started workflow '${target.targetName}'`);
                 }
                 else {
                     await rpc.invoke(target.targetName, data);
-                    this.singletonServices.logger.info(`Trigger '${triggerName}' invoked RPC '${target.targetName}'`);
+                    singletonServices.logger.info(`Trigger '${triggerName}' invoked RPC '${target.targetName}'`);
                 }
             }
             catch (error) {
-                this.singletonServices.logger.error(`Error invoking ${target.targetType} '${target.targetName}' from trigger '${triggerName}': ${error}`);
+                singletonServices.logger.error(`Error invoking ${target.targetType} '${target.targetName}' from trigger '${triggerName}': ${error}`);
             }
         }
     }

package/dist/wirings/trigger/trigger-runner.d.ts

@@ -1,4 +1,3 @@
-import { CreateWireServices, type CoreSingletonServices } from '../../types/core.types.js';
 import type { CoreTrigger, CoreTriggerSource, TriggerInstance } from './trigger.types.js';
 /**
  * Registers a trigger with the Pikku framework.
@@ -17,8 +16,6 @@ export declare const wireTriggerSource: <TInput = unknown, TOutput = unknown>(so
  */
 export type SetupTriggerParams<TInput = unknown, TOutput = unknown> = {
     name: string;
-    singletonServices: CoreSingletonServices;
-    createWireServices?: CreateWireServices;
     input?: TInput;
     onTrigger: (data: TOutput) => void | Promise<void>;
 };
@@ -27,11 +24,10 @@ export type SetupTriggerParams<TInput = unknown, TOutput = unknown> = {
  * Returns a TriggerInstance with a teardown function.
  *
  * @param name - The trigger name (must be registered via wireTrigger)
- * @param singletonServices - The singleton services
  * @param input - The input to pass to the trigger function
  * @param onTrigger - Callback invoked when the trigger fires
  */
-export declare function setupTrigger<TInput = unknown, TOutput = unknown>({ name, singletonServices, createWireServices, input, onTrigger, }: SetupTriggerParams<TInput, TOutput>): Promise<TriggerInstance>;
+export declare function setupTrigger<TInput = unknown, TOutput = unknown>({ name, input, onTrigger, }: SetupTriggerParams<TInput, TOutput>): Promise<TriggerInstance>;
 /**
  * Gets all registered triggers
  */

package/dist/wirings/trigger/trigger-runner.js

@@ -1,4 +1,4 @@
-import { pikkuState } from '../../pikku-state.js';
+import { pikkuState, getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { PikkuMissingMetaError } from '../../errors/errors.js';
 /**
@@ -39,11 +39,12 @@ export const wireTriggerSource = (source) => {
  * Returns a TriggerInstance with a teardown function.
  *
  * @param name - The trigger name (must be registered via wireTrigger)
- * @param singletonServices - The singleton services
  * @param input - The input to pass to the trigger function
  * @param onTrigger - Callback invoked when the trigger fires
  */
-export async function setupTrigger({ name, singletonServices, createWireServices, input, onTrigger, }) {
+export async function setupTrigger({ name, input, onTrigger, }) {
+    const singletonServices = getSingletonServices();
+    const createWireServices = getCreateWireServices();
     const source = pikkuState(null, 'trigger', 'triggerSources').get(name);
     const sourceMeta = pikkuState(null, 'trigger', 'sourceMeta')[name];
     if (!source) {

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,6 +1,6 @@
-import { CoreConfig, CoreSingletonServices, CreateWireServices, SerializedError } from '../../types/core.types.js';
+import type { SerializedError } from '../../types/core.types.js';
 import type { StepState, WorkflowRun, WorkflowRunWire, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
-import { WorkflowService } from '../../services/workflow-service.js';
+import type { WorkflowService } from '../../services/workflow-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 /**
  * Exception thrown when workflow needs to pause for async step
@@ -46,9 +46,6 @@ export declare class WorkflowStepNameNotString extends Error {
  * Combines orchestration and step execution
  */
 export declare abstract class PikkuWorkflowService implements WorkflowService {
-    private config;
-    private singletonServices;
-    private createWireServices;
     private inlineRuns;
     constructor();
     /**
@@ -63,7 +60,6 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * Unregister a run from inline tracking
      */
     unregisterInlineRun(runId: string): void;
-    setServices(singletonServices: CoreSingletonServices, createWireServices: CreateWireServices | undefined, { workflow }: CoreConfig): void;
     registerWorkflowVersions(): Promise<void>;
     abstract createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire): Promise<string>;
     /**

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -1,5 +1,5 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
-import { pikkuState } from '../../pikku-state.js';
+import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
@@ -83,9 +83,6 @@ const WORKFLOW_END_STATES = new Set([
  * Combines orchestration and step execution
  */
 export class PikkuWorkflowService {
-    config;
-    singletonServices;
-    createWireServices;
     inlineRuns = new Set();
     constructor() { }
     /**
@@ -106,17 +103,6 @@ export class PikkuWorkflowService {
     unregisterInlineRun(runId) {
         this.inlineRuns.delete(runId);
     }
-    setServices(singletonServices, createWireServices, { workflow }) {
-        this.singletonServices = singletonServices;
-        this.createWireServices = createWireServices;
-        this.config = {
-            retries: workflow?.retries ?? 0,
-            retryDelay: workflow?.retryDelay ?? 0,
-            orchestratorQueueName: workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
-            stepWorkerQueueName: workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',
-            sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowSleeper',
-        };
-    }
     async registerWorkflowVersions() {
         const allMeta = pikkuState(null, 'workflows', 'meta');
         for (const [name, meta] of Object.entries(allMeta)) {
@@ -178,7 +164,7 @@ export class PikkuWorkflowService {
         }
         // Check if this is a graph workflow (source === 'graph')
         if (workflowMeta.source === 'graph') {
-            const shouldInline = options?.inline || !this.singletonServices?.queueService;
+            const shouldInline = options?.inline || !getSingletonServices()?.queueService;
             return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire);
         }
         // DSL workflow - check registration exists
@@ -194,7 +180,7 @@ export class PikkuWorkflowService {
         if (options?.inline) {
             this.inlineRuns.add(runId);
         }
-        if (options?.inline || !this.singletonServices?.queueService) {
+        if (options?.inline || !getSingletonServices()?.queueService) {
             this.runWorkflowJob(runId, rpcService)
                 .catch(() => { })
                 .finally(() => {
@@ -255,9 +241,9 @@ export class PikkuWorkflowService {
             const wire = { workflow: workflowWire };
             try {
                 const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
-                    singletonServices: this.singletonServices,
+                    singletonServices: getSingletonServices(),
                     wire,
-                    createWireServices: this.createWireServices,
+                    createWireServices: getCreateWireServices(),
                     data: () => run.input,
                 });
                 await this.updateRunStatus(runId, 'completed', result);
@@ -409,10 +395,10 @@ export class PikkuWorkflowService {
         }
     }
     verifyQueueService() {
-        if (!this.singletonServices?.queueService) {
+        if (!getSingletonServices()?.queueService) {
             throw new Error('QueueService not configured. Remote workflows require a queue service.');
         }
-        return this.singletonServices.queueService;
+        return getSingletonServices().queueService;
     }
     async rpcStep(runId, stepName, rpcName, data, rpcService, stepOptions) {
         // Check if step already exists
@@ -445,11 +431,11 @@ export class PikkuWorkflowService {
         // Step is pending - schedule it
         await this.setStepScheduled(stepState.stepId);
         // Enqueue step worker (unless inline mode)
-        if (!this.isInline(runId) && this.singletonServices.queueService) {
+        if (!this.isInline(runId) && getSingletonServices().queueService) {
             // Map step retry options to queue job options
             const retries = stepOptions?.retries ?? 0;
             const retryDelay = stepOptions?.retryDelay;
-            await this.singletonServices.queueService.add(this.getConfig().stepWorkerQueueName, {
+            await getSingletonServices().queueService.add(this.getConfig().stepWorkerQueueName, {
                 runId,
                 stepName,
                 rpcName,
@@ -609,9 +595,9 @@ export class PikkuWorkflowService {
         // Step is pending - schedule it
         await this.setStepScheduled(stepState.stepId);
         // Check if inline mode or no scheduler service
-        if (!this.isInline(runId) && this.singletonServices.schedulerService) {
+        if (!this.isInline(runId) && getSingletonServices().schedulerService) {
             // Remote mode - schedule sleep via scheduler service
-            await this.singletonServices.schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, {
+            await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, {
                 runId,
                 stepId: stepState.stepId,
             });
@@ -693,9 +679,14 @@ export class PikkuWorkflowService {
         }
     }
     getConfig() {
-        if (!this.singletonServices || !this.config) {
-            throw new WorkflowServiceNotInitialized();
-        }
-        return this.config;
+        const singletonServices = getSingletonServices();
+        const workflow = singletonServices.config?.workflow;
+        return {
+            retries: workflow?.retries ?? 0,
+            retryDelay: workflow?.retryDelay ?? 0,
+            orchestratorQueueName: workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
+            stepWorkerQueueName: workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',
+            sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowSleeper',
+        };
     }
 }

package/dist/wirings/workflow/workflow.types.d.ts

@@ -1,5 +1,5 @@
-import { SerializedError, CommonWireMeta } from '../../types/core.types.js';
-import { CorePikkuFunctionConfig } from '../../function/functions.types.js';
+import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -30,6 +30,7 @@
     "./rpc": "./dist/wirings/rpc/index.js",
     "./mcp": "./dist/wirings/mcp/index.js",
     "./ai-agent": "./dist/wirings/ai-agent/index.js",
+    "./gateway": "./dist/wirings/gateway/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/channel": "./dist/wirings/cli/channel/index.js",
     "./node": "./dist/wirings/node/index.js",
@@ -40,6 +41,7 @@
     "./services": "./dist/services/index.js",
     "./services/local-content": "./dist/services/local-content.js",
     "./services/gopass-secrets": "./dist/services/gopass-secrets.js",
+    "./internal": "./dist/internal.js",
     "./schema": "./dist/schema.js"
   },
   "dependencies": {
@@ -49,7 +51,7 @@
     "picoquery": "^2.5.0"
   },
   "devDependencies": {
-    "@types/node": "^24.10.12",
+    "@types/node": "^24.11.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9"
   },

package/src/crypto-utils.test.ts

@@ -0,0 +1,116 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { encryptJSON, decryptJSON } from './crypto-utils.js'
+
+describe('encryptJSON / decryptJSON', () => {
+  const secret = 'test-secret-key-for-encryption'
+
+  test('should round-trip a simple object', async () => {
+    const original = { hello: 'world', num: 42 }
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should round-trip a string value', async () => {
+    const original = 'just a string'
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.strictEqual(decrypted, original)
+  })
+
+  test('should round-trip a number', async () => {
+    const original = 12345
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.strictEqual(decrypted, original)
+  })
+
+  test('should round-trip null', async () => {
+    const encrypted = await encryptJSON(secret, null)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.strictEqual(decrypted, null)
+  })
+
+  test('should round-trip a boolean', async () => {
+    const encrypted = await encryptJSON(secret, true)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.strictEqual(decrypted, true)
+  })
+
+  test('should round-trip a nested object', async () => {
+    const original = { user: { id: 1, roles: ['admin', 'user'] }, active: true }
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should round-trip an array', async () => {
+    const original = [1, 'two', { three: 3 }]
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should produce different ciphertexts for same input (random IV)', async () => {
+    const value = { same: 'data' }
+    const enc1 = await encryptJSON(secret, value)
+    const enc2 = await encryptJSON(secret, value)
+    assert.notStrictEqual(enc1, enc2)
+  })
+
+  test('should produce a base64url string (no +, /, or = characters)', async () => {
+    const encrypted = await encryptJSON(secret, { test: 'base64url' })
+    assert.ok(!/[+/=]/.test(encrypted), `Expected base64url, got: ${encrypted}`)
+  })
+
+  test('should fail to decrypt with wrong secret', async () => {
+    const encrypted = await encryptJSON(secret, { data: 'sensitive' })
+    await assert.rejects(
+      () => decryptJSON('wrong-secret', encrypted),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('should reject an invalid encrypted payload (too short)', async () => {
+    await assert.rejects(() => decryptJSON(secret, 'dG9vc2hvcnQ'), {
+      message: 'Invalid encrypted payload',
+    })
+  })
+
+  test('should reject empty string', async () => {
+    await assert.rejects(() => decryptJSON(secret, ''), {
+      message: 'Invalid encrypted payload',
+    })
+  })
+
+  test('should reject corrupted ciphertext', async () => {
+    const encrypted = await encryptJSON(secret, { data: 'test' })
+    const corrupted = encrypted.slice(0, -4) + 'XXXX'
+    await assert.rejects(
+      () => decryptJSON(secret, corrupted),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('should handle unicode content', async () => {
+    const original = { emoji: '🎉', japanese: 'こんにちは', arabic: 'مرحبا' }
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should handle empty object', async () => {
+    const original = {}
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should handle large payload', async () => {
+    const original = { data: 'x'.repeat(10000) }
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+})

package/src/errors/error.test.ts

@@ -1,7 +1,75 @@
 import { test, describe } from 'node:test'
 import assert from 'assert'
-import { getErrorResponse, addError } from './error-handler.js'
-import { ForbiddenError, BadRequestError, NotFoundError } from './errors.js'
+import {
+  getErrorResponse,
+  addError,
+  addErrors,
+  PikkuError,
+} from './error-handler.js'
+import {
+  BadRequestError,
+  UnauthorizedError,
+  MissingSessionError,
+  InvalidSessionError,
+  PaymentRequiredError,
+  ForbiddenError,
+  InvalidOriginError,
+  NotFoundError,
+  MethodNotAllowedError,
+  NotAcceptableError,
+  ProxyAuthenticationRequiredError,
+  RequestTimeoutError,
+  ConflictError,
+  GoneError,
+  LengthRequiredError,
+  PreconditionFailedError,
+  PayloadTooLargeError,
+  URITooLongError,
+  UnsupportedMediaTypeError,
+  RangeNotSatisfiableError,
+  ExpectationFailedError,
+  UnprocessableContentError,
+  LockedError,
+  TooManyRequestsError,
+  InternalServerError,
+  NotImplementedError,
+  BadGatewayError,
+  ServiceUnavailableError,
+  GatewayTimeoutError,
+  HTTPVersionNotSupportedError,
+  MaxComputeTimeReachedError,
+  MissingSchemaError,
+  InvalidMiddlewareWireError,
+  PikkuMissingMetaError,
+} from './errors.js'
+
+describe('PikkuError', () => {
+  test('should create error with default message', () => {
+    const error = new PikkuError()
+    assert.strictEqual(error.message, 'An error occurred')
+  })
+
+  test('should create error with custom message', () => {
+    const error = new PikkuError('custom message')
+    assert.strictEqual(error.message, 'custom message')
+  })
+
+  test('should be instance of Error', () => {
+    const error = new PikkuError()
+    assert.ok(error instanceof Error)
+  })
+
+  test('should be instance of PikkuError', () => {
+    const error = new PikkuError()
+    assert.ok(error instanceof PikkuError)
+  })
+
+  test('subclasses should be instanceof PikkuError', () => {
+    assert.ok(new BadRequestError() instanceof PikkuError)
+    assert.ok(new NotFoundError() instanceof PikkuError)
+    assert.ok(new ForbiddenError() instanceof PikkuError)
+  })
+})
 
 describe('getErrorResponse', () => {
   test('should return the correct error response for BadRequestError', () => {
@@ -52,3 +120,76 @@ describe('getErrorResponse', () => {
     assert.deepStrictEqual(response, customErrorDetails)
   })
 })
+
+describe('addErrors', () => {
+  test('should register multiple errors at once', () => {
+    class ErrA extends Error {}
+    class ErrB extends Error {}
+    addErrors([
+      [ErrA, { status: 450, message: 'Error A' }],
+      [ErrB, { status: 451, message: 'Error B' }],
+    ])
+    assert.deepStrictEqual(getErrorResponse(new ErrA()), {
+      status: 450,
+      message: 'Error A',
+    })
+    assert.deepStrictEqual(getErrorResponse(new ErrB()), {
+      status: 451,
+      message: 'Error B',
+    })
+  })
+})
+
+describe('all built-in error classes', () => {
+  const errorCases: [string, any, number][] = [
+    ['InvalidMiddlewareWireError', InvalidMiddlewareWireError, 500],
+    ['PikkuMissingMetaError', PikkuMissingMetaError, 500],
+    ['BadRequestError', BadRequestError, 400],
+    ['UnauthorizedError', UnauthorizedError, 401],
+    ['MissingSessionError', MissingSessionError, 401],
+    ['InvalidSessionError', InvalidSessionError, 401],
+    ['PaymentRequiredError', PaymentRequiredError, 402],
+    ['ForbiddenError', ForbiddenError, 403],
+    ['InvalidOriginError', InvalidOriginError, 403],
+    ['NotFoundError', NotFoundError, 404],
+    ['MethodNotAllowedError', MethodNotAllowedError, 405],
+    ['NotAcceptableError', NotAcceptableError, 406],
+    ['ProxyAuthenticationRequiredError', ProxyAuthenticationRequiredError, 407],
+    ['RequestTimeoutError', RequestTimeoutError, 408],
+    ['ConflictError', ConflictError, 409],
+    ['GoneError', GoneError, 410],
+    ['LengthRequiredError', LengthRequiredError, 411],
+    ['PreconditionFailedError', PreconditionFailedError, 412],
+    ['PayloadTooLargeError', PayloadTooLargeError, 413],
+    ['URITooLongError', URITooLongError, 414],
+    ['UnsupportedMediaTypeError', UnsupportedMediaTypeError, 415],
+    ['RangeNotSatisfiableError', RangeNotSatisfiableError, 416],
+    ['ExpectationFailedError', ExpectationFailedError, 417],
+    ['UnprocessableContentError', UnprocessableContentError, 422],
+    ['LockedError', LockedError, 423],
+    ['TooManyRequestsError', TooManyRequestsError, 429],
+    ['InternalServerError', InternalServerError, 500],
+    ['NotImplementedError', NotImplementedError, 501],
+    ['BadGatewayError', BadGatewayError, 502],
+    ['ServiceUnavailableError', ServiceUnavailableError, 503],
+    ['GatewayTimeoutError', GatewayTimeoutError, 504],
+    ['HTTPVersionNotSupportedError', HTTPVersionNotSupportedError, 505],
+    ['MaxComputeTimeReachedError', MaxComputeTimeReachedError, 524],
+    ['MissingSchemaError', MissingSchemaError, 500],
+  ]
+
+  for (const [name, ErrorClass, expectedStatus] of errorCases) {
+    test(`${name} should map to status ${expectedStatus}`, () => {
+      const error = new ErrorClass()
+      const response = getErrorResponse(error)
+      assert.ok(response, `Expected error response for ${name}`)
+      assert.strictEqual(response!.status, expectedStatus)
+      assert.ok(response!.message.length > 0)
+    })
+
+    test(`${name} should be instance of PikkuError`, () => {
+      const error = new ErrorClass()
+      assert.ok(error instanceof PikkuError)
+    })
+  }
+})

package/src/errors/errors.ts

@@ -76,6 +76,16 @@ addError(ForbiddenError, {
     'The client does not have permission to access the requested resource.',
 })
 
+/**
+ * The session is readonly and cannot access a non-readonly function.
+ * @group Error
+ */
+export class ReadonlySessionError extends PikkuError {}
+addError(ReadonlySessionError, {
+  status: 403,
+  message: 'The session is readonly and cannot access this function.',
+})
+
 /**
  * The request was made from an origin that is not permitted to access this resource.
  * @group Error

package/src/errors/index.ts

@@ -1 +1,2 @@
 export * from './errors.js'
+export { PikkuError, addError, addErrors } from './error-handler.js'

package/src/function/function-runner.test.ts

@@ -3,8 +3,8 @@ import * as assert from 'node:assert'
 import { addFunction, runPikkuFunc } from './function-runner.js'
 import { addMiddleware, addPermission } from '../index.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
-import { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
-import { CorePermissionGroup } from './functions.types.js'
+import type { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
+import type { CorePermissionGroup } from './functions.types.js'
 
 beforeEach(() => {
   resetPikkuState()