academe-kit 0.10.1 → 0.10.3

package/dist/types/components/JourneyStep/frames/types.d.ts

@@ -26,9 +26,19 @@ export interface FrameRenderArgs {
     scale: number;
     layout: FrameLayout;
     progress?: number;
+    /** Frames que renderizam o próprio ícone (3D) recebem-no aqui. */
+    icon?: ReactNode;
+    /** Permite ao frame estilizar o ícone no estado bloqueado. */
+    isLocked?: boolean;
 }
 export interface FrameRenderer {
     kind: FrameKind;
+    /**
+     * Frames 3D (ex.: sphere) desenham profundidade (base/skirt + lift + squash)
+     * e renderizam o próprio ícone. Quando true, o JourneyStep adiciona a classe
+     * `is-3d`, repassa o ícone ao frame e não desenha o ícone padrão.
+     */
+    is3d?: boolean;
     layout: (scale: number) => FrameLayout;
     render: (args: FrameRenderArgs) => ReactNode;
 }

package/dist/types/index.d.ts

@@ -17,6 +17,7 @@ export type { AcademeKeycloakContextProps, SecurityProviderProps, KeycloakUser,
 export { createAcademeApiClient } from "./services";
 export type { AcademeApiClient, AcademeServices } from "./services";
 export type { ChallengeUserQuizAttempt, ChallengeUserQuizAttemptsResponse, } from "./services/ChallengeService";
+export type { JourneyStepView, JourneyChallengeView, JourneyView, } from "./services/UserProgressService";
 export { cn } from "./lib/utils";
 import "./index.css";
 import "./styles/globals.css";

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

@@ -645,6 +645,73 @@ export declare function createReportService(apiClient: AcademeApiClient): {
             } | undefined;
         };
     }, `${string}/${string}`>>;
+    /**
+     * Status de jornada dos alunos para os summary cards da rota /students.
+     *
+     * @param id                  UUID da instituição.
+     * @param params.periodId     UUID do bimestre, ou `"all"` para todos os bimestres
+     *                            do ano letivo. Omitido = bimestre corrente.
+     * @param params.challengeId  UUID de UM challenge específico para restringir o
+     *                            cálculo dentro do recorte temporal.
+     */
+    getStudentsJourneyStatusByInstitution(id: string, params?: {
+        periodId?: string;
+        challengeId?: string;
+    }): Promise<import("openapi-fetch").FetchResponse<{
+        parameters: {
+            query?: {
+                periodId?: string;
+                challengeId?: string;
+            };
+            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"]["StudentsJourneyStatusResponse"];
+                    };
+                };
+            };
+            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;
+                challengeId?: string;
+            } | undefined;
+        };
+    }, `${string}/${string}`>>;
 };
 export type ReportService = ReturnType<typeof createReportService>;
 export {};

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

@@ -19,7 +19,10 @@ export declare function createSubmissionService(apiClient: AcademeApiClient): {
                 userId?: string;
                 groupId?: string;
                 institutionId?: string;
+                institutionClassroomId?: string;
+                serieId?: string;
                 status?: "submitted" | "ai_evaluated" | "approved" | "rejected";
+                search?: string;
                 page?: import("../types/academe-api").components["parameters"]["page"];
                 limit?: import("../types/academe-api").components["parameters"]["limit"];
             };
@@ -57,7 +60,10 @@ export declare function createSubmissionService(apiClient: AcademeApiClient): {
                 userId?: string;
                 groupId?: string;
                 institutionId?: string;
+                institutionClassroomId?: string;
+                serieId?: string;
                 status?: "submitted" | "ai_evaluated" | "approved" | "rejected";
+                search?: string;
                 page?: import("../types/academe-api").components["parameters"]["page"];
                 limit?: import("../types/academe-api").components["parameters"]["limit"];
             } | undefined;

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

