// ==========================================
// DOCUMENT ENUMS
// ==========================================

enum DocumentCategory {
  POLICY
  HANDBOOK
  CONTRACT
  PERFORMANCE
  TRAINING
  CERTIFICATE
  PERSONAL
  OTHER
}

cd packages/database
npx prisma format
# Should complete without errors

cat prisma/schema.prisma | grep -A 12 "enum DocumentCategory"
# Should show all enum values

# Remove the enum block from schema.prisma

packages/database/prisma/schema.prisma (DocumentCategory enum)

enum DocumentVisibility {
  PRIVATE      // Only document owner
  TEAM         // Owner's team(s)
  DEPARTMENT   // Owner's department(s)
  MANAGERS     // All employees with manager role
  COMPANY      // All employees in tenant
  CUSTOM       // Use DocumentAccess table for explicit grants
}

cd packages/database
npx prisma format
cat prisma/schema.prisma | grep -A 8 "enum DocumentVisibility"

# Remove DocumentVisibility enum block

packages/database/prisma/schema.prisma (DocumentVisibility enum)

enum AccessType {
  USER
  TEAM
  DEPARTMENT
  ROLE
}

cd packages/database
npx prisma format
cat prisma/schema.prisma | grep -A 6 "enum AccessType"

# Remove AccessType enum block

packages/database/prisma/schema.prisma (AccessType enum)

enum DocumentPermission {
  VIEW
  DOWNLOAD
  EDIT
}

enum DocumentStatus {
  ACTIVE
  ARCHIVED
  DELETED
}

cd packages/database
npx prisma format
cat prisma/schema.prisma | grep -A 5 "enum DocumentPermission"
cat prisma/schema.prisma | grep -A 5 "enum DocumentStatus"

# Remove both enum blocks

packages/database/prisma/schema.prisma (DocumentPermission, DocumentStatus enums)

// ==========================================
// DOCUMENT MODELS
// ==========================================

model Document {
  id           String             @id @default(cuid())
  tenantId     String
  employeeId   String?            // Optional link to employee record
  uploadedById String             // Who uploaded
  title        String
  description  String?
  category     DocumentCategory
  fileUrl      String             // GCS URL
  fileName     String             // Original filename
  mimeType     String
  fileSize     Int                // Bytes
  visibility   DocumentVisibility @default(PRIVATE)
  vectorId     String?            // For future AI search
  indexed      Boolean            @default(false)
  status       DocumentStatus     @default(ACTIVE)
  createdAt    DateTime           @default(now())
  updatedAt    DateTime           @updatedAt

  tenant       Tenant             @relation(fields: [tenantId], references: [id], onDelete: Cascade)

  @@index([tenantId, category])
  @@index([tenantId, visibility])
  @@index([tenantId, uploadedById])
  @@map("documents")
}

// Add to Tenant model
documents Document[]

cd packages/database
npx prisma format
cat prisma/schema.prisma | grep -A 25 "model Document {"

# Remove Document model and Tenant relation

packages/database/prisma/schema.prisma (Document model)

model DocumentAccess {
  id         String             @id @default(cuid())
  documentId String
  accessType AccessType
  targetId   String?            // userId, teamId, departmentId, or roleId
  permission DocumentPermission @default(VIEW)
  grantedBy  String
  grantedAt  DateTime           @default(now())
  expiresAt  DateTime?

  document   Document           @relation(fields: [documentId], references: [id], onDelete: Cascade)

  @@index([documentId])
  @@index([targetId])
  @@map("document_access")
}

// Add to Document model (after tenant relation)
accessGrants DocumentAccess[]

cd packages/database
npx prisma format
cat prisma/schema.prisma | grep -A 15 "model DocumentAccess {"
cat prisma/schema.prisma | grep "accessGrants"

# Remove DocumentAccess model and accessGrants relation

packages/database/prisma/schema.prisma (DocumentAccess model)

cd packages/database
npx prisma migrate dev --name add_document_management

cd packages/database
npx prisma studio
# Open browser, verify Document and DocumentAccess tables exist

