Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(contact): declare the 400 every contact route can answer

Yudhi Armyndharis5f5cea3c22a9
diff --git a/src/modules/contact/contact.controller.spec.ts b/src/modules/contact/contact.controller.spec.ts
index dd72b1ebd..2d276714d 100644
--- a/src/modules/contact/contact.controller.spec.ts
+++ b/src/modules/contact/contact.controller.spec.ts
@@ -126,3 +126,30 @@ describe('ContactController', () => {
expect(service[method]).toHaveBeenCalledWith('s1', 'c1');
});
});
+
+// Every route resolves the session's engine first, which answers 400 "Session is not started" for a
+// session with no running engine; clients generated from the OpenAPI contract need it declared.
+describe('ContactController OpenAPI error responses', () => {
+ const handler = (name: string) => Object.getOwnPropertyDescriptor(ContactController.prototype, name)?.value as object;
+ const routes = Object.getOwnPropertyNames(ContactController.prototype).filter(
+ name => name !== 'constructor' && Reflect.getMetadata('path', handler(name)) !== undefined,
+ );
+
+ it('covers every route', () => {
+ expect(routes).toHaveLength(11);
+ });
+
+ it.each(routes)('%s declares 400', method => {
+ const responses = Reflect.getMetadata('swagger/apiResponse', handler(method)) as Record<string, unknown>;
+ expect(Object.keys(responses)).toContain('400');
+ });
+
+ // A started session that is not ready answers 409, so the 400 must not describe it as "not ready".
+ it.each(routes)('%s describes its 400 as a session that is not started', method => {
+ const responses = Reflect.getMetadata('swagger/apiResponse', handler(method)) as Record<
+ string,
+ { description?: string }
+ >;
+ expect(responses['400']?.description).toMatch(/^Session is not started/);
+ });
+});
diff --git a/src/modules/contact/contact.controller.ts b/src/modules/contact/contact.controller.ts
index 6272cbb0f..b6ee1d086 100644
--- a/src/modules/contact/contact.controller.ts
+++ b/src/modules/contact/contact.controller.ts
@@ -33,7 +33,7 @@ export class ContactController {
description: 'List of contacts, windowed by limit/offset. A bare array — there is no envelope.',
type: [ContactDto],
})
- @ApiResponse({ status: 400, description: 'Session not ready' })
+ @ApiResponse({ status: 400, description: 'Session is not started' })
@ApiResponse({
status: 503,
description:
@@ -64,6 +64,7 @@ export class ContactController {
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiQuery({ name: 'ids', required: true, description: 'Comma-separated contact ids (max 50 used)' })
@ApiResponse({ status: 200, description: 'Picture URL per requested id', type: ProfilePicturesResponseDto })
+ @ApiResponse({ status: 400, description: 'Session is not started' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
// NOTE: declared BEFORE @Get(':contactId') so the literal segment wins over the param route.
async getProfilePictures(@Param('sessionId') sessionId: string, @Query('ids') ids?: string) {
@@ -86,6 +87,7 @@ export class ContactController {
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({ status: 200, description: 'Blocked contact ids', type: [String] })
+ @ApiResponse({ status: 400, description: 'Session is not started' })
@ApiResponse({ status: 503, description: 'WhatsApp did not answer the blocklist query — retry shortly' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
// NOTE: declared BEFORE @Get(':contactId') so the literal segment wins over the param route.
@@ -103,6 +105,7 @@ export class ContactController {
description: 'Contact details',
type: ContactDto,
})
+ @ApiResponse({ status: 400, description: 'Session is not started' })
@ApiResponse({ status: 404, description: 'Contact not found' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({
@@ -136,6 +139,7 @@ export class ContactController {
description: 'Number existence check result',
type: NumberCheckResponseDto,
})
+ @ApiResponse({ status: 400, description: 'Session is not started' })
@ApiResponse({
status: 503,
description:
@@ -167,6 +171,7 @@ export class ContactController {
description: 'Profile picture URL',
type: ProfilePictureResponseDto,
})
+ @ApiResponse({ status: 400, description: 'Session is not started' })
@ApiResponse({
status: 503,
description:
@@ -189,6 +194,7 @@ export class ContactController {
description: 'Resolved phone number (MSISDN digits), or null when the engine cannot map it',
type: ResolvedPhoneResponseDto,
})
+ @ApiResponse({ status: 400, description: 'Session is not started' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async resolvePhone(@Param('sessionId') sessionId: string, @Param('contactId') contactId: string) {
const phone = await this.contactService.resolveContactPhone(sessionId, contactId);
@@ -203,7 +209,10 @@ export class ContactController {
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiParam({ name: 'contactId', description: 'Contact ID (e.g., [email protected])' })
@ApiResponse({ status: 200, description: 'Contact saved', type: ContactAckResponseDto })
- @ApiResponse({ status: 400, description: 'Session not active or invalid request' })
+ @ApiResponse({
+ status: 400,
+ description: 'Session is not started, an invalid body, or a contact id that is not a phone-based individual id',
+ })
@ApiResponse({
status: 503,
description:
@@ -229,7 +238,10 @@ export class ContactController {
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiParam({ name: 'contactId', description: 'Contact ID (e.g., [email protected])' })
@ApiResponse({ status: 200, description: 'Contact deleted', type: ContactAckResponseDto })
- @ApiResponse({ status: 400, description: 'Session not active' })
+ @ApiResponse({
+ status: 400,
+ description: 'Session is not started, or a contact id that is not a phone-based individual id',
+ })
@ApiResponse({
status: 503,
description:
@@ -254,6 +266,13 @@ export class ContactController {
description: 'Contact blocked',
type: ContactAckResponseDto,
})
+ @ApiResponse({
+ status: 400,
+ description:
+ 'Session is not started, or the id does not name an individual. On Baileys also an id the session ' +
+ 'cannot map between phone and privacy-id form (a `@lid` with no known phone to block, a phone-based ' +
+ 'id with no known `@lid`).',
+ })
@ApiResponse({
status: 503,
description:
@@ -277,6 +296,12 @@ export class ContactController {
description: 'Contact unblocked',
type: ContactAckResponseDto,
})
+ @ApiResponse({
+ status: 400,
+ description:
+ 'Session is not started, or the id does not name an individual. On Baileys also a phone-based id ' +
+ 'the session cannot map to its privacy id (`@lid`).',
+ })
@ApiResponse({
status: 503,
description: