@better-zap/hono 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Better Zap
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @better-zap/hono
+
+Hono runtime and webhook adapter for Better Zap.

package/dist/index.cjs

@@ -0,0 +1,572 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let hono = require("hono");
+let better_zap = require("better-zap");
+//#region src/plugins/runtime.ts
+function initializePlugins(options) {
+	let pluginContext = {};
+	let pluginServices = {};
+	for (const plugin of options.plugins) {
+		const result = plugin.init?.({
+			database: options.database,
+			config: options.config,
+			context: {
+				...options.coreContext,
+				...pluginContext
+			},
+			services: {
+				...options.coreServices,
+				...pluginServices
+			},
+			log: options.log
+		});
+		if (!result) continue;
+		if (result.context) pluginContext = {
+			...pluginContext,
+			...result.context
+		};
+		if (result.services) pluginServices = {
+			...pluginServices,
+			...result.services
+		};
+	}
+	return {
+		context: {
+			...options.coreContext,
+			...pluginContext
+		},
+		services: {
+			...options.coreServices,
+			...pluginServices
+		}
+	};
+}
+async function runPluginMessageHooks(options) {
+	for (const plugin of options.plugins) {
+		if (!plugin.hooks?.onMessage) continue;
+		try {
+			await plugin.hooks.onMessage(options.ctx);
+		} catch (error) {
+			options.log.error("plugin.on_message_failed", {
+				pluginId: plugin.id,
+				waMessageId: options.ctx.message.id,
+				phone: options.ctx.phone,
+				...(0, better_zap.serializeError)(error)
+			});
+		}
+	}
+}
+async function runPluginStatusHooks(options) {
+	for (const plugin of options.plugins) {
+		if (!plugin.hooks?.onStatusUpdate) continue;
+		try {
+			await plugin.hooks.onStatusUpdate(options.ctx);
+		} catch (error) {
+			options.log.error("plugin.on_status_update_failed", {
+				pluginId: plugin.id,
+				waMessageId: options.ctx.status.id,
+				status: options.ctx.status.status,
+				...(0, better_zap.serializeError)(error)
+			});
+		}
+	}
+}
+//#endregion
+//#region src/handler/conversations.ts
+async function handleListConversations(c) {
+	try {
+		const conversations = await c.get("store").getConversations();
+		return c.json(conversations);
+	} catch (error) {
+		c.get("logger").error("conversations.list_error", (0, better_zap.serializeError)(error));
+		return c.json({ error: "Internal error fetching conversations" }, 500);
+	}
+}
+async function handleGetConversation(c) {
+	try {
+		const phone = c.req.param("phone");
+		if (!phone) return c.json({ error: "phone is required" }, 400);
+		const store = c.get("store");
+		const normalized = (0, better_zap.formatPhone)(decodeURIComponent(phone));
+		const conversation = await store.getConversationByPhone(normalized);
+		if (!conversation) return c.json({ error: "Conversation not found" }, 404);
+		return c.json(conversation);
+	} catch (error) {
+		c.get("logger").error("conversations.get_error", (0, better_zap.serializeError)(error));
+		return c.json({ error: "Internal error fetching conversation" }, 500);
+	}
+}
+async function handleGetMessages(c) {
+	try {
+		const phone = c.req.param("phone");
+		if (!phone) return c.json({ error: "phone is required" }, 400);
+		const store = c.get("store");
+		const normalized = (0, better_zap.formatPhone)(decodeURIComponent(phone));
+		const conversation = await store.getConversationByPhone(normalized);
+		if (!conversation) return c.json({ error: "Conversation not found" }, 404);
+		const cursor = c.req.query("cursor") || void 0;
+		const limitParam = c.req.query("limit");
+		const limit = limitParam ? parseInt(limitParam, 10) : void 0;
+		const messages = await store.getMessagesByConversationPaginated(conversation.id, cursor, limit);
+		return c.json(messages);
+	} catch (error) {
+		c.get("logger").error("conversations.messages_error", (0, better_zap.serializeError)(error));
+		return c.json({ error: "Internal error fetching messages" }, 500);
+	}
+}
+//#endregion
+//#region src/handler/send.ts
+async function handleSendText(c) {
+	const { to, body, messageType, userId, metadata } = await c.req.json();
+	if (!to || !body) return c.json({ error: "to and body are required" }, 400);
+	const whatsapp = c.get("whatsapp");
+	const logging = messageType ? {
+		messageType,
+		userId,
+		metadata
+	} : void 0;
+	const result = await whatsapp.sendText(to, body, logging);
+	return c.json(result, result.success ? 200 : 500);
+}
+function createSendTemplateHandler(templates) {
+	return async function handleSendTemplate(c) {
+		const body = await c.req.json();
+		if (!body.to || !body.template) return c.json({ error: "to and template are required" }, 400);
+		const whatsapp = c.get("whatsapp");
+		const logging = body.logging ?? (body.messageType ? {
+			messageType: body.messageType,
+			content: body.content || `[template: ${body.template}]`,
+			userId: body.userId,
+			metadata: body.metadata
+		} : void 0);
+		let language = body.language;
+		let components = body.components;
+		if ("params" in body && body.params !== void 0) {
+			if (!(0, better_zap.hasConfiguredTemplates)(templates)) return c.json({ error: "Typed template params require a configured template registry" }, 400);
+			try {
+				const serializedTemplate = (0, better_zap.serializeTemplateFromRegistry)(templates, body.template, {
+					language: body.language,
+					params: body.params
+				});
+				language = serializedTemplate.language;
+				components = serializedTemplate.components;
+			} catch (error) {
+				const message = error instanceof Error ? error.message : "Failed to serialize template from registry";
+				return c.json({ error: message }, 400);
+			}
+		}
+		const result = await whatsapp.sendTemplate(body.to, body.template, language, components, logging);
+		return c.json(result, result.success ? 200 : 500);
+	};
+}
+async function handleSendInteractive(c) {
+	const { to, type, body, buttons, buttonLabel, sections, cards, messageType, userId, metadata } = await c.req.json();
+	if (!to || !body) return c.json({ error: "to and body are required" }, 400);
+	const whatsapp = c.get("whatsapp");
+	const logging = messageType ? {
+		messageType,
+		userId,
+		metadata
+	} : void 0;
+	if (type === "list") {
+		if (!buttonLabel || !sections) return c.json({ error: "buttonLabel and sections are required for list type" }, 400);
+		const result = await whatsapp.sendInteractiveList(to, body, buttonLabel, sections, logging);
+		return c.json(result, result.success ? 200 : 500);
+	}
+	if (type === "carousel") {
+		if (!cards) return c.json({ error: "cards are required for carousel type" }, 400);
+		if (cards.length < 2 || cards.length > 10) return c.json({ error: "carousel requires between 2 and 10 cards" }, 400);
+		const result = await whatsapp.sendInteractiveMediaCarousel({
+			to,
+			body,
+			cards
+		}, logging);
+		return c.json(result, result.success ? 200 : 500);
+	}
+	if (!buttons) return c.json({ error: "buttons are required for button type" }, 400);
+	const result = await whatsapp.sendInteractiveButtons(to, body, buttons, logging);
+	return c.json(result, result.success ? 200 : 500);
+}
+async function handleSendLocation(c) {
+	const { to, latitude, longitude, name, address, messageType, userId, metadata } = await c.req.json();
+	if (!to || latitude == null || longitude == null || !name || !address) return c.json({ error: "to, latitude, longitude, name, and address are required" }, 400);
+	const whatsapp = c.get("whatsapp");
+	const logging = messageType ? {
+		messageType,
+		userId,
+		metadata
+	} : void 0;
+	const result = await whatsapp.sendLocation(to, latitude, longitude, name, address, logging);
+	return c.json(result, result.success ? 200 : 500);
+}
+//#endregion
+//#region src/webhook/signature-verification.ts
+const textEncoder = new TextEncoder();
+let cachedMetaAppSecret = null;
+let cachedMetaHmacKey = null;
+async function verifyMetaWebhookSignature({ rawBody, signatureHeader, appSecret }) {
+	if (!signatureHeader) return false;
+	const [algorithm, signatureHexRaw] = signatureHeader.split("=", 2);
+	if (algorithm?.toLowerCase() !== "sha256" || !signatureHexRaw) return false;
+	const signatureBytes = hexToBytes(signatureHexRaw.trim());
+	if (!signatureBytes) return false;
+	const key = await getMetaHmacKey(appSecret);
+	const expectedSignatureBuffer = await crypto.subtle.sign("HMAC", key, rawBody);
+	return constantTimeEqual(new Uint8Array(expectedSignatureBuffer), signatureBytes);
+}
+function getMetaHmacKey(appSecret) {
+	if (cachedMetaAppSecret === appSecret && cachedMetaHmacKey) return cachedMetaHmacKey;
+	cachedMetaAppSecret = appSecret;
+	cachedMetaHmacKey = crypto.subtle.importKey("raw", textEncoder.encode(appSecret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return cachedMetaHmacKey;
+}
+function hexToBytes(hex) {
+	if (hex.length % 2 !== 0) return null;
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < bytes.length; i += 1) {
+		const value = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+		if (Number.isNaN(value)) return null;
+		bytes[i] = value;
+	}
+	return bytes;
+}
+function constantTimeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i += 1) diff |= a[i] ^ b[i];
+	return diff === 0;
+}
+//#endregion
+//#region src/webhook/message-content.ts
+/**
+* Extract human-readable content from incoming messages for audit logs.
+*/
+function getMessageContent(message) {
+	switch (message.type) {
+		case "text": return message.text?.body || "[texto vazio]";
+		case "image": return `[imagem${message.image?.caption ? `: ${message.image.caption}` : ""}]`;
+		case "audio": return "[áudio]";
+		case "video": return `[vídeo${message.video?.caption ? `: ${message.video.caption}` : ""}]`;
+		case "document": return `[documento: ${message.document?.filename || "arquivo"}]`;
+		case "location": return `[localização: ${message.location?.name || `${message.location?.latitude},${message.location?.longitude}`}]`;
+		case "button": return `[botão: ${message.button?.text}]`;
+		case "interactive":
+			if (message.interactive?.button_reply) return `[resposta botão: ${message.interactive.button_reply.title}]`;
+			if (message.interactive?.list_reply) return `[resposta lista: ${message.interactive.list_reply.title}]`;
+			return "[interativo]";
+		case "sticker": return "[figurinha]";
+		case "reaction": return "[reação]";
+		default: return `[${message.type}]`;
+	}
+}
+//#endregion
+//#region src/webhook/create-webhook-handler.ts
+const textDecoder = new TextDecoder();
+/**
+* Creates a Hono router that handles the full WhatsApp webhook lifecycle.
+*
+* **SDK guarantees (non-hookable):**
+* - Signature is always verified before any processing
+* - Meta always receives a fast 200 OK (processing runs via `waitUntil`)
+* - Hook errors never crash the webhook (wrapped in try/catch)
+* - Contact is resolved and content is extracted before `onMessage`
+* - Status timestamp is parsed to ISO before `onStatusUpdate`
+*
+* @typeParam Env - Hono bindings type (e.g. Cloudflare Worker env).
+*/
+function createWebhookHandler(config) {
+	const log = config.log;
+	const webhook = new hono.Hono();
+	webhook.get("/", (c) => {
+		const mode = c.req.query("hub.mode");
+		const token = c.req.query("hub.verify_token");
+		const challenge = c.req.query("hub.challenge");
+		if (mode === "subscribe" && token === config.verifyToken) {
+			log.info("webhook.verification_successful");
+			return c.text(challenge || "", 200);
+		}
+		log.warn("webhook.verification_failed");
+		return c.text("Forbidden", 403);
+	});
+	webhook.post("/", async (c) => {
+		try {
+			if (!config.appSecret) {
+				log.error("webhook.missing_app_secret");
+				return c.text("Server Misconfigured", 500);
+			}
+			const rawBody = await c.req.raw.arrayBuffer();
+			if (!await verifyMetaWebhookSignature({
+				rawBody,
+				signatureHeader: c.req.header("x-hub-signature-256"),
+				appSecret: config.appSecret
+			})) {
+				log.warn("webhook.invalid_signature");
+				return c.text("Unauthorized", 401);
+			}
+			let payload;
+			try {
+				payload = JSON.parse(textDecoder.decode(rawBody));
+			} catch {
+				log.warn("webhook.invalid_payload");
+				return c.text("Bad Request", 400);
+			}
+			if (c.executionCtx) c.executionCtx.waitUntil(processPayload(payload, c.env, config, log));
+			else await processPayload(payload, c.env, config, log);
+			return c.text("OK", 200);
+		} catch (error) {
+			log.error("webhook.request_error", (0, better_zap.serializeError)(error));
+			return c.text("Internal Server Error", 500);
+		}
+	});
+	return webhook;
+}
+/** Top-level dispatcher — iterates entries in the webhook payload. */
+async function processPayload(payload, env, config, log) {
+	try {
+		if (payload.object !== "whatsapp_business_account") {
+			log.debug("webhook.ignored_payload", { object: payload.object });
+			return;
+		}
+		for (const entry of payload.entry) await processEntry(entry, env, config, log);
+	} catch (error) {
+		log.error("webhook.async_process_error", (0, better_zap.serializeError)(error));
+	}
+}
+/** Iterates changes within a single entry. */
+async function processEntry(entry, env, config, log) {
+	for (const change of entry.changes) await processChange(change, env, config, log);
+}
+/** Routes messages, statuses, and errors to the appropriate handler. */
+async function processChange(change, env, config, log) {
+	const value = change.value;
+	if (value.messages && value.messages.length > 0) for (const message of value.messages) await processIncomingMessage(message, resolveContact(value.contacts, message), config, log);
+	if (value.statuses && value.statuses.length > 0) for (const status of value.statuses) await processStatusUpdate(status, config, log);
+	if (value.errors && value.errors.length > 0) {
+		const errorHandler = config.onError ?? ((err) => {
+			log.error("webhook.meta_error", { error: err });
+		});
+		for (const error of value.errors) try {
+			errorHandler(error);
+		} catch (hookError) {
+			log.error("webhook.on_error_hook_failed", {
+				metaError: error,
+				hookError: (0, better_zap.serializeError)(hookError)
+			});
+		}
+	}
+}
+/**
+* Processes a single incoming message:
+* 1. Deduplicates by waMessageId
+* 2. Extracts human-readable content
+* 3. Logs the message for audit trail
+* 4. Calls {@link WebhookConfig.onMessage}
+*/
+async function processIncomingMessage(message, contact, config, log) {
+	const phone = message.from;
+	log.info("webhook.message_received", {
+		waMessageId: message.id,
+		phone,
+		messageType: message.type
+	});
+	if (await config.logger.isDuplicate(message.id)) {
+		log.info("webhook.duplicate_ignored", {
+			waMessageId: message.id,
+			phone
+		});
+		return;
+	}
+	const content = getMessageContent(message);
+	const { id, type, text, from, timestamp, ...rawMetadata } = message;
+	await config.logger.logIncoming({
+		phone,
+		waMessageId: message.id,
+		content,
+		senderName: contact?.profile?.name,
+		metadata: Object.keys(rawMetadata).length > 0 ? rawMetadata : void 0
+	});
+	const ctx = {
+		message,
+		contact,
+		content,
+		phone
+	};
+	try {
+		await config.onMessage(ctx);
+	} catch (error) {
+		log.error("webhook.on_message_hook_failed", {
+			waMessageId: message.id,
+			phone,
+			...(0, better_zap.serializeError)(error)
+		});
+	}
+}
+/**
+* Processes a single delivery status update:
+* 1. Parses Unix timestamp to ISO-8601
+* 2. Extracts first error (if any)
+* 3. Atomically updates status only if it advances the lifecycle
+* 4. Calls {@link WebhookConfig.onStatusUpdate} only if the update was applied
+*/
+async function processStatusUpdate(status, config, log) {
+	const firstError = status.errors?.[0];
+	const timestamp = (/* @__PURE__ */ new Date(parseInt(status.timestamp) * 1e3)).toISOString();
+	const errorMessage = firstError?.message;
+	const errorCode = firstError?.code;
+	if (!await config.logger.updateStatus(status.id, status.status, timestamp, errorMessage)) return;
+	log.info("webhook.status_updated", {
+		waMessageId: status.id,
+		status: status.status
+	});
+	const ctx = {
+		status,
+		timestamp,
+		errorMessage,
+		errorCode
+	};
+	try {
+		await config.onStatusUpdate(ctx);
+	} catch (error) {
+		log.error("webhook.on_status_update_hook_failed", {
+			waMessageId: status.id,
+			...(0, better_zap.serializeError)(error)
+		});
+	}
+}
+/** Matches a contact to a message by `wa_id`, falling back to the first contact. */
+function resolveContact(contacts, message) {
+	if (!contacts || contacts.length === 0) return;
+	return contacts.find((c) => c.wa_id === message.from) ?? contacts[0];
+}
+//#endregion
+//#region src/internal/cloudflare/constants.ts
+const GLOBAL_WORKSPACE_DO_ID = "global-workspace";
+//#endregion
+//#region src/internal/cloudflare/conversation-sync.ts
+function createConversationSyncNotifier(conversationSync) {
+	if (!conversationSync) return;
+	return { async notify(event) {
+		const id = conversationSync.idFromName(GLOBAL_WORKSPACE_DO_ID);
+		await conversationSync.get(id).fetch(new Request("http://do/sync", {
+			method: "POST",
+			body: JSON.stringify(event)
+		}));
+	} };
+}
+//#endregion
+//#region src/better-zap.ts
+function serializeRuntimeTemplate(templates, templateName, options) {
+	return (0, better_zap.serializeTemplateFromRegistry)(templates, templateName, {
+		language: options.language,
+		params: options.params ?? {}
+	});
+}
+function betterZap(options) {
+	const { database, config, webhook: webhookHooks, conversationSync, basePath = "/api/whatsapp" } = options;
+	const templates = options.templates ?? better_zap.EMPTY_TEMPLATE_REGISTRY;
+	const log = (0, better_zap.createLogger)(options.logger);
+	const logger = new better_zap.MessageLoggerService(database.whatsappLog, log, createConversationSyncNotifier(conversationSync));
+	const whatsapp = new better_zap.WhatsAppService(config, logger, log);
+	const coreContext = {
+		db: database,
+		api: whatsapp,
+		logger
+	};
+	const coreServices = {
+		whatsapp,
+		logger
+	};
+	const plugins = options.plugins ?? [];
+	const pluginRuntime = initializePlugins({
+		plugins,
+		database,
+		config,
+		coreContext,
+		coreServices,
+		log
+	});
+	const webhookRouter = createWebhookHandler({
+		verifyToken: config.webhookToken,
+		appSecret: config.appSecret,
+		logger,
+		log,
+		onMessage: async (ctx) => {
+			const hookContext = {
+				...ctx,
+				...pluginRuntime.context
+			};
+			await runPluginMessageHooks({
+				plugins,
+				ctx: hookContext,
+				log
+			});
+			await webhookHooks.onMessage(hookContext);
+		},
+		onStatusUpdate: async (ctx) => {
+			const hookContext = {
+				...ctx,
+				...pluginRuntime.context
+			};
+			await runPluginStatusHooks({
+				plugins,
+				ctx: hookContext,
+				log
+			});
+			await webhookHooks.onStatusUpdate(hookContext);
+		}
+	});
+	const app = new hono.Hono().basePath(basePath);
+	app.use("*", async (c, next) => {
+		c.set("whatsapp", whatsapp);
+		c.set("store", database.whatsappLog);
+		c.set("logger", log);
+		await next();
+	});
+	app.route("/webhook", webhookRouter);
+	app.post("/send/text", handleSendText);
+	app.post("/send/template", createSendTemplateHandler(templates));
+	app.post("/send/interactive", handleSendInteractive);
+	app.post("/send/location", handleSendLocation);
+	app.get("/conversations", handleListConversations);
+	app.get("/conversations/:phone", handleGetConversation);
+	app.get("/conversations/:phone/messages", handleGetMessages);
+	const api = {
+		send: {
+			text: (to, body, opts) => whatsapp.sendText(to, body, opts),
+			template: ((to, templateName, opts = {}) => {
+				if (!(0, better_zap.hasConfiguredTemplates)(templates)) return whatsapp.sendTemplate(to, String(templateName), opts?.language, opts?.components, opts?.logging);
+				const serializedTemplate = serializeRuntimeTemplate(templates, templateName, opts);
+				return whatsapp.sendTemplate(to, String(templateName), serializedTemplate.language, serializedTemplate.components, opts.logging);
+			}),
+			templateRaw: (to, templateName, opts) => whatsapp.sendTemplate(to, templateName, opts?.language, opts?.components, opts?.logging),
+			interactiveButtons: (to, body, buttons, opts) => whatsapp.sendInteractiveButtons(to, body, buttons, opts),
+			interactiveList: (to, body, buttonLabel, sections, opts) => whatsapp.sendInteractiveList(to, body, buttonLabel, sections, opts),
+			interactiveMediaCarousel: (data, opts) => whatsapp.sendInteractiveMediaCarousel(data, opts),
+			location: (to, location, opts) => whatsapp.sendLocation(to, location.latitude, location.longitude, location.name, location.address, opts),
+			markAsRead: (messageId) => whatsapp.markAsRead(messageId),
+			reaction: (to, messageId, emoji) => whatsapp.sendReaction(to, messageId, emoji)
+		},
+		conversations: {
+			list: () => database.whatsappLog.getConversations(),
+			get: (phone) => database.whatsappLog.getConversationByPhone((0, better_zap.formatPhone)(phone)),
+			messages: async (phone, opts) => {
+				const conversation = await database.whatsappLog.getConversationByPhone((0, better_zap.formatPhone)(phone));
+				if (!conversation) return [];
+				return await database.whatsappLog.getMessagesByConversationPaginated(conversation.id, opts?.cursor, opts?.limit);
+			}
+		}
+	};
+	const handler = async (request, env, executionCtx) => app.fetch(request, env, executionCtx);
+	return {
+		handler,
+		api,
+		services: pluginRuntime.services
+	};
+}
+//#endregion
+exports.betterZap = betterZap;
+exports.createWebhookHandler = createWebhookHandler;
+exports.getMessageContent = getMessageContent;
+exports.verifyMetaWebhookSignature = verifyMetaWebhookSignature;

