@pikku/core 0.6.21 → 0.6.23

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## 0.6
 
+## 0.6.23
+
+### Patch Changes
+
+- 1c8c470: fix: await schema validation
+
+## 0.6.22
+
+### Patch Changes
+
+- 60b2265: refactor: supporting request and response objects
+
 ## 0.6.21
 
 ### Patch Changes

package/dist/channel/channel-handler.d.ts

@@ -1,3 +1,3 @@
-import { CoreServices } from '../types/core.types.js';
+import { CoreServices, CoreUserSession } from '../types/core.types.js';
 import { CoreAPIChannel, PikkuChannelHandler } from './channel.types.js';
-export declare const processMessageHandlers: (services: CoreServices, channelConfig: CoreAPIChannel<any, any>, channelHandler: PikkuChannelHandler) => (rawData: any) => Promise<unknown>;
+export declare const processMessageHandlers: (services: CoreServices, session: CoreUserSession | undefined, channelConfig: CoreAPIChannel<any, any>, channelHandler: PikkuChannelHandler) => (rawData: any) => Promise<unknown>;

package/dist/channel/channel-handler.js

@@ -1,45 +1,65 @@
 import { verifyPermissions } from '../permissions.js';
 import { pikkuState } from '../pikku-state.js';
-const validateSchema = (logger, data, channelName, routingProperty, routerValue) => {
+const getRouteMeta = (channelName, routingProperty, routerValue) => {
     const channelsMeta = pikkuState('channel', 'meta');
-    for (const channelMeta of channelsMeta) {
-        if (routingProperty && routerValue) {
-            const channelRoute = channelMeta.messageRoutes[routingProperty]?.[routerValue];
-            if (channelRoute) {
-                const schemaNames = channelRoute.inputs;
-                if (schemaNames) {
-                    // TODO
-                    // loadSchema(schemaNames, logger)
-                    // validateJson(schemaNames, data)
-                }
-                return;
-            }
+    const channelMeta = channelsMeta.find((channelMeta) => channelMeta.name === channelName);
+    if (!channelMeta) {
+        throw new Error(`Channel ${channelName} not found`);
+    }
+    if (!routingProperty) {
+        if (!channelMeta.message) {
+            throw new Error(`Channel ${channelName} has no default message route`);
         }
+        return channelMeta.message;
+    }
+    if (!routerValue) {
+        throw new Error(`Channel ${channelName} requires a router value for ${routingProperty}`);
+    }
+    const route = channelMeta.messageRoutes[routingProperty]?.[routerValue];
+    if (!route) {
+        throw new Error(`Channel ${channelName} has no route for ${routingProperty}:${routerValue}`);
     }
+    return route;
 };
-const validateAuth = (requiresSession, userSession, onMessage) => {
+const validateSchema = (logger, data, channelRoute) => {
+    const schemaNames = channelRoute.inputs;
+    if (schemaNames) {
+        // TODO
+        // loadSchema(schemaNames, logger)
+        // validateJson(schemaNames, data)
+    }
+};
+const validateAuth = (requiresSession, session, onMessage) => {
     const auth = typeof onMessage === 'function'
         ? requiresSession
         : onMessage.auth === undefined
             ? requiresSession
             : onMessage.auth;
-    if (auth && !userSession) {
+    if (auth && !session) {
         return false;
     }
     return true;
 };
-const validatePermissions = async (services, userSession, onMessage, data) => {
+const validatePermissions = async (services, session, onMessage, data) => {
     const permissions = typeof onMessage === 'function' ? {} : onMessage.permissions;
-    return await verifyPermissions(permissions, services, data, userSession);
+    return await verifyPermissions(permissions, services, data, session);
 };
-const runFunction = async (services, channelHandler, onMessage, data) => {
+const runFunction = async (services, channelHandler, channelMessageMeta, session, onMessage, data) => {
     const func = typeof onMessage === 'function' ? onMessage : onMessage.func;
-    return await func(services, channelHandler.getChannel(), data);
+    if (channelMessageMeta.type?.toLowerCase().includes('function')) {
+        return await func({
+            ...services,
+            channel: channelHandler.getChannel(),
+        }, data, session);
+    }
+    else {
+        return await func(services, channelHandler.getChannel(), data);
+    }
 };
-export const processMessageHandlers = (services, channelConfig, channelHandler) => {
+export const processMessageHandlers = (services, session, channelConfig, channelHandler) => {
     const logger = services.logger;
     const requiresSession = channelConfig.auth !== false;
-    const processMessage = async (data, onMessage, routingProperty, routerValue) => {
+    const processMessage = async (data, onMessage, session, routingProperty, routerValue) => {
         if (!validateAuth(requiresSession, channelHandler, onMessage)) {
             const routeMessage = routingProperty
                 ? `route '${routingProperty}:${routerValue}'`
@@ -49,12 +69,15 @@ export const processMessageHandlers = (services, channelConfig, channelHandler)
             channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`);
             return;
         }
-        validateSchema(services.logger, data, channelConfig.name, routingProperty, routerValue);
+        const routeMeta = getRouteMeta(channelConfig.name, routingProperty, routerValue);
+        if (routeMeta) {
+            await validateSchema(services.logger, data, routeMeta);
+        }
         const hasPermission = await validatePermissions(services, channelHandler, onMessage, data);
         if (!hasPermission) {
             logger.error(`Channel ${channelConfig.name} requires permissions for ${routingProperty || 'default message route'}`);
         }
-        return await runFunction(services, channelHandler, onMessage, data);
+        return await runFunction(services, channelHandler, routeMeta, session, onMessage, data);
     };
     const onMessage = async (rawData) => {
         let result;
@@ -68,14 +91,14 @@ export const processMessageHandlers = (services, channelConfig, channelHandler)
                     const routerValue = messageData[routingProperty];
                     if (routerValue && routes[routerValue]) {
                         processed = true;
-                        result = await processMessage(messageData, routes[routerValue], routingProperty, routerValue);
+                        result = await processMessage(messageData, routes[routerValue], session, routingProperty, routerValue);
                         break;
                     }
                 }
                 // Default handler if no routes matched but json data was parsed
                 if (!processed && channelConfig.onMessage) {
                     processed = true;
-                    result = await processMessage(messageData, channelConfig.onMessage);
+                    result = await processMessage(messageData, channelConfig.onMessage, session);
                 }
             }
             catch (error) {
@@ -85,7 +108,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler)
         // Default handler if no routes matched and json data wasn't parsed
         if (!processed && channelConfig.onMessage) {
             processed = true;
-            result = await processMessage(rawData, channelConfig.onMessage);
+            result = await processMessage(rawData, channelConfig.onMessage, session);
         }
         if (!processed) {
             logger.error(`No handler found for message in channel ${channelConfig.name} for ${rawData}`);

package/dist/channel/channel-runner.d.ts

@@ -4,11 +4,11 @@ export declare const addChannel: <In, Channel extends string, ChannelFunction, C
 export declare const getMatchingChannelConfig: (request: string) => {
     matchedPath: import("path-to-regexp").MatchResult<Partial<Record<string, string | string[]>>>;
     params: Partial<Record<string, string | string[]>>;
-    channelConfig: CoreAPIChannel<any, string, import("./channel.types.js").CoreChannelConnection<any, unknown, import("../index.js").CoreServices>, import("./channel.types.js").CoreChannelDisconnection<any, import("../index.js").CoreServices>, import("./channel.types.js").CoreChannelMessage<unknown, unknown, unknown, import("../index.js").CoreServices>, import("./channel.types.js").CoreChannelMessage<unknown, unknown, unknown, import("../index.js").CoreServices>, import("../index.js").CoreAPIPermission<any>>;
+    channelConfig: CoreAPIChannel<any, string, import("./channel.types.js").CoreChannelConnection<any, unknown, import("../index.js").CoreServices>, import("./channel.types.js").CoreChannelDisconnection<any, import("../index.js").CoreServices>, import("./channel.types.js").CoreChannelMessage<unknown, unknown, unknown, import("../index.js").CoreServices> | import("../index.js").CoreAPIFunction<unknown, unknown>, import("./channel.types.js").CoreChannelMessage<unknown, unknown, unknown, import("../index.js").CoreServices> | import("../index.js").CoreAPIFunction<unknown, unknown>, import("../index.js").CoreAPIPermission<any>>;
     schemaName: string | null | undefined;
 } | null;
-export declare const openChannel: ({ route, singletonServices, coerceToArray, http, }: Pick<CoreAPIChannel<unknown, string>, "route"> & Omit<RunChannelParams<unknown>, "response" | "request"> & {
-    userSessionService?: UserSessionService<any>;
+export declare const openChannel: ({ route, singletonServices, coerceToArray, request, }: Pick<CoreAPIChannel<unknown, string>, "route"> & RunChannelParams<unknown> & {
+    userSessionService: UserSessionService<any>;
 } & RunChannelOptions) => Promise<{
     openingData: unknown;
     channelConfig: CoreAPIChannel<unknown, any>;

package/dist/channel/channel-runner.js

@@ -27,7 +27,7 @@ export const getMatchingChannelConfig = (request) => {
     }
     return null;
 };
-export const openChannel = async ({ route, singletonServices, coerceToArray = false, http, }) => {
+export const openChannel = async ({ route, singletonServices, coerceToArray = false, request, }) => {
     const matchingChannel = getMatchingChannelConfig(route);
     if (!matchingChannel) {
         singletonServices.logger.info(`Channel not found: ${route}`);
@@ -35,15 +35,15 @@ export const openChannel = async ({ route, singletonServices, coerceToArray = fa
     }
     const { params, channelConfig, schemaName } = matchingChannel;
     const requiresSession = channelConfig.auth !== false;
-    http?.request?.setParams(params);
+    request?.setParams(params);
     singletonServices.logger.info(`Matched channel: ${channelConfig.name} | route: ${channelConfig.route} | auth: ${requiresSession.toString()}`);
     let openingData;
-    if (http?.request) {
-        openingData = await http.request.getData();
+    if (request) {
+        openingData = await request.data();
         if (coerceToArray && schemaName) {
             coerceQueryStringToArray(schemaName, openingData);
         }
-        validateSchema(singletonServices.logger, singletonServices.schemaService, schemaName, openingData);
+        await validateSchema(singletonServices.logger, singletonServices.schemaService, schemaName, openingData);
     }
     return { openingData, channelConfig };
 };

package/dist/channel/channel.types.d.ts

@@ -1,11 +1,7 @@
 import { PikkuError } from '../errors/error-handler.js';
-import { HTTPFunctionMetaInputTypes, PikkuHTTP } from '../http/http-routes.types.js';
-import { PikkuHTTPAbstractRequest } from '../http/pikku-http-abstract-request.js';
-import { PikkuHTTPAbstractResponse } from '../http/pikku-http-abstract-response.js';
+import { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http-routes.types.js';
 import { APIDocs, CoreServices, CoreSingletonServices, CreateSessionServices, PikkuMiddleware } from '../types/core.types.js';
-import { CoreAPIPermission } from '../types/functions.types.js';
-import { PikkuRequest } from '../pikku-request.js';
-import { PikkuResponse } from '../pikku-response.js';
+import { CoreAPIFunction, CoreAPIPermission } from '../types/functions.types.js';
 export type RunChannelOptions = Partial<{
     skipUserSession: boolean;
     respondWith404: boolean;
@@ -16,12 +12,15 @@ export type RunChannelOptions = Partial<{
 export type RunChannelParams<ChannelData> = {
     channelId: string;
     singletonServices: CoreSingletonServices;
-    request?: PikkuRequest<ChannelData> | PikkuHTTPAbstractRequest<ChannelData>;
-    response?: PikkuResponse | PikkuHTTPAbstractResponse;
-    http?: PikkuHTTP;
+    request?: PikkuHTTPRequest<ChannelData>;
+    response?: PikkuHTTPResponse;
     createSessionServices?: CreateSessionServices;
 };
-export interface HandlerMeta {
+export interface ChannelMessageMeta {
+    inputs: string[] | null;
+    outputs: string[] | null;
+    docs?: APIDocs;
+    type: null | string;
 }
 export interface ChannelMeta {
     name: string;
@@ -32,14 +31,8 @@ export interface ChannelMeta {
     inputTypes?: HTTPFunctionMetaInputTypes;
     connect: boolean;
     disconnect: boolean;
-    message: {
-        inputs: string[] | null;
-        outputs: string[] | null;
-    } | null;
-    messageRoutes: Record<string, Record<string, {
-        inputs: string[] | null;
-        outputs: string[] | null;
-    }>>;
+    message: ChannelMessageMeta | null;
+    messageRoutes: Record<string, Record<string, ChannelMessageMeta>>;
     docs?: APIDocs;
     tags?: string[];
 }
@@ -58,7 +51,7 @@ export type CoreAPIChannelMessage<ChannelFunctionMessage = CoreChannelMessage<un
     func: ChannelFunctionMessage;
     route: string;
 };
-export type CoreAPIChannel<ChannelData, Channel extends string, ChannelFunctionConnection = CoreChannelConnection<ChannelData>, ChannelFunctionDisconnection = CoreChannelDisconnection<ChannelData>, ChannelFunctionDefaultMessage = CoreChannelMessage<unknown, unknown, unknown>, ChannelFunctionMessageRoute = CoreChannelMessage<unknown, unknown, unknown>, APIPermission = CoreAPIPermission<ChannelData>> = {
+export type CoreAPIChannel<ChannelData, Channel extends string, ChannelFunctionConnection = CoreChannelConnection<ChannelData>, ChannelFunctionDisconnection = CoreChannelDisconnection<ChannelData>, ChannelFunctionDefaultMessage = CoreChannelMessage<unknown, unknown, unknown> | CoreAPIFunction<unknown, unknown>, ChannelFunctionMessageRoute = CoreChannelMessage<unknown, unknown, unknown> | CoreAPIFunction<unknown, unknown>, APIPermission = CoreAPIPermission<ChannelData>> = {
     name: string;
     route: Channel;
     onConnect?: ChannelFunctionConnection;

package/dist/channel/local/local-channel-runner.d.ts

@@ -1,3 +1,3 @@
 import { CoreAPIChannel, RunChannelOptions, RunChannelParams } from '../channel.types.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
-export declare const runLocalChannel: ({ singletonServices, channelId, request, response, route, createSessionServices, skipUserSession, respondWith404, coerceToArray, logWarningsForStatusCodes, bubbleErrors, }: Pick<CoreAPIChannel<unknown, any>, "route"> & RunChannelOptions & RunChannelParams<unknown>) => Promise<PikkuLocalChannelHandler | void>;
+export declare const runLocalChannel: ({ singletonServices, channelId, request, response, route, createSessionServices, skipUserSession, respondWith404, coerceToArray, logWarningsForStatusCodes, bubbleErrors, }: Partial<Pick<CoreAPIChannel<unknown, any>, "route">> & RunChannelOptions & RunChannelParams<unknown>) => Promise<PikkuLocalChannelHandler | void>;

package/dist/channel/local/local-channel-runner.js

@@ -5,29 +5,35 @@ import { processMessageHandlers } from '../channel-handler.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
 import { handleError } from '../../handle-error.js';
 import { runMiddleware } from '../../middleware-runner.js';
-import { LocalUserSessionService } from '../../services/user-session-service.js';
+import { PikkuUserSessionService } from '../../services/user-session-service.js';
 export const runLocalChannel = async ({ singletonServices, channelId, request, response, route, createSessionServices, skipUserSession = false, respondWith404 = true, coerceToArray = false, logWarningsForStatusCodes = [], bubbleErrors = false, }) => {
     let sessionServices;
     let channelHandler;
-    const userSessionService = new LocalUserSessionService();
-    const http = createHTTPInteraction(request, response);
+    const userSessionService = new PikkuUserSessionService();
+    let http;
+    if (request) {
+        http = createHTTPInteraction(request, response);
+        route = http?.request?.path();
+    }
     const main = async () => {
         try {
             const { openingData, channelConfig } = await openChannel({
                 channelId,
                 createSessionServices,
                 respondWith404,
-                http,
+                request,
+                response,
                 route,
                 singletonServices,
                 skipUserSession,
                 coerceToArray,
+                userSessionService,
             });
             channelHandler = new PikkuLocalChannelHandler(channelId, channelConfig.name, openingData);
             const channel = channelHandler.getChannel();
-            const userSession = await userSessionService.get();
+            const session = await userSessionService.get();
             if (createSessionServices) {
-                sessionServices = await createSessionServices(singletonServices, { http }, userSession);
+                sessionServices = await createSessionServices(singletonServices, { http }, session);
             }
             const allServices = {
                 ...singletonServices,
@@ -43,7 +49,7 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
                     await closeSessionServices(singletonServices.logger, sessionServices);
                 }
             });
-            channelHandler.registerOnMessage(processMessageHandlers(allServices, channelConfig, channelHandler));
+            channelHandler.registerOnMessage(processMessageHandlers(allServices, session, channelConfig, channelHandler));
         }
         catch (e) {
             handleError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
@@ -56,7 +62,7 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
     };
     await runMiddleware({
         ...singletonServices,
-        userSession: userSessionService,
+        userSessionService,
     }, { http }, route.middleware || [], main);
     return channelHandler;
 };

package/dist/channel/serverless/serverless-channel-runner.js

@@ -3,9 +3,10 @@ import { processMessageHandlers } from '../channel-handler.js';
 import { openChannel } from '../channel-runner.js';
 import { createHTTPInteraction } from '../../http/http-route-runner.js';
 import { handleError } from '../../handle-error.js';
-import { RemoteUserSessionService } from '../../services/user-session-service.js';
+import { PikkuUserSessionService } from '../../services/user-session-service.js';
 import { runMiddleware } from '../../middleware-runner.js';
 import { pikkuState } from '../../pikku-state.js';
+import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js';
 const getVariablesForChannel = ({ channelId, channelName, channelHandlerFactory, openingData, }) => {
     const channels = pikkuState('channel', 'channels');
     const channelConfig = channels.find((channelConfig) => channelConfig.name === channelName);
@@ -21,15 +22,19 @@ const getVariablesForChannel = ({ channelId, channelName, channelHandlerFactory,
 };
 export const runChannelConnect = async ({ singletonServices, channelId, channelObject, request, response, route, createSessionServices, channelStore, channelHandlerFactory, coerceToArray = false, logWarningsForStatusCodes = [], respondWith404 = true, bubbleErrors = false, }) => {
     let sessionServices;
-    const http = createHTTPInteraction(request, response);
-    const userSessionService = new RemoteUserSessionService(channelStore, channelId);
+    let http;
+    if (request instanceof Request) {
+        http = createHTTPInteraction(new PikkuFetchHTTPRequest(request), response);
+    }
+    const userSessionService = new PikkuUserSessionService(channelStore, channelId);
     const { channelConfig, openingData } = await openChannel({
         channelId,
         createSessionServices,
-        http,
+        request,
         route,
         singletonServices,
         coerceToArray,
+        userSessionService,
     });
     const main = async () => {
         try {
@@ -48,7 +53,7 @@ export const runChannelConnect = async ({ singletonServices, channelId, channelO
                 sessionServices = await createSessionServices(singletonServices, { http }, await userSessionService.get());
             }
             await channelConfig.onConnect?.({ ...singletonServices, ...sessionServices }, channel);
-            http?.response?.setStatus(101);
+            http?.response?.status(101);
         }
         catch (e) {
             handleError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
@@ -61,7 +66,7 @@ export const runChannelConnect = async ({ singletonServices, channelId, channelO
     };
     await runMiddleware({
         ...singletonServices,
-        userSession: userSessionService,
+        userSessionService,
     }, { http }, channelConfig.middleware || [], main);
 };
 export const runChannelDisconnect = async ({ singletonServices, ...params }) => {
@@ -94,7 +99,7 @@ export const runChannelMessage = async ({ singletonServices, ...params }, data)
     }
     let response;
     try {
-        const onMessage = processMessageHandlers({ ...singletonServices, ...sessionServices }, channelConfig, channelHandler);
+        const onMessage = processMessageHandlers({ ...singletonServices, ...sessionServices }, session, channelConfig, channelHandler);
         response = await onMessage(data);
     }
     finally {

package/dist/handle-error.js

@@ -20,8 +20,8 @@ export const handleError = (e, http, trackerId, logger, logWarningsForStatusCode
     const errorResponse = getErrorResponse(e);
     if (errorResponse != null) {
         // Set status and response body
-        http?.response?.setStatus(errorResponse.status);
-        http?.response?.setJson({
+        http?.response?.status(errorResponse.status);
+        http?.response?.json({
             message: errorResponse.message,
             payload: e.payload,
             traceId: trackerId,
@@ -37,21 +37,23 @@ export const handleError = (e, http, trackerId, logger, logWarningsForStatusCode
     else {
         // Handle unexpected errors
         logger.error(e);
-        http?.response?.setStatus(500);
+        http?.response?.status(500);
         if (trackerId) {
             logger.warn(`Error id: ${trackerId}`);
-            http?.response?.setJson({ errorId: trackerId });
+            http?.response?.json({ errorId: trackerId });
         }
     }
     // Handle 404 errors specifically
     if (e instanceof NotFoundError) {
-        http?.response?.end();
+        // TODO
+        // http?.response?.end()
     }
     // Either bubble up or end the response
     if (bubbleError) {
         throw e;
     }
     else {
-        http?.response?.end();
+        // TODO
+        // http?.response?.end()
     }
 };

package/dist/http/http-route-runner.d.ts

@@ -1,33 +1,90 @@
-import { CoreHTTPFunctionRoute, RunRouteOptions, RunRouteParams, PikkuHTTP } from './http-routes.types.js';
+import { CoreHTTPFunctionRoute, RunRouteOptions, RunRouteParams, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse } from './http-routes.types.js';
 import { PikkuMiddleware } from '../types/core.types.js';
-import { PikkuRequest } from '../pikku-request.js';
-import { PikkuResponse } from '../pikku-response.js';
+import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 /**
- * Add middleware to a specific route or globally
+ * Registers middleware either globally or for a specific route.
  *
- * @param {APIMiddleware[] | string} routeOrMiddleware - Route pattern to match or middleware array
- * @param {APIMiddleware} [middleware] - Middleware to add (required if first param is a string)
+ * When a string route pattern is provided along with middleware, the middleware
+ * is applied only to that route. Otherwise, if an array is provided, it is treated
+ * as global middleware (applied to all routes).
+ *
+ * @template APIMiddleware The middleware type.
+ * @param {APIMiddleware[] | string} routeOrMiddleware - Either a global middleware array or a route pattern string.
+ * @param {APIMiddleware[]} [middleware] - The middleware array to apply when a route pattern is specified.
  */
 export declare const addMiddleware: <APIMiddleware extends PikkuMiddleware>(routeOrMiddleware: APIMiddleware[] | string, middleware?: APIMiddleware[]) => void;
 /**
- * Add a route to the global routes registry
+ * Adds a new route to the global HTTP route registry.
+ *
+ * The route configuration includes the HTTP method, route path, permissions,
+ * middleware, and the handler function that implements the route's logic.
  *
- * @param {CoreHTTPFunctionRoute} route - Route configuration to add
+ * @template In Expected input type.
+ * @template Out Expected output type.
+ * @template Route Route pattern as a string.
+ * @template APIFunction Type for the route handler function.
+ * @template APIFunctionSessionless Type for a sessionless handler.
+ * @template APIPermission Type representing required permissions.
+ * @template APIMiddleware Middleware type to be used with the route.
+ * @param {CoreHTTPFunctionRoute<In, Out, Route, APIFunction, APIFunctionSessionless, APIPermission, APIMiddleware>} route - The route configuration object.
  */
 export declare const addRoute: <In, Out, Route extends string, APIFunction, APIFunctionSessionless, APIPermission, APIMiddleware>(route: CoreHTTPFunctionRoute<In, Out, Route, APIFunction, APIFunctionSessionless, APIPermission, APIMiddleware>) => void;
 /**
- * Create an HTTP interaction object from request and response
+ * Combines the request and response objects into a single HTTP interaction object.
+ *
+ * This utility function creates an object that holds both the HTTP request and response,
+ * which simplifies passing these around through middleware and route execution.
+ *
+ * @param {PikkuHTTPRequest | undefined} request - The HTTP request object.
+ * @param {PikkuHTTPResponse | undefined} response - The HTTP response object.
+ * @returns {PikkuHTTP | undefined} The combined HTTP interaction object or undefined if none provided.
+ */
+export declare const createHTTPInteraction: (request: PikkuHTTPRequest | undefined, response: PikkuHTTPResponse | undefined) => PikkuHTTP | undefined;
+/**
+ * Executes an HTTP route for a given Fetch API request.
  *
- * @param {PikkuRequest | undefined} request - The HTTP request object
- * @param {PikkuResponse | undefined} response - The HTTP response object
- * @returns {PikkuHTTP | undefined} HTTP interaction object or undefined
+ * This function wraps the entire lifecycle of handling an HTTP request:
+ *  - Matching the request to a registered route.
+ *  - Validating input and session state.
+ *  - Running middleware and the route handler.
+ *  - Handling errors and forming the response.
+ *
+ * @template In Expected input data type.
+ * @template Out Expected output data type.
+ * @param {Request} request - The native Fetch API Request object.
+ * @param {RunRouteOptions & RunRouteParams} params - Additional options including services and session management.
+ * @returns {Promise<Response>} A promise that resolves to a Fetch API Response object.
+ */
+export declare const fetch: <In, Out>(request: Request, params: RunRouteOptions & RunRouteParams) => Promise<Response>;
+/**
+ * Executes an HTTP route using a Pikku-specific request wrapper.
+ *
+ * This variant accepts either a native Request or a PikkuHTTPRequest object and returns
+ * a PikkuFetchHTTPResponse for further manipulation if needed.
+ *
+ * @template In Expected input data type.
+ * @template Out Expected output data type.
+ * @param {Request | PikkuHTTPRequest} request - The request object.
+ * @param {RunRouteOptions & RunRouteParams} params - Execution options including services and session configuration.
+ * @returns {Promise<PikkuFetchHTTPResponse>} A promise that resolves to a PikkuFetchHTTPResponse object.
  */
-export declare const createHTTPInteraction: (request: PikkuRequest | undefined, response: PikkuResponse | undefined) => PikkuHTTP | undefined;
+export declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest, params: RunRouteOptions & RunRouteParams) => Promise<PikkuFetchHTTPResponse>;
 /**
- * Run an HTTP route with the given parameters
+ * Core function to process an HTTP request through route matching, validation,
+ * middleware execution, error handling, and session service cleanup.
+ *
+ * This function does the following:
+ *  - Wraps the incoming request and response into an HTTP interaction object.
+ *  - Determines the correct route based on HTTP method and path.
+ *  - Executes middleware and the route handler.
+ *  - Catches and handles errors, optionally bubbling them if configured.
+ *  - Cleans up any session services created during processing.
  *
- * @param {Object} options - Options for running the route
- * @returns {Promise<Out | void>} Result of the route handler
- * @ignore
+ * @template In Expected input data type.
+ * @template Out Expected output data type.
+ * @param {Request | PikkuHTTPRequest} request - The incoming HTTP request.
+ * @param {PikkuHTTPResponse} response - The response object to be populated.
+ * @param {RunRouteOptions & RunRouteParams} options - Options such as singleton services, session handling, and error configuration.
+ * @returns {Promise<Out | void>} The output from the route handler or void if an error occurred.
  */
-export declare const runHTTPRoute: <In, Out>({ singletonServices, request, response, createSessionServices, route: apiRoute, method: apiType, skipUserSession, respondWith404, logWarningsForStatusCodes, coerceToArray, bubbleErrors, }: Pick<CoreHTTPFunctionRoute<unknown, unknown, any>, "route" | "method"> & RunRouteOptions & RunRouteParams<In>) => Promise<Out | void>;
+export declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { singletonServices, createSessionServices, skipUserSession, respondWith404, logWarningsForStatusCodes, coerceToArray, bubbleErrors, }: RunRouteOptions & RunRouteParams) => Promise<Out | void>;