katanakit-js 2.13.7 → 2.14.0

package/dist/{katanakit-js/adapters → adapters}/express/server.js

@@ -5,8 +5,20 @@ import router from "./router.js";
 /** Module-level state for the Express server. */
 let app = null;
 let started = false;
+let finalized = false;
+/**
+ * Returns the raw request body buffer captured by the JSON parser, if any.
+ * Needed to verify webhook signatures (e.g. `X-Hub-Signature-256`).
+ *
+ * @param request - The Express request.
+ * @returns The raw body buffer, or `undefined` when not available.
+ */
+export function useGetRawBody(request) {
+    return request.rawBody;
+}
 /**
  * Set up CORS, JSON body parser and URL-encoded middleware.
+ * The JSON parser also captures the raw body for signature verification.
  *
  * @param expressApp - Express application instance
  *
@@ -25,7 +37,12 @@ function useExpressSetupMiddlewares(expressApp) {
         methods: ["GET", "POST", "PUT", "DELETE"],
     }));
     expressApp.disable("x-powered-by");
-    expressApp.use(express.json({ limit: "100kb" }));
+    expressApp.use(express.json({
+        limit: "100kb",
+        verify: (req, _res, buf) => {
+            req.rawBody = buf;
+        },
+    }));
     expressApp.use(express.urlencoded({ extended: true, limit: "100kb" }));
 }
 /**
@@ -49,7 +66,8 @@ function useExpressSetupRoutes(expressApp) {
     expressApp.use("/", router);
 }
 /**
- * Set up global error handling and 404 fallback.
+ * Set up global error handling and 404 fallback. Register this AFTER all
+ * channel routers are mounted so it does not shadow them.
  *
  * @param expressApp - Express application instance
  *
@@ -61,7 +79,7 @@ function useExpressSetupRoutes(expressApp) {
  */
 function useExpressSetupErrorHandling(expressApp) {
     expressApp.use((err, _req, res, _next) => {
-        console.error("Unhandled error:", err);
+        useLogger("error", "Unhandled error:", err);
         res.status(500).json({ error: "Internal Server Error" });
     });
     expressApp.use((_req, res) => {
@@ -69,14 +87,17 @@ function useExpressSetupErrorHandling(expressApp) {
     });
 }
 /**
- * Create and configure the Express application.
+ * Create and configure the Express application. Mount channel routers on the
+ * returned app BEFORE calling {@link useExpressFinalize} / {@link useExpressStart},
+ * otherwise the 404 catch-all will shadow them.
  *
  * @returns Configured Express Application instance
  *
  * @example
  * ```ts
  * const expressApp = useExpressCreate();
- * // App is ready with middleware, routes and error handling
+ * expressApp.use("/assistant", useCreateAssistantRouter());
+ * useExpressStart();
  * ```
  */
 export const useExpressCreate = () => {
@@ -85,11 +106,28 @@ export const useExpressCreate = () => {
     app = express();
     useExpressSetupMiddlewares(app);
     useExpressSetupRoutes(app);
-    useExpressSetupErrorHandling(app);
     return app;
 };
+/**
+ * Registers the error handler and 404 catch-all. Idempotent. Call this after
+ * mounting every channel router so it runs last. {@link useExpressStart}
+ * invokes it automatically.
+ *
+ * @example
+ * ```ts
+ * useExpressGetApp().use("/assistant", useCreateAssistantRouter());
+ * useExpressFinalize();
+ * ```
+ */
+export const useExpressFinalize = () => {
+    if (finalized)
+        return;
+    finalized = true;
+    useExpressSetupErrorHandling(useExpressCreate());
+};
 /**
  * Start the Express HTTP server. Idempotent — subsequent calls are no-ops.
+ * Finalizes error handling before listening.
  *
  * @param port - Port to listen on (default: 3000)
  * @param host - Host to bind to (default: "localhost")
@@ -104,6 +142,7 @@ export const useExpressStart = (port = 3000, host = "localhost") => {
     if (started)
         return;
     started = true;
+    useExpressFinalize();
     const expressApp = useExpressCreate();
     expressApp.listen(port, host, () => {
         useLogger("info", `Server running on http://${host}:${port}`);

package/dist/adapters/express/server.js.map

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

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/nuxt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/nuxt/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/adapters/nuxt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/nuxt/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/adapters/nuxt/nuxt.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nuxt.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/nuxt/nuxt.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAsBxD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAUxE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG;IAC3D,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,EAAE,EAAE,OAAO,CAAC;CACZ,CAaA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EACjC,KAAK,EAAE;IAAE,IAAI,EAAE;QAAE,GAAG,EAAE;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,EAChD,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GACpB,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAWvC"}

package/dist/adapters/nuxt/nuxt.service.js.map

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

package/dist/adapters/telegram/index.d.ts

@@ -0,0 +1,3 @@
+export type { TelegramConfig, TelegramPollingOptions, TelegramReplyFn, } from "./telegram.service.js";
+export { TELEGRAM_API_BASE, useHandleTelegramUpdate, useInitTelegram, useStartTelegramPolling, useTelegramSendMessage, } from "./telegram.service.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/telegram/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/telegram/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,cAAc,EACd,sBAAsB,EACtB,eAAe,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACN,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,uBAAuB,EACvB,sBAAsB,GACtB,MAAM,uBAAuB,CAAC"}

package/dist/adapters/telegram/index.js

@@ -0,0 +1,2 @@
+export { TELEGRAM_API_BASE, useHandleTelegramUpdate, useInitTelegram, useStartTelegramPolling, useTelegramSendMessage, } from "./telegram.service.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/telegram/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/telegram/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACN,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,uBAAuB,EACvB,sBAAsB,GACtB,MAAM,uBAAuB,CAAC"}

package/dist/adapters/telegram/main.d.ts

@@ -0,0 +1,2 @@
+import "dotenv/config";
+//# sourceMappingURL=main.d.ts.map

package/dist/adapters/telegram/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/adapters/telegram/main.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC"}

package/dist/adapters/telegram/main.js

@@ -0,0 +1,11 @@
+import "dotenv/config";
+import { useInitAssistant } from "../../core/services/assistant.service.js";
+import { useInitTelegram, useStartTelegramPolling } from "./telegram.service.js";
+const token = process.env.TELEGRAM_BOT_TOKEN;
+if (!token) {
+    throw new Error("[telegram] TELEGRAM_BOT_TOKEN is not set.");
+}
+useInitAssistant();
+useInitTelegram({ token });
+useStartTelegramPolling();
+//# sourceMappingURL=main.js.map

package/dist/adapters/telegram/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../src/adapters/telegram/main.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;AAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;IACZ,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;AAC9D,CAAC;AAED,gBAAgB,EAAE,CAAC;AACnB,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAE3B,uBAAuB,EAAE,CAAC"}

package/dist/adapters/telegram/telegram.service.d.ts

@@ -0,0 +1,60 @@
+import type { AssistantResult } from "../../types/index.js";
+/** Default Telegram Bot API base URL. */
+export declare const TELEGRAM_API_BASE = "https://api.telegram.org";
+/** Configuration for a Telegram bot. */
+export interface TelegramConfig {
+    token: string;
+    apiBaseUrl?: string;
+}
+/** Callback producing an assistant reply for a channel session. */
+export type TelegramReplyFn = (sessionId: string, text: string) => Promise<AssistantResult>;
+/**
+ * Registers the Telegram bot configuration.
+ *
+ * @param cfg - Bot token (from BotFather) and optional API base URL.
+ *
+ * @example
+ * ```ts
+ * useInitTelegram({ token: process.env.TELEGRAM_BOT_TOKEN });
+ * ```
+ */
+export declare function useInitTelegram(cfg: TelegramConfig): void;
+/**
+ * Sends a text message to a Telegram chat.
+ *
+ * @param chatId - Destination chat id.
+ * @param text - Message body.
+ * @returns The Telegram API response.
+ */
+export declare function useTelegramSendMessage(chatId: number, text: string): Promise<Response>;
+/**
+ * Handles a single Telegram update: replies to inbound text messages.
+ *
+ * @param update - A Telegram update object (from `getUpdates` or a webhook).
+ * @param reply - Reply callback. Defaults to the assistant {@link useReply}.
+ *
+ * @example
+ * ```ts
+ * await useHandleTelegramUpdate(update);
+ * ```
+ */
+export declare function useHandleTelegramUpdate(update: unknown, reply?: TelegramReplyFn): Promise<void>;
+/** Options for the long-polling loop. */
+export interface TelegramPollingOptions {
+    intervalMs?: number;
+    signal?: AbortSignal;
+    reply?: TelegramReplyFn;
+}
+/**
+ * Starts the long-polling loop that keeps fetching and answering updates.
+ * Runs until the provided signal aborts (or forever).
+ *
+ * @param options - Polling cadence, abort signal and reply callback.
+ *
+ * @example
+ * ```ts
+ * useStartTelegramPolling();
+ * ```
+ */
+export declare function useStartTelegramPolling(options?: TelegramPollingOptions): Promise<void>;
+//# sourceMappingURL=telegram.service.d.ts.map

package/dist/adapters/telegram/telegram.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/telegram/telegram.service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,yCAAyC;AACzC,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAa5F;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAEzD;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAO5F;AAQD;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC5C,MAAM,EAAE,OAAO,EACf,KAAK,GAAE,eAA0B,GAC/B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,eAAe,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCjG"}

package/dist/adapters/telegram/telegram.service.js

@@ -0,0 +1,103 @@
+import { useReply } from "../../core/services/assistant.service.js";
+import { useLogger } from "../../core/services/logger.service.js";
+import { useSleep } from "../../core/services/utils.service.js";
+/** Default Telegram Bot API base URL. */
+export const TELEGRAM_API_BASE = "https://api.telegram.org";
+/** Module-level bot configuration. */
+let config = null;
+/** Retrieves the configured bot or throws. */
+function getConfig() {
+    if (!config) {
+        throw new Error("[Telegram] Not configured. Call useInitTelegram() first.");
+    }
+    return config;
+}
+/**
+ * Registers the Telegram bot configuration.
+ *
+ * @param cfg - Bot token (from BotFather) and optional API base URL.
+ *
+ * @example
+ * ```ts
+ * useInitTelegram({ token: process.env.TELEGRAM_BOT_TOKEN });
+ * ```
+ */
+export function useInitTelegram(cfg) {
+    config = { ...cfg };
+}
+/**
+ * Sends a text message to a Telegram chat.
+ *
+ * @param chatId - Destination chat id.
+ * @param text - Message body.
+ * @returns The Telegram API response.
+ */
+export async function useTelegramSendMessage(chatId, text) {
+    const { token, apiBaseUrl } = getConfig();
+    return fetch(`${apiBaseUrl ?? TELEGRAM_API_BASE}/bot${token}/sendMessage`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ chat_id: chatId, text }),
+    });
+}
+/**
+ * Handles a single Telegram update: replies to inbound text messages.
+ *
+ * @param update - A Telegram update object (from `getUpdates` or a webhook).
+ * @param reply - Reply callback. Defaults to the assistant {@link useReply}.
+ *
+ * @example
+ * ```ts
+ * await useHandleTelegramUpdate(update);
+ * ```
+ */
+export async function useHandleTelegramUpdate(update, reply = useReply) {
+    const message = update?.message;
+    if (!message?.text || message.text.trim() === "")
+        return;
+    const sessionId = `telegram:${message.chat.id}`;
+    const result = await reply(sessionId, message.text);
+    if (result.ok) {
+        await useTelegramSendMessage(message.chat.id, result.data.reply);
+    }
+}
+/**
+ * Starts the long-polling loop that keeps fetching and answering updates.
+ * Runs until the provided signal aborts (or forever).
+ *
+ * @param options - Polling cadence, abort signal and reply callback.
+ *
+ * @example
+ * ```ts
+ * useStartTelegramPolling();
+ * ```
+ */
+export async function useStartTelegramPolling(options = {}) {
+    const { intervalMs = 2000, signal, reply = useReply } = options;
+    const { token, apiBaseUrl } = getConfig();
+    const base = apiBaseUrl ?? TELEGRAM_API_BASE;
+    let offset = 0;
+    while (!signal?.aborted) {
+        try {
+            const response = await fetch(`${base}/bot${token}/getUpdates?timeout=30&offset=${offset}`, {
+                signal,
+            });
+            if (!response.ok) {
+                throw new Error(`getUpdates HTTP ${response.status}`);
+            }
+            const data = (await response.json());
+            for (const update of data.result ?? []) {
+                offset = Math.max(offset, update.update_id + 1);
+                await useHandleTelegramUpdate(update, reply);
+            }
+        }
+        catch (error) {
+            if (signal?.aborted)
+                break;
+            const message = error instanceof Error ? error.message : String(error);
+            useLogger("error", `[Telegram] ${message}`);
+        }
+        await useSleep(intervalMs);
+    }
+}
+//# sourceMappingURL=telegram.service.js.map

