better-zap 0.0.1 → 0.0.3

package/dist/{client-ColqW3Zc.d.mts → client-CRwYOHIG.d.cts}

@@ -317,9 +317,16 @@ interface SendResult {
   messageId?: string;
   error?: string;
   errorCode?: number;
+  code?: string;
   httpStatus?: number;
+  details?: Record<string, any>;
 }
-type Conversation = {
+type FreeformMessageWindow = {
+  isOpen: boolean;
+  lastIncomingMessageAt: string | null;
+  expiresAt: string | null;
+};
+type ConversationRecord = {
   id: string;
   phone: string;
   contactName: string | null;
@@ -331,6 +338,9 @@ type Conversation = {
   messageCount: number;
   lastIncomingMessageAt: string | null;
 };
+type Conversation = ConversationRecord & {
+  freeformMessageWindow: FreeformMessageWindow;
+};
 type UIMessageStatus = "sent" | "delivered" | "read" | "failed";
 type UIMessage = {
   id: string;
@@ -452,19 +462,9 @@ interface WhatsAppLogStore {
    * Progression: sent(1) → delivered(2) → read(3). failed(4) always wins.
    */
   updateStatusIfProgressed(waMessageId: string, newStatus: WhatsAppStatus, updates: Partial<WhatsAppLogRecord>): Promise<boolean>;
-  getConversationById(conversationId: string): Promise<ConversationSummary | null>;
-  getConversationByPhone(phone: string): Promise<ConversationSummary | null>;
-  getConversations(): Promise<Array<{
-    id: string;
-    phone: string;
-    contactName: string | null;
-    unreadCount: number;
-    status: string;
-    lastMessageAt: string;
-    lastMessagePreview: string | null;
-    lastDirection: string;
-    messageCount: number;
-  }>>;
+  getConversationById(conversationId: string): Promise<ConversationRecord | null>;
+  getConversationByPhone(phone: string): Promise<ConversationRecord | null>;
+  getConversations(): Promise<ConversationRecord[]>;
   getMessagesByConversationPaginated(conversationId: string, cursor?: string | null, limit?: number): Promise<Array<{
     id: string;
     phone?: string;
@@ -478,7 +478,7 @@ interface WhatsAppLogStore {
   }>>;
   /**
    * Check if there's a recent outgoing message to this phone within N hours.
-   * Used to approximate Meta's 24h conversation window and for cooldown checks.
+   * Used for consumer-defined cooldown checks.
    */
   hasRecentOutgoingMessage(phone: string, withinHours: number): Promise<boolean>;
 }
@@ -491,6 +491,12 @@ declare class MessageLoggerService {
   private log;
   constructor(store: WhatsAppLogStore, log: Logger, notifier?: MessageLoggerNotifier | undefined);
   private notify;
+  getConversationById(conversationId: string): Promise<Conversation | null>;
+  getConversationByPhone(phone: string): Promise<Conversation | null>;
+  getConversations(): Promise<Conversation[]>;
+  /** @deprecated Prefer `getFreeformMessageWindow()`. */
+  getCustomerCareWindow(phone: string): Promise<FreeformMessageWindow>;
+  getFreeformMessageWindow(phone: string): Promise<FreeformMessageWindow>;
   /**
    * Check if a message with this waMessageId was already processed.
    */
@@ -527,6 +533,7 @@ declare class MessageLoggerService {
     phone: string;
     waMessageId: string;
     content: string;
+    sentAt: string;
     senderName?: string;
     metadata?: Record<string, unknown>;
   }): Promise<void>;
@@ -548,7 +555,7 @@ declare class WhatsAppService {
   private logger;
   private log;
   constructor(config: WhatsAppConfig, logger: MessageLoggerService, log: Logger);
-  /** Send a text message (within 24h service window only). */
+  /** Send a text message within the 24h free-form message window only. */
   sendText(to: string, body: string, logging?: Omit<OutgoingLoggingMetadata, "content">): Promise<SendResult>;
   /** Send a template message (works outside service window). */
   sendTemplate(to: string, templateName: string, languageCode?: string, components?: TemplateComponent[], logging?: OutgoingLoggingMetadata): Promise<SendResult>;
@@ -591,6 +598,7 @@ declare class WhatsAppService {
   sendReaction(to: string, messageId: string, emoji: string): Promise<SendResult>;
   /** Core send method with retry logic (2 retries, exponential backoff). */
   private send;
+  private logSendResult;
   /** Actually performs the network request with retries. */
   private performRequest;
 }
@@ -627,6 +635,7 @@ type TemplateParameterInputMap = {
 type SupportedTemplateParameterType = keyof TemplateParameterInputMap;
 interface TemplateParameterDefinition<TType extends SupportedTemplateParameterType = SupportedTemplateParameterType> {
   name: string;
+  parameterName?: string;
   type: TType;
 }
 type TemplateComponentDefinition = {
@@ -692,6 +701,18 @@ interface ZapClientOptions<TTemplates extends TemplateRegistry = {}> {
    */
   templates?: TTemplates;
 }
+declare class BetterZapClientError extends Error {
+  status: number;
+  code?: string;
+  details?: unknown;
+  body?: unknown;
+  constructor(message: string, options: {
+    status: number;
+    code?: string;
+    details?: unknown;
+    body?: unknown;
+  });
+}
 interface SendTextParams {
   to: string;
   body: string;
@@ -766,4 +787,4 @@ interface ZapClient<TTemplates extends TemplateRegistry = {}> {
 }
 declare function createZapClient<TTemplates extends TemplateRegistry = {}>(options?: ZapClientOptions<TTemplates>): ZapClient<TTemplates>;
 //#endregion
-export { WebhookContact as $, noopLogger as A, InteractiveMediaCarouselCardInput as B, WhatsAppLogStore as C, Logger as D, LogLevel as E, StatusUpdateEvent as F, SendMessageError as G, MessageError as H, SyncEvent as I, TemplateComponent as J, SendMessageResponse as K, WhatsAppConfig as L, ConversationSummary as M, ConversationUpdateEvent as N, LoggerConfig as O, NewMessageEvent as P, WebhookChange as Q, Conversation as R, WhatsAppLogRecord as S, WhatsAppStatus as T, MessageStatus as U, MediaMessage as V, SendInteractiveMediaCarouselData as W, UIMessage as X, TemplateParameter as Y, UIMessageStatus as Z, WhatsAppService as _, TemplateComponentDefinition as a, WhatsAppInteractiveButtonsMessage as at, WHATSAPP_MESSAGE_TYPES as b, TemplateParameterDefinition as c, WhatsAppLocationMessage as ct, TemplateRegistry as d, WebhookEntry as et, defineTemplates as f, OutgoingLoggingMetadata as g, serializeTemplateFromRegistry as h, SupportedTemplateParameterType as i, WhatsAppCarouselCard as it, serializeError as j, createLogger as k, TemplateParameterInputMap as l, WhatsAppTemplateMessage as lt, hasConfiguredTemplates as m, createZapClient as n, WebhookPayload as nt, TemplateDefinition as o, WhatsAppInteractiveListMessage as ot, getTemplateNames as p, SendResult as q, EMPTY_TEMPLATE_REGISTRY as r, WebhookValue as rt, TemplateName as s, WhatsAppInteractiveMediaCarouselMessage as st, ZapClient as t, WebhookError as tt, TemplateParams as u, WhatsAppTextMessage as ut, MessageLoggerNotifier as v, WhatsAppMessageType as w, WhatsAppDirection as x, MessageLoggerService as y, IncomingMessage as z };
+export { UIMessage as $, createLogger as A, ConversationRecord as B, WhatsAppLogRecord as C, LogLevel as D, WhatsAppStatus as E, NewMessageEvent as F, MessageError as G, IncomingMessage as H, StatusUpdateEvent as I, SendMessageError as J, MessageStatus as K, SyncEvent as L, serializeError as M, ConversationSummary as N, Logger as O, ConversationUpdateEvent as P, TemplateParameter as Q, WhatsAppConfig as R, WhatsAppDirection as S, WhatsAppMessageType as T, InteractiveMediaCarouselCardInput as U, FreeformMessageWindow as V, MediaMessage as W, SendResult as X, SendMessageResponse as Y, TemplateComponent as Z, OutgoingLoggingMetadata as _, SupportedTemplateParameterType as a, WebhookPayload as at, MessageLoggerService as b, TemplateName as c, WhatsAppInteractiveButtonsMessage as ct, TemplateParams as d, WhatsAppLocationMessage as dt, UIMessageStatus as et, TemplateRegistry as f, WhatsAppTemplateMessage as ft, serializeTemplateFromRegistry as g, hasConfiguredTemplates as h, EMPTY_TEMPLATE_REGISTRY as i, WebhookError as it, noopLogger as j, LoggerConfig as k, TemplateParameterDefinition as l, WhatsAppInteractiveListMessage as lt, getTemplateNames as m, ZapClient as n, WebhookContact as nt, TemplateComponentDefinition as o, WebhookValue as ot, defineTemplates as p, WhatsAppTextMessage as pt, SendInteractiveMediaCarouselData as q, createZapClient as r, WebhookEntry as rt, TemplateDefinition as s, WhatsAppCarouselCard as st, BetterZapClientError as t, WebhookChange as tt, TemplateParameterInputMap as u, WhatsAppInteractiveMediaCarouselMessage as ut, WhatsAppService as v, WhatsAppLogStore as w, WHATSAPP_MESSAGE_TYPES as x, MessageLoggerNotifier as y, Conversation as z };

package/dist/{client-D5Lgtacj.d.cts → client-s6x3lYea.d.mts}

@@ -317,9 +317,16 @@ interface SendResult {
   messageId?: string;
   error?: string;
   errorCode?: number;
+  code?: string;
   httpStatus?: number;
+  details?: Record<string, any>;
 }
-type Conversation = {
+type FreeformMessageWindow = {
+  isOpen: boolean;
+  lastIncomingMessageAt: string | null;
+  expiresAt: string | null;
+};
+type ConversationRecord = {
   id: string;
   phone: string;
   contactName: string | null;
@@ -331,6 +338,9 @@ type Conversation = {
   messageCount: number;
   lastIncomingMessageAt: string | null;
 };
+type Conversation = ConversationRecord & {
+  freeformMessageWindow: FreeformMessageWindow;
+};
 type UIMessageStatus = "sent" | "delivered" | "read" | "failed";
 type UIMessage = {
   id: string;
@@ -452,19 +462,9 @@ interface WhatsAppLogStore {
    * Progression: sent(1) → delivered(2) → read(3). failed(4) always wins.
    */
   updateStatusIfProgressed(waMessageId: string, newStatus: WhatsAppStatus, updates: Partial<WhatsAppLogRecord>): Promise<boolean>;
-  getConversationById(conversationId: string): Promise<ConversationSummary | null>;
-  getConversationByPhone(phone: string): Promise<ConversationSummary | null>;
-  getConversations(): Promise<Array<{
-    id: string;
-    phone: string;
-    contactName: string | null;
-    unreadCount: number;
-    status: string;
-    lastMessageAt: string;
-    lastMessagePreview: string | null;
-    lastDirection: string;
-    messageCount: number;
-  }>>;
+  getConversationById(conversationId: string): Promise<ConversationRecord | null>;
+  getConversationByPhone(phone: string): Promise<ConversationRecord | null>;
+  getConversations(): Promise<ConversationRecord[]>;
   getMessagesByConversationPaginated(conversationId: string, cursor?: string | null, limit?: number): Promise<Array<{
     id: string;
     phone?: string;
@@ -478,7 +478,7 @@ interface WhatsAppLogStore {
   }>>;
   /**
    * Check if there's a recent outgoing message to this phone within N hours.
-   * Used to approximate Meta's 24h conversation window and for cooldown checks.
+   * Used for consumer-defined cooldown checks.
    */
   hasRecentOutgoingMessage(phone: string, withinHours: number): Promise<boolean>;
 }
@@ -491,6 +491,12 @@ declare class MessageLoggerService {
   private log;
   constructor(store: WhatsAppLogStore, log: Logger, notifier?: MessageLoggerNotifier | undefined);
   private notify;
+  getConversationById(conversationId: string): Promise<Conversation | null>;
+  getConversationByPhone(phone: string): Promise<Conversation | null>;
+  getConversations(): Promise<Conversation[]>;
+  /** @deprecated Prefer `getFreeformMessageWindow()`. */
+  getCustomerCareWindow(phone: string): Promise<FreeformMessageWindow>;
+  getFreeformMessageWindow(phone: string): Promise<FreeformMessageWindow>;
   /**
    * Check if a message with this waMessageId was already processed.
    */
@@ -527,6 +533,7 @@ declare class MessageLoggerService {
     phone: string;
     waMessageId: string;
     content: string;
+    sentAt: string;
     senderName?: string;
     metadata?: Record<string, unknown>;
   }): Promise<void>;
@@ -548,7 +555,7 @@ declare class WhatsAppService {
   private logger;
   private log;
   constructor(config: WhatsAppConfig, logger: MessageLoggerService, log: Logger);
-  /** Send a text message (within 24h service window only). */
+  /** Send a text message within the 24h free-form message window only. */
   sendText(to: string, body: string, logging?: Omit<OutgoingLoggingMetadata, "content">): Promise<SendResult>;
   /** Send a template message (works outside service window). */
   sendTemplate(to: string, templateName: string, languageCode?: string, components?: TemplateComponent[], logging?: OutgoingLoggingMetadata): Promise<SendResult>;
@@ -591,6 +598,7 @@ declare class WhatsAppService {
   sendReaction(to: string, messageId: string, emoji: string): Promise<SendResult>;
   /** Core send method with retry logic (2 retries, exponential backoff). */
   private send;
+  private logSendResult;
   /** Actually performs the network request with retries. */
   private performRequest;
 }
@@ -627,6 +635,7 @@ type TemplateParameterInputMap = {
 type SupportedTemplateParameterType = keyof TemplateParameterInputMap;
 interface TemplateParameterDefinition<TType extends SupportedTemplateParameterType = SupportedTemplateParameterType> {
   name: string;
+  parameterName?: string;
   type: TType;
 }
 type TemplateComponentDefinition = {
@@ -692,6 +701,18 @@ interface ZapClientOptions<TTemplates extends TemplateRegistry = {}> {
    */
   templates?: TTemplates;
 }
+declare class BetterZapClientError extends Error {
+  status: number;
+  code?: string;
+  details?: unknown;
+  body?: unknown;
+  constructor(message: string, options: {
+    status: number;
+    code?: string;
+    details?: unknown;
+    body?: unknown;
+  });
+}
 interface SendTextParams {
   to: string;
   body: string;
@@ -766,4 +787,4 @@ interface ZapClient<TTemplates extends TemplateRegistry = {}> {
 }
 declare function createZapClient<TTemplates extends TemplateRegistry = {}>(options?: ZapClientOptions<TTemplates>): ZapClient<TTemplates>;
 //#endregion
-export { WebhookContact as $, noopLogger as A, InteractiveMediaCarouselCardInput as B, WhatsAppLogStore as C, Logger as D, LogLevel as E, StatusUpdateEvent as F, SendMessageError as G, MessageError as H, SyncEvent as I, TemplateComponent as J, SendMessageResponse as K, WhatsAppConfig as L, ConversationSummary as M, ConversationUpdateEvent as N, LoggerConfig as O, NewMessageEvent as P, WebhookChange as Q, Conversation as R, WhatsAppLogRecord as S, WhatsAppStatus as T, MessageStatus as U, MediaMessage as V, SendInteractiveMediaCarouselData as W, UIMessage as X, TemplateParameter as Y, UIMessageStatus as Z, WhatsAppService as _, TemplateComponentDefinition as a, WhatsAppInteractiveButtonsMessage as at, WHATSAPP_MESSAGE_TYPES as b, TemplateParameterDefinition as c, WhatsAppLocationMessage as ct, TemplateRegistry as d, WebhookEntry as et, defineTemplates as f, OutgoingLoggingMetadata as g, serializeTemplateFromRegistry as h, SupportedTemplateParameterType as i, WhatsAppCarouselCard as it, serializeError as j, createLogger as k, TemplateParameterInputMap as l, WhatsAppTemplateMessage as lt, hasConfiguredTemplates as m, createZapClient as n, WebhookPayload as nt, TemplateDefinition as o, WhatsAppInteractiveListMessage as ot, getTemplateNames as p, SendResult as q, EMPTY_TEMPLATE_REGISTRY as r, WebhookValue as rt, TemplateName as s, WhatsAppInteractiveMediaCarouselMessage as st, ZapClient as t, WebhookError as tt, TemplateParams as u, WhatsAppTextMessage as ut, MessageLoggerNotifier as v, WhatsAppMessageType as w, WhatsAppDirection as x, MessageLoggerService as y, IncomingMessage as z };
+export { UIMessage as $, createLogger as A, ConversationRecord as B, WhatsAppLogRecord as C, LogLevel as D, WhatsAppStatus as E, NewMessageEvent as F, MessageError as G, IncomingMessage as H, StatusUpdateEvent as I, SendMessageError as J, MessageStatus as K, SyncEvent as L, serializeError as M, ConversationSummary as N, Logger as O, ConversationUpdateEvent as P, TemplateParameter as Q, WhatsAppConfig as R, WhatsAppDirection as S, WhatsAppMessageType as T, InteractiveMediaCarouselCardInput as U, FreeformMessageWindow as V, MediaMessage as W, SendResult as X, SendMessageResponse as Y, TemplateComponent as Z, OutgoingLoggingMetadata as _, SupportedTemplateParameterType as a, WebhookPayload as at, MessageLoggerService as b, TemplateName as c, WhatsAppInteractiveButtonsMessage as ct, TemplateParams as d, WhatsAppLocationMessage as dt, UIMessageStatus as et, TemplateRegistry as f, WhatsAppTemplateMessage as ft, serializeTemplateFromRegistry as g, hasConfiguredTemplates as h, EMPTY_TEMPLATE_REGISTRY as i, WebhookError as it, noopLogger as j, LoggerConfig as k, TemplateParameterDefinition as l, WhatsAppInteractiveListMessage as lt, getTemplateNames as m, ZapClient as n, WebhookContact as nt, TemplateComponentDefinition as o, WebhookValue as ot, defineTemplates as p, WhatsAppTextMessage as pt, SendInteractiveMediaCarouselData as q, createZapClient as r, WebhookEntry as rt, TemplateDefinition as s, WhatsAppCarouselCard as st, BetterZapClientError as t, WebhookChange as tt, TemplateParameterInputMap as u, WhatsAppInteractiveMediaCarouselMessage as ut, WhatsAppService as v, WhatsAppLogStore as w, WHATSAPP_MESSAGE_TYPES as x, MessageLoggerNotifier as y, Conversation as z };

package/dist/client.cjs

@@ -1,16 +1,36 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/client.ts
+var BetterZapClientError = class extends Error {
+	status;
+	code;
+	details;
+	body;
+	constructor(message, options) {
+		super(message);
+		this.name = "BetterZapClientError";
+		this.status = options.status;
+		this.code = options.code;
+		this.details = options.details;
+		this.body = options.body;
+	}
+};
 function createZapClient(options) {
 	const baseURL = options?.baseURL ?? (typeof window !== "undefined" ? window.location.origin : "");
 	const basePath = options?.basePath ?? "/api/whatsapp";
 	const fetchFn = options?.fetch ?? fetch;
 	async function request(path, init) {
 		const response = await fetchFn(`${baseURL}${basePath}${path}`, init);
+		const payload = await response.json().catch(() => null);
 		if (!response.ok) {
-			const error = await response.json().catch(() => ({}));
-			throw new Error(error.error || `Request failed: ${response.status}`);
+			const error = payload;
+			throw new BetterZapClientError(error?.error || `Request failed: ${response.status}`, {
+				status: response.status,
+				code: error?.code,
+				details: error?.details,
+				body: payload
+			});
 		}
-		return response.json();
+		return payload;
 	}
 	function post(path, body) {
 		return request(path, {
@@ -34,6 +54,7 @@ function createZapClient(options) {
 		conversations: {
 			list: () => request("/conversations"),
 			get: (phone) => request(`/conversations/${normalizePhone(phone)}`).catch((err) => {
+				if (err instanceof BetterZapClientError && err.status === 404) return null;
 				if (err.message?.includes("Conversation not found")) return null;
 				throw err;
 			}),
@@ -48,4 +69,5 @@ function createZapClient(options) {
 	};
 }
 //#endregion
+exports.BetterZapClientError = BetterZapClientError;
 exports.createZapClient = createZapClient;

package/dist/client.d.cts

@@ -1,2 +1,2 @@
-import { n as createZapClient, t as ZapClient } from "./client-D5Lgtacj.cjs";
-export { ZapClient, createZapClient };
+import { n as ZapClient, r as createZapClient, t as BetterZapClientError } from "./client-CRwYOHIG.cjs";
+export { BetterZapClientError, ZapClient, createZapClient };

package/dist/client.d.mts

@@ -1,2 +1,2 @@
-import { n as createZapClient, t as ZapClient } from "./client-ColqW3Zc.mjs";
-export { ZapClient, createZapClient };
+import { n as ZapClient, r as createZapClient, t as BetterZapClientError } from "./client-s6x3lYea.mjs";
+export { BetterZapClientError, ZapClient, createZapClient };

package/dist/client.mjs

@@ -1,15 +1,35 @@
 //#region src/client.ts
+var BetterZapClientError = class extends Error {
+	status;
+	code;
+	details;
+	body;
+	constructor(message, options) {
+		super(message);
+		this.name = "BetterZapClientError";
+		this.status = options.status;
+		this.code = options.code;
+		this.details = options.details;
+		this.body = options.body;
+	}
+};
 function createZapClient(options) {
 	const baseURL = options?.baseURL ?? (typeof window !== "undefined" ? window.location.origin : "");
 	const basePath = options?.basePath ?? "/api/whatsapp";
 	const fetchFn = options?.fetch ?? fetch;
 	async function request(path, init) {
 		const response = await fetchFn(`${baseURL}${basePath}${path}`, init);
+		const payload = await response.json().catch(() => null);
 		if (!response.ok) {
-			const error = await response.json().catch(() => ({}));
-			throw new Error(error.error || `Request failed: ${response.status}`);
+			const error = payload;
+			throw new BetterZapClientError(error?.error || `Request failed: ${response.status}`, {
+				status: response.status,
+				code: error?.code,
+				details: error?.details,
+				body: payload
+			});
 		}
-		return response.json();
+		return payload;
 	}
 	function post(path, body) {
 		return request(path, {
@@ -33,6 +53,7 @@ function createZapClient(options) {
 		conversations: {
 			list: () => request("/conversations"),
 			get: (phone) => request(`/conversations/${normalizePhone(phone)}`).catch((err) => {
+				if (err instanceof BetterZapClientError && err.status === 404) return null;
 				if (err.message?.includes("Conversation not found")) return null;
 				throw err;
 			}),
@@ -47,4 +68,4 @@ function createZapClient(options) {
 	};
 }
 //#endregion
-export { createZapClient };
+export { BetterZapClientError, createZapClient };

package/dist/index.cjs

@@ -1,5 +1,61 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_client = require("./client.cjs");
+//#region src/freeform-message-window.ts
+const FREEFORM_MESSAGE_WINDOW_MS = 1440 * 60 * 1e3;
+function toTimestamp(value) {
+	if (!value) return null;
+	const timestamp = new Date(value).getTime();
+	return Number.isFinite(timestamp) ? timestamp : null;
+}
+function createFreeformMessageWindow(lastIncomingMessageAt, now = /* @__PURE__ */ new Date()) {
+	const lastIncomingTimestamp = toTimestamp(lastIncomingMessageAt);
+	if (lastIncomingTimestamp == null) return {
+		isOpen: false,
+		lastIncomingMessageAt: null,
+		expiresAt: null
+	};
+	const expiresAtTimestamp = lastIncomingTimestamp + FREEFORM_MESSAGE_WINDOW_MS;
+	return {
+		isOpen: now.getTime() < expiresAtTimestamp,
+		lastIncomingMessageAt,
+		expiresAt: new Date(expiresAtTimestamp).toISOString()
+	};
+}
+function normalizeConversationRecord(record, now = /* @__PURE__ */ new Date()) {
+	const freeformMessageWindow = createFreeformMessageWindow(record.lastIncomingMessageAt, now);
+	return {
+		...record,
+		lastIncomingMessageAt: freeformMessageWindow.lastIncomingMessageAt,
+		freeformMessageWindow
+	};
+}
+function normalizeConversationRecords(records, now = /* @__PURE__ */ new Date()) {
+	return records.map((record) => normalizeConversationRecord(record, now));
+}
+function getLatestIncomingMessageAt(messages) {
+	if (!messages?.length) return null;
+	let latestIncomingMessageAt = null;
+	let latestTimestamp = -Infinity;
+	for (const message of messages) {
+		if (message.direction !== "incoming") continue;
+		const timestamp = toTimestamp(message.sentAt);
+		if (timestamp == null || timestamp <= latestTimestamp) continue;
+		latestIncomingMessageAt = message.sentAt;
+		latestTimestamp = timestamp;
+	}
+	return latestIncomingMessageAt;
+}
+function resolveConversationFreeformMessageWindow(conversation, messages, now = /* @__PURE__ */ new Date()) {
+	const baseLastIncomingMessageAt = conversation?.freeformMessageWindow?.lastIncomingMessageAt ?? conversation?.lastIncomingMessageAt ?? null;
+	const latestIncomingMessageAt = getLatestIncomingMessageAt(messages);
+	if (!latestIncomingMessageAt) return createFreeformMessageWindow(baseLastIncomingMessageAt, now);
+	const baseTimestamp = toTimestamp(baseLastIncomingMessageAt);
+	const latestTimestamp = toTimestamp(latestIncomingMessageAt);
+	if (latestTimestamp == null) return createFreeformMessageWindow(baseLastIncomingMessageAt, now);
+	if (baseTimestamp != null && latestTimestamp <= baseTimestamp) return createFreeformMessageWindow(baseLastIncomingMessageAt, now);
+	return createFreeformMessageWindow(latestIncomingMessageAt, now);
+}
+//#endregion
 //#region src/logger.ts
 const LOG_LEVEL_ORDER = {
 	debug: 0,
@@ -78,6 +134,7 @@ function delay(ms) {
 //#region src/services/whatsapp.service.ts
 const META_API_VERSION = "v25.0";
 const META_BASE_URL = "https://graph.facebook.com";
+const CONTEXT_WINDOW_CLOSED_ERROR = "Free-form message window is closed.";
 var WhatsAppService = class {
 	baseUrl;
 	token;
@@ -91,15 +148,31 @@ var WhatsAppService = class {
 		this.logger = logger;
 		this.log = log;
 	}
-	/** Send a text message (within 24h service window only). */
+	/** Send a text message within the 24h free-form message window only. */
 	async sendText(to, body, logging) {
-		const hasUrl = /https?:\/\/\S+/i.test(body);
+		const normalizedPhone = formatPhone(to);
+		const freeformMessageWindow = await this.logger.getFreeformMessageWindow(normalizedPhone);
+		if (!freeformMessageWindow.isOpen) {
+			const result = {
+				success: false,
+				error: CONTEXT_WINDOW_CLOSED_ERROR,
+				code: "CONTEXT_WINDOW_CLOSED",
+				httpStatus: 409,
+				details: { freeformMessageWindow }
+			};
+			await this.logSendResult(normalizedPhone, logging ? {
+				...logging,
+				messageType: logging.messageType || "bot_reply",
+				content: body
+			} : void 0, result);
+			return result;
+		}
 		const payload = {
 			messaging_product: "whatsapp",
 			recipient_type: "individual",
-			to: formatPhone(to),
+			to: normalizedPhone,
 			type: "text",
-			text: hasUrl ? {
+			text: /https?:\/\/\S+/i.test(body) ? {
 				body,
 				preview_url: true
 			} : { body }
@@ -311,20 +384,24 @@ var WhatsAppService = class {
 			};
 		}
 		const result = await this.performRequest(payload, retries);
-		if (logging) try {
+		await this.logSendResult(payload.to, logging, result, payload.type === "template" ? payload.template.name : void 0);
+		return result;
+	}
+	async logSendResult(phone, logging, result, templateName) {
+		if (!logging) return;
+		try {
 			await this.logger.logOutgoing({
-				phone: payload.to,
+				phone,
 				userId: logging.userId,
 				messageType: logging.messageType,
 				content: logging.content,
-				templateName: payload.type === "template" ? payload.template.name : void 0,
+				templateName,
 				result,
 				metadata: logging.metadata
 			});
 		} catch (logError) {
 			this.log.error("whatsapp.log_failed", serializeError(logError));
 		}
-		return result;
 	}
 	/** Actually performs the network request with retries. */
 	async performRequest(payload, retries) {
@@ -406,6 +483,24 @@ var MessageLoggerService = class {
 			this.log.error("message_logger.sync_notify_failed", serializeError(err));
 		}
 	}
+	async getConversationById(conversationId) {
+		const conversation = await this.store.getConversationById(conversationId);
+		return conversation ? normalizeConversationRecord(conversation) : null;
+	}
+	async getConversationByPhone(phone) {
+		const conversation = await this.store.getConversationByPhone(phone);
+		return conversation ? normalizeConversationRecord(conversation) : null;
+	}
+	async getConversations() {
+		return normalizeConversationRecords(await this.store.getConversations());
+	}
+	/** @deprecated Prefer `getFreeformMessageWindow()`. */
+	async getCustomerCareWindow(phone) {
+		return this.getFreeformMessageWindow(phone);
+	}
+	async getFreeformMessageWindow(phone) {
+		return (await this.getConversationByPhone(phone))?.freeformMessageWindow ?? createFreeformMessageWindow(null);
+	}
 	/**
 	* Check if a message with this waMessageId was already processed.
 	*/
@@ -429,7 +524,7 @@ var MessageLoggerService = class {
 			sentAt: (/* @__PURE__ */ new Date()).toISOString(),
 			metadata: params.metadata
 		});
-		const conversation = await this.store.getConversationById(inserted.conversationId);
+		const conversation = await this.getConversationById(inserted.conversationId);
 		if (conversation) await this.notify({
 			type: "NEW_MESSAGE",
 			message: inserted,
@@ -481,9 +576,9 @@ var MessageLoggerService = class {
 			content: params.content,
 			status: "delivered",
 			metadata: params.metadata,
-			sentAt: (/* @__PURE__ */ new Date()).toISOString()
+			sentAt: params.sentAt
 		});
-		const conversation = await this.store.getConversationById(inserted.conversationId);
+		const conversation = await this.getConversationById(inserted.conversationId);
 		if (conversation) await this.notify({
 			type: "NEW_MESSAGE",
 			message: inserted,
@@ -528,53 +623,69 @@ function serializeTemplateFromRegistry(templates, templateName, options) {
 	};
 }
 function serializeTemplateParameter(parameter, value) {
+	const metaParameterName = parameter.parameterName ? { parameter_name: parameter.parameterName } : {};
 	switch (parameter.type) {
 		case "text": return {
 			type: "text",
+			...metaParameterName,
 			text: value
 		};
 		case "payload": return {
 			type: "payload",
+			...metaParameterName,
 			payload: value
 		};
 		case "location": return {
 			type: "location",
+			...metaParameterName,
 			location: value
 		};
 		case "image": return {
 			type: "image",
+			...metaParameterName,
 			image: value
 		};
 		case "video": return {
 			type: "video",
+			...metaParameterName,
 			video: value
 		};
 		case "document": return {
 			type: "document",
+			...metaParameterName,
 			document: value
 		};
 		case "currency": return {
 			type: "currency",
+			...metaParameterName,
 			currency: value
 		};
 		case "date_time": return {
 			type: "date_time",
+			...metaParameterName,
 			date_time: value
 		};
 	}
 }
 //#endregion
+exports.BetterZapClientError = require_client.BetterZapClientError;
 exports.EMPTY_TEMPLATE_REGISTRY = EMPTY_TEMPLATE_REGISTRY;
+exports.FREEFORM_MESSAGE_WINDOW_MS = FREEFORM_MESSAGE_WINDOW_MS;
 exports.MessageLoggerService = MessageLoggerService;
 exports.WHATSAPP_MESSAGE_TYPES = WHATSAPP_MESSAGE_TYPES;
 exports.WhatsAppService = WhatsAppService;
+exports.createFreeformMessageWindow = createFreeformMessageWindow;
 exports.createLogger = createLogger;
 exports.createZapClient = require_client.createZapClient;
 exports.defineTemplates = defineTemplates;
 exports.delay = delay;
 exports.formatPhone = formatPhone;
+exports.getLatestIncomingMessageAt = getLatestIncomingMessageAt;
 exports.getTemplateNames = getTemplateNames;
 exports.hasConfiguredTemplates = hasConfiguredTemplates;
 exports.noopLogger = noopLogger;
+exports.normalizeConversationRecord = normalizeConversationRecord;
+exports.normalizeConversationRecords = normalizeConversationRecords;
+exports.resolveConversationFreeformMessageWindow = resolveConversationFreeformMessageWindow;
 exports.serializeError = serializeError;
 exports.serializeTemplateFromRegistry = serializeTemplateFromRegistry;

package/dist/index.d.cts

@@ -1,5 +1,13 @@
-import { $ as WebhookContact, A as noopLogger, B as InteractiveMediaCarouselCardInput, C as WhatsAppLogStore, D as Logger, E as LogLevel, F as StatusUpdateEvent, G as SendMessageError, H as MessageError, I as SyncEvent, J as TemplateComponent, K as SendMessageResponse, L as WhatsAppConfig, M as ConversationSummary, N as ConversationUpdateEvent, O as LoggerConfig, P as NewMessageEvent, Q as WebhookChange, R as Conversation, S as WhatsAppLogRecord, T as WhatsAppStatus, U as MessageStatus, V as MediaMessage, W as SendInteractiveMediaCarouselData, X as UIMessage, Y as TemplateParameter, Z as UIMessageStatus, _ as WhatsAppService, a as TemplateComponentDefinition, at as WhatsAppInteractiveButtonsMessage, b as WHATSAPP_MESSAGE_TYPES, c as TemplateParameterDefinition, ct as WhatsAppLocationMessage, d as TemplateRegistry, et as WebhookEntry, f as defineTemplates, g as OutgoingLoggingMetadata, h as serializeTemplateFromRegistry, i as SupportedTemplateParameterType, it as WhatsAppCarouselCard, j as serializeError, k as createLogger, l as TemplateParameterInputMap, lt as WhatsAppTemplateMessage, m as hasConfiguredTemplates, n as createZapClient, nt as WebhookPayload, o as TemplateDefinition, ot as WhatsAppInteractiveListMessage, p as getTemplateNames, q as SendResult, r as EMPTY_TEMPLATE_REGISTRY, rt as WebhookValue, s as TemplateName, st as WhatsAppInteractiveMediaCarouselMessage, t as ZapClient, tt as WebhookError, u as TemplateParams, ut as WhatsAppTextMessage, v as MessageLoggerNotifier, w as WhatsAppMessageType, x as WhatsAppDirection, y as MessageLoggerService, z as IncomingMessage } from "./client-D5Lgtacj.cjs";
+import { $ as UIMessage, A as createLogger, B as ConversationRecord, C as WhatsAppLogRecord, D as LogLevel, E as WhatsAppStatus, F as NewMessageEvent, G as MessageError, H as IncomingMessage, I as StatusUpdateEvent, J as SendMessageError, K as MessageStatus, L as SyncEvent, M as serializeError, N as ConversationSummary, O as Logger, P as ConversationUpdateEvent, Q as TemplateParameter, R as WhatsAppConfig, S as WhatsAppDirection, T as WhatsAppMessageType, U as InteractiveMediaCarouselCardInput, V as FreeformMessageWindow, W as MediaMessage, X as SendResult, Y as SendMessageResponse, Z as TemplateComponent, _ as OutgoingLoggingMetadata, a as SupportedTemplateParameterType, at as WebhookPayload, b as MessageLoggerService, c as TemplateName, ct as WhatsAppInteractiveButtonsMessage, d as TemplateParams, dt as WhatsAppLocationMessage, et as UIMessageStatus, f as TemplateRegistry, ft as WhatsAppTemplateMessage, g as serializeTemplateFromRegistry, h as hasConfiguredTemplates, i as EMPTY_TEMPLATE_REGISTRY, it as WebhookError, j as noopLogger, k as LoggerConfig, l as TemplateParameterDefinition, lt as WhatsAppInteractiveListMessage, m as getTemplateNames, n as ZapClient, nt as WebhookContact, o as TemplateComponentDefinition, ot as WebhookValue, p as defineTemplates, pt as WhatsAppTextMessage, q as SendInteractiveMediaCarouselData, r as createZapClient, rt as WebhookEntry, s as TemplateDefinition, st as WhatsAppCarouselCard, t as BetterZapClientError, tt as WebhookChange, u as TemplateParameterInputMap, ut as WhatsAppInteractiveMediaCarouselMessage, v as WhatsAppService, w as WhatsAppLogStore, x as WHATSAPP_MESSAGE_TYPES, y as MessageLoggerNotifier, z as Conversation } from "./client-CRwYOHIG.cjs";
 
+//#region src/freeform-message-window.d.ts
+declare const FREEFORM_MESSAGE_WINDOW_MS: number;
+declare function createFreeformMessageWindow(lastIncomingMessageAt: string | null, now?: Date): FreeformMessageWindow;
+declare function normalizeConversationRecord(record: ConversationRecord, now?: Date): Conversation;
+declare function normalizeConversationRecords(records: ConversationRecord[], now?: Date): Conversation[];
+declare function getLatestIncomingMessageAt(messages: UIMessage[] | undefined): string | null;
+declare function resolveConversationFreeformMessageWindow(conversation: Pick<Conversation, "freeformMessageWindow" | "lastIncomingMessageAt"> | null | undefined, messages?: UIMessage[], now?: Date): FreeformMessageWindow;
+//#endregion
 //#region src/events.d.ts
 type MessageContext = {
   message: IncomingMessage;
@@ -120,4 +128,4 @@ interface BetterZapApi<TTemplates extends TemplateRegistry = {}> {
   };
 }
 //#endregion
-export { type Awaitable, type BetterZapApi, type BetterZapContext, type BetterZapCoreConfig, type BetterZapCoreContext, type BetterZapCoreServices, type BetterZapDatabase, type BetterZapPlugin, type BetterZapPluginInitContext, type BetterZapPluginInitResult, type BetterZapServices, type Conversation, type ConversationSummary, type ConversationUpdateEvent, EMPTY_TEMPLATE_REGISTRY, type IncomingMessage, type InferBetterZapPluginContext, type InferBetterZapPluginServices, type InteractiveMediaCarouselCardInput, type LogLevel, type Logger, type LoggerConfig, type MediaMessage, type MessageContext, type MessageError, type MessageLoggerNotifier, MessageLoggerService, type MessageStatus, type NewMessageEvent, type OutgoingLoggingMetadata, type SendInteractiveMediaCarouselData, type SendMessageError, type SendMessageResponse, type SendResult, type StatusContext, type StatusUpdateEvent, type SupportedTemplateParameterType, type SyncEvent, type TemplateComponent, type TemplateComponentDefinition, type TemplateDefinition, type TemplateName, type TemplateParameter, type TemplateParameterDefinition, type TemplateParameterInputMap, type TemplateParams, type TemplateRegistry, type UIMessage, type UIMessageStatus, WHATSAPP_MESSAGE_TYPES, type WebhookChange, type WebhookContact, type WebhookEntry, type WebhookError, type WebhookPayload, type WebhookValue, type WhatsAppCarouselCard, type WhatsAppConfig, type WhatsAppDirection, type WhatsAppInteractiveButtonsMessage, type WhatsAppInteractiveListMessage, type WhatsAppInteractiveMediaCarouselMessage, type WhatsAppLocationMessage, type WhatsAppLogRecord, type WhatsAppLogStore, type WhatsAppMessageType, WhatsAppService, type WhatsAppStatus, type WhatsAppTemplateMessage, type WhatsAppTextMessage, type ZapClient, createLogger, createZapClient, defineTemplates, delay, formatPhone, getTemplateNames, hasConfiguredTemplates, noopLogger, serializeError, serializeTemplateFromRegistry };
+export { type Awaitable, type BetterZapApi, BetterZapClientError, type BetterZapContext, type BetterZapCoreConfig, type BetterZapCoreContext, type BetterZapCoreServices, type BetterZapDatabase, type BetterZapPlugin, type BetterZapPluginInitContext, type BetterZapPluginInitResult, type BetterZapServices, type Conversation, type ConversationRecord, type ConversationSummary, type ConversationUpdateEvent, EMPTY_TEMPLATE_REGISTRY, FREEFORM_MESSAGE_WINDOW_MS, type FreeformMessageWindow, type IncomingMessage, type InferBetterZapPluginContext, type InferBetterZapPluginServices, type InteractiveMediaCarouselCardInput, type LogLevel, type Logger, type LoggerConfig, type MediaMessage, type MessageContext, type MessageError, type MessageLoggerNotifier, MessageLoggerService, type MessageStatus, type NewMessageEvent, type OutgoingLoggingMetadata, type SendInteractiveMediaCarouselData, type SendMessageError, type SendMessageResponse, type SendResult, type StatusContext, type StatusUpdateEvent, type SupportedTemplateParameterType, type SyncEvent, type TemplateComponent, type TemplateComponentDefinition, type TemplateDefinition, type TemplateName, type TemplateParameter, type TemplateParameterDefinition, type TemplateParameterInputMap, type TemplateParams, type TemplateRegistry, type UIMessage, type UIMessageStatus, WHATSAPP_MESSAGE_TYPES, type WebhookChange, type WebhookContact, type WebhookEntry, type WebhookError, type WebhookPayload, type WebhookValue, type WhatsAppCarouselCard, type WhatsAppConfig, type WhatsAppDirection, type WhatsAppInteractiveButtonsMessage, type WhatsAppInteractiveListMessage, type WhatsAppInteractiveMediaCarouselMessage, type WhatsAppLocationMessage, type WhatsAppLogRecord, type WhatsAppLogStore, type WhatsAppMessageType, WhatsAppService, type WhatsAppStatus, type WhatsAppTemplateMessage, type WhatsAppTextMessage, type ZapClient, createFreeformMessageWindow, createLogger, createZapClient, defineTemplates, delay, formatPhone, getLatestIncomingMessageAt, getTemplateNames, hasConfiguredTemplates, noopLogger, normalizeConversationRecord, normalizeConversationRecords, resolveConversationFreeformMessageWindow, serializeError, serializeTemplateFromRegistry };

package/dist/index.d.mts

@@ -1,5 +1,13 @@
-import { $ as WebhookContact, A as noopLogger, B as InteractiveMediaCarouselCardInput, C as WhatsAppLogStore, D as Logger, E as LogLevel, F as StatusUpdateEvent, G as SendMessageError, H as MessageError, I as SyncEvent, J as TemplateComponent, K as SendMessageResponse, L as WhatsAppConfig, M as ConversationSummary, N as ConversationUpdateEvent, O as LoggerConfig, P as NewMessageEvent, Q as WebhookChange, R as Conversation, S as WhatsAppLogRecord, T as WhatsAppStatus, U as MessageStatus, V as MediaMessage, W as SendInteractiveMediaCarouselData, X as UIMessage, Y as TemplateParameter, Z as UIMessageStatus, _ as WhatsAppService, a as TemplateComponentDefinition, at as WhatsAppInteractiveButtonsMessage, b as WHATSAPP_MESSAGE_TYPES, c as TemplateParameterDefinition, ct as WhatsAppLocationMessage, d as TemplateRegistry, et as WebhookEntry, f as defineTemplates, g as OutgoingLoggingMetadata, h as serializeTemplateFromRegistry, i as SupportedTemplateParameterType, it as WhatsAppCarouselCard, j as serializeError, k as createLogger, l as TemplateParameterInputMap, lt as WhatsAppTemplateMessage, m as hasConfiguredTemplates, n as createZapClient, nt as WebhookPayload, o as TemplateDefinition, ot as WhatsAppInteractiveListMessage, p as getTemplateNames, q as SendResult, r as EMPTY_TEMPLATE_REGISTRY, rt as WebhookValue, s as TemplateName, st as WhatsAppInteractiveMediaCarouselMessage, t as ZapClient, tt as WebhookError, u as TemplateParams, ut as WhatsAppTextMessage, v as MessageLoggerNotifier, w as WhatsAppMessageType, x as WhatsAppDirection, y as MessageLoggerService, z as IncomingMessage } from "./client-ColqW3Zc.mjs";
+import { $ as UIMessage, A as createLogger, B as ConversationRecord, C as WhatsAppLogRecord, D as LogLevel, E as WhatsAppStatus, F as NewMessageEvent, G as MessageError, H as IncomingMessage, I as StatusUpdateEvent, J as SendMessageError, K as MessageStatus, L as SyncEvent, M as serializeError, N as ConversationSummary, O as Logger, P as ConversationUpdateEvent, Q as TemplateParameter, R as WhatsAppConfig, S as WhatsAppDirection, T as WhatsAppMessageType, U as InteractiveMediaCarouselCardInput, V as FreeformMessageWindow, W as MediaMessage, X as SendResult, Y as SendMessageResponse, Z as TemplateComponent, _ as OutgoingLoggingMetadata, a as SupportedTemplateParameterType, at as WebhookPayload, b as MessageLoggerService, c as TemplateName, ct as WhatsAppInteractiveButtonsMessage, d as TemplateParams, dt as WhatsAppLocationMessage, et as UIMessageStatus, f as TemplateRegistry, ft as WhatsAppTemplateMessage, g as serializeTemplateFromRegistry, h as hasConfiguredTemplates, i as EMPTY_TEMPLATE_REGISTRY, it as WebhookError, j as noopLogger, k as LoggerConfig, l as TemplateParameterDefinition, lt as WhatsAppInteractiveListMessage, m as getTemplateNames, n as ZapClient, nt as WebhookContact, o as TemplateComponentDefinition, ot as WebhookValue, p as defineTemplates, pt as WhatsAppTextMessage, q as SendInteractiveMediaCarouselData, r as createZapClient, rt as WebhookEntry, s as TemplateDefinition, st as WhatsAppCarouselCard, t as BetterZapClientError, tt as WebhookChange, u as TemplateParameterInputMap, ut as WhatsAppInteractiveMediaCarouselMessage, v as WhatsAppService, w as WhatsAppLogStore, x as WHATSAPP_MESSAGE_TYPES, y as MessageLoggerNotifier, z as Conversation } from "./client-s6x3lYea.mjs";
 
+//#region src/freeform-message-window.d.ts
+declare const FREEFORM_MESSAGE_WINDOW_MS: number;
+declare function createFreeformMessageWindow(lastIncomingMessageAt: string | null, now?: Date): FreeformMessageWindow;
+declare function normalizeConversationRecord(record: ConversationRecord, now?: Date): Conversation;
+declare function normalizeConversationRecords(records: ConversationRecord[], now?: Date): Conversation[];
+declare function getLatestIncomingMessageAt(messages: UIMessage[] | undefined): string | null;
+declare function resolveConversationFreeformMessageWindow(conversation: Pick<Conversation, "freeformMessageWindow" | "lastIncomingMessageAt"> | null | undefined, messages?: UIMessage[], now?: Date): FreeformMessageWindow;
+//#endregion
 //#region src/events.d.ts
 type MessageContext = {
   message: IncomingMessage;
@@ -120,4 +128,4 @@ interface BetterZapApi<TTemplates extends TemplateRegistry = {}> {
   };
 }
 //#endregion
-export { type Awaitable, type BetterZapApi, type BetterZapContext, type BetterZapCoreConfig, type BetterZapCoreContext, type BetterZapCoreServices, type BetterZapDatabase, type BetterZapPlugin, type BetterZapPluginInitContext, type BetterZapPluginInitResult, type BetterZapServices, type Conversation, type ConversationSummary, type ConversationUpdateEvent, EMPTY_TEMPLATE_REGISTRY, type IncomingMessage, type InferBetterZapPluginContext, type InferBetterZapPluginServices, type InteractiveMediaCarouselCardInput, type LogLevel, type Logger, type LoggerConfig, type MediaMessage, type MessageContext, type MessageError, type MessageLoggerNotifier, MessageLoggerService, type MessageStatus, type NewMessageEvent, type OutgoingLoggingMetadata, type SendInteractiveMediaCarouselData, type SendMessageError, type SendMessageResponse, type SendResult, type StatusContext, type StatusUpdateEvent, type SupportedTemplateParameterType, type SyncEvent, type TemplateComponent, type TemplateComponentDefinition, type TemplateDefinition, type TemplateName, type TemplateParameter, type TemplateParameterDefinition, type TemplateParameterInputMap, type TemplateParams, type TemplateRegistry, type UIMessage, type UIMessageStatus, WHATSAPP_MESSAGE_TYPES, type WebhookChange, type WebhookContact, type WebhookEntry, type WebhookError, type WebhookPayload, type WebhookValue, type WhatsAppCarouselCard, type WhatsAppConfig, type WhatsAppDirection, type WhatsAppInteractiveButtonsMessage, type WhatsAppInteractiveListMessage, type WhatsAppInteractiveMediaCarouselMessage, type WhatsAppLocationMessage, type WhatsAppLogRecord, type WhatsAppLogStore, type WhatsAppMessageType, WhatsAppService, type WhatsAppStatus, type WhatsAppTemplateMessage, type WhatsAppTextMessage, type ZapClient, createLogger, createZapClient, defineTemplates, delay, formatPhone, getTemplateNames, hasConfiguredTemplates, noopLogger, serializeError, serializeTemplateFromRegistry };
+export { type Awaitable, type BetterZapApi, BetterZapClientError, type BetterZapContext, type BetterZapCoreConfig, type BetterZapCoreContext, type BetterZapCoreServices, type BetterZapDatabase, type BetterZapPlugin, type BetterZapPluginInitContext, type BetterZapPluginInitResult, type BetterZapServices, type Conversation, type ConversationRecord, type ConversationSummary, type ConversationUpdateEvent, EMPTY_TEMPLATE_REGISTRY, FREEFORM_MESSAGE_WINDOW_MS, type FreeformMessageWindow, type IncomingMessage, type InferBetterZapPluginContext, type InferBetterZapPluginServices, type InteractiveMediaCarouselCardInput, type LogLevel, type Logger, type LoggerConfig, type MediaMessage, type MessageContext, type MessageError, type MessageLoggerNotifier, MessageLoggerService, type MessageStatus, type NewMessageEvent, type OutgoingLoggingMetadata, type SendInteractiveMediaCarouselData, type SendMessageError, type SendMessageResponse, type SendResult, type StatusContext, type StatusUpdateEvent, type SupportedTemplateParameterType, type SyncEvent, type TemplateComponent, type TemplateComponentDefinition, type TemplateDefinition, type TemplateName, type TemplateParameter, type TemplateParameterDefinition, type TemplateParameterInputMap, type TemplateParams, type TemplateRegistry, type UIMessage, type UIMessageStatus, WHATSAPP_MESSAGE_TYPES, type WebhookChange, type WebhookContact, type WebhookEntry, type WebhookError, type WebhookPayload, type WebhookValue, type WhatsAppCarouselCard, type WhatsAppConfig, type WhatsAppDirection, type WhatsAppInteractiveButtonsMessage, type WhatsAppInteractiveListMessage, type WhatsAppInteractiveMediaCarouselMessage, type WhatsAppLocationMessage, type WhatsAppLogRecord, type WhatsAppLogStore, type WhatsAppMessageType, WhatsAppService, type WhatsAppStatus, type WhatsAppTemplateMessage, type WhatsAppTextMessage, type ZapClient, createFreeformMessageWindow, createLogger, createZapClient, defineTemplates, delay, formatPhone, getLatestIncomingMessageAt, getTemplateNames, hasConfiguredTemplates, noopLogger, normalizeConversationRecord, normalizeConversationRecords, resolveConversationFreeformMessageWindow, serializeError, serializeTemplateFromRegistry };

package/dist/index.mjs

@@ -1,4 +1,60 @@
-import { createZapClient } from "./client.mjs";
+import { BetterZapClientError, createZapClient } from "./client.mjs";
+//#region src/freeform-message-window.ts
+const FREEFORM_MESSAGE_WINDOW_MS = 1440 * 60 * 1e3;
+function toTimestamp(value) {
+	if (!value) return null;
+	const timestamp = new Date(value).getTime();
+	return Number.isFinite(timestamp) ? timestamp : null;
+}
+function createFreeformMessageWindow(lastIncomingMessageAt, now = /* @__PURE__ */ new Date()) {
+	const lastIncomingTimestamp = toTimestamp(lastIncomingMessageAt);
+	if (lastIncomingTimestamp == null) return {
+		isOpen: false,
+		lastIncomingMessageAt: null,
+		expiresAt: null
+	};
+	const expiresAtTimestamp = lastIncomingTimestamp + FREEFORM_MESSAGE_WINDOW_MS;
+	return {
+		isOpen: now.getTime() < expiresAtTimestamp,
+		lastIncomingMessageAt,
+		expiresAt: new Date(expiresAtTimestamp).toISOString()
+	};
+}
+function normalizeConversationRecord(record, now = /* @__PURE__ */ new Date()) {
+	const freeformMessageWindow = createFreeformMessageWindow(record.lastIncomingMessageAt, now);
+	return {
+		...record,
+		lastIncomingMessageAt: freeformMessageWindow.lastIncomingMessageAt,
+		freeformMessageWindow
+	};
+}
+function normalizeConversationRecords(records, now = /* @__PURE__ */ new Date()) {
+	return records.map((record) => normalizeConversationRecord(record, now));
+}
+function getLatestIncomingMessageAt(messages) {
+	if (!messages?.length) return null;
+	let latestIncomingMessageAt = null;
+	let latestTimestamp = -Infinity;
+	for (const message of messages) {
+		if (message.direction !== "incoming") continue;
+		const timestamp = toTimestamp(message.sentAt);
+		if (timestamp == null || timestamp <= latestTimestamp) continue;
+		latestIncomingMessageAt = message.sentAt;
+		latestTimestamp = timestamp;
+	}
+	return latestIncomingMessageAt;
+}
+function resolveConversationFreeformMessageWindow(conversation, messages, now = /* @__PURE__ */ new Date()) {
+	const baseLastIncomingMessageAt = conversation?.freeformMessageWindow?.lastIncomingMessageAt ?? conversation?.lastIncomingMessageAt ?? null;
+	const latestIncomingMessageAt = getLatestIncomingMessageAt(messages);
+	if (!latestIncomingMessageAt) return createFreeformMessageWindow(baseLastIncomingMessageAt, now);
+	const baseTimestamp = toTimestamp(baseLastIncomingMessageAt);
+	const latestTimestamp = toTimestamp(latestIncomingMessageAt);
+	if (latestTimestamp == null) return createFreeformMessageWindow(baseLastIncomingMessageAt, now);
+	if (baseTimestamp != null && latestTimestamp <= baseTimestamp) return createFreeformMessageWindow(baseLastIncomingMessageAt, now);
+	return createFreeformMessageWindow(latestIncomingMessageAt, now);
+}
+//#endregion
 //#region src/logger.ts
 const LOG_LEVEL_ORDER = {
 	debug: 0,
@@ -77,6 +133,7 @@ function delay(ms) {
 //#region src/services/whatsapp.service.ts
 const META_API_VERSION = "v25.0";
 const META_BASE_URL = "https://graph.facebook.com";
+const CONTEXT_WINDOW_CLOSED_ERROR = "Free-form message window is closed.";
 var WhatsAppService = class {
 	baseUrl;
 	token;
@@ -90,15 +147,31 @@ var WhatsAppService = class {
 		this.logger = logger;
 		this.log = log;
 	}
-	/** Send a text message (within 24h service window only). */
+	/** Send a text message within the 24h free-form message window only. */
 	async sendText(to, body, logging) {
-		const hasUrl = /https?:\/\/\S+/i.test(body);
+		const normalizedPhone = formatPhone(to);
+		const freeformMessageWindow = await this.logger.getFreeformMessageWindow(normalizedPhone);
+		if (!freeformMessageWindow.isOpen) {
+			const result = {
+				success: false,
+				error: CONTEXT_WINDOW_CLOSED_ERROR,
+				code: "CONTEXT_WINDOW_CLOSED",
+				httpStatus: 409,
+				details: { freeformMessageWindow }
+			};
+			await this.logSendResult(normalizedPhone, logging ? {
+				...logging,
+				messageType: logging.messageType || "bot_reply",
+				content: body
+			} : void 0, result);
+			return result;
+		}
 		const payload = {
 			messaging_product: "whatsapp",
 			recipient_type: "individual",
-			to: formatPhone(to),
+			to: normalizedPhone,
 			type: "text",
-			text: hasUrl ? {
+			text: /https?:\/\/\S+/i.test(body) ? {
 				body,
 				preview_url: true
 			} : { body }
@@ -310,20 +383,24 @@ var WhatsAppService = class {
 			};
 		}
 		const result = await this.performRequest(payload, retries);
-		if (logging) try {
+		await this.logSendResult(payload.to, logging, result, payload.type === "template" ? payload.template.name : void 0);
+		return result;
+	}
+	async logSendResult(phone, logging, result, templateName) {
+		if (!logging) return;
+		try {
 			await this.logger.logOutgoing({
-				phone: payload.to,
+				phone,
 				userId: logging.userId,
 				messageType: logging.messageType,
 				content: logging.content,
-				templateName: payload.type === "template" ? payload.template.name : void 0,
+				templateName,
 				result,
 				metadata: logging.metadata
 			});
 		} catch (logError) {
 			this.log.error("whatsapp.log_failed", serializeError(logError));
 		}
-		return result;
 	}
 	/** Actually performs the network request with retries. */
 	async performRequest(payload, retries) {
@@ -405,6 +482,24 @@ var MessageLoggerService = class {
 			this.log.error("message_logger.sync_notify_failed", serializeError(err));
 		}
 	}
+	async getConversationById(conversationId) {
+		const conversation = await this.store.getConversationById(conversationId);
+		return conversation ? normalizeConversationRecord(conversation) : null;
+	}
+	async getConversationByPhone(phone) {
+		const conversation = await this.store.getConversationByPhone(phone);
+		return conversation ? normalizeConversationRecord(conversation) : null;
+	}
+	async getConversations() {
+		return normalizeConversationRecords(await this.store.getConversations());
+	}
+	/** @deprecated Prefer `getFreeformMessageWindow()`. */
+	async getCustomerCareWindow(phone) {
+		return this.getFreeformMessageWindow(phone);
+	}
+	async getFreeformMessageWindow(phone) {
+		return (await this.getConversationByPhone(phone))?.freeformMessageWindow ?? createFreeformMessageWindow(null);
+	}
 	/**
 	* Check if a message with this waMessageId was already processed.
 	*/
@@ -428,7 +523,7 @@ var MessageLoggerService = class {
 			sentAt: (/* @__PURE__ */ new Date()).toISOString(),
 			metadata: params.metadata
 		});
-		const conversation = await this.store.getConversationById(inserted.conversationId);
+		const conversation = await this.getConversationById(inserted.conversationId);
 		if (conversation) await this.notify({
 			type: "NEW_MESSAGE",
 			message: inserted,
@@ -480,9 +575,9 @@ var MessageLoggerService = class {
 			content: params.content,
 			status: "delivered",
 			metadata: params.metadata,
-			sentAt: (/* @__PURE__ */ new Date()).toISOString()
+			sentAt: params.sentAt
 		});
-		const conversation = await this.store.getConversationById(inserted.conversationId);
+		const conversation = await this.getConversationById(inserted.conversationId);
 		if (conversation) await this.notify({
 			type: "NEW_MESSAGE",
 			message: inserted,
@@ -527,40 +622,49 @@ function serializeTemplateFromRegistry(templates, templateName, options) {
 	};
 }
 function serializeTemplateParameter(parameter, value) {
+	const metaParameterName = parameter.parameterName ? { parameter_name: parameter.parameterName } : {};
 	switch (parameter.type) {
 		case "text": return {
 			type: "text",
+			...metaParameterName,
 			text: value
 		};
 		case "payload": return {
 			type: "payload",
+			...metaParameterName,
 			payload: value
 		};
 		case "location": return {
 			type: "location",
+			...metaParameterName,
 			location: value
 		};
 		case "image": return {
 			type: "image",
+			...metaParameterName,
 			image: value
 		};
 		case "video": return {
 			type: "video",
+			...metaParameterName,
 			video: value
 		};
 		case "document": return {
 			type: "document",
+			...metaParameterName,
 			document: value
 		};
 		case "currency": return {
 			type: "currency",
+			...metaParameterName,
 			currency: value
 		};
 		case "date_time": return {
 			type: "date_time",
+			...metaParameterName,
 			date_time: value
 		};
 	}
 }
 //#endregion
-export { EMPTY_TEMPLATE_REGISTRY, MessageLoggerService, WHATSAPP_MESSAGE_TYPES, WhatsAppService, createLogger, createZapClient, defineTemplates, delay, formatPhone, getTemplateNames, hasConfiguredTemplates, noopLogger, serializeError, serializeTemplateFromRegistry };
+export { BetterZapClientError, EMPTY_TEMPLATE_REGISTRY, FREEFORM_MESSAGE_WINDOW_MS, MessageLoggerService, WHATSAPP_MESSAGE_TYPES, WhatsAppService, createFreeformMessageWindow, createLogger, createZapClient, defineTemplates, delay, formatPhone, getLatestIncomingMessageAt, getTemplateNames, hasConfiguredTemplates, noopLogger, normalizeConversationRecord, normalizeConversationRecords, resolveConversationFreeformMessageWindow, serializeError, serializeTemplateFromRegistry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-zap",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Framework-agnostic Better Zap core for typed WhatsApp integrations.",
   "license": "ISC",
   "type": "module",
@@ -34,7 +34,7 @@
   "devDependencies": {
     "@types/node": "^25.4.0",
     "tsdown": "^0.21.2",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.2",
     "vitest": "^4.1.0"
   },
   "scripts": {