academe-kit 0.9.8 → 0.10.0

package/dist/types/index.d.ts

@@ -16,6 +16,7 @@ export { useProtectedAppColors } from "./components/ProtectedApp";
 export type { AcademeKeycloakContextProps, SecurityProviderProps, KeycloakUser, SecurityContextType, AcademeUser, } from "./context/SecurityProvider/types";
 export { createAcademeApiClient } from "./services";
 export type { AcademeApiClient, AcademeServices } from "./services";
+export type { ChallengeUserQuizAttempt, ChallengeUserQuizAttemptsResponse, } from "./services/ChallengeService";
 export { cn } from "./lib/utils";
 import "./index.css";
 import "./styles/globals.css";

package/dist/types/services/ChallengeService.d.ts

@@ -28,6 +28,35 @@ export interface UpdateEvaluationCriterionBody {
     description?: string;
     index?: number;
 }
+export interface ChallengeUserQuizAttempt {
+    challengeStepId: string;
+    challengeStepName: string;
+    challengeStepIndex: number;
+    courseModuleId: string;
+    courseModuleTitle: string;
+    quizId: string;
+    quizTitle: string;
+    attempt: {
+        id: string;
+        score: number;
+        passed: boolean;
+        startedAt: string;
+        completedAt: string | null;
+    } | null;
+    certificate: {
+        id: string;
+        certificateNumber: string;
+        url: string | null;
+    } | null;
+}
+export interface ChallengeUserQuizAttemptsResponse {
+    data?: {
+        status?: string;
+        data?: ChallengeUserQuizAttempt[];
+    };
+    error?: unknown;
+    response: Response;
+}
 export declare function createChallengeService(apiClient: AcademeApiClient): {
     /**
      * List challenges with filters and pagination
@@ -339,6 +368,12 @@ export declare function createChallengeService(apiClient: AcademeApiClient): {
             title?: string;
         };
     }, `${string}/${string}`>>;
+    /**
+     * Get a user's quiz attempts for the quizzes attached to this challenge's
+     * course modules (one entry per step with course_module.quiz_id).
+     * Defaults to the authenticated user when userId is omitted.
+     */
+    getUserQuizAttempts(challengeId: string, userId?: string): Promise<ChallengeUserQuizAttemptsResponse>;
     /**
      * Add a step to the challenge
      */

package/dist/types/services/ReportService.d.ts

@@ -570,6 +570,81 @@ export declare function createReportService(apiClient: AcademeApiClient): {
             query: GetTopStudentsParams;
         };
     }, `${string}/${string}`>>;
+    /**
+     * Get encourage dashboard for an institution
+     * Retorna o payload agregado da tela /new-dashboard:
+     * overview (com lista de períodos do ano letivo + flag isAllPeriods),
+     * KPIs, licenças (alunos), jornada (cursos do bimestre selecionado ou do
+     * ano letivo quando allPeriods), submissões do bimestre corrente,
+     * desempenho por turma, top alunos e top professores do bimestre.
+     *
+     * @param id                UUID da instituição.
+     * @param params.periodId   UUID do educational_model_period. Quando omitido,
+     *                          o backend resolve para o período corrente (NOW).
+     *                          Ignorado quando allPeriods=true.
+     * @param params.allPeriods Quando true, desliga o recorte por período em
+     *                          Jornada/Classes/TopTeachers — passa a refletir
+     *                          o ano letivo inteiro. SubmissionsCard continua
+     *                          sempre no bimestre corrente.
+     */
+    getEncourageDashboardByInstitution(id: string, params?: {
+        periodId?: string;
+        allPeriods?: boolean;
+    }): Promise<import("openapi-fetch").FetchResponse<{
+        parameters: {
+            query?: {
+                periodId?: string;
+                allPeriods?: "true";
+            };
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: import("../types/academe-api").components["schemas"]["EncourageDashboardResponse"];
+                    };
+                };
+            };
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    }, {
+        params: {
+            path: {
+                id: string;
+            };
+            query: {
+                periodId?: string;
+                allPeriods?: "true";
+            } | undefined;
+        };
+    }, `${string}/${string}`>>;
 };
 export type ReportService = ReturnType<typeof createReportService>;
 export {};

package/dist/types/services/SubmissionService.d.ts

@@ -37,7 +37,14 @@ export declare function createSubmissionService(apiClient: AcademeApiClient): {
                     "application/json": {
                         status?: string;
                         data?: import("../types/academe-api").components["schemas"]["Submission"][];
-                        meta?: import("../types/academe-api").components["schemas"]["PaginationMeta"];
+                        meta?: import("../types/academe-api").components["schemas"]["PaginationMeta"] & {
+                            statusCounts?: {
+                                submitted?: number;
+                                ai_evaluated?: number;
+                                approved?: number;
+                                rejected?: number;
+                            };
+                        };
                     };
                 };
             };

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

@@ -2790,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;
@@ -10559,7 +10644,12 @@ export interface paths {
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    /** @description UUID do educational_model_period. Quando omitido, o backend resolve para o período corrente (NOW). Ignorado quando allPeriods=true. */
+                    periodId?: string;
+                    /** @description Quando 'true', desliga o recorte por período em Jornada/Classes/TopTeachers — passa a refletir o ano letivo inteiro. SubmissionsCard continua sempre no bimestre corrente. */
+                    allPeriods?: "true";
+                };
                 header?: never;
                 path: {
                     /** @description ID da instituição */
@@ -11619,7 +11709,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;
+                                };
+                            };
                         };
                     };
                 };
@@ -12281,6 +12386,128 @@ 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;
@@ -15145,6 +15372,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: {
             /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "academe-kit",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "type": "module",
   "description": "Official React SDK for Academe ecosystem - Authentication, protected routes, API services, and UI components for educational management applications",
   "main": "dist/index.cjs",
@@ -99,4 +99,4 @@
     "tailwind-merge": "^3.3.1",
     "tailwindcss-animate": "^1.0.7"
   }
-}
+}