@maroonedsoftware/comms 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# @maroonedsoftware/comms
+
+The channel-agnostic messaging core for ServerKit. Register a `command` / `action` / `message`
+handler **once** and run it on every wired channel, replying through a uniform `Reply`.
+
+This package is **channel-free** — it has no dependency on any chat platform. Each channel package
+ships its own adapter as a `./comms` subpath (e.g. `@maroonedsoftware/slack/comms`) that binds to this
+core via an optional peer dependency. So you install `comms` plus whichever channels you wire.
+
+## Installation
+
+```bash
+pnpm add @maroonedsoftware/comms @maroonedsoftware/slack   # + any other channels
+```
+
+## Exports
+
+| Symbol                         | Purpose                                                                                          |
+|--------------------------------|--------------------------------------------------------------------------------------------------|
+| `ChannelRouter`                | Registers `command`/`action`/`message`/`fallback` handlers and `dispatch`es normalized events. Holds `.templates`. |
+| `IncomingEvent`                | Normalized inbound event (`channel`, `kind`, `user`, `conversation`, `text?`, `command?`, `action?`, `raw`). |
+| `OutgoingMessage` / `OutgoingButton` | Portable outbound message (`text`, optional `subject`, optional `buttons`).                 |
+| `Reply`                        | A `Notifier` bound to one recipient — what handlers use: `send` / `sendTemplate` / `sendNative`.  |
+| `Notifier`                     | Send-to-recipient interface each channel adapter implements (the seam for future push/email).     |
+| `bindReply(notifier, to)`      | Builds a `Reply` from a `Notifier` + recipient.                                                   |
+| `TemplateRegistry`             | Named rich templates: `register(name, channel, fn)`, `registerDefault(name, fn)`, `render(...)`.  |
+| `CommsError`                   | `ServerkitError` subclass (e.g. `sendTemplate` for an unknown template).                          |
+
+## Defining handlers (channel-agnostic)
+
+```ts
+import { ChannelRouter } from '@maroonedsoftware/comms';
+
+export const router = new ChannelRouter();
+
+router.command('deploy', async (event, reply) => {
+  await reply.send({
+    text: `Deploying ${event.command!.args || 'production'}…`,
+    buttons: [{ id: 'deploy:confirm', label: 'Confirm' }, { id: 'deploy:cancel', label: 'Cancel' }],
+  });
+});
+
+router.action('deploy:confirm', async (event, reply) => {
+  await reply.send({ text: `:rocket: Confirmed by ${event.user.username ?? event.user.id}` });
+});
+
+router.message(async (event, reply) => {
+  if (/help/i.test(event.text ?? '')) await reply.send({ text: 'Try `/deploy <env>`.' });
+});
+```
+
+Routing precedence per event: `command` → by normalized name (`/Deploy` and `deploy` both match
+`deploy`), `action` → by id, `message` → the single message handler, else the optional `fallback`.
+
+## Wiring a channel
+
+Each channel package exposes a `./comms` adapter. Wire it from your own HTTP route, reusing that
+package's signature verification:
+
+```ts
+import { SlackClient, SlackConfig, verifySlackSignature } from '@maroonedsoftware/slack';
+import { dispatchSlackCommand } from '@maroonedsoftware/slack/comms';
+import { router } from './router.js';
+
+http.post('/slack/commands', async (ctx) => {
+  const raw = await rawBody(ctx.req, { encoding: 'utf8' });
+  verifySlackSignature({ signingSecret: ctx.container.get(SlackConfig).signingSecret, rawBody: raw,
+    timestamp: ctx.get('x-slack-request-timestamp'), signature: ctx.get('x-slack-signature') });
+  await dispatchSlackCommand(router, ctx.container.get(SlackClient), Object.fromEntries(new URLSearchParams(raw)) as any);
+  ctx.status = 200; ctx.body = '';
+});
+```
+
+The **same `router`** is reused by `@maroonedsoftware/discord/comms`, `/whatsapp/comms`, and
+`/telegram/comms`. See each channel package's README for its adapter's exports and any caveats (e.g.
+Discord has no inbound `message`; WhatsApp/Telegram commands come from `/`-prefixed text).
+
+## Rich outbound via the template registry
+
+For anything beyond text + buttons, register a named template — rich per channel, portable fallback
+elsewhere — and call it channel-agnostically:
+
+```ts
+router.templates.register('order.card', 'slack', (d: { id: string }) => ({ blocks: [/* Block Kit */] }));
+router.templates.registerDefault('order.card', (d: { id: string }) => ({ text: `Order ${d.id} ✅` }));
+
+router.action('order:confirm', async (event, reply) => {
+  await reply.sendTemplate('order.card', { id: event.action!.value });   // native on Slack, fallback elsewhere
+});
+```
+
+Resolution prefers a channel-native renderer, then the portable default; an unregistered name throws
+`CommsError`. The registry stores plain functions — back a renderer with Handlebars or any engine; no
+template engine is bundled. For one-off native payloads, `reply.sendNative(payload)` is the raw escape
+hatch.
+
+## Outbound-only sends
+
+Each adapter also exposes a `Notifier` (`create<Channel>Notifier(client, router.templates)`) for
+proactive, non-reply sends: `notifier.send(recipientId, { text: '…' })`.
+
+## License
+
+MIT

