@pikku/core 0.12.1 → 0.12.2

package/dist/wirings/channel/pikku-abstract-channel-handler.d.ts

@@ -1,4 +1,4 @@
-import type { PikkuChannel, PikkuChannelHandler } from './channel.types.js';
+import type { BinaryData, PikkuChannel, PikkuChannelHandler } from './channel.types.js';
 export declare abstract class PikkuAbstractChannelHandler<OpeningData = unknown, Out = unknown> implements PikkuChannelHandler<OpeningData, Out> {
     channelId: string;
     channelName: string;
@@ -6,6 +6,7 @@ export declare abstract class PikkuAbstractChannelHandler<OpeningData = unknown,
     protected channel?: PikkuChannel<OpeningData, Out>;
     constructor(channelId: string, channelName: string, openingData: OpeningData);
     abstract send(message: Out, isBinary?: boolean): Promise<void> | void;
+    abstract sendBinary(data: BinaryData): Promise<void> | void;
     getChannel(): PikkuChannel<OpeningData, Out>;
     open(): void;
     close(): Promise<void> | void;

package/dist/wirings/channel/pikku-abstract-channel-handler.js

@@ -14,6 +14,7 @@ export class PikkuAbstractChannelHandler {
                 channelId: this.channelId,
                 openingData: this.openingData,
                 send: this.send.bind(this),
+                sendBinary: this.sendBinary.bind(this),
                 close: this.close.bind(this),
                 state: 'initial',
             };

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

@@ -171,7 +171,7 @@ export const runChannelMessage = async ({ channelId, channelStore, channelHandle
     };
     let response;
     try {
-        const onMessage = processMessageHandlers(services, channelConfig, channelHandler, userSession);
+        const { onMessage } = processMessageHandlers(services, channelConfig, channelHandler, userSession);
         response = await onMessage(data);
     }
     catch (e) {

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

@@ -207,6 +207,9 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
                 await Promise.resolve(renderer(singletonServices, data, undefined));
             }
         },
+        sendBinary: () => {
+            throw new Error('Binary data is not supported on CLI channels');
+        },
         close: () => {
             if (channel) {
                 channel.state = 'closed';

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

@@ -0,0 +1,24 @@
+import type { CoreGateway } from './gateway.types.js';
+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 declare const wireGateway: (config: CoreGateway) => void;
+/**
+ * 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
+ */
+export declare const createListenerMessageHandler: (name: string, config: CoreGateway, singletonServices: CoreSingletonServices) => ((rawData: unknown) => Promise<void>);

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

@@ -0,0 +1,325 @@
+import { pikkuState } from '../../pikku-state.js';
+import { addFunction } from '../../function/function-runner.js';
+import { runMiddleware } from '../../middleware-runner.js';
+import { httpRouter } from '../http/routers/http-router.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) => {
+    // Store gateway config
+    pikkuState(null, 'gateway', 'gateways').set(config.name, config);
+    switch (config.type) {
+        case 'webhook':
+            wireWebhookGateway(config);
+            break;
+        case 'websocket':
+            wireWebsocketGateway(config);
+            break;
+        case 'listener':
+            wireListenerGateway(config);
+            break;
+        default:
+            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) {
+        throw new Error(`Webhook gateway '${name}' requires a route`);
+    }
+    const postFuncId = `gateway__${name}__post`;
+    const httpMeta = pikkuState(null, 'http', 'meta');
+    const funcMeta = pikkuState(null, 'function', 'meta');
+    const routes = pikkuState(null, 'http', 'routes');
+    // --- POST handler (main message receiver) --------------------------------
+    funcMeta[postFuncId] = {
+        pikkuFuncId: postFuncId,
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sessionless: true,
+    };
+    httpMeta['post'][route] = {
+        pikkuFuncId: postFuncId,
+        route,
+        method: 'post',
+    };
+    const postHandler = {
+        auth: false,
+        func: createWebhookPostHandler(config),
+    };
+    addFunction(postFuncId, postHandler);
+    if (!routes.has('post')) {
+        routes.set('post', new Map());
+    }
+    routes.get('post').set(route, {
+        method: 'post',
+        route,
+        func: postHandler,
+        auth: false,
+    });
+    // --- GET handler (webhook verification, e.g. WhatsApp challenge) ---------
+    if (adapter.verifyWebhook) {
+        const verifyFuncId = `gateway__${name}__verify`;
+        funcMeta[verifyFuncId] = {
+            pikkuFuncId: verifyFuncId,
+            inputSchemaName: null,
+            outputSchemaName: null,
+            sessionless: true,
+        };
+        httpMeta['get'][route] = {
+            pikkuFuncId: verifyFuncId,
+            route,
+            method: 'get',
+        };
+        const verifyHandler = {
+            auth: false,
+            func: createWebhookVerifyHandler(adapter),
+        };
+        addFunction(verifyFuncId, verifyHandler);
+        if (!routes.has('get')) {
+            routes.set('get', new Map());
+        }
+        routes.get('get').set(route, {
+            method: 'get',
+            route,
+            func: verifyHandler,
+            auth: 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. Call user func with parsed message
+ *  6. Auto-send response via adapter if func returns outbound content
+ */
+const createWebhookPostHandler = (config) => {
+    const { name, adapter, func: userFunc, middleware: userMiddleware } = config;
+    const userFuncConfig = userFunc;
+    return async (services, data, wire) => {
+        // 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,
+            platform: adapter.name,
+            send: (msg) => adapter.send(parsed.senderId, msg),
+        };
+        wire.gateway = gateway;
+        // Build combined middleware chain: gateway-level + func-level
+        const allMiddleware = [
+            ...(userMiddleware || []),
+            ...(userFuncConfig.middleware || []),
+        ];
+        const exec = async () => {
+            const result = await userFuncConfig.func(services, parsed, wire);
+            // 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 };
+        };
+        if (allMiddleware.length > 0) {
+            return await runMiddleware(services, wire, allMiddleware, exec);
+        }
+        return await exec();
+    };
+};
+/**
+ * Creates the GET handler for webhook verification challenges.
+ * Passes query parameters to the adapter's verifyWebhook method.
+ */
+const createWebhookVerifyHandler = (adapter) => {
+    return async (_services, _data, wire) => {
+        if (!adapter.verifyWebhook) {
+            return { error: 'Verification not supported' };
+        }
+        const query = wire.http?.request?.query();
+        const result = await adapter.verifyWebhook(query, wire.http?.request);
+        if (result.verified) {
+            return result.response;
+        }
+        return { error: 'Verification failed' };
+    };
+};
+// ---------------------------------------------------------------------------
+// WebSocket gateway — client connects via WebSocket
+// ---------------------------------------------------------------------------
+const wireWebsocketGateway = (config) => {
+    const { name, route, adapter } = 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,
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sessionless: true,
+    };
+    funcMeta[connectFuncId] = {
+        pikkuFuncId: connectFuncId,
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sessionless: true,
+    };
+    // Add channel metadata
+    channelsMeta[name] = {
+        name,
+        route,
+        gateway: true,
+        connect: { pikkuFuncId: connectFuncId },
+        message: { pikkuFuncId: messageFuncId },
+    };
+    const userFuncConfig = config.func;
+    const userMiddleware = config.middleware;
+    // Register onConnect
+    addFunction(connectFuncId, {
+        auth: false,
+        func: async (_services, _data, wire) => {
+            ;
+            wire.gateway = {
+                gatewayName: name,
+                senderId: '',
+                platform: adapter.name,
+                send: async (msg) => {
+                    wire.channel?.send(msg);
+                },
+            };
+        },
+    });
+    // Register onMessage
+    addFunction(messageFuncId, {
+        auth: false,
+        func: async (services, data, wire) => {
+            const parsed = adapter.parse(data);
+            if (!parsed)
+                return;
+            const gateway = {
+                gatewayName: name,
+                senderId: parsed.senderId,
+                platform: adapter.name,
+                send: async (msg) => {
+                    wire.channel?.send(msg);
+                },
+            };
+            wire.gateway = gateway;
+            const allMiddleware = [
+                ...(userMiddleware || []),
+                ...(userFuncConfig.middleware || []),
+            ];
+            const exec = async () => {
+                const result = await userFuncConfig.func(services, parsed, wire);
+                if (result &&
+                    (result.text || result.richContent || result.attachments)) {
+                    wire.channel?.send(result);
+                }
+            };
+            if (allMiddleware.length > 0) {
+                await runMiddleware(services, wire, allMiddleware, exec);
+            }
+            else {
+                await exec();
+            }
+        },
+    });
+    // Store channel config
+    channels.set(name, {
+        name,
+        route,
+        auth: false,
+        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
+ */
+export const createListenerMessageHandler = (name, config, singletonServices) => {
+    const { adapter } = config;
+    const userFuncConfig = config.func;
+    const userMiddleware = config.middleware;
+    return async (rawData) => {
+        const parsed = adapter.parse(rawData);
+        if (!parsed)
+            return;
+        const wire = {};
+        const gateway = {
+            gatewayName: name,
+            senderId: parsed.senderId,
+            platform: adapter.name,
+            send: (msg) => adapter.send(parsed.senderId, msg),
+        };
+        wire.gateway = gateway;
+        const allMiddleware = [
+            ...(userMiddleware || []),
+            ...(userFuncConfig.middleware || []),
+        ];
+        const exec = async () => {
+            const result = await userFuncConfig.func(singletonServices, parsed, wire);
+            if (result && (result.text || result.richContent || result.attachments)) {
+                await adapter.send(parsed.senderId, result);
+            }
+        };
+        if (allMiddleware.length > 0) {
+            await runMiddleware(singletonServices, wire, allMiddleware, exec);
+        }
+        else {
+            await exec();
+        }
+    };
+};

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

@@ -0,0 +1,127 @@
+import type { CommonWireMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../types/core.types.js';
+import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } 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;
+    data?: ArrayBuffer | Uint8Array;
+    mimeType?: string;
+    filename?: string;
+}
+/**
+ * Normalized inbound message from any platform
+ */
+export interface GatewayInboundMessage {
+    /** Platform-specific sender identifier (phone number, Slack user ID, etc.) */
+    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). */
+    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. */
+    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. */
+    verifyWebhook?(data: unknown, request?: PikkuHTTPRequest): WebhookVerificationResult | Promise<WebhookVerificationResult>;
+}
+/**
+ * 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)
+ */
+export type GatewayTransportType = 'webhook' | 'websocket' | 'listener';
+/**
+ * Core gateway configuration for wireGateway()
+ */
+export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>, PikkuPermission extends CorePikkuPermission = CorePikkuPermission, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware> = {
+    /** Unique name for this gateway */
+    name: string;
+    /** Transport type */
+    type: GatewayTransportType;
+    /** HTTP route for webhook/websocket types */
+    route?: string;
+    /** The gateway adapter (parse inbound, send outbound) */
+    adapter: GatewayAdapter;
+    /** The handler function that processes parsed messages */
+    func: PikkuFunctionConfig;
+    /** Optional middleware chain (e.g., auth) */
+    middleware?: CorePikkuMiddlewareGroup<any, any>;
+    /** Optional permissions */
+    permissions?: CorePermissionGroup | PikkuPermission[];
+    /** Optional tags for categorization */
+    tags?: string[];
+    /** Whether authentication is required (default: true) */
+    auth?: boolean;
+};
+/**
+ * Metadata for a registered gateway, stored in state
+ */
+export type GatewayMeta = CommonWireMeta & {
+    name: string;
+    type: GatewayTransportType;
+    route?: string;
+    gateway: true;
+};
+/**
+ * All gateway metadata keyed by name
+ */
+export type GatewaysMeta = Record<string, GatewayMeta>;

package/dist/wirings/gateway/gateway.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+export { wireGateway, createListenerMessageHandler } from './gateway-runner.js';
+export type { GatewayAdapter, GatewayAttachment, GatewayInboundMessage, GatewayOutboundMessage, GatewayMeta, GatewaysMeta, GatewayTransportType, CoreGateway, PikkuGateway, WebhookVerificationResult, } from './gateway.types.js';

package/dist/wirings/gateway/index.js

@@ -0,0 +1 @@
+export { wireGateway, createListenerMessageHandler } from './gateway-runner.js';

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

@@ -240,6 +240,9 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             send: (data) => {
                 response.arrayBuffer(isSerializable(data) ? JSON.stringify(data) : data);
             },
+            sendBinary: (data) => {
+                response.arrayBuffer(data);
+            },
             close: () => {
                 channel.state = 'closed';
                 response.close?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.1",
+  "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",
@@ -50,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/middleware-runner.ts

@@ -121,6 +121,7 @@ const middlewareCache: Record<
   agent: {},
   cli: {},
   workflow: {},
+  gateway: {},
 }
 
 /**

package/src/permissions.ts

@@ -130,6 +130,7 @@ const combinedPermissionsCache: Record<
   agent: {},
   cli: {},
   workflow: {},
+  gateway: {},
 }
 
 /**

package/src/pikku-state.ts

@@ -10,6 +10,7 @@ import type {
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
 import type { AIAgentMeta } from './wirings/ai-agent/ai-agent.types.js'
+import type { GatewaysMeta } from './wirings/gateway/gateway.types.js'
 import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
 import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
@@ -121,6 +122,10 @@ const createEmptyPackageState = (): PikkuPackageState => ({
     agents: new Map(),
     agentsMeta: {} as AIAgentMeta,
   },
+  gateway: {
+    gateways: new Map(),
+    meta: {} as GatewaysMeta,
+  },
   cli: {
     meta: { programs: {}, renderers: {} },
     programs: {},

package/src/services/gateway-service.ts

@@ -0,0 +1,20 @@
+/**
+ * Abstract GatewayService interface.
+ *
+ * Implementations manage listener gateway lifecycle — initializing adapters
+ * and delivering messages to handler functions.
+ *
+ * A `LocalGatewayService` starts all listeners unconditionally;
+ * a distributed implementation could check leader election first.
+ */
+export interface GatewayService {
+  /**
+   * Start all listener gateways
+   */
+  start(): Promise<void>
+
+  /**
+   * Stop all listener gateways
+   */
+  stop(): Promise<void>
+}

package/src/services/index.ts

@@ -17,6 +17,7 @@ export { ConsoleLogger } from './logger-console.js'
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js'
 export { InMemoryTriggerService } from './in-memory-trigger-service.js'
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js'
+export { LocalGatewayService } from './local-gateway-service.js'
 export type { ContentService } from './content-service.js'
 export type { JWTService } from './jwt-service.js'
 export type { Logger } from './logger.js'
@@ -30,6 +31,7 @@ export type {
   SchedulerService,
 } from './scheduler-service.js'
 export type { TriggerService } from './trigger-service.js'
+export type { GatewayService } from './gateway-service.js'
 export type {
   DeploymentService,
   DeploymentConfig,