@pikku/core 0.12.71 → 0.12.74

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

@@ -3,27 +3,9 @@ import { NotFoundError, UnauthorizedError } from '../../errors/errors.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { runMiddleware } from '../../middleware-runner.js';
 import { httpRouter } from '../http/routers/http-router.js';
-/**
- * Lazily resolve a gateway's adapter. Factories are invoked once with the
- * singleton services and cached (promise-cached, so concurrent first
- * requests share one construction).
- */
 const resolvedAdapters = new WeakMap();
-/**
- * The generated function id a gateway's handler is registered under.
- */
 const gatewayHandlerFuncId = (name) => `gateway__${name}__handler`;
-/**
- * Bridges a session established by gateway middleware onto the wire so the
- * handler's gate can see it.
- *
- * Gateway middleware is the only place a webhook can acquire a session (e.g.
- * mapping a verified platform sender to a user). Middleware that assigns
- * `wire.session` needs nothing, but middleware using the idiomatic
- * `wire.setSession()` writes to the enclosing wiring's session service, which
- * the handler's own invocation does not read — without this the session would
- * be silently invisible to `auth` and `scopes`.
- */
+// knowledge: decisions/security/gateway-middleware-sessions-must-be-bridged-onto-the-wire.md
 const bridgeMiddlewareSession = async (wire) => {
     if (wire.session || !wire.getSession)
         return;
@@ -32,17 +14,7 @@ const bridgeMiddlewareSession = async (wire) => {
         wire.session = session;
     }
 };
-/**
- * Registers a gateway's handler as a real pikku function so that invoking it
- * goes through the function runner's gate. Without this the handler is called
- * directly and its own `auth`, `scopes` and `permissions` are never evaluated.
- *
- * The handler is registered as sessionless: a gateway's inbound traffic is
- * platform-authenticated (adapter signature verification), not session-bearing,
- * so requiring a session by default would break every webhook. A handler that
- * does need one declares `auth: true`, exactly like `pikkuSessionlessFunc`.
- * `scopes` and `permissions` are always enforced when declared.
- */
+// knowledge: decisions/security/gateway-handlers-run-through-the-function-runner-gate.md
 const registerGatewayHandler = (config) => {
     const funcId = gatewayHandlerFuncId(config.name);
     const funcMeta = pikkuState(null, 'function', 'meta');
@@ -66,17 +38,7 @@ export const resolveGatewayAdapter = (config, services) => {
     }
     return resolved;
 };
