@pikku/core 0.12.1 → 0.12.3

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

@@ -1,15 +1,22 @@
+import type { BinaryData } from '../channel.types.js';
 import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js';
 export declare class PikkuLocalChannelHandler<OpeningData = unknown, Out = unknown> extends PikkuAbstractChannelHandler<OpeningData, Out> {
     private onMessageCallback?;
+    private onBinaryMessageCallback?;
     private openCallBack?;
-    private closeCallback?;
+    private closeCallbacks;
     private sendCallback?;
+    private sendBinaryCallback?;
     registerOnOpen(callback: () => void): void;
     open(): void;
     registerOnMessage(callback: (data: any) => Promise<unknown>): void;
     message(data: unknown): Promise<unknown>;
+    registerOnBinaryMessage(callback: (data: BinaryData) => Promise<BinaryData | void> | BinaryData | void): void;
+    binaryMessage(data: BinaryData): Promise<BinaryData | void>;
     registerOnClose(callback: () => void): void;
     close(): void;
     registerOnSend(send: (message: Out) => void): void;
     send(message: Out, isBinary?: boolean): void;
+    registerOnSendBinary(send: (data: BinaryData) => void): void;
+    sendBinary(data: BinaryData): void;
 }

package/dist/wirings/channel/local/local-channel-handler.js

@@ -1,9 +1,11 @@
 import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js';
 export class PikkuLocalChannelHandler extends PikkuAbstractChannelHandler {
     onMessageCallback;
+    onBinaryMessageCallback;
     openCallBack;
-    closeCallback;
+    closeCallbacks = [];
     sendCallback;
+    sendBinaryCallback;
     registerOnOpen(callback) {
         this.openCallBack = callback;
     }
@@ -19,15 +21,23 @@ export class PikkuLocalChannelHandler extends PikkuAbstractChannelHandler {
     async message(data) {
         return this.onMessageCallback?.(data);
     }
+    registerOnBinaryMessage(callback) {
+        this.onBinaryMessageCallback = callback;
+    }
+    async binaryMessage(data) {
+        return this.onBinaryMessageCallback?.(data);
+    }
     registerOnClose(callback) {
-        this.closeCallback = callback;
+        this.closeCallbacks.push(callback);
     }
     close() {
         if (this.getChannel().state === 'closed') {
             return;
         }
         super.close();
-        this.closeCallback?.();
+        for (const cb of this.closeCallbacks) {
+            cb();
+        }
     }
     registerOnSend(send) {
         this.sendCallback = send;
@@ -38,4 +48,13 @@ export class PikkuLocalChannelHandler extends PikkuAbstractChannelHandler {
         }
         return this.sendCallback?.(message, isBinary);
     }
+    registerOnSendBinary(send) {
+        this.sendBinaryCallback = send;
+    }
+    sendBinary(data) {
+        if (!this.sendBinaryCallback) {
+            throw new Error('No sendBinary callback registered');
+        }
+        this.sendBinaryCallback(data);
+    }
 }

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

@@ -75,7 +75,10 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                     }
                     catch (e) {
                         singletonServices.logger.error(`Error handling onConnect: ${e}`);
-                        channel.send({ error: e.message || 'Unknown error' });
+                        channel.send({
+                            error: e.message || 'Unknown error',
+                            errorName: e.constructor?.name,
+                        });
                     }
                 }
             });
@@ -94,22 +97,42 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                     }
                     catch (e) {
                         singletonServices.logger.error(`Error handling onDisconnect: ${e}`);
-                        channel.send({ error: e.message || 'Unknown error' });
+                        channel.send({
+                            error: e.message || 'Unknown error',
+                            errorName: e.constructor?.name,
+                        });
                     }
                 }
                 await closeServices();
             });
-            const onMessage = processMessageHandlers(services, channelConfig, channelHandler, userSession);
+            const { onMessage, onBinaryMessage } = processMessageHandlers(services, channelConfig, channelHandler, userSession);
             channelHandler.registerOnMessage(async (data) => {
                 try {
                     const result = await onMessage(data);
                     await channel.send(result);
                 }
                 catch (e) {
-                    singletonServices.logger.error(`Error handling message: ${e.message}`);
-                    channel.send({ error: e.message || 'Unknown error' });
+                    singletonServices.logger.error(e);
+                    channel.send({
+                        error: e.message || 'Unknown error',
+                        errorName: e.constructor?.name,
+                    });
+                    setTimeout(() => channel.close(), 200);
                 }
             });
+            if (onBinaryMessage) {
+                channelHandler.registerOnBinaryMessage(async (data) => {
+                    try {
+                        const result = await onBinaryMessage(data);
+                        if (result) {
+                            await channel.sendBinary(result);
+                        }
+                    }
+                    catch (e) {
+                        singletonServices.logger.error(`Error handling binary message: ${e.message}`);
+                    }
+                });
+            }
         }
         catch (e) {
             handleHTTPError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);

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,12 +171,15 @@ 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) {
         singletonServices.logger.error(`Error processing message: ${e.message || e}`);
-        return { error: e.message || 'Unknown error' };
+        return {
+            error: e.message || 'Unknown error',
+            errorName: e.constructor?.name,
+        };
     }
     finally {
         if (wireServices) {

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

@@ -130,14 +130,20 @@ function pluckCLIData(mergedData, funcName, availableOptions) {
     const funcMeta = pikkuState(null, 'function', 'meta')[funcName];
     const schemaName = funcMeta?.inputSchemaName;
     const schema = schemaName
-        ? pikkuState(null, 'misc', 'schemas').get(schemaName)
+        ? pikkuState(funcMeta?.packageName ?? null, 'misc', 'schemas').get(schemaName)
         : null;
     if (schema && schema.properties) {
         // If we have a schema, only include fields that are in the schema
         const result = {};
         for (const key of Object.keys(schema.properties)) {
             if (key in mergedData) {
-                result[key] = mergedData[key];
+                let value = mergedData[key];
+                // CLI passes all values as strings — coerce to array when schema expects one
+                const propSchema = schema.properties[key];
+                if (propSchema?.type === 'array' && !Array.isArray(value)) {
+                    value = typeof value === 'string' ? value.split(',') : [value];
+                }
+                result[key] = value;
             }
             else if (availableOptions[key]?.default !== undefined) {
                 // Apply default if not provided
@@ -207,6 +213,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';
@@ -234,9 +243,11 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             wireMiddleware: allWireMiddleware,
             inheritedPermissions: currentCommand.permissions,
             wirePermissions: undefined,
+            coerceDataFromSchema: true,
             tags: programData?.tags,
             wire,
             sessionService: userSession,
+            packageName: currentCommand.packageName,
         });
         // Apply renderer one final time with the final output (if renderer exists)
         // Skip if result is undefined (void functions handle their own output)

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

@@ -52,6 +52,7 @@ export interface CLIProgramState {
 export interface CLICommandMeta {
     parameters?: string;
     pikkuFuncId: string;
+    packageName?: string;
     positionals: CLIPositional[];
     options: Record<string, CLIOption>;
     renderName?: string;

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();
+        }
+    };
+};