package/dist/adapters/telegram/telegram.service.js.map

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

package/dist/adapters/vue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/vue/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/vue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/vue/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/vue/vue.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/vue/vue.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,QAAQ,EAEb,KAAK,GAAG,EAKR,MAAM,KAAK,CAAC;AAGb,OAAO,KAAK,EAAE,QAAQ,EAAe,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAClC,sDAAsD;IACtD,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACpB,0DAA0D;IAC1D,KAAK,EAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC5B,sCAAsC;IACtC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACtB,oCAAoC;IACpC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC/B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,GAC5B,gBAAgB,CAAC,CAAC,CAAC,CAiErB"}

package/dist/adapters/vue/vue.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.service.js","sourceRoot":"","sources":["../../../src/adapters/vue/vue.service.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,kBAAkB,EAClB,KAAK,EAEL,WAAW,EAEX,GAAG,EACH,UAAU,EACV,KAAK,EACL,KAAK,GACL,MAAM,KAAK,CAAC;AAEb,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAiB/D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,cAAc,CAC7B,OAAe,EACf,YAAoB,EACpB,OAA8B;IAE9B,MAAM,IAAI,GAAG,UAAU,CAAW,IAAI,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,GAAG,CAAkB,IAAI,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IAE1B,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,gBAAgB,GAA2B,IAAI,CAAC;IACpD,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE;QACzC,MAAM,OAAO,GAAG,EAAE,cAAc,CAAC;QACjC,gBAAgB,EAAE,KAAK,EAAE,CAAC;QAC1B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,gBAAgB,GAAG,UAAU,CAAC;QAE9B,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QAEnB,MAAM,MAAM,GAAmB,MAAM,QAAQ,CAAI,OAAO,EAAE,YAAY,EAAE;YACvE,MAAM,EAAE,KAAK;YACb,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC;YAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;SACzB,CAAC,CAAC;QAEH,IAAI,QAAQ,IAAI,OAAO,KAAK,cAAc,EAAE,CAAC;YAC5C,OAAO;QACR,CAAC;QAED,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC;YACzB,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;aAAM,CAAC;YACP,4DAA4D;YAC5D,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACjF,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YAC5B,CAAC;QACF,CAAC;QAED,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC,CAAC;IAEF,6DAA6D;IAC7D,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACpB,KAAK,CACJ,OAAO,EACP,GAAG,EAAE;YACJ,KAAK,OAAO,EAAE,CAAC;QAChB,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACd,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,IAAI,kBAAkB,EAAE,EAAE,CAAC;QAC1B,WAAW,CAAC,GAAG,EAAE;YAChB,QAAQ,GAAG,IAAI,CAAC;YAChB,gBAAgB,EAAE,KAAK,EAAE,CAAC;QAC3B,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,0BAA0B;IAC1B,KAAK,OAAO,EAAE,CAAC;IAEf,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC"}