package/dist/comms.error.d.ts

@@ -0,0 +1,16 @@
+import { ServerkitError } from '@maroonedsoftware/errors';
+/**
+ * Domain error raised by the comms layer (e.g. `sendTemplate` for an
+ * unregistered template name).
+ *
+ * Extends {@link ServerkitError} so `errorMiddleware` renders a 500 with
+ * `{ message, details }` if one escapes a route handler.
+ */
+export declare class CommsError extends ServerkitError {
+}
+/**
+ * Type guard for {@link CommsError}. Narrows `unknown` to `CommsError`. Returns
+ * `true` for any subclass.
+ */
+export declare const IsCommsError: (error: unknown) => error is CommsError;
+//# sourceMappingURL=comms.error.d.ts.map

package/dist/comms.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms.error.d.ts","sourceRoot":"","sources":["../src/comms.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,cAAc;CAAG;AAEjD;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,UAAyC,CAAC"}

package/dist/comms.event.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Identifier for a wired channel. The built-in chat adapters use the four
+ * literals; the open `string` keeps the type extensible for future channels
+ * (sms, push, email, …).
+ */
+export type ChannelId = 'slack' | 'discord' | 'whatsapp' | 'telegram' | (string & {});
+/**
+ * The normalized kinds of inbound event the {@link ChannelRouter} routes on.
+ *
+ * - `command` — a slash/text command (`/deploy staging`).
+ * - `action` — a pressed button / interactive component, keyed by a developer id.
+ * - `message` — a free-text message with no command prefix.
+ */
+export type IncomingEventKind = 'command' | 'action' | 'message';
+/**
+ * A channel-agnostic inbound event. Each channel's `./comms` adapter normalizes
+ * its native payload into this shape; handlers registered on the
+ * {@link ChannelRouter} receive it regardless of the source channel.
+ */
+export interface IncomingEvent {
+    /** Which channel produced the event. */
+    channel: ChannelId;
+    /** The routed kind — see {@link IncomingEventKind}. */
+    kind: IncomingEventKind;
+    /** The user who triggered the event. */
+    user: {
+        id: string;
+        username?: string;
+    };
+    /** The conversation/chat the event belongs to — also the address a {@link Reply} sends back to. */
+    conversation: {
+        id: string;
+    };
+    /** Message text or full command text, when present. */
+    text?: string;
+    /** Present when `kind === 'command'`. `name` is normalized (no leading slash, lowercased). */
+    command?: {
+        name: string;
+        args: string;
+    };
+    /** Present when `kind === 'action'`. `id` is the developer-defined button/component id. */
+    action?: {
+        id: string;
+        value?: string;
+    };
+    /** The channel-native payload (and context) the adapter normalized from, untouched. */
+    raw: unknown;
+}
+//# sourceMappingURL=comms.event.d.ts.map

package/dist/comms.event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms.event.d.ts","sourceRoot":"","sources":["../src/comms.event.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,OAAO,EAAE,SAAS,CAAC;IACnB,uDAAuD;IACvD,IAAI,EAAE,iBAAiB,CAAC;IACxB,wCAAwC;IACxC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,mGAAmG;IACnG,YAAY,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,2FAA2F;IAC3F,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,uFAAuF;IACvF,GAAG,EAAE,OAAO,CAAC;CACd"}