package/dist/index.d.cts

@@ -0,0 +1,88 @@
+import { BetterZapApi, BetterZapApi as BetterZapApi$1, BetterZapContext, BetterZapContext as BetterZapContext$1, BetterZapCoreConfig, BetterZapCoreConfig as BetterZapCoreConfig$1, BetterZapDatabase, BetterZapDatabase as BetterZapDatabase$1, BetterZapPlugin, BetterZapPlugin as BetterZapPlugin$1, BetterZapPluginInitContext, BetterZapPluginInitResult, BetterZapServices, BetterZapServices as BetterZapServices$1, IncomingMessage, InferBetterZapPluginContext, InferBetterZapPluginContext as InferBetterZapPluginContext$1, InferBetterZapPluginServices, InferBetterZapPluginServices as InferBetterZapPluginServices$1, Logger, LoggerConfig, MessageContext, MessageContext as MessageContext$1, MessageLoggerService, StatusContext, StatusContext as StatusContext$1, TemplateRegistry, WebhookError, WhatsAppLogStore, WhatsAppService } from "better-zap";
+import { Hono } from "hono";
+
+//#region src/better-zap.types.d.ts
+interface BetterZapConfig<TDatabase extends BetterZapDatabase$1 = BetterZapDatabase$1, TPlugins extends readonly BetterZapPlugin$1<TDatabase, any, any>[] = readonly [], TTemplates extends TemplateRegistry = {}> {
+  database: TDatabase;
+  config: BetterZapCoreConfig$1;
+  plugins?: TPlugins;
+  templates?: TTemplates;
+  conversationSync?: DurableObjectNamespace<any>;
+  webhook: {
+    onMessage: (ctx: MessageContext$1 & BetterZapContext$1<TDatabase, InferBetterZapPluginContext$1<TPlugins>>) => Promise<void>;
+    onStatusUpdate: (ctx: StatusContext$1 & BetterZapContext$1<TDatabase, InferBetterZapPluginContext$1<TPlugins>>) => Promise<void>;
+  };
+  basePath?: string;
+  logger?: LoggerConfig;
+}
+interface BetterZap<TPluginServices extends Record<string, unknown> = {}, TTemplates extends TemplateRegistry = {}> {
+  handler: (request: Request, env?: any, executionCtx?: any) => Promise<Response>;
+  api: BetterZapApi$1<TTemplates>;
+  services: BetterZapServices$1<TPluginServices>;
+}
+//#endregion
+//#region src/better-zap.d.ts
+declare function betterZap<TDatabase extends BetterZapDatabase$1 = BetterZapDatabase$1, TPlugins extends readonly BetterZapPlugin$1<TDatabase, any, any>[] = readonly BetterZapPlugin$1<TDatabase, any, any>[], TTemplates extends TemplateRegistry = {}>(options: BetterZapConfig<TDatabase, TPlugins, TTemplates>): BetterZap<InferBetterZapPluginServices$1<TPlugins>, TTemplates>;
+//#endregion
+//#region src/webhook/create-webhook-handler.d.ts
+/**
+ * Configuration for {@link createWebhookHandler}.
+ *
+ * @typeParam Env - Hono bindings type (e.g. Cloudflare Worker env).
+ */
+type WebhookConfig = {
+  /** Token for the Meta verification challenge (`GET /webhook`). */verifyToken: string; /** App secret used for HMAC-SHA256 signature verification. */
+  appSecret: string; /** logger for automatic message storage. */
+  logger: MessageLoggerService; /** Structured logger for operational logging. */
+  log: Logger; /** Called once per incoming message, after SDK pre-processing. */
+  onMessage: (ctx: MessageContext$1) => Promise<void>; /** Called once per delivery status update (sent → delivered → read → failed). */
+  onStatusUpdate: (ctx: StatusContext$1) => Promise<void>;
+  /**
+   * Called for Meta platform-level errors.
+   * @default Uses the configured {@link WebhookConfig.log} logger's {@code error} method.
+   */
+  onError?: (error: WebhookError) => void;
+};
+/**
+ * Creates a Hono router that handles the full WhatsApp webhook lifecycle.
+ *
+ * **SDK guarantees (non-hookable):**
+ * - Signature is always verified before any processing
+ * - Meta always receives a fast 200 OK (processing runs via `waitUntil`)
+ * - Hook errors never crash the webhook (wrapped in try/catch)
+ * - Contact is resolved and content is extracted before `onMessage`
+ * - Status timestamp is parsed to ISO before `onStatusUpdate`
+ *
+ * @typeParam Env - Hono bindings type (e.g. Cloudflare Worker env).
+ */
+declare function createWebhookHandler(config: WebhookConfig): Hono<{
+  Bindings: Record<string, any>;
+}>;
+//#endregion
+//#region src/webhook/signature-verification.d.ts
+declare function verifyMetaWebhookSignature({
+  rawBody,
+  signatureHeader,
+  appSecret
+}: {
+  rawBody: ArrayBuffer;
+  signatureHeader: string | undefined;
+  appSecret: string;
+}): Promise<boolean>;
+//#endregion
+//#region src/webhook/message-content.d.ts
+/**
+ * Extract human-readable content from incoming messages for audit logs.
+ */
+declare function getMessageContent(message: IncomingMessage): string;
+//#endregion
+//#region src/handler/types.d.ts
+type BetterZapEnv = {
+  Variables: {
+    whatsapp: WhatsAppService;
+    store: WhatsAppLogStore;
+    logger: Logger;
+  };
+};
+//#endregion
+export { type BetterZap, type BetterZapApi, type BetterZapConfig, type BetterZapContext, type BetterZapCoreConfig, type BetterZapDatabase, type BetterZapEnv, type BetterZapPlugin, type BetterZapPluginInitContext, type BetterZapPluginInitResult, type BetterZapServices, type InferBetterZapPluginContext, type InferBetterZapPluginServices, type MessageContext, type StatusContext, type WebhookConfig, betterZap, createWebhookHandler, getMessageContent, verifyMetaWebhookSignature };