package/dist/adapters/whatsapp/index.d.ts

@@ -0,0 +1,3 @@
+export type { WhatsAppConfig, WhatsAppReplyFn } from "./whatsapp.service.js";
+export { useCreateWhatsAppRouter, useHandleWhatsAppMessage, useInitWhatsApp, useSendWhatsAppMessage, useStartWhatsApp, useVerifyWhatsAppSignature, useVerifyWhatsAppWebhook, WHATSAPP_API_BASE, WHATSAPP_API_VERSION, WHATSAPP_MAX_MESSAGES_PER_WEBHOOK, } from "./whatsapp.service.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/whatsapp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/whatsapp/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EACN,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,EACpB,iCAAiC,GACjC,MAAM,uBAAuB,CAAC"}

package/dist/adapters/whatsapp/index.js

@@ -0,0 +1,2 @@
+export { useCreateWhatsAppRouter, useHandleWhatsAppMessage, useInitWhatsApp, useSendWhatsAppMessage, useStartWhatsApp, useVerifyWhatsAppSignature, useVerifyWhatsAppWebhook, WHATSAPP_API_BASE, WHATSAPP_API_VERSION, WHATSAPP_MAX_MESSAGES_PER_WEBHOOK, } from "./whatsapp.service.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/whatsapp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/whatsapp/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,EACpB,iCAAiC,GACjC,MAAM,uBAAuB,CAAC"}

