Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

5.5 KB
Raw Blame
import { Controller, Get, Query, BadRequestException } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse, ApiQuery } from '@nestjs/swagger';
import { SearchResultsResponseDto } from './dto/search-response.dto';
import { ChatScoped, CurrentApiKey, RequireRole } from '../auth/decorators/auth.decorators';
import { ChatScopeService } from '../auth/chat-scope.service';
import { ApiKey, ApiKeyRole } from '../auth/entities/api-key.entity';
import { SearchService } from './search.service';
import { SearchQueryDto } from './dto/search-query.dto';
import {
  SEARCH_CONTAINS_TERMS_MAX_LENGTH,
  SEARCH_CONTAINS_WINDOW,
  SEARCH_MATCH_MODES,
  SEARCH_OFFSET_MAX,
} from './search.constants';
import type { SearchResults } from './search.types';

@ApiTags('search')
@Controller('search')
export class SearchController {
  constructor(
    private readonly searchService: SearchService,
    private readonly chatScope: ChatScopeService,
  ) {}

  @ChatScoped('filtered')
  @Get()
  @RequireRole(ApiKeyRole.OPERATOR)
  @ApiOperation({ summary: 'Search messages across sessions (active search provider)' })
  @ApiResponse({ status: 200, description: 'Search results from the active provider', type: SearchResultsResponseDto })
  @ApiResponse({
    status: 400,
    description:
      'Empty or whitespace-only "q", or one over 1000 characters or 32 words or holding a NUL character; an ' +
      'unknown "match"; or a "match=contains" query with no term of 3 or more characters (on PostgreSQL, 3 ' +
      `letters or digits in a row) or with more than ${SEARCH_CONTAINS_TERMS_MAX_LENGTH} characters in its terms`,
  })
  @ApiResponse({ status: 403, description: 'Chat scope denied or chat-restricted search uses a plugin provider' })
  @ApiResponse({
    status: 501,
    description:
      'No search provider configured, or the built-in provider lacks the index the requested match mode needs ' +
      '(for "match=contains": SEARCH_CONTAINS_ENABLED=true and a finished index build, and on PostgreSQL the ' +
      'pg_trgm and unaccent extensions)',
  })
  @ApiResponse({
    status: 502,
    description:
      'The active plugin search provider returned a result shape that failed validation, so nothing ' +
      'trustworthy could be forwarded. The built-in provider never returns this.',
  })
  @ApiResponse({
    status: 503,
    description:
      'The active plugin search provider did not answer: its worker is not running, timed out, or reported ' +
      'a failure. The built-in provider never returns this. Retryable.',
  })
  @ApiQuery({
    name: 'q',
    required: true,
    description: 'Search term (required, non-empty, at most 1000 characters and 32 words, no NUL character)',
  })
  @ApiQuery({
    name: 'match',
    required: false,
    enum: SEARCH_MATCH_MODES,
    description:
      'word (default): whole words. contains: any part of a word, ignoring case and accents; ranks the ' +
      `${SEARCH_CONTAINS_WINDOW} most recently stored matches by match quality; needs SEARCH_CONTAINS_ENABLED=true, ` +
      `a term of 3 or more characters and at most ${SEARCH_CONTAINS_TERMS_MAX_LENGTH} characters in all its terms`,
  })
  @ApiQuery({ name: 'sessionId', required: false, description: 'Restrict to a single session' })
  @ApiQuery({
    name: 'chatId',
    required: false,
    description:
      "Restrict to a single chat id. With the built-in search provider, a phone also matches the chat's other stored forms (the other user dialect and any lid that resolves to it); a plugin provider receives the id as sent.",
  })
  @ApiQuery({ name: 'direction', required: false, description: 'incoming | outgoing' })
  @ApiQuery({ name: 'type', required: false, description: 'Message type filter' })
  @ApiQuery({
    name: 'from',
    required: false,
    description:
      "Sender filter. With the built-in search provider, matches `from` or a group message's `author`, and a phone also matches any lid that resolves to it; a plugin provider receives the id as sent.",
  })
  @ApiQuery({ name: 'dateFrom', required: false, description: 'Epoch-ms lower bound (inclusive)' })
  @ApiQuery({ name: 'dateTo', required: false, description: 'Epoch-ms upper bound (inclusive)' })
  @ApiQuery({ name: 'limit', required: false, type: 'integer', description: 'Max hits to return' })
  @ApiQuery({
    name: 'offset',
    required: false,
    type: 'integer',
    description: `Pagination offset, at most ${SEARCH_OFFSET_MAX}`,
  })
  async search(@Query() dto: SearchQueryDto, @CurrentApiKey() apiKey?: ApiKey): Promise<SearchResults> {
    if (!dto.q || !dto.q.trim()) {
      throw new BadRequestException('Query parameter "q" is required and must be non-empty.');
    }
    // callerSessionIds comes ONLY from the authenticated key's allowedSessions — never from the
    // query/body — so a scoped key cannot broaden its reach; the same holds for the chat scope,
    // expanded lid-aware here and applied inside the providers BEFORE limit/offset/total. A null/empty
    // session allowlist (e.g. ADMIN) resolves to undefined → searches all sessions, mirroring GET
    // /webhooks. The DTO carries no `sessionIds` or `chatIds` field (the global ValidationPipe's
    // forbidNonWhitelisted would reject it anyway), and SearchService makes both scopes authoritative
    // by overwriting them at the provider boundary. An optional `?chatId=` is additionally fenced by
    // the guard against the key's allowlist, so a restricted key cannot name another chat either.
    const chatIds = await this.chatScope.idsForFilter(apiKey);
    return this.searchService.search(dto, apiKey?.allowedSessions ?? undefined, chatIds);
  }
}