# Alternative: check migration file exists
ls -la prisma/migrations/*add_document_management*

cd packages/database
npx prisma migrate reset
# Then re-run migrations

packages/database/prisma/migrations/*add_document_management*

cd apps/api
npm install @google-cloud/storage

# apps/api/.env
GCS_PROJECT_ID=your-project-id
GCS_BUCKET_NAME=hrms-documents
GCS_KEY_FILE=./gcs-service-account.json
# For local development, you can use a service account key file
# For production, use workload identity or default credentials

// apps/api/src/documents/storage.config.ts
import { Storage } from '@google-cloud/storage';

export interface StorageConfig {
  projectId: string;
  bucketName: string;
  keyFilename?: string;
}

export function getStorageConfig(): StorageConfig {
  return {
    projectId: process.env.GCS_PROJECT_ID || '',
    bucketName: process.env.GCS_BUCKET_NAME || 'hrms-documents',
    keyFilename: process.env.GCS_KEY_FILE,
  };
}

export function createStorageClient(): Storage {
  const config = getStorageConfig();

  if (config.keyFilename) {
    return new Storage({
      projectId: config.projectId,
      keyFilename: config.keyFilename,
    });
  }

  // Use default credentials (for Cloud Run, GKE, etc.)
  return new Storage({
    projectId: config.projectId,
  });
}

mkdir -p apps/api/src/documents/repositories
mkdir -p apps/api/src/documents/services
mkdir -p apps/api/src/documents/controllers
mkdir -p apps/api/src/documents/dto

cd apps/api
cat src/documents/storage.config.ts
# Should show storage configuration

npx tsc --noEmit
# Should compile without errors

rm -rf apps/api/src/documents
npm uninstall @google-cloud/storage

apps/api/src/documents/storage.config.ts

import { Injectable, BadRequestException } from '@nestjs/common';
import { createStorageClient, getStorageConfig } from '../storage.config';
import { v4 as uuidv4 } from 'uuid';

const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB
const ALLOWED_MIME_TYPES = [
  'application/pdf',
  'application/msword',
  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
  'application/vnd.ms-excel',
  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  'image/png',
  'image/jpeg',
  'text/plain',
];

export interface UploadResult {
  fileUrl: string;
  fileName: string;
  mimeType: string;
  fileSize: number;
}

@Injectable()
export class UploadService {
  private storage = createStorageClient();
  private config = getStorageConfig();

  async uploadFile(
    file: Express.Multer.File,
    tenantId: string,
  ): Promise<UploadResult> {
    // Validate file size
    if (file.size > MAX_FILE_SIZE) {
      throw new BadRequestException(
        `File size exceeds maximum allowed (${MAX_FILE_SIZE / 1024 / 1024}MB)`,
      );
    }

    // Validate mime type
    if (!ALLOWED_MIME_TYPES.includes(file.mimetype)) {
      throw new BadRequestException(
        `File type not allowed. Allowed types: ${ALLOWED_MIME_TYPES.join(', ')}`,
      );
    }

    // Generate unique filename
    const ext = file.originalname.split('.').pop();
    const uniqueName = `${tenantId}/${uuidv4()}.${ext}`;

    const bucket = this.storage.bucket(this.config.bucketName);
    const blob = bucket.file(uniqueName);

    // Upload to GCS
    await blob.save(file.buffer, {
      metadata: {
        contentType: file.mimetype,
        metadata: {
          originalName: file.originalname,
          tenantId,
        },
      },
    });

    // Get the public URL (or use signed URLs for private access)
    const fileUrl = `gs://${this.config.bucketName}/${uniqueName}`;

    return {
      fileUrl,
      fileName: file.originalname,
      mimeType: file.mimetype,
      fileSize: file.size,
    };
  }

  async getSignedUrl(fileUrl: string, expiresInMinutes = 60): Promise<string> {
    // Extract path from gs:// URL
    const path = fileUrl.replace(`gs://${this.config.bucketName}/`, '');

    const bucket = this.storage.bucket(this.config.bucketName);
    const blob = bucket.file(path);

    const [signedUrl] = await blob.getSignedUrl({
      version: 'v4',
      action: 'read',
      expires: Date.now() + expiresInMinutes * 60 * 1000,
    });

    return signedUrl;
  }

  async deleteFile(fileUrl: string): Promise<void> {
    const path = fileUrl.replace(`gs://${this.config.bucketName}/`, '');

    const bucket = this.storage.bucket(this.config.bucketName);
    const blob = bucket.file(path);

    await blob.delete();
  }
}

cd apps/api
npm install uuid
npm install -D @types/uuid

cd apps/api
cat src/documents/services/upload.service.ts
npx tsc --noEmit
# Should compile without errors

rm apps/api/src/documents/services/upload.service.ts

apps/api/src/documents/services/upload.service.ts

import { Injectable } from '@nestjs/common';
import { PrismaService } from '../../prisma/prisma.service';
import {
  Prisma,
  Document,
  DocumentCategory,
  DocumentVisibility,
  DocumentStatus,
} from '@prisma/client';

export interface DocumentWithAccess extends Document {
  accessGrants?: {
    id: string;
    accessType: string;
    targetId: string | null;
    permission: string;
    expiresAt: Date | null;
  }[];
}

export interface DocumentQueryOptions {
  category?: DocumentCategory;
  visibility?: DocumentVisibility;
  status?: DocumentStatus;
  uploadedById?: string;
  search?: string;
  page?: number;
  limit?: number;
}

@Injectable()
export class DocumentRepository {
  constructor(private prisma: PrismaService) {}

  async create(
    data: Prisma.DocumentCreateInput,
  ): Promise<Document> {
    return this.prisma.document.create({ data });
  }

  async findById(
    tenantId: string,
    id: string,
  ): Promise<DocumentWithAccess | null> {
    return this.prisma.document.findFirst({
      where: {
        id,
        tenantId,
        status: { not: 'DELETED' },
      },
      include: {
        accessGrants: {
          where: {
            OR: [
              { expiresAt: null },
              { expiresAt: { gt: new Date() } },
            ],
          },
        },
      },
    });
  }

  async findByTenant(
    tenantId: string,
    options: DocumentQueryOptions = {},
  ): Promise<{ items: Document[]; total: number }> {
    const {
      category,
      visibility,
      status = 'ACTIVE',
      uploadedById,
      search,
      page = 1,
      limit = 20,
    } = options;

    const where: Prisma.DocumentWhereInput = {
      tenantId,
      status,
      ...(category && { category }),
      ...(visibility && { visibility }),
      ...(uploadedById && { uploadedById }),
      ...(search && {
        OR: [
          { title: { contains: search, mode: 'insensitive' } },
          { description: { contains: search, mode: 'insensitive' } },
          { fileName: { contains: search, mode: 'insensitive' } },
        ],
      }),
    };

    const [items, total] = await Promise.all([
      this.prisma.document.findMany({
        where,
        orderBy: { createdAt: 'desc' },
        skip: (page - 1) * limit,
        take: limit,
      }),
      this.prisma.document.count({ where }),
    ]);

    return { items, total };
  }

  async findAccessibleByUser(
    tenantId: string,
    userId: string,
    userTeamIds: string[],
    userDepartmentIds: string[],
    userRoleIds: string[],
    isManager: boolean,
    options: DocumentQueryOptions = {},
  ): Promise<{ items: Document[]; total: number }> {
    const {
      category,
      search,
      page = 1,
      limit = 20,
    } = options;

    // Pre-fetch dependent data (can't await inside array literal)
    const teamUploaderIds = userTeamIds.length > 0
      ? await this.getUploadersInTeams(tenantId, userTeamIds)
      : [];
    const deptUploaderIds = userDepartmentIds.length > 0
      ? await this.getUploadersInDepartments(tenantId, userDepartmentIds)
      : [];

    // Build visibility conditions
    const visibilityConditions: Prisma.DocumentWhereInput[] = [
      // Documents uploaded by the user
      { uploadedById: userId },
      // COMPANY visibility - all can see
      { visibility: 'COMPANY' },
      // MANAGERS visibility - if user is a manager
      ...(isManager ? [{ visibility: 'MANAGERS' as DocumentVisibility }] : []),
      // TEAM visibility - if user is in the same team as uploader
      ...(teamUploaderIds.length > 0 ? [{
        visibility: 'TEAM' as DocumentVisibility,
        uploadedById: { in: teamUploaderIds },
      }] : []),
      // DEPARTMENT visibility - if user is in the same department as uploader
      ...(deptUploaderIds.length > 0 ? [{
        visibility: 'DEPARTMENT' as DocumentVisibility,
        uploadedById: { in: deptUploaderIds },
      }] : []),
      // CUSTOM visibility - check DocumentAccess grants
      {
        visibility: 'CUSTOM',
        accessGrants: {
          some: {
            AND: [
              {
                OR: [
                  { accessType: 'USER', targetId: userId },
                  { accessType: 'TEAM', targetId: { in: userTeamIds } },
                  { accessType: 'DEPARTMENT', targetId: { in: userDepartmentIds } },
                  { accessType: 'ROLE', targetId: { in: userRoleIds } },
                ],
              },
              {
                OR: [
                  { expiresAt: null },
                  { expiresAt: { gt: new Date() } },
                ],
              },
            ],
          },
        },
      },
    ];

    // Build the main where clause
    // Note: When using OR for visibility AND search, we need to structure carefully
    const baseWhere: Prisma.DocumentWhereInput = {
      tenantId,
      status: 'ACTIVE',
      OR: visibilityConditions,
      ...(category && { category }),
    };

    // If search is provided, add it as an AND condition
    const where: Prisma.DocumentWhereInput = search
      ? {
          AND: [
            baseWhere,
            {
              OR: [
                { title: { contains: search, mode: 'insensitive' } },
                { description: { contains: search, mode: 'insensitive' } },
              ],
            },
          ],
        }
      : baseWhere;

    const [items, total] = await Promise.all([
      this.prisma.document.findMany({
        where,
        orderBy: { createdAt: 'desc' },
        skip: (page - 1) * limit,
        take: limit,
      }),
      this.prisma.document.count({ where }),
    ]);

    return { items, total };
  }

  private async getUploadersInTeams(
    tenantId: string,
    teamIds: string[],
  ): Promise<string[]> {
    // Find all employees in the given teams, return their associated user IDs
    // Note: This assumes Employee has a relation to User via some identifier
    // The uploadedById in Document should match the authenticated user's ID
    const teamMembers = await this.prisma.employeeTeam.findMany({
      where: { teamId: { in: teamIds } },
      select: {
        employee: {
          select: { id: true, email: true }
        }
      },
    });
    // Return employee IDs as uploader identifiers
    // In production, this should map to the user ID from your auth system
    return teamMembers.map((tm) => tm.employee.id);
  }

  private async getUploadersInDepartments(
    tenantId: string,
    departmentIds: string[],
  ): Promise<string[]> {
    const deptMembers = await this.prisma.employeeDepartment.findMany({
      where: { departmentId: { in: departmentIds } },
      select: {
        employee: {
          select: { id: true, email: true }
        }
      },
    });
    // Return employee IDs as uploader identifiers
    return deptMembers.map((dm) => dm.employee.id);
  }

  async update(
    tenantId: string,
    id: string,
    data: Prisma.DocumentUpdateInput,
  ): Promise<Document> {
    // Use updateMany to enforce tenant isolation
    const result = await this.prisma.document.updateMany({
      where: { id, tenantId },
      data,
    });

    if (result.count === 0) {
      throw new NotFoundException(`Document ${id} not found`);
    }

    return this.findById(tenantId, id);
  }

  async softDelete(tenantId: string, id: string): Promise<void> {
    // Use updateMany to enforce tenant isolation
    const result = await this.prisma.document.updateMany({
      where: { id, tenantId },
      data: { status: 'DELETED' },
    });

    if (result.count === 0) {
      throw new NotFoundException(`Document ${id} not found`);
    }
  }
}

cd apps/api
cat src/documents/repositories/document.repository.ts
npx tsc --noEmit

rm apps/api/src/documents/repositories/document.repository.ts

apps/api/src/documents/repositories/document.repository.ts

import { Injectable } from '@nestjs/common';
import { PrismaService } from '../../prisma/prisma.service';
import {
  Document,
  DocumentAccess,
  DocumentPermission,
  DocumentVisibility,
  AccessType,
} from '@prisma/client';

export interface UserContext {
  userId: string;
  employeeId: string;
  teamIds: string[];
  departmentIds: string[];
  roleIds: string[];
  isManager: boolean;
}

@Injectable()
export class DocumentAccessService {
  constructor(private prisma: PrismaService) {}

  async canView(
    document: Document,
    user: UserContext,
  ): Promise<boolean> {
    return this.checkPermission(document, user, 'VIEW');
  }

  async canDownload(
    document: Document,
    user: UserContext,
  ): Promise<boolean> {
    return this.checkPermission(document, user, 'DOWNLOAD');
  }

  async canEdit(
    document: Document,
    user: UserContext,
  ): Promise<boolean> {
    return this.checkPermission(document, user, 'EDIT');
  }

  async canDelete(
    document: Document,
    user: UserContext,
  ): Promise<boolean> {
    // Only the uploader can delete
    return document.uploadedById === user.userId;
  }

  async canShare(
    document: Document,
    user: UserContext,
  ): Promise<boolean> {
    // Only the uploader or users with EDIT permission can share
    if (document.uploadedById === user.userId) {
      return true;
    }
    return this.checkPermission(document, user, 'EDIT');
  }

  private async checkPermission(
    document: Document,
    user: UserContext,
    requiredPermission: DocumentPermission,
  ): Promise<boolean> {
    // Owner always has all permissions
    if (document.uploadedById === user.userId) {
      return true;
    }

    // Check visibility-based access
    const hasVisibilityAccess = await this.checkVisibilityAccess(
      document,
      user,
    );

    if (hasVisibilityAccess) {
      // Visibility-based access grants VIEW permission by default
      // DOWNLOAD and EDIT require explicit grants for non-owners
      if (requiredPermission === 'VIEW') {
        return true;
      }
    }

    // Check explicit access grants (for CUSTOM visibility or higher permissions)
    if (document.visibility === 'CUSTOM' || requiredPermission !== 'VIEW') {
      return this.checkExplicitAccess(document.id, user, requiredPermission);
    }

    return hasVisibilityAccess;
  }

  private async checkVisibilityAccess(
    document: Document,
    user: UserContext,
  ): Promise<boolean> {
    switch (document.visibility) {
      case 'PRIVATE':
        return false; // Only owner, handled above

      case 'COMPANY':
        return true; // All employees in tenant can view

      case 'MANAGERS':
        return user.isManager;

      case 'TEAM':
        // Check if user is in any of the uploader's teams
        return this.isInSameTeam(document.uploadedById, user.teamIds);

      case 'DEPARTMENT':
        // Check if user is in any of the uploader's departments
        return this.isInSameDepartment(document.uploadedById, user.departmentIds);

      case 'CUSTOM':
        return false; // Must check explicit grants

      default:
        return false;
    }
  }

  private async isInSameTeam(
    uploaderId: string,
    userTeamIds: string[],
  ): Promise<boolean> {
    if (userTeamIds.length === 0) return false;

    // uploaderId is the authenticated user's ID (from session)
    // We need to find if the uploader's employee record shares a team with the current user
    const uploaderTeams = await this.prisma.employeeTeam.findMany({
      where: {
        employee: { id: uploaderId }, // Using employee ID as uploader identifier
        teamId: { in: userTeamIds },
      },
    });

    return uploaderTeams.length > 0;
  }

  private async isInSameDepartment(
    uploaderId: string,
    userDepartmentIds: string[],
  ): Promise<boolean> {
    if (userDepartmentIds.length === 0) return false;

    const uploaderDepts = await this.prisma.employeeDepartment.findMany({
      where: {
        employee: { id: uploaderId }, // Using employee ID as uploader identifier
        departmentId: { in: userDepartmentIds },
      },
    });

    return uploaderDepts.length > 0;
  }

  private async checkExplicitAccess(
    documentId: string,
    user: UserContext,
    requiredPermission: DocumentPermission,
  ): Promise<boolean> {
    const permissionHierarchy: DocumentPermission[] = ['VIEW', 'DOWNLOAD', 'EDIT'];
    const requiredIndex = permissionHierarchy.indexOf(requiredPermission);

    const grants = await this.prisma.documentAccess.findMany({
      where: {
        documentId,
        AND: [
          {
            OR: [
              { accessType: 'USER', targetId: user.userId },
              { accessType: 'TEAM', targetId: { in: user.teamIds } },
              { accessType: 'DEPARTMENT', targetId: { in: user.departmentIds } },
              { accessType: 'ROLE', targetId: { in: user.roleIds } },
            ],
          },
          {
            OR: [
              { expiresAt: null },
              { expiresAt: { gt: new Date() } },
            ],
          },
        ],
      },
    });

    // Check if any grant meets the required permission level
    return grants.some((grant) => {
      const grantIndex = permissionHierarchy.indexOf(grant.permission);
      return grantIndex >= requiredIndex;
    });
  }

  async grantAccess(
    documentId: string,
    accessType: AccessType,
    targetId: string,
    permission: DocumentPermission,
    grantedBy: string,
    expiresAt?: Date,
  ): Promise<DocumentAccess> {
    // Check if grant already exists
    const existing = await this.prisma.documentAccess.findFirst({
      where: {
        documentId,
        accessType,
        targetId,
      },
    });

    if (existing) {
      // Update existing grant
      return this.prisma.documentAccess.update({
        where: { id: existing.id },
        data: { permission, expiresAt },
      });
    }

    // Create new grant
    return this.prisma.documentAccess.create({
      data: {
        documentId,
        accessType,
        targetId,
        permission,
        grantedBy,
        expiresAt,
      },
    });
  }

  async revokeAccess(
    documentId: string,
    accessType: AccessType,
    targetId: string,
  ): Promise<void> {
    await this.prisma.documentAccess.deleteMany({
      where: {
        documentId,
        accessType,
        targetId,
      },
    });
  }

  async getAccessGrants(documentId: string): Promise<DocumentAccess[]> {
    return this.prisma.documentAccess.findMany({
      where: {
        documentId,
        OR: [
          { expiresAt: null },
          { expiresAt: { gt: new Date() } },
        ],
      },
    });
  }
}

cd apps/api
cat src/documents/services/document-access.service.ts
npx tsc --noEmit

rm apps/api/src/documents/services/document-access.service.ts

apps/api/src/documents/services/document-access.service.ts

import {
  Injectable,
  NotFoundException,
  ForbiddenException,
} from '@nestjs/common';
import { DocumentRepository } from '../repositories/document.repository';
import { DocumentAccessService, UserContext } from './document-access.service';
import { UploadService } from './upload.service';
import {
  Document,
  DocumentCategory,
  DocumentVisibility,
  DocumentPermission,
  AccessType,
} from '@prisma/client';

export interface CreateDocumentDto {
  title: string;
  description?: string;
  category: DocumentCategory;
  visibility: DocumentVisibility;
  employeeId?: string;
}

export interface UpdateDocumentDto {
  title?: string;
  description?: string;
  category?: DocumentCategory;
  visibility?: DocumentVisibility;
}

export interface ShareDocumentDto {
  accessType: AccessType;
  targetId: string;
  permission: DocumentPermission;
  expiresAt?: Date;
}

@Injectable()
export class DocumentService {
  constructor(
    private documentRepository: DocumentRepository,
    private accessService: DocumentAccessService,
    private uploadService: UploadService,
  ) {}

  async upload(
    tenantId: string,
    employeeId: string,  // Must be Employee.id, not User.id (for org lookups)
    file: Express.Multer.File,
    dto: CreateDocumentDto,
  ): Promise<Document> {
    // Upload file to GCS
    const uploadResult = await this.uploadService.uploadFile(file, tenantId);

    // Create document record
    // Note: uploadedById stores Employee.id for TEAM/DEPARTMENT visibility checks
    return this.documentRepository.create({
      tenant: { connect: { id: tenantId } },
      uploadedById: employeeId,
      title: dto.title,
      description: dto.description,
      category: dto.category,
      visibility: dto.visibility,
      employeeId: dto.employeeId,
      fileUrl: uploadResult.fileUrl,
      fileName: uploadResult.fileName,
      mimeType: uploadResult.mimeType,
      fileSize: uploadResult.fileSize,
    });
  }

  async findById(
    tenantId: string,
    id: string,
    user: UserContext,
  ): Promise<Document> {
    const document = await this.documentRepository.findById(tenantId, id);

    if (!document) {
      throw new NotFoundException('Document not found');
    }

    const canView = await this.accessService.canView(document, user);
    if (!canView) {
      throw new ForbiddenException('You do not have access to this document');
    }

    return document;
  }

  async findAccessible(
    tenantId: string,
    user: UserContext,
    options: {
      category?: DocumentCategory;
      search?: string;
      page?: number;
      limit?: number;
    } = {},
  ): Promise<{ items: Document[]; total: number; page: number; limit: number; totalPages: number }> {
    const { page = 1, limit = 20 } = options;

    const result = await this.documentRepository.findAccessibleByUser(
      tenantId,
      user.userId,
      user.teamIds,
      user.departmentIds,
      user.roleIds,
      user.isManager,
      options,
    );

    return {
      ...result,
      page,
      limit,
      totalPages: Math.ceil(result.total / limit),
    };
  }

  async findMyDocuments(
    tenantId: string,
    userId: string,
    options: {
      category?: DocumentCategory;
      search?: string;
      page?: number;
      limit?: number;
    } = {},
  ): Promise<{ items: Document[]; total: number; page: number; limit: number; totalPages: number }> {
    const { page = 1, limit = 20 } = options;

    const result = await this.documentRepository.findByTenant(tenantId, {
      ...options,
      uploadedById: userId,
    });

    return {
      ...result,
      page,
      limit,
      totalPages: Math.ceil(result.total / limit),
    };
  }

  async getDownloadUrl(
    tenantId: string,
    id: string,
    user: UserContext,
  ): Promise<string> {
    const document = await this.documentRepository.findById(tenantId, id);

    if (!document) {
      throw new NotFoundException('Document not found');
    }

    const canDownload = await this.accessService.canDownload(document, user);
    if (!canDownload) {
      throw new ForbiddenException('You do not have download access to this document');
    }

    return this.uploadService.getSignedUrl(document.fileUrl);
  }

  async update(
    tenantId: string,
    id: string,
    user: UserContext,
    dto: UpdateDocumentDto,
  ): Promise<Document> {
    const document = await this.documentRepository.findById(tenantId, id);

    if (!document) {
      throw new NotFoundException('Document not found');
    }

    const canEdit = await this.accessService.canEdit(document, user);
    if (!canEdit) {
      throw new ForbiddenException('You do not have edit access to this document');
    }

    return this.documentRepository.update(tenantId, id, dto);
  }

  async delete(
    tenantId: string,
    id: string,
    user: UserContext,
  ): Promise<void> {
    const document = await this.documentRepository.findById(tenantId, id);

    if (!document) {
      throw new NotFoundException('Document not found');
    }

    const canDelete = await this.accessService.canDelete(document, user);
    if (!canDelete) {
      throw new ForbiddenException('You do not have permission to delete this document');
    }

    // Soft delete
    await this.documentRepository.softDelete(tenantId, id);
  }

  async share(
    tenantId: string,
    id: string,
    user: UserContext,
    dto: ShareDocumentDto,
  ): Promise<void> {
    const document = await this.documentRepository.findById(tenantId, id);

    if (!document) {
      throw new NotFoundException('Document not found');
    }

    const canShare = await this.accessService.canShare(document, user);
    if (!canShare) {
      throw new ForbiddenException('You do not have permission to share this document');
    }

    // If sharing with CUSTOM visibility, update document visibility
    if (document.visibility !== 'CUSTOM') {
      await this.documentRepository.update(tenantId, id, {
        visibility: 'CUSTOM',
      });
    }

    await this.accessService.grantAccess(
      id,
      dto.accessType,
      dto.targetId,
      dto.permission,
      user.userId,
      dto.expiresAt,
    );
  }

  async unshare(
    tenantId: string,
    id: string,
    user: UserContext,
    accessType: AccessType,
    targetId: string,
  ): Promise<void> {
    const document = await this.documentRepository.findById(tenantId, id);

    if (!document) {
      throw new NotFoundException('Document not found');
    }

    const canShare = await this.accessService.canShare(document, user);
    if (!canShare) {
      throw new ForbiddenException('You do not have permission to modify sharing');
    }

    await this.accessService.revokeAccess(id, accessType, targetId);
  }

  async getSharing(
    tenantId: string,
    id: string,
    user: UserContext,
  ): Promise<{ accessGrants: any[] }> {
    const document = await this.documentRepository.findById(tenantId, id);

    if (!document) {
      throw new NotFoundException('Document not found');
    }

    const canShare = await this.accessService.canShare(document, user);
    if (!canShare) {
      throw new ForbiddenException('You do not have permission to view sharing settings');
    }

    const accessGrants = await this.accessService.getAccessGrants(id);
    return { accessGrants };
  }
}

cd apps/api
cat src/documents/services/document.service.ts
npx tsc --noEmit

rm apps/api/src/documents/services/document.service.ts

apps/api/src/documents/services/document.service.ts

// apps/api/src/documents/dto/create-document.dto.ts
import { IsString, IsOptional, IsEnum } from 'class-validator';
import { DocumentCategory, DocumentVisibility } from '@prisma/client';

export class CreateDocumentDto {
  @IsString()
  title: string;

  @IsOptional()
  @IsString()
  description?: string;

  @IsEnum(DocumentCategory)
  category: DocumentCategory;

  @IsEnum(DocumentVisibility)
  visibility: DocumentVisibility;

  @IsOptional()
  @IsString()
  employeeId?: string;
}

// apps/api/src/documents/dto/update-document.dto.ts
import { IsString, IsOptional, IsEnum } from 'class-validator';
import { DocumentCategory, DocumentVisibility } from '@prisma/client';

export class UpdateDocumentDto {
  @IsOptional()
  @IsString()
  title?: string;

  @IsOptional()
  @IsString()
  description?: string;

  @IsOptional()
  @IsEnum(DocumentCategory)
  category?: DocumentCategory;

  @IsOptional()
  @IsEnum(DocumentVisibility)
  visibility?: DocumentVisibility;
}

// apps/api/src/documents/dto/share-document.dto.ts
import { IsString, IsOptional, IsEnum, IsDateString } from 'class-validator';
import { AccessType, DocumentPermission } from '@prisma/client';

export class ShareDocumentDto {
  @IsEnum(AccessType)
  accessType: AccessType;

  @IsString()
  targetId: string;

  @IsEnum(DocumentPermission)
  permission: DocumentPermission;

  @IsOptional()
  @IsDateString()
  expiresAt?: string;
}

// apps/api/src/documents/documents.module.ts
import { Module } from '@nestjs/common';
import { MulterModule } from '@nestjs/platform-express';
import { memoryStorage } from 'multer';
import { PrismaModule } from '../prisma/prisma.module';
import { DocumentRepository } from './repositories/document.repository';
import { UploadService } from './services/upload.service';
import { DocumentAccessService } from './services/document-access.service';
import { DocumentService } from './services/document.service';
import { DocumentController } from './controllers/document.controller';

@Module({
  imports: [
    PrismaModule,
    MulterModule.register({
      storage: memoryStorage(),
      limits: {
        fileSize: 50 * 1024 * 1024, // 50MB
      },
    }),
  ],
  controllers: [DocumentController],
  providers: [
    DocumentRepository,
    UploadService,
    DocumentAccessService,
    DocumentService,
  ],
  exports: [DocumentService],
})
export class DocumentsModule {}

// Add to imports in app.module.ts
import { DocumentsModule } from './documents/documents.module';

@Module({
  imports: [
    // ... existing modules
    DocumentsModule,
  ],
})
export class AppModule {}

// apps/api/src/documents/controllers/document.controller.ts
import {
  Controller,
  Get,
  Post,
  Patch,
  Delete,
  Body,
  Param,
  Query,
  UseGuards,
  UseInterceptors,
  UploadedFile,
} from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';
import { TenantGuard } from '../../tenant/tenant.guard';
import { TenantId } from '../../tenant/tenant.decorator';
import { CurrentUser } from '../../auth/current-user.decorator';
import { DocumentService } from '../services/document.service';
import { CreateDocumentDto } from '../dto/create-document.dto';
import { UpdateDocumentDto } from '../dto/update-document.dto';
import { ShareDocumentDto } from '../dto/share-document.dto';
import { DocumentCategory, AccessType } from '@prisma/client';

@Controller('api/v1/documents')
@UseGuards(TenantGuard)
export class DocumentController {
  constructor(private documentService: DocumentService) {}

  @Post()
  @UseInterceptors(FileInterceptor('file'))
  async upload(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @UploadedFile() file: Express.Multer.File,
    @Body() dto: CreateDocumentDto,
  ) {
    // Pass employeeId (not userId) for TEAM/DEPARTMENT visibility checks
    const document = await this.documentService.upload(
      tenantId,
      user.employeeId,
      file,
      dto,
    );
    return { data: document, error: null };
  }

  @Get()
  async list(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Query('category') category?: DocumentCategory,
    @Query('search') search?: string,
    @Query('page') page?: string,
    @Query('limit') limit?: string,
  ) {
    const userContext = await this.buildUserContext(user);
    const result = await this.documentService.findAccessible(
      tenantId,
      userContext,
      {
        category,
        search,
        page: page ? parseInt(page, 10) : 1,
        limit: limit ? parseInt(limit, 10) : 20,
      },
    );
    return { data: result, error: null };
  }

  @Get('my')
  async myDocuments(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Query('category') category?: DocumentCategory,
    @Query('search') search?: string,
    @Query('page') page?: string,
    @Query('limit') limit?: string,
  ) {
    // Use employeeId to match uploadedById in documents
    const result = await this.documentService.findMyDocuments(
      tenantId,
      user.employeeId,
      {
        category,
        search,
        page: page ? parseInt(page, 10) : 1,
        limit: limit ? parseInt(limit, 10) : 20,
      },
    );
    return { data: result, error: null };
  }

  @Get(':id')
  async findOne(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Param('id') id: string,
  ) {
    const userContext = await this.buildUserContext(user);
    const document = await this.documentService.findById(
      tenantId,
      id,
      userContext,
    );
    return { data: document, error: null };
  }

  @Get(':id/download')
  async download(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Param('id') id: string,
  ) {
    const userContext = await this.buildUserContext(user);
    const url = await this.documentService.getDownloadUrl(
      tenantId,
      id,
      userContext,
    );
    return { data: { url }, error: null };
  }

  @Patch(':id')
  async update(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Param('id') id: string,
    @Body() dto: UpdateDocumentDto,
  ) {
    const userContext = await this.buildUserContext(user);
    const document = await this.documentService.update(
      tenantId,
      id,
      userContext,
      dto,
    );
    return { data: document, error: null };
  }

  @Delete(':id')
  async delete(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Param('id') id: string,
  ) {
    const userContext = await this.buildUserContext(user);
    await this.documentService.delete(tenantId, id, userContext);
    return { data: { success: true }, error: null };
  }

  @Post(':id/share')
  async share(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Param('id') id: string,
    @Body() dto: ShareDocumentDto,
  ) {
    const userContext = await this.buildUserContext(user);
    await this.documentService.share(tenantId, id, userContext, {
      ...dto,
      expiresAt: dto.expiresAt ? new Date(dto.expiresAt) : undefined,
    });
    return { data: { success: true }, error: null };
  }

  @Delete(':id/share/:accessType/:targetId')
  async unshare(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Param('id') id: string,
    @Param('accessType') accessType: AccessType,
    @Param('targetId') targetId: string,
  ) {
    const userContext = await this.buildUserContext(user);
    await this.documentService.unshare(
      tenantId,
      id,
      userContext,
      accessType,
      targetId,
    );
    return { data: { success: true }, error: null };
  }

  @Get(':id/sharing')
  async getSharing(
    @TenantId() tenantId: string,
    @CurrentUser() user: any,
    @Param('id') id: string,
  ) {
    const userContext = await this.buildUserContext(user);
    const sharing = await this.documentService.getSharing(
      tenantId,
      id,
      userContext,
    );
    return { data: sharing, error: null };
  }

  private async buildUserContext(user: any) {
    // MVP: Trust JWT claims for team/department membership
    // PRODUCTION NOTE: JWT claims are set at login and may become stale if user
    // is reassigned to different teams/departments. For production, consider:
    // - Fetching fresh membership from EmployeeTeam/EmployeeDepartment tables
    // - Using short-lived tokens with refresh
    // - Invalidating tokens on org changes
    return {
      userId: user.userId,
      employeeId: user.employeeId,
      teamIds: user.teamIds || [],
      departmentIds: user.departmentIds || [],
      roleIds: user.roleIds || [],
      isManager: user.isManager || false,
    };
  }
}

cd apps/api
npm install @nestjs/platform-express
npm install -D @types/multer

cd apps/api
cat src/documents/documents.module.ts
cat src/documents/controllers/document.controller.ts
npx tsc --noEmit

rm -rf apps/api/src/documents/controllers
rm -rf apps/api/src/documents/dto
rm apps/api/src/documents/documents.module.ts
# Also remove DocumentsModule from app.module.ts imports

apps/api/src/documents/documents.module.ts
apps/api/src/documents/controllers/document.controller.ts
apps/api/src/documents/dto/*

// Update the post method in apps/web/lib/api.ts to handle FormData
async post<T = unknown>(path: string, body: unknown): Promise<{ data: T; error: null }> {
  const tenantId = await getTenantId();

  const headers: Record<string, string> = {
    'x-tenant-id': tenantId,
  };

  let processedBody: string | FormData;

  if (body instanceof FormData) {
    // Don't set Content-Type for FormData - browser sets it with boundary
    processedBody = body;
  } else {
    headers['Content-Type'] = 'application/json';
    processedBody = JSON.stringify(body);
  }

  const res = await fetch(`${API_URL}/api/v1${path}`, {
    method: 'POST',
    headers,
    body: processedBody,
  });

  if (!res.ok) {
    throw new Error(`API request failed: ${res.status}`);
  }

  return res.json();
}

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { api } from '../api';

// Define types locally instead of importing from @prisma/client
// This ensures the frontend doesn't depend on Prisma directly

export type DocumentCategory =
  | 'POLICY'
  | 'HANDBOOK'
  | 'CONTRACT'
  | 'PERFORMANCE'
  | 'TRAINING'
  | 'CERTIFICATE'
  | 'PERSONAL'
  | 'OTHER';

export type DocumentVisibility =
  | 'PRIVATE'
  | 'TEAM'
  | 'DEPARTMENT'
  | 'MANAGERS'
  | 'COMPANY'
  | 'CUSTOM';

export type AccessType = 'USER' | 'TEAM' | 'DEPARTMENT' | 'ROLE';

export type DocumentPermission = 'VIEW' | 'DOWNLOAD' | 'EDIT';

export type DocumentStatus = 'ACTIVE' | 'ARCHIVED' | 'DELETED';

export interface Document {
  id: string;
  tenantId: string;
  employeeId: string | null;
  uploadedById: string;
  title: string;
  description: string | null;
  category: DocumentCategory;
  fileUrl: string;
  fileName: string;
  mimeType: string;
  fileSize: number;
  visibility: DocumentVisibility;
  vectorId: string | null;
  indexed: boolean;
  status: DocumentStatus;
  createdAt: string;
  updatedAt: string;
}

export interface DocumentAccess {
  id: string;
  documentId: string;
  accessType: AccessType;
  targetId: string | null;
  permission: DocumentPermission;
  grantedBy: string;
  grantedAt: string;
  expiresAt: string | null;
}

interface DocumentListResponse {
  items: Document[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

export function useDocuments(options?: {
  category?: DocumentCategory;
  search?: string;
  page?: number;
  limit?: number;
}) {
  return useQuery({
    queryKey: ['documents', options],
    queryFn: async (): Promise<DocumentListResponse> => {
      const params = new URLSearchParams();
      if (options?.category) params.set('category', options.category);
      if (options?.search) params.set('search', options.search);
      if (options?.page) params.set('page', options.page.toString());
      if (options?.limit) params.set('limit', options.limit.toString());
      const response = await api.get<DocumentListResponse>(
        `/documents?${params}`,
      );
      return response.data;
    },
  });
}

export function useMyDocuments(options?: {
  category?: DocumentCategory;
  search?: string;
  page?: number;
  limit?: number;
}) {
  return useQuery({
    queryKey: ['my-documents', options],
    queryFn: async (): Promise<DocumentListResponse> => {
      const params = new URLSearchParams();
      if (options?.category) params.set('category', options.category);
      if (options?.search) params.set('search', options.search);
      if (options?.page) params.set('page', options.page.toString());
      if (options?.limit) params.set('limit', options.limit.toString());
      const response = await api.get<DocumentListResponse>(
        `/documents/my?${params}`,
      );
      return response.data;
    },
  });
}

export function useDocument(id: string) {
  return useQuery({
    queryKey: ['document', id],
    queryFn: async (): Promise<Document> => {
      const response = await api.get<Document>(`/documents/${id}`);
      return response.data;
    },
    enabled: !!id,
  });
}

export function useUploadDocument() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (data: {
      file: File;
      title: string;
      description?: string;
      category: DocumentCategory;
      visibility: DocumentVisibility;
      employeeId?: string;
    }) => {
      const formData = new FormData();
      formData.append('file', data.file);
      formData.append('title', data.title);
      if (data.description) formData.append('description', data.description);
      formData.append('category', data.category);
      formData.append('visibility', data.visibility);
      if (data.employeeId) formData.append('employeeId', data.employeeId);

      const response = await api.post<Document>('/documents', formData);
      return response.data;
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['documents'] });
      queryClient.invalidateQueries({ queryKey: ['my-documents'] });
    },
  });
}

export function useUpdateDocument() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({
      id,
      data,
    }: {
      id: string;
      data: {
        title?: string;
        description?: string;
        category?: DocumentCategory;
        visibility?: DocumentVisibility;
      };
    }) => {
      const response = await api.patch<Document>(`/documents/${id}`, data);
      return response.data;
    },
    onSuccess: (_, { id }) => {
      queryClient.invalidateQueries({ queryKey: ['documents'] });
      queryClient.invalidateQueries({ queryKey: ['my-documents'] });
      queryClient.invalidateQueries({ queryKey: ['document', id] });
    },
  });
}

export function useDeleteDocument() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (id: string) => {
      await api.delete(`/documents/${id}`);
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['documents'] });
      queryClient.invalidateQueries({ queryKey: ['my-documents'] });
    },
  });
}

export function useDownloadDocument() {
  return useMutation({
    mutationFn: async (id: string) => {
      const response = await api.get<{ url: string }>(
        `/documents/${id}/download`,
      );
      return response.data.url;
    },
  });
}

export function useShareDocument() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({
      id,
      data,
    }: {
      id: string;
      data: {
        accessType: AccessType;
        targetId: string;
        permission: DocumentPermission;
        expiresAt?: string;
      };
    }) => {
      await api.post(`/documents/${id}/share`, data);
    },
    onSuccess: (_, { id }) => {
      queryClient.invalidateQueries({ queryKey: ['document', id] });
    },
  });
}

export function useUnshareDocument() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({
      id,
      accessType,
      targetId,
    }: {
      id: string;
      accessType: AccessType;
      targetId: string;
    }) => {
      await api.delete(`/documents/${id}/share/${accessType}/${targetId}`);
    },
    onSuccess: (_, { id }) => {
      queryClient.invalidateQueries({ queryKey: ['document', id] });
    },
  });
}