@@ -0,0 +1,304 @@
+import type { AcademeApiClient } from "./index";
+import type { components } from "../types/academe-api";
+export type JourneyStepView = components["schemas"]["JourneyStepView"];
+export type JourneyChallengeView = components["schemas"]["JourneyChallengeView"];
+export type JourneyView = components["schemas"]["JourneyView"];
+/**
+ * Service do agregado `user-challenge-progress` — o caminho oficial para os
+ * clientes (web/mobile) montarem a jornada e o progresso do usuário. Espelha
+ * app-academe-v2/src/services/academe/user-progress.service.ts.
+ */
+export declare function createUserProgressService(apiClient: AcademeApiClient): {
+    /**
+     * Jornada pré-computada do usuário (status, progress, color, icon,
+     * isUpcoming, série) — base de renderização direta da tela de jornada.
+     *
+     * `userId` é [Admin]: quando informado, retorna a jornada do usuário-alvo
+     * (ex.: backoffice visualizando a jornada de um aluno); omitido = jornada
+     * do próprio usuário autenticado.
+     */
+    getJourney(serieId?: string, userId?: string): Promise<JourneyView>;
+    /**
+     * Visão step-by-step do progresso do usuário em um desafio. Cada step traz
+     * `myStartedAt`, `myCompletedAt` e (em desafios em grupo) os agregados do
+     * grupo.
+     */
+    getChallengeProgress(challengeId: string): Promise<import("openapi-fetch").FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: components["parameters"]["id"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: {
+                            challengeStepId?: string;
+                            stepName?: string;
+                            index?: number;
+                            totalMembers?: number;
+                            completedMembers?: number;
+                            groupCompleted?: boolean;
+                            myStartedAt?: string | null;
+                            myCompletedAt?: string | null;
+                        }[];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                id: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * Avança um tick na jornada do usuário no desafio, agnóstico do tipo da
+     * etapa. Cada chamada executa UMA ação:
+     *   - Sem progresso na etapa atual → action='started'
+     *   - Etapa iniciada (sem completedAt) → action='completed'
+     *   - Todas as etapas concluídas → action='finished' (no-op)
+     *
+     * Caminho oficial para clientes (web/mobile). Não usar os endpoints
+     * internos `/steps/{stepId}/start` ou `/steps/{stepId}/complete`.
+     */
+    advance(challengeId: string): Promise<import("openapi-fetch").FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: components["parameters"]["id"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: {
+                            action?: "started" | "completed" | "finished";
+                            challengeId?: string;
+                            currentStep?: {
+                                id?: string;
+                                index?: number;
+                                name?: string;
+                                startedAt?: string | null;
+                                completedAt?: string | null;
+                            } | null;
+                            nextStep?: {
+                                id?: string;
+                                index?: number;
+                                name?: string;
+                                startedAt?: string | null;
+                            } | null;
+                        };
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                id: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * Status de conclusão do grupo numa etapa. Em desafios em grupo: retorna a
+     * agregação (`canAdvance=true` quando todos concluíram). Em desafios
+     * individuais: retorna o status do próprio usuário.
+     */
+    getStepGroupStatus(stepId: string): Promise<import("openapi-fetch").FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                stepId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: {
+                            isGroupChallenge?: boolean;
+                            totalMembers?: number;
+                            completedMembers?: number;
+                            canAdvance?: boolean;
+                        };
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                stepId: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * Progresso agregado do usuário em um módulo (ou no curso inteiro quando
+     * `moduleId` é omitido). Usado pelos steps do tipo `course` da jornada.
+     */
+    getCourseProgress(courseId: string, moduleId?: string | null): Promise<import("openapi-fetch").FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                courseId: string;
+                moduleId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: components["schemas"]["UsersCourseLogProgress"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                courseId: string;
+                moduleId: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * [Interno] Força o início de uma etapa específica (idempotente). Clientes
+     * devem preferir `advance`; mantido para casos pontuais (ex.: iniciar a
+     * próxima etapa após concluir um curso aberto a partir da jornada).
+     */
+    start(stepId: string): Promise<import("openapi-fetch").FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                stepId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: components["schemas"]["UserChallengeProgress"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                stepId: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * [Admin] Conclui de uma vez TODAS as etapas ativas de um desafio para um
+     * usuário-alvo, criando a linha de progresso quando não existir. Idempotente
+     * — etapas já concluídas não são alteradas.
+     *
+     * Diferente de `advance` (que avança um tick por vez para o usuário
+     * autenticado), aqui o desafio inteiro é concluído de uma vez para o usuário
+     * identificado no path. Em desafios em grupo, apenas o progresso do
+     * usuário-alvo é concluído; os demais membros não são afetados.
+     */
+    completeAllForUser(challengeId: string, userId: string): Promise<import("openapi-fetch").FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                userId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: {
+                            challengeId?: string;
+                            userId?: string;
+                            total?: number;
+                            completedSteps?: {
+                                id?: string;
+                                index?: number;
+                                name?: string;
+                                completedAt?: string | null;
+                            }[];
+                        };
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    }, {
+        params: {
+            path: {
+                id: string;
+                userId: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+};
+export type UserProgressService = ReturnType<typeof createUserProgressService>;

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

@@ -21,6 +21,7 @@ import { type StorageFileService } from './StorageFileService';
 import { type ChallengeService } from './ChallengeService';
 import { type StepService } from './StepService';
 import { type SubmissionService } from './SubmissionService';
+import { type UserProgressService } from './UserProgressService';
 export type AcademeApiClient = ReturnType<typeof createClient<paths>>;
 export declare function createAcademeApiClient(baseUrl: string): AcademeApiClient;
 export interface AcademeServices {
@@ -45,6 +46,7 @@ export interface AcademeServices {
     challenge: ChallengeService;
     step: StepService;
     submission: SubmissionService;
+    userProgress: UserProgressService;
 }
 export declare function createAcademeServices(apiClient: AcademeApiClient): AcademeServices;
 export { createUserService, type UserService } from "./userService";
@@ -67,3 +69,4 @@ export { createStorageFileService, type StorageFileService } from './StorageFile
 export { createChallengeService, type ChallengeService } from './ChallengeService';
 export { createStepService, type StepService } from './StepService';
 export { createSubmissionService, type SubmissionService } from './SubmissionService';
+export { createUserProgressService, type UserProgressService } from './UserProgressService';