Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

45.1 KB
Raw Blame
import {
  Controller,
  Get,
  Post,
  Patch,
  Put,
  Delete,
  Param,
  Query,
  Body,
  HttpCode,
  HttpStatus,
  ParseUUIDPipe,
  BadRequestException,
  ForbiddenException,
  Res,
} from '@nestjs/common';
import type { Response } from 'express';
import { ApiTags, ApiOperation, ApiResponse, ApiParam, ApiQuery, ApiExtraModels, getSchemaPath } from '@nestjs/swagger';
import { SessionService } from './session.service';
import {
  CreateSessionDto,
  SessionConfigResponseDto,
  UpdateSessionConfigDto,
  SessionProxyResponseDto,
  UpdateSessionProxyDto,
  SessionResponseDto,
  QRCodeResponseDto,
  MarkChatReadDto,
  MarkChatUnreadDto,
  SubscribePresenceDto,
  SetOwnPresenceDto,
  ChatPresenceResponseDto,
  ArchiveChatDto,
  MuteChatDto,
  PinChatDto,
  DeleteChatDto,
  SendChatStateDto,
  RequestPairingCodeDto,
  PairingCodeResponseDto,
  ChatSummaryDto,
  SessionActionResponseDto,
  SessionGroupSummaryDto,
  SessionsOverviewResponseDto,
} from './dto';
import { Session } from './entities/session.entity';
import { ChatSummary } from '../../engine/interfaces/whatsapp-engine.interface';
import { paginate } from '../../common/utils/paginate';
import { AuditService } from '../audit/audit.service';
import { AuditAction } from '../audit/entities/audit-log.entity';
import {
  ChatScoped,
  CurrentApiKey,
  RequireRole,
  RequireUnscopedKey,
  SessionScoped,
} from '../auth/decorators/auth.decorators';
import { ChatScopeService } from '../auth/chat-scope.service';
import { ApiKey, ApiKeyRole } from '../auth/entities/api-key.entity';
import {
  ENGINE_NOT_READY_409,
  PAIRING_NOT_READY_409,
  PAIRING_TRANSPORT_503,
  RECIPIENT_LOOKUP_503,
} from '../../common/openapi/engine-status-responses';

@ApiTags('sessions')
@Controller('sessions')
// The `:sessionId` route param here is a WhatsApp session id, so the ApiKeyGuard enforces a key's
// allowedSessions scope against it (other controllers' `:id` is an unrelated resource id).
@SessionScoped()
export class SessionController {
  constructor(
    private readonly sessionService: SessionService,
    private readonly auditService: AuditService,
    private readonly chatScope: ChatScopeService,
  ) {}

  private transformSession(session: Session): SessionResponseDto {
    // engineLoaded() reads the engine map itself, so this is read at response time: a session that just
    // finished reconnecting reports the engine in the same response that reports its status.
    return SessionResponseDto.fromEntity(session, this.sessionService.engineLoaded(session));
  }

  @Post()
  @RequireRole(ApiKeyRole.OPERATOR)
  // Creating a session has no existing session id for the class-level @SessionScoped fence to check,
  // and the new session is outside the caller's allowlist by construction — so a key restricted to
  // specific sessions cannot create one. Different metadata key from @SessionScoped; they coexist.
  @RequireUnscopedKey()
  @ApiOperation({ summary: 'Create a new WhatsApp session' })
  @ApiResponse({
    status: 201,
    description: 'Session created',
    type: SessionResponseDto,
  })
  @ApiResponse({
    status: 403,
    description:
      'Key lacks the OPERATOR role, is restricted to specific sessions, or set proxyUrl without the ADMIN role',
  })
  @ApiResponse({ status: 400, description: 'Validation failed, or the body carries a field the DTO does not declare.' })
  @ApiResponse({ status: 409, description: 'Session name already exists' })
  @ApiResponse({
    status: 503,
    description: 'On SQLite, another database transaction stayed open for 10 s; nothing was stored, so retry.',
  })
  async create(@Body() dto: CreateSessionDto, @CurrentApiKey() apiKey?: ApiKey): Promise<SessionResponseDto> {
    // A session proxy carries the session's egress, including the gateway's fetches of caller-supplied
    // URLs, so choosing one is a deployment decision: ADMIN only, like PATCH :sessionId/proxy. The
    // global guard always attaches the key, so a missing one is refused too.
    if (dto.proxyUrl && apiKey?.role !== ApiKeyRole.ADMIN) {
      throw new ForbiddenException('Setting proxyUrl requires an ADMIN key');
    }
    const session = await this.sessionService.create(dto);
    await this.auditService.logInfo(AuditAction.SESSION_CREATED, {
      sessionId: session.id,
      sessionName: session.name,
    });
    return this.transformSession(session);
  }