package/dist/adapters/whatsapp/main.d.ts

@@ -0,0 +1,2 @@
+import "dotenv/config";
+//# sourceMappingURL=main.d.ts.map

package/dist/adapters/whatsapp/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/adapters/whatsapp/main.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC"}

package/dist/adapters/whatsapp/main.js

@@ -0,0 +1,14 @@
+import "dotenv/config";
+import { useInitAssistant } from "../../core/services/assistant.service.js";
+import { useInitWhatsApp, useStartWhatsApp } from "./whatsapp.service.js";
+const token = process.env.WHATSAPP_TOKEN;
+const phoneNumberId = process.env.WHATSAPP_PHONE_NUMBER_ID;
+const verifyToken = process.env.WHATSAPP_VERIFY_TOKEN;
+const appSecret = process.env.WHATSAPP_APP_SECRET;
+if (!token || !phoneNumberId || !verifyToken || !appSecret) {
+    throw new Error("[whatsapp] WHATSAPP_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_VERIFY_TOKEN and WHATSAPP_APP_SECRET must be set.");
+}
+useInitAssistant();
+useInitWhatsApp({ token, phoneNumberId, verifyToken, appSecret });
+useStartWhatsApp(Number(process.env.PORT ?? 3000), process.env.HOST ?? "localhost");
+//# sourceMappingURL=main.js.map