package/dist/index.d.mts

@@ -0,0 +1,88 @@
+import { Hono } from "hono";
+import { BetterZapApi, BetterZapApi as BetterZapApi$1, BetterZapContext, BetterZapContext as BetterZapContext$1, BetterZapCoreConfig, BetterZapCoreConfig as BetterZapCoreConfig$1, BetterZapDatabase, BetterZapDatabase as BetterZapDatabase$1, BetterZapPlugin, BetterZapPlugin as BetterZapPlugin$1, BetterZapPluginInitContext, BetterZapPluginInitResult, BetterZapServices, BetterZapServices as BetterZapServices$1, IncomingMessage, InferBetterZapPluginContext, InferBetterZapPluginContext as InferBetterZapPluginContext$1, InferBetterZapPluginServices, InferBetterZapPluginServices as InferBetterZapPluginServices$1, Logger, LoggerConfig, MessageContext, MessageContext as MessageContext$1, MessageLoggerService, StatusContext, StatusContext as StatusContext$1, TemplateRegistry, WebhookError, WhatsAppLogStore, WhatsAppService } from "better-zap";
+
+//#region src/better-zap.types.d.ts
+interface BetterZapConfig<TDatabase extends BetterZapDatabase$1 = BetterZapDatabase$1, TPlugins extends readonly BetterZapPlugin$1<TDatabase, any, any>[] = readonly [], TTemplates extends TemplateRegistry = {}> {
+  database: TDatabase;
+  config: BetterZapCoreConfig$1;
+  plugins?: TPlugins;
+  templates?: TTemplates;
+  conversationSync?: DurableObjectNamespace<any>;
+  webhook: {
+    onMessage: (ctx: MessageContext$1 & BetterZapContext$1<TDatabase, InferBetterZapPluginContext$1<TPlugins>>) => Promise<void>;
+    onStatusUpdate: (ctx: StatusContext$1 & BetterZapContext$1<TDatabase, InferBetterZapPluginContext$1<TPlugins>>) => Promise<void>;
+  };
+  basePath?: string;
+  logger?: LoggerConfig;
+}
+interface BetterZap<TPluginServices extends Record<string, unknown> = {}, TTemplates extends TemplateRegistry = {}> {
+  handler: (request: Request, env?: any, executionCtx?: any) => Promise<Response>;
+  api: BetterZapApi$1<TTemplates>;
+  services: BetterZapServices$1<TPluginServices>;
+}
+//#endregion
+//#region src/better-zap.d.ts
+declare function betterZap<TDatabase extends BetterZapDatabase$1 = BetterZapDatabase$1, TPlugins extends readonly BetterZapPlugin$1<TDatabase, any, any>[] = readonly BetterZapPlugin$1<TDatabase, any, any>[], TTemplates extends TemplateRegistry = {}>(options: BetterZapConfig<TDatabase, TPlugins, TTemplates>): BetterZap<InferBetterZapPluginServices$1<TPlugins>, TTemplates>;
+//#endregion
+//#region src/webhook/create-webhook-handler.d.ts
+/**
+ * Configuration for {@link createWebhookHandler}.
+ *
+ * @typeParam Env - Hono bindings type (e.g. Cloudflare Worker env).
+ */
+type WebhookConfig = {
+  /** Token for the Meta verification challenge (`GET /webhook`). */verifyToken: string; /** App secret used for HMAC-SHA256 signature verification. */
+  appSecret: string; /** logger for automatic message storage. */
+  logger: MessageLoggerService; /** Structured logger for operational logging. */
+  log: Logger; /** Called once per incoming message, after SDK pre-processing. */
+  onMessage: (ctx: MessageContext$1) => Promise<void>; /** Called once per delivery status update (sent → delivered → read → failed). */
+  onStatusUpdate: (ctx: StatusContext$1) => Promise<void>;
+  /**
+   * Called for Meta platform-level errors.
+   * @default Uses the configured {@link WebhookConfig.log} logger's {@code error} method.
+   */
+  onError?: (error: WebhookError) => void;
+};
+/**
+ * Creates a Hono router that handles the full WhatsApp webhook lifecycle.
+ *
+ * **SDK guarantees (non-hookable):**
+ * - Signature is always verified before any processing
+ * - Meta always receives a fast 200 OK (processing runs via `waitUntil`)
+ * - Hook errors never crash the webhook (wrapped in try/catch)
+ * - Contact is resolved and content is extracted before `onMessage`
+ * - Status timestamp is parsed to ISO before `onStatusUpdate`
+ *
+ * @typeParam Env - Hono bindings type (e.g. Cloudflare Worker env).
+ */
+declare function createWebhookHandler(config: WebhookConfig): Hono<{
+  Bindings: Record<string, any>;
+}>;
+//#endregion
+//#region src/webhook/signature-verification.d.ts
+declare function verifyMetaWebhookSignature({
+  rawBody,
+  signatureHeader,
+  appSecret
+}: {
+  rawBody: ArrayBuffer;
+  signatureHeader: string | undefined;
+  appSecret: string;
+}): Promise<boolean>;
+//#endregion
+//#region src/webhook/message-content.d.ts
+/**
+ * Extract human-readable content from incoming messages for audit logs.
+ */
+declare function getMessageContent(message: IncomingMessage): string;
+//#endregion
+//#region src/handler/types.d.ts
+type BetterZapEnv = {
+  Variables: {
+    whatsapp: WhatsAppService;
+    store: WhatsAppLogStore;
+    logger: Logger;
+  };
+};
+//#endregion
+export { type BetterZap, type BetterZapApi, type BetterZapConfig, type BetterZapContext, type BetterZapCoreConfig, type BetterZapDatabase, type BetterZapEnv, type BetterZapPlugin, type BetterZapPluginInitContext, type BetterZapPluginInitResult, type BetterZapServices, type InferBetterZapPluginContext, type InferBetterZapPluginServices, type MessageContext, type StatusContext, type WebhookConfig, betterZap, createWebhookHandler, getMessageContent, verifyMetaWebhookSignature };

