@better-zap/hono 0.1.0 → 0.2.1

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { EMPTY_TEMPLATE_REGISTRY, MessageLoggerService, WhatsAppService, createLogger, formatPhone, hasConfiguredTemplates, normalizeConversationRecord, normalizeConversationRecords, serializeError, serializeTemplateFromRegistry } from "better-zap";
+import { CoexistenceService, EMPTY_TEMPLATE_REGISTRY, MessageLoggerService, WhatsAppService, createLogger, formatPhone, hasConfiguredTemplates, normalizeCoexistenceSessionEvent, normalizeConversationRecord, normalizeConversationRecords, serializeError, serializeTemplateFromRegistry } from "better-zap";
 //#region src/plugins/runtime.ts
 function initializePlugins(options) {
 	let pluginContext = {};
@@ -70,6 +70,409 @@ async function runPluginStatusHooks(options) {
 	}
 }
 //#endregion
+//#region src/handler/coexistence.ts
+const ROUTES_NOT_CONFIGURED = "Coexistence routes are not configured";
+const STORAGE_NOT_CONFIGURED = "Coexistence storage is not configured";
+const SYNC_DEADLINE_MS = 1440 * 60 * 1e3;
+const PREFLIGHT_FAILURE_FIELDS = [
+	["unsupportedCountry", "unsupported_country"],
+	["unsupportedAppVersion", "unsupported_app_version"],
+	["lowActivityNumber", "low_activity_number"],
+	["priorProviderWabaRegistration", "prior_provider_waba_registration"],
+	["missingPaymentSetup", "missing_payment_setup"]
+];
+function getCoexistence(c) {
+	return c.get("coexistence");
+}
+function getCoexistenceStore(c) {
+	return c.get("coexistenceStore");
+}
+function shouldSubscribeWabaAfterCodeExchange(c) {
+	return c.get("subscribeWabaAfterCodeExchange") !== false;
+}
+function graphResultResponse(c, result) {
+	if (result.success) return c.json(result.data ?? { success: true });
+	return c.json({
+		success: false,
+		error: result.error ?? "Meta Graph request failed",
+		code: "meta_graph_request_failed",
+		...result.errorCode ? { errorCode: result.errorCode } : {},
+		...result.details ? { details: result.details } : {}
+	}, result.httpStatus ?? 502);
+}
+function isSessionPayload(value) {
+	return typeof value === "object" && value !== null && "event" in value && typeof value.event === "string";
+}
+function resolveSessionPayload(body) {
+	if (isSessionPayload(body.session)) return body.session;
+	if (isSessionPayload(body.sessionInfo)) return body.sessionInfo;
+	if (isSessionPayload(body)) return body;
+	if (typeof body.data === "object" && body.data !== null) return {
+		event: "FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING",
+		data: body.data
+	};
+	return null;
+}
+function resolveCode(body, session) {
+	if (typeof body.code === "string" && body.code.length > 0) return body.code;
+	if (typeof session?.data?.code === "string" && session.data.code.length > 0) return session.data.code;
+	return null;
+}
+function createRecordId(prefix) {
+	return `${prefix}_${crypto.randomUUID()}`;
+}
+function optionalString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function optionalNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function resolveIdempotencyKey(c, body) {
+	return optionalString(body.idempotencyKey) ?? optionalString(c.req.header("Idempotency-Key")) ?? optionalString(c.req.header("X-Idempotency-Key"));
+}
+function validateStateAndNonce(body, session) {
+	const state = optionalString(body.state);
+	const expectedState = optionalString(body.expectedState) ?? optionalString(session.data?.state);
+	if (expectedState && state !== expectedState) return "state mismatch";
+	const nonce = optionalString(body.nonce);
+	const expectedNonce = optionalString(body.expectedNonce) ?? optionalString(session.data?.nonce);
+	if (expectedNonce && nonce !== expectedNonce) return "nonce mismatch";
+	return null;
+}
+async function recordOnboardingSession(c, input) {
+	await getCoexistenceStore(c)?.recordOnboardingSession({
+		id: input.idempotencyKey ?? createRecordId("coexistence_session"),
+		event: input.session.event,
+		accountId: input.session.data?.business_id,
+		wabaId: input.session.data?.waba_id,
+		phoneNumberId: input.session.data?.phone_number_id,
+		payload: {
+			...input.session,
+			data: {
+				...input.session.data,
+				...input.state ? { state: input.state } : {},
+				...input.nonce ? { nonce: input.nonce } : {},
+				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+			}
+		},
+		...input.preflight ? { preflight: input.preflight } : {}
+	});
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function boolField(value, key) {
+	return typeof value[key] === "boolean" ? value[key] : void 0;
+}
+function stringField(value, key) {
+	return typeof value[key] === "string" ? value[key] : void 0;
+}
+function failureCodesField(value) {
+	if (!Array.isArray(value?.failureCodes)) return;
+	return value.failureCodes.filter((code) => typeof code === "string");
+}
+function resolvePreflightState(body, session) {
+	const source = isObject(body.preflight) ? body.preflight : isObject(body.eligibility) ? body.eligibility : void 0;
+	const billing = isObject(body.billing) ? body.billing : void 0;
+	if (!source && !billing) return;
+	const state = {
+		phoneNumberId: stringField(source ?? {}, "phoneNumberId") ?? session?.data?.phone_number_id,
+		wabaId: stringField(source ?? {}, "wabaId") ?? session?.data?.waba_id,
+		displayPhoneNumber: stringField(source ?? {}, "displayPhoneNumber") ?? session?.data?.display_phone_number,
+		eligibilityStatus: stringField(source ?? {}, "eligibilityStatus"),
+		billingStatus: stringField(source ?? {}, "billingStatus") ?? stringField(billing ?? {}, "status"),
+		unsupportedCountry: boolField(source ?? {}, "unsupportedCountry"),
+		unsupportedAppVersion: boolField(source ?? {}, "unsupportedAppVersion"),
+		lowActivityNumber: boolField(source ?? {}, "lowActivityNumber"),
+		priorProviderWabaRegistration: boolField(source ?? {}, "priorProviderWabaRegistration"),
+		missingPaymentSetup: boolField(source ?? {}, "missingPaymentSetup") ?? boolField(billing ?? {}, "missingPaymentSetup") ?? (stringField(billing ?? {}, "status") === "missing_payment_setup" ? true : void 0),
+		failureCodes: failureCodesField(source),
+		metadata: {
+			...isObject(source?.metadata) ? { eligibility: source.metadata } : {},
+			...isObject(billing) ? { billing } : {}
+		}
+	};
+	state.failureCodes = getPreflightFailureCodes(state);
+	return state;
+}
+function getPreflightFailureCodes(state) {
+	const explicit = Array.isArray(state.failureCodes) ? state.failureCodes.filter((code) => typeof code === "string") : [];
+	const derived = PREFLIGHT_FAILURE_FIELDS.flatMap(([field, code]) => state[field] ? [code] : []);
+	return [...new Set([...explicit, ...derived])];
+}
+function preflightFailureResponse(c, failureCodes) {
+	return c.json({
+		success: false,
+		error: "Coexistence preflight failed",
+		code: "coexistence_preflight_failed",
+		failureCodes
+	}, 422);
+}
+async function handleEmbeddedSignupCallback(c) {
+	const coexistence = getCoexistence(c);
+	if (!coexistence) return c.json({ error: ROUTES_NOT_CONFIGURED }, 501);
+	const coexistenceStore = getCoexistenceStore(c);
+	if (!coexistenceStore) return c.json({ error: STORAGE_NOT_CONFIGURED }, 501);
+	try {
+		const body = await c.req.json();
+		const session = resolveSessionPayload(body);
+		if (!session) return c.json({ error: "session is required" }, 400);
+		const stateError = validateStateAndNonce(body, session);
+		if (stateError) return c.json({ error: stateError }, 400);
+		const normalizedEvent = normalizeCoexistenceSessionEvent(session.event);
+		const code = resolveCode(body, session);
+		const idempotencyKey = resolveIdempotencyKey(c, body);
+		const state = optionalString(body.state);
+		const nonce = optionalString(body.nonce);
+		const preflight = resolvePreflightState(body, session);
+		if (idempotencyKey && coexistenceStore.getRawEventStatus) {
+			const existing = await coexistenceStore.getRawEventStatus(idempotencyKey);
+			if (existing?.status === "processed") return c.json({
+				success: true,
+				status: "duplicate",
+				idempotencyKey,
+				result: existing.result ?? null
+			});
+		}
+		await recordOnboardingSession(c, {
+			session,
+			idempotencyKey,
+			state,
+			nonce,
+			...preflight ? { preflight } : {}
+		});
+		if (preflight) {
+			await coexistenceStore.upsertPreflightState?.(preflight);
+			const failureCodes = getPreflightFailureCodes(preflight);
+			if (failureCodes.length > 0) return preflightFailureResponse(c, failureCodes);
+		}
+		if (normalizedEvent !== "FINISH") return c.json({
+			success: true,
+			status: "recorded",
+			event: normalizedEvent,
+			session
+		});
+		if (!code) return c.json({ error: "code is required" }, 400);
+		const tokenExchange = await coexistence.exchangeEmbeddedSignupCode({
+			code,
+			redirectUri: typeof body.redirectUri === "string" ? body.redirectUri : void 0
+		});
+		if (!tokenExchange.success) {
+			if (idempotencyKey) await coexistenceStore.updateRawEventStatus?.({
+				id: idempotencyKey,
+				status: "failed",
+				error: tokenExchange.error ?? "Meta Graph request failed"
+			});
+			return graphResultResponse(c, tokenExchange);
+		}
+		if (!tokenExchange.data) {
+			if (idempotencyKey) await coexistenceStore.updateRawEventStatus?.({
+				id: idempotencyKey,
+				status: "failed",
+				error: "Token exchange returned no credential data"
+			});
+			return c.json({
+				success: false,
+				error: "Token exchange returned no credential data"
+			}, 502);
+		}
+		let subscriptionStatus = "not_requested";
+		let subscriptionResult;
+		if (session.data?.waba_id) if (shouldSubscribeWabaAfterCodeExchange(c)) {
+			subscriptionResult = await coexistence.subscribeWaba({
+				wabaId: session.data.waba_id,
+				accessToken: tokenExchange.data.accessToken
+			});
+			subscriptionStatus = subscriptionResult.success ? "subscribed" : "failed";
+		} else subscriptionStatus = "skipped";
+		if (session.data?.waba_id && session.data.phone_number_id) await coexistenceStore.upsertConnectedAccount({
+			wabaId: session.data.waba_id,
+			businessId: session.data.business_id,
+			accountId: session.data.business_id,
+			phoneNumberId: session.data.phone_number_id,
+			displayPhoneNumber: session.data.display_phone_number,
+			credentialRef: tokenExchange.data.credentialRef,
+			credentialProvider: tokenExchange.data.credentialProvider,
+			credentialMetadata: tokenExchange.data.credentialMetadata,
+			...preflight ? { preflight } : {},
+			metadata: {
+				onboardingEvent: session.event,
+				tokenType: tokenExchange.data.tokenType,
+				tokenExpiresIn: optionalNumber(tokenExchange.data.expiresIn),
+				subscriptionStatus,
+				...subscriptionResult ? { subscription: {
+					success: subscriptionResult.success,
+					error: subscriptionResult.error,
+					errorCode: subscriptionResult.errorCode,
+					httpStatus: subscriptionResult.httpStatus,
+					details: subscriptionResult.details
+				} } : {}
+			}
+		});
+		if (subscriptionResult && !subscriptionResult.success) {
+			await coexistenceStore.recordLifecycleEvent({
+				accountId: session.data?.business_id,
+				wabaId: session.data?.waba_id,
+				phoneNumberId: session.data?.phone_number_id,
+				event: "WABA_SUBSCRIPTION_FAILED",
+				payload: {
+					session,
+					error: subscriptionResult.error,
+					errorCode: subscriptionResult.errorCode,
+					httpStatus: subscriptionResult.httpStatus,
+					details: subscriptionResult.details
+				}
+			});
+			if (idempotencyKey) await coexistenceStore.updateRawEventStatus?.({
+				id: idempotencyKey,
+				status: "failed",
+				error: subscriptionResult.error ?? "Meta Graph request failed",
+				result: {
+					phase: "subscribe_waba",
+					wabaId: session.data?.waba_id,
+					error: subscriptionResult.error,
+					errorCode: subscriptionResult.errorCode,
+					details: subscriptionResult.details
+				}
+			});
+			return c.json({
+				success: false,
+				phase: "subscribe_waba",
+				error: subscriptionResult.error ?? "Meta Graph request failed",
+				...subscriptionResult.errorCode ? { errorCode: subscriptionResult.errorCode } : {},
+				...subscriptionResult.details ? { details: subscriptionResult.details } : {}
+			}, subscriptionResult.httpStatus ?? 502);
+		}
+		const responseBody = {
+			success: true,
+			status: "exchanged",
+			session,
+			subscriptionStatus
+		};
+		if (idempotencyKey) await coexistenceStore.updateRawEventStatus?.({
+			id: idempotencyKey,
+			status: "processed",
+			result: responseBody
+		});
+		return c.json(responseBody);
+	} catch (error) {
+		c.get("logger").error("coexistence.callback_error", serializeError(error));
+		return c.json({
+			error: "Internal error handling coexistence callback",
+			code: "coexistence_callback_failed"
+		}, 500);
+	}
+}
+async function handlePhoneStatus(c) {
+	const coexistence = getCoexistence(c);
+	if (!coexistence) return c.json({ error: ROUTES_NOT_CONFIGURED }, 501);
+	try {
+		const phoneNumberId = c.req.param("phoneNumberId");
+		if (!phoneNumberId) return c.json({ error: "phoneNumberId is required" }, 400);
+		return graphResultResponse(c, await coexistence.getPhoneStatus({ phoneNumberId }));
+	} catch (error) {
+		c.get("logger").error("coexistence.status_error", serializeError(error));
+		return c.json({
+			error: "Internal error fetching coexistence phone status",
+			code: "coexistence_status_failed"
+		}, 500);
+	}
+}
+async function handleSyncRequest(c, syncType) {
+	const coexistence = getCoexistence(c);
+	if (!coexistence) return c.json({ error: ROUTES_NOT_CONFIGURED }, 501);
+	try {
+		const phoneNumberId = c.req.param("phoneNumberId");
+		if (!phoneNumberId) return c.json({ error: "phoneNumberId is required" }, 400);
+		const blocked = await getBlockedConnectedAccount(c, phoneNumberId);
+		if (blocked) return c.json({
+			success: false,
+			error: "Coexistence account is not usable",
+			code: "coexistence_account_not_usable",
+			status: blocked.status,
+			phoneNumberId
+		}, 409);
+		const body = await resolveOptionalJsonBody(c);
+		const coexistenceStore = getCoexistenceStore(c);
+		const inFlight = await coexistenceStore?.getInFlightSyncJob?.({
+			phoneNumberId,
+			syncType
+		});
+		if (inFlight) return c.json({
+			success: false,
+			error: "Coexistence sync already in flight",
+			code: "sync_already_in_flight",
+			requestId: inFlight.requestId,
+			deadlineAt: inFlight.deadlineAt
+		}, 409);
+		const preflight = await coexistenceStore?.getPreflightStateByPhoneNumberId?.(phoneNumberId) ?? resolveInlinePreflightState(body, phoneNumberId);
+		const failureCodes = preflight ? getPreflightFailureCodes(preflight) : [];
+		if (failureCodes.length > 0) return preflightFailureResponse(c, failureCodes);
+		const result = syncType === "smb_app_state_sync" ? await coexistence.startContactsSync({ phoneNumberId }) : await coexistence.startHistorySync({ phoneNumberId });
+		if (!result.success) return graphResultResponse(c, result);
+		await recordSyncJob(c, {
+			phoneNumberId,
+			syncType,
+			result: result.data,
+			onboardingSessionId: typeof body?.onboardingSessionId === "string" ? body.onboardingSessionId : void 0
+		});
+		return graphResultResponse(c, result);
+	} catch (error) {
+		c.get("logger").error("coexistence.sync_error", serializeError(error));
+		return c.json({
+			error: "Internal error requesting coexistence sync",
+			code: "coexistence_sync_failed"
+		}, 500);
+	}
+}
+async function getBlockedConnectedAccount(c, phoneNumberId) {
+	const coexistenceStore = getCoexistenceStore(c);
+	if (!coexistenceStore) return null;
+	const account = await coexistenceStore.getConnectedAccountByPhoneNumberId(phoneNumberId);
+	if (!account) return null;
+	return account.usable === false || account.status === "offboarded" ? account : null;
+}
+async function recordSyncJob(c, input) {
+	const requestId = input.result?.request_id;
+	const coexistenceStore = getCoexistenceStore(c);
+	if (!requestId || !coexistenceStore) return;
+	const requestedAt = /* @__PURE__ */ new Date();
+	const deadlineAt = input.syncType === "history" ? new Date(requestedAt.getTime() + SYNC_DEADLINE_MS) : void 0;
+	await coexistenceStore.createSyncJob({
+		requestId,
+		syncType: input.syncType,
+		onboardingSessionId: input.onboardingSessionId,
+		phoneNumberId: input.phoneNumberId,
+		status: "requested",
+		requestedAt,
+		deadlineAt,
+		metadata: { response: input.result }
+	});
+}
+async function resolveOptionalJsonBody(c) {
+	if (!(c.req.header("content-type") ?? "").includes("application/json")) return;
+	try {
+		return await c.req.json();
+	} catch {
+		return;
+	}
+}
+function resolveInlinePreflightState(body, phoneNumberId) {
+	if (!body) return;
+	const state = resolvePreflightState(body, null);
+	if (!state) return;
+	return {
+		...state,
+		phoneNumberId: state.phoneNumberId ?? phoneNumberId
+	};
+}
+function handleContactsSync(c) {
+	return handleSyncRequest(c, "smb_app_state_sync");
+}
+function handleHistorySync(c) {
+	return handleSyncRequest(c, "history");
+}
+//#endregion
 //#region src/handler/conversations.ts
 async function handleListConversations(c) {
 	try {
@@ -340,9 +743,51 @@ async function processPayload(payload, env, config, log) {
 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. */
+/** Routes webhook changes to field-specific processors. */
 async function processChange(change, env, config, log) {
+	switch (change.field) {
+		case "messages":
+			await processMessagesChange(change, env, config, log);
+			return;
+		case "history":
+			await processHistoryChange(change, config, log);
+			return;
+		case "smb_app_state_sync":
+			await processSmbAppStateSyncChange(change, config, log);
+			return;
+		case "smb_message_echoes":
+			await processSmbMessageEchoesChange(change, config, log);
+			return;
+		case "account_update":
+			await processAccountUpdateChange(change, config, log);
+			return;
+		case "account_offboarded":
+			await processAccountOffboardedChange(change, config, log);
+			return;
+		case "account_reconnected":
+			await processAccountReconnectedChange(change, config, log);
+			return;
+		default:
+			log.debug("webhook.unknown_field_ignored", { field: change.field });
+			return;
+	}
+}
+/** Routes ordinary messages, statuses, and errors to the existing handlers. */
+async function processMessagesChange(change, _env, config, log) {
 	const value = change.value;
+	const messageClassification = classifyCoexistenceMessages(value.messages);
+	if (messageClassification === "edit") {
+		await processMessageEditChange(change, config, log);
+		return;
+	}
+	if (messageClassification === "revoke") {
+		await processMessageRevokeChange(change, config, log);
+		return;
+	}
+	if (messageClassification === "unsupported") {
+		await processUnsupportedMessagesChange(change, config, log);
+		return;
+	}
 	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) {
@@ -359,12 +804,345 @@ async function processChange(change, env, config, log) {
 		}
 	}
 }
+async function processHistoryChange(change, config, log) {
+	const value = change.value;
+	const requestId = value.request_id;
+	let importedMessages = 0;
+	let duplicateMessages = 0;
+	let hasHistoryErrors = (value.errors?.length ?? 0) > 0;
+	if (requestId && config.database?.coexistence) await config.database.coexistence.updateSyncJobByRequestId(requestId, {
+		status: "processing",
+		metadata: { field: "history" }
+	});
+	if (value.errors && value.errors.length > 0) await processCoexistenceErrors(change, value, config, log);
+	for (const chunk of value.history ?? []) {
+		if (chunk.errors && chunk.errors.length > 0) {
+			hasHistoryErrors = true;
+			await processCoexistenceErrors(change, {
+				...value,
+				errors: chunk.errors
+			}, config, log);
+		}
+		for (const message of chunk.messages ?? []) {
+			if (message.revoked || message.type === "revoked") {
+				await runOptionalHook(() => config.onCoexistenceMessageRevoke?.({
+					value: {
+						...value,
+						messages: [message]
+					},
+					change,
+					revokedMessages: 1
+				}), "webhook.on_coexistence_message_revoke_hook_failed", log);
+				continue;
+			}
+			if (message.edited || message.type === "message_edit") {
+				await runOptionalHook(() => config.onCoexistenceMessageEdit?.({
+					value: {
+						...value,
+						messages: [message]
+					},
+					change,
+					editedMessages: 1
+				}), "webhook.on_coexistence_message_edit_hook_failed", log);
+				continue;
+			}
+			if (message.unsupported || message.type === "unsupported" || (message.errors?.length ?? 0) > 0) {
+				await processCoexistenceErrors(change, {
+					...value,
+					unsupported: true,
+					errors: (message.errors ?? []).map(toWebhookError)
+				}, config, log);
+				continue;
+			}
+			const result = await importCoexistenceMessage({
+				message,
+				contacts: value.contacts,
+				metadata: value.metadata,
+				requestId,
+				source: "history",
+				config
+			});
+			if (result === "created") importedMessages += 1;
+			else if (result === "duplicate") duplicateMessages += 1;
+		}
+		for (const status of chunk.statuses ?? []) await processStatusUpdate(status, config, log);
+	}
+	if (requestId && config.database?.coexistence) {
+		const updatedAt = /* @__PURE__ */ new Date();
+		await config.database.coexistence.updateSyncJobByRequestId(requestId, {
+			status: hasHistoryErrors ? "failed" : "completed",
+			...hasHistoryErrors ? { failedAt: updatedAt } : { completedAt: updatedAt },
+			updatedAt,
+			metadata: {
+				field: "history",
+				importedMessages,
+				duplicateMessages
+			}
+		});
+	}
+	await runOptionalHook(() => config.onCoexistenceHistory?.({
+		value,
+		change,
+		importedMessages,
+		duplicateMessages
+	}), "webhook.on_coexistence_history_hook_failed", log);
+}
+async function processSmbAppStateSyncChange(change, config, log) {
+	const value = change.value;
+	let upsertedContacts = 0;
+	let removedContacts = 0;
+	const hasSyncErrors = (value.errors?.length ?? 0) > 0;
+	if (value.request_id && config.database?.coexistence) await config.database.coexistence.updateSyncJobByRequestId(value.request_id, {
+		status: "processing",
+		metadata: { field: "smb_app_state_sync" }
+	});
+	if (hasSyncErrors) await processCoexistenceErrors(change, value, config, log);
+	if (!hasSyncErrors && config.database?.coexistence) for (const contact of value.contacts ?? []) {
+		if (contact.removed) {
+			await config.database.coexistence.removeContact({
+				waId: contact.wa_id,
+				phoneNumberId: value.metadata?.phone_number_id
+			});
+			removedContacts += 1;
+			continue;
+		}
+		await config.database.coexistence.upsertContact({
+			waId: contact.wa_id,
+			phoneNumberId: value.metadata?.phone_number_id,
+			displayName: contact.profile?.name,
+			removed: false,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			metadata: contact
+		});
+		upsertedContacts += 1;
+	}
+	if (value.request_id && config.database?.coexistence) {
+		const updatedAt = /* @__PURE__ */ new Date();
+		await config.database.coexistence.updateSyncJobByRequestId(value.request_id, {
+			status: hasSyncErrors ? "failed" : "completed",
+			...hasSyncErrors ? { failedAt: updatedAt } : { completedAt: updatedAt },
+			updatedAt,
+			metadata: {
+				field: "smb_app_state_sync",
+				upsertedContacts,
+				removedContacts,
+				errors: value.errors
+			}
+		});
+	}
+	await runOptionalHook(() => config.onSmbAppStateSync?.({
+		value,
+		change,
+		upsertedContacts,
+		removedContacts
+	}), "webhook.on_smb_app_state_sync_hook_failed", log);
+}
+async function processMessageEditChange(change, config, log) {
+	const value = change.value;
+	const editedMessages = value.messages.length;
+	await runOptionalHook(() => config.onCoexistenceMessageEdit?.({
+		value,
+		change,
+		editedMessages
+	}), "webhook.on_coexistence_message_edit_hook_failed", log);
+}
+async function processMessageRevokeChange(change, config, log) {
+	const value = change.value;
+	const revokedMessages = value.messages.length;
+	await runOptionalHook(() => config.onCoexistenceMessageRevoke?.({
+		value,
+		change,
+		revokedMessages
+	}), "webhook.on_coexistence_message_revoke_hook_failed", log);
+}
+async function processUnsupportedMessagesChange(change, config, log) {
+	const value = change.value;
+	const errors = [...value.errors ?? [], ...(value.messages ?? []).flatMap((message) => (message.errors ?? []).map(toWebhookError))];
+	await runOptionalHook(() => config.onCoexistenceUnsupportedMessage?.({
+		value,
+		change,
+		errors
+	}), "webhook.on_coexistence_unsupported_hook_failed", log);
+}
+async function processSmbMessageEchoesChange(change, config, log) {
+	const value = change.value;
+	let importedMessages = 0;
+	let duplicateMessages = 0;
+	for (const message of value.messages ?? []) {
+		const result = await importCoexistenceMessage({
+			message,
+			contacts: value.contacts,
+			metadata: value.metadata,
+			source: "smb_message_echoes",
+			forceDirection: "outgoing",
+			config
+		});
+		if (result === "created") importedMessages += 1;
+		else if (result === "duplicate") duplicateMessages += 1;
+	}
+	await runOptionalHook(() => config.onSmbMessageEcho?.({
+		value,
+		change,
+		importedMessages,
+		duplicateMessages
+	}), "webhook.on_smb_message_echo_hook_failed", log);
+}
+async function processAccountUpdateChange(change, config, log) {
+	const value = change.value;
+	if (config.database?.coexistence) await config.database.coexistence.recordLifecycleEvent({
+		wabaId: value.waba_info?.waba_id,
+		phoneNumberId: value.phone_number_id,
+		accountId: value.waba_info?.owner_business_id,
+		event: value.event ?? "account_update",
+		payload: value,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	await runOptionalHook(() => config.onCoexistenceAccountUpdate?.({
+		value,
+		change
+	}), "webhook.on_coexistence_account_update_hook_failed", log);
+}
+async function processAccountOffboardedChange(change, config, log) {
+	const value = change.value;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	if (config.database?.coexistence) {
+		await config.database.coexistence.recordLifecycleEvent({
+			wabaId: value.waba_info?.waba_id,
+			phoneNumberId: value.phone_number_id ?? value.metadata?.phone_number_id,
+			accountId: value.waba_info?.owner_business_id,
+			event: value.event ?? "ACCOUNT_OFFBOARDED",
+			payload: value,
+			createdAt: now
+		});
+		await upsertLifecycleAccountState(value, config, {
+			status: "offboarded",
+			usable: false,
+			offboardedAt: now,
+			updatedAt: now,
+			metadata: {
+				lifecycleEvent: "account_offboarded",
+				reason: value.reason,
+				raw: value
+			}
+		});
+	}
+	await runOptionalHook(() => config.onCoexistenceAccountOffboarded?.({
+		value,
+		change
+	}), "webhook.on_coexistence_account_offboarded_hook_failed", log);
+}
+async function processAccountReconnectedChange(change, config, log) {
+	const value = change.value;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	if (config.database?.coexistence) {
+		await config.database.coexistence.recordLifecycleEvent({
+			wabaId: value.waba_info?.waba_id,
+			phoneNumberId: value.phone_number_id ?? value.metadata?.phone_number_id,
+			accountId: value.waba_info?.owner_business_id,
+			event: value.event ?? "ACCOUNT_RECONNECTED",
+			payload: value,
+			createdAt: now
+		});
+		await upsertLifecycleAccountState(value, config, {
+			status: "reconnected",
+			usable: true,
+			reconnectedAt: now,
+			updatedAt: now,
+			metadata: {
+				lifecycleEvent: "account_reconnected",
+				reconnectReason: value.reconnect_reason,
+				cloudApiProducts: value.cloud_api_products,
+				raw: value
+			}
+		});
+	}
+	await runOptionalHook(() => config.onCoexistenceAccountReconnected?.({
+		value,
+		change
+	}), "webhook.on_coexistence_account_reconnected_hook_failed", log);
+}
+async function processCoexistenceErrors(change, value, config, log) {
+	const errors = value.errors ?? [];
+	const requestId = "request_id" in value && typeof value.request_id === "string" ? value.request_id : void 0;
+	if (requestId && config.database?.coexistence) await config.database.coexistence.updateSyncJobByRequestId(requestId, {
+		status: "failed",
+		metadata: {
+			field: change.field,
+			errors,
+			isHistoryOptOut: errors.some((error) => error.code === 2593109)
+		}
+	});
+	await runOptionalHook(() => config.onCoexistenceUnsupportedMessage?.({
+		value,
+		change,
+		errors
+	}), "webhook.on_coexistence_unsupported_hook_failed", log);
+}
+async function upsertLifecycleAccountState(value, config, patch) {
+	const store = config.database?.coexistence;
+	const phoneNumberId = value.phone_number_id ?? value.metadata?.phone_number_id;
+	const wabaId = value.waba_info?.waba_id;
+	if (!store || !phoneNumberId || !wabaId) return;
+	const existing = await store.getConnectedAccountByPhoneNumberId(phoneNumberId) ?? await store.getConnectedAccountByWabaId(wabaId);
+	await store.upsertConnectedAccount({
+		wabaId,
+		phoneNumberId,
+		accountId: value.waba_info?.owner_business_id ?? existing?.accountId,
+		businessId: existing?.businessId,
+		displayPhoneNumber: value.metadata?.display_phone_number ?? existing?.displayPhoneNumber,
+		...existing,
+		...patch,
+		metadata: {
+			...existing?.metadata,
+			...patch.metadata
+		}
+	});
+}
+async function importCoexistenceMessage(input) {
+	if (!input.config.database?.coexistence) return "skipped";
+	const direction = input.forceDirection ?? resolveMessageDirection(input.message, input.metadata?.display_phone_number);
+	const contact = resolveCoexistenceContact(input.contacts, input.message);
+	const phone = resolveConversationPhone(input.message, direction, contact);
+	return await input.config.logger.logImportedMessage({
+		phone,
+		waMessageId: input.message.id,
+		direction,
+		content: getMessageContent(input.message),
+		sentAt: parseWebhookTimestamp(input.message.timestamp),
+		senderName: contact?.profile?.name,
+		metadata: {
+			source: input.source,
+			requestId: input.requestId,
+			phoneNumberId: input.metadata?.phone_number_id,
+			raw: input.message
+		}
+	}) ? "created" : "duplicate";
+}
+function resolveMessageDirection(message, businessDisplayPhoneNumber) {
+	if (!businessDisplayPhoneNumber) return "incoming";
+	return formatPhone(message.from) === formatPhone(businessDisplayPhoneNumber) ? "outgoing" : "incoming";
+}
+function resolveConversationPhone(message, direction, contact) {
+	if (direction === "incoming") return message.from;
+	const messageWithRecipient = message;
+	return messageWithRecipient.to ?? messageWithRecipient.recipient_id ?? contact?.wa_id ?? message.from;
+}
+function parseWebhookTimestamp(timestamp) {
+	const sentAt = /* @__PURE__ */ new Date(parseInt(timestamp, 10) * 1e3);
+	return Number.isNaN(sentAt.getTime()) ? (/* @__PURE__ */ new Date()).toISOString() : sentAt.toISOString();
+}
+async function runOptionalHook(run, logEvent, log) {
+	try {
+		await run();
+	} catch (error) {
+		log.error(logEvent, serializeError(error));
+	}
+}
 /**
 * 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}
+* 1. Extracts human-readable content
+* 2. Atomically logs and deduplicates by waMessageId
+* 3. Calls {@link WebhookConfig.onMessage}
 */
 async function processIncomingMessage(message, contact, config, log) {
 	const phone = message.from;
@@ -373,25 +1151,24 @@ async function processIncomingMessage(message, contact, config, log) {
 		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 sentAt = /* @__PURE__ */ new Date(parseInt(message.timestamp, 10) * 1e3);
 	const normalizedSentAt = Number.isNaN(sentAt.getTime()) ? (/* @__PURE__ */ new Date()).toISOString() : sentAt.toISOString();
 	const { id, type, text, from, timestamp, ...rawMetadata } = message;
-	await config.logger.logIncoming({
+	if (!await config.logger.logIncoming({
 		phone,
 		waMessageId: message.id,
 		content,
 		sentAt: normalizedSentAt,
 		senderName: contact?.profile?.name,
 		metadata: Object.keys(rawMetadata).length > 0 ? rawMetadata : void 0
-	});
+	})) {
+		log.info("webhook.duplicate_ignored", {
+			waMessageId: message.id,
+			phone
+		});
+		return;
+	}
 	const ctx = {
 		message,
 		contact,
@@ -445,6 +1222,23 @@ function resolveContact(contacts, message) {
 	if (!contacts || contacts.length === 0) return;
 	return contacts.find((c) => c.wa_id === message.from) ?? contacts[0];
 }
+function resolveCoexistenceContact(contacts, message) {
+	if (!contacts || contacts.length === 0) return;
+	return contacts.find((c) => c.wa_id === message.from) ?? contacts[0];
+}
+function classifyCoexistenceMessages(messages) {
+	if (!messages || messages.length === 0) return "ordinary";
+	if (messages.some((message) => message.revoked || message.type === "revoked")) return "revoke";
+	if (messages.some((message) => message.edited || message.type === "message_edit")) return "edit";
+	if (messages.some((message) => message.unsupported || message.type === "unsupported" || (message.errors?.length ?? 0) > 0)) return "unsupported";
+	return "ordinary";
+}
+function toWebhookError(error) {
+	return {
+		...error,
+		error_data: error.error_data ?? { details: error.message }
+	};
+}
 //#endregion
 //#region src/internal/cloudflare/constants.ts
 const GLOBAL_WORKSPACE_DO_ID = "global-workspace";
@@ -474,6 +1268,15 @@ function betterZap(options) {
 	const log = createLogger(options.logger);
 	const logger = new MessageLoggerService(database.whatsappLog, log, createConversationSyncNotifier(conversationSync));
 	const whatsapp = new WhatsAppService(config, logger, log);
+	const coexistence = options.coexistence && options.coexistence.enabled !== false ? options.coexistence.service ?? new CoexistenceService({
+		accessToken: options.coexistence.accessToken,
+		appId: options.coexistence.appId,
+		appSecret: options.coexistence.appSecret,
+		graphApiVersion: options.coexistence.graphApiVersion,
+		graphBaseUrl: options.coexistence.graphBaseUrl,
+		fetch: options.coexistence.fetch,
+		credentialProvider: options.coexistence.credentials
+	}) : void 0;
 	const coreContext = {
 		db: database,
 		api: whatsapp,
@@ -497,6 +1300,7 @@ function betterZap(options) {
 		appSecret: config.appSecret,
 		logger,
 		log,
+		database,
 		onMessage: async (ctx) => {
 			const hookContext = {
 				...ctx,
@@ -520,6 +1324,60 @@ function betterZap(options) {
 				log
 			});
 			await webhookHooks.onStatusUpdate(hookContext);
+		},
+		onCoexistenceHistory: async (ctx) => {
+			await webhookHooks.onCoexistenceHistory?.({
+				...ctx,
+				...pluginRuntime.context
+			});
+		},
+		onSmbAppStateSync: async (ctx) => {
+			await webhookHooks.onSmbAppStateSync?.({
+				...ctx,
+				...pluginRuntime.context
+			});
+		},
+		onSmbMessageEcho: async (ctx) => {
+			await webhookHooks.onSmbMessageEcho?.({
+				...ctx,
+				...pluginRuntime.context
+			});
+		},
+		onCoexistenceAccountUpdate: async (ctx) => {
+			await webhookHooks.onCoexistenceAccountUpdate?.({
+				...ctx,
+				...pluginRuntime.context
+			});
+		},
+		onCoexistenceAccountOffboarded: async (ctx) => {
+			await webhookHooks.onCoexistenceAccountOffboarded?.({
+				...ctx,
+				...pluginRuntime.context
+			});
+		},
+		onCoexistenceAccountReconnected: async (ctx) => {
+			await webhookHooks.onCoexistenceAccountReconnected?.({
+				...ctx,
+				...pluginRuntime.context
+			});
+		},
+		onCoexistenceMessageEdit: async (ctx) => {
+			await webhookHooks.onCoexistenceMessageEdit?.({
+				...ctx,
+				...pluginRuntime.context
+			});
+		},
+		onCoexistenceMessageRevoke: async (ctx) => {
+			await webhookHooks.onCoexistenceMessageRevoke?.({
+				...ctx,
+				...pluginRuntime.context
+			});
+		},
+		onCoexistenceUnsupportedMessage: async (ctx) => {
+			await webhookHooks.onCoexistenceUnsupportedMessage?.({
+				...ctx,
+				...pluginRuntime.context
+			});
 		}
 	});
 	const app = new Hono().basePath(basePath);
@@ -527,9 +1385,24 @@ function betterZap(options) {
 		c.set("whatsapp", whatsapp);
 		c.set("store", database.whatsappLog);
 		c.set("logger", log);
+		c.set("coexistence", coexistence);
+		c.set("coexistenceStore", database.coexistence);
+		c.set("subscribeWabaAfterCodeExchange", options.coexistence?.subscribeWabaAfterCodeExchange ?? true);
 		await next();
 	});
 	app.route("/webhook", webhookRouter);
+	if (options.authorizeAppRequest) app.use("*", async (c, next) => {
+		try {
+			if (!await options.authorizeAppRequest?.({
+				request: c.req.raw,
+				env: c.env
+			})) return c.json({ error: "Unauthorized" }, 401);
+			await next();
+		} catch (error) {
+			log.error("app_api.authorization_failed", serializeError(error));
+			return c.json({ error: "Authorization failed" }, 500);
+		}
+	});
 	app.post("/send/text", handleSendText);
 	app.post("/send/template", createSendTemplateHandler(templates));
 	app.post("/send/interactive", handleSendInteractive);
@@ -537,6 +1410,10 @@ function betterZap(options) {
 	app.get("/conversations", handleListConversations);
 	app.get("/conversations/:phone", handleGetConversation);
 	app.get("/conversations/:phone/messages", handleGetMessages);
+	app.post("/coexistence/embedded-signup/callback", handleEmbeddedSignupCallback);
+	app.get("/coexistence/phone-numbers/:phoneNumberId/status", handlePhoneStatus);
+	app.post("/coexistence/phone-numbers/:phoneNumberId/sync/contacts", handleContactsSync);
+	app.post("/coexistence/phone-numbers/:phoneNumberId/sync/history", handleHistorySync);
 	const api = {
 		send: {
 			text: (to, body, opts) => whatsapp.sendText(to, body, opts),