package/dist/comms.message.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A portable reply button. Channels that support interactive buttons render it
+ * natively (Slack actions, Discord components, WhatsApp interactive, Telegram
+ * inline keyboard); channels without buttons degrade it (e.g. WhatsApp lists
+ * for >3, SMS numbered text).
+ */
+export interface OutgoingButton {
+    /** Developer-defined id echoed back as the {@link IncomingEvent.action} id when pressed. */
+    id: string;
+    /** Human-visible label. */
+    label: string;
+    /** Optional payload value carried back on the action. */
+    value?: string;
+}
+/**
+ * The portable outbound message — the lowest common denominator every channel
+ * renderer can express. Anything richer is reached through a registered template
+ * (`reply.sendTemplate`) or the raw escape hatch (`reply.sendNative`).
+ */
+export interface OutgoingMessage {
+    /** Body text. */
+    text: string;
+    /** Optional subject/title — used by email (subject) and push (title); chat/SMS renderers ignore it. */
+    subject?: string;
+    /** Optional reply buttons. */
+    buttons?: OutgoingButton[];
+}
+//# sourceMappingURL=comms.message.d.ts.map

package/dist/comms.message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms.message.d.ts","sourceRoot":"","sources":["../src/comms.message.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B"}

package/dist/comms.reply.d.ts

@@ -0,0 +1,37 @@
+import type { ChannelId } from './comms.event.js';
+import type { OutgoingMessage } from './comms.message.js';
+/**
+ * Send-to-recipient outbound interface, implemented by each channel's `./comms`
+ * adapter (`create<Channel>Notifier`). It is the forward-compatible seam that
+ * notify-only channels (push, email) will also implement.
+ */
+export interface Notifier {
+    /** Which channel this notifier sends on. */
+    readonly channel: ChannelId;
+    /** Send a portable message to a recipient (chat id / phone / token / address). */
+    send(to: string, message: OutgoingMessage): Promise<void>;
+    /** Render and send a registered template by name (rich per channel, portable fallback). */
+    sendTemplate(to: string, name: string, data?: unknown): Promise<void>;
+    /** Send a channel-native payload verbatim — the raw escape hatch. */
+    sendNative(to: string, payload: unknown): Promise<void>;
+}
+/**
+ * A {@link Notifier} pre-bound to one recipient — what handlers receive to reply
+ * to the inbound event they're handling. Built by adapters via {@link bindReply}.
+ */
+export interface Reply {
+    /** Which channel the originating event came from. */
+    readonly channel: ChannelId;
+    /** Reply with a portable message. */
+    send(message: OutgoingMessage): Promise<void>;
+    /** Reply by rendering a registered template by name. */
+    sendTemplate(name: string, data?: unknown): Promise<void>;
+    /** Reply with a channel-native payload verbatim. */
+    sendNative(payload: unknown): Promise<void>;
+}
+/**
+ * Binds a {@link Notifier} to a fixed recipient, yielding the {@link Reply} that
+ * handlers use. Each call delegates to the notifier with the bound `to`.
+ */
+export declare const bindReply: (notifier: Notifier, to: string) => Reply;
+//# sourceMappingURL=comms.reply.d.ts.map

package/dist/comms.reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms.reply.d.ts","sourceRoot":"","sources":["../src/comms.reply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,kFAAkF;IAClF,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,2FAA2F;IAC3F,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,qEAAqE;IACrE,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,qCAAqC;IACrC,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,wDAAwD;IACxD,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,oDAAoD;IACpD,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,QAAQ,EAAE,IAAI,MAAM,KAAG,KAKzD,CAAC"}

package/dist/comms.router.d.ts

@@ -0,0 +1,50 @@
+import { Logger } from '@maroonedsoftware/logger';
+import type { IncomingEvent } from './comms.event.js';
+import type { Reply } from './comms.reply.js';
+import { TemplateRegistry } from './comms.template.js';
+/** A channel-agnostic handler invoked with the normalized event and a bound {@link Reply}. */
+export type CommsHandler = (event: IncomingEvent, reply: Reply) => Promise<void> | void;
+/** Normalizes a command name to its registry key: no leading slash, lowercased. */
+export declare const normalizeCommandName: (name: string) => string;
+/**
+ * The channel-agnostic router. Register `command` / `action` / `message`
+ * handlers (and an optional `fallback`) once; each channel's `./comms` adapter
+ * normalizes its inbound payload into an {@link IncomingEvent} and calls
+ * {@link dispatch}, which routes to the matching handler.
+ *
+ * Holds a {@link TemplateRegistry} (`router.templates`) the adapters read when a
+ * handler calls `reply.sendTemplate(...)`.
+ *
+ * @example
+ * ```ts
+ * const router = new ChannelRouter();
+ * router.command('deploy', async (event, reply) => reply.send({ text: `Deploying ${event.command!.args}` }));
+ * router.action('deploy:confirm', async (event, reply) => reply.send({ text: 'Confirmed' }));
+ * ```
+ */
+export declare class ChannelRouter {
+    private readonly logger?;
+    /** Outbound template registry shared with the channel adapters. */
+    readonly templates: TemplateRegistry;
+    private readonly commands;
+    private readonly actions;
+    private messageHandler?;
+    private fallbackHandler?;
+    constructor(logger?: Logger | undefined);
+    /** Register a handler for a command (with or without a leading slash; name is normalized). */
+    command(name: string, handler: CommsHandler): this;
+    /** Register a handler for a button/component action id. */
+    action(id: string, handler: CommsHandler): this;
+    /** Register the single catch-all message handler (free-text, non-command messages). */
+    message(handler: CommsHandler): this;
+    /** Register a fallback handler invoked when nothing else matches. */
+    fallback(handler: CommsHandler): this;
+    /**
+     * Route a normalized event to its handler: `command` → by name, `action` → by
+     * id, `message` → the message handler. Falls back to the registered fallback
+     * (or logs at debug and returns) when nothing matches.
+     */
+    dispatch(event: IncomingEvent, reply: Reply): Promise<void>;
+    private resolve;
+}
+//# sourceMappingURL=comms.router.d.ts.map

package/dist/comms.router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms.router.d.ts","sourceRoot":"","sources":["../src/comms.router.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,8FAA8F;AAC9F,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAExF,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAA+C,CAAC;AAEpG;;;;;;;;;;;;;;;GAeG;AACH,qBACa,aAAa;IASZ,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IARpC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,mBAA0B;IAE5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,cAAc,CAAC,CAAe;IACtC,OAAO,CAAC,eAAe,CAAC,CAAe;gBAEV,MAAM,CAAC,EAAE,MAAM,YAAA;IAE5C,8FAA8F;IAC9F,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAKlD,2DAA2D;IAC3D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAK/C,uFAAuF;IACvF,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKpC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKrC;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE,OAAO,CAAC,OAAO;CAYhB"}

package/dist/comms.template.d.ts

@@ -0,0 +1,47 @@
+import type { ChannelId } from './comms.event.js';
+import type { OutgoingMessage } from './comms.message.js';
+/** Renders template data into a channel-native payload (rich, channel-specific). */
+export type NativeRenderer<D = unknown> = (data: D) => unknown;
+/** Renders template data into a portable {@link OutgoingMessage} (cross-channel fallback). */
+export type PortableRenderer<D = unknown> = (data: D) => OutgoingMessage;
+/**
+ * Result of {@link TemplateRegistry.render}: either a channel-native payload (a
+ * per-channel renderer matched) or a portable message (the default fallback),
+ * or `undefined` when no template is registered under the name.
+ */
+export type TemplateRenderResult = {
+    kind: 'native';
+    payload: unknown;
+} | {
+    kind: 'portable';
+    message: OutgoingMessage;
+} | undefined;
+/**
+ * A registry of named outbound templates. Register a **rich, per-channel**
+ * renderer with {@link register} and/or a **portable default** with
+ * {@link registerDefault}; adapters resolve a template for the current channel
+ * via {@link render}, with channel-native taking precedence over the default.
+ *
+ * The registry stores plain functions — a consumer is free to back a renderer
+ * with Handlebars or any engine. No template engine is bundled.
+ *
+ * @example
+ * ```ts
+ * registry.register('order.card', 'slack', d => ({ blocks: [...] }));
+ * registry.registerDefault('order.card', d => ({ text: `Order ${d.id} ✅` }));
+ * ```
+ */
+export declare class TemplateRegistry {
+    private readonly native;
+    private readonly defaults;
+    /** Register a channel-native renderer for `name` on `channel`. */
+    register<D>(name: string, channel: ChannelId, render: NativeRenderer<D>): this;
+    /** Register the portable default renderer for `name`, used on channels without a native renderer. */
+    registerDefault<D>(name: string, render: PortableRenderer<D>): this;
+    /**
+     * Resolve and run the best renderer for `name` on `channel`: a channel-native
+     * renderer if registered, else the portable default, else `undefined`.
+     */
+    render(name: string, channel: ChannelId, data: unknown): TemplateRenderResult;
+}
+//# sourceMappingURL=comms.template.d.ts.map

