@hed-hog/lms 0.0.306 → 0.0.310

package/hedhog/frontend/app/courses/[id]/structure/_data/services/course-structure.service.ts.ejs

@@ -0,0 +1,420 @@
+/**
+ * Service — LMS Course Structure
+ *
+ * Contains all API call functions for the course structure feature.
+ * Each function receives the `request` helper from `useApp()` as its first
+ * argument, following the pattern used in operations/_lib/api.ts.
+ *
+ * Usage inside a React component or custom hook:
+ *   const { request } = useApp();
+ *   const structure = await getCourseStructure(request, courseId);
+ *
+ * ⚠️ API BASE PATH:
+ *   All structure endpoints live under /lms/courses/:courseId/structure.
+ *   If the base path changes, update STRUCTURE_BASE() at the top of this file.
+ *
+ * ⚠️ MISSING BACKEND ENDPOINTS:
+ *   moveLesson, reorderSessions, and reorderLessons are stubs that throw until
+ *   the corresponding backend endpoints are implemented. The UI should catch
+ *   these errors and fall back to optimistic local state (Zustand store).
+ *   See TODO[BACKEND] comments for the required endpoint signatures.
+ */
+
+import type {
+  ApiCreateLessonPayload,
+  ApiCreateSessionPayload,
+  ApiDuplicateSessionResponse,
+  ApiGetStructureResponse,
+  ApiLesson,
+  ApiMoveLessonPayload,
+  ApiPasteLessonsPayload,
+  ApiPasteLessonsResponse,
+  ApiReorderLessonsPayload,
+  ApiReorderSessionsPayload,
+  ApiSession,
+  ApiUpdateCoursePayload,
+  ApiUpdateLessonPayload,
+  ApiUpdateSessionPayload,
+} from '../types/api-course.types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Request function type (mirrors useApp().request from @hed-hog/next-app-provider)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Matches the signature of the `request` helper returned by useApp(). */
+type RequestFn = (input: {
+  url: string;
+  method: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+}) => Promise<{ data: unknown }>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// URL helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * ⚠️ BACKEND ADAPTER POINT:
+ *   Update this function if the structure endpoint base path changes.
+ */
+const STRUCTURE_BASE = (courseId: string | number) =>
+  `/lms/courses/${courseId}/structure`;
+
+const SESSIONS_PATH = (courseId: string | number) =>
+  `${STRUCTURE_BASE(courseId)}/sessions`;
+
+const SESSION_PATH = (courseId: string | number, sessionId: string | number) =>
+  `${SESSIONS_PATH(courseId)}/${sessionId}`;
+
+const LESSONS_PATH = (courseId: string | number, sessionId: string | number) =>
+  `${SESSION_PATH(courseId, sessionId)}/lessons`;
+
+const LESSON_PATH = (
+  courseId: string | number,
+  sessionId: string | number,
+  lessonId: string | number
+) => `${LESSONS_PATH(courseId, sessionId)}/${lessonId}`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal utility
+// ─────────────────────────────────────────────────────────────────────────────
+
+function extractData<T>(response: { data: unknown }): T {
+  return response.data as T;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Implemented endpoints
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * GET /lms/courses/:courseId/structure
+ *
+ * Loads the full course structure: sessions, lessons, and available instructors.
+ *
+ * ⚠️ BACKEND NOTE:
+ *   The response does NOT include course metadata (title, slug, etc.).
+ *   Fetch GET /lms/courses/:courseId separately for page header data.
+ */
+export async function getCourseStructure(
+  request: RequestFn,
+  courseId: string | number
+): Promise<ApiGetStructureResponse> {
+  const response = await request({
+    url: STRUCTURE_BASE(courseId),
+    method: 'GET',
+  });
+  return extractData<ApiGetStructureResponse>(response);
+}
+
+/**
+ * PATCH /lms/courses/:courseId
+ *
+ * Partial update of course metadata (title, slug, description, status).
+ * Uses the standard course endpoint, not the structure sub-path.
+ */
+export async function updateCourse(
+  request: RequestFn,
+  courseId: string | number,
+  payload: ApiUpdateCoursePayload
+): Promise<void> {
+  await request({
+    url: `/lms/courses/${courseId}`,
+    method: 'PATCH',
+    data: payload,
+  });
+}
+
+/**
+ * POST /lms/courses/:courseId/structure/sessions
+ *
+ * Creates a new session (course_module) appended to the end of the course.
+ * Returns the created session object.
+ */
+export async function createSession(
+  request: RequestFn,
+  courseId: string | number,
+  payload: ApiCreateSessionPayload
+): Promise<ApiSession> {
+  const response = await request({
+    url: SESSIONS_PATH(courseId),
+    method: 'POST',
+    data: payload,
+  });
+  return extractData<ApiSession>(response);
+}
+
+/**
+ * PATCH /lms/courses/:courseId/structure/sessions/:sessionId
+ *
+ * Partial update of a session. Only provided fields are persisted.
+ * Returns the updated session object.
+ */
+export async function updateSession(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number,
+  payload: ApiUpdateSessionPayload
+): Promise<ApiSession> {
+  const response = await request({
+    url: SESSION_PATH(courseId, sessionId),
+    method: 'PATCH',
+    data: payload,
+  });
+  return extractData<ApiSession>(response);
+}
+
+/**
+ * DELETE /lms/courses/:courseId/structure/sessions/:sessionId
+ *
+ * Deletes a session and cascades to all its lessons (course_lesson records).
+ */
+export async function deleteSession(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number
+): Promise<{ success: boolean }> {
+  const response = await request({
+    url: SESSION_PATH(courseId, sessionId),
+    method: 'DELETE',
+  });
+  return extractData<{ success: boolean }>(response);
+}
+
+/**
+ * POST /lms/courses/:courseId/structure/sessions/:sessionId/lessons
+ *
+ * Creates a new lesson in the specified session.
+ * Returns the full lesson object (backend runs getLessonById after creation).
+ */
+export async function createLesson(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number,
+  payload: ApiCreateLessonPayload
+): Promise<ApiLesson> {
+  const response = await request({
+    url: LESSONS_PATH(courseId, sessionId),
+    method: 'POST',
+    data: payload,
+  });
+  return extractData<ApiLesson>(response);
+}
+
+/**
+ * PATCH /lms/courses/:courseId/structure/sessions/:sessionId/lessons/:lessonId
+ *
+ * Partial update of a lesson. Only provided fields are persisted.
+ * Returns the full updated lesson object.
+ */
+export async function updateLesson(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number,
+  lessonId: string | number,
+  payload: ApiUpdateLessonPayload
+): Promise<ApiLesson> {
+  const response = await request({
+    url: LESSON_PATH(courseId, sessionId, lessonId),
+    method: 'PATCH',
+    data: payload,
+  });
+  return extractData<ApiLesson>(response);
+}
+
+/**
+ * DELETE /lms/courses/:courseId/structure/sessions/:sessionId/lessons/:lessonId
+ *
+ * Deletes a lesson and its relations (files, instructors, questions).
+ */
+export async function deleteLesson(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number,
+  lessonId: string | number
+): Promise<{ success: boolean }> {
+  const response = await request({
+    url: LESSON_PATH(courseId, sessionId, lessonId),
+    method: 'DELETE',
+  });
+  return extractData<{ success: boolean }>(response);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pending backend endpoints (stubs — throw until implemented)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * [PENDING BACKEND] Move a lesson to a different session or position.
+ *
+ * TODO[BACKEND]: Add to CourseStructureController:
+ *   @Patch('sessions/:sessionId/lessons/:lessonId/move')
+ *   Body: { toSessionId: number; toIndex?: number }
+ *
+ * TODO[FRONTEND]: Once the endpoint exists, replace the throw below with:
+ *   const response = await request({
+ *     url: `${LESSON_PATH(courseId, sessionId, lessonId)}/move`,
+ *     method: 'PATCH',
+ *     data: payload,
+ *   });
+ *   return extractData<void>(response);
+ *
+ * The UI should catch this error and keep the optimistic Zustand state.
+/**
+ * PATCH /lms/courses/:courseId/structure/sessions/:sessionId/lessons/:lessonId/move
+ *
+ * Moves a lesson to a different session or reorders within the same session.
+ */
+export async function moveLesson(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number,
+  lessonId: string | number,
+  payload: ApiMoveLessonPayload
+): Promise<{ success: boolean }> {
+  const response = await request({
+    url: `${LESSON_PATH(courseId, sessionId, lessonId)}/move`,
+    method: 'PATCH',
+    data: payload,
+  });
+  return extractData<{ success: boolean }>(response);
+}
+
+/**
+ * PATCH /lms/courses/:courseId/structure/sessions/reorder
+ *
+ * Persists the new session order after drag-and-drop.
+ * Body: { sessionIds: number[] } — full ordered list of session IDs.
+ */
+export async function reorderSessions(
+  request: RequestFn,
+  courseId: string | number,
+  payload: ApiReorderSessionsPayload
+): Promise<{ success: boolean }> {
+  const response = await request({
+    url: `${SESSIONS_PATH(courseId)}/reorder`,
+    method: 'PATCH',
+    data: payload,
+  });
+  return extractData<{ success: boolean }>(response);
+}
+
+/**
+ * PATCH /lms/courses/:courseId/structure/sessions/:sessionId/lessons/reorder
+ *
+ * Persists the new lesson order within a session after drag-and-drop.
+ * Body: { lessonIds: number[] } — full ordered list of lesson IDs.
+ */
+export async function reorderLessons(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number,
+  payload: ApiReorderLessonsPayload
+): Promise<{ success: boolean }> {
+  const response = await request({
+    url: `${LESSONS_PATH(courseId, sessionId)}/reorder`,
+    method: 'PATCH',
+    data: payload,
+  });
+  return extractData<{ success: boolean }>(response);
+}
+
+/**
+ * POST /lms/courses/:courseId/structure/sessions/:sessionId/duplicate
+ *
+ * Creates a full copy of the session and all its lessons.
+ * Returns the new session and the list of cloned lessons.
+ */
+export async function duplicateSession(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number
+): Promise<ApiDuplicateSessionResponse> {
+  const response = await request({
+    url: `${SESSION_PATH(courseId, sessionId)}/duplicate`,
+    method: 'POST',
+  });
+  return extractData<ApiDuplicateSessionResponse>(response);
+}
+
+/**
+ * POST /lms/courses/:courseId/structure/sessions/:sessionId/lessons/:lessonId/duplicate
+ *
+ * Creates a copy of the lesson in the same session.
+ * Returns the new lesson object.
+ */
+export async function duplicateLesson(
+  request: RequestFn,
+  courseId: string | number,
+  sessionId: string | number,
+  lessonId: string | number
+): Promise<ApiLesson> {
+  const response = await request({
+    url: `${LESSON_PATH(courseId, sessionId, lessonId)}/duplicate`,
+    method: 'POST',
+  });
+  return extractData<ApiLesson>(response);
+}
+
+/**
+ * POST /lms/courses/:courseId/structure/sessions/:sessionId/lessons/paste
+ *
+ * Creates copies of the given lesson IDs into the target session.
+ * Source lessons must belong to the same course.
+ * Returns the list of newly created lessons.
+ */
+export async function pasteLessons(
+  request: RequestFn,
+  courseId: string | number,
+  targetSessionId: string | number,
+  payload: ApiPasteLessonsPayload
+): Promise<ApiPasteLessonsResponse> {
+  const response = await request({
+    url: `${LESSONS_PATH(courseId, targetSessionId)}/paste`,
+    method: 'POST',
+    data: payload,
+  });
+  return extractData<ApiPasteLessonsResponse>(response);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// File upload / delete (generic — used by lesson resources)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * POST /file
+ *
+ * Uploads a single file as multipart/form-data.
+ * Returns the server-assigned file record ID and the stored filename.
+ *
+ * Used by the lesson resource upload flow in EditorLesson.
+ */
+export async function uploadFile(
+  request: RequestFn,
+  file: File
+): Promise<{ id: number; filename: string }> {
+  const formData = new FormData();
+  formData.append('file', file);
+  formData.append('destination', 'lms/lessons');
+
+  const response = await request({
+    url: '/file',
+    method: 'POST',
+    data: formData,
+    headers: { 'Content-Type': 'multipart/form-data' },
+  });
+  return extractData<{ id: number; filename: string }>(response);
+}
+
+/**
+ * DELETE /file/:fileId
+ *
+ * Permanently deletes a stored file by its ID.
+ * Called when the user removes a resource from a lesson.
+ */
+export async function deleteFile(
+  request: RequestFn,
+  fileId: number
+): Promise<void> {
+  await request({ url: `/file/${fileId}`, method: 'DELETE' });
+}

package/hedhog/frontend/app/courses/[id]/structure/_data/types/api-course.types.ts.ejs

@@ -0,0 +1,254 @@
+/**
+ * API Types — LMS Course Structure
+ *
+ * Raw shapes returned by (and sent to) the backend API.
+ * Field names follow the Portuguese identifiers used by the NestJS service.
+ *
+ * ⚠️ BACKEND ADAPTER POINT:
+ *   If the backend renames any field, update ONLY this file and the adapter.
+ *   The rest of the frontend is fully decoupled from these raw shapes.
+ *
+ * Reference: libraries/lms/src/course/course-structure.service.ts
+ * Reference: libraries/lms/src/course/dto/
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Response types (backend → frontend)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Resource (arquivo de suporte) attached to a lesson. */
+export interface ApiLessonResource {
+  id: number;
+  nome: string;
+  /** MIME category or custom type label; may be null. */
+  tipo: string | null;
+  publico: boolean;
+  /**
+   * TODO[BACKEND]: The API does not currently return a URL for the resource.
+   * Add a resolved URL field (e.g. `/file/open/:id`) to the lesson response
+   * in CourseStructureService.getLessonById() to enable in-browser preview.
+   */
+  url?: string;
+}
+
+/** Instructor linked to a lesson or available in the course pool. */
+export interface ApiLessonInstructor {
+  id: number;
+  name: string;
+}
+
+/**
+ * Single lesson (aula) as returned by getStructure or createLesson/updateLesson.
+ *
+ * ⚠️ BACKEND NOTE — type mapping:
+ *   The backend maps DB lesson types to UI types in mapDbTypeToUiType():
+ *     DB 'video' → UI 'video'
+ *     DB 'text'  → UI 'post'
+ *     DB 'quiz'  → UI 'questao' or 'exercicio' (based on content.sourceType)
+ *
+ * ⚠️ BACKEND NOTE — missing fields:
+ *   `order` and `visibility` are NOT included in the API response.
+ *   `status` is not part of the DB schema.
+ *   These are inferred or defaulted in the adapter.
+ */
+export interface ApiLesson {
+  id: string;
+  codigo: string;
+  titulo: string;
+  descricaoPublica: string;
+  descricaoPrivada: string;
+  /** UI-level lesson type resolved by the backend service. */
+  tipo: 'video' | 'questao' | 'post' | 'exercicio';
+  /** Duration in minutes. */
+  duracao: number;
+  /** ID of the parent session (course_module). */
+  sessaoId: string;
+  videoProvedor?: 'youtube' | 'vimeo' | 'bunny' | 'custom';
+  videoUrl?: string;
+  duracaoAutomatica?: boolean;
+  transcricao?: string;
+  /**
+   * ID of the linked exam (when tipo === 'questao').
+   * ⚠️ TYPE MISMATCH: backend sends number; frontend stores as string.
+   * Conversion is handled in the adapter.
+   */
+  exameVinculado?: number;
+  conteudoPost?: string;
+  recursos: ApiLessonResource[];
+  instrutores: ApiLessonInstructor[];
+}
+
+/**
+ * Single session (sessão / course_module) as returned by getStructure
+ * or createSession/updateSession.
+ *
+ * ⚠️ BACKEND NOTE — missing fields:
+ *   `order` is stored in the DB but NOT included in the response.
+ *   The adapter infers it from the array position (already sorted ASC by the backend).
+ *   TODO[BACKEND]: Include `order` in session responses.
+ */
+export interface ApiSession {
+  id: string;
+  codigo: string;
+  titulo: string;
+  /** Duration in minutes. */
+  duracao: number;
+  collapsed: boolean;
+}
+
+/**
+ * Course metadata as returned inside the GET /structure response.
+ */
+export interface ApiCourse {
+  id: string;
+  name: string;
+  slug: string;
+  titulo: string;
+  descricao: string;
+}
+
+/**
+ * Response shape of GET /lms/courses/:id/structure
+ *
+ * Reference: CourseStructureService.getStructure()
+ */
+export interface ApiGetStructureResponse {
+  sessoes: ApiSession[];
+  aulas: ApiLesson[];
+  /** Pool of instructors qualified for course-lessons. */
+  instructors: ApiLessonInstructor[];
+  /** Course metadata included since getStructure was updated to return it. */
+  curso: ApiCourse | null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Request types (frontend → backend)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * POST /lms/courses/:id/structure/sessions
+ * Reference: CreateCourseStructureSessionDto
+ */
+export interface ApiCreateSessionPayload {
+  titulo: string;
+  /** Duration in minutes. */
+  duracao: number;
+  descricao?: string;
+  codigo?: string;
+}
+
+/**
+ * PATCH /lms/courses/:id
+ * Reference: UpdateCourseDto (extends PartialType(CreateCourseDto))
+ */
+export interface ApiUpdateCoursePayload {
+  title?: string;
+  slug?: string;
+  name?: string;
+  description?: string;
+  /** 'published' = visible to students; 'draft' = hidden. */
+  status?: 'draft' | 'published' | 'archived';
+}
+
+/**
+ * PATCH /lms/courses/:id/structure/sessions/:sessionId
+ * Reference: UpdateCourseStructureSessionDto (all fields optional via PartialType)
+ */
+export interface ApiUpdateSessionPayload {
+  titulo?: string;
+  /** Duration in minutes. */
+  duracao?: number;
+  descricao?: string;
+  codigo?: string;
+}
+
+/**
+ * POST /lms/courses/:id/structure/sessions/:sessionId/lessons
+ * Reference: CreateCourseStructureLessonDto
+ */
+export interface ApiCreateLessonPayload {
+  titulo: string;
+  tipo: 'video' | 'questao' | 'post' | 'exercicio';
+  /** Duration in minutes. */
+  duracao: number;
+  descricaoPublica?: string;
+  descricaoPrivada?: string;
+  videoProvedor?: 'youtube' | 'vimeo' | 'bunny' | 'custom';
+  videoUrl?: string;
+  duracaoAutomatica?: boolean;
+  transcricao?: string;
+  /** ID of the linked exam. ⚠️ TYPE MISMATCH: backend expects number; frontend stores string. */
+  exameVinculado?: number;
+  conteudoPost?: string;
+  instructorIds?: number[];
+  recursos?: Array<{
+    nome: string;
+    fileId?: number;
+    tipo?: string;
+    publico?: boolean;
+  }>;
+  codigo?: string;
+}
+
+/**
+ * PATCH /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId
+ * Reference: UpdateCourseStructureLessonDto (all fields optional via PartialType)
+ */
+export type ApiUpdateLessonPayload = Partial<ApiCreateLessonPayload>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pending backend endpoint request types
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The following types define the expected payloads for endpoints that do NOT
+// yet exist in the backend. They are kept here so that when the endpoints are
+// implemented, the service layer only needs to remove the "throw" stubs.
+//
+// TODO[BACKEND]: Implement in CourseStructureController:
+//   1. PATCH /lms/courses/:id/structure/sessions/reorder
+//      Body: ApiReorderSessionsPayload
+//   2. PATCH /lms/courses/:id/structure/sessions/:sessionId/lessons/reorder
+//      Body: ApiReorderLessonsPayload
+//   3. PATCH /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId/move
+//      Body: ApiMoveLessonPayload
+
+/** [PENDING BACKEND] Reorder sessions by providing new sorted ID list. */
+export interface ApiReorderSessionsPayload {
+  /** Ordered array of session IDs reflecting the new visual order. */
+  sessionIds: number[];
+}
+
+/** [PENDING BACKEND] Reorder lessons within a session. */
+export interface ApiReorderLessonsPayload {
+  /** Ordered array of lesson IDs in their new positions. */
+  lessonIds: number[];
+}
+
+/** [PENDING BACKEND] Move a lesson to a different session or position. */
+export interface ApiMoveLessonPayload {
+  toSessionId: number;
+  toIndex?: number;
+}
+
+/**
+ * POST /lms/courses/:id/structure/sessions/:sessionId/duplicate
+ * Response: new session + all cloned lessons.
+ */
+export interface ApiDuplicateSessionResponse {
+  session: ApiSession;
+  lessons: ApiLesson[];
+}
+
+/**
+ * POST /lms/courses/:id/structure/sessions/:sessionId/lessons/paste
+ * Body: IDs of source lessons to clone into the target session.
+ */
+export interface ApiPasteLessonsPayload {
+  /** IDs of source lessons (must belong to the same course). */
+  lessonIds: number[];
+}
+
+/** Response from pasteLessons endpoint. */
+export interface ApiPasteLessonsResponse {
+  lessons: ApiLesson[];
+}