package/dist/adapters/whatsapp/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../src/adapters/whatsapp/main.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE1E,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AACzC,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;AAC3D,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;AACtD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;AAElD,IAAI,CAAC,KAAK,IAAI,CAAC,aAAa,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,EAAE,CAAC;IAC5D,MAAM,IAAI,KAAK,CACd,iHAAiH,CACjH,CAAC;AACH,CAAC;AAED,gBAAgB,EAAE,CAAC;AACnB,eAAe,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;AAElE,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,WAAW,CAAC,CAAC"}

package/dist/adapters/whatsapp/whatsapp.service.d.ts

@@ -0,0 +1,96 @@
+import { Router } from "express";
+import type { AssistantResult } from "../../types/index.js";
+/** Default WhatsApp Cloud API (Graph) base URL. */
+export declare const WHATSAPP_API_BASE = "https://graph.facebook.com";
+/** Default Graph API version. */
+export declare const WHATSAPP_API_VERSION = "v21.0";
+/** Cap of inbound messages processed per webhook payload (cost-amplification guard). */
+export declare const WHATSAPP_MAX_MESSAGES_PER_WEBHOOK = 5;
+/** Configuration for the WhatsApp Cloud API integration. */
+export interface WhatsAppConfig {
+    token: string;
+    phoneNumberId: string;
+    verifyToken: string;
+    /** Meta app secret used to verify webhook signatures (`X-Hub-Signature-256`). */
+    appSecret: string;
+    apiVersion?: string;
+    apiBaseUrl?: string;
+}
+/** Callback producing an assistant reply for a channel session. */
+export type WhatsAppReplyFn = (sessionId: string, text: string) => Promise<AssistantResult>;
+/**
+ * Registers the WhatsApp Cloud API configuration.
+ *
+ * @param cfg - Access token, phone number id and webhook verify token.
+ *
+ * @example
+ * ```ts
+ * useInitWhatsApp({
+ *   token: process.env.WHATSAPP_TOKEN,
+ *   phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,
+ *   verifyToken: process.env.WHATSAPP_VERIFY_TOKEN,
+ *   appSecret: process.env.WHATSAPP_APP_SECRET,
+ * });
+ * ```
+ */
+export declare function useInitWhatsApp(cfg: WhatsAppConfig): void;
+/**
+ * Verifies a Meta webhook delivery signature (`X-Hub-Signature-256`).
+ *
+ * @param rawBody - The raw request body buffer captured by the JSON parser.
+ * @param signatureHeader - Value of the `X-Hub-Signature-256` header.
+ * @returns `true` when the signature matches the app secret HMAC.
+ *
+ * @example
+ * ```ts
+ * const ok = useVerifyWhatsAppSignature(useGetRawBody(req), req.header("x-hub-signature-256"));
+ * ```
+ */
+export declare function useVerifyWhatsAppSignature(rawBody: Buffer | undefined, signatureHeader: string | undefined): boolean;
+/**
+ * Verifies a Meta webhook challenge. Returns the challenge to echo on success,
+ * or `null` when the mode or token is invalid.
+ *
+ * @param mode - `hub.mode` query param.
+ * @param verifyToken - `hub.verify_token` query param.
+ * @param challenge - `hub.challenge` query param.
+ * @returns The challenge string when valid, otherwise `null`.
+ */
+export declare function useVerifyWhatsAppWebhook(mode: string, verifyToken: string, challenge: string): string | null;
+/**
+ * Sends a text message to a WhatsApp number via the Cloud API.
+ *
+ * @param to - Destination number (E.164).
+ * @param text - Message body.
+ * @returns The Graph API response.
+ */
+export declare function useSendWhatsAppMessage(to: string, text: string): Promise<Response>;
+/**
+ * Handles a WhatsApp webhook payload: replies to each inbound text message.
+ *
+ * @param payload - The JSON webhook body from Meta.
+ * @param reply - Reply callback. Defaults to the assistant {@link useReply}.
+ *
+ * @example
+ * ```ts
+ * await useHandleWhatsAppMessage(payload);
+ * ```
+ */
+export declare function useHandleWhatsAppMessage(payload: unknown, reply?: WhatsAppReplyFn): Promise<void>;
+/** Builds the Express router exposing the WhatsApp webhook. */
+export declare function useCreateWhatsAppRouter(): Router;
+/**
+ * Mounts the WhatsApp webhook on the shared Express app and starts the server.
+ *
+ * @param port - Port to listen on (default: 3000)
+ * @param host - Host to bind to (default: "localhost")
+ * @param mountPath - Base path for the webhook routes (default: "/whatsapp")
+ *
+ * @example
+ * ```ts
+ * useStartWhatsApp(3000, "localhost");
+ * // GET /whatsapp/webhook (verify), POST /whatsapp/webhook (messages)
+ * ```
+ */
+export declare function useStartWhatsApp(port?: number, host?: string, mountPath?: string): void;
+//# sourceMappingURL=whatsapp.service.d.ts.map

package/dist/adapters/whatsapp/whatsapp.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/whatsapp/whatsapp.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAkD,MAAM,EAAE,MAAM,SAAS,CAAC;AAKjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,+BAA+B,CAAC;AAE9D,iCAAiC;AACjC,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,wFAAwF;AACxF,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAa5F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAEzD;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,eAAe,EAAE,MAAM,GAAG,SAAS,GACjC,OAAO,CAKT;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CAMf;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkBxF;AAkBD;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC7C,OAAO,EAAE,OAAO,EAChB,KAAK,GAAE,eAA0B,GAC/B,OAAO,CAAC,IAAI,CAAC,CAef;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,IAAI,MAAM,CAwChD;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,SAAO,EAAE,IAAI,SAAc,EAAE,SAAS,SAAc,GAAG,IAAI,CAM/F"}