academe-kit 0.9.7 → 0.9.9

package/dist/types/types/academe-api.d.ts

@@ -2019,6 +2019,12 @@ export interface paths {
                     templatesOnly?: boolean;
                     /** @description Search by title */
                     search?: string;
+                    /**
+                     * @description Comma-separated list of extra relations to load. Currently supported:
+                     *     `steps` — embeds each challenge's `steps` (with their catalog `step`).
+                     *     Opt-in to avoid penalizing list views that don't need them.
+                     */
+                    include?: "steps";
                     /** @description Page number */
                     page?: components["parameters"]["page"];
                     /** @description Items per page */
@@ -2073,6 +2079,11 @@ export interface paths {
                         maxGroupMembers?: number;
                         /** @default false */
                         isInviteOnly?: boolean;
+                        /**
+                         * Format: uuid
+                         * @description Curso ao qual o desafio está associado (agrupa a jornada no dashboard)
+                         */
+                        courseId: string;
                         /** Format: uuid */
                         institutionId?: string | null;
                         /** Format: uuid */
@@ -2215,6 +2226,8 @@ export interface paths {
                         maxGroupMembers?: number;
                         isInviteOnly?: boolean;
                         /** Format: uuid */
+                        courseId?: string;
+                        /** Format: uuid */
                         serieId?: string;
                         index?: number;
                         /** @enum {string} */
@@ -2321,9 +2334,10 @@ export interface paths {
         /**
          * Add a step to the challenge
          * @description Polymorphic validation:
-         *     - When step.type=course, courseId is required
          *     - When step.type=tutorial, tutorialVideoUrl is required
-         *     - Other types must not have these specialized fields
+         *     - The course of a step is determined by the parent challenge's courseId.
+         *       Optionally, courseModuleId pinpoints a specific module within that course.
+         *     - tutorial fields are optional on any step type.
          */
         post: {
             parameters: {
@@ -2347,8 +2361,6 @@ export interface paths {
                         description?: string;
                         index: number;
                         /** Format: uuid */
-                        courseId?: string;
-                        /** Format: uuid */
                         courseModuleId?: string;
                         tutorialTitle?: string;
                         tutorialDescription?: string;
@@ -2778,6 +2790,91 @@ export interface paths {
         };
         trace?: never;
     };
+    "/challenges/{id}/quiz-attempts": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a user's quiz attempts for this challenge's course modules
+         * @description Returns the quiz attempts of `userId` on every quiz attached to a course
+         *     module that is referenced by one of this challenge's steps. Optionally
+         *     includes the issued certificate per attempt.
+         *
+         *     Each entry corresponds to a `challenges_steps` row that has a non-null
+         *     `course_module_id` whose `course_module.quiz_id` is also non-null.
+         *     `attempt` is `null` when the user has not yet attempted that quiz.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Defaults to the authenticated user when omitted. */
+                    userId?: string;
+                };
+                header?: never;
+                path: {
+                    /** @description Resource ID */
+                    id: components["parameters"]["id"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description List of quiz attempts (one per quiz-bearing challenge step) */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: {
+                                /** Format: uuid */
+                                challengeStepId?: string;
+                                challengeStepName?: string;
+                                challengeStepIndex?: number;
+                                /** Format: uuid */
+                                courseModuleId?: string;
+                                courseModuleTitle?: string;
+                                /** Format: uuid */
+                                quizId?: string;
+                                quizTitle?: string;
+                                attempt?: {
+                                    /** Format: uuid */
+                                    id?: string;
+                                    score?: number;
+                                    passed?: boolean;
+                                    /** Format: date-time */
+                                    startedAt?: string;
+                                    /** Format: date-time */
+                                    completedAt?: string | null;
+                                } | null;
+                                certificate?: {
+                                    /** Format: uuid */
+                                    id?: string;
+                                    certificateNumber?: string;
+                                    url?: string | null;
+                                } | null;
+                            }[];
+                        };
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                401: components["responses"]["Unauthorized"];
+                404: components["responses"]["NotFound"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/classrooms": {
         parameters: {
             query?: never;
@@ -9476,6 +9573,8 @@ export interface paths {
                     page?: number;
                     /** @description Items per page */
                     limit?: number;
+                    /** @description When true, returns questions in random order with shuffled answer alternatives. Each request reshuffles independently. */
+                    randomize?: boolean;
                 };
                 header?: never;
                 path?: never;
@@ -10529,6 +10628,76 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/reports/encourage-dashboard/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Payload completo da nova tela /new-dashboard
+         * @description Retorna o dashboard agregado por instituição: overview, KPIs,
+         *     licenças (apenas tipo aluno), jornada (cursos deduplicados),
+         *     submissões, desempenho por turma, top 10 alunos (por certificados,
+         *     desempate por nota) e top 10 professores (por avaliações).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description ID da instituição */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Payload completo do encourage dashboard */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: components["schemas"]["EncourageDashboardResponse"];
+                        };
+                    };
+                };
+                /** @description institutionId inválido */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Não autenticado */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Erro interno */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/roles": {
         parameters: {
             query?: never;
@@ -11535,7 +11704,22 @@ export interface paths {
                             /** @example success */
                             status?: string;
                             data?: components["schemas"]["Submission"][];
-                            meta?: components["schemas"]["PaginationMeta"];
+                            meta?: components["schemas"]["PaginationMeta"] & {
+                                /**
+                                 * @description Contagem por status, ignorando o filtro `status`. Útil para
+                                 *     alimentar abas/pills sem requisições adicionais.
+                                 */
+                                statusCounts?: {
+                                    /** @example 12 */
+                                    submitted?: number;
+                                    /** @example 4 */
+                                    ai_evaluated?: number;
+                                    /** @example 30 */
+                                    approved?: number;
+                                    /** @example 2 */
+                                    rejected?: number;
+                                };
+                            };
                         };
                     };
                 };
@@ -12197,6 +12381,208 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/user-challenge-progress/journey": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Jornada completa pré-computada do aluno autenticado
+         * @description Retorna todos os desafios da série com suas etapas e o status de progresso do aluno
+         *     já computados pelo backend. Substitui as ~25 chamadas HTTP paralelas que o frontend
+         *     fazia anteriormente para montar a tela de jornada.
+         *
+         *     **Regra de prioridade:** para cada `index` de desafio dentro da série, o backend
+         *     prefere o challenge específico da instituição do aluno sobre o template global
+         *     (`institution_id IS NULL`). Isso permite que escolas customizem desafios pontuais
+         *     sem recriar toda a jornada.
+         *
+         *     **Resolução da série:** se `serieId` não for informado, o backend resolve
+         *     automaticamente a partir da turma (`institutionClassroom`) do aluno. Se o aluno
+         *     não estiver em nenhuma turma e `serieId` também não for passado, retorna
+         *     `challenges: []` com `serieId: null`.
+         *
+         *     **Status por etapa:** `done` = completedAt preenchido; `current` = primeira etapa
+         *     não concluída (apenas uma por vez); `locked` = todas as demais.
+         *
+         *     **Progresso:** para etapas `type=course` no status `current`, o campo `progress`
+         *     reflete o percentual de lições concluídas no módulo. Para `done` é sempre 100,
+         *     para `locked` é sempre 0.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /**
+                     * @description ID da série a filtrar. Opcional — se omitido, o backend resolve pela turma do aluno.
+                     *     Útil para pré-visualização administrativa ou quando o aluno pertence a múltiplas séries.
+                     */
+                    serieId?: string;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Jornada pré-computada com desafios e etapas */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "status": "success",
+                         *       "data": {
+                         *         "serieId": "a1b2c3d4-0000-0000-0000-000000000001",
+                         *         "serieLabel": "6º ANO",
+                         *         "challenges": [
+                         *           {
+                         *             "id": "a1b2c3d4-0000-0000-0000-000000000002",
+                         *             "title": "Desafio 1 — Energia Limpa",
+                         *             "index": 0,
+                         *             "courseId": "a1b2c3d4-0000-0000-0000-000000000003",
+                         *             "isUpcoming": false,
+                         *             "steps": [
+                         *               {
+                         *                 "id": "a1b2c3d4-0000-0000-0000-000000000010",
+                         *                 "name": "Inicie o desafio",
+                         *                 "index": 0,
+                         *                 "type": "challenge",
+                         *                 "color": "#1AC84A",
+                         *                 "icon": "LuStar",
+                         *                 "status": "done",
+                         *                 "progress": 100,
+                         *                 "courseModuleId": null,
+                         *                 "courseModuleName": null
+                         *               },
+                         *               {
+                         *                 "id": "a1b2c3d4-0000-0000-0000-000000000011",
+                         *                 "name": "Módulo de IA",
+                         *                 "index": 1,
+                         *                 "type": "course",
+                         *                 "color": "#8030D8",
+                         *                 "icon": "LuCirclePlay",
+                         *                 "status": "current",
+                         *                 "progress": 67,
+                         *                 "courseModuleId": "a1b2c3d4-0000-0000-0000-000000000020",
+                         *                 "courseModuleName": "Introdução a IA"
+                         *               }
+                         *             ]
+                         *           }
+                         *         ]
+                         *       }
+                         *     }
+                         */
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: components["schemas"]["JourneyView"];
+                        };
+                    };
+                };
+                /** @description serieId inválido (não é um UUID) */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/user-challenge-progress/challenges/{id}/advance": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Advance one tick in the user's journey on a challenge
+         * @description Unified journey advancement, agnostic of step type. Each call performs ONE action:
+         *
+         *     1. Resolves the current step = first active step (by index) not yet completed by the user.
+         *     2. If no progress row exists for that step → creates one (action='started').
+         *     3. If progress row exists with completed_at IS NULL → sets completed_at (action='completed').
+         *     4. If all steps are completed → no-op (action='finished').
+         *
+         *     Web and mobile clients must use this endpoint regardless of the step type
+         *     (challenge, course, tutorial, publication, evaluation, certificate).
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Resource ID */
+                    id: components["parameters"]["id"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Tick result */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: {
+                                /** @enum {string} */
+                                action?: "started" | "completed" | "finished";
+                                /** Format: uuid */
+                                challengeId?: string;
+                                currentStep?: {
+                                    /** Format: uuid */
+                                    id?: string;
+                                    index?: number;
+                                    name?: string;
+                                    /** Format: date-time */
+                                    startedAt?: string | null;
+                                    /** Format: date-time */
+                                    completedAt?: string | null;
+                                } | null;
+                                /** @description Next step in the journey. When action='completed', this step is also auto-started on the same call (startedAt populated). */
+                                nextStep?: {
+                                    /** Format: uuid */
+                                    id?: string;
+                                    index?: number;
+                                    name?: string;
+                                    /** Format: date-time */
+                                    startedAt?: string | null;
+                                } | null;
+                            };
+                        };
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                404: components["responses"]["NotFound"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/user-challenge-progress/steps/{stepId}/start": {
         parameters: {
             query?: never;
@@ -12207,9 +12593,12 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Start a challenge step (idempotent)
-         * @description Creates a user_challenge_progress row. If one already exists for this user/step,
+         * [Internal/Admin] Force-start a specific challenge step (idempotent)
+         * @description Creates a user_challenge_progress row for the given step. If one already exists,
          *     returns the existing row (idempotent).
+         *
+         *     Client apps (web/mobile) should use POST /user-challenge-progress/challenges/{id}/advance
+         *     instead. This endpoint is retained for internal/admin tooling that needs to force a state.
          */
         post: {
             parameters: {
@@ -12256,8 +12645,12 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Mark step as completed
-         * @description Sets completed_at on the user's progress row. Idempotent (no-op if already completed)
+         * [Internal/Admin] Force-complete a specific challenge step
+         * @description Sets completed_at on the user's progress row for the given step. Idempotent
+         *     (no-op if already completed).
+         *
+         *     Client apps (web/mobile) should use POST /user-challenge-progress/challenges/{id}/advance
+         *     instead. This endpoint is retained for internal/admin tooling that needs to force a state.
          */
         post: {
             parameters: {
@@ -14274,6 +14667,9 @@ export interface components {
             createdAt: string;
             /** Format: date-time */
             updatedAt: string;
+            organization?: components["schemas"]["Organization"] | null;
+            address?: components["schemas"]["Address"] | null;
+            institutionReward?: Record<string, never> | null;
         };
         Organization: {
             /** Format: uuid */
@@ -14819,6 +15215,11 @@ export interface components {
             maxGroupMembers?: number;
             /** @example false */
             isInviteOnly?: boolean;
+            /**
+             * Format: uuid
+             * @description Curso ao qual o desafio está associado (agrupa a jornada no dashboard)
+             */
+            courseId?: string;
             /**
              * Format: uuid
              * @description Null para template global
@@ -14854,6 +15255,8 @@ export interface components {
             createdAt?: string;
             /** Format: date-time */
             updatedAt?: string;
+            /** @description Populado quando `include=steps` é informado no GET /challenges, ou via GET /challenges/{id} */
+            steps?: components["schemas"]["ChallengeStep"][];
         };
         ChallengeMedia: {
             /** Format: uuid */
@@ -14882,10 +15285,8 @@ export interface components {
             index?: number;
             /**
              * Format: uuid
-             * @description Obrigatório quando step type=course
+             * @description Opcional. Quando step type=course, aponta para o módulo específico do curso do challenge.
              */
-            courseId?: string | null;
-            /** Format: uuid */
             courseModuleId?: string | null;
             tutorialTitle?: string | null;
             tutorialDescription?: string | null;
@@ -14896,6 +15297,8 @@ export interface components {
             createdAt?: string;
             /** Format: date-time */
             updatedAt?: string;
+            /** @description Catálogo do step (cor, ícone, tipo). Populado junto com o relation `steps.step`. */
+            step?: components["schemas"]["Step"];
         };
         /** @description Item do checklist descritivo de entrega */
         ChallengeDeliveryStep: {
@@ -14967,6 +15370,99 @@ export interface components {
             /** Format: date-time */
             updatedAt?: string;
         };
+        /** @description Etapa de um desafio com status computado pelo backend */
+        JourneyStepView: {
+            /**
+             * Format: uuid
+             * @description ID do challenge_step
+             */
+            id: string;
+            /** @example Módulo de IA */
+            name: string;
+            /**
+             * @description Ordem da etapa dentro do desafio
+             * @example 1
+             */
+            index: number;
+            /**
+             * @description Tipo da etapa (do catálogo de steps)
+             * @example course
+             * @enum {string}
+             */
+            type: "challenge" | "course" | "tutorial" | "publication" | "evaluation" | "certificate";
+            /**
+             * @description Cor hex do step catalog
+             * @example #8030D8
+             */
+            color: string;
+            /**
+             * @description Nome do ícone Lucide do step catalog
+             * @example LuCirclePlay
+             */
+            icon: string;
+            /**
+             * @description Status computado pelo backend: done=concluído, current=etapa ativa, locked=ainda bloqueado
+             * @example current
+             * @enum {string}
+             */
+            status: "done" | "current" | "locked";
+            /**
+             * @description Percentual de progresso (0-100). Para done=100, para locked=0, para current=% do curso ou 0
+             * @example 67
+             */
+            progress: number;
+            /**
+             * Format: uuid
+             * @description ID do módulo do curso referenciado por esta etapa (apenas quando type=course)
+             */
+            courseModuleId?: string | null;
+            /**
+             * @description Título do módulo do curso (apenas quando courseModuleId não é null)
+             * @example Introdução a IA
+             */
+            courseModuleName?: string | null;
+        };
+        /** @description Desafio da jornada com suas etapas e status computados */
+        JourneyChallengeView: {
+            /**
+             * Format: uuid
+             * @description ID do challenge
+             */
+            id: string;
+            /** @example Desafio 1 — Energia Limpa */
+            title: string;
+            /**
+             * @description Ordem do desafio na série
+             * @example 0
+             */
+            index: number;
+            /**
+             * Format: uuid
+             * @description Curso ao qual o desafio está associado
+             */
+            courseId: string;
+            /**
+             * @description True quando o desafio ainda não está disponível para o aluno (challenge seguinte ao ativo com steps pendentes)
+             * @example false
+             */
+            isUpcoming: boolean;
+            steps: components["schemas"]["JourneyStepView"][];
+        };
+        /** @description Resposta completa do endpoint GET /user-challenge-progress/journey — dados pré-computados para renderização direta da tela de jornada */
+        JourneyView: {
+            /** @description Desafios da jornada ordenados por index, com prioridade escola > template aplicada */
+            challenges: components["schemas"]["JourneyChallengeView"][];
+            /**
+             * Format: uuid
+             * @description ID da série resolvida (da turma do aluno, ou do query param serieId)
+             */
+            serieId: string | null;
+            /**
+             * @description Rótulo legível da série para exibição na UI
+             * @example 6º ANO
+             */
+            serieLabel: string | null;
+        };
         /** @description Aggregated progress of a user on a course or module, derived from users_course_log completion events */
         UsersCourseLogProgress: {
             /**
@@ -15905,6 +16401,121 @@ export interface components {
             totalStudents?: number;
             year?: number;
         };
+        EncourageActivePeriod: {
+            /** Format: uuid */
+            id?: string;
+            /** Format: date-time */
+            start?: string;
+            /** Format: date-time */
+            end?: string;
+            /** @example Bimestre */
+            label?: string;
+            /** @example 4 */
+            periodsPerYear?: number;
+        };
+        EncourageOverview: {
+            userFirstName?: string;
+            institutionName?: string;
+            activePeriod?: components["schemas"]["EncourageActivePeriod"];
+            /** Format: float */
+            globalProgressPct?: number;
+        };
+        EncourageKpis: {
+            totalStudents?: number;
+            /** Format: float */
+            totalStudentsDeltaPct?: number;
+            completedProjects?: number;
+            /** Format: float */
+            completedProjectsDeltaPct?: number;
+            /** Format: float */
+            engagementRatePct?: number;
+            /** Format: float */
+            engagementRateDeltaPct?: number;
+            neverLoggedIn?: number;
+            neverLoggedInDelta?: number;
+        };
+        /** @description Licenças do tipo aluno (seats.group_id → group.type = 'student') */
+        EncourageLicenses: {
+            used?: number;
+            total?: number;
+            /** Format: float */
+            pct?: number;
+            available?: number;
+        };
+        EncourageJourneyCourse: {
+            /** Format: uuid */
+            courseId?: string;
+            title?: string;
+            /** Format: date-time */
+            dueDate?: string;
+            /** Format: float */
+            progressPct?: number;
+            challengesCount?: number;
+            color?: string;
+        };
+        EncourageJourney: {
+            totalCourses?: number;
+            /** Format: float */
+            averageProgressPct?: number;
+            /** @enum {string} */
+            periodKind?: "semester" | "trimester" | "bimester";
+            courses?: components["schemas"]["EncourageJourneyCourse"][];
+        };
+        EncourageSubmissions: {
+            total?: number;
+            evaluated?: number;
+            awaitingTeacher?: number;
+            awaitingAi?: number;
+        };
+        EncourageClassPerformance: {
+            /** Format: uuid */
+            classroomId?: string;
+            /** @example 2º A — Médio */
+            name?: string;
+            /** @example Manhã */
+            meta?: string;
+            /** @description Total de alunos cadastrados na turma */
+            studentsCount?: number;
+            /** @description Alunos que submeteram pelo menos 1 challenge do período ativo */
+            submittedCount?: number;
+            /** Format: float */
+            progressPct?: number;
+            /** @enum {string} */
+            level?: "high" | "medium" | "low";
+        };
+        EncourageTopStudent: {
+            /** Format: uuid */
+            userId?: string;
+            rank?: number;
+            name?: string;
+            initials?: string;
+            avatarColor?: string;
+            certificates?: number;
+            /** Format: float */
+            averageScore?: number;
+        };
+        EncourageTopTeacher: {
+            /** Format: uuid */
+            userId?: string;
+            rank?: number;
+            name?: string;
+            initials?: string;
+            avatarColor?: string;
+            evaluationsCount?: number;
+            averageEvaluationSeconds?: number;
+            /** Format: float */
+            averageScore?: number;
+        };
+        EncourageDashboardResponse: {
+            overview?: components["schemas"]["EncourageOverview"];
+            kpis?: components["schemas"]["EncourageKpis"];
+            licenses?: components["schemas"]["EncourageLicenses"];
+            journey?: components["schemas"]["EncourageJourney"];
+            submissions?: components["schemas"]["EncourageSubmissions"];
+            classes?: components["schemas"]["EncourageClassPerformance"][];
+            topStudents?: components["schemas"]["EncourageTopStudent"][];
+            topTeachers?: components["schemas"]["EncourageTopTeacher"][];
+        };
         UserCreationRequest: {
             /**
              * Format: uuid