stack/apps/api/src/knowledge/search.controller.ts

import { Controller, Get, Post, Body, Query, UseGuards } from "@nestjs/common";
import { SearchService, PaginatedSearchResults } from "./services/search.service";
import {
  SearchQueryDto,
  TagSearchDto,
  RecentEntriesDto,
  SemanticSearchBodyDto,
  SemanticSearchQueryDto,
  HybridSearchBodyDto,
} from "./dto";
import { AuthGuard } from "../auth/guards/auth.guard";
import { WorkspaceGuard, PermissionGuard } from "../common/guards";
import { Workspace, Permission, RequirePermission } from "../common/decorators";
import type { PaginatedEntries, KnowledgeEntryWithTags } from "./entities/knowledge-entry.entity";

/**
 * Response for recent entries endpoint
 */
interface RecentEntriesResponse {
  data: KnowledgeEntryWithTags[];
  count: number;
}

/**
 * Controller for knowledge search endpoints
 * All endpoints require authentication and workspace context
 */
@Controller("knowledge/search")
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
export class SearchController {
  constructor(private readonly searchService: SearchService) {}

  /**
   * GET /api/knowledge/search
   * Full-text search across knowledge entries
   * Searches title and content with relevance ranking
   * Requires: Any workspace member
   *
   * @query q - The search query string (required)
   * @query tags - Comma-separated tag slugs to filter by (optional, entries must have ALL tags)
   * @query status - Filter by entry status (optional)
   * @query page - Page number (default: 1)
   * @query limit - Results per page (default: 20, max: 100)
   */
  @Get()
  @RequirePermission(Permission.WORKSPACE_ANY)
  async search(
    @Workspace() workspaceId: string,
    @Query() query: SearchQueryDto
  ): Promise<PaginatedSearchResults> {
    return this.searchService.search(query.q, workspaceId, {
      status: query.status,
      page: query.page,
      limit: query.limit,
      tags: query.tags,
    });
  }

  /**
   * GET /api/knowledge/search/by-tags
   * Search entries by tags (entries must have ALL specified tags)
   * Requires: Any workspace member
   *
   * @query tags - Comma-separated list of tag slugs (required)
   * @query status - Filter by entry status (optional)
   * @query page - Page number (default: 1)
   * @query limit - Results per page (default: 20, max: 100)
   */
  @Get("by-tags")
  @RequirePermission(Permission.WORKSPACE_ANY)
  async searchByTags(
    @Workspace() workspaceId: string,
    @Query() query: TagSearchDto
  ): Promise<PaginatedEntries> {
    return this.searchService.searchByTags(query.tags, workspaceId, {
      status: query.status,
      page: query.page,
      limit: query.limit,
    });
  }

  /**
   * GET /api/knowledge/search/recent
   * Get recently modified entries
   * Requires: Any workspace member
   *
   * @query limit - Maximum number of entries (default: 10, max: 50)
   * @query status - Filter by entry status (optional)
   */
  @Get("recent")
  @RequirePermission(Permission.WORKSPACE_ANY)
  async recentEntries(
    @Workspace() workspaceId: string,
    @Query() query: RecentEntriesDto
  ): Promise<RecentEntriesResponse> {
    const entries = await this.searchService.recentEntries(
      workspaceId,
      query.limit ?? 10,
      query.status
    );
    return {
      data: entries,
      count: entries.length,
    };
  }

  /**
   * POST /api/knowledge/search/semantic
   * Semantic search using vector similarity
   * Requires: Any workspace member, Ollama configured
   *
   * @body query - The search query string (required)
   * @body status - Filter by entry status (optional)
   * @query page - Page number (default: 1)
   * @query limit - Results per page (default: 20, max: 100)
   */
  @Post("semantic")
  @RequirePermission(Permission.WORKSPACE_ANY)
  async semanticSearch(
    @Workspace() workspaceId: string,
    @Body() body: SemanticSearchBodyDto,
    @Query() query: SemanticSearchQueryDto
  ): Promise<PaginatedSearchResults> {
    return this.searchService.semanticSearch(body.query, workspaceId, {
      status: body.status,
      page: query.page,
      limit: query.limit,
    });
  }

  /**
   * POST /api/knowledge/search/hybrid
   * Hybrid search combining vector similarity and full-text search
   * Uses Reciprocal Rank Fusion to merge results
   * Requires: Any workspace member
   *
   * @body query - The search query string (required)
   * @body status - Filter by entry status (optional)
   * @query page - Page number (default: 1)
   * @query limit - Results per page (default: 20, max: 100)
   */
  @Post("hybrid")
  @RequirePermission(Permission.WORKSPACE_ANY)
  async hybridSearch(
    @Workspace() workspaceId: string,
    @Body() body: HybridSearchBodyDto,
    @Query() query: SemanticSearchQueryDto
  ): Promise<PaginatedSearchResults> {
    return this.searchService.hybridSearch(body.query, workspaceId, {
      status: body.status,
      page: query.page,
      limit: query.limit,
    });
  }
}