Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(contact): answer 409 for batch pictures when the engine is not ready
Yudhi Armyndharisd3455a4f2fa2
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 012c78ff1..7b5752172 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -2527,6 +2527,8 @@ Batch-resolve profile picture URLs for many contacts in one request (a chat side`pictures` is keyed by the requested id. A per-id failure — or a lookup that exceeds the 8 s per-id deadline — yields `null` for that id rather than failing the batch. An omitted or empty `ids` returns `{ "pictures": {} }`.+An engine that is not ready is the exception: it describes the session rather than one id, so the whole request answers `409` and no partial result is returned.+> Route-order caveat: `profile-pictures` is declared **before** `GET /:contactId`, so the literal segment wins — a contact whose id is literally `profile-pictures` cannot be fetched through the single-contact route.**Errors:** `400` session is not started · `401` missing/invalid API key, or key not scoped to this session · `409` conflict or engine not ready (retryable)diff --git a/src/modules/contact/contact.service.spec.ts b/src/modules/contact/contact.service.spec.tsindex 1f2523391..e36188c64 100644--- a/src/modules/contact/contact.service.spec.ts+++ b/src/modules/contact/contact.service.spec.ts@@ -2,6 +2,8 @@ import { BadRequestException, ConflictException, NotFoundException } from '@nestimport { ContactService } from './contact.service';import { EngineRegistry } from '../../engine/engine-registry.service';import { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';+import { EngineTransportError } from '../../common/errors/engine-transport.error';describe('ContactService', () => {const makeService = (engine: Partial<IWhatsAppEngine> | undefined) => {@@ -73,6 +75,26 @@ describe('ContactService', () => {expect(out).toEqual({ '[email protected]': 'https://pps/1.jpg', '[email protected]': null, '[email protected]': 'https://pps/3.jpg' });});+ // Not ready is a fact about the session, not about one avatar: a 200 with every picture null would+ // be cached by the dashboard as "nobody has a picture" for the whole stale window.+ it('fails the whole batch with 409 when the engine is not ready, without starting further chunks', async () => {+ const getProfilePicture = jest.fn().mockRejectedValue(new EngineNotReadyError());+ const ids = Array.from({ length: 12 }, (_, i) => `${i}@c.us`);+ const batch = makeService({ getProfilePicture }).getProfilePictures('s1', ids);+ await expect(batch).rejects.toBeInstanceOf(EngineNotReadyError);+ await expect(batch).rejects.toMatchObject({ status: 409 });+ expect(getProfilePicture).toHaveBeenCalledTimes(5);+ });++ it('still nulls a single id whose lookup fails with a transport error', async () => {+ const getProfilePicture = jest+ .fn()+ .mockRejectedValueOnce(new EngineTransportError('query stalled'))+ .mockResolvedValueOnce('https://pps/2.jpg');+ const out = await makeService({ getProfilePicture }).getProfilePictures('s1', ['[email protected]', '[email protected]']);+ expect(out).toEqual({ '[email protected]': null, '[email protected]': 'https://pps/2.jpg' });+ });+it('ignores ids beyond the 50-id batch cap', async () => {const getProfilePicture = jest.fn().mockResolvedValue(null);const ids = Array.from({ length: 60 }, (_, i) => `${i}@c.us`);diff --git a/src/modules/contact/contact.service.ts b/src/modules/contact/contact.service.tsindex de88de1b5..e184258d9 100644--- a/src/modules/contact/contact.service.ts+++ b/src/modules/contact/contact.service.ts@@ -3,6 +3,7 @@ import { EngineRegistry } from '../../engine/engine-registry.service';import { createLogger } from '../../common/services/logger.service';import { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';import { paginate, ListOptions } from '../../common/utils/paginate';+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';import { isIndividualWid, parseWaId, toNeutralJid } from '../../engine/identity/wa-id';/**@@ -85,7 +86,10 @@ export class ContactService {* Batch-resolve profile picture URLs for a list of contact ids (the dashboard's chat-list avatars* — one HTTP call instead of N, so the per-IP throttle isn't exhausted by a sidebar full of* parallel fetches). Engine lookups run 5 at a time with a per-id deadline; a per-id failure or- * timeout yields null for that id (hidden/no picture), never aborts the batch. Ids beyond+ * timeout yields null for that id (hidden/no picture), never aborts the batch. The exception is+ * EngineNotReadyError: it describes the session, not the id, so it fails the whole request with+ * 409 after the current chunk and the remaining chunks are not started. Answering 200 with every+ * avatar null would be cached by the dashboard as "no pictures". Ids beyond* PROFILE_PICTURES_MAX_IDS are ignored.*/async getProfilePictures(sessionId: string, ids: string[]): Promise<Record<string, string | null>> {@@ -93,6 +97,7 @@ export class ContactService {const capped = ids.slice(0, ContactService.PROFILE_PICTURES_MAX_IDS);const pictures: Record<string, string | null> = {};const CHUNK = 5;+ let notReady: EngineNotReadyError | undefined;for (let i = 0; i < capped.length; i += CHUNK) {const chunk = capped.slice(i, i + CHUNK);const results = await Promise.all(@@ -109,14 +114,16 @@ export class ContactService {clearTimeout(timer);resolve([id, url] as const);},- () => {+ (error: unknown) => {clearTimeout(timer);+ if (error instanceof EngineNotReadyError) notReady = error;resolve([id, null] as const);},);});}),);+ if (notReady) throw notReady;for (const [id, url] of results) {pictures[id] = url;}