academe-kit 0.9.5 → 0.9.7

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

@@ -1282,6 +1282,68 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/certificates/{userId}/download-all": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Download all certificates of a user as a single PDF
+         * @description Downloads all certificates of the given user merged into a single PDF file.
+         *     Each certificate occupies one page in the resulting file.
+         *     PDFs are downloaded from S3 in parallel and merged using pdf-lib.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description ID of the user whose certificates will be downloaded */
+                    userId: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Merged PDF file containing all user certificates */
+                200: {
+                    headers: {
+                        /** @description attachment; filename="Meus-Certificados.pdf" */
+                        "Content-Disposition"?: string;
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/pdf": string;
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                /** @description No certificates found for the user */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example error */
+                            status?: string;
+                            /** @example No certificates found for this user */
+                            message?: string;
+                        };
+                    };
+                };
+                500: components["responses"]["ServerError"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/certificates": {
         parameters: {
             query?: never;
@@ -1291,13 +1353,24 @@ export interface paths {
         };
         /**
          * List all certificates
-         * @description Retrieve a list of all certificates in the system.
+         * @description Retrieve a paginated list of all certificates in the system.
          *     Each certificate includes course information (id, title, description) when available.
          *     Course data is extracted from the related Quiz through QuizAttempt.
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    /** @description Filter certificates by user ID */
+                    userId?: string;
+                    /** @description Search term */
+                    search?: components["parameters"]["search"];
+                    /** @description Page number */
+                    page?: components["parameters"]["page"];
+                    /** @description Items per page */
+                    limit?: components["parameters"]["limit"];
+                    /** @description Whether to include course data in the response (default true). Pass false to skip course lookup. */
+                    includeCourse?: boolean;
+                };
                 header?: never;
                 path?: never;
                 cookie?: never;
@@ -1314,6 +1387,16 @@ export interface paths {
                             /** @example success */
                             status?: string;
                             data?: components["schemas"]["Certificate"][];
+                            meta?: {
+                                /** @example 10 */
+                                total?: number;
+                                /** @example 1 */
+                                page?: number;
+                                /** @example 10 */
+                                limit?: number;
+                                /** @example 1 */
+                                totalPages?: number;
+                            };
                         };
                     };
                 };
@@ -1349,8 +1432,6 @@ export interface paths {
                             /** @example success */
                             status?: string;
                             data?: components["schemas"]["Certificate"];
-                            /** @example Certificate created successfully */
-                            message?: string;
                         };
                     };
                 };
@@ -1428,18 +1509,11 @@ export interface paths {
             requestBody?: never;
             responses: {
                 /** @description Certificate deleted successfully */
-                200: {
+                204: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content: {
-                        "application/json": {
-                            /** @example success */
-                            status?: string;
-                            /** @example Certificate deleted successfully */
-                            message?: string;
-                        };
-                    };
+                    content?: never;
                 };
                 400: components["responses"]["BadRequest"];
                 401: components["responses"]["Unauthorized"];
@@ -1479,8 +1553,6 @@ export interface paths {
                             /** @example success */
                             status?: string;
                             data?: components["schemas"]["Certificate"];
-                            /** @example Certificate updated successfully */
-                            message?: string;
                         };
                     };
                 };
@@ -1492,6 +1564,123 @@ export interface paths {
         };
         trace?: never;
     };
