mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases 2 Wiki Activity

docs(brain): add JSDoc documentation

Browse Source
This commit is contained in:
Jason Woltje
2026-01-29 21:29:53 -06:00
parent f3bcb46ccd
commit 0bd12b5751
4 changed files with 142 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
apps/api/src/brain/brain.controller.ts
View File

@@ -12,11 +12,25 @@ import { AuthGuard } from "../auth/guards/auth.guard";
import { WorkspaceGuard, PermissionGuard } from "../common/guards";
import { Workspace, Permission, RequirePermission } from "../common/decorators";
/**
* @description Controller for AI/brain operations on workspace data.
* Provides endpoints for querying, searching, and getting context across
* tasks, events, and projects within a workspace.
*/
@Controller("brain")
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
export class BrainController {
constructor(private readonly brainService: BrainService) {}
/**
* @description Query workspace entities with flexible filtering options.
* Allows filtering tasks, events, and projects by various criteria.
* @param queryDto - Query parameters including entity types, filters, and search term
* @param workspaceId - The workspace ID (injected from request context)
* @returns Filtered tasks, events, and projects with metadata
* @throws UnauthorizedException if user lacks workspace access
* @throws ForbiddenException if user lacks required permissions
*/
@Post("query")
@RequirePermission(Permission.WORKSPACE_ANY)
async query(
@@ -26,6 +40,16 @@ export class BrainController {
return this.brainService.query({ ...queryDto, workspaceId });
}
/**
* @description Get current workspace context for AI operations.
* Returns a summary of active tasks, overdue items, upcoming events, and projects.
* @param contextDto - Context options specifying which entities to include
* @param workspaceId - The workspace ID (injected from request context)
* @returns Workspace context with summary counts and optional detailed entity lists
* @throws UnauthorizedException if user lacks workspace access
* @throws ForbiddenException if user lacks required permissions
* @throws NotFoundException if workspace does not exist
*/
@Get("context")
@RequirePermission(Permission.WORKSPACE_ANY)
async getContext(
@@ -35,6 +59,16 @@ export class BrainController {
return this.brainService.getContext({ ...contextDto, workspaceId });
}
/**
* @description Search across all workspace entities by text.
* Performs case-insensitive search on titles, descriptions, and locations.
* @param searchTerm - Text to search for across all entity types
* @param limit - Maximum number of results per entity type (max: 100, default: 20)
* @param workspaceId - The workspace ID (injected from request context)
* @returns Matching tasks, events, and projects with metadata
* @throws UnauthorizedException if user lacks workspace access
* @throws ForbiddenException if user lacks required permissions
*/
@Get("search")
@RequirePermission(Permission.WORKSPACE_ANY)
async search(

28
apps/api/src/brain/brain.service.ts
View File

@@ -80,10 +80,21 @@ export interface BrainContext {
}>;
}
/**
* @description Service for querying and aggregating workspace data for AI/brain operations.
* Provides unified access to tasks, events, and projects with filtering and search capabilities.
*/
@Injectable()
export class BrainService {
constructor(private readonly prisma: PrismaService) {}
/**
* @description Query workspace entities with flexible filtering options.
* Retrieves tasks, events, and/or projects based on specified criteria.
* @param queryDto - Query parameters including workspaceId, entity types, filters, and search term
* @returns Filtered tasks, events, and projects with metadata about the query
* @throws PrismaClientKnownRequestError if database query fails
*/
async query(queryDto: BrainQueryDto): Promise<BrainQueryResult> {
const { workspaceId, entities, search, limit = 20 } = queryDto;
const includeEntities = entities || [EntityType.TASK, EntityType.EVENT, EntityType.PROJECT];
@@ -115,6 +126,14 @@ export class BrainService {
};
}
/**
* @description Get current workspace context for AI operations.
* Provides a summary of active tasks, overdue items, upcoming events, and projects.
* @param contextDto - Context options including workspaceId and which entities to include
* @returns Workspace context with summary counts and optional detailed entity lists
* @throws NotFoundError if workspace does not exist
* @throws PrismaClientKnownRequestError if database query fails
*/
async getContext(contextDto: BrainContextDto): Promise<BrainContext> {
const {
workspaceId,
@@ -203,6 +222,15 @@ export class BrainService {
return context;
}
/**
* @description Search across all workspace entities by text.
* Performs case-insensitive search on titles, descriptions, and locations.
* @param workspaceId - The workspace to search within
* @param searchTerm - Text to search for across all entity types
* @param limit - Maximum number of results per entity type (default: 20)
* @returns Matching tasks, events, and projects with metadata
* @throws PrismaClientKnownRequestError if database query fails
*/
async search(workspaceId: string, searchTerm: string, limit: number = 20): Promise<BrainQueryResult> {
const [tasks, events, projects] = await Promise.all([
this.queryTasks(workspaceId, undefined, searchTerm, limit),