  @Get()
  @ApiOperation({ summary: 'List all sessions' })
  @ApiResponse({
    status: 200,
    description: 'List of sessions',
    type: [SessionResponseDto],
  })
  @ApiQuery({ name: 'limit', required: false, description: 'Max sessions to return (1-1000, default 1000)' })
  @ApiQuery({ name: 'offset', required: false, description: 'Number of sessions to skip (for paging)' })
  @ApiQuery({
    name: 'name',
    required: false,
    type: String,
    description:
      'Return only the session with exactly this name (case-sensitive); no match returns an empty array. ' +
      'An empty value or a repeated key is rejected with 400.',
  })
  @ApiResponse({ status: 400, description: '`name` is empty or repeated.' })
  async findAll(
    @CurrentApiKey() apiKey?: ApiKey,
    @Query('limit') limit?: string,
    @Query('offset') offset?: string,
    @Query('name') name?: string | string[],
  ): Promise<SessionResponseDto[]> {
    // ?name=a&name=b arrives as an array and ?name= as ''; neither names one session, and silently
    // dropping the filter would hand back every session instead.
    if (Array.isArray(name) || name === '') {
      throw new BadRequestException('name must be a single non-empty value');
    }
    // Scope to the key's allowedSessions so a session-restricted key cannot enumerate every
    // session. A null/empty allowlist lists all whatever the key's role; a scoped ADMIN key is filtered too.
    const sessions = await this.sessionService.findAll(apiKey?.allowedSessions, {
      limit: limit ? parseInt(limit, 10) : undefined,
      offset: offset ? parseInt(offset, 10) : undefined,
      name,
    });
    return sessions.map(s => this.transformSession(s));
  }

