Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import {
useInfiniteQuery,
useQueryClient,
type InfiniteData,
type UseInfiniteQueryResult,
type QueryCacheNotifyEvent,
} from '@tanstack/react-query';
import type { QueryClient } from '@tanstack/react-query';
import { useEffect } from 'react';
import {
mergeChatMessages,
mapEngineHistoryMessage,
updateMessageById,
removeMessageById,
type ChatMessageView,
} from '../utils/chatMessages';
import { upsertIntoPages, nextMessagePageParam, type MessagePage } from '../utils/messagePages';
import { sessionApi } from '../services/api';
export type MessagesQueryKey = readonly ['messages', string, string];
export function messagesQueryKey(sessionId: string, chatId: string): MessagesQueryKey {
return ['messages', sessionId, chatId] as const;
}
/**
* How many DB rows one page asks for. The gateway clamps `limit` to 100
* (`message.service.ts`: `Math.min(Math.max(Math.trunc(rawLimit), 1), 100)`), so this is its
* maximum. Termination assumes the clamp holds: a page short of THIS value is read as the last one
* (see `nextMessagePageParam`), so a lower clamp on the server would end paging after page one.
*/
export const MESSAGE_PAGE_SIZE = 100;
export type MessagesData = InfiniteData<MessagePage>;
/**
* The one flat chronological view of a paged cache. A single page is ascending but partial, so
* neither a message's position nor its absence can be read from one.
*/
export function flattenMessagePages(data: MessagesData): ChatMessageView[] {
return mergeChatMessages(
data.pages.flatMap(page => page.db),
data.pages.flatMap(page => page.history),
);
}
/**
* Fetch a chat's messages a page at a time, newest page first, cached at staleTime: Infinity;
* realtime updates flow through useChatMessagesActions, not refetches.
*
* Engine history comes with the first page only — it is a one-shot backfill of a thread the gateway
* never captured, with no cursor to page through. Fetched without media to keep the cache small; the
* DB copy wins in mergeChatMessages, so recent media still renders.
*
* Base64 media payloads are bounded twice: `mergeOrAppend` caps each page's `db` as messages land
* in it (so a media-heavy page 0 can't grow the cache unbounded), and `select` caps the flattened,
* correctly-ordered thread again for what actually renders — the two bounds cover the cache and the
* viewport respectively, and neither alone would cover both.
*
* `historySupported` is false for an engine that answers 501 to the history read (Baileys): the request is
* never sent, so every chat opened there does not log a failed call in the browser console.
*/
export function useChatMessages(
sessionId: string,
chatId: string | null,
historySupported = true,
): UseInfiniteQueryResult<ChatMessageView[], Error> {
const queryClient = useQueryClient();
const query = useInfiniteQuery<MessagePage, Error, ChatMessageView[], MessagesQueryKey, number>({
queryKey: messagesQueryKey(sessionId, chatId ?? ''),
initialPageParam: 0,
queryFn: async ({ pageParam }) => {
const wantsHistory = pageParam === 0 && historySupported;
const [dbRes, historyRes] = await Promise.allSettled([
sessionApi.getChatMessages(sessionId, chatId!, MESSAGE_PAGE_SIZE, pageParam),
wantsHistory ? sessionApi.getChatHistory(sessionId, chatId!, 100, false) : Promise.resolve([]),
]);
// Only the first page may fall back to history alone; an older page has no second source, so a
// rejected DB read there is a real failure and must surface rather than resolve to an empty
// page that would read as "no more messages".
if (dbRes.status === 'rejected' && (!wantsHistory || historyRes.status === 'rejected')) throw dbRes.reason;
const db = dbRes.status === 'fulfilled' ? dbRes.value : { messages: [] };
const history = historyRes.status === 'fulfilled' ? historyRes.value.map(mapEngineHistoryMessage) : [];
// The gateway answers newest-first (createdAt DESC); reversed here so `page.db` is ascending
// like the flattened thread. mergeOrAppend's cap strips from the front of an ascending list —
// storing pages in server order would make it strip the newest payloads first.
return { db: [...db.messages].reverse(), history, fetched: db.messages.length };
},
getNextPageParam: (_lastPage, allPages) => nextMessagePageParam(allPages, MESSAGE_PAGE_SIZE),
// Consumers keep seeing one flat chronological list; paging stays inside the cache.
select: flattenMessagePages,
enabled: Boolean(sessionId && chatId),
staleTime: Infinity,
gcTime: 5 * 60 * 1000,
});
// A page in flight carries a snapshot of `data.pages` taken when it started (TanStack's
// infiniteQueryBehavior reads `oldPages` in onFetch), so its result overwrites anything written
// meanwhile — and at staleTime: Infinity no refetch brings it back. An optimistic send during
// that window would leave the thread for good. writeMessagesCache queues those writes and
// schedules their replay for the moment the fetch settles (see scheduleReplayOnSettle) — not for
// whenever this hook next happens to mount, which is too late: another writer (the composer's own
// send reconciling, a socket event routed through cachedSessionThreads to a chat that is not even
// open) can land on the cache between the fetch settling and a remount, and a replay fired only on
// remount would stomp that newer write with the stale queued one. This effect stays as a second
// chance for the same key in case the fetch had already settled before any write ever queued for
// it — a normal case, and a no-op here since the queue is empty by then.
// Gated on `idle`, not on `isFetching`. A fetch the browser parks when it goes offline reports
// fetchStatus 'paused', which makes `isFetching` false while the request is still going to land:
// draining here would hand the resumed page a queue that no longer exists to replay. The writer
// and the settle subscription key on the same value for the same reason.
const { fetchStatus } = query;
useEffect(() => {
if (fetchStatus !== 'idle') return;
replayWritesLostToFetch(queryClient, messagesQueryKey(sessionId, chatId ?? ''));
}, [queryClient, fetchStatus, sessionId, chatId]);
return query;
}
interface PendingWrite {
apply: (data: MessagesData) => MessagesData;
/** The cache value this write produced — see replayWritesLostToFetch. */
wrote: MessagesData | undefined;
}
// Module scope because the helpers below are plain functions with no component to hang state on.
const writesLostToFetch = new Map<string, PendingWrite[]>();
// One queryCache subscription per key with a queue outstanding, so replay fires the instant that
// key's fetch settles rather than whenever a consumer next mounts — see scheduleReplayOnSettle.
const settleSubscriptions = new Map<string, () => void>();
const pendingKey = (key: MessagesQueryKey): string => JSON.stringify(key);
const sameQueryKey = (a: readonly unknown[], b: MessagesQueryKey): boolean =>
a.length === b.length && a.every((part, i) => part === b[i]);
/**
* Fire replayWritesLostToFetch for `key` the moment its query stops fetching, independent of
* whether any component watching it is mounted. Self-unsubscribes on that event or on the query
* being removed from the cache entirely (gcTime elapsed with nothing open) — replaying onto a
* query that no longer exists would just reseed a phantom entry, which writeMessagesCache's own
* "never seed a slice" rule exists to prevent.
*
* Idempotent to call redundantly: only takes effect while no subscription is already tracked for
* this key (writeMessagesCache only calls it when the queue transitions from empty to non-empty).
*/
function scheduleReplayOnSettle(queryClient: QueryClient, key: MessagesQueryKey): void {
const id = pendingKey(key);
if (settleSubscriptions.has(id)) return;
const unsubscribe = queryClient.getQueryCache().subscribe((event: QueryCacheNotifyEvent) => {
if (!sameQueryKey(event.query.queryKey, key)) return;
if (event.type === 'removed') {
settleSubscriptions.delete(id);
unsubscribe();
writesLostToFetch.delete(id);
return;
}
// Settled means `idle`, not merely "not fetching". A fetch the browser pauses when it goes
// offline reports `paused` and resumes later, so treating that as a settle would drain the
// queue, unsubscribe, and leave the resumed page free to overwrite those writes for good.
if (event.query.state.fetchStatus !== 'idle') return;
settleSubscriptions.delete(id);
unsubscribe();
replayWritesLostToFetch(queryClient, key);
});
settleSubscriptions.set(id, unsubscribe);
}
/**
* Apply one change to a chat's paged cache, recording it for replay when a page is in flight.
*
* Never seeds a slice: an entry created here would be "fresh" under staleTime: Infinity, so opening
* the chat would skip the queryFn and show this write alone. A write while the FIRST page is in
* flight has no data to land on, so it is only queued, then replayed onto that page when it
* settles; the composer is live before the thread loads, and dropping the write lost the message.
*
* `apply` must be idempotent: a replay can re-run it against a cache that already reflects it.
*/
function writeMessagesCache(
queryClient: QueryClient,
key: MessagesQueryKey,
apply: (data: MessagesData) => MessagesData,
): void {
const state = queryClient.getQueryState<MessagesData>(key);
if (state === undefined || (state.data === undefined && state.fetchStatus === 'idle')) return;
queryClient.setQueryData<MessagesData>(key, old => (old === undefined ? undefined : apply(old)));
// Anything but `idle` still has a page coming that will overwrite this write when it lands, so
// it has to be queued. `paused` is the case a bare `=== 'fetching'` test misses: the browser
// parks the fetch when it goes offline and resumes it later.
if (state.fetchStatus === 'idle') return;
const id = pendingKey(key);
const queued = writesLostToFetch.get(id) ?? [];
const wrote = queryClient.getQueryData<MessagesData>(key);
writesLostToFetch.set(id, [...queued, { apply, wrote }]);
if (queued.length === 0) scheduleReplayOnSettle(queryClient, key);
}
/**
* Re-apply, in order, the writes a landed page overwrote.
*
* Only if one actually did. A fetch that FAILED leaves the cache exactly as the last queued write
* left it, so nothing was lost and replaying would apply the whole queue twice. Identity answers
* that in one comparison — a landed page always produces a new value — and it is a per-QUEUE
* question, not a per-entry one: either a fetch replaced the data, in which case every queued
* write went with it, or it did not, in which case none did.
*
* Called right as the fetch that could have clobbered the queue settles (scheduleReplayOnSettle),
* so this identity check is comparing against the immediately-landed page, before any OTHER writer
* gets a turn — that ordering is what keeps a later, unrelated write from being overwritten by a
* stale replay that only fired once some consumer happened to remount.
*/
export function replayWritesLostToFetch(queryClient: QueryClient, key: MessagesQueryKey): void {
const id = pendingKey(key);
const queue = writesLostToFetch.get(id);
if (queue === undefined || queue.length === 0) return;
writesLostToFetch.delete(id);
if (queue[queue.length - 1].wrote === queryClient.getQueryData<MessagesData>(key)) return;
queryClient.setQueryData<MessagesData>(key, old =>
old === undefined ? undefined : queue.reduce((data, write) => write.apply(data), old),
);
}
/**
* Apply a list transform to every cached page. Both arrays are transformed: a message the gateway
* never persisted exists only in `history`, so touching `db` alone would drop its edits and deletes.
*
* The transform sees one page at a time, so it must not depend on the thread's order or
* completeness — `flattenMessagePages` answers those questions.
*/
export function updateCachedMessages(
queryClient: QueryClient,
key: MessagesQueryKey,
transform: (list: ChatMessageView[]) => ChatMessageView[],
): void {
writeMessagesCache(queryClient, key, data => ({
...data,
pages: data.pages.map(page => ({ ...page, db: transform(page.db), history: transform(page.history) })),
}));
}
/**
* Insert or merge one message, optionally dropping an optimistic placeholder by id.
*
* Which page receives it matters: `mergeOrAppend` appends when it finds no match, so running it
* over every page would add a copy to each one. The message is merged into the page that already
* holds it, and only lands on the newest page when no page does.
*/
export function upsertCachedMessage(
queryClient: QueryClient,
key: MessagesQueryKey,
incoming: ChatMessageView,
options: { dropId?: string } = {},
): void {
writeMessagesCache(queryClient, key, data =>
data.pages.length === 0 ? data : { ...data, pages: upsertIntoPages(data.pages, incoming, options.dropId) },
);
}
/**
* The cached chats under one session that hold a matching message, as [key, flat thread] pairs.
*
* `matches` is applied to the raw pages first so only a thread that actually holds the message pays
* for the merge — a realtime event concerns one chat, and flattening every open one per event would
* sort and cap them all to throw the result away.
*/
export function cachedSessionThreads(
queryClient: QueryClient,
sessionId: string,
matches: (message: ChatMessageView) => boolean,
): Array<[MessagesQueryKey, ChatMessageView[]]> {
const threads: Array<[MessagesQueryKey, ChatMessageView[]]> = [];
for (const [key, data] of queryClient.getQueriesData<MessagesData>({ queryKey: ['messages', sessionId] })) {
if (data === undefined) continue;
const holds = data.pages.some(page => page.db.some(matches) || page.history.some(matches));
if (holds) threads.push([key as MessagesQueryKey, flattenMessagePages(data)]);
}
return threads;
}
/**
* Mutation helpers that write directly to the React Query cache. Use these
* from the WebSocket subscriber, the optimistic-send flow, and ACK handlers
* instead of calling setMessages locally.
*/
export function useChatMessagesActions() {
const qc = useQueryClient();
return {
appendMessage(sessionId: string, chatId: string, msg: ChatMessageView) {
upsertCachedMessage(qc, messagesQueryKey(sessionId, chatId), msg);
},
updateMessage(sessionId: string, chatId: string, id: string, patch: Partial<ChatMessageView>) {
updateCachedMessages(qc, messagesQueryKey(sessionId, chatId), list => updateMessageById(list, id, patch));
},
removeMessage(sessionId: string, chatId: string, id: string) {
updateCachedMessages(qc, messagesQueryKey(sessionId, chatId), list => removeMessageById(list, id));
},
};
}