@hed-hog/lms 0.0.306 → 0.0.310

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

@@ -0,0 +1,987 @@
+'use client';
+
+/**
+ * Course Structure — React Query Mutations
+ *
+ * Each hook:
+ *  - reads `courseId` from the Zustand store (set by page.tsx on mount)
+ *  - calls the corresponding service function
+ *  - normalises the API response via the adapter
+ *  - updates both Zustand store AND React Query cache for consistency
+ *  - shows sonner toast feedback
+ *
+ * Cache strategy:
+ *  - Structural changes (create / delete / duplicate / paste / move):
+ *      invalidateQueries → background refetch refreshes cache & store
+ *  - In-place changes (update fields):
+ *      manual setQueryData (no round-trip)
+ *  - Optimistic mutations (reorder / move):
+ *      onMutate: cancelQueries + snapshot + setQueryData
+ *      onError:  restore cache snapshot + Zustand rollback
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+import { useApp } from '@hed-hog/next-app-provider';
+
+import { useStructureStore } from '../_components/store';
+import type {
+  LessonFormValues,
+  Resource,
+  SessionFormValues,
+} from '../_components/types';
+import {
+  normalizeLesson,
+  normalizeSession,
+  toCreateLessonPayload,
+  toCreateSessionPayload,
+  toUpdateLessonPayload,
+  toUpdateSessionPayload,
+} from './adapters/course-structure.adapter';
+import {
+  createLesson as apiCreateLesson,
+  createSession as apiCreateSession,
+  deleteLesson as apiDeleteLesson,
+  deleteSession as apiDeleteSession,
+  duplicateLesson as apiDuplicateLesson,
+  duplicateSession as apiDuplicateSession,
+  moveLesson as apiMoveLesson,
+  pasteLessons as apiPasteLessons,
+  reorderLessons as apiReorderLessons,
+  reorderSessions as apiReorderSessions,
+  updateCourse as apiUpdateCourse,
+  updateLesson as apiUpdateLesson,
+  updateSession as apiUpdateSession,
+} from './services/course-structure.service';
+import type { CourseStructureCacheData } from './use-course-structure-query';
+import { courseStructureQueryKey } from './use-course-structure-query';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useUpdateCourseMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface UpdateCourseVars {
+  formValues: import('../_components/types').CourseFormValues;
+}
+
+/**
+ * Mutation: PATCH /lms/courses/:id
+ *
+ * Persists the course metadata form (title, slug, code, description, published).
+ * On success: updates the store via `updateCourse` and patches the React Query
+ * cache entry so the header immediately reflects the new title/slug.
+ */
+export function useUpdateCourseMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const updateCourseInStore = useStructureStore((s) => s.updateCourse);
+
+  return useMutation({
+    mutationFn: ({ formValues }: UpdateCourseVars) =>
+      apiUpdateCourse(request, courseId, {
+        title: formValues.title,
+        slug: formValues.slug.toLowerCase(),
+        name: formValues.name,
+        description: formValues.description,
+        status: formValues.published ? 'published' : 'draft',
+      }),
+    onSuccess: (_, { formValues }) => {
+      updateCourseInStore(formValues);
+      // Patch cache so structure query reflects new course metadata.
+      queryClient.setQueryData<
+        import('./use-course-structure-query').CourseStructureCacheData
+      >(courseStructureQueryKey(courseId), (old) => {
+        if (!old || !old.course) return old;
+        return {
+          ...old,
+          course: {
+            ...old.course,
+            title: formValues.title,
+            slug: formValues.slug.toLowerCase(),
+            name: formValues.name,
+            description: formValues.description,
+            published: formValues.published,
+          },
+        };
+      });
+      toast.success('Curso salvo');
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao salvar curso');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useCreateSessionMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Mutation: POST /lms/courses/:id/structure/sessions
+ *
+ * Creates a new session with default values and appends it to the store.
+ * The newly created session becomes the active/selected item.
+ */
+export function useCreateSessionMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const sessions = useStructureStore((s) => s.sessions);
+  const addSessionFromApi = useStructureStore((s) => s.addSessionFromApi);
+
+  return useMutation({
+    mutationFn: () => {
+      const nextIndex = sessions.length + 1;
+      const payload = toCreateSessionPayload({
+        title: `Nova Sessão ${String(nextIndex).padStart(2, '0')}`,
+        duration: 0,
+        code: `S${String(nextIndex).padStart(2, '0')}`,
+        description: '',
+      });
+      return apiCreateSession(request, courseId, payload);
+    },
+    onSuccess: (apiSession) => {
+      const session = normalizeSession(apiSession, sessions.length);
+      addSessionFromApi(session);
+      // Invalidate so cache stays in sync; useEffect in page.tsx will re-sync
+      // store when isMutating reaches 0 (guarded against mid-flight overwrites).
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.success('Sessão criada');
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao criar sessão');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useUpdateSessionMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface UpdateSessionVars {
+  sessionId: string | number;
+  formValues: SessionFormValues;
+}
+
+/**
+ * Mutation: PATCH /lms/courses/:id/structure/sessions/:sessionId
+ *
+ * Persists the form values and updates the store on success.
+ */
+export function useUpdateSessionMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const updateSessionInStore = useStructureStore((s) => s.updateSession);
+
+  return useMutation({
+    mutationFn: ({ sessionId, formValues }: UpdateSessionVars) =>
+      apiUpdateSession(
+        request,
+        courseId,
+        sessionId,
+        toUpdateSessionPayload(formValues)
+      ),
+    onSuccess: (_apiSession, { sessionId, formValues }) => {
+      updateSessionInStore(String(sessionId), formValues);
+      // Manual cache update avoids a full refetch for an in-place title/desc change.
+      queryClient.setQueryData<CourseStructureCacheData>(
+        courseStructureQueryKey(courseId),
+        (old) => {
+          if (!old) return old;
+          return {
+            ...old,
+            sessions: old.sessions.map((s) =>
+              s.id === String(sessionId)
+                ? {
+                    ...s,
+                    title: formValues.title ?? s.title,
+                    code: formValues.code ?? s.code,
+                    duration: formValues.duration ?? s.duration,
+                  }
+                : s
+            ),
+          };
+        }
+      );
+      toast.success('Sessão salva');
+    },
+    onError: () => {
+      // Fall back to server truth
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao salvar sessão');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useCreateLessonMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface CreateLessonVars {
+  sessionId: string | number;
+}
+
+/**
+ * Mutation: POST /lms/courses/:id/structure/sessions/:sessionId/lessons
+ *
+ * Creates a new lesson with default values in the given session.
+ * The newly created lesson becomes the active/selected item.
+ */
+export function useCreateLessonMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const lessons = useStructureStore((s) => s.lessons);
+  const addLessonFromApi = useStructureStore((s) => s.addLessonFromApi);
+
+  return useMutation({
+    mutationFn: ({ sessionId }: CreateLessonVars) => {
+      const sessionLessons = lessons.filter(
+        (l) => l.sessionId === String(sessionId)
+      );
+      const nextIndex = sessionLessons.length + 1;
+      const payload = toCreateLessonPayload({
+        title: `Nova Aula ${String(nextIndex).padStart(2, '0')}`,
+        type: 'video',
+        duration: 0,
+        code: `A${String(lessons.length + 1).padStart(2, '0')}`,
+        publicDescription: '',
+        privateDescription: '',
+        status: 'preparada',
+        visibility: 'publico',
+      });
+      return apiCreateLesson(request, courseId, sessionId, payload);
+    },
+    onSuccess: (apiLesson) => {
+      const lesson = normalizeLesson(apiLesson, lessons.length);
+      addLessonFromApi(lesson);
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.success('Aula criada');
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao criar aula');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useUpdateLessonMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface UpdateLessonVars {
+  lessonId: string | number;
+  sessionId: string | number;
+  formValues: Partial<
+    LessonFormValues & {
+      transcription?: string;
+      resources?: Resource[];
+      instructorIds?: number[];
+    }
+  >;
+}
+
+/**
+ * Mutation: PATCH /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId
+ *
+ * Persists the form values and updates the store on success.
+ */
+export function useUpdateLessonMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const updateLessonInStore = useStructureStore((s) => s.updateLesson);
+
+  return useMutation({
+    mutationFn: ({ lessonId, sessionId, formValues }: UpdateLessonVars) =>
+      apiUpdateLesson(
+        request,
+        courseId,
+        sessionId,
+        lessonId,
+        toUpdateLessonPayload(formValues)
+      ),
+    onSuccess: (_apiLesson, { lessonId, formValues }) => {
+      updateLessonInStore(String(lessonId), formValues);
+      // Manual cache update for in-place field changes.
+      queryClient.setQueryData<CourseStructureCacheData>(
+        courseStructureQueryKey(courseId),
+        (old) => {
+          if (!old) return old;
+          return {
+            ...old,
+            lessons: old.lessons.map((l) =>
+              l.id === String(lessonId)
+                ? {
+                    ...l,
+                    title: formValues.title ?? l.title,
+                    duration: formValues.duration ?? l.duration,
+                    type: formValues.type ?? l.type,
+                  }
+                : l
+            ),
+          };
+        }
+      );
+      toast.success('Aula salva');
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao salvar aula');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useDeleteSessionMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface DeleteSessionVars {
+  sessionId: string | number;
+}
+
+/**
+ * Mutation: DELETE /lms/courses/:id/structure/sessions/:sessionId
+ *
+ * Deletes the session (and its lessons, cascade on backend) then removes it
+ * from the Zustand store. Selection is reset to the course root.
+ */
+export function useDeleteSessionMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const deleteSessionInStore = useStructureStore((s) => s.deleteSession);
+
+  return useMutation({
+    mutationFn: ({ sessionId }: DeleteSessionVars) =>
+      apiDeleteSession(request, courseId, sessionId),
+    onSuccess: (_, { sessionId }) => {
+      deleteSessionInStore(String(sessionId));
+      // Remove session and its lessons from the cache.
+      queryClient.setQueryData<CourseStructureCacheData>(
+        courseStructureQueryKey(courseId),
+        (old) => {
+          if (!old) return old;
+          const sid = String(sessionId);
+          return {
+            ...old,
+            sessions: old.sessions.filter((s) => s.id !== sid),
+            lessons: old.lessons.filter((l) => l.sessionId !== sid),
+          };
+        }
+      );
+      toast.success('Sessão excluída');
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao excluir sessão');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useDeleteLessonMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface DeleteLessonVars {
+  lessonId: string | number;
+  sessionId: string | number;
+}
+
+/**
+ * Mutation: DELETE /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId
+ *
+ * Deletes a lesson and removes it from the Zustand store.
+ */
+export function useDeleteLessonMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const deleteLessonInStore = useStructureStore((s) => s.deleteLesson);
+
+  return useMutation({
+    mutationFn: ({ lessonId, sessionId }: DeleteLessonVars) =>
+      apiDeleteLesson(request, courseId, sessionId, lessonId),
+    onSuccess: (_, { lessonId }) => {
+      deleteLessonInStore(String(lessonId));
+      const lid = String(lessonId);
+      queryClient.setQueryData<CourseStructureCacheData>(
+        courseStructureQueryKey(courseId),
+        (old) =>
+          old
+            ? { ...old, lessons: old.lessons.filter((l) => l.id !== lid) }
+            : old
+      );
+      toast.success('Aula excluída');
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao excluir aula');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useBulkDeleteMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface BulkDeleteVars {
+  /** IDs of sessions to delete (backend cascades their lessons). */
+  sessionIds: string[];
+  /** Individual lessons to delete (only those whose session is NOT also deleted). */
+  lessons: Array<{ lessonId: string; sessionId: string }>;
+}
+
+/**
+ * Bulk delete: iterate API calls since no batch endpoint exists.
+ *
+ * Strategy:
+ *  1. Delete sessions in parallel (backend cascades their lessons).
+ *  2. Delete orphan lessons in parallel (those not in a deleted session).
+ *  3. Use Promise.allSettled so one failure doesn't abort the rest.
+ *  4. Remove successful items from the store individually.
+ *  5. Show partial-error toast when some items fail.
+ */
+export function useBulkDeleteMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const deleteSessionInStore = useStructureStore((s) => s.deleteSession);
+  const deleteLessonInStore = useStructureStore((s) => s.deleteLesson);
+
+  return useMutation({
+    mutationFn: async ({ sessionIds, lessons }: BulkDeleteVars) => {
+      const sessionResults = await Promise.allSettled(
+        sessionIds.map((id) => apiDeleteSession(request, courseId, id))
+      );
+      const lessonResults = await Promise.allSettled(
+        lessons.map(({ lessonId, sessionId }) =>
+          apiDeleteLesson(request, courseId, sessionId, lessonId)
+        )
+      );
+      return {
+        sessionIds,
+        lessonIds: lessons.map((l) => l.lessonId),
+        sessionResults,
+        lessonResults,
+      };
+    },
+    onSuccess: ({ sessionIds, lessonIds, sessionResults, lessonResults }) => {
+      const successSessionIds = sessionIds.filter(
+        (_, i) => sessionResults[i]?.status === 'fulfilled'
+      );
+      const successLessonIds = lessonIds.filter(
+        (_, i) => lessonResults[i]?.status === 'fulfilled'
+      );
+      const errorCount = [...sessionResults, ...lessonResults].filter(
+        (r) => r.status === 'rejected'
+      ).length;
+
+      successSessionIds.forEach((id) => deleteSessionInStore(id));
+      successLessonIds.forEach((id) => deleteLessonInStore(id));
+
+      // Update cache: remove deleted sessions and their cascaded lessons,
+      // plus individually deleted orphan lessons.
+      const deletedSessionSet = new Set(successSessionIds);
+      const deletedLessonSet = new Set(successLessonIds);
+      queryClient.setQueryData<CourseStructureCacheData>(
+        courseStructureQueryKey(courseId),
+        (old) => {
+          if (!old) return old;
+          return {
+            ...old,
+            sessions: old.sessions.filter((s) => !deletedSessionSet.has(s.id)),
+            lessons: old.lessons.filter(
+              (l) =>
+                !deletedSessionSet.has(l.sessionId) &&
+                !deletedLessonSet.has(l.id)
+            ),
+          };
+        }
+      );
+
+      const successCount = successSessionIds.length + successLessonIds.length;
+      if (errorCount === 0) {
+        toast.success(
+          `${successCount} ${successCount === 1 ? 'item excluído' : 'itens excluídos'}`
+        );
+      } else {
+        toast.error(
+          `${errorCount} falha${errorCount > 1 ? 's' : ''} — ${successCount} excluído${successCount !== 1 ? 's' : ''}`
+        );
+      }
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao excluir itens');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useReorderSessionsMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface ReorderSessionsVars {
+  /** New ordered list of session IDs. */
+  orderedIds: string[];
+  /** Snapshot of sessions before the reorder (for rollback). */
+  previousSessions: import('../_components/types').Session[];
+}
+
+/**
+ * Mutation: PATCH /lms/courses/:id/structure/sessions/reorder
+ *
+ * Optimistic: UI is already updated by the Zustand store before this runs.
+ * On error: rolls back via setStructureFromApi with the previous snapshot.
+ */
+export function useReorderSessionsMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const setStructureFromApi = useStructureStore((s) => s.setStructureFromApi);
+  const lessons = useStructureStore((s) => s.lessons);
+
+  const qKey = courseStructureQueryKey(courseId);
+
+  return useMutation({
+    mutationFn: ({ orderedIds }: ReorderSessionsVars) =>
+      apiReorderSessions(request, courseId, {
+        sessionIds: orderedIds.map(Number),
+      }),
+    onMutate: async ({ orderedIds }) => {
+      // Cancel any in-flight refetches so they don't overwrite optimistic state.
+      await queryClient.cancelQueries({ queryKey: qKey });
+      const previousCache =
+        queryClient.getQueryData<CourseStructureCacheData>(qKey);
+      // Reflect the new order in the cache immediately.
+      queryClient.setQueryData<CourseStructureCacheData>(qKey, (old) => {
+        if (!old) return old;
+        const map = new Map(old.sessions.map((s) => [s.id, s]));
+        const reordered = orderedIds
+          .map((id, i) => {
+            const s = map.get(id);
+            return s ? { ...s, order: i + 1 } : null;
+          })
+          .filter(Boolean) as import('../_components/types').Session[];
+        return { ...old, sessions: reordered };
+      });
+      return { previousCache };
+    },
+    onError: (_err, { previousSessions }, context) => {
+      // Rollback Zustand store.
+      setStructureFromApi({ sessions: previousSessions, lessons });
+      // Rollback cache to snapshot.
+      if (context?.previousCache) {
+        queryClient.setQueryData(qKey, context.previousCache);
+      }
+      toast.error('Erro ao salvar ordem das sessões — revertido');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useReorderLessonsMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface ReorderLessonsVars {
+  sessionId: string;
+  /** New ordered list of lesson IDs within the session. */
+  orderedIds: string[];
+  /** Snapshot of all lessons before the reorder (for rollback). */
+  previousLessons: import('../_components/types').Lesson[];
+}
+
+/**
+ * Mutation: PATCH /lms/courses/:id/structure/sessions/:sessionId/lessons/reorder
+ *
+ * Optimistic: UI is already updated by the Zustand store before this runs.
+ * On error: rolls back via setStructureFromApi with the previous snapshot.
+ */
+export function useReorderLessonsMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const sessions = useStructureStore((s) => s.sessions);
+  const setStructureFromApi = useStructureStore((s) => s.setStructureFromApi);
+
+  const qKey = courseStructureQueryKey(courseId);
+
+  return useMutation({
+    mutationFn: ({ sessionId, orderedIds }: ReorderLessonsVars) =>
+      apiReorderLessons(request, courseId, sessionId, {
+        lessonIds: orderedIds.map(Number),
+      }),
+    onMutate: async ({ orderedIds, sessionId }) => {
+      await queryClient.cancelQueries({ queryKey: qKey });
+      const previousCache =
+        queryClient.getQueryData<CourseStructureCacheData>(qKey);
+      queryClient.setQueryData<CourseStructureCacheData>(qKey, (old) => {
+        if (!old) return old;
+        const map = new Map(old.lessons.map((l) => [l.id, l]));
+        const sessionLessons = orderedIds
+          .map((id, i) => {
+            const l = map.get(id);
+            return l ? { ...l, sessionId, order: i + 1 } : null;
+          })
+          .filter(Boolean) as import('../_components/types').Lesson[];
+        const otherLessons = old.lessons.filter(
+          (l) => l.sessionId !== sessionId
+        );
+        return { ...old, lessons: [...otherLessons, ...sessionLessons] };
+      });
+      return { previousCache };
+    },
+    onError: (_err, { previousLessons }, context) => {
+      setStructureFromApi({ sessions, lessons: previousLessons });
+      if (context?.previousCache) {
+        queryClient.setQueryData(qKey, context.previousCache);
+      }
+      toast.error('Erro ao salvar ordem das aulas — revertido');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useMoveLessonMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface MoveLessonVars {
+  lessonId: string;
+  fromSessionId: string;
+  toSessionId: string;
+  toIndex: number;
+  /** Snapshot of all lessons before the move (for rollback). */
+  previousLessons: import('../_components/types').Lesson[];
+}
+
+/**
+ * Mutation: PATCH /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId/move
+ *
+ * Optimistic: UI is already updated by the Zustand store (moveLesson) before this runs.
+ * On error: rolls back via setStructureFromApi with the previous snapshot.
+ */
+export function useMoveLessonMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const sessions = useStructureStore((s) => s.sessions);
+  const setStructureFromApi = useStructureStore((s) => s.setStructureFromApi);
+
+  const qKey = courseStructureQueryKey(courseId);
+
+  return useMutation({
+    mutationFn: ({
+      lessonId,
+      fromSessionId,
+      toSessionId,
+      toIndex,
+    }: MoveLessonVars) =>
+      apiMoveLesson(request, courseId, fromSessionId, lessonId, {
+        toSessionId: Number(toSessionId),
+        toIndex,
+      }),
+    onMutate: async ({ lessonId, toSessionId, toIndex }) => {
+      await queryClient.cancelQueries({ queryKey: qKey });
+      const previousCache =
+        queryClient.getQueryData<CourseStructureCacheData>(qKey);
+      queryClient.setQueryData<CourseStructureCacheData>(qKey, (old) => {
+        if (!old) return old;
+        const lesson = old.lessons.find((l) => l.id === lessonId);
+        if (!lesson) return old;
+        const others = old.lessons.filter((l) => l.id !== lessonId);
+        const movedLesson = {
+          ...lesson,
+          sessionId: toSessionId,
+          order: toIndex + 1,
+        };
+        return { ...old, lessons: [...others, movedLesson] };
+      });
+      return { previousCache };
+    },
+    onError: (_err, { previousLessons }, context) => {
+      setStructureFromApi({ sessions, lessons: previousLessons });
+      if (context?.previousCache) {
+        queryClient.setQueryData(qKey, context.previousCache);
+      }
+      toast.error('Erro ao mover aula — revertido');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useDuplicateSessionMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Mutation: POST /lms/courses/:id/structure/sessions/:sessionId/duplicate
+ *
+ * Creates a full copy of the session and all its lessons.
+ * Non-optimistic: waits for API then adds real items to store.
+ */
+export function useDuplicateSessionMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const sessions = useStructureStore((s) => s.sessions);
+  const addSessionWithLessonsFromApi = useStructureStore(
+    (s) => s.addSessionWithLessonsFromApi
+  );
+
+  return useMutation({
+    mutationFn: ({ sessionId }: { sessionId: string }) =>
+      apiDuplicateSession(request, courseId, sessionId),
+    onSuccess: (data) => {
+      const session = normalizeSession(data.session, sessions.length);
+      const lessons = data.lessons.map((l, i) => normalizeLesson(l, i));
+      addSessionWithLessonsFromApi(session, lessons);
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.success(`Sessão duplicada`);
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao duplicar sessão');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useDuplicateLessonMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Mutation: POST /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId/duplicate
+ *
+ * Creates a copy of the lesson in the same session.
+ * Non-optimistic: waits for API then adds the real item to store.
+ */
+export function useDuplicateLessonMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const lessons = useStructureStore((s) => s.lessons);
+  const addLessonFromApi = useStructureStore((s) => s.addLessonFromApi);
+
+  return useMutation({
+    mutationFn: ({
+      sessionId,
+      lessonId,
+    }: {
+      sessionId: string;
+      lessonId: string;
+    }) => apiDuplicateLesson(request, courseId, sessionId, lessonId),
+    onSuccess: (apiLesson) => {
+      const lesson = normalizeLesson(apiLesson, lessons.length);
+      addLessonFromApi(lesson);
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.success('Aula duplicada');
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao duplicar aula');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// usePasteLessonsMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Mutation: POST /lms/courses/:id/structure/sessions/:sessionId/lessons/paste
+ *
+ * Creates copies of the given lesson IDs into the target session.
+ * Non-optimistic: waits for API then adds the new items to store.
+ */
+export function usePasteLessonsMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const lessons = useStructureStore((s) => s.lessons);
+  const addLessonsFromApi = useStructureStore((s) => s.addLessonsFromApi);
+  const clearClipboard = useStructureStore((s) => s.clearClipboard);
+
+  return useMutation({
+    mutationFn: ({
+      targetSessionId,
+      lessonIds,
+    }: {
+      targetSessionId: string;
+      lessonIds: string[];
+    }) =>
+      apiPasteLessons(request, courseId, targetSessionId, {
+        lessonIds: lessonIds.map(Number),
+      }),
+    onSuccess: (data, { lessonIds }) => {
+      const newLessons = data.lessons.map((l, i) =>
+        normalizeLesson(l, lessons.length + i)
+      );
+      addLessonsFromApi(newLessons);
+      clearClipboard();
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.success(
+        lessonIds.length > 1
+          ? `${lessonIds.length} aulas coladas`
+          : 'Aula colada'
+      );
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao colar aulas');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// usePasteSessionsMutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Duplicates each copied session (and its lessons) via the duplicate endpoint.
+ * "Colar sessão" = duplicate each session in the clipboard into the same course.
+ *
+ * Non-optimistic: fires duplicate requests serially, then adds all results.
+ */
+export function usePasteSessionsMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const sessions = useStructureStore((s) => s.sessions);
+  const addSessionWithLessonsFromApi = useStructureStore(
+    (s) => s.addSessionWithLessonsFromApi
+  );
+  const clearClipboard = useStructureStore((s) => s.clearClipboard);
+
+  return useMutation({
+    mutationFn: ({ sessionIds }: { sessionIds: string[] }) =>
+      Promise.all(
+        sessionIds.map((id) => apiDuplicateSession(request, courseId, id))
+      ),
+    onSuccess: (results, { sessionIds }) => {
+      results.forEach((data, i) => {
+        const session = normalizeSession(data.session, sessions.length + i);
+        const lessons = data.lessons.map((l, li) => normalizeLesson(l, li));
+        addSessionWithLessonsFromApi(session, lessons);
+      });
+      clearClipboard();
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.success(
+        sessionIds.length > 1
+          ? `${sessionIds.length} sessões coladas`
+          : 'Sessão colada'
+      );
+    },
+    onError: () => {
+      void queryClient.invalidateQueries({
+        queryKey: courseStructureQueryKey(courseId),
+      });
+      toast.error('Erro ao colar sessões');
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useMoveLessonsMutation  (bulk)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Moves multiple lessons to a target session, calling the move endpoint for each.
+ * Optimistic: caller updates store before calling mutate().
+ * On error: rolls back store to snapshot.
+ */
+export function useMoveLessonsMutation() {
+  const { request } = useApp();
+  const queryClient = useQueryClient();
+  const courseId = useStructureStore((s) => s.courseId);
+  const sessions = useStructureStore((s) => s.sessions);
+  const setStructureFromApi = useStructureStore((s) => s.setStructureFromApi);
+
+  const qKey = courseStructureQueryKey(courseId);
+
+  return useMutation({
+    mutationFn: async ({
+      moves,
+    }: {
+      moves: Array<{
+        lessonId: string;
+        fromSessionId: string;
+        toSessionId: string;
+        toIndex: number;
+      }>;
+      previousLessons: import('../_components/types').Lesson[];
+    }) => {
+      // Sequential to preserve order integrity in the target session
+      for (const m of moves) {
+        await apiMoveLesson(request, courseId, m.fromSessionId, m.lessonId, {
+          toSessionId: Number(m.toSessionId),
+          toIndex: m.toIndex,
+        });
+      }
+    },
+    onMutate: async ({ moves }) => {
+      await queryClient.cancelQueries({ queryKey: qKey });
+      const previousCache =
+        queryClient.getQueryData<CourseStructureCacheData>(qKey);
+      queryClient.setQueryData<CourseStructureCacheData>(qKey, (old) => {
+        if (!old) return old;
+        const moveMap = new Map(moves.map((m) => [m.lessonId, m]));
+        return {
+          ...old,
+          lessons: old.lessons.map((l) => {
+            const m = moveMap.get(l.id);
+            return m
+              ? { ...l, sessionId: m.toSessionId, order: m.toIndex + 1 }
+              : l;
+          }),
+        };
+      });
+      return { previousCache };
+    },
+    onError: (_err, { previousLessons }, context) => {
+      setStructureFromApi({ sessions, lessons: previousLessons });
+      if (context?.previousCache) {
+        queryClient.setQueryData(qKey, context.previousCache);
+      }
+      toast.error('Erro ao mover aulas — revertido');
+    },
+  });
+}