@pikku/core 0.12.71 → 0.12.74

package/src/wirings/gateway/gateway-runner.ts

@@ -10,29 +10,11 @@ import type {
   PikkuGateway,
 } from './gateway.types.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<CoreGateway, Promise<GatewayAdapter>>()
 
-/**
- * The generated function id a gateway's handler is registered under.
- */
 const gatewayHandlerFuncId = (name: string) => `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: PikkuRawWire): Promise<void> => {
   if (wire.session || !wire.getSession) return
   const session = await wire.getSession()
@@ -41,17 +23,7 @@ const bridgeMiddlewareSession = async (wire: PikkuRawWire): Promise<void> => {
   }
 }
 
-/**
- * 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: CoreGateway): string => {
   const funcId = gatewayHandlerFuncId(config.name)
   const funcMeta = pikkuState(null, 'function', 'meta')
@@ -86,17 +58,7 @@ import type {
   CoreSingletonServices,
 } from '../../types/core.types.js'
 
-/**
- * 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: CoreGateway): void => {
-  // Store gateway config
   pikkuState(null, 'gateway', 'gateways').set(config.name, config)
 
   switch (config.type) {
@@ -116,10 +78,6 @@ export const wireGateway = (config: CoreGateway): void => {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Webhook gateway — platform POSTs to us
-// ---------------------------------------------------------------------------
-
 const wireWebhookGateway = (config: CoreGateway): void => {
   const { name, route, adapter } = config
   if (!route) {
@@ -129,11 +87,6 @@ const wireWebhookGateway = (config: CoreGateway): void => {
   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),
@@ -151,10 +104,7 @@ const wireWebhookGateway = (config: CoreGateway): void => {
     auth: false,
   } as any)
 
-  // --- 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`
 
@@ -173,27 +123,14 @@ const wireWebhookGateway = (config: CoreGateway): void => {
       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,
     } as any)
   }
 
-  // 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: CoreGateway) => {
   const { name, middleware: userMiddleware } = config
   const handlerFuncId = registerGatewayHandler(config)
@@ -205,7 +142,6 @@ const createWebhookPostHandler = (config: CoreGateway) => {
   ) => {
     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) {
@@ -213,14 +149,11 @@ const createWebhookPostHandler = (config: CoreGateway) => {
       }
     }
 
-    // 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: PikkuGateway = {
       gatewayName: name,
       senderId: parsed.senderId,
@@ -229,10 +162,7 @@ const createWebhookPostHandler = (config: CoreGateway) => {
     }
     ;(wire as any).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 as any)
       return await runPikkuFunc('gateway', name, handlerFuncId, {
@@ -250,7 +180,6 @@ const createWebhookPostHandler = (config: CoreGateway) => {
       ? 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 as GatewayOutboundMessage)
     }
@@ -258,10 +187,6 @@ const createWebhookPostHandler = (config: CoreGateway) => {
   }
 }
 
