Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(openapi): publish the instance field bounds and secret mask

Yudhi Armyndharis322704e9c586
diff --git a/src/modules/integration/dto/instance.dto.spec.ts b/src/modules/integration/dto/instance.dto.spec.ts
index e3aa72adf..de3175bba 100644
--- a/src/modules/integration/dto/instance.dto.spec.ts
+++ b/src/modules/integration/dto/instance.dto.spec.ts
@@ -1,6 +1,6 @@
import { BadRequestException, ValidationPipe } from '@nestjs/common';
import { DECORATORS } from '@nestjs/swagger';
-import { UpdateInstanceDto } from './instance.dto';
+import { CreateInstanceDto, UpdateInstanceDto } from './instance.dto';
import { GLOBAL_VALIDATION_OPTIONS } from '../../../config/app-validation';
describe('UpdateInstanceDto', () => {
@@ -35,3 +35,23 @@ describe('UpdateInstanceDto', () => {
expect(property?.description).toMatch(/null/);
});
});
+
+type PublishedProperty = { description?: string; pattern?: string; minLength?: number; maxLength?: number };
+const published = (dto: object, key: string): PublishedProperty | undefined =>
+ Reflect.getMetadata(DECORATORS.API_MODEL_PROPERTIES, dto, key) as PublishedProperty | undefined;
+
+describe('CreateInstanceDto published schema', () => {
+ // @nestjs/swagger does not derive bounds from the validators, so each one is declared explicitly.
+ it('publishes the bounds the validators enforce', () => {
+ const proto = CreateInstanceDto.prototype;
+ expect(published(proto, 'instanceId')?.pattern).toBe('^[a-zA-Z0-9_-]{1,64}$');
+ expect(published(proto, 'sessionScope')).toMatchObject({ minLength: 1, maxLength: 256 });
+ expect(published(proto, 'verifyToken')?.maxLength).toBe(512);
+ expect(published(proto, 'secret')).toMatchObject({ minLength: 16, maxLength: 512 });
+ expect(published(UpdateInstanceDto.prototype, 'sessionScope')).toMatchObject({ minLength: 1, maxLength: 256 });
+ });
+
+ it('describes the secret mask the API actually returns', () => {
+ expect(published(CreateInstanceDto.prototype, 'secret')?.description).toContain("Masked ('***')");
+ });
+});
diff --git a/src/modules/integration/dto/instance.dto.ts b/src/modules/integration/dto/instance.dto.ts
index 0ad1ce0a6..10837dc16 100644
--- a/src/modules/integration/dto/instance.dto.ts
+++ b/src/modules/integration/dto/instance.dto.ts
@@ -20,6 +20,7 @@ export class CreateInstanceDto {
@ApiProperty({
description:
'Operator-chosen instance id (unique within the plugin). Namespaces the ingress URL and the instance secret.',
+ pattern: INSTANCE_ID_PATTERN.source,
example: 'chatwoot-prod-1',
})
@IsString()
@@ -28,6 +29,8 @@ export class CreateInstanceDto {
@ApiPropertyOptional({
description: 'Session id the instance is scoped to. Omit for all sessions.',
+ minLength: 1,
+ maxLength: 256,
example: '8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a',
})
@IsOptional()
@@ -38,6 +41,7 @@ export class CreateInstanceDto {
@ApiPropertyOptional({
description: 'Token echoed back for the provider webhook verification handshake. Auto-generated when omitted.',
+ maxLength: 512,
example: 'a1b2c3d4e5f6',
})
@IsOptional()
@@ -50,8 +54,10 @@ export class CreateInstanceDto {
// Omit to auto-generate a random 64-hex secret.
@ApiPropertyOptional({
description:
- 'Ingress HMAC secret shared with the provider. Omit to auto-generate a random 64-hex secret. Masked (****) on every read.',
+ "Ingress HMAC secret shared with the provider. Omit to auto-generate a random 64-hex secret. Masked ('***') on every later read; plaintext returned only once on create/regenerate-secret.",
writeOnly: true,
+ minLength: 16,
+ maxLength: 512,
example: 'super-secret-provider-webhook-key',
})
@IsOptional()
@@ -87,6 +93,8 @@ export class UpdateInstanceDto {
nullable: true,
// `string | null` reduces to `Object` under emitDecoratorMetadata; declare the real type.
type: String,
+ minLength: 1,
+ maxLength: 256,
})
@IsOptional()
@IsString()