@cogenta/channels 0.1.0

package/dist/providers/telegram/client.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A minimal, hand-typed client for the four Telegram Bot API methods this
+ * adapter needs. Telegram's Bot API is plain HTTPS/JSON — no official SDK
+ * is required, and this codebase's established precedent (`@cogenta/import`'s
+ * hand-rolled WXR parser, `@cogenta/mcp`'s hand-rolled JSON-RPC subset)
+ * favours a small, zero-dependency client over a general-purpose SDK for an
+ * API this simple, rather than adding a new direct dependency for four HTTP
+ * calls.
+ */
+export interface TelegramInlineButton {
+    readonly text: string;
+    readonly callback_data: string;
+}
+export interface TelegramReplyMarkup {
+    readonly inline_keyboard: readonly (readonly TelegramInlineButton[])[];
+}
+export interface TelegramSendMessageParams {
+    readonly chat_id: string;
+    readonly text: string;
+    readonly parse_mode?: 'MarkdownV2';
+    readonly reply_markup?: TelegramReplyMarkup;
+}
+export interface TelegramEditMessageParams {
+    readonly chat_id: string;
+    readonly message_id: number;
+    readonly text: string;
+    readonly parse_mode?: 'MarkdownV2';
+    readonly reply_markup?: TelegramReplyMarkup;
+}
+export interface TelegramMessage {
+    readonly message_id: number;
+    readonly chat: {
+        readonly id: number;
+    };
+}
+export interface TelegramUser {
+    readonly id: number;
+}
+export interface TelegramIncomingMessage {
+    readonly message_id: number;
+    readonly chat: {
+        readonly id: number;
+    };
+    readonly from?: TelegramUser;
+    readonly text?: string;
+}
+export interface TelegramCallbackQuery {
+    readonly id: string;
+    readonly from: TelegramUser;
+    readonly message?: TelegramIncomingMessage;
+    readonly data?: string;
+}
+export interface TelegramUpdate {
+    readonly update_id: number;
+    readonly message?: TelegramIncomingMessage;
+    readonly callback_query?: TelegramCallbackQuery;
+}
+export interface TelegramClientConfig {
+    readonly token: string;
+    /** Overridable for tests; defaults to the real Telegram API host. */
+    readonly baseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+    /** Overridable for tests, so a 429 retry doesn't really wait. */
+    readonly sleepImpl?: (ms: number) => Promise<void>;
+}
+export interface TelegramClient {
+    sendMessage(params: TelegramSendMessageParams): Promise<TelegramMessage>;
+    editMessageText(params: TelegramEditMessageParams): Promise<void>;
+    answerCallbackQuery(callbackQueryId: string, text?: string): Promise<void>;
+    getUpdates(offset: number, timeoutSeconds: number): Promise<readonly TelegramUpdate[]>;
+}
+/**
+ * `createTelegramClient` retries a rate-limited call using Telegram's own
+ * `retry_after` value (seconds) rather than a guessed backoff — "Prévoir la
+ * file, le backoff et le regroupement dès le premier adaptateur" (lot doc).
+ */
+export declare function createTelegramClient(config: TelegramClientConfig): TelegramClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/providers/telegram/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/providers/telegram/client.ts"],"names":[],"mappings":"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"}

package/dist/providers/telegram/client.js