-/**
- * Creates the GET handler for webhook verification challenges.
- * Passes query parameters to the adapter's verifyWebhook method.
- */
 const createWebhookVerifyHandler = (config: CoreGateway) => {
   return async (
     services: CoreSingletonServices,
@@ -280,7 +205,7 @@ const createWebhookVerifyHandler = (config: CoreGateway) => {
     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)
@@ -290,17 +215,12 @@ const createWebhookVerifyHandler = (config: CoreGateway) => {
   }
 }
 
-// ---------------------------------------------------------------------------
-// WebSocket gateway — client connects via WebSocket
-// ---------------------------------------------------------------------------
-
 const wireWebsocketGateway = (config: CoreGateway): void => {
   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')
@@ -309,7 +229,6 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
   const messageFuncId = `gateway__${name}__message`
   const connectFuncId = `gateway__${name}__connect`
 
-  // Add function metadata
   const funcMeta = pikkuState(null, 'function', 'meta')
   funcMeta[messageFuncId] = {
     pikkuFuncId: messageFuncId,
@@ -324,7 +243,6 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
     sessionless: true,
   }
 
-  // Add channel metadata
   channelsMeta[name] = {
     name,
     route,
@@ -336,7 +254,6 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
   const handlerFuncId = registerGatewayHandler(config)
 
-  // Register onConnect
   addFunction(connectFuncId, {
     auth: false,
     func: async (services: any, _data: unknown, wire: PikkuWire) => {
@@ -352,7 +269,6 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
     },
   } as any)
 
-  // Register onMessage
   addFunction(messageFuncId, {
     auth: false,
     func: async (services: any, data: unknown, wire: PikkuWire) => {
@@ -393,7 +309,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
     },
   } as any)
 
-  // Store channel config
+  // knowledge: decisions/internals/gateway-wiring-is-a-meta-wiring-over-http-and-channels.md
   channels.set(name, {
     name,
     route,
@@ -402,32 +318,14 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
     onMessage: { func: async () => {} },
   } as any)
 
-  // Force router to re-initialize
   httpRouter.reset()
 }
 
-// ---------------------------------------------------------------------------
-// Listener gateway — standalone event loop, no route
-// ---------------------------------------------------------------------------
-
 const wireListenerGateway = (config: CoreGateway): void => {
-  // 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: string,
   config: CoreGateway,

package/src/wirings/gateway/gateway.types.ts

@@ -7,9 +7,6 @@ import type {
 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
@@ -18,140 +15,73 @@ export interface GatewayAttachment {
   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
@@ -161,7 +91,4 @@ export type GatewayMeta = CommonWireMeta & {
   gateway: true
 }
 
-/**
- * All gateway metadata keyed by name
- */
 export type GatewaysMeta = Record<string, GatewayMeta>

package/src/wirings/http/http-routes.test.ts

@@ -6,15 +6,12 @@ import { addFunction } from '../../function/function-runner.js'
 import { httpRouter } from './routers/http-router.js'
 import type { CorePikkuMiddleware } from '../../types/core.types.js'
 
-// Mock function for testing
 const mockFunc = async () => ({ success: true })
 
-// Mock middleware
 const mockMiddleware: CorePikkuMiddleware = async (_services, _wire, next) => {
   await next()
 }
 
-// Helper to set up function metadata for routes
 const setupFunctionMeta = (
   routes: Array<{ method: string; route: string }>
 ) => {

package/src/wirings/http/http-routes.ts

@@ -7,29 +7,6 @@ import type {
 } from './http.types.js'
 import { wireHTTP } from './http-runner.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 function defineHTTPRoutes<T extends HTTPRouteMap>(
   routes: T
 ): HTTPRouteContract<T>
@@ -39,7 +16,6 @@ export function defineHTTPRoutes<T extends HTTPRouteMap>(
 export function defineHTTPRoutes<T extends HTTPRouteMap>(
   configOrRoutes: T | (HTTPRoutesGroupConfig & { routes: T })
 ): HTTPRouteContract<T> {
-  // 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' &&
@@ -47,50 +23,9 @@ export function defineHTTPRoutes<T extends HTTPRouteMap>(
   ) {
     return configOrRoutes as HTTPRouteContract<T>
   }
-  // Otherwise it's just routes
   return { routes: configOrRoutes as 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 const wireHTTPRoutes = (config: WireHTTPRoutesConfig): void => {
   const { routes, ...groupConfig } = config
 
@@ -101,9 +36,6 @@ export const wireHTTPRoutes = (config: WireHTTPRoutesConfig): void => {
   }
 }
 
-/**
- * Recursively processes a route map, handling nested maps and contracts
- */
 function processRouteMap(
   map: HTTPRouteMap,
   parentConfig: HTTPRoutesGroupConfig
@@ -112,23 +44,14 @@ function processRouteMap(
     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 as HTTPRouteMap, 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: HTTPRoutesGroupConfig,
   child: HTTPRoutesGroupConfig
@@ -141,9 +64,6 @@ function mergeGroupConfig(
   }
 }
 
-/**
- * Registers a single route by calling wireHTTP with merged configuration
- */
 function registerRoute(
   route: HTTPRouteConfig,
   groupConfig: HTTPRoutesGroupConfig
@@ -167,9 +87,6 @@ function registerRoute(
   } as any)
 }
 
-/**
- * Type guard to check if a value is an individual route config
- */
 function isRouteConfig(value: unknown): value is HTTPRouteConfig {
   return (
     typeof value === 'object' &&
@@ -180,9 +97,6 @@ function isRouteConfig(value: unknown): value is HTTPRouteConfig {
   )
 }
 
-/**
- * Type guard to check if a value is a route contract (has routes property but is not a route config)
- */
 function isRouteContract(value: unknown): value is HTTPRouteContract {
   return (
     typeof value === 'object' &&

package/src/wirings/http/http-runner.test.ts

@@ -187,7 +187,6 @@ describe('fetch', () => {
       func: { func: routeFunc, middleware: [sessionMiddleware] },
     })
 
-    // Initialize router after adding route (for tests)
     httpRouter.initialize()
 
     const result = await fetch(request)