@hed-hog/lms 0.0.361 → 0.0.365

package/src/course/lms-bulk-upload.service.ts

@@ -1,204 +1,1092 @@
-import { FileService } from '@hed-hog/core';
-import { PrismaService } from '@hed-hog/api-prisma';
-import { SettingService } from '@hed-hog/core';
-import {
-    BadRequestException,
-    Inject,
-    Injectable,
-    NotFoundException,
-    forwardRef,
-} from '@nestjs/common';
-
-type IntegrationProfileConfig = {
-  access_key_id?: string;
-  secret_access_key?: string;
-  session_token?: string;
-  region?: string;
-  bucket?: string;
-  role_arn?: string;
-  external_id?: string;
-};
-
-@Injectable()
-export class LmsBulkUploadService {
-  constructor(
-    @Inject(forwardRef(() => SettingService))
-    private readonly settingService: SettingService,
-    @Inject(forwardRef(() => PrismaService))
-    private readonly prismaService: PrismaService,
-    @Inject(forwardRef(() => FileService))
-    private readonly fileService: FileService,
-  ) {}
-
-  async getBulkUploadSettings() {
-    const settings = await this.settingService.getSettingValues([
-      'lms-bulk-upload-storage-profile-id',
-      'lms-bulk-upload-s3-bucket',
-      'lms-bulk-upload-sts-duration-seconds',
-    ]);
-
-    return {
-      storageProfileId: Number(settings['lms-bulk-upload-storage-profile-id'] || 0) || null,
-      bucketName:
-        typeof settings['lms-bulk-upload-s3-bucket'] === 'string'
-          ? settings['lms-bulk-upload-s3-bucket'].trim()
-          : '',
-      sessionDurationSeconds:
-        Number(settings['lms-bulk-upload-sts-duration-seconds'] || 3600) || 3600,
-    };
-  }
-
-  async getTemporaryCredentials(userId: number) {
-    const { profile, region, bucket, durationSeconds, prefix } =
-      await this.resolveStorageProfileAndBucket(userId);
-
-    const credentials = profile.config as IntegrationProfileConfig;
-    const accessKeyId = String(credentials.access_key_id ?? '').trim();
-    const secretAccessKey = String(credentials.secret_access_key ?? '').trim();
-    const sessionToken = String(credentials.session_token ?? '').trim() || undefined;
-
-    if (!accessKeyId || !secretAccessKey) {
-      throw new BadRequestException(
-        'Storage profile does not contain AWS credentials (access_key_id/secret_access_key).',
-      );
-    }
-
-    const roleArn = String(credentials.role_arn ?? '').trim();
-    const externalId = String(credentials.external_id ?? '').trim();
-
-    const tempCredentials = await this.fileService.getTemporaryCredentials({
-      accessKeyId,
-      secretAccessKey,
-      sessionToken,
-      region,
-      roleArn: roleArn || undefined,
-      externalId: externalId || undefined,
-      durationSeconds,
-      sessionName: `hedhog-desktop-u${userId}-${Date.now()}`,
-    });
-
-    return {
-      provider: 'aws-s3',
-      bucket,
-      region,
-      keyPrefix: prefix,
-      credentials: {
-        accessKeyId: tempCredentials.AccessKeyId,
-        secretAccessKey: tempCredentials.SecretAccessKey,
-        sessionToken: tempCredentials.SessionToken,
-        expiresAt: tempCredentials.Expiration?.toISOString() ?? null,
-      },
-    };
-  }
-
-  async verifyFileOnS3(userId: number, payload: { key?: string; fileName?: string }) {
-    const { profile, region, bucket, prefix } = await this.resolveStorageProfileAndBucket(userId);
-
-    const credentials = profile.config as IntegrationProfileConfig;
-    const accessKeyId = String(credentials.access_key_id ?? '').trim();
-    const secretAccessKey = String(credentials.secret_access_key ?? '').trim();
-    const sessionToken = String(credentials.session_token ?? '').trim() || undefined;
-
-    if (!accessKeyId || !secretAccessKey) {
-      throw new BadRequestException(
-        'Storage profile does not contain AWS credentials (access_key_id/secret_access_key).',
-      );
-    }
-
-    const objectKey = String(payload.key ?? '').trim() || `${prefix}${String(payload.fileName ?? '').trim()}`;
-    if (!objectKey) {
-      throw new BadRequestException('Provide file key or fileName to verify on S3.');
-    }
-
-    try {
-      const result = await this.fileService.headS3Object({
-        accessKeyId,
-        secretAccessKey,
-        sessionToken,
-        region,
-        bucket,
-        key: objectKey,
-      });
-
-      return {
-        isValid: true,
-        key: objectKey,
-        sizeBytes: result.ContentLength ?? null,
-        etag: result.ETag ?? null,
-      };
-    } catch {
-      return {
-        isValid: false,
-        key: objectKey,
-      };
-    }
-  }
-
-  private async resolveStorageProfileAndBucket(userId: number) {
-    const settings = await this.settingService.getSettingValues([
-      'lms-bulk-upload-storage-profile-id',
-      'lms-bulk-upload-s3-bucket',
-      'lms-bulk-upload-sts-duration-seconds',
-    ]);
-
-    const profileId = Number(settings['lms-bulk-upload-storage-profile-id'] || 0);
-    if (!Number.isFinite(profileId) || profileId <= 0) {
-      throw new BadRequestException(
-        'LMS bulk upload storage profile is not configured (lms-bulk-upload-storage-profile-id).',
-      );
-    }
-
-    const profile = await this.prismaService.integration_profile.findUnique({
-      where: { id: profileId },
-      include: {
-        integration_type: { select: { slug: true } },
-        integration_provider: { select: { slug: true } },
-      },
-    });
-
-    if (!profile) {
-      throw new NotFoundException(`Storage integration profile ${profileId} was not found.`);
-    }
-
-    if (profile.integration_type.slug !== 'storage') {
-      throw new BadRequestException(
-        `Integration profile ${profileId} is not a storage profile.`,
-      );
-    }
-
-    const providerSlug = String(profile.integration_provider.slug ?? '').toLowerCase();
-    if (providerSlug !== 's3') {
-      throw new BadRequestException(
-        `Integration provider ${providerSlug} is not supported for desktop bulk upload. Use AWS S3 profile.`,
-      );
-    }
-
-    const config = (profile.config as IntegrationProfileConfig) ?? {};
-    const region = String(config.region ?? '').trim() || 'us-east-1';
-
-    const bucketFromSettings = String(settings['lms-bulk-upload-s3-bucket'] ?? '').trim();
-    const bucketFromProfile = String(config.bucket ?? '').trim();
-    const bucket = bucketFromSettings || bucketFromProfile;
-
-    if (!bucket) {
-      throw new BadRequestException(
-        'LMS bulk upload bucket is not configured. Set lms-bulk-upload-s3-bucket or profile bucket.',
-      );
-    }
-
-    const durationSeconds = Math.max(
-      900,
-      Math.min(43200, Number(settings['lms-bulk-upload-sts-duration-seconds'] || 3600) || 3600),
-    );
-
-    const prefix = `desktop/lms/u${userId}/`;
-
-    return {
-      profile,
-      region,
-      bucket,
-      durationSeconds,
-      prefix,
-    };
-  }
-}
+import { PrismaService } from '@hed-hog/api-prisma';
+import { FileService, SettingService, WebhookIntegrationService } from '@hed-hog/core';
+import {
+    BadRequestException,
+    Inject,
+    Injectable,
+    NotFoundException,
+    forwardRef,
+} from '@nestjs/common';
+import {
+    BULK_UPLOAD_CLEANUP_STATUSES,
+    BULK_UPLOAD_CLEANUP_WINDOWS,
+    BulkUploadCleanupStatus,
+    BulkUploadCleanupWindow,
+} from './dto/cleanup-upload-history.dto';
+import { LmsBulkUploadInfraService } from './lms-bulk-upload-infra.service';
+import {
+    LMS_BULK_UPLOAD_RECEIVE_VIDEO_COMMAND,
+    LMS_BULK_UPLOAD_WEBHOOK_SLUG,
+} from './lms-bulk-upload.constants';
+
+type IntegrationProfileConfig = {
+  access_key_id?: string;
+  secret_access_key?: string;
+  session_token?: string;
+  region?: string;
+  bucket?: string;
+  role_arn?: string;
+  external_id?: string;
+};
+
+type BulkUploadSessionStatus =
+  | 'started'
+  | 'uploading'
+  | 'paused'
+  | 'cancelling'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+type BulkUploadItemStatus =
+  | 'queued'
+  | 'uploading'
+  | 'cancelling'
+  | 'received'
+  | 'done'
+  | 'error'
+  | 'cancelled'
+  | 'lesson_not_found';
+
+type StartBulkUploadPayload = {
+  appName?: string;
+  folderPath?: string | null;
+  files?: Array<{
+    uploadId?: string;
+    fileName?: string;
+    sizeBytes?: number;
+  }>;
+};
+
+type BulkUploadHeartbeatPayload = {
+  sessionId?: number;
+  status?: string;
+  progressPercent?: number;
+  items?: Array<{
+    uploadId?: string;
+    status?: string;
+    progressPercent?: number;
+    errorMessage?: string | null;
+    uploadedKey?: string | null;
+  }>;
+};
+
+@Injectable()
+export class LmsBulkUploadService {
+  constructor(
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prismaService: PrismaService,
+    @Inject(forwardRef(() => FileService))
+    private readonly fileService: FileService,
+    @Inject(forwardRef(() => WebhookIntegrationService))
+    private readonly webhookIntegrationService: WebhookIntegrationService,
+    @Inject(forwardRef(() => LmsBulkUploadInfraService))
+    private readonly bulkUploadInfraService: LmsBulkUploadInfraService,
+  ) {}
+
+  async configureBulkUpload(
+    userId: number,
+    payload: { storageProfileId?: number },
+  ) {
+    const storageProfileId = Number(payload?.storageProfileId ?? 0);
+    const settings = await this.settingService.getSettingValues([
+      'lms-bulk-upload-lambda-role-arn',
+    ]);
+    const lambdaRoleArn = String(settings['lms-bulk-upload-lambda-role-arn'] ?? '').trim();
+
+    if (!Number.isFinite(storageProfileId) || storageProfileId <= 0) {
+      throw new BadRequestException('Select a valid storage integration profile.');
+    }
+
+    const { profile, region, bucket, durationSeconds } =
+      await this.resolveStorageProfileAndBucket(userId, {
+        storageProfileId,
+      });
+
+    const credentials = profile.config as IntegrationProfileConfig;
+    const accessKeyId = String(credentials.access_key_id ?? '').trim();
+    const secretAccessKey = String(credentials.secret_access_key ?? '').trim();
+    const sessionToken = String(credentials.session_token ?? '').trim() || undefined;
+
+    if (!accessKeyId || !secretAccessKey) {
+      throw new BadRequestException(
+        'Storage profile does not contain AWS credentials (access_key_id/secret_access_key).',
+      );
+    }
+
+    await this.fileService.headS3Bucket({
+      accessKeyId,
+      secretAccessKey,
+      sessionToken,
+      region,
+      bucket,
+    });
+
+    const roleArn = String(credentials.role_arn ?? '').trim();
+    const externalId = String(credentials.external_id ?? '').trim();
+    const tempCredentials = await this.fileService.getTemporaryCredentials({
+      accessKeyId,
+      secretAccessKey,
+      sessionToken,
+      region,
+      roleArn: roleArn || undefined,
+      externalId: externalId || undefined,
+      durationSeconds,
+      sessionName: `hedhog-desktop-u${userId}-${Date.now()}`,
+    });
+
+    await this.fileService.headS3Bucket({
+      accessKeyId: tempCredentials.AccessKeyId,
+      secretAccessKey: tempCredentials.SecretAccessKey,
+      sessionToken: tempCredentials.SessionToken,
+      region,
+      bucket,
+    });
+
+    const webhook = await this.ensureBulkUploadWebhook();
+
+    if (!webhook.public_url || !webhook.plainToken) {
+      throw new BadRequestException(
+        'Bulk upload webhook could not be provisioned with URL/token.',
+      );
+    }
+
+    const infrastructure = await this.bulkUploadInfraService.syncDesktopUploadInfrastructure({
+      bucketName: bucket,
+      region,
+      webhookUrl: String(webhook.public_url),
+      webhookSecret: String(webhook.plainToken),
+      accessKeyId,
+      secretAccessKey,
+      sessionToken,
+      lambdaRoleArn,
+    });
+
+    await this.settingService.setManySettings({
+      setting: [
+        {
+          slug: 'lms-bulk-upload-storage-profile-id',
+          value: String(storageProfileId),
+        },
+      ],
+    });
+
+    return {
+      success: true,
+      storageProfileId,
+      bucketName: bucket,
+      region,
+      credentials: {
+        expiresAt: tempCredentials.Expiration?.toISOString() ?? null,
+      },
+      infrastructure,
+      webhook,
+    };
+  }
+
+  async regenerateWebhookTokenAndSync(userId: number) {
+    const { profile, region, bucket } = await this.resolveStorageProfileAndBucket(userId);
+    const settings = await this.settingService.getSettingValues([
+      'lms-bulk-upload-lambda-role-arn',
+    ]);
+    const lambdaRoleArn = String(settings['lms-bulk-upload-lambda-role-arn'] ?? '').trim();
+
+    const credentials = profile.config as IntegrationProfileConfig;
+    const accessKeyId = String(credentials.access_key_id ?? '').trim();
+    const secretAccessKey = String(credentials.secret_access_key ?? '').trim();
+    const sessionToken = String(credentials.session_token ?? '').trim() || undefined;
+
+    if (!accessKeyId || !secretAccessKey) {
+      throw new BadRequestException(
+        'Storage profile does not contain AWS credentials (access_key_id/secret_access_key).',
+      );
+    }
+
+    await this.fileService.headS3Bucket({
+      accessKeyId,
+      secretAccessKey,
+      sessionToken,
+      region,
+      bucket,
+    });
+
+    const webhook = await this.ensureBulkUploadWebhook();
+
+    if (!webhook.public_url || !webhook.plainToken) {
+      throw new BadRequestException(
+        'Bulk upload webhook could not be provisioned with URL/token.',
+      );
+    }
+
+    const infrastructure = await this.bulkUploadInfraService.syncDesktopUploadInfrastructure({
+      bucketName: bucket,
+      region,
+      webhookUrl: String(webhook.public_url),
+      webhookSecret: String(webhook.plainToken),
+      accessKeyId,
+      secretAccessKey,
+      sessionToken,
+      lambdaRoleArn,
+    });
+
+    return {
+      success: true,
+      storageProfileId: Number(profile.id),
+      bucketName: bucket,
+      region,
+      infrastructure,
+      webhook,
+    };
+  }
+
+  async setBulkUploadLambdaRoleArn(value: string | null | undefined) {
+    const lambdaRoleArn = String(value ?? '').trim();
+
+    if (lambdaRoleArn) {
+      const iamRolePattern = /^arn:(aws[a-zA-Z-]*)?:iam::\d{12}:role\/?[a-zA-Z_0-9+=,.@\-_/]+$/;
+      if (!iamRolePattern.test(lambdaRoleArn)) {
+        throw new BadRequestException(
+          'lambdaRoleArn must be an IAM Role ARN (arn:aws:iam::<account-id>:role/<role-name>). Lambda function ARNs are not valid here.',
+        );
+      }
+    }
+
+    await this.settingService.setManySettings({
+      setting: [
+        {
+          slug: 'lms-bulk-upload-lambda-role-arn',
+          value: lambdaRoleArn,
+        },
+      ],
+    });
+
+    return {
+      success: true,
+      lambdaRoleArn,
+    };
+  }
+
+  async getBulkUploadSettings() {
+    const settings = await this.settingService.getSettingValues([
+      'lms-bulk-upload-storage-profile-id',
+      'lms-bulk-upload-lambda-role-arn',
+      'lms-bulk-upload-sts-duration-seconds',
+    ]);
+
+    const storageProfileId = Number(settings['lms-bulk-upload-storage-profile-id'] || 0) || null;
+
+    let bucketName = '';
+    if (storageProfileId) {
+      const profile = await this.prismaService.integration_profile.findUnique({
+        where: { id: storageProfileId },
+        select: { config: true },
+      });
+
+      const config = (profile?.config as IntegrationProfileConfig | null) ?? null;
+      bucketName = String(config?.bucket ?? '').trim();
+    }
+
+    const webhook = await this.prismaService.webhook_integration.findFirst({
+      where: {
+        OR: [
+          { slug: LMS_BULK_UPLOAD_WEBHOOK_SLUG },
+          { slug: { startsWith: `${LMS_BULK_UPLOAD_WEBHOOK_SLUG}-` } },
+        ],
+      },
+      orderBy: { id: 'asc' },
+      select: { id: true, status: true, public_uuid: true },
+    });
+
+    const webhookConfigured =
+      webhook?.status === 'active' && Boolean(webhook?.public_uuid);
+
+    return {
+      storageProfileId,
+      bucketName,
+      lambdaRoleArn: String(settings['lms-bulk-upload-lambda-role-arn'] ?? '').trim(),
+      sessionDurationSeconds:
+        Number(settings['lms-bulk-upload-sts-duration-seconds'] || 3600) || 3600,
+      webhookConfigured,
+    };
+  }
+
+  async getTemporaryCredentials(userId: number) {
+    const { profile, region, bucket, durationSeconds, prefix } =
+      await this.resolveStorageProfileAndBucket(userId);
+
+    const credentials = profile.config as IntegrationProfileConfig;
+    const accessKeyId = String(credentials.access_key_id ?? '').trim();
+    const secretAccessKey = String(credentials.secret_access_key ?? '').trim();
+    const sessionToken = String(credentials.session_token ?? '').trim() || undefined;
+
+    if (!accessKeyId || !secretAccessKey) {
+      throw new BadRequestException(
+        'Storage profile does not contain AWS credentials (access_key_id/secret_access_key).',
+      );
+    }
+
+    const roleArn = String(credentials.role_arn ?? '').trim();
+    const externalId = String(credentials.external_id ?? '').trim();
+
+    const tempCredentials = await this.fileService.getTemporaryCredentials({
+      accessKeyId,
+      secretAccessKey,
+      sessionToken,
+      region,
+      roleArn: roleArn || undefined,
+      externalId: externalId || undefined,
+      durationSeconds,
+      sessionName: `hedhog-desktop-u${userId}-${Date.now()}`,
+    });
+
+    return {
+      provider: 'aws-s3',
+      bucket,
+      region,
+      keyPrefix: prefix,
+      credentials: {
+        accessKeyId: tempCredentials.AccessKeyId,
+        secretAccessKey: tempCredentials.SecretAccessKey,
+        sessionToken: tempCredentials.SessionToken,
+        expiresAt: tempCredentials.Expiration?.toISOString() ?? null,
+      },
+    };
+  }
+
+  async verifyFileOnS3(userId: number, payload: { key?: string; fileName?: string }) {
+    const { profile, region, bucket, prefix } = await this.resolveStorageProfileAndBucket(userId);
+
+    const credentials = profile.config as IntegrationProfileConfig;
+    const accessKeyId = String(credentials.access_key_id ?? '').trim();
+    const secretAccessKey = String(credentials.secret_access_key ?? '').trim();
+    const sessionToken = String(credentials.session_token ?? '').trim() || undefined;
+
+    if (!accessKeyId || !secretAccessKey) {
+      throw new BadRequestException(
+        'Storage profile does not contain AWS credentials (access_key_id/secret_access_key).',
+      );
+    }
+
+    const objectKey = String(payload.key ?? '').trim() || `${prefix}${String(payload.fileName ?? '').trim()}`;
+    if (!objectKey) {
+      throw new BadRequestException('Provide file key or fileName to verify on S3.');
+    }
+
+    try {
+      const result = await this.fileService.headS3Object({
+        accessKeyId,
+        secretAccessKey,
+        sessionToken,
+        region,
+        bucket,
+        key: objectKey,
+      });
+
+      return {
+        isValid: true,
+        key: objectKey,
+        sizeBytes: result.ContentLength ?? null,
+        etag: result.ETag ?? null,
+      };
+    } catch {
+      return {
+        isValid: false,
+        key: objectKey,
+      };
+    }
+  }
+
+  private async ensureBulkUploadWebhook() {
+    const existing = await this.prismaService.webhook_integration.findFirst({
+      where: {
+        OR: [
+          { slug: LMS_BULK_UPLOAD_WEBHOOK_SLUG },
+          { slug: { startsWith: `${LMS_BULK_UPLOAD_WEBHOOK_SLUG}-` } },
+        ],
+      },
+      orderBy: { id: 'asc' },
+      select: {
+        id: true,
+        slug: true,
+        status: true,
+      },
+    });
+
+    const webhook = !existing
+      ? await this.webhookIntegrationService.create({
+          slug: LMS_BULK_UPLOAD_WEBHOOK_SLUG,
+          name: 'LMS Bulk Upload',
+          description: 'Webhook para integração de upload em massa do LMS',
+          status: 'active',
+          require_token: true,
+        })
+      : existing.status !== 'active'
+        ? await this.webhookIntegrationService.update(existing.id, {
+            status: 'active',
+            require_token: true,
+          })
+        : await this.webhookIntegrationService.get(existing.id);
+
+    const actions = await this.webhookIntegrationService.listActions(webhook.id);
+    const receiveAction = actions.find(
+      (action) =>
+        action.type === 'app_command' &&
+        action.app_command_slug === LMS_BULK_UPLOAD_RECEIVE_VIDEO_COMMAND,
+    );
+
+    if (!receiveAction) {
+      await this.webhookIntegrationService.createAction(webhook.id, {
+        type: 'app_command',
+        name: 'Receber vídeo do upload em massa',
+        status: 'active',
+        order: 1,
+        app_command_slug: LMS_BULK_UPLOAD_RECEIVE_VIDEO_COMMAND,
+        app_command_params: {},
+      });
+    } else if (receiveAction.status !== 'active' || receiveAction.order !== 1) {
+      await this.webhookIntegrationService.updateAction(webhook.id, receiveAction.id, {
+        type: 'app_command',
+        name: 'Receber vídeo do upload em massa',
+        status: 'active',
+        order: 1,
+        app_command_slug: LMS_BULK_UPLOAD_RECEIVE_VIDEO_COMMAND,
+        app_command_params: {},
+      });
+    }
+
+    // Always regenerate the token on every save so the Lambda env vars stay in sync
+    // with the latest webhook credentials.
+    return this.webhookIntegrationService.regenerateToken(webhook.id);
+  }
+
+  async startUploadSession(userId: number, payload: StartBulkUploadPayload) {
+    const files = (payload?.files ?? [])
+      .map((file) => ({
+        uploadId: String(file?.uploadId ?? '').trim(),
+        fileName: String(file?.fileName ?? '').trim(),
+        sizeBytes: Math.max(0, Number(file?.sizeBytes ?? 0) || 0),
+      }))
+      .filter((file) => file.uploadId.length > 0 && file.fileName.length > 0);
+
+    if (files.length === 0) {
+      throw new BadRequestException('Provide at least one file to register bulk upload session.');
+    }
+
+    const appName = String(payload?.appName ?? 'hedhog-desktop').trim().slice(0, 80) || 'hedhog-desktop';
+    const folderPath = String(payload?.folderPath ?? '').trim() || null;
+    const totalFiles = files.length;
+    const totalBytes = files.reduce((sum, file) => sum + file.sizeBytes, 0);
+    const now = new Date();
+
+    const insertedSession = await this.prismaService.$queryRawUnsafe<Array<{ id: number }>>(
+      `INSERT INTO "lms_bulk_upload_session"
+        ("user_id", "app_name", "folder_path", "status", "progress_percent", "total_files", "total_bytes", "heartbeat_at", "started_at", "created_at", "updated_at")
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+      RETURNING "id"`,
+      userId,
+      appName,
+      folderPath,
+      'started',
+      0,
+      totalFiles,
+      totalBytes,
+      now,
+      now,
+      now,
+      now,
+    );
+
+    const sessionId = Number(insertedSession?.[0]?.id ?? 0);
+    if (!Number.isFinite(sessionId) || sessionId <= 0) {
+      throw new BadRequestException('Could not register bulk upload session.');
+    }
+
+    for (const file of files) {
+      await this.prismaService.$executeRawUnsafe(
+        `INSERT INTO "lms_bulk_upload_item"
+          ("session_id", "upload_id", "file_name", "size_bytes", "status", "progress_percent", "last_heartbeat_at", "created_at", "updated_at")
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+        sessionId,
+        file.uploadId,
+        file.fileName,
+        file.sizeBytes,
+        'queued',
+        0,
+        now,
+        now,
+        now,
+      );
+    }
+
+    return {
+      sessionId,
+      totalFiles,
+      totalBytes,
+      status: 'started' as BulkUploadSessionStatus,
+    };
+  }
+
+  async heartbeatUploadSession(userId: number, payload: BulkUploadHeartbeatPayload) {
+    const sessionId = Number(payload?.sessionId ?? 0);
+    if (!Number.isFinite(sessionId) || sessionId <= 0) {
+      throw new BadRequestException('Provide a valid sessionId for heartbeat.');
+    }
+
+    const sessionRows = await this.prismaService.$queryRawUnsafe<Array<{ id: number; user_id: number }>>(
+      `SELECT "id", "user_id"
+       FROM "lms_bulk_upload_session"
+       WHERE "id" = $1
+       LIMIT 1`,
+      sessionId,
+    );
+
+    const session = sessionRows?.[0] ?? null;
+    if (!session) {
+      throw new NotFoundException(`Bulk upload session ${sessionId} was not found.`);
+    }
+
+    if (Number(session.user_id) !== userId) {
+      throw new BadRequestException('You can only update your own bulk upload session.');
+    }
+
+    const now = new Date();
+    const normalizedItems = (payload?.items ?? []).map((item) => {
+      const status = this.normalizeItemStatus(item?.status);
+      return {
+        uploadId: String(item?.uploadId ?? '').trim(),
+        status,
+        progressPercent: this.clampPercent(item?.progressPercent),
+        errorMessage: String(item?.errorMessage ?? '').trim() || null,
+        uploadedKey: String(item?.uploadedKey ?? '').trim() || null,
+      };
+    }).filter((item) => item.uploadId.length > 0);
+
+    for (const item of normalizedItems) {
+      await this.prismaService.$executeRawUnsafe(
+        `UPDATE "lms_bulk_upload_item"
+         SET
+           "status" = $3,
+           "progress_percent" = $4,
+           "error_message" = $5,
+           "uploaded_key" = $6,
+           "last_heartbeat_at" = $7,
+           "completed_at" = CASE WHEN $3 IN ('received', 'done', 'error', 'cancelled') THEN COALESCE("completed_at", $7) ELSE "completed_at" END,
+           "updated_at" = $7
+         WHERE "session_id" = $1
+           AND "upload_id" = $2`,
+        sessionId,
+        item.uploadId,
+        item.status,
+        item.progressPercent,
+        item.errorMessage,
+        item.uploadedKey,
+        now,
+      );
+    }
+
+    const summaryRows = await this.prismaService.$queryRawUnsafe<Array<{
+      total: number;
+      done_count: number;
+      error_count: number;
+      cancelled_count: number;
+      uploading_count: number;
+      queued_count: number;
+      average_progress: number;
+    }>>(
+      `SELECT
+        COUNT(*)::int AS total,
+        COUNT(*) FILTER (WHERE "status" = 'done')::int AS done_count,
+        COUNT(*) FILTER (WHERE "status" = 'error')::int AS error_count,
+        COUNT(*) FILTER (WHERE "status" = 'cancelled')::int AS cancelled_count,
+        COUNT(*) FILTER (WHERE "status" = 'uploading')::int AS uploading_count,
+        COUNT(*) FILTER (WHERE "status" = 'queued')::int AS queued_count,
+        COALESCE(AVG("progress_percent"), 0)::float AS average_progress
+      FROM "lms_bulk_upload_item"
+      WHERE "session_id" = $1`,
+      sessionId,
+    );
+
+    const summary = summaryRows?.[0] ?? {
+      total: 0,
+      done_count: 0,
+      error_count: 0,
+      cancelled_count: 0,
+      uploading_count: 0,
+      queued_count: 0,
+      average_progress: 0,
+    };
+
+    const requestedStatus = this.normalizeSessionStatus(payload?.status);
+    const computedStatus = this.computeSessionStatus(summary);
+    const finalStatus = requestedStatus ?? computedStatus;
+    const progressPercent = this.clampPercent(payload?.progressPercent ?? summary.average_progress ?? 0);
+    const isTerminal = ['completed', 'failed', 'cancelled'].includes(finalStatus);
+
+    await this.prismaService.$executeRawUnsafe(
+      `UPDATE "lms_bulk_upload_session"
+       SET
+         "status" = $2,
+         "progress_percent" = $3,
+         "heartbeat_at" = $4,
+         "finished_at" = CASE WHEN $5 THEN COALESCE("finished_at", $4) ELSE "finished_at" END,
+         "updated_at" = $4
+       WHERE "id" = $1`,
+      sessionId,
+      finalStatus,
+      progressPercent,
+      now,
+      isTerminal,
+    );
+
+    return {
+      sessionId,
+      status: finalStatus,
+      progressPercent,
+      totals: {
+        total: Number(summary.total || 0),
+        done: Number(summary.done_count || 0),
+        error: Number(summary.error_count || 0),
+        cancelled: Number(summary.cancelled_count || 0),
+      },
+    };
+  }
+
+  async listUploadItems(params: { page?: number; pageSize?: number; search?: string; status?: string }) {
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.min(Math.max(Number(params.pageSize) || 20, 1), 100);
+    const offset = (page - 1) * pageSize;
+    const search = String(params.search ?? '').trim();
+    const status = this.normalizeItemStatus(params.status, true);
+
+    const where: string[] = [];
+    const args: Array<string | number> = [];
+
+    if (status) {
+      args.push(status);
+      where.push(`i."status" = $${args.length}`);
+    }
+
+    if (search) {
+      args.push(`%${search}%`);
+      const searchParam = `$${args.length}`;
+      where.push(
+        `(i."file_name" ILIKE ${searchParam} OR s."app_name" ILIKE ${searchParam} OR COALESCE(sender."name", u."name", '') ILIKE ${searchParam} OR CAST(s."user_id" AS TEXT) ILIKE ${searchParam} OR COALESCE(mc."title", '') ILIKE ${searchParam} OR COALESCE(ml."title", '') ILIKE ${searchParam})`,
+      );
+    }
+
+    const whereSql = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
+
+    const countRows = await this.prismaService.$queryRawUnsafe<Array<{ total: number }>>(
+      `SELECT COUNT(*)::int AS total
+       FROM "lms_bulk_upload_item" i
+       JOIN "lms_bulk_upload_session" s ON s."id" = i."session_id"
+       LEFT JOIN "user" u ON u."id" = s."user_id"
+       LEFT JOIN LATERAL (
+         SELECT p."name"
+         FROM "person_user" pu
+         JOIN "person" p ON p."id" = pu."person_id"
+         WHERE pu."user_id" = s."user_id"
+         ORDER BY pu."id" DESC
+         LIMIT 1
+       ) sender ON TRUE
+       LEFT JOIN "course" mc ON mc."id" = i."matched_course_id"
+       LEFT JOIN "course_module" ms ON ms."id" = i."matched_session_id"
+       LEFT JOIN "course_lesson" ml ON ml."id" = i."matched_lesson_id"
+       ${whereSql}`,
+      ...args,
+    );
+
+    const total = Number(countRows?.[0]?.total ?? 0);
+    const dataRows = await this.prismaService.$queryRawUnsafe<Array<{
+      id: number;
+      session_id: number;
+      upload_id: string;
+      file_name: string;
+      size_bytes: number;
+      status: string;
+      progress_percent: number;
+      error_message: string | null;
+      uploaded_key: string | null;
+      received_at: Date | null;
+      updated_at: Date;
+      completed_at: Date | null;
+      app_name: string;
+      user_id: number;
+      user_photo_id: number | null;
+      user_name: string | null;
+      session_status: string;
+      session_started_at: Date;
+      matched_course_id: number | null;
+      matched_course_title: string | null;
+      matched_course_slug: string | null;
+      matched_course_logo_file_id: number | null;
+      matched_session_id: number | null;
+      matched_session_title: string | null;
+      matched_lesson_id: number | null;
+      matched_lesson_title: string | null;
+    }>>(
+      `SELECT
+        i."id",
+        i."session_id",
+        i."upload_id",
+        i."file_name",
+        i."size_bytes",
+        i."status",
+        i."progress_percent",
+        i."error_message",
+        i."uploaded_key",
+        i."received_at",
+        i."updated_at",
+        i."completed_at",
+        s."app_name",
+        s."user_id",
+        u."photo_id" AS user_photo_id,
+        COALESCE(sender."name", u."name") AS user_name,
+        s."status" AS session_status,
+        s."started_at" AS session_started_at,
+        mc."id" AS matched_course_id,
+        mc."title" AS matched_course_title,
+        mc."slug" AS matched_course_slug,
+        logo."file_id" AS matched_course_logo_file_id,
+        ms."id" AS matched_session_id,
+        ms."title" AS matched_session_title,
+        ml."id" AS matched_lesson_id,
+        ml."title" AS matched_lesson_title
+      FROM "lms_bulk_upload_item" i
+      JOIN "lms_bulk_upload_session" s ON s."id" = i."session_id"
+      LEFT JOIN "user" u ON u."id" = s."user_id"
+      LEFT JOIN LATERAL (
+        SELECT p."name"
+        FROM "person_user" pu
+        JOIN "person" p ON p."id" = pu."person_id"
+        WHERE pu."user_id" = s."user_id"
+        ORDER BY pu."id" DESC
+        LIMIT 1
+      ) sender ON TRUE
+      LEFT JOIN "course" mc ON mc."id" = i."matched_course_id"
+      LEFT JOIN "course_module" ms ON ms."id" = i."matched_session_id"
+      LEFT JOIN "course_lesson" ml ON ml."id" = i."matched_lesson_id"
+      LEFT JOIN LATERAL (
+        SELECT ci."file_id"
+        FROM "course_image" ci
+        INNER JOIN "image_type" it ON it."id" = ci."image_type_id"
+        WHERE ci."course_id" = mc."id"
+          AND it."slug" = 'course-logo'
+        ORDER BY ci."id" DESC
+        LIMIT 1
+      ) logo ON TRUE
+      ${whereSql}
+      ORDER BY i."updated_at" DESC
+      LIMIT $${args.length + 1}
+      OFFSET $${args.length + 2}`,
+      ...args,
+      pageSize,
+      offset,
+    );
+
+    return {
+      data: dataRows.map((row) => ({
+        id: row.id,
+        sessionId: row.session_id,
+        uploadId: row.upload_id,
+        fileName: row.file_name,
+        sizeBytes: Number(row.size_bytes || 0),
+        status: row.status,
+        progressPercent: Number(row.progress_percent || 0),
+        errorMessage: row.error_message,
+        uploadedKey: row.uploaded_key,
+        receivedAt: row.received_at,
+        updatedAt: row.updated_at,
+        completedAt: row.completed_at,
+        appName: row.app_name,
+        userId: row.user_id,
+        userPhotoId: row.user_photo_id ? Number(row.user_photo_id) : null,
+        userName: row.user_name,
+        sessionStatus: row.session_status,
+        startedAt: row.session_started_at,
+        matchedCourseId: row.matched_course_id ? Number(row.matched_course_id) : null,
+        matchedCourseTitle: row.matched_course_title,
+        matchedCourseSlug: row.matched_course_slug,
+        matchedCourseLogoFileId: row.matched_course_logo_file_id ? Number(row.matched_course_logo_file_id) : null,
+        matchedSessionId: row.matched_session_id ? Number(row.matched_session_id) : null,
+        matchedSessionTitle: row.matched_session_title,
+        matchedLessonId: row.matched_lesson_id ? Number(row.matched_lesson_id) : null,
+        matchedLessonTitle: row.matched_lesson_title,
+      })),
+      total,
+      page,
+      pageSize,
+      lastPage: Math.max(1, Math.ceil(total / pageSize)),
+    };
+  }
+
+  async checkUploadedFiles(files: Array<{ fileName?: string; sizeBytes?: number }>) {
+    const normalized = files
+      .map((f) => ({
+        fileName: String(f?.fileName ?? '').trim(),
+        sizeBytes: Math.max(0, Number(f?.sizeBytes ?? 0) || 0),
+      }))
+      .filter((f) => f.fileName.length > 0);
+
+    if (normalized.length === 0) return { uploaded: [] };
+
+    const conditions = normalized
+      .map((_, i) => `(file_name = $${i * 2 + 1} AND size_bytes = $${i * 2 + 2}::bigint)`)
+      .join(' OR ');
+    const args: Array<string | number> = normalized.flatMap((f) => [f.fileName, f.sizeBytes]);
+
+    const rows = await this.prismaService.$queryRawUnsafe<
+      Array<{ file_name: string; size_bytes: number; uploaded_at: Date | null }>
+    >(
+      `SELECT file_name, size_bytes,
+              MAX(COALESCE(received_at, completed_at, updated_at)) AS uploaded_at
+       FROM "lms_bulk_upload_item"
+       WHERE status IN ('received', 'done')
+         AND (${conditions})
+       GROUP BY file_name, size_bytes`,
+      ...args,
+    );
+
+    return {
+      uploaded: rows.map((row) => ({
+        fileName: row.file_name,
+        sizeBytes: Number(row.size_bytes),
+        uploadedAt: row.uploaded_at?.toISOString() ?? null,
+      })),
+    };
+  }
+
+  async cleanupUploadHistory(payload: {
+    statuses?: BulkUploadCleanupStatus[];
+    timeWindow?: BulkUploadCleanupWindow;
+  }) {
+    const statusSet = new Set<string>();
+
+    for (const rawStatus of payload?.statuses ?? []) {
+      const normalized = String(rawStatus ?? '').trim().toLowerCase();
+      if (BULK_UPLOAD_CLEANUP_STATUSES.includes(normalized as BulkUploadCleanupStatus)) {
+        statusSet.add(normalized);
+      }
+    }
+
+    if (statusSet.size === 0) {
+      statusSet.add('done');
+    }
+
+    const statuses = Array.from(statusSet);
+    const allowedWindows = new Set<string>(BULK_UPLOAD_CLEANUP_WINDOWS);
+    const rawWindow = String(payload?.timeWindow ?? '').trim().toLowerCase();
+    const timeWindow = allowedWindows.has(rawWindow) ? rawWindow : 'last_day';
+
+    let cutoffDate: Date | null = null;
+    if (timeWindow === 'last_hour') {
+      cutoffDate = new Date(Date.now() - 60 * 60 * 1000);
+    } else if (timeWindow === 'last_day') {
+      cutoffDate = new Date(Date.now() - 24 * 60 * 60 * 1000);
+    } else if (timeWindow === 'last_week') {
+      cutoffDate = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+    }
+
+    const statusPlaceholders = statuses.map((_, index) => `$${index + 1}`).join(', ');
+    const args: Array<string | Date> = [...statuses];
+    let timeFilterSql = '';
+
+    if (cutoffDate) {
+      args.push(cutoffDate);
+      timeFilterSql = ` AND i."updated_at" >= $${args.length}`;
+    }
+
+    const deletedRows = await this.prismaService.$queryRawUnsafe<Array<{ session_id: number }>>(
+      `DELETE FROM "lms_bulk_upload_item" i
+       USING "lms_bulk_upload_session" s
+       WHERE i."session_id" = s."id"
+         AND i."status" IN (${statusPlaceholders})
+         ${timeFilterSql}
+       RETURNING i."session_id"`,
+      ...args,
+    );
+
+    const deletedItems = deletedRows.length;
+    const sessionIds = Array.from(
+      new Set(
+        deletedRows
+          .map((row) => Number(row.session_id || 0))
+          .filter((sessionId) => Number.isFinite(sessionId) && sessionId > 0),
+      ),
+    );
+
+    let deletedSessions = 0;
+    if (sessionIds.length > 0) {
+      const sessionPlaceholders = sessionIds
+        .map((_, index) => `$${index + 1}`)
+        .join(', ');
+
+      const deletedSessionRows = await this.prismaService.$queryRawUnsafe<Array<{ id: number }>>(
+        `DELETE FROM "lms_bulk_upload_session" s
+         WHERE s."id" IN (${sessionPlaceholders})
+           AND NOT EXISTS (
+             SELECT 1
+             FROM "lms_bulk_upload_item" i
+             WHERE i."session_id" = s."id"
+           )
+         RETURNING s."id"`,
+        ...sessionIds,
+      );
+
+      deletedSessions = deletedSessionRows.length;
+    }
+
+    return {
+      success: true,
+      deletedItems,
+      deletedSessions,
+      filtersApplied: {
+        statuses,
+        timeWindow,
+      },
+    };
+  }
+
+  private clampPercent(value: unknown) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) return 0;
+    return Math.max(0, Math.min(100, Math.round(parsed)));
+  }
+
+  private normalizeSessionStatus(value: unknown): BulkUploadSessionStatus | null {
+    const normalized = String(value ?? '').trim().toLowerCase();
+    if (!normalized) return null;
+
+    if (
+      normalized === 'started' ||
+      normalized === 'uploading' ||
+      normalized === 'paused' ||
+      normalized === 'cancelling' ||
+      normalized === 'completed' ||
+      normalized === 'failed' ||
+      normalized === 'cancelled'
+    ) {
+      return normalized;
+    }
+
+    return null;
+  }
+
+  private normalizeItemStatus(value: unknown, allowEmpty = false): BulkUploadItemStatus | null {
+    const normalized = String(value ?? '').trim().toLowerCase();
+    if (!normalized && allowEmpty) return null;
+
+    if (
+      normalized === 'queued' ||
+      normalized === 'uploading' ||
+      normalized === 'cancelling' ||
+      normalized === 'received' ||
+      normalized === 'done' ||
+      normalized === 'error' ||
+      normalized === 'cancelled' ||
+      normalized === 'lesson_not_found'
+    ) {
+      return normalized;
+    }
+
+    return allowEmpty ? null : 'queued';
+  }
+
+  private computeSessionStatus(summary: {
+    total: number;
+    done_count: number;
+    error_count: number;
+    cancelled_count: number;
+    uploading_count: number;
+    queued_count: number;
+  }): BulkUploadSessionStatus {
+    const total = Number(summary.total || 0);
+    const done = Number(summary.done_count || 0);
+    const error = Number(summary.error_count || 0);
+    const cancelled = Number(summary.cancelled_count || 0);
+    const uploading = Number(summary.uploading_count || 0);
+    const queued = Number(summary.queued_count || 0);
+
+    if (total === 0) return 'started';
+    if (done === total) return 'completed';
+    if (done + error + cancelled === total && error > 0) return 'failed';
+    if (done + error + cancelled === total && cancelled > 0 && error === 0) return 'cancelled';
+    if (uploading > 0) return 'uploading';
+    if (queued === total) return 'started';
+    return 'uploading';
+  }
+
+  private async resolveStorageProfileAndBucket(
+    userId: number,
+    overrides?: { storageProfileId?: number },
+  ) {
+    const settings = await this.settingService.getSettingValues([
+      'lms-bulk-upload-storage-profile-id',
+      'lms-bulk-upload-sts-duration-seconds',
+    ]);
+
+    const profileId = Number(
+      overrides?.storageProfileId ??
+        settings['lms-bulk-upload-storage-profile-id'] ??
+        0,
+    );
+    if (!Number.isFinite(profileId) || profileId <= 0) {
+      throw new BadRequestException(
+        'LMS bulk upload storage profile is not configured (lms-bulk-upload-storage-profile-id).',
+      );
+    }
+
+    const profile = await this.prismaService.integration_profile.findUnique({
+      where: { id: profileId },
+      include: {
+        integration_type: { select: { slug: true } },
+        integration_provider: { select: { slug: true } },
+      },
+    });
+
+    if (!profile) {
+      throw new NotFoundException(`Storage integration profile ${profileId} was not found.`);
+    }
+
+    if (profile.integration_type.slug !== 'storage') {
+      throw new BadRequestException(
+        `Integration profile ${profileId} is not a storage profile.`,
+      );
+    }
+
+    const providerSlug = String(profile.integration_provider.slug ?? '').toLowerCase();
+    if (providerSlug !== 's3') {
+      throw new BadRequestException(
+        `Integration provider ${providerSlug} is not supported for desktop bulk upload. Use AWS S3 profile.`,
+      );
+    }
+
+    const config = (profile.config as IntegrationProfileConfig) ?? {};
+    const region = String(config.region ?? '').trim() || 'us-east-1';
+
+    const bucket = String(config.bucket ?? '').trim();
+
+    if (!bucket) {
+      throw new BadRequestException(
+        `Storage integration profile ${profileId} does not define a bucket in config.bucket.`,
+      );
+    }
+
+    const durationSeconds = Math.max(
+      900,
+      Math.min(43200, Number(settings['lms-bulk-upload-sts-duration-seconds'] || 3600) || 3600),
+    );
+
+    const prefix = `desktop/lms/u${userId}/`;
+
+    return {
+      profile,
+      region,
+      bucket,
+      durationSeconds,
+      prefix,
+    };
+  }
+}