@@ -0,0 +1,53 @@
+import { CogentaError } from '@cogenta/core';
+const DEFAULT_BASE_URL = 'https://api.telegram.org';
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * `createTelegramClient` retries a rate-limited call using Telegram's own
+ * `retry_after` value (seconds) rather than a guessed backoff — "Prévoir la
+ * file, le backoff et le regroupement dès le premier adaptateur" (lot doc).
+ */
+export function createTelegramClient(config) {
+    const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const sleepImpl = config.sleepImpl ?? defaultSleep;
+    async function call(method, body) {
+        for (;;) {
+            const response = await fetchImpl(`${baseUrl}/bot${config.token}/${method}`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            const json = (await response.json());
+            if (response.status === 429 && !json.ok) {
+                const retryAfterSeconds = json.parameters?.retry_after ?? 1;
+                await sleepImpl(retryAfterSeconds * 1000);
+                continue;
+            }
+            if (!json.ok) {
+                throw new CogentaError({
+                    code: 'CHANNEL_TELEGRAM_API_ERROR',
+                    message: `Telegram API call "${method}" failed: ${json.description}`,
+                    hint: 'Check the bot token, and that the chat or message this call references still exists.',
+                    details: { method, errorCode: json.error_code },
+                });
+            }
+            return json.result;
+        }
+    }
+    return {
+        sendMessage: (params) => call('sendMessage', params),
+        async editMessageText(params) {
+            await call('editMessageText', params);
+        },
+        async answerCallbackQuery(callbackQueryId, text) {
+            await call('answerCallbackQuery', {
+                callback_query_id: callbackQueryId,
+                ...(text === undefined ? {} : { text }),
+            });
+        },
+        getUpdates: (offset, timeoutSeconds) => call('getUpdates', { offset, timeout: timeoutSeconds }),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/providers/telegram/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/providers/telegram/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AA+F5C,MAAM,gBAAgB,GAAG,0BAA0B,CAAA;AAEnD,SAAS,YAAY,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,gBAAgB,CAAA;IAClD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,KAAK,CAAA;IAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,YAAY,CAAA;IAElD,KAAK,UAAU,IAAI,CAAI,MAAc,EAAE,IAAa;QAClD,SAAS,CAAC;YACR,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,OAAO,OAAO,MAAM,CAAC,KAAK,IAAI,MAAM,EAAE,EAAE;gBAC1E,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;aAC3B,CAAC,CAAA;YACF,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA2B,CAAA;YAE9D,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACxC,MAAM,iBAAiB,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,IAAI,CAAC,CAAA;gBAC3D,MAAM,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;gBACzC,SAAQ;YACV,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,MAAM,IAAI,YAAY,CAAC;oBACrB,IAAI,EAAE,4BAA4B;oBAClC,OAAO,EAAE,sBAAsB,MAAM,aAAa,IAAI,CAAC,WAAW,EAAE;oBACpE,IAAI,EAAE,sFAAsF;oBAC5F,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE;iBAChD,CAAC,CAAA;YACJ,CAAC;YAED,OAAO,IAAI,CAAC,MAAM,CAAA;QACpB,CAAC;IACH,CAAC;IAED,OAAO;QACL,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAkB,aAAa,EAAE,MAAM,CAAC;QAErE,KAAK,CAAC,eAAe,CAAC,MAAM;YAC1B,MAAM,IAAI,CAAyB,iBAAiB,EAAE,MAAM,CAAC,CAAA;QAC/D,CAAC;QAED,KAAK,CAAC,mBAAmB,CAAC,eAAe,EAAE,IAAI;YAC7C,MAAM,IAAI,CAAO,qBAAqB,EAAE;gBACtC,iBAAiB,EAAE,eAAe;gBAClC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;aACxC,CAAC,CAAA;QACJ,CAAC;QAED,UAAU,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,CACrC,IAAI,CAA4B,YAAY,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;KACrF,CAAA;AACH,CAAC"}

package/dist/providers/telegram/inbound.d.ts

@@ -0,0 +1,21 @@
+import type { InboundHandler } from '../../adapter.js';
+import type { CommandRouter } from '../../inbound/router.js';
+import type { ChannelLinkStore } from '../../linking/store.js';
+import type { TelegramClient, TelegramUpdate } from './client.js';
+export interface TelegramInboundDeps {
+    readonly client: TelegramClient;
+    readonly linkStore: ChannelLinkStore;
+    readonly router: CommandRouter;
+    /** The handler registered via the adapter's `onInbound()`, if any. */
+    getExternalHandler(): InboundHandler | undefined;
+}
+/**
+ * The real routing/authorization wiring for one inbound Telegram update —
+ * extracted from the adapter so it is directly testable without spinning
+ * the real long-polling loop. Handles both a typed text command and a
+ * button press (`callback_query`, whose `data` is itself a command string
+ * rendered by `render.ts`) through the exact same `CommandRouter.route()`,
+ * never a second, parallel authorization path.
+ */
+export declare function createTelegramInboundHandler(deps: TelegramInboundDeps): (update: TelegramUpdate) => Promise<void>;
+//# sourceMappingURL=inbound.d.ts.map

package/dist/providers/telegram/inbound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../../../src/providers/telegram/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AASjE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,sEAAsE;IACtE,kBAAkB,IAAI,cAAc,GAAG,SAAS,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,GACxB,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAgE3C"}

package/dist/providers/telegram/inbound.js

@@ -0,0 +1,72 @@
+const CHANNEL_NAME = 'telegram';
+const MARKDOWN_V2_SPECIAL = /[_*[\]()~`>#+\-=|{}.!\\]/g;
+function escapePlainReply(text) {
+    return text.replace(MARKDOWN_V2_SPECIAL, (char) => `\\${char}`);
+}
+/**
+ * The real routing/authorization wiring for one inbound Telegram update —
+ * extracted from the adapter so it is directly testable without spinning
+ * the real long-polling loop. Handles both a typed text command and a
+ * button press (`callback_query`, whose `data` is itself a command string
+ * rendered by `render.ts`) through the exact same `CommandRouter.route()`,
+ * never a second, parallel authorization path.
+ */
+export function createTelegramInboundHandler(deps) {
+    async function resolveIdentity(channelUserId) {
+        return deps.linkStore.resolveIdentity(CHANNEL_NAME, channelUserId);
+    }
+    async function reply(chatId, text) {
+        await deps.client.sendMessage({ chat_id: chatId, text: escapePlainReply(text) });
+    }
+    async function handleText(chatId, channelUserId, text) {
+        let identity = await resolveIdentity(channelUserId);
+        if (identity.linkedUserId === null) {
+            // An unlinked identity gets exactly one thing to try: the message AS
+            // a linking code. Any other failure stays silent — "Une identité de
+            // canal non liée à un compte est ignorée, sans réponse."
+            try {
+                await deps.linkStore.verifyCode(text.trim(), CHANNEL_NAME, channelUserId);
+                identity = await resolveIdentity(channelUserId);
+                await reply(chatId, '✅ Compte lié. Vous pouvez maintenant utiliser les commandes.');
+            }
+            catch {
+                // Wrong/expired/nonexistent code from an unlinked identity: silence.
+            }
+            const handler = deps.getExternalHandler();
+            if (handler !== undefined)
+                await handler({ text, identity });
+            return;
+        }
+        const handler = deps.getExternalHandler();
+        if (handler !== undefined)
+            await handler({ text, identity });
+        const result = await deps.router.route(text, identity);
+        if (!result.shouldReply)
+            return;
+        if (result.kind === 'forbidden') {
+            await reply(chatId, "🚫 Vous n'avez pas la permission d'exécuter cette commande.");
+        }
+        else if (result.kind === 'unrecognized') {
+            await reply(chatId, `Commande inconnue : ${result.commandName}`);
+        }
+    }
+    return async function handleUpdate(update) {
+        if (update.message?.text !== undefined && update.message.from !== undefined) {
+            await handleText(String(update.message.chat.id), String(update.message.from.id), update.message.text);
+            return;
+        }
+        if (update.callback_query !== undefined) {
+            const query = update.callback_query;
+            const chatId = query.message === undefined ? undefined : String(query.message.chat.id);
+            const channelUserId = String(query.from.id);
+            const data = query.data ?? '';
+            if (chatId !== undefined && data.length > 0) {
+                await handleText(chatId, channelUserId, data);
+            }
+            // Dismiss the button's loading state regardless of outcome — a UI
+            // affordance, not a disclosure.
+            await deps.client.answerCallbackQuery(query.id);
+        }
+    };
+}
+//# sourceMappingURL=inbound.js.map

package/dist/providers/telegram/inbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound.js","sourceRoot":"","sources":["../../../src/providers/telegram/inbound.ts"],"names":[],"mappings":"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"}

package/dist/providers/telegram/render.d.ts

@@ -0,0 +1,15 @@
+import type { ChannelMessage } from '../../adapter.js';
+import type { TelegramReplyMarkup } from './client.js';
+export declare function escapeMarkdownV2(text: string): string;
+export interface RenderedTelegramMessage {
+    readonly text: string;
+    readonly replyMarkup?: TelegramReplyMarkup;
+}
+/**
+ * Renders one of the lot's three fixed message levels into Telegram
+ * MarkdownV2 text plus (for an alert with actions) inline buttons. Every
+ * piece of user-authored text is escaped; only the structural markup this
+ * function itself adds (bold, bullets) is left unescaped.
+ */
+export declare function renderTelegramMessage(message: ChannelMessage): RenderedTelegramMessage;
+//# sourceMappingURL=render.d.ts.map

package/dist/providers/telegram/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/providers/telegram/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,cAAc,EAAmB,MAAM,kBAAkB,CAAA;AACtF,OAAO,KAAK,EAAwB,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAY5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAkCD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAA;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,uBAAuB,CA+CtF"}

package/dist/providers/telegram/render.js

@@ -0,0 +1,87 @@
+/**
+ * "On n'écrit pas de Markdown Telegram dans le code métier." All
+ * Telegram-specific rendering lives here, entirely inside this adapter —
+ * `ChannelMessage` itself never knows Telegram's escaping rules exist.
+ */
+// Telegram's MarkdownV2 requires escaping these characters outside of an
+// entity (https://core.telegram.org/bots/api#markdownv2-style).
+const MARKDOWN_V2_SPECIAL = /[_*[\]()~`>#+\-=|{}.!\\]/g;
+export function escapeMarkdownV2(text) {
+    return text.replace(MARKDOWN_V2_SPECIAL, (char) => `\\${char}`);
+}
+const SEVERITY_PREFIX = {
+    info: 'ℹ️',
+    warning: '⚠️',
+    critical: '🔴',
+};
+/**
+ * Telegram's real, hard API limit on `sendMessage`'s `text`
+ * (https://core.telegram.org/bots/api#sendmessage) — not the abstract
+ * screen-budget `buildReport` (`../../formats/report.js`) already enforces
+ * at construction time. That budget is deliberately smaller and about
+ * readability; this one is a last-resort safety net so a `ReportChannelMessage`
+ * assembled without going through `buildReport` can never produce a request
+ * Telegram would reject outright.
+ */
+const TELEGRAM_MAX_TEXT_CHARS = 4096;
+const TRUNCATION_MARK = '…';
+function renderActions(actions) {
+    if (actions === undefined || actions.length === 0)
+        return undefined;
+    const buttons = actions.map((action) => ({
+        text: action.label,
+        // The callback_data IS the command text a button press routes as —
+        // reusing the exact same `CommandRouter.route()` a typed command goes
+        // through, never a second, parallel authorization path.
+        callback_data: action.id,
+    }));
+    return { inline_keyboard: [buttons] };
+}
+/**
+ * Renders one of the lot's three fixed message levels into Telegram
+ * MarkdownV2 text plus (for an alert with actions) inline buttons. Every
+ * piece of user-authored text is escaped; only the structural markup this
+ * function itself adds (bold, bullets) is left unescaped.
+ */
+export function renderTelegramMessage(message) {
+    if (message.level === 'notification') {
+        // "Information sans action. Une ligne."
+        return { text: escapeMarkdownV2(message.text) };
+    }
+    if (message.level === 'alert') {
+        const prefix = SEVERITY_PREFIX[message.severity];
+        const lines = [
+            `${prefix} *${escapeMarkdownV2(message.title)}*`,
+            escapeMarkdownV2(message.context),
+            `➡️ ${escapeMarkdownV2(message.expectedAction)}`,
+            `[${escapeMarkdownV2('Voir dans l’admin')}](${message.adminUrl})`,
+        ];
+        const replyMarkup = renderActions(message.actions);
+        return { text: lines.join('\n\n'), ...(replyMarkup === undefined ? {} : { replyMarkup }) };
+    }
+    // 'report' — "Chiffres clés en tête, détail ensuite, jamais plus d'un
+    // écran sans repli."
+    const lines = [`*${escapeMarkdownV2(message.title)}*`];
+    if (message.keyFigures.length > 0) {
+        lines.push(message.keyFigures
+            .map((figure) => `*${escapeMarkdownV2(figure.value)}* ${escapeMarkdownV2(figure.label)}`)
+            .join('  ·  '));
+    }
+    for (const section of message.sections) {
+        const heading = section.heading === undefined ? '' : `*${escapeMarkdownV2(section.heading)}*\n`;
+        lines.push(`${heading}${escapeMarkdownV2(section.body)}`);
+    }
+    const footer = message.moreUrl === undefined
+        ? ''
+        : `\n\n[${escapeMarkdownV2('Voir le détail')}](${message.moreUrl})`;
+    const body = lines.join('\n\n');
+    // Telegram's real limit applies to `body + footer` together — the footer
+    // (the reader's only way to the full detail) must never itself be the
+    // part that gets cut off, so the body is what shrinks.
+    const budget = TELEGRAM_MAX_TEXT_CHARS - footer.length;
+    const truncated = body.length > budget
+        ? `${body.slice(0, Math.max(0, budget - TRUNCATION_MARK.length))}${TRUNCATION_MARK}`
+        : body;
+    return { text: `${truncated}${footer}` };
+}
+//# sourceMappingURL=render.js.map

package/dist/providers/telegram/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/providers/telegram/render.ts"],"names":[],"mappings":"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"}

package/dist/providers/webhook/adapter.d.ts

@@ -0,0 +1,40 @@
+import type { ChannelAdapter } from '../../adapter.js';
+import { type WebhookActionLinkOptions } from './render.js';
+export type WebhookFetch = (url: string, init: {
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+}>;
+export interface WebhookAdapterOptions {
+    /** Shared secret signing every outbound request — the receiver's `verifyIncomingWebhook` must use the same value. */
+    readonly secret: string;
+    /** Required only if messages with actions (e.g. approvals) are ever sent — see `render.ts`. */
+    readonly actionLinks?: WebhookActionLinkOptions;
+    /** Defaults to the global `fetch`; overridable for tests. */
+    readonly fetchImpl?: WebhookFetch;
+}
+/**
+ * "Webhook générique signé" (L6 task 11) — the general-purpose "any HTTP
+ * endpoint" channel. `target.id` is the receiving URL itself (this is what
+ * `ChannelTarget`'s "platform-side identifier" means for a channel whose
+ * platform IS arbitrary HTTP): one adapter instance, one shared signing
+ * secret, any number of destination URLs.
+ *
+ * Outbound-only for real command execution: `capabilities.buttons` is
+ * `false` (no UI to click, hence the signed-link rendering, same pattern as
+ * the email adapter, L6 task 8) and `capabilities.inbound` is `false` —
+ * building real inbound COMMAND execution for an arbitrary third-party
+ * caller is a materially different, larger undertaking (it would need a
+ * real HTTP route wired to a live site, per-integration identity linking
+ * decisions, and its own authorization story) than this task's actual,
+ * security-critical deliverable: the signing/verification PRIMITIVE
+ * (`signing.ts`), which is real, complete, and exercised end-to-end here by
+ * `send()`. `verifyIdentity` is an honest refusal, exactly matching the
+ * email adapter's precedent, rather than a half-built linking flow with no
+ * real inbound transport to carry it.
+ */
+export declare function createWebhookAdapter(options: WebhookAdapterOptions): ChannelAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/providers/webhook/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/webhook/adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAwB,KAAK,wBAAwB,EAAE,MAAM,aAAa,CAAA;AASjF,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KACpE,OAAO,CAAC;IACX,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAC,CAAA;AAEF,MAAM,WAAW,qBAAqB;IACpC,qHAAqH;IACrH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,+FAA+F;IAC/F,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAA;IAC/C,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAoDnF"}

package/dist/providers/webhook/adapter.js

@@ -0,0 +1,71 @@
+import { CogentaError } from '@cogenta/core';
+import { renderWebhookPayload } from './render.js';
+import { signOutgoingWebhook, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, } from './signing.js';
+const CHANNEL_NAME = 'webhook';
+/**
+ * "Webhook générique signé" (L6 task 11) — the general-purpose "any HTTP
+ * endpoint" channel. `target.id` is the receiving URL itself (this is what
+ * `ChannelTarget`'s "platform-side identifier" means for a channel whose
+ * platform IS arbitrary HTTP): one adapter instance, one shared signing
+ * secret, any number of destination URLs.
+ *
+ * Outbound-only for real command execution: `capabilities.buttons` is
+ * `false` (no UI to click, hence the signed-link rendering, same pattern as
+ * the email adapter, L6 task 8) and `capabilities.inbound` is `false` —
+ * building real inbound COMMAND execution for an arbitrary third-party
+ * caller is a materially different, larger undertaking (it would need a
+ * real HTTP route wired to a live site, per-integration identity linking
+ * decisions, and its own authorization story) than this task's actual,
+ * security-critical deliverable: the signing/verification PRIMITIVE
+ * (`signing.ts`), which is real, complete, and exercised end-to-end here by
+ * `send()`. `verifyIdentity` is an honest refusal, exactly matching the
+ * email adapter's precedent, rather than a half-built linking flow with no
+ * real inbound transport to carry it.
+ */
+export function createWebhookAdapter(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    return {
+        name: CHANNEL_NAME,
+        capabilities: {
+            richText: false,
+            buttons: false,
+            threads: false,
+            attachments: false,
+            inbound: false,
+        },
+        async send(target, message) {
+            const payload = renderWebhookPayload(message, options.actionLinks);
+            const rawBody = JSON.stringify(payload);
+            const signed = signOutgoingWebhook(options.secret, rawBody);
+            const response = await fetchImpl(target.id, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    [WEBHOOK_TIMESTAMP_HEADER]: signed.timestamp,
+                    [WEBHOOK_SIGNATURE_HEADER]: signed.signature,
+                },
+                body: rawBody,
+            });
+            if (!response.ok) {
+                throw new CogentaError({
+                    code: 'CHANNEL_WEBHOOK_DELIVERY_FAILED',
+                    message: `Webhook delivery to ${target.id} failed with status ${response.status}.`,
+                    hint: 'Check that the target URL is reachable and returns a 2xx status for a valid signed request.',
+                    details: { url: target.id, status: response.status },
+                });
+            }
+            // A generic webhook receiver has no message-id concept of its own to
+            // hand back — the timestamp+signature pair is the only real,
+            // independently-verifiable identifier this send actually produced.
+            return `${signed.timestamp}:${signed.signature}`;
+        },
+        async verifyIdentity() {
+            throw new CogentaError({
+                code: 'CHANNEL_WEBHOOK_INBOUND_UNSUPPORTED',
+                message: 'The generic webhook adapter does not support identity linking — it is outbound-only.',
+                hint: 'Link accounts through a channel with capabilities.inbound === true (e.g. Telegram, Slack, Discord).',
+            });
+        },
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/providers/webhook/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/providers/webhook/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAQ5C,OAAO,EAAE,oBAAoB,EAAiC,MAAM,aAAa,CAAA;AACjF,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,cAAc,CAAA;AAErB,MAAM,YAAY,GAAG,SAAS,CAAA;AAmB9B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,MAAM,SAAS,GAAiB,OAAO,CAAC,SAAS,IAAK,KAAiC,CAAA;IAEvF,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,YAAY,EAAE;YACZ,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,KAAK;YACd,WAAW,EAAE,KAAK;YAClB,OAAO,EAAE,KAAK;SACf;QAED,KAAK,CAAC,IAAI,CAAC,MAAqB,EAAE,OAAuB;YACvD,MAAM,OAAO,GAAG,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;YAClE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;YACvC,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;YAE3D,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE;gBAC1C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC,SAAS;oBAC5C,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC,SAAS;iBAC7C;gBACD,IAAI,EAAE,OAAO;aACd,CAAC,CAAA;YAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,YAAY,CAAC;oBACrB,IAAI,EAAE,iCAAiC;oBACvC,OAAO,EAAE,uBAAuB,MAAM,CAAC,EAAE,uBAAuB,QAAQ,CAAC,MAAM,GAAG;oBAClF,IAAI,EAAE,6FAA6F;oBACnG,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE;iBACrD,CAAC,CAAA;YACJ,CAAC;YAED,qEAAqE;YACrE,6DAA6D;YAC7D,mEAAmE;YACnE,OAAO,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,EAAE,CAAA;QAClD,CAAC;QAED,KAAK,CAAC,cAAc;YAClB,MAAM,IAAI,YAAY,CAAC;gBACrB,IAAI,EAAE,qCAAqC;gBAC3C,OAAO,EACL,sFAAsF;gBACxF,IAAI,EAAE,qGAAqG;aAC5G,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/providers/webhook/render.d.ts

@@ -0,0 +1,26 @@
+import type { ChannelMessage } from '../../adapter.js';
+import { type EmailActionLinkOptions } from '../email/render.js';
+export interface WebhookActionLinkOptions extends EmailActionLinkOptions {
+}
+export interface WebhookPayload {
+    readonly level: ChannelMessage['level'];
+    readonly title: string;
+    readonly text: string;
+    readonly actions?: readonly {
+        readonly label: string;
+        readonly url: string;
+    }[];
+}
+/**
+ * A generic webhook receiver has no rendering surface of its own (no
+ * Markdown dialect, no Block Kit) — the payload is plain, structured JSON.
+ * Actions still can't be buttons ("## Approbations depuis le canal": "Sur un
+ * canal sans boutons [...] l'action est un lien signé à usage unique"), so
+ * this reuses `email/render.ts`'s real validation (it already throws
+ * `CHANNEL_EMAIL_TRANSPORT_ERROR` for an unrenderable action or a missing
+ * `actionLinks` config — that check is not duplicated here) for its plain
+ * text and only rebuilds the action *links* locally, since the payload shape
+ * (label/url pairs) differs from email's HTML anchor rendering.
+ */
+export declare function renderWebhookPayload(message: ChannelMessage, actionLinks?: WebhookActionLinkOptions): WebhookPayload;
+//# sourceMappingURL=render.d.ts.map

package/dist/providers/webhook/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/providers/webhook/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAErE,OAAO,EAAE,KAAK,sBAAsB,EAAsB,MAAM,oBAAoB,CAAA;AAEpF,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;CAAG;AAE3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC/E;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,cAAc,EACvB,WAAW,CAAC,EAAE,wBAAwB,GACrC,cAAc,CAgBhB"}

package/dist/providers/webhook/render.js

@@ -0,0 +1,41 @@
+import { buildSignedApprovalLink } from '../../approvals/signed-link.js';
+import { renderEmailMessage } from '../email/render.js';
+/**
+ * `action.id` is command text (`"approve <token>"`/`"deny <token>"`, the
+ * same shape `email/render.ts`'s `actionToLink` already parses) — mirrored
+ * here rather than imported, since that helper is private to its own
+ * module; both wrap the one real primitive, `buildSignedApprovalLink`.
+ */
+function actionToUrl(action, links) {
+    const match = /^(approve|deny)\s+(.+)$/.exec(action.id);
+    const [, word = 'approve', token = action.id] = match ?? [];
+    const decision = word === 'approve' ? 'approved' : 'rejected';
+    return buildSignedApprovalLink(links.baseUrl, links.signingKey, token, decision, links.expiresInSeconds);
+}
+/**
+ * A generic webhook receiver has no rendering surface of its own (no
+ * Markdown dialect, no Block Kit) — the payload is plain, structured JSON.
+ * Actions still can't be buttons ("## Approbations depuis le canal": "Sur un
+ * canal sans boutons [...] l'action est un lien signé à usage unique"), so
+ * this reuses `email/render.ts`'s real validation (it already throws
+ * `CHANNEL_EMAIL_TRANSPORT_ERROR` for an unrenderable action or a missing
+ * `actionLinks` config — that check is not duplicated here) for its plain
+ * text and only rebuilds the action *links* locally, since the payload shape
+ * (label/url pairs) differs from email's HTML anchor rendering.
+ */
+export function renderWebhookPayload(message, actionLinks) {
+    const rendered = renderEmailMessage(message, actionLinks);
+    const actions = message.level === 'alert' && message.actions !== undefined && message.actions.length > 0
+        ? message.actions.map((action) => ({
+            label: action.label,
+            url: actionToUrl(action, actionLinks),
+        }))
+        : undefined;
+    return {
+        level: message.level,
+        title: rendered.subject,
+        text: rendered.text,
+        ...(actions === undefined ? {} : { actions }),
+    };
+}
+//# sourceMappingURL=render.js.map

package/dist/providers/webhook/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/providers/webhook/render.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AACxE,OAAO,EAA+B,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAWpF;;;;;GAKG;AACH,SAAS,WAAW,CAAC,MAAqB,EAAE,KAA+B;IACzE,MAAM,KAAK,GAAG,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACvD,MAAM,CAAC,EAAE,IAAI,GAAG,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,GAAG,KAAK,IAAI,EAAE,CAAA;IAC3D,MAAM,QAAQ,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAA;IAC7D,OAAO,uBAAuB,CAC5B,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,UAAU,EAChB,KAAK,EACL,QAAQ,EACR,KAAK,CAAC,gBAAgB,CACvB,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAuB,EACvB,WAAsC;IAEtC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAA;IACzD,MAAM,OAAO,GACX,OAAO,CAAC,KAAK,KAAK,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QACtF,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,GAAG,EAAE,WAAW,CAAC,MAAM,EAAE,WAAuC,CAAC;SAClE,CAAC,CAAC;QACL,CAAC,CAAC,SAAS,CAAA;IAEf,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,QAAQ,CAAC,OAAO;QACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;KAC9C,CAAA;AACH,CAAC"}

package/dist/providers/webhook/signing.d.ts

@@ -0,0 +1,59 @@
+export interface SignedWebhookRequest {
+    readonly timestamp: string;
+    readonly signature: string;
+}
+/** The two headers an outbound signed webhook carries; a receiver names them however it configures its route. */
+export declare const WEBHOOK_TIMESTAMP_HEADER = "X-Cogenta-Timestamp";
+export declare const WEBHOOK_SIGNATURE_HEADER = "X-Cogenta-Signature";
+/** The outbound half: what `createWebhookAdapter`'s `send()` attaches to every request. */
+export declare function signOutgoingWebhook(secret: string, rawBody: string, nowSeconds?: number): SignedWebhookRequest;
+export type WebhookVerificationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'invalid_signature' | 'expired' | 'replayed';
+};
+/**
+ * Bounded, in-memory replay guard — proportionate to the freshness window a
+ * verifier already enforces (an entry older than the window can never pass
+ * freshness anyway, so nothing needs to be remembered past it). Not a
+ * general-purpose dedup store; one instance per verifying process/secret is
+ * the expected usage, matching how a route handler would own it.
+ */
+export declare class WebhookReplayGuard {
+    #private;
+    /** Returns `true` if `signature` was already recorded within a still-valid window. */
+    hasSeen(signature: string, nowSeconds: number, freshnessWindowSeconds: number): boolean;
+    remember(signature: string, nowSeconds: number): void;
+}
+export interface VerifyIncomingWebhookInput {
+    readonly headers: SignedWebhookRequest;
+    readonly rawBody: string;
+    readonly secret: string;
+    readonly now?: number;
+    readonly freshnessWindowSeconds?: number;
+    /** Omit to skip replay checking (e.g. a caller that already dedupes upstream). */
+    readonly replayGuard?: WebhookReplayGuard;
+}
+/**
+ * Three independent checks, all mandatory, in the order that fails cheapest
+ * first: a malformed/non-numeric timestamp or a stale one is rejected before
+ * ever computing an HMAC over it, and only a request that is both fresh and
+ * authentic is checked for replay (recording a signature for a request that
+ * never even had a valid signature would let an attacker exhaust the replay
+ * guard with garbage).
+ *
+ * Unlike `linking/codes.ts`'s deliberately uniform `CHANNEL_LINK_CODE_INVALID`
+ * (chosen to deny an attacker an enumeration oracle over *which accounts
+ * exist*), this returns a *distinguishable* reason. There is no identity to
+ * enumerate here — a webhook secret is either configured correctly or it
+ * isn't, and telling an operator debugging a misconfigured integration
+ * "your signature doesn't match" versus "your timestamp is stale" versus
+ * "this exact request was already processed" is a legitimate operational
+ * need, not an attack surface: none of the three reasons reveal anything an
+ * attacker couldn't already infer from a generic 401.
+ */
+export declare function verifyIncomingWebhook(input: VerifyIncomingWebhookInput): WebhookVerificationResult;
+/** Throws the typed `CogentaError` matching a failed `verifyIncomingWebhook` result; a no-op on success. */
+export declare function assertValidIncomingWebhook(result: WebhookVerificationResult): void;
+//# sourceMappingURL=signing.d.ts.map

package/dist/providers/webhook/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../../src/providers/webhook/signing.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,iHAAiH;AACjH,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAC7D,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAM7D,2FAA2F;AAC3F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAsC,GACjD,oBAAoB,CAGtB;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,GAAG,UAAU,CAAA;CAAE,CAAA;AAEzF;;;;;;GAMG;AACH,qBAAa,kBAAkB;;IAG7B,sFAAsF;IACtF,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,GAAG,OAAO,CAGtF;IAED,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAEpD;CAOF;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAA;IACxC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,0BAA0B,GAChC,yBAAyB,CAwB3B;AAQD,4GAA4G;AAC5G,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAQlF"}