-/**
- * Register a messaging gateway.
- *
- * `wireGateway` is a meta-wiring that composes existing primitives
- * (`wireHTTP`, `wireChannel`) under the hood.  It does not replace them;
- * it layers on top.
- *
- * @param config - Gateway configuration (name, type, adapter, func, middleware, etc.)
- */
 export const wireGateway = (config) => {
-    // Store gateway config
     pikkuState(null, 'gateway', 'gateways').set(config.name, config);
     switch (config.type) {
         case 'webhook':
@@ -92,9 +54,6 @@ export const wireGateway = (config) => {
             throw new Error(`Unknown gateway type '${config.type}' for gateway '${config.name}'`);
     }
 };
-// ---------------------------------------------------------------------------
-// Webhook gateway — platform POSTs to us
-// ---------------------------------------------------------------------------
 const wireWebhookGateway = (config) => {
     const { name, route, adapter } = config;
     if (!route) {
@@ -102,10 +61,6 @@ const wireWebhookGateway = (config) => {
     }
     const postFuncId = `gateway__${name}__post`;
     const routes = pikkuState(null, 'http', 'routes');
-    // --- POST handler (main message receiver) --------------------------------
-    // Meta for these wrapper funcs/routes is compiled — the inspector projects
-    // wireGateway into the generated HTTP + function meta; only the handler
-    // implementations register here, same as every other wire.
     const postHandler = {
         auth: false,
         func: createWebhookPostHandler(config),
@@ -120,9 +75,7 @@ const wireWebhookGateway = (config) => {
         func: postHandler,
         auth: false,
     });
-    // --- GET handler (webhook verification, e.g. WhatsApp challenge) ---------
-    // Factory adapters can't be probed for verifyWebhook until first resolve,
-    // so register the GET route unconditionally for them.
+    // knowledge: decisions/internals/gateway-adapters-resolve-lazily-and-are-promise-cached.md
     if (typeof adapter === 'function' || adapter.verifyWebhook) {
         const verifyFuncId = `gateway__${name}__verify`;
         const verifyHandler = {
@@ -138,44 +91,27 @@ const wireWebhookGateway = (config) => {
             route,
             func: verifyHandler,
             auth: false,
-            // challenge echo must be byte-identical — no JSON quoting
+            // knowledge: decisions/internals/gateway-webhook-challenges-echo-bytes-not-json.md
             returnsJSON: false,
         });
     }
-    // Force router to re-initialize on next match
     httpRouter.reset();
 };
-/**
- * Creates the POST handler function for a webhook gateway.
- *
- * Flow:
- *  1. Check for POST-based verification (e.g. Slack `url_verification`)
- *  2. Parse body via adapter → GatewayInboundMessage (or null to ignore)
- *  3. Populate `wire.gateway`
- *  4. Run user middleware (which can read `wire.gateway` for auth)
- *  5. Invoke the handler through the function runner, which enforces its
- *     `auth`/`scopes`/`permissions` before running it
- *  6. Auto-send response via adapter if func returns outbound content
- */
 const createWebhookPostHandler = (config) => {
     const { name, middleware: userMiddleware } = config;
     const handlerFuncId = registerGatewayHandler(config);
     return async (services, data, wire) => {
         const adapter = await resolveGatewayAdapter(config, services);
-        // Check for POST-based webhook verification (e.g. Slack url_verification)
         if (adapter.verifyWebhook) {
             const verifyResult = await adapter.verifyWebhook(data, wire.http?.request);
             if (verifyResult.verified) {
                 return verifyResult.response;
             }
         }
-        // Parse the platform-specific payload
         const parsed = adapter.parse(data);
         if (!parsed) {
-            // Ignored event (delivery receipt, typing indicator, etc.)
             return { ok: true };
         }
-        // Populate wire.gateway
         const gateway = {
             gatewayName: name,
             senderId: parsed.senderId,
@@ -183,10 +119,7 @@ const createWebhookPostHandler = (config) => {
             send: (msg) => adapter.send(parsed.senderId, msg),
         };
         wire.gateway = gateway;
-        // Gateway middleware runs first and outside the gate, so it can establish
-        // the session the gate then checks. The handler is invoked through the
-        // function runner, which enforces its auth, scopes and permissions and
-        // applies the handler's own middleware.
+        // Gateway middleware runs outside the gate so it can establish the session the gate checks.
         const invoke = async () => {
             await bridgeMiddlewareSession(wire);
             return await runPikkuFunc('gateway', name, handlerFuncId, {
@@ -200,17 +133,12 @@ const createWebhookPostHandler = (config) => {
         const result = gatewayMiddleware?.length
             ? await runMiddleware(services, wire, gatewayMiddleware, invoke)
             : await invoke();
-        // Auto-send response if the func returns outbound content
         if (result && (result.text || result.richContent || result.attachments)) {
             await adapter.send(parsed.senderId, result);
         }
         return { ok: true };
     };
 };
-/**
- * Creates the GET handler for webhook verification challenges.
- * Passes query parameters to the adapter's verifyWebhook method.
- */
 const createWebhookVerifyHandler = (config) => {
     return async (services, _data, wire) => {
         const adapter = await resolveGatewayAdapter(config, services);
@@ -222,7 +150,7 @@ const createWebhookVerifyHandler = (config) => {
         if (!result.verified) {
             throw new UnauthorizedError('Webhook verification failed');
         }
-        // string challenges echo raw (byte-for-byte compare); objects stay JSON
+        // knowledge: decisions/internals/gateway-webhook-challenges-echo-bytes-not-json.md
         const response = result.response;
         if (typeof response === 'string' || typeof response === 'number') {
             return String(response);
@@ -231,21 +159,16 @@ const createWebhookVerifyHandler = (config) => {
         return JSON.stringify(response);
     };
 };
-// ---------------------------------------------------------------------------
-// WebSocket gateway — client connects via WebSocket
-// ---------------------------------------------------------------------------
 const wireWebsocketGateway = (config) => {
     const { name, route } = config;
     if (!route) {
         throw new Error(`WebSocket gateway '${name}' requires a route`);
     }
-    // Store gateway config — the channel runner will reference this
     pikkuState(null, 'gateway', 'gateways').set(config.name, config);
     const channelsMeta = pikkuState(null, 'channel', 'meta');
     const channels = pikkuState(null, 'channel', 'channels');
     const messageFuncId = `gateway__${name}__message`;
     const connectFuncId = `gateway__${name}__connect`;
-    // Add function metadata
     const funcMeta = pikkuState(null, 'function', 'meta');
     funcMeta[messageFuncId] = {
         pikkuFuncId: messageFuncId,
@@ -259,7 +182,6 @@ const wireWebsocketGateway = (config) => {
         outputSchemaName: null,
         sessionless: true,
     };
-    // Add channel metadata
     channelsMeta[name] = {
         name,
         route,
@@ -269,7 +191,6 @@ const wireWebsocketGateway = (config) => {
     };
     const userMiddleware = config.middleware;
     const handlerFuncId = registerGatewayHandler(config);
-    // Register onConnect
     addFunction(connectFuncId, {
         auth: false,
         func: async (services, _data, wire) => {
@@ -284,7 +205,6 @@ const wireWebsocketGateway = (config) => {
             };
         },
     });
-    // Register onMessage
     addFunction(messageFuncId, {
         auth: false,
         func: async (services, data, wire) => {
@@ -319,7 +239,7 @@ const wireWebsocketGateway = (config) => {
             }
         },
     });
-    // Store channel config
+    // knowledge: decisions/internals/gateway-wiring-is-a-meta-wiring-over-http-and-channels.md
     channels.set(name, {
         name,
         route,
@@ -327,29 +247,12 @@ const wireWebsocketGateway = (config) => {
         onConnect: { func: async () => { } },
         onMessage: { func: async () => { } },
     });
-    // Force router to re-initialize
     httpRouter.reset();
 };
-// ---------------------------------------------------------------------------
-// Listener gateway — standalone event loop, no route
-// ---------------------------------------------------------------------------
 const wireListenerGateway = (config) => {
-    // Listener gateways don't register routes.
-    // They are started manually and call into the gateway's func directly.
-    // The gateway config is already stored in pikkuState.
     pikkuState(null, 'gateway', 'gateways').set(config.name, config);
 };
-/**
- * Create the message handler callback for a listener gateway.
- *
- * Returns a function `(rawData: unknown) => Promise<void>` that can be
- * passed to `adapter.init()`.  Used by `LocalGatewayService` (and any
- * other GatewayService implementation) to wire up listener gateways.
- *
- * @param name   - Gateway name (for wire.gateway metadata)
- * @param config - The gateway configuration (adapter, func, middleware)
- * @param singletonServices - Singleton services to pass to handler/middleware
- */
+/** The returned callback is what a GatewayService passes to `adapter.init()`. */
 export const createListenerMessageHandler = (name, config, singletonServices) => {
     const userMiddleware = config.middleware;
     const handlerFuncId = registerGatewayHandler(config);

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

@@ -1,9 +1,6 @@
 import type { CommonWireMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CoreSingletonServices } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { PikkuHTTPRequest } from '../http/http.types.js';
-/**
- * Attachment in gateway messages (images, files, etc.)
- */
 export interface GatewayAttachment {
     type: string;
     url?: string;
@@ -11,125 +8,58 @@ export interface GatewayAttachment {
     mimeType?: string;
     filename?: string;
 }
-/**
- * Normalized inbound message from any platform
- */
 export interface GatewayInboundMessage {
-    /** Platform-specific sender identifier (phone number, Slack user ID, etc.) */
+    /** Platform-specific: a phone number, a Slack user id, and so on. */
     senderId: string;
-    /** Message text content */
     text: string;
-    /** Original platform-specific payload */
     raw: unknown;
-    /** Optional file/media attachments */
     attachments?: GatewayAttachment[];
-    /** Optional platform-specific metadata */
     metadata?: Record<string, unknown>;
 }
-/**
- * Outbound message to send back via the platform
- */
 export interface GatewayOutboundMessage {
-    /** Plain text response */
     text?: string;
-    /** Platform-specific rich content (Slack blocks, WhatsApp templates, etc.) */
     richContent?: Record<string, unknown>;
-    /** Optional file/media attachments */
     attachments?: GatewayAttachment[];
 }
-/**
- * Result of webhook verification (e.g., WhatsApp GET challenge, Slack url_verification)
- */
 export type WebhookVerificationResult = {
     verified: true;
     response: unknown;
 } | {
     verified: false;
 };
-/**
- * Gateway adapter interface — implemented by platform-specific addon packages.
- *
- * Two responsibilities:
- * 1. Parse incoming platform-specific format into normalized GatewayInboundMessage
- * 2. Send outgoing GatewayOutboundMessage via the platform's API
- */
 export interface GatewayAdapter {
-    /** Platform name (e.g., 'whatsapp', 'slack', 'telegram') */
     name: string;
-    /** Parse platform-specific payload into normalized message. Return null to ignore (e.g., delivery receipts). */
+    /** Return null to ignore the event, e.g. a delivery receipt. */
     parse(data: unknown): GatewayInboundMessage | null;
-    /** Send a message to a specific sender via the platform's API */
     send(senderId: string, message: GatewayOutboundMessage): Promise<void>;
-    /** Initialize the adapter (connect to platform, start listening).
-     *  Called by GatewayService.start() — the adapter should call onMessage for each incoming event. */
+    /** Called by GatewayService.start(); must call onMessage per incoming event. */
     init(onMessage: (data: unknown) => Promise<void>): Promise<void>;
-    /** Tear down the adapter (disconnect, release resources). */
     close(): Promise<void>;
-    /** Handle webhook verification challenges (only for webhook type).
-     *  Receives the data (body or query params) and the Pikku HTTP request for additional inspection. */
+    /** Receives the GET query params, or the POST body when called from the POST handler. */
     verifyWebhook?(data: unknown, request?: PikkuHTTPRequest): WebhookVerificationResult | Promise<WebhookVerificationResult>;
 }
-/**
- * Factory that builds a GatewayAdapter from singleton services.
- *
- * Real platform adapters (WhatsApp Cloud API, Slack, …) need secrets or
- * services that only exist after boot, while `wireGateway` runs at module
- * load. Pass a factory instead of an instance and it is resolved lazily on
- * the first inbound request (webhook/websocket) or on gateway start
- * (listener), then cached for the lifetime of the gateway.
- */
 export type GatewayAdapterFactory = (services: CoreSingletonServices) => GatewayAdapter | Promise<GatewayAdapter>;
-/**
- * The gateway wire object available on wire.gateway inside handler functions and middleware
- */
 export interface PikkuGateway {
-    /** Name of this gateway instance */
     gatewayName: string;
-    /** Platform-specific sender identifier */
     senderId: string;
-    /** Platform name from adapter.name */
     platform: string;
-    /** Send a proactive message to the sender */
     send(msg: GatewayOutboundMessage): Promise<void>;
 }
-/**
- * Gateway transport type:
- * - 'webhook': Platform POSTs to us (WhatsApp Cloud API, Slack Events API, Telegram webhooks)
- * - 'websocket': Client connects via WebSocket (WebChat, browser widget)
- * - 'listener': Standalone event loop, no route (Baileys, Signal CLI, Matrix sync)
- */
+/** 'webhook' the platform POSTs to us, 'websocket' the client connects to us, 'listener' no route at all. */
 export type GatewayTransportType = 'webhook' | 'websocket' | 'listener';
-/**
- * Core gateway configuration for wireGateway()
- */
 export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware> = Partial<Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>> & {
-    /** Unique name for this gateway */
     name: string;
-    /** Transport type */
     type: GatewayTransportType;
-    /** HTTP route for webhook/websocket types */
+    /** Required for 'webhook' and 'websocket'; unused for 'listener'. */
     route?: string;
     platform?: string;
-    /** The gateway adapter (parse inbound, send outbound), or a factory
-     *  resolved lazily from singleton services (for adapters needing secrets) */
     adapter: GatewayAdapter | GatewayAdapterFactory;
-    /** The handler function that processes parsed messages */
     func: PikkuFunctionConfig;
-    /** Optional middleware chain (e.g., auth) */
     middleware?: CorePikkuMiddlewareGroup<any, any>;
-    /** Optional tags for categorization */
     tags?: string[];
-    /**
-     * Whether the handler requires a session. Left unset, the handler's own
-     * `auth` governs, and a gateway handler is sessionless by default — inbound
-     * gateway traffic is platform-authenticated by the adapter, not
-     * session-bearing. Set `true` to require a session for every message.
-     */
+    /** Unset lets the handler's own `auth` govern; gateway handlers are sessionless by default. */
     auth?: boolean;
 };
-/**
- * Metadata for a registered gateway, stored in state
- */
 export type GatewayMeta = CommonWireMeta & {
     name: string;
     type: GatewayTransportType;
@@ -138,7 +68,4 @@ export type GatewayMeta = CommonWireMeta & {
     auth?: boolean;
     gateway: true;
 };
-/**
- * All gateway metadata keyed by name
- */
 export type GatewaysMeta = Record<string, GatewayMeta>;

package/dist/wirings/http/http-routes.d.ts

@@ -1,69 +1,6 @@
 import type { HTTPRouteMap, HTTPRouteContract, HTTPRoutesGroupConfig, WireHTTPRoutesConfig } from './http.types.js';
-/**
- * Type-safe helper for defining route contracts that can be composed.
- * Supports optional group-level config that cascades to all routes.
- *
- * @example
- * ```typescript
- * // Simple routes without group config
- * export const todosRoutes = defineHTTPRoutes({
- *   list: { method: 'get', route: '/todos', func: listTodos },
- *   get: { method: 'get', route: '/todos/:id', func: getTodo },
- * })
- *
- * // Routes with group-level config
- * export const todosRoutes = defineHTTPRoutes({
- *   auth: true,
- *   tags: ['todos'],
- *   routes: {
- *     list: { method: 'get', route: '/todos', func: listTodos },
- *     get: { method: 'get', route: '/todos/:id', func: getTodo },
- *   }
- * })
- * ```
- */
 export declare function defineHTTPRoutes<T extends HTTPRouteMap>(routes: T): HTTPRouteContract<T>;
 export declare function defineHTTPRoutes<T extends HTTPRouteMap>(config: HTTPRoutesGroupConfig & {
     routes: T;
 }): HTTPRouteContract<T>;
-/**
- * Wires multiple HTTP routes from a nested map or array configuration.
- * Inspired by ts-rest's contract pattern, provides a single place to wire an entire API.
- *
- * @example
- * ```typescript
- * // Nested object format
- * wireHTTPRoutes({
- *   basePath: '/api/v1',
- *   tags: ['api'],
- *   routes: {
- *     todos: {
- *       list: { method: 'get', route: '/todos', func: listTodos },
- *       get: { method: 'get', route: '/todos/:id', func: getTodo },
- *     },
- *     auth: {
- *       login: { method: 'post', route: '/auth/login', func: login, auth: false },
- *     },
- *   },
- * })
- *
- * // Flat array format
- * wireHTTPRoutes({
- *   basePath: '/api',
- *   routes: [
- *     { method: 'get', route: '/todos', func: listTodos },
- *     { method: 'post', route: '/todos', func: createTodo },
- *   ],
- * })
- *
- * // Composing route contracts
- * wireHTTPRoutes({
- *   basePath: '/api/v1',
- *   routes: {
- *     todos: todosRoutes,  // from defineHTTPRoutes()
- *     auth: authRoutes,    // from defineHTTPRoutes()
- *   },
- * })
- * ```
- */
 export declare const wireHTTPRoutes: (config: WireHTTPRoutesConfig) => void;

package/dist/wirings/http/http-routes.js

@@ -1,54 +1,12 @@
 import { wireHTTP } from './http-runner.js';
 export function defineHTTPRoutes(configOrRoutes) {
-    // If it has a 'routes' property and contains a map (not a route config), it's config + routes
     if ('routes' in configOrRoutes &&
         typeof configOrRoutes.routes === 'object' &&
         !isRouteConfig(configOrRoutes.routes)) {
         return configOrRoutes;
     }
-    // Otherwise it's just routes
     return { routes: configOrRoutes };
 }
-/**
- * Wires multiple HTTP routes from a nested map or array configuration.
- * Inspired by ts-rest's contract pattern, provides a single place to wire an entire API.
- *
- * @example
- * ```typescript
- * // Nested object format
- * wireHTTPRoutes({
- *   basePath: '/api/v1',
- *   tags: ['api'],
- *   routes: {
- *     todos: {
- *       list: { method: 'get', route: '/todos', func: listTodos },
- *       get: { method: 'get', route: '/todos/:id', func: getTodo },
- *     },
- *     auth: {
- *       login: { method: 'post', route: '/auth/login', func: login, auth: false },
- *     },
- *   },
- * })
- *
- * // Flat array format
- * wireHTTPRoutes({
- *   basePath: '/api',
- *   routes: [
- *     { method: 'get', route: '/todos', func: listTodos },
- *     { method: 'post', route: '/todos', func: createTodo },
- *   ],
- * })
- *
- * // Composing route contracts
- * wireHTTPRoutes({
- *   basePath: '/api/v1',
- *   routes: {
- *     todos: todosRoutes,  // from defineHTTPRoutes()
- *     auth: authRoutes,    // from defineHTTPRoutes()
- *   },
- * })
- * ```
- */
 export const wireHTTPRoutes = (config) => {
     const { routes, ...groupConfig } = config;
     if (Array.isArray(routes)) {
@@ -58,32 +16,20 @@ export const wireHTTPRoutes = (config) => {
         processRouteMap(routes, groupConfig);
     }
 };
-/**
- * Recursively processes a route map, handling nested maps and contracts
- */
 function processRouteMap(map, parentConfig) {
     for (const [_key, value] of Object.entries(map)) {
         if (isRouteConfig(value)) {
             registerRoute(value, parentConfig);
         }
         else if (isRouteContract(value)) {
-            // Merge parent config with contract config, then process routes
             const mergedConfig = mergeGroupConfig(parentConfig, value);
             processRouteMap(value.routes, mergedConfig);
         }
         else {
-            // Nested map without config
             processRouteMap(value, parentConfig);
         }
     }
 }
-/**
- * Merge group configs with proper cascading behavior:
- * - basePath: Concatenates
- * - tags: Merges (parent + child)
- * - middleware: Merges (parent runs first)
- * - auth: Inner overrides outer
- */
 function mergeGroupConfig(parent, child) {
     return {
         basePath: (parent.basePath || '') + (child.basePath || ''),
@@ -92,9 +38,6 @@ function mergeGroupConfig(parent, child) {
         auth: child.auth ?? parent.auth,
     };
 }
-/**
- * Registers a single route by calling wireHTTP with merged configuration
- */
 function registerRoute(route, groupConfig) {
     const fullRoute = (groupConfig.basePath || '') + route.route;
     wireHTTP({
@@ -113,9 +56,6 @@ function registerRoute(route, groupConfig) {
         sse: route.sse,
     });
 }
-/**
- * Type guard to check if a value is an individual route config
- */
 function isRouteConfig(value) {
     return (typeof value === 'object' &&
         value !== null &&
@@ -123,9 +63,6 @@ function isRouteConfig(value) {
         'func' in value &&
         'route' in value);
 }
-/**
- * Type guard to check if a value is a route contract (has routes property but is not a route config)
- */
 function isRouteContract(value) {
     return (typeof value === 'object' &&
         value !== null &&