  @ChatScoped('agnostic')
  @Get(':sessionId')
  @ApiOperation({ summary: 'Get session by ID' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Session details',
    type: SessionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'The session id is not a UUID' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  async findOne(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
    const session = await this.sessionService.findOne(id);
    return this.transformSession(session);
  }

  @Get(':sessionId/config')
  @ApiOperation({ summary: 'Get the tunable configuration for a session' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Effective session configuration',
    type: SessionConfigResponseDto,
  })
  @ApiResponse({ status: 400, description: 'The session id is not a UUID' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  async getConfig(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionConfigResponseDto> {
    return this.sessionService.getConfig(id);
  }

  @Patch(':sessionId/config')
  @RequireRole(ApiKeyRole.OPERATOR)
  @ApiOperation({
    summary: 'Update the tunable configuration for a session',
    description:
      'Merges the supplied keys into the session config; omitted keys are left unchanged and an ' +
      'explicit null clears a key back to its default. No restart is required or performed. ' +
      '`autoRejectCalls` is re-read on every incoming call, so it applies immediately; the two ' +
      'reconnect settings are read once per start and therefore apply on the next start.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Updated session configuration',
    type: SessionConfigResponseDto,
  })
  @ApiResponse({ status: 400, description: 'A supplied value is outside its accepted range' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({ status: 409, description: 'The session config kept changing under concurrent requests; retry' })
  async updateConfig(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: UpdateSessionConfigDto,
  ): Promise<SessionConfigResponseDto> {
    const config = await this.sessionService.updateConfig(id, dto);
    await this.auditService.logInfo(AuditAction.SESSION_CONFIG_UPDATED, {
      sessionId: id,
      // The resulting state, not the request: a merge patch is meaningless in an audit trail without
      // knowing what it merged into. Only the three recognised keys, never the raw column.
      metadata: { ...config },
    });
    return config;
  }

  @Get(':sessionId/proxy')
  @ApiOperation({ summary: 'Get the per-session egress proxy configuration (credentials masked)' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Effective proxy configuration',
    type: SessionProxyResponseDto,
  })
  @ApiResponse({ status: 400, description: 'The session id is not a UUID' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  async getProxy(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionProxyResponseDto> {
    return this.sessionService.getProxy(id);
  }

  @Patch(':sessionId/proxy')
  // A session proxy carries all of the session's egress, including the gateway's fetches of
  // caller-supplied URLs, and its host is not checked against internal addresses: it is trusted
  // egress chosen by the deployment's administrator. Setting or clearing it is therefore ADMIN only,
  // like proxyUrl on POST /sessions, and never open to a key restricted to specific sessions.
  @RequireRole(ApiKeyRole.ADMIN)
  @RequireUnscopedKey()
  @ApiOperation({
    summary: 'Update the per-session egress proxy configuration',
    description:
      'Sets or clears the proxy URL. Credentials in `proxyUrl` are stored but never returned by GET. ' +
      'No restart is performed — changes apply on the next session start.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Updated proxy configuration',
    type: SessionProxyResponseDto,
  })
  @ApiResponse({ status: 400, description: 'Invalid proxyUrl' })
  @ApiResponse({ status: 403, description: 'Key lacks the ADMIN role, or is restricted to specific sessions' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  async updateProxy(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: UpdateSessionProxyDto,
  ): Promise<SessionProxyResponseDto> {
    const proxy = await this.sessionService.updateProxy(id, dto);
    await this.auditService.logInfo(AuditAction.SESSION_CONFIG_UPDATED, {
      sessionId: id,
      metadata: { proxyEnabled: proxy.enabled, proxyType: proxy.proxyType, proxyHost: proxy.proxyHost },
    });
    return proxy;
  }

  @Delete(':sessionId')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.NO_CONTENT)
  @ApiOperation({ summary: 'Delete a session' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({ status: 204, description: 'Session deleted' })
  @ApiResponse({ status: 400, description: 'The session id is not a UUID' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 409,
    description:
      'A credential teardown for the same session name is still in flight (retryable: the body ' +
      "carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; wait for it to settle and retry), OR " +
      "another node currently holds this session's live engine and deleting it here would strip a " +
      'session the owner is running, OR ownership changes while deletion runs. The first two refusals ' +
      'remove nothing. Ownership loss stops later deletion units; earlier batches may already be committed.',
  })
  async delete(@Param('sessionId', ParseUUIDPipe) id: string): Promise<void> {
    const session = await this.sessionService.findOne(id);
    await this.sessionService.delete(id);
    await this.auditService.logInfo(AuditAction.SESSION_DELETED, {
      sessionId: id,
      sessionName: session.name,
    });
  }

  @Post(':sessionId/start')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({
    summary: 'Start a session and initialize WhatsApp connection',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Session started',
    type: SessionResponseDto,
  })
  @ApiResponse({
    status: 400,
    description:
      'Session already started or already starting, or this node is at its MAX_CONCURRENT_SESSIONS cap ' +
      '(`Maximum concurrent sessions reached (N)`), answered only after the 404 and the 409 for a ' +
      'session running on another node; a start refused at the cap launches nothing and leaves a ' +
      'stop in place.',
  })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 409,
    description:
      'A credential teardown for the same session name is still in flight (e.g. a prior logout ' +
      'that owns destructive cleanup). Retryable — the body carries `code: ' +
      'SESSION_NAME_TEARDOWN_PENDING`; wait for it to settle and retry. No destructive side ' +
      'effect runs before this refusal. Also returned when another node currently holds this ' +
      "session's engine: only the owner may start it, and the claim is refused before any engine " +
      'is launched, so no second connection to the account is opened. Also returned, with no `code`, ' +
      'when a stop, a logout or force-kill that found a running engine, or a data import (`stopOrphans`) ' +
      'of this session began or finished while the start was waiting, or a delete of it was still ' +
      'running: the start yields and launches nothing. After a stop or force-kill, a new POST /start ' +
      'clears it and starts the session; after a delete, or an import that removed the session, the ' +
      'retry answers 404.',
  })
  @ApiResponse({
    status: 503,
    description:
      "The gateway is shutting down, or the engine's browser or socket connection died during launch and " +
      'the one automatic retry failed too; no engine is left running, so the start can be retried.',
  })
  @ApiResponse({
    status: 504,
    description:
      'The engine did not finish starting within its timeout (WhatsApp Web or the network unreachable, ' +
      'a stalled browser or resource limit, or, on whatsapp-web.js, an unreachable proxyUrl or the auth ' +
      'timeout); the engine is torn down and the start can be retried.',
  })
  async start(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
    const session = await this.sessionService.start(id, { explicit: true });
    await this.auditService.logInfo(AuditAction.SESSION_STARTED, {
      sessionId: session.id,
      sessionName: session.name,
    });
    return this.transformSession(session);
  }

  @Post(':sessionId/stop')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: 'Stop a session and disconnect WhatsApp' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Session stopped',
    type: SessionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'The session id is not a UUID' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 409,
    description:
      "Another node currently holds this session's live engine (multi-node deployments): stopping " +
      'it here would report the session down while the owner keeps running it, so the request is ' +
      'refused. Retry against the owning node, or once its lease has lapsed.',
  })
  @ApiResponse({
    status: 502,
    description:
      'Session was stopped locally, but the engine teardown did not complete (the graceful ' +
      'disconnect and the force-destroy escalation both failed, so the engine process may still ' +
      "be running). Retryable — the body carries `code: 'SESSION_STOP_INCOMPLETE'`; the status " +
      'is settled to `disconnected` and no success audit is written. Retry the stop; restart the ' +
      'node to reap a leaked process.',
  })
  async stop(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
    const session = await this.sessionService.stop(id);
    await this.auditService.logInfo(AuditAction.SESSION_STOPPED, {
      sessionId: session.id,
      sessionName: session.name,
    });
    return this.transformSession(session);
  }

  @Post(':sessionId/logout')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({
    summary: 'Log out of WhatsApp (unlinks this device) and stop the session',
    description:
      'Attempts an engine-native unlink of this companion device, then tears the session down ' +
      'locally. `200` means the engine-native unlink operation completed AND the required local ' +
      'credential cleanup completed — for Baileys a valid companion identity, an acknowledged ' +
      '`remove-companion-device` IQ response, and removal of the on-disk auth dir; for ' +
      'whatsapp-web.js the native `Client.logout()` promise settled. `200` is NOT an independent ' +
      'observation that the handset UI no longer shows the linked device. Because a completed ' +
      'unlink wipes the stored credentials, reconnecting after a `200` always requires a fresh QR ' +
      'scan or pairing code.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description:
      'Unlink operation and required local cleanup completed; session is stopped and `phone` is ' +
      'cleared. Recorded in the audit log as `session_logged_out`.',
    content: {
      'application/json': {
        schema: { $ref: '#/components/schemas/SessionResponseDto' },
        example: {
          id: '8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a',
          name: 'my-bot',
          status: 'disconnected',
          phone: null,
          // logout clears `phone` only, so a session that had connected keeps the name and the
          // connection timestamp it was last linked with.
          pushName: 'John Doe',
          connectedAt: '2026-06-24T08:15:00.000Z',
          lastActive: '2026-06-25T09:01:55.000Z',
          createdAt: '2026-06-20T11:30:00.000Z',
          updatedAt: '2026-06-25T09:11:00.000Z',
          lastError: null,
          restriction: null,
          // The engine is torn out of the map before the status write, so a logout always reports false.
          engineLoaded: false,
        },
      },
    },
  })
  @ApiResponse({
    status: 400,
    description: 'Session is not started (no engine to send through); the row is left untouched',
  })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 502,
    description:
      'Session was stopped locally, but the logout operation is incomplete (no send, no ' +
      'acknowledgement, timeout/transport error, or local-cleanup failure). Retryable — the ' +
      "body carries `code: 'SESSION_LOGOUT_INCOMPLETE'`; `phone` is cleared and no success audit " +
      'is written. Start the session again and retry the logout.',
  })
  async logout(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
    const session = await this.sessionService.logout(id);
    await this.auditService.logInfo(AuditAction.SESSION_LOGGED_OUT, {
      sessionId: session.id,
      sessionName: session.name,
    });
    return this.transformSession(session);
  }

  @Post(':sessionId/force-kill')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: 'Force-kill a stuck session (SIGKILL its wedged engine, then tear it down)' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Session force-killed',
    type: SessionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'Session is not started' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 502,
    description:
      'Session was stopped locally, but the engine force-kill did not complete (the force-destroy ' +
      'threw or timed out, so the engine process may still be running). The body carries ' +
      "`code: 'SESSION_FORCE_KILL_INCOMPLETE'`; the status is settled to `disconnected` and no " +
      'success audit is written. Restart the node to reap a leaked process.',
  })
  async forceKill(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
    const session = await this.sessionService.forceKill(id);
    await this.auditService.logInfo(AuditAction.SESSION_FORCE_KILLED, {
      sessionId: session.id,
      sessionName: session.name,
    });
    return this.transformSession(session);
  }

  @Get(':sessionId/qr')
  @RequireRole(ApiKeyRole.OPERATOR)
  @ApiOperation({ summary: 'Get QR code for session authentication' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'QR code data',
    type: QRCodeResponseDto,
  })
  @ApiResponse({
    status: 400,
    description: 'QR code not ready or session already authenticated',
  })
  @ApiResponse({ status: 404, description: 'Session not found' })
  async getQRCode(@Param('sessionId', ParseUUIDPipe) id: string): Promise<QRCodeResponseDto> {
    const qrCode = await this.sessionService.getQRCode(id);
    await this.auditService.logInfo(AuditAction.SESSION_QR_GENERATED, {
      sessionId: id,
    });
    return qrCode;
  }

  @Post(':sessionId/pairing-code')
  @RequireRole(ApiKeyRole.OPERATOR)
  @ApiOperation({
    summary: 'Request an 8-char pairing code to link via phone number (alternative to QR)',
    description:
      'On the whatsapp-web.js engine, only request a code for a number you are prepared to re-link. A request ' +
      'for a number that already has a linked session has been observed to end with WhatsApp revoking that ' +
      'device: the linked session logs out, its credentials are deleted and it falls back to `qr_ready`. ' +
      'On that engine a number that is the stored phone of another session of this gateway (the Brazilian, ' +
      'Mexican and Argentine mobile spellings of one number count as the same) is refused with `409` and WhatsApp ' +
      'is not asked; the gateway cannot see a link made on another gateway or only on the phone. ' +
      'Baileys was not affected in the same tests and accepts the request: its sessions are companion devices ' +
      'and may share a number. Link by QR when a session of that number must stay up.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({ status: 201, description: 'Pairing code generated', type: PairingCodeResponseDto })
  @ApiResponse({ status: 400, description: 'Session not started or already authenticated' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 409,
    description:
      PAIRING_NOT_READY_409 +
      ' On whatsapp-web.js also answered, with nothing sent to WhatsApp, when the requested number is the stored ' +
      'phone of another session of this gateway: delete that session, or log it out while it runs, first.',
  })
  @ApiResponse({ status: 503, description: PAIRING_TRANSPORT_503 })
  async requestPairingCode(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: RequestPairingCodeDto,
  ): Promise<PairingCodeResponseDto> {
    return this.sessionService.requestPairingCode(id, dto.phoneNumber);
  }

  // Shares a Path Item with GroupController's POST on the same route — one parameter name for the
  // one positional segment, or the contract splits it into two entries.
  @ChatScoped('filtered')
  @Get(':sessionId/groups')
  @ApiOperation({ summary: 'Get all groups for a session' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'List of groups the session is a member of',
    type: [SessionGroupSummaryDto],
  })
  @ApiResponse({ status: 400, description: 'Session not ready' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 503,
    description:
      'WhatsApp did not answer the group-list query. Deliberately not reported as an empty list — ' +
      'the engine returns the same empty value for "you are in no groups", and a caller cannot tell ' +
      'those apart from the body. On Baileys, also answered when WhatsApp rate-limits or times out the ' +
      'request (code 429 or 408); retry after a pause.',
  })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  @ApiQuery({ name: 'limit', required: false, description: 'Max groups to return (1–1000, default 1000)' })
  @ApiQuery({ name: 'offset', required: false, description: 'Number of groups to skip (for paging)' })
  async getGroups(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @CurrentApiKey() apiKey?: ApiKey,
    @Query('limit') limit?: string,
    @Query('offset') offset?: string,
  ): Promise<{ id: string; name: string; linkedParentJID?: string | null }[]> {
    // Filtered before paging, as getChats is, so a chat-restricted key sees only its groups and
    // never a short window while an allowed group sat just past it.
    const visible = await this.chatScope.filter(apiKey, await this.sessionService.listGroups(id), g => g.id);
    return paginate(visible, limit ? parseInt(limit, 10) : undefined, offset ? parseInt(offset, 10) : undefined);
  }

  @ChatScoped('filtered')
  @Get(':sessionId/chats')
  @ApiOperation({ summary: 'Get active chats for a session' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({ status: 200, description: 'List of active chats (most recent first)', type: [ChatSummaryDto] })
  @ApiResponse({ status: 400, description: 'Session not ready' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  @ApiResponse({
    status: 503,
    description:
      'The whatsapp-web.js page connection died mid-read, or WhatsApp Web did not answer within the ' +
      'protocol timeout, so nothing could be read. Deliberately not reported as an empty list: a page ' +
      'that went away says nothing about the chats.',
  })
  @ApiQuery({ name: 'limit', required: false, description: 'Max chats to return (1–1000, default 1000)' })
  @ApiQuery({ name: 'offset', required: false, description: 'Number of chats to skip (for paging)' })
  async getChats(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @CurrentApiKey() apiKey?: ApiKey,
    @Query('limit') limit?: string,
    @Query('offset') offset?: string,
  ): Promise<ChatSummary[]> {
    // This route is admitted to a chat-restricted key because it FILTERS to the key's chats rather
    // than naming one in the path. Filter BEFORE paginating: filtering the page instead would give a
    // restricted key a short or empty window while an allowed chat sat just past it.
    const skip = offset ? parseInt(offset, 10) : undefined;
    const visible = await this.chatScope.filter(apiKey, await this.sessionService.listChats(id, skip), chat => chat.id);
    return paginate(visible, limit ? parseInt(limit, 10) : undefined, skip);
  }

  @ChatScoped('fenced')
  @Post(':sessionId/chats/read')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: 'Mark a chat as read/seen' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description:
      'Returns `{ success }`. `false` means the engine declined to act: the Baileys engine sends the ' +
      'read receipt against the newest message the chat received that it holds in memory, else the ' +
      'newest received one the gateway stored, so a chat with neither (one holding only the ' +
      "account's own sends included) is reported as declined rather than marked read. The " +
      'whatsapp-web.js engine reads the chat from the page and needs no local history.',
    type: SessionActionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'Session not ready' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 503,
    description:
      'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
      'the gateway stopped waiting for a confirmation that never came.',
  })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  async markChatRead(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: MarkChatReadDto,
  ): Promise<{ success: boolean }> {
    const success = await this.sessionService.sendSeen(id, dto.chatId, dto.messageIds);
    return { success };
  }

  @ChatScoped('fenced')
  @Post(':sessionId/presence/subscribe')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({
    summary: "Subscribe to a chat's presence",
    description:
      'Asks WhatsApp to start reporting who is online or typing in this chat. Updates arrive as the ' +
      '`presence.update` webhook and socket event — there is no synchronous answer, because presence ' +
      'cannot be queried from either engine, only received.\n\n' +
      'The subscription belongs to the connection: it does **not** survive a restart or an automatic ' +
      'reconnect, and must be re-issued. Subscribe per chat rather than to everything — WhatsApp emits ' +
      'an update on every transition, so a broad subscription is a firehose.\n\n' +
      'whatsapp-web.js cannot do this at all (it exposes no presence subscribe and emits no presence ' +
      'event) and answers `501`.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description: 'Subscribed; updates now arrive as presence.update events',
    type: SessionActionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'Session not started' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({ status: 501, description: 'The active engine cannot observe presence (whatsapp-web.js)' })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
  async subscribeToPresence(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: SubscribePresenceDto,
  ): Promise<{ success: boolean }> {
    await this.sessionService.subscribeToPresence(id, dto.chatId);
    return { success: true };
  }

  @Put(':sessionId/presence')
  @RequireRole(ApiKeyRole.OPERATOR)
  @ApiOperation({
    summary: "Set the account's own global presence (appear online or offline)",
    description:
      'Publishes whether this account appears online. WhatsApp routes notifications away from the ' +
      'phone while a linked device announces itself online, so a headless bot that never goes ' +
      "offline suppresses the phone's own alerts — set `available: false` to hand them back.\n\n" +
      'A successful call is remembered for the life of the running engine and re-applied once each ' +
      'time that connection opens, including a Baileys transient reconnect: the socket announces ' +
      'itself on connect (`available` unless `BAILEYS_MARK_ONLINE_ON_CONNECT=false`), which would ' +
      "otherwise replace the caller's choice. The preference is dropped whenever the gateway replaces " +
      'the engine: stop, restart, reconnect recovery, a watchdog recycle, or a takeover by another ' +
      'node. Re-issue it after `session.status` reports `ready` again. On Baileys, typing, recording ' +
      'and outbound sends do not publish global presence.\n\n' +
      'On Baileys the call fails with 409 when the account push name has not synced yet — the ' +
      'library would otherwise accept the request and send nothing. Supported on both engines.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({ status: 200, description: 'Presence published', type: SessionActionResponseDto })
  @ApiResponse({ status: 400, description: 'Session not started, or validation failed' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 409,
    description:
      ENGINE_NOT_READY_409 +
      ' On Baileys this route also answers `409` for a `ready` session whose account push name has ' +
      'not synced yet. Nothing was sent, and a retry succeeds only once the name has synced.',
  })
  @ApiResponse({
    status: 503,
    description:
      'The whatsapp-web.js page connection died, or WhatsApp Web did not answer within the protocol ' +
      'timeout. Nothing was confirmed; setting presence converges when repeated, so a retry is safe.',
  })
  async setOnlinePresence(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: SetOwnPresenceDto,
  ): Promise<{ success: boolean }> {
    await this.sessionService.setOnlinePresence(id, dto.available);
    return { success: true };
  }

  @ChatScoped('fenced')
  @Get(':sessionId/presence/:chatId')
  @RequireRole(ApiKeyRole.VIEWER)
  @ApiOperation({
    summary: "Read a chat's last reported presence",
    description:
      'Serves the most recent report received since the chat was subscribed. Returns `null` when ' +
      'nothing has been reported — either the chat was never subscribed, or nothing has changed ' +
      'since. That is a normal state, not a missing resource, so it is `200` with a null body rather ' +
      'than a `404`.\n\n' +
      'Held in memory and never persisted: presence is short-lived, and answering "typing" from ' +
      'before a restart would be worse than answering nothing.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiParam({ name: 'chatId', description: 'Chat ID as subscribed' })
  @ApiExtraModels(ChatPresenceResponseDto)
  @ApiResponse({
    status: 200,
    description: 'Last reported presence, or null',
    schema: { nullable: true, allOf: [{ $ref: getSchemaPath(ChatPresenceResponseDto) }] },
  })
  @ApiResponse({ status: 400, description: 'The session id is not a UUID' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  async getPresence(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Param('chatId') chatId: string,
    @Res() res: Response,
  ): Promise<void> {
    const presence = await this.sessionService.getPresence(id, chatId);
    const body: ChatPresenceResponseDto | null = presence
      ? { ...presence, observedAt: new Date(presence.observedAt) }
      : null;
    // Written directly: Nest answers a returned null with an empty body, not the JSON `null` above.
    res.json(body);
  }

  @ChatScoped('fenced')
  @Post(':sessionId/chats/unread')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: 'Mark a chat as unread' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description:
      'Returns `{ success }`. `false` means the engine declined to act. The Baileys engine keys the mark ' +
      "to the chat's newest message in memory, else the newest stored one, else sends it without one for a " +
      'chat the session knows; an id it knows no chat for answers `false`, and so does an archived chat ' +
      'with no known message, which the phone leaves unmarked without one.',
    type: SessionActionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'Session not ready' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 503,
    description:
      'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
      'the gateway stopped waiting for a confirmation that never came.',
  })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  async markChatUnread(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: MarkChatUnreadDto,
  ): Promise<{ success: boolean }> {
    const success = await this.sessionService.markUnread(id, dto.chatId);
    return { success };
  }

  @ChatScoped('fenced')
  @Delete(':sessionId/chats/:chatId/messages')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({
    summary: 'Delete every message in a chat, keeping the chat itself',
    description:
      "On success the gateway also removes its stored copies of the chat's messages (rows, inline and archived " +
      'media, search entries) and emits `message:deleted` for each. Changes made on the phone are not mirrored.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiParam({ name: 'chatId', description: "Chat JID, e.g. [email protected] (URL-encode the '@')" })
  @ApiResponse({
    status: 200,
    description:
      'Returns `{ success }`. `false` means the engine declined to act — an unknown chat, or on the ' +
      'Baileys engine a chat with no message in memory or stored, since the clear is keyed to its ' +
      'last message.',
    type: SessionActionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'Session not ready' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 503,
    description:
      'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
      'the gateway stopped waiting for a confirmation that never came.',
  })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  async clearChatMessages(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Param('chatId') chatId: string,
  ): Promise<{ success: boolean }> {
    const success = await this.sessionService.clearChatMessages(id, chatId);
    return { success };
  }

  @ChatScoped('fenced')
  @Post(':sessionId/chats/archive')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: 'Archive or unarchive a chat' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description:
      'Returns `{ success }`. `false` means the engine declined to act. The Baileys engine keys the ' +
      "change to the chat's newest message in memory, else the newest stored one, else sends it " +
      'without one, which WhatsApp applies as well, for a chat the session knows; an id it knows no ' +
      'chat for answers `false`.',
    type: SessionActionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'Session not ready' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 503,
    description:
      'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
      'the gateway stopped waiting for a confirmation that never came.',
  })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  async archiveChat(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: ArchiveChatDto,
  ): Promise<{ success: boolean }> {
    const success = await this.sessionService.archiveChat(id, dto.chatId, dto.archive);
    return { success };
  }

  @ChatScoped('fenced')
  @Post(':sessionId/chats/mute')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: 'Mute or unmute a chat' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description:
      'Returns `{ success: true }`. Unlike the archive route there is no declined outcome: the mute ' +
      "change is not keyed to the chat's last message on either engine, so a chat with no known " +
      'history mutes like any other.',
    type: SessionActionResponseDto,
  })
  @ApiResponse({
    status: 400,
    description:
      'Session not ready, an invalid chatId / muteUntil, or a chatId the whatsapp-web.js engine ' +
      'cannot resolve. The Baileys engine writes the mute without resolving the chat first and ' +
      'answers `success: true` for a chat that does not exist.',
  })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 503,
    description:
      'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
      'the gateway stopped waiting for a confirmation that never came.',
  })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  async muteChat(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: MuteChatDto,
  ): Promise<{ success: boolean }> {
    await this.sessionService.muteChat(id, dto.chatId, dto.muteUntil);
    return { success: true };
  }

  @ChatScoped('fenced')
  @Post(':sessionId/chats/pin')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: 'Pin or unpin a chat at the top of the chat list' })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description:
      'Returns `{ success }`. `false` means the engine declined, and only a pin can: WhatsApp allows ' +
      'at most three pinned chats and the whatsapp-web.js engine reports the refusal. Unpinning always ' +
      'succeeds, and the Baileys engine always reports success because it cannot observe the cap.',
    type: SessionActionResponseDto,
  })
  @ApiResponse({
    status: 400,
    description:
      'Session not ready, or a chatId the session cannot resolve. An unknown chat is reported here ' +
      'rather than as `success: false`, which on this route means only that the three-pin cap ' +
      'refused a real chat. The Baileys engine cannot resolve chats ahead of the write and answers ' +
      '`success: true` for an unknown chat.',
  })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 503,
    description:
      'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
      'the gateway stopped waiting for a confirmation that never came.',
  })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  async pinChat(@Param('sessionId', ParseUUIDPipe) id: string, @Body() dto: PinChatDto): Promise<{ success: boolean }> {
    const success = await this.sessionService.pinChat(id, dto.chatId, dto.pin);
    return { success };
  }

  @ChatScoped('fenced')
  @Post(':sessionId/chats/delete')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({
    summary: 'Delete a chat from the chat list (e.g. a group you have left)',
    description:
      "On success the gateway also removes its stored copies of the chat's messages (rows, inline and archived " +
      'media, search entries) and emits `message:deleted` for each. Changes made on the phone are not mirrored.',
  })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({
    status: 200,
    description:
      'Returns `{ success }`. `false` means the engine declined to act: an unknown chat, or on the ' +
      'Baileys engine a chat with no message in memory or stored, since the delete is keyed to its ' +
      'last message.',
    type: SessionActionResponseDto,
  })
  @ApiResponse({ status: 400, description: 'Session not ready' })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({
    status: 503,
    description:
      'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
      'the gateway stopped waiting for a confirmation that never came.',
  })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  async deleteChat(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: DeleteChatDto,
  ): Promise<{ success: boolean }> {
    const success = await this.sessionService.deleteChat(id, dto.chatId);
    return { success };
  }

  @ChatScoped('fenced')
  @Post(':sessionId/chats/typing')
  @RequireRole(ApiKeyRole.OPERATOR)
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: "Send a typing/recording presence indicator to a chat (or clear it with 'paused')" })
  @ApiParam({ name: 'sessionId', description: 'Session ID' })
  @ApiResponse({ status: 200, description: 'Presence sent', type: SessionActionResponseDto })
  @ApiResponse({
    status: 400,
    description:
      'Session is not started, or validation failed (an empty chatId, a state other than typing, ' +
      'recording or paused, or a body field the DTO does not declare).',
  })
  @ApiResponse({ status: 404, description: 'Session not found' })
  @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
  async sendChatState(
    @Param('sessionId', ParseUUIDPipe) id: string,
    @Body() dto: SendChatStateDto,
  ): Promise<{ success: boolean }> {
    await this.sessionService.sendChatState(id, dto.chatId, dto.state);
    return { success: true };
  }

  @Get('stats/overview')
  @ApiOperation({
    summary: 'Get session statistics for multi-session monitoring',
  })
  @ApiResponse({
    status: 200,
    description: 'Session statistics including counts and memory usage',
    type: SessionsOverviewResponseDto,
  })
  async getStats(@CurrentApiKey() apiKey?: ApiKey): Promise<{
    total: number;
    active: number;
    ready: number;
    disconnected: number;
    byStatus: Record<string, number>;
    memoryUsage: { heapUsed: number; heapTotal: number; rss: number };
  }> {
    // Scope aggregate stats to the key's allowedSessions so a session-restricted key cannot enumerate
    // global session counts/status (the route carries no :sessionId for the guard to scope against).
    return this.sessionService.getStats(apiKey?.allowedSessions);
  }
}