academe-kit 0.11.5 → 0.11.7

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

@@ -2875,6 +2875,94 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/challenges/{id}/participants": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List the students taking part in this challenge
+         * @description Returns the roster of students for the challenge along with each
+         *     student's status, derived from `submissions` (latest attempt) and
+         *     `user_challenge_progress` (whether any step was started).
+         *
+         *     The roster is built from `institution_registration` rows of the given
+         *     institution, filtered by the challenge's serie. `institutionId` and
+         *     `serieId` may be supplied via query to provide the viewing context —
+         *     useful for global template challenges (`institution_id IS NULL`) shown
+         *     via fallback in the pedagogical portal. They default to the
+         *     challenge's own institution/serie when omitted.
+         *
+         *     Status values: `novo` (not started), `andamento` (started a step, no
+         *     submission), `entregue` (submitted | ai_evaluated), `aprovado`
+         *     (approved), `rejeitado` (rejected).
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Viewing institution. Defaults to the challenge's institution. */
+                    institutionId?: string;
+                    /** @description Serie filter. Defaults to the challenge's serie. */
+                    serieId?: string;
+                };
+                header?: never;
+                path: {
+                    /** @description Resource ID */
+                    id: components["parameters"]["id"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Roster of participants with derived status */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: {
+                                totalStudents?: number;
+                                classrooms?: {
+                                    /** Format: uuid */
+                                    id?: string;
+                                    name?: string;
+                                    count?: number;
+                                }[];
+                                participants?: {
+                                    /** Format: uuid */
+                                    userId?: string;
+                                    name?: string;
+                                    email?: string | null;
+                                    avatarUrl?: string | null;
+                                    /** Format: uuid */
+                                    classroomId?: string | null;
+                                    classroomName?: string | null;
+                                    /** @enum {string} */
+                                    status?: "novo" | "andamento" | "entregue" | "aprovado" | "rejeitado";
+                                    /** Format: uuid */
+                                    submissionId?: string | null;
+                                }[];
+                            };
+                        };
+                    };
+                };
+                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;
@@ -9643,6 +9731,67 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/quiz-questions/bulk": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Bulk create quiz questions
+         * @description Cria várias perguntas (com respostas) de uma vez para um quiz.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        quizId: string;
+                        questions: {
+                            text: string;
+                            type: "multiple_choice" | "true_false" | "open";
+                            points?: number;
+                            options?: {
+                                text: string;
+                                is_correct: boolean;
+                            }[];
+                        }[];
+                    };
+                };
+            };
+            responses: {
+                /** @description Questions created */
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: components["schemas"]["QuizQuestion"][];
+                        };
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                401: components["responses"]["Unauthorized"];
+                500: components["responses"]["ServerError"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/quiz-questions/{id}": {
         parameters: {
             query?: never;
@@ -9855,6 +10004,145 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/quiz/with-context": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List quizzes with course/module/category context
+         * @description Retrieve a paginated list of quizzes, each enriched with the course, module and category it belongs to. `context` is null for standalone quizzes.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Filter by quiz title */
+                    title?: string;
+                    /** @description Filter by active status */
+                    isActive?: boolean;
+                    /** @description Filter by creator user ID */
+                    createdBy?: string;
+                    /** @description Search in title */
+                    search?: string;
+                    /** @description Page number */
+                    page?: number;
+                    /** @description Items per page */
+                    limit?: number;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description List of quizzes with context */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: (components["schemas"]["Quiz"] & {
+                                context?: {
+                                    course?: {
+                                        id?: string;
+                                        title?: string;
+                                    } | null;
+                                    module?: {
+                                        id?: string;
+                                        title?: string;
+                                    } | null;
+                                    category?: {
+                                        id?: string;
+                                        name?: string;
+                                        color?: string | null;
+                                    } | null;
+                                } | null;
+                            })[];
+                            meta?: components["schemas"]["PaginationMeta"];
+                        };
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                500: components["responses"]["ServerError"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/quiz/generate-questions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Generate quiz questions with AI
+         * @description Gera perguntas a partir de um texto base via IA. Não persiste — apenas devolve.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        text: string;
+                        numQuestions: number;
+                        difficulty?: "facil" | "normal" | "dificil";
+                        existingQuestions?: string[];
+                        model?: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Generated questions */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: {
+                                question_text: string;
+                                question_type: "multiple_choice" | "true_false";
+                                points: number;
+                                options: {
+                                    text: string;
+                                    is_correct: boolean;
+                                }[];
+                            }[];
+                        };
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                401: components["responses"]["Unauthorized"];
+                500: components["responses"]["ServerError"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/quiz/{id}": {
         parameters: {
             query?: never;
@@ -11822,6 +12110,12 @@ export interface paths {
          *     - Cannot create after status=approved
          *     - Cannot exceed challenge.maxSubmissionsAttempts
          *     - attempt_number is computed server-side with a row lock (FOR UPDATE)
+         *
+         *     When `items` is provided, the submission and its files/links are persisted
+         *     in the SAME transaction (atomic) and AI evaluation is dispatched after commit.
+         *     Each item must have exactly ONE of fileId or url, and must match the
+         *     challenge.submissionType (file types require fileId; links require url).
+         *     This is the preferred path for clients (no separate POST /submissions/{id}/files).
          */
         post: {
             parameters: {
@@ -11846,6 +12140,17 @@ export interface paths {
                          */
                         groupId?: string;
                         description?: string;
+                        /**
+                         * @description Submission delivery. When present, files/links are stored atomically
+                         *     with the submission and AI evaluation is dispatched after commit.
+                         */
+                        items?: {
+                            /** Format: uuid */
+                            fileId?: string | null;
+                            /** Format: uri */
+                            url?: string | null;
+                            index?: number;
+                        }[];
                     };
                 };
             };
@@ -11860,6 +12165,45 @@ export interface paths {
                             /** @example success */
                             status?: string;
                             data?: components["schemas"]["Submission"];
+                            /**
+                             * @description Journey side-effects of the submission. On the FIRST attempt the
+                             *     publication step is completed and the user advances; `advance`
+                             *     carries the resulting tick so the client can animate the journey.
+                             *     `advance` is null on re-submissions (attempt > 1) or if the advance
+                             *     step failed (non-fatal — the submission is still created).
+                             */
+                            meta?: {
+                                advance?: {
+                                    /** @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;
+                                    nextStep?: {
+                                        /** Format: uuid */
+                                        id?: string;
+                                        index?: number;
+                                        name?: string;
+                                        /** Format: date-time */
+                                        startedAt?: string | null;
+                                    } | null;
+                                    autoCompletedSteps?: {
+                                        /** Format: uuid */
+                                        id?: string;
+                                        index?: number;
+                                        name?: string;
+                                    }[];
+                                } | null;
+                            };
                         };
                     };
                 };
@@ -11923,6 +12267,79 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/submissions/{id}/classroom-rank": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Ordem de entrega do aluno na turma para o desafio desta submissão
+         * @description Retorna a posição do aluno entre os colegas de turma (institution_classroom
+         *     via membership) a entregar o desafio, ordenando pela PRIMEIRA entrega de cada
+         *     aluno (MIN(submitted_at)). Usado pelo app do aluno como incentivo a entregar
+         *     cedo ("Você foi o Nº de X da turma a entregar"). Quando o aluno não tem turma
+         *     na instituição, retorna order=0 e classSize=0 e o cliente esconde o card.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Resource ID */
+                    id: components["parameters"]["id"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Posição na turma */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: {
+                                /**
+                                 * @description Posição do aluno (1-based) entre os que entregaram; 0 quando sem turma
+                                 * @example 3
+                                 */
+                                order?: number;
+                                /**
+                                 * @description Total de alunos da turma (independente de terem entregado)
+                                 * @example 28
+                                 */
+                                classSize?: number;
+                                /**
+                                 * @description Quantos alunos da turma já entregaram o desafio
+                                 * @example 12
+                                 */
+                                submittedCount?: number;
+                                /**
+                                 * @description true quando order está entre 1 e 3
+                                 * @example true
+                                 */
+                                earlyBird?: boolean;
+                            };
+                        };
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                404: components["responses"]["NotFound"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/submissions/{id}/files": {
         parameters: {
             query?: never;
@@ -12504,6 +12921,12 @@ export interface paths {
                      *     Útil para pré-visualização administrativa ou quando o aluno pertence a múltiplas séries.
                      */
                     serieId?: string;
+                    /**
+                     * @description Escola atual (contexto de instituição do app). Opcional — se omitido, usa a 1ª
+                     *     matrícula. A jornada é por escola: filtra os challenges e resolve a turma/série
+                     *     default a partir da membership do usuário NESTA instituição.
+                     */
+                    institutionId?: string;
                     /**
                      * @description [Admin] Quando presente, retorna a jornada do usuário-alvo em vez da do
                      *     autenticado. Usado pelo backoffice para visualizar a jornada de um aluno.
@@ -13401,6 +13824,97 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/users/me/classrooms": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Turmas e séries do usuário autenticado
+         * @description Contexto de matrícula do aluno: TODAS as suas turmas (com série, turno e
+         *     instituição), a escola ATUAL e a lista DEDUPLICADA de séries dessa escola.
+         *
+         *     Fonte única para o app: `classrooms` alimenta a listagem de turmas no
+         *     perfil; `currentInstitutionId` é a escola atual (o app mostra uma escola
+         *     por vez); `series` traz APENAS as séries da escola atual (deduplicada e
+         *     ordenada por nível/valor) — alimenta o seletor da jornada, que também é
+         *     por escola. O botão só aparece com 2+ séries na escola atual.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Turmas + séries acessíveis */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: {
+                                /**
+                                 * Format: uuid
+                                 * @description Escola atual (a da matrícula). As séries são desta escola.
+                                 */
+                                currentInstitutionId?: string | null;
+                                classrooms?: {
+                                    /** Format: uuid */
+                                    institutionClassroomId?: string;
+                                    /** Format: uuid */
+                                    classroomId?: string;
+                                    /** @example 6º A */
+                                    classroomName?: string;
+                                    /** @example manhã */
+                                    shiftName?: string | null;
+                                    /** Format: uuid */
+                                    institutionId?: string;
+                                    /** @example Escola Modelo */
+                                    institutionName?: string | null;
+                                    serie?: {
+                                        /** Format: uuid */
+                                        serieId?: string;
+                                        /** @example 6 */
+                                        serieValue?: number;
+                                        /** @example 6º ANO */
+                                        serieLabel?: string;
+                                        /** @enum {string} */
+                                        level?: "fundamental" | "medio";
+                                    } | null;
+                                }[];
+                                series?: {
+                                    /** Format: uuid */
+                                    serieId?: string;
+                                    /** @example 6 */
+                                    serieValue?: number;
+                                    /** @example 6º ANO */
+                                    serieLabel?: string;
+                                    /** @enum {string} */
+                                    level?: "fundamental" | "medio";
+                                }[];
+                            };
+                        };
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/users/me/push-tokens": {
         parameters: {
             query?: never;
@@ -15013,6 +15527,8 @@ export interface components {
             certificateTemplate?: components["schemas"]["CertificateTemplate"];
             /** @description Course information related to the certificate (extracted from Quiz or CertificateTemplate) */
             course?: components["schemas"]["CourseSimplified"];
+            /** @description Course module information related to the certificate (resolved from the quiz the student took). Null when the certificate came from a template course. */
+            module?: components["schemas"]["ModuleSimplified"];
         };
         /** @description Simplified course information included in certificate responses */
         CourseSimplified: {
@@ -15032,6 +15548,26 @@ export interface components {
              */
             description?: string | null;
         };
+        /** @description Simplified course module information included in certificate responses */
+        ModuleSimplified: {
+            /**
+             * Format: uuid
+             * @description Course module ID
+             */
+            id?: string;
+            /**
+             * @description Course module title
+             * @example Variables and Data Types
+             */
+            title?: string;
+            /** @description Course module description */
+            description?: string | null;
+            /**
+             * @description Course module workload in hours
+             * @example 40
+             */
+            duration?: number | null;
+        };
         /** @description Simplified quiz information included in course and module responses */
         QuizSimplified: {
             /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "academe-kit",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "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",