+    "/certificates/{id}/download": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Download certificate PDF
+         * @description Download the PDF of a specific certificate.
+         *     Acts as a proxy to download from S3, avoiding CORS issues.
+         *     Only the certificate owner can download their certificate.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Resource ID */
+                    id: components["parameters"]["id"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Certificate PDF file */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/pdf": string;
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                403: components["responses"]["Forbidden"];
+                404: components["responses"]["NotFound"];
+                500: components["responses"]["ServerError"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/certificates/generate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Generate a certificate PDF server-side
+         * @description Generates a certificate PDF on the server and creates the certificate record.
+         *     This eliminates CORS issues by downloading the template image on the server.
+         *
+         *     If the user is currently on a journey "course" step whose `courseModuleId`
+         *     matches the quiz's course module, that step is auto-completed as part of
+         *     this call (best-effort; failures here are silent and do not affect the cert).
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["GenerateCertificateDto"];
+                };
+            };
+            responses: {
+                /** @description Certificate generated and created successfully */
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: {
+                                certificate?: components["schemas"]["Certificate"];
+                                /** @example https://s3.amazonaws.com/bucket/certificate.pdf */
+                                pdfUrl?: string;
+                                /**
+                                 * @description True when this generation also concluded the user's current journey "course" step
+                                 * @example true
+                                 */
+                                stepCompleted?: boolean;
+                                /**
+                                 * Format: uuid
+                                 * @description ID of the challenge_step that was auto-completed, or null when no step was matched
+                                 */
+                                challengeStepId?: string | null;
+                            };
+                        };
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                401: components["responses"]["Unauthorized"];
+                500: components["responses"]["ServerError"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/challenge-groups": {
         parameters: {
             query?: never;
@@ -11357,7 +11546,7 @@ export interface paths {
         /**
          * Create new submission attempt
          * @description Creates a submission with status=submitted. Validations:
-         *     - Cannot submit to a global template (clone first)
+         *     - institutionId is sent by the client (user's institution_registration), not derived from the challenge
          *     - For group challenges: groupId is required and user must be a member
          *     - For individual challenges: groupId must be omitted
          *     - Cannot create when there is already an active submission (submitted/ai_evaluated)
@@ -11377,6 +11566,11 @@ export interface paths {
                     "application/json": {
                         /** Format: uuid */
                         challengeId: string;
+                        /**
+                         * Format: uuid
+                         * @description Institution the user is submitting under (from institution_registration)
+                         */
+                        institutionId: string;
                         /**
                          * Format: uuid
                          * @description Required when challenge.isGroup=true
@@ -12373,6 +12567,103 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/users-course-log/me/courses/{courseId}/progress": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get authenticated user's progress in a course
+         * @description Returns completed/total active lessons (across every active module of the course)
+         *     and a percentage based on `users_course_log` completion events.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    courseId: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Course progress snapshot */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: components["schemas"]["UsersCourseLogProgress"];
+                        };
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                404: components["responses"]["NotFound"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/users-course-log/me/courses/{courseId}/modules/{moduleId}/progress": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get authenticated user's progress in a module
+         * @description Returns completed/total active lessons of the module and a percentage based on
+         *     `users_course_log` completion events. Used by the Journey "curso" step.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    courseId: string;
+                    moduleId: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Module progress snapshot */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: components["schemas"]["UsersCourseLogProgress"];
+                        };
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                404: components["responses"]["NotFound"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/users/me": {
         parameters: {
             query?: never;
@@ -12846,7 +13137,19 @@ export interface paths {
         head?: never;
         /**
          * Update user
-         * @description Update user information
+         * @description Update user information.
+         *
+         *     **Profile and seat code behavior:**
+         *     - Send `groupId` to change the user's profile/group.
+         *     - When `groupId` changes, the system will:
+         *       1. Release the previous seat code used by the user (`isReserved = false`)
+         *       2. Allocate a seat code for the new group in the same institution registration
+         *       3. Create a new seat code automatically if none is available for that group
+         *
+         *     **Important:**
+         *     - The target group must exist.
+         *     - The institution must have a seat configured for the target group.
+         *     - If any institution registration cannot be migrated to the new group, the operation fails.
          */
         patch: {
             parameters: {
@@ -14664,6 +14967,29 @@ export interface components {
             /** Format: date-time */
             updatedAt?: string;
         };
+        /** @description Aggregated progress of a user on a course or module, derived from users_course_log completion events */
+        UsersCourseLogProgress: {
+            /**
+             * @description Number of active lessons completed by the user
+             * @example 3
+             */
+            completedLessons?: number;
+            /**
+             * @description Total number of active lessons in scope
+             * @example 5
+             */
+            totalLessons?: number;
+            /**
+             * @description Completion percentage rounded to nearest integer
+             * @example 60
+             */
+            percent?: number;
+            /**
+             * @description True when totalLessons > 0 and completedLessons >= totalLessons
+             * @example false
+             */
+            isCompleted?: boolean;
+        };
         Submission: {
             /** Format: uuid */
             id?: string;
@@ -15771,6 +16097,27 @@ export interface components {
             /** Format: uri */
             url?: string;
         };
+        GenerateCertificateDto: {
+            /** Format: uuid */
+            userId: string;
+            /** Format: uuid */
+            quizAttemptId?: string;
+            /** Format: uuid */
+            certificateTemplateId: string;
+            /** @example João Silva */
+            studentName: string;
+            /** @example Introdução ao JavaScript */
+            quizTitle: string;
+            /** @example 85 */
+            score?: number;
+            /** @example CERT-2024-000001 */
+            certificateNumber?: string;
+            /**
+             * Format: date-time
+             * @example 2024-01-01T00:00:00.000Z
+             */
+            issuedAt?: string;
+        };
         CreateGuardianDto: {
             /**
              * Format: email

package/package.json

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