package/dist/comms.template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms.template.d.ts","sourceRoot":"","sources":["../src/comms.template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,oFAAoF;AACpF,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;AAC/D,8FAA8F;AAC9F,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,eAAe,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,GAAG,SAAS,CAAC;AAErI;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqD;IAC5E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE,kEAAkE;IAClE,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAU9E,qGAAqG;IACrG,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI;IAKnE;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,oBAAoB;CAO9E"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './comms.event.js';
+export * from './comms.message.js';
+export * from './comms.reply.js';
+export * from './comms.template.js';
+export * from './comms.router.js';
+export * from './comms.error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,155 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/comms.reply.ts
+var bindReply = /* @__PURE__ */ __name((notifier, to) => ({
+  channel: notifier.channel,
+  send: /* @__PURE__ */ __name((message) => notifier.send(to, message), "send"),
+  sendTemplate: /* @__PURE__ */ __name((name, data) => notifier.sendTemplate(to, name, data), "sendTemplate"),
+  sendNative: /* @__PURE__ */ __name((payload) => notifier.sendNative(to, payload), "sendNative")
+}), "bindReply");
+
+// src/comms.template.ts
+var TemplateRegistry = class {
+  static {
+    __name(this, "TemplateRegistry");
+  }
+  native = /* @__PURE__ */ new Map();
+  defaults = /* @__PURE__ */ new Map();
+  /** Register a channel-native renderer for `name` on `channel`. */
+  register(name, channel, render) {
+    let byChannel = this.native.get(name);
+    if (!byChannel) {
+      byChannel = /* @__PURE__ */ new Map();
+      this.native.set(name, byChannel);
+    }
+    byChannel.set(channel, render);
+    return this;
+  }
+  /** Register the portable default renderer for `name`, used on channels without a native renderer. */
+  registerDefault(name, render) {
+    this.defaults.set(name, render);
+    return this;
+  }
+  /**
+  * Resolve and run the best renderer for `name` on `channel`: a channel-native
+  * renderer if registered, else the portable default, else `undefined`.
+  */
+  render(name, channel, data) {
+    const nativeRenderer = this.native.get(name)?.get(channel);
+    if (nativeRenderer) return {
+      kind: "native",
+      payload: nativeRenderer(data)
+    };
+    const portable = this.defaults.get(name);
+    if (portable) return {
+      kind: "portable",
+      message: portable(data)
+    };
+    return void 0;
+  }
+};
+
+// src/comms.router.ts
+import { Injectable } from "injectkit";
+import { Logger } from "@maroonedsoftware/logger";
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var normalizeCommandName = /* @__PURE__ */ __name((name) => name.replace(/^\//, "").toLowerCase(), "normalizeCommandName");
+var ChannelRouter = class {
+  static {
+    __name(this, "ChannelRouter");
+  }
+  logger;
+  /** Outbound template registry shared with the channel adapters. */
+  templates = new TemplateRegistry();
+  commands = /* @__PURE__ */ new Map();
+  actions = /* @__PURE__ */ new Map();
+  messageHandler;
+  fallbackHandler;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  /** Register a handler for a command (with or without a leading slash; name is normalized). */
+  command(name, handler) {
+    this.commands.set(normalizeCommandName(name), handler);
+    return this;
+  }
+  /** Register a handler for a button/component action id. */
+  action(id, handler) {
+    this.actions.set(id, handler);
+    return this;
+  }
+  /** Register the single catch-all message handler (free-text, non-command messages). */
+  message(handler) {
+    this.messageHandler = handler;
+    return this;
+  }
+  /** Register a fallback handler invoked when nothing else matches. */
+  fallback(handler) {
+    this.fallbackHandler = handler;
+    return this;
+  }
+  /**
+  * Route a normalized event to its handler: `command` → by name, `action` → by
+  * id, `message` → the message handler. Falls back to the registered fallback
+  * (or logs at debug and returns) when nothing matches.
+  */
+  async dispatch(event, reply) {
+    const handler = this.resolve(event);
+    if (!handler) {
+      this.logger?.debug("No comms handler for event", {
+        channel: event.channel,
+        kind: event.kind
+      });
+      return;
+    }
+    await handler(event, reply);
+  }
+  resolve(event) {
+    if (event.kind === "command" && event.command) {
+      return this.commands.get(normalizeCommandName(event.command.name)) ?? this.fallbackHandler;
+    }
+    if (event.kind === "action" && event.action) {
+      return this.actions.get(event.action.id) ?? this.fallbackHandler;
+    }
+    if (event.kind === "message") {
+      return this.messageHandler ?? this.fallbackHandler;
+    }
+    return this.fallbackHandler;
+  }
+};
+ChannelRouter = _ts_decorate([
+  Injectable(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof Logger === "undefined" ? Object : Logger
+  ])
+], ChannelRouter);
+
+// src/comms.error.ts
+import { ServerkitError } from "@maroonedsoftware/errors";
+var CommsError = class extends ServerkitError {
+  static {
+    __name(this, "CommsError");
+  }
+};
+var IsCommsError = /* @__PURE__ */ __name((error) => error instanceof CommsError, "IsCommsError");
+export {
+  ChannelRouter,
+  CommsError,
+  IsCommsError,
+  TemplateRegistry,
+  bindReply,
+  normalizeCommandName
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/comms.reply.ts","../src/comms.template.ts","../src/comms.router.ts","../src/comms.error.ts"],"sourcesContent":["import type { ChannelId } from './comms.event.js';\nimport type { OutgoingMessage } from './comms.message.js';\n\n/**\n * Send-to-recipient outbound interface, implemented by each channel's `./comms`\n * adapter (`create<Channel>Notifier`). It is the forward-compatible seam that\n * notify-only channels (push, email) will also implement.\n */\nexport interface Notifier {\n  /** Which channel this notifier sends on. */\n  readonly channel: ChannelId;\n  /** Send a portable message to a recipient (chat id / phone / token / address). */\n  send(to: string, message: OutgoingMessage): Promise<void>;\n  /** Render and send a registered template by name (rich per channel, portable fallback). */\n  sendTemplate(to: string, name: string, data?: unknown): Promise<void>;\n  /** Send a channel-native payload verbatim — the raw escape hatch. */\n  sendNative(to: string, payload: unknown): Promise<void>;\n}\n\n/**\n * A {@link Notifier} pre-bound to one recipient — what handlers receive to reply\n * to the inbound event they're handling. Built by adapters via {@link bindReply}.\n */\nexport interface Reply {\n  /** Which channel the originating event came from. */\n  readonly channel: ChannelId;\n  /** Reply with a portable message. */\n  send(message: OutgoingMessage): Promise<void>;\n  /** Reply by rendering a registered template by name. */\n  sendTemplate(name: string, data?: unknown): Promise<void>;\n  /** Reply with a channel-native payload verbatim. */\n  sendNative(payload: unknown): Promise<void>;\n}\n\n/**\n * Binds a {@link Notifier} to a fixed recipient, yielding the {@link Reply} that\n * handlers use. Each call delegates to the notifier with the bound `to`.\n */\nexport const bindReply = (notifier: Notifier, to: string): Reply => ({\n  channel: notifier.channel,\n  send: message => notifier.send(to, message),\n  sendTemplate: (name, data) => notifier.sendTemplate(to, name, data),\n  sendNative: payload => notifier.sendNative(to, payload),\n});\n","import type { ChannelId } from './comms.event.js';\nimport type { OutgoingMessage } from './comms.message.js';\n\n/** Renders template data into a channel-native payload (rich, channel-specific). */\nexport type NativeRenderer<D = unknown> = (data: D) => unknown;\n/** Renders template data into a portable {@link OutgoingMessage} (cross-channel fallback). */\nexport type PortableRenderer<D = unknown> = (data: D) => OutgoingMessage;\n\n/**\n * Result of {@link TemplateRegistry.render}: either a channel-native payload (a\n * per-channel renderer matched) or a portable message (the default fallback),\n * or `undefined` when no template is registered under the name.\n */\nexport type TemplateRenderResult = { kind: 'native'; payload: unknown } | { kind: 'portable'; message: OutgoingMessage } | undefined;\n\n/**\n * A registry of named outbound templates. Register a **rich, per-channel**\n * renderer with {@link register} and/or a **portable default** with\n * {@link registerDefault}; adapters resolve a template for the current channel\n * via {@link render}, with channel-native taking precedence over the default.\n *\n * The registry stores plain functions — a consumer is free to back a renderer\n * with Handlebars or any engine. No template engine is bundled.\n *\n * @example\n * ```ts\n * registry.register('order.card', 'slack', d => ({ blocks: [...] }));\n * registry.registerDefault('order.card', d => ({ text: `Order ${d.id} ✅` }));\n * ```\n */\nexport class TemplateRegistry {\n  private readonly native = new Map<string, Map<ChannelId, NativeRenderer>>();\n  private readonly defaults = new Map<string, PortableRenderer>();\n\n  /** Register a channel-native renderer for `name` on `channel`. */\n  register<D>(name: string, channel: ChannelId, render: NativeRenderer<D>): this {\n    let byChannel = this.native.get(name);\n    if (!byChannel) {\n      byChannel = new Map();\n      this.native.set(name, byChannel);\n    }\n    byChannel.set(channel, render as NativeRenderer);\n    return this;\n  }\n\n  /** Register the portable default renderer for `name`, used on channels without a native renderer. */\n  registerDefault<D>(name: string, render: PortableRenderer<D>): this {\n    this.defaults.set(name, render as PortableRenderer);\n    return this;\n  }\n\n  /**\n   * Resolve and run the best renderer for `name` on `channel`: a channel-native\n   * renderer if registered, else the portable default, else `undefined`.\n   */\n  render(name: string, channel: ChannelId, data: unknown): TemplateRenderResult {\n    const nativeRenderer = this.native.get(name)?.get(channel);\n    if (nativeRenderer) return { kind: 'native', payload: nativeRenderer(data) };\n    const portable = this.defaults.get(name);\n    if (portable) return { kind: 'portable', message: portable(data) };\n    return undefined;\n  }\n}\n","import { Injectable } from 'injectkit';\nimport { Logger } from '@maroonedsoftware/logger';\nimport type { IncomingEvent } from './comms.event.js';\nimport type { Reply } from './comms.reply.js';\nimport { TemplateRegistry } from './comms.template.js';\n\n/** A channel-agnostic handler invoked with the normalized event and a bound {@link Reply}. */\nexport type CommsHandler = (event: IncomingEvent, reply: Reply) => Promise<void> | void;\n\n/** Normalizes a command name to its registry key: no leading slash, lowercased. */\nexport const normalizeCommandName = (name: string): string => name.replace(/^\\//, '').toLowerCase();\n\n/**\n * The channel-agnostic router. Register `command` / `action` / `message`\n * handlers (and an optional `fallback`) once; each channel's `./comms` adapter\n * normalizes its inbound payload into an {@link IncomingEvent} and calls\n * {@link dispatch}, which routes to the matching handler.\n *\n * Holds a {@link TemplateRegistry} (`router.templates`) the adapters read when a\n * handler calls `reply.sendTemplate(...)`.\n *\n * @example\n * ```ts\n * const router = new ChannelRouter();\n * router.command('deploy', async (event, reply) => reply.send({ text: `Deploying ${event.command!.args}` }));\n * router.action('deploy:confirm', async (event, reply) => reply.send({ text: 'Confirmed' }));\n * ```\n */\n@Injectable()\nexport class ChannelRouter {\n  /** Outbound template registry shared with the channel adapters. */\n  readonly templates = new TemplateRegistry();\n\n  private readonly commands = new Map<string, CommsHandler>();\n  private readonly actions = new Map<string, CommsHandler>();\n  private messageHandler?: CommsHandler;\n  private fallbackHandler?: CommsHandler;\n\n  constructor(private readonly logger?: Logger) {}\n\n  /** Register a handler for a command (with or without a leading slash; name is normalized). */\n  command(name: string, handler: CommsHandler): this {\n    this.commands.set(normalizeCommandName(name), handler);\n    return this;\n  }\n\n  /** Register a handler for a button/component action id. */\n  action(id: string, handler: CommsHandler): this {\n    this.actions.set(id, handler);\n    return this;\n  }\n\n  /** Register the single catch-all message handler (free-text, non-command messages). */\n  message(handler: CommsHandler): this {\n    this.messageHandler = handler;\n    return this;\n  }\n\n  /** Register a fallback handler invoked when nothing else matches. */\n  fallback(handler: CommsHandler): this {\n    this.fallbackHandler = handler;\n    return this;\n  }\n\n  /**\n   * Route a normalized event to its handler: `command` → by name, `action` → by\n   * id, `message` → the message handler. Falls back to the registered fallback\n   * (or logs at debug and returns) when nothing matches.\n   */\n  async dispatch(event: IncomingEvent, reply: Reply): Promise<void> {\n    const handler = this.resolve(event);\n    if (!handler) {\n      this.logger?.debug('No comms handler for event', { channel: event.channel, kind: event.kind });\n      return;\n    }\n    await handler(event, reply);\n  }\n\n  private resolve(event: IncomingEvent): CommsHandler | undefined {\n    if (event.kind === 'command' && event.command) {\n      return this.commands.get(normalizeCommandName(event.command.name)) ?? this.fallbackHandler;\n    }\n    if (event.kind === 'action' && event.action) {\n      return this.actions.get(event.action.id) ?? this.fallbackHandler;\n    }\n    if (event.kind === 'message') {\n      return this.messageHandler ?? this.fallbackHandler;\n    }\n    return this.fallbackHandler;\n  }\n}\n","import { ServerkitError } from '@maroonedsoftware/errors';\n\n/**\n * Domain error raised by the comms layer (e.g. `sendTemplate` for an\n * unregistered template name).\n *\n * Extends {@link ServerkitError} so `errorMiddleware` renders a 500 with\n * `{ message, details }` if one escapes a route handler.\n */\nexport class CommsError extends ServerkitError {}\n\n/**\n * Type guard for {@link CommsError}. Narrows `unknown` to `CommsError`. Returns\n * `true` for any subclass.\n */\nexport const IsCommsError = (error: unknown): error is CommsError => error instanceof CommsError;\n"],"mappings":"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","names":["bindReply","notifier","to","channel","send","message","sendTemplate","name","data","sendNative","payload","TemplateRegistry","native","Map","defaults","register","name","channel","render","byChannel","get","set","registerDefault","data","nativeRenderer","kind","payload","portable","message","undefined","Injectable","Logger","normalizeCommandName","name","replace","toLowerCase","ChannelRouter","templates","TemplateRegistry","commands","Map","actions","messageHandler","fallbackHandler","logger","command","handler","set","action","id","message","fallback","dispatch","event","reply","resolve","debug","channel","kind","get","ServerkitError","CommsError","ServerkitError","IsCommsError","error"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@maroonedsoftware/comms",
+  "version": "0.1.0",
+  "description": "Channel-agnostic messaging core (router, reply, template registry) for ServerKit.",
+  "author": {
+    "name": "Marooned Software",
+    "url": "https://github.com/MaroonedSoftware/serverkit"
+  },
+  "bugs": {
+    "url": "https://github.com/MaroonedSoftware/serverkit/issues"
+  },
+  "homepage": "https://github.com/MaroonedSoftware/serverkit/packages/comms#readme",
+  "keywords": [
+    "backend",
+    "comms",
+    "messaging",
+    "serverkit",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaroonedSoftware/serverkit.git"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist/**"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --sourcemap && tsc --emitDeclarationOnly --declaration",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "lint": "eslint --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@maroonedsoftware/errors": "workspace:*",
+    "@maroonedsoftware/logger": "workspace:*",
+    "injectkit": "^1.5.0"
+  },
+  "devDependencies": {
+    "@repo/config-eslint": "workspace:*",
+    "@repo/config-typescript": "workspace:*"
+  }
+}