package/dist/index.mjs

@@ -0,0 +1,568 @@
+import { Hono } from "hono";
+import { EMPTY_TEMPLATE_REGISTRY, MessageLoggerService, WhatsAppService, createLogger, formatPhone, hasConfiguredTemplates, serializeError, serializeTemplateFromRegistry } from "better-zap";
+//#region src/plugins/runtime.ts
+function initializePlugins(options) {
+	let pluginContext = {};
+	let pluginServices = {};
+	for (const plugin of options.plugins) {
+		const result = plugin.init?.({
+			database: options.database,
+			config: options.config,
+			context: {
+				...options.coreContext,
+				...pluginContext
+			},
+			services: {
+				...options.coreServices,
+				...pluginServices
+			},
+			log: options.log
+		});
+		if (!result) continue;
+		if (result.context) pluginContext = {
+			...pluginContext,
+			...result.context
+		};
+		if (result.services) pluginServices = {
+			...pluginServices,
+			...result.services
+		};
+	}
+	return {
+		context: {
+			...options.coreContext,
+			...pluginContext
+		},
+		services: {
+			...options.coreServices,
+			...pluginServices
+		}
+	};
+}
+async function runPluginMessageHooks(options) {
+	for (const plugin of options.plugins) {
+		if (!plugin.hooks?.onMessage) continue;
+		try {
+			await plugin.hooks.onMessage(options.ctx);
+		} catch (error) {
+			options.log.error("plugin.on_message_failed", {
+				pluginId: plugin.id,
+				waMessageId: options.ctx.message.id,
+				phone: options.ctx.phone,
+				...serializeError(error)
+			});
+		}
+	}
+}
+async function runPluginStatusHooks(options) {
+	for (const plugin of options.plugins) {
+		if (!plugin.hooks?.onStatusUpdate) continue;
+		try {
+			await plugin.hooks.onStatusUpdate(options.ctx);
+		} catch (error) {
+			options.log.error("plugin.on_status_update_failed", {
+				pluginId: plugin.id,
+				waMessageId: options.ctx.status.id,
+				status: options.ctx.status.status,
+				...serializeError(error)
+			});
+		}
+	}
+}
+//#endregion
+//#region src/handler/conversations.ts
+async function handleListConversations(c) {
+	try {
+		const conversations = await c.get("store").getConversations();
+		return c.json(conversations);
+	} catch (error) {
+		c.get("logger").error("conversations.list_error", serializeError(error));
+		return c.json({ error: "Internal error fetching conversations" }, 500);
+	}
+}
+async function handleGetConversation(c) {
+	try {
+		const phone = c.req.param("phone");
+		if (!phone) return c.json({ error: "phone is required" }, 400);
+		const store = c.get("store");
+		const normalized = formatPhone(decodeURIComponent(phone));
+		const conversation = await store.getConversationByPhone(normalized);
+		if (!conversation) return c.json({ error: "Conversation not found" }, 404);
+		return c.json(conversation);
+	} catch (error) {
+		c.get("logger").error("conversations.get_error", serializeError(error));
+		return c.json({ error: "Internal error fetching conversation" }, 500);
+	}
+}
+async function handleGetMessages(c) {
+	try {
+		const phone = c.req.param("phone");
+		if (!phone) return c.json({ error: "phone is required" }, 400);
+		const store = c.get("store");
+		const normalized = formatPhone(decodeURIComponent(phone));
+		const conversation = await store.getConversationByPhone(normalized);
+		if (!conversation) return c.json({ error: "Conversation not found" }, 404);
+		const cursor = c.req.query("cursor") || void 0;
+		const limitParam = c.req.query("limit");
+		const limit = limitParam ? parseInt(limitParam, 10) : void 0;
+		const messages = await store.getMessagesByConversationPaginated(conversation.id, cursor, limit);
+		return c.json(messages);
+	} catch (error) {
+		c.get("logger").error("conversations.messages_error", serializeError(error));
+		return c.json({ error: "Internal error fetching messages" }, 500);
+	}
+}
+//#endregion
+//#region src/handler/send.ts
+async function handleSendText(c) {
+	const { to, body, messageType, userId, metadata } = await c.req.json();
+	if (!to || !body) return c.json({ error: "to and body are required" }, 400);
+	const whatsapp = c.get("whatsapp");
+	const logging = messageType ? {
+		messageType,
+		userId,
+		metadata
+	} : void 0;
+	const result = await whatsapp.sendText(to, body, logging);
+	return c.json(result, result.success ? 200 : 500);
+}
+function createSendTemplateHandler(templates) {
+	return async function handleSendTemplate(c) {
+		const body = await c.req.json();
+		if (!body.to || !body.template) return c.json({ error: "to and template are required" }, 400);
+		const whatsapp = c.get("whatsapp");
+		const logging = body.logging ?? (body.messageType ? {
+			messageType: body.messageType,
+			content: body.content || `[template: ${body.template}]`,
+			userId: body.userId,
+			metadata: body.metadata
+		} : void 0);
+		let language = body.language;
+		let components = body.components;
+		if ("params" in body && body.params !== void 0) {
+			if (!hasConfiguredTemplates(templates)) return c.json({ error: "Typed template params require a configured template registry" }, 400);
+			try {
+				const serializedTemplate = serializeTemplateFromRegistry(templates, body.template, {
+					language: body.language,
+					params: body.params
+				});
+				language = serializedTemplate.language;
+				components = serializedTemplate.components;
+			} catch (error) {
+				const message = error instanceof Error ? error.message : "Failed to serialize template from registry";
+				return c.json({ error: message }, 400);
+			}
+		}
+		const result = await whatsapp.sendTemplate(body.to, body.template, language, components, logging);
+		return c.json(result, result.success ? 200 : 500);
+	};
+}
+async function handleSendInteractive(c) {
+	const { to, type, body, buttons, buttonLabel, sections, cards, messageType, userId, metadata } = await c.req.json();
+	if (!to || !body) return c.json({ error: "to and body are required" }, 400);
+	const whatsapp = c.get("whatsapp");
+	const logging = messageType ? {
+		messageType,
+		userId,
+		metadata
+	} : void 0;
+	if (type === "list") {
+		if (!buttonLabel || !sections) return c.json({ error: "buttonLabel and sections are required for list type" }, 400);
+		const result = await whatsapp.sendInteractiveList(to, body, buttonLabel, sections, logging);
+		return c.json(result, result.success ? 200 : 500);
+	}
+	if (type === "carousel") {
+		if (!cards) return c.json({ error: "cards are required for carousel type" }, 400);
+		if (cards.length < 2 || cards.length > 10) return c.json({ error: "carousel requires between 2 and 10 cards" }, 400);
+		const result = await whatsapp.sendInteractiveMediaCarousel({
+			to,
+			body,
+			cards
+		}, logging);
+		return c.json(result, result.success ? 200 : 500);
+	}
+	if (!buttons) return c.json({ error: "buttons are required for button type" }, 400);
+	const result = await whatsapp.sendInteractiveButtons(to, body, buttons, logging);
+	return c.json(result, result.success ? 200 : 500);
+}
+async function handleSendLocation(c) {
+	const { to, latitude, longitude, name, address, messageType, userId, metadata } = await c.req.json();
+	if (!to || latitude == null || longitude == null || !name || !address) return c.json({ error: "to, latitude, longitude, name, and address are required" }, 400);
+	const whatsapp = c.get("whatsapp");
+	const logging = messageType ? {
+		messageType,
+		userId,
+		metadata
+	} : void 0;
+	const result = await whatsapp.sendLocation(to, latitude, longitude, name, address, logging);
+	return c.json(result, result.success ? 200 : 500);
+}
+//#endregion
+//#region src/webhook/signature-verification.ts
+const textEncoder = new TextEncoder();
+let cachedMetaAppSecret = null;
+let cachedMetaHmacKey = null;
+async function verifyMetaWebhookSignature({ rawBody, signatureHeader, appSecret }) {
+	if (!signatureHeader) return false;
+	const [algorithm, signatureHexRaw] = signatureHeader.split("=", 2);
+	if (algorithm?.toLowerCase() !== "sha256" || !signatureHexRaw) return false;
+	const signatureBytes = hexToBytes(signatureHexRaw.trim());
+	if (!signatureBytes) return false;
+	const key = await getMetaHmacKey(appSecret);
+	const expectedSignatureBuffer = await crypto.subtle.sign("HMAC", key, rawBody);
+	return constantTimeEqual(new Uint8Array(expectedSignatureBuffer), signatureBytes);
+}
+function getMetaHmacKey(appSecret) {
+	if (cachedMetaAppSecret === appSecret && cachedMetaHmacKey) return cachedMetaHmacKey;
+	cachedMetaAppSecret = appSecret;
+	cachedMetaHmacKey = crypto.subtle.importKey("raw", textEncoder.encode(appSecret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return cachedMetaHmacKey;
+}
+function hexToBytes(hex) {
+	if (hex.length % 2 !== 0) return null;
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < bytes.length; i += 1) {
+		const value = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+		if (Number.isNaN(value)) return null;
+		bytes[i] = value;
+	}
+	return bytes;
+}
+function constantTimeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i += 1) diff |= a[i] ^ b[i];
+	return diff === 0;
+}
+//#endregion
+//#region src/webhook/message-content.ts
+/**
+* Extract human-readable content from incoming messages for audit logs.
+*/
+function getMessageContent(message) {
+	switch (message.type) {
+		case "text": return message.text?.body || "[texto vazio]";
+		case "image": return `[imagem${message.image?.caption ? `: ${message.image.caption}` : ""}]`;
+		case "audio": return "[áudio]";
+		case "video": return `[vídeo${message.video?.caption ? `: ${message.video.caption}` : ""}]`;
+		case "document": return `[documento: ${message.document?.filename || "arquivo"}]`;
+		case "location": return `[localização: ${message.location?.name || `${message.location?.latitude},${message.location?.longitude}`}]`;
+		case "button": return `[botão: ${message.button?.text}]`;
+		case "interactive":
+			if (message.interactive?.button_reply) return `[resposta botão: ${message.interactive.button_reply.title}]`;
+			if (message.interactive?.list_reply) return `[resposta lista: ${message.interactive.list_reply.title}]`;
+			return "[interativo]";
+		case "sticker": return "[figurinha]";
+		case "reaction": return "[reação]";
+		default: return `[${message.type}]`;
+	}
+}
+//#endregion
+//#region src/webhook/create-webhook-handler.ts
+const textDecoder = new TextDecoder();
+/**
+* Creates a Hono router that handles the full WhatsApp webhook lifecycle.
+*
+* **SDK guarantees (non-hookable):**
+* - Signature is always verified before any processing
+* - Meta always receives a fast 200 OK (processing runs via `waitUntil`)
+* - Hook errors never crash the webhook (wrapped in try/catch)
+* - Contact is resolved and content is extracted before `onMessage`
+* - Status timestamp is parsed to ISO before `onStatusUpdate`
+*
+* @typeParam Env - Hono bindings type (e.g. Cloudflare Worker env).
+*/
+function createWebhookHandler(config) {
+	const log = config.log;
+	const webhook = new Hono();
+	webhook.get("/", (c) => {
+		const mode = c.req.query("hub.mode");
+		const token = c.req.query("hub.verify_token");
+		const challenge = c.req.query("hub.challenge");
+		if (mode === "subscribe" && token === config.verifyToken) {
+			log.info("webhook.verification_successful");
+			return c.text(challenge || "", 200);
+		}
+		log.warn("webhook.verification_failed");
+		return c.text("Forbidden", 403);
+	});
+	webhook.post("/", async (c) => {
+		try {
+			if (!config.appSecret) {
+				log.error("webhook.missing_app_secret");
+				return c.text("Server Misconfigured", 500);
+			}
+			const rawBody = await c.req.raw.arrayBuffer();
+			if (!await verifyMetaWebhookSignature({
+				rawBody,
+				signatureHeader: c.req.header("x-hub-signature-256"),
+				appSecret: config.appSecret
+			})) {
+				log.warn("webhook.invalid_signature");
+				return c.text("Unauthorized", 401);
+			}
+			let payload;
+			try {
+				payload = JSON.parse(textDecoder.decode(rawBody));
+			} catch {
+				log.warn("webhook.invalid_payload");
+				return c.text("Bad Request", 400);
+			}
+			if (c.executionCtx) c.executionCtx.waitUntil(processPayload(payload, c.env, config, log));
+			else await processPayload(payload, c.env, config, log);
+			return c.text("OK", 200);
+		} catch (error) {
+			log.error("webhook.request_error", serializeError(error));
+			return c.text("Internal Server Error", 500);
+		}
+	});
+	return webhook;
+}
+/** Top-level dispatcher — iterates entries in the webhook payload. */
+async function processPayload(payload, env, config, log) {
+	try {
+		if (payload.object !== "whatsapp_business_account") {
+			log.debug("webhook.ignored_payload", { object: payload.object });
+			return;
+		}
+		for (const entry of payload.entry) await processEntry(entry, env, config, log);
+	} catch (error) {
+		log.error("webhook.async_process_error", serializeError(error));
+	}
+}
+/** Iterates changes within a single entry. */
+async function processEntry(entry, env, config, log) {
+	for (const change of entry.changes) await processChange(change, env, config, log);
+}
+/** Routes messages, statuses, and errors to the appropriate handler. */
+async function processChange(change, env, config, log) {
+	const value = change.value;
+	if (value.messages && value.messages.length > 0) for (const message of value.messages) await processIncomingMessage(message, resolveContact(value.contacts, message), config, log);
+	if (value.statuses && value.statuses.length > 0) for (const status of value.statuses) await processStatusUpdate(status, config, log);
+	if (value.errors && value.errors.length > 0) {
+		const errorHandler = config.onError ?? ((err) => {
+			log.error("webhook.meta_error", { error: err });
+		});
+		for (const error of value.errors) try {
+			errorHandler(error);
+		} catch (hookError) {
+			log.error("webhook.on_error_hook_failed", {
+				metaError: error,
+				hookError: serializeError(hookError)
+			});
+		}
+	}
+}
+/**
+* Processes a single incoming message:
+* 1. Deduplicates by waMessageId
+* 2. Extracts human-readable content
+* 3. Logs the message for audit trail
+* 4. Calls {@link WebhookConfig.onMessage}
+*/
+async function processIncomingMessage(message, contact, config, log) {
+	const phone = message.from;
+	log.info("webhook.message_received", {
+		waMessageId: message.id,
+		phone,
+		messageType: message.type
+	});
+	if (await config.logger.isDuplicate(message.id)) {
+		log.info("webhook.duplicate_ignored", {
+			waMessageId: message.id,
+			phone
+		});
+		return;
+	}
+	const content = getMessageContent(message);
+	const { id, type, text, from, timestamp, ...rawMetadata } = message;
+	await config.logger.logIncoming({
+		phone,
+		waMessageId: message.id,
+		content,
+		senderName: contact?.profile?.name,
+		metadata: Object.keys(rawMetadata).length > 0 ? rawMetadata : void 0
+	});
+	const ctx = {
+		message,
+		contact,
+		content,
+		phone
+	};
+	try {
+		await config.onMessage(ctx);
+	} catch (error) {
+		log.error("webhook.on_message_hook_failed", {
+			waMessageId: message.id,
+			phone,
+			...serializeError(error)
+		});
+	}
+}
+/**
+* Processes a single delivery status update:
+* 1. Parses Unix timestamp to ISO-8601
+* 2. Extracts first error (if any)
+* 3. Atomically updates status only if it advances the lifecycle
+* 4. Calls {@link WebhookConfig.onStatusUpdate} only if the update was applied
+*/
+async function processStatusUpdate(status, config, log) {
+	const firstError = status.errors?.[0];
+	const timestamp = (/* @__PURE__ */ new Date(parseInt(status.timestamp) * 1e3)).toISOString();
+	const errorMessage = firstError?.message;
+	const errorCode = firstError?.code;
+	if (!await config.logger.updateStatus(status.id, status.status, timestamp, errorMessage)) return;
+	log.info("webhook.status_updated", {
+		waMessageId: status.id,
+		status: status.status
+	});
+	const ctx = {
+		status,
+		timestamp,
+		errorMessage,
+		errorCode
+	};
+	try {
+		await config.onStatusUpdate(ctx);
+	} catch (error) {
+		log.error("webhook.on_status_update_hook_failed", {
+			waMessageId: status.id,
+			...serializeError(error)
+		});
+	}
+}
+/** Matches a contact to a message by `wa_id`, falling back to the first contact. */
+function resolveContact(contacts, message) {
+	if (!contacts || contacts.length === 0) return;
+	return contacts.find((c) => c.wa_id === message.from) ?? contacts[0];
+}
+//#endregion
+//#region src/internal/cloudflare/constants.ts
+const GLOBAL_WORKSPACE_DO_ID = "global-workspace";
+//#endregion
+//#region src/internal/cloudflare/conversation-sync.ts
+function createConversationSyncNotifier(conversationSync) {
+	if (!conversationSync) return;
+	return { async notify(event) {
+		const id = conversationSync.idFromName(GLOBAL_WORKSPACE_DO_ID);
+		await conversationSync.get(id).fetch(new Request("http://do/sync", {
+			method: "POST",
+			body: JSON.stringify(event)
+		}));
+	} };
+}
+//#endregion
+//#region src/better-zap.ts
+function serializeRuntimeTemplate(templates, templateName, options) {
+	return serializeTemplateFromRegistry(templates, templateName, {
+		language: options.language,
+		params: options.params ?? {}
+	});
+}
+function betterZap(options) {
+	const { database, config, webhook: webhookHooks, conversationSync, basePath = "/api/whatsapp" } = options;
+	const templates = options.templates ?? EMPTY_TEMPLATE_REGISTRY;
+	const log = createLogger(options.logger);
+	const logger = new MessageLoggerService(database.whatsappLog, log, createConversationSyncNotifier(conversationSync));
+	const whatsapp = new WhatsAppService(config, logger, log);
+	const coreContext = {
+		db: database,
+		api: whatsapp,
+		logger
+	};
+	const coreServices = {
+		whatsapp,
+		logger
+	};
+	const plugins = options.plugins ?? [];
+	const pluginRuntime = initializePlugins({
+		plugins,
+		database,
+		config,
+		coreContext,
+		coreServices,
+		log
+	});
+	const webhookRouter = createWebhookHandler({
+		verifyToken: config.webhookToken,
+		appSecret: config.appSecret,
+		logger,
+		log,
+		onMessage: async (ctx) => {
+			const hookContext = {
+				...ctx,
+				...pluginRuntime.context
+			};
+			await runPluginMessageHooks({
+				plugins,
+				ctx: hookContext,
+				log
+			});
+			await webhookHooks.onMessage(hookContext);
+		},
+		onStatusUpdate: async (ctx) => {
+			const hookContext = {
+				...ctx,
+				...pluginRuntime.context
+			};
+			await runPluginStatusHooks({
+				plugins,
+				ctx: hookContext,
+				log
+			});
+			await webhookHooks.onStatusUpdate(hookContext);
+		}
+	});
+	const app = new Hono().basePath(basePath);
+	app.use("*", async (c, next) => {
+		c.set("whatsapp", whatsapp);
+		c.set("store", database.whatsappLog);
+		c.set("logger", log);
+		await next();
+	});
+	app.route("/webhook", webhookRouter);
+	app.post("/send/text", handleSendText);
+	app.post("/send/template", createSendTemplateHandler(templates));
+	app.post("/send/interactive", handleSendInteractive);
+	app.post("/send/location", handleSendLocation);
+	app.get("/conversations", handleListConversations);
+	app.get("/conversations/:phone", handleGetConversation);
+	app.get("/conversations/:phone/messages", handleGetMessages);
+	const api = {
+		send: {
+			text: (to, body, opts) => whatsapp.sendText(to, body, opts),
+			template: ((to, templateName, opts = {}) => {
+				if (!hasConfiguredTemplates(templates)) return whatsapp.sendTemplate(to, String(templateName), opts?.language, opts?.components, opts?.logging);
+				const serializedTemplate = serializeRuntimeTemplate(templates, templateName, opts);
+				return whatsapp.sendTemplate(to, String(templateName), serializedTemplate.language, serializedTemplate.components, opts.logging);
+			}),
+			templateRaw: (to, templateName, opts) => whatsapp.sendTemplate(to, templateName, opts?.language, opts?.components, opts?.logging),
+			interactiveButtons: (to, body, buttons, opts) => whatsapp.sendInteractiveButtons(to, body, buttons, opts),
+			interactiveList: (to, body, buttonLabel, sections, opts) => whatsapp.sendInteractiveList(to, body, buttonLabel, sections, opts),
+			interactiveMediaCarousel: (data, opts) => whatsapp.sendInteractiveMediaCarousel(data, opts),
+			location: (to, location, opts) => whatsapp.sendLocation(to, location.latitude, location.longitude, location.name, location.address, opts),
+			markAsRead: (messageId) => whatsapp.markAsRead(messageId),
+			reaction: (to, messageId, emoji) => whatsapp.sendReaction(to, messageId, emoji)
+		},
+		conversations: {
+			list: () => database.whatsappLog.getConversations(),
+			get: (phone) => database.whatsappLog.getConversationByPhone(formatPhone(phone)),
+			messages: async (phone, opts) => {
+				const conversation = await database.whatsappLog.getConversationByPhone(formatPhone(phone));
+				if (!conversation) return [];
+				return await database.whatsappLog.getMessagesByConversationPaginated(conversation.id, opts?.cursor, opts?.limit);
+			}
+		}
+	};
+	const handler = async (request, env, executionCtx) => app.fetch(request, env, executionCtx);
+	return {
+		handler,
+		api,
+		services: pluginRuntime.services
+	};
+}
+//#endregion
+export { betterZap, createWebhookHandler, getMessageContent, verifyMetaWebhookSignature };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@better-zap/hono",
+  "version": "0.0.1",
+  "description": "Hono adapter and webhook runtime for Better Zap.",
+  "license": "ISC",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "hono": "4.12.5",
+    "better-zap": "0.0.1"
+  },
+  "peerDependencies": {
+    "hono": "4.12.5"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20240117.0",
+    "@types/node": "^25.4.0",
+    "tsdown": "^0.21.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}