academe-kit 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,45 @@
-# academe-kit
+# Academe Kit
 
-A React component library built with Tailwind CSS and Storybook.
+Official React SDK for the Academe ecosystem. Provides authentication, protected routes, API services, and UI components for building educational management applications.
+
+[![npm version](https://img.shields.io/npm/v/academe-kit.svg)](https://www.npmjs.com/package/academe-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+  - [AcademeAuthProvider](#academeauthprovider)
+  - [useAcademeAuth Hook](#useacademeauth-hook)
+- [Protected Components](#protected-components)
+  - [ProtectedApp](#protectedapp)
+  - [ProtectedComponent](#protectedcomponent)
+  - [ProtectedRouter](#protectedrouter)
+- [API Services](#api-services)
+  - [UserService](#userservice)
+  - [InstitutionService](#institutionservice)
+  - [ClassroomService](#classroomservice)
+  - [ShiftService](#shiftservice)
+  - [SerieService](#serieservice)
+  - [OrganizationService](#organizationservice)
+  - [ReportService](#reportservice)
+  - [GuardianService](#guardianservice)
+- [Roles](#roles)
+- [UI Components](#ui-components)
+- [Types](#types)
+- [Development](#development)
+- [License](#license)
+
+## Features
+
+- **Authentication**: Keycloak-based authentication with automatic token management
+- **Protected Routes**: Role-based access control for routes and components
+- **API Client**: Type-safe API client with OpenAPI-generated types
+- **Services**: Pre-built services for Users, Institutions, Classrooms, and more
+- **UI Components**: Reusable React components styled with Tailwind CSS
+- **TypeScript**: Full TypeScript support with comprehensive type definitions
 
 ## Installation
 
@@ -8,29 +47,458 @@ A React component library built with Tailwind CSS and Storybook.
 npm install academe-kit
 ```
 
-## Usage
+**Peer Dependencies:**
+
+```bash
+npm install react react-dom
+```
+
+## Quick Start
 
 ```tsx
-import { Button } from 'academe-kit';
+import { AcademeAuthProvider, ProtectedApp, useAcademeAuth } from 'academe-kit';
+import 'academe-kit/dist/index.css';
 
 function App() {
-  return <Button>Click me</Button>;
+  return (
+    <AcademeAuthProvider
+      realm="your-realm"
+      hubUrl="https://hub.academe.com.br"
+      clientId="your-client-id"
+      keycloakUrl="https://auth.academe.com.br"
+      apiBaseUrl="https://api.academe.com.br"
+    >
+      <ProtectedApp>
+        <MainApp />
+      </ProtectedApp>
+    </AcademeAuthProvider>
+  );
+}
+
+function MainApp() {
+  const { user, services } = useAcademeAuth();
+
+  return (
+    <div>
+      <h1>Welcome, {user?.name}</h1>
+    </div>
+  );
+}
+```
+
+## Authentication
+
+### AcademeAuthProvider
+
+The main provider that wraps your application and handles authentication with Keycloak.
+
+```tsx
+import { AcademeAuthProvider } from 'academe-kit';
+
+<AcademeAuthProvider
+  realm="your-realm"           // Keycloak realm name
+  hubUrl="https://hub.url"     // Academe Hub URL
+  clientId="your-client-id"    // Keycloak client ID
+  keycloakUrl="https://kc.url" // Keycloak server URL
+  apiBaseUrl="https://api.url" // Optional: API base URL (default: https://stg-api.academe.com.br)
+>
+  {children}
+</AcademeAuthProvider>
+```
+
+### useAcademeAuth Hook
+
+Access authentication state and methods from any component within the provider.
+
+```tsx
+import { useAcademeAuth } from 'academe-kit';
+
+function MyComponent() {
+  const {
+    // State
+    isInitialized,    // boolean - Provider initialization status
+    user,             // AcademeUser | null - Current user data
+    apiClient,        // AcademeApiClient | null - Type-safe API client
+    services,         // AcademeServices | null - All available services
+
+    // Methods
+    isAuthenticated,  // () => boolean - Check authentication status
+    signOut,          // () => void - Sign out and clear session
+    goToLogin,        // (options?) => void - Redirect to login
+    refreshUserData,  // () => Promise<void> - Refresh user data from API
+
+    // Role checks
+    hasRealmRole,     // (role: string) => boolean
+    hasClientRole,    // (role: string, resource?: string) => boolean
+    hasSchool,        // (schoolId: string) => boolean
+  } = useAcademeAuth();
+
+  return (
+    <div>
+      {isAuthenticated() ? (
+        <p>Logged in as {user?.name}</p>
+      ) : (
+        <button onClick={() => goToLogin()}>Login</button>
+      )}
+    </div>
+  );
 }
 ```
 
+#### User Object
+
+```typescript
+interface AcademeUser {
+  id: string;
+  name: string;
+  email: string;
+  document?: string;
+  institutionRegistrations?: InstitutionRegistration[];
+  keycloakUser?: {
+    name: string;
+    lastName: string;
+    email: string;
+  };
+  // ... other fields from API
+}
+```
+
+## Protected Components
+
+### ProtectedApp
+
+Wraps your entire application to ensure authentication before rendering. Shows a loading spinner during initialization and redirects unauthenticated users to login.
+
+```tsx
+import { ProtectedApp } from 'academe-kit';
+
+<ProtectedApp
+  requiredRealmRoles={['school_admin']}     // Optional: Required realm roles
+  requiredClientRoles={['manage-users']}    // Optional: Required client roles
+>
+  <YourApp />
+</ProtectedApp>
+```
+
+### ProtectedComponent
+
+Conditionally renders children based on user roles. Returns empty fragment if user lacks required permissions.
+
+```tsx
+import { ProtectedComponent } from 'academe-kit';
+
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      {/* Only visible to admins */}
+      <ProtectedComponent requiredRealmRoles={['admin_academe']}>
+        <AdminPanel />
+      </ProtectedComponent>
+
+      {/* Only visible to users with specific client role */}
+      <ProtectedComponent requiredClientRoles={['manage-reports']}>
+        <ReportsSection />
+      </ProtectedComponent>
+    </div>
+  );
+}
+```
+
+### ProtectedRouter
+
+Route-level protection that shows an unauthorized message instead of hiding content.
+
+```tsx
+import { ProtectedRouter } from 'academe-kit';
+
+function AdminPage() {
+  return (
+    <ProtectedRouter
+      requiredClientRoles={['admin-access']}
+      unauthorizedMessage="You don't have permission to access this page."
+    >
+      <AdminDashboard />
+    </ProtectedRouter>
+  );
+}
+```
+
+## API Services
+
+All services are available through the `useAcademeAuth` hook via `services` object.
+
+```tsx
+const { services } = useAcademeAuth();
+
+// Use any service
+const users = await services.user.getUsers();
+const institutions = await services.institution.getAll();
+```
+
+### UserService
+
+```typescript
+services.user.getMe()                          // Get current user
+services.user.getUsers(params?)                // List users with filters
+services.user.getUserById(id)                  // Get user by ID
+services.user.createUser(body)                 // Create new user
+services.user.updateUser(id, body)             // Update user
+services.user.deleteUser(id)                   // Delete user
+services.user.getUserGroups(id)                // Get user's groups
+services.user.getUserCertificates(id)          // Get user's certificates
+services.user.getUserInstitutions(id)          // Get user's institutions
+services.user.syncUser(id)                     // Sync with Keycloak
+```
+
+### InstitutionService
+
+```typescript
+services.institution.getAll()                                       // List all institutions
+services.institution.getById(id)                                    // Get institution by ID
+
+// Groups
+services.institution.getGroups(institutionId)
+services.institution.addGroup(institutionId, data)
+services.institution.updateGroup(institutionId, groupId, data)
+services.institution.removeGroup(institutionId, groupId)
+
+// Classrooms
+services.institution.getClassrooms(institutionId, options?)
+services.institution.getClassroomById(institutionId, classroomId)
+services.institution.addClassroom(institutionId, data)
+services.institution.updateClassroom(institutionId, classroomId, data)
+services.institution.removeClassroom(institutionId, classroomId)
+
+// Users & Registrations
+services.institution.getUsers(institutionId, options?)
+services.institution.getRegistrations(institutionId)
+services.institution.getRegistrationById(institutionId, registrationId)
+services.institution.getRegistrationByUserId(institutionId, userId)
+services.institution.registerUser(institutionId, data)
+services.institution.updateRegistration(institutionId, registrationId, data)
+services.institution.assignUserToClassroom(institutionId, registrationId, data)
+services.institution.removeRegistration(institutionId, registrationId)
+services.institution.getGroupUsers(institutionId)
+```
+
+### ClassroomService
+
+```typescript
+services.classroom.getAll()                           // List all classrooms
+services.classroom.getById(id)                        // Get classroom by ID
+services.classroom.getByInstitution(institutionId, params?)
+services.classroom.create(data)                       // Create classroom
+services.classroom.update(id, data)                   // Update classroom
+services.classroom.delete(id)                         // Delete classroom
+```
+
+### ShiftService
+
+```typescript
+services.shift.getAll()            // List all shifts
+services.shift.getById(id)         // Get shift by ID
+services.shift.create(data)        // Create shift
+services.shift.update(id, data)    // Update shift
+services.shift.delete(id)          // Delete shift
+```
+
+### SerieService
+
+```typescript
+services.serie.getAll()            // List all series
+services.serie.getById(id)         // Get serie by ID
+services.serie.create(data)        // Create serie
+services.serie.update(id, data)    // Update serie
+services.serie.delete(id)          // Delete serie
+```
+
+### OrganizationService
+
+```typescript
+services.organization.getAll(params?)     // List with filters (name, type, isActive, etc.)
+services.organization.getById(id)         // Get organization by ID
+services.organization.create(body)        // Create organization
+services.organization.update(id, body)    // Update organization
+services.organization.delete(id)          // Delete organization
+```
+
+### ReportService
+
+```typescript
+// Dashboard
+services.report.getDashboard(params?)
+services.report.getDashboardByInstitution(id)
+
+// Courses by Area
+services.report.getCoursesByArea()
+services.report.getCoursesByAreaByInstitution(id)
+
+// Adhesion Rate
+services.report.getAdhesionRate()
+services.report.getAdhesionRateByInstitution(id)
+
+// Recent Activities
+services.report.getRecentActivities(params?)              // period: '7days' | '30days' | 'all'
+services.report.getRecentActivitiesByInstitution(id, params?)
+
+// Top Students
+services.report.getTopStudents(params)                    // filterType: 'nota' | 'engajamento' | 'conclusao'
+services.report.getTopStudentsByInstitution(id, params)
+```
+
+### GuardianService
+
+```typescript
+services.guardian.getAll()                      // List all guardians
+services.guardian.getById(id)                   // Get guardian by ID
+services.guardian.create(data)                  // Create guardian
+services.guardian.update(id, data)              // Update guardian
+services.guardian.delete(id)                    // Delete guardian
+services.guardian.getUsers(id)                  // Get guardian's students
+services.guardian.assignToUser(data)            // Assign guardian to user
+services.guardian.removeFromUser(guardianId, userId)
+```
+
+## Roles
+
+Pre-defined role constants for consistent role checking.
+
+```typescript
+import { GLOBAL_ROLES, DASHBOARD_ROLES, BACKOFFICE_ROLES } from 'academe-kit';
+
+// Available global roles
+GLOBAL_ROLES.ADMIN_ACADEME  // 'admin_academe'
+GLOBAL_ROLES.SCHOOL_ADMIN   // 'school_admin'
+GLOBAL_ROLES.TEACHER        // 'teacher'
+GLOBAL_ROLES.STUDENT        // 'student'
+GLOBAL_ROLES.GUARDIAN       // 'guardian'
+```
+
+Usage with protected components:
+
+```tsx
+import { ProtectedComponent, GLOBAL_ROLES } from 'academe-kit';
+
+<ProtectedComponent requiredRealmRoles={[GLOBAL_ROLES.ADMIN_ACADEME]}>
+  <AdminContent />
+</ProtectedComponent>
+```
+
+## UI Components
+
+### Button
+
+```tsx
+import { Button } from 'academe-kit';
+
+<Button variant="primary" size="md" onClick={handleClick}>
+  Click me
+</Button>
+
+// Variants: 'primary' | 'secondary' | 'outline'
+// Sizes: 'sm' | 'md' | 'lg'
+```
+
+### Spinner
+
+```tsx
+import { Spinner } from 'academe-kit';
+
+<Spinner />
+```
+
+### Utility: cn
+
+Class name utility combining `clsx` and `tailwind-merge`:
+
+```tsx
+import { cn } from 'academe-kit';
+
+<div className={cn('base-class', isActive && 'active-class', className)} />
+```
+
+## Types
+
+All types are exported for TypeScript support:
+
+```typescript
+import type {
+  // Auth types
+  AcademeUser,
+  SecurityContextType,
+  KeycloakUser,
+  SecurityProviderProps,
+  AcademeKeycloakContextProps,
+
+  // Component props
+  ButtonProps,
+
+  // API types
+  types,     // Entity types (User, Institution, Classroom, etc.)
+  apiTypes,  // Full OpenAPI-generated types
+} from 'academe-kit';
+```
+
+### Entity Types
+
+```typescript
+import { types } from 'academe-kit';
+
+type User = types.User;
+type Institution = types.Institution;
+type Classroom = types.Classroom;
+type Organization = types.Organization;
+type Serie = types.Serie;
+type Shift = types.Shift;
+```
+
 ## Development
 
 ```bash
 # Install dependencies
 npm install
 
-# Run Storybook
+# Run Storybook for component development
 npm run dev
 
 # Build the library
 npm run build
+
+# Build with watch mode
+npm run build:watch
+
+# Build Storybook static site
+npm run build-storybook
+
+# Generate API types from OpenAPI spec (requires API running locally)
+npm run generate:api-types
+```
+
+### Project Structure
+
+```
+src/
+├── components/          # UI components
+│   ├── Button/
+│   ├── ProtectedApp/
+│   ├── ProtectedComponent/
+│   ├── ProtectedRouter/
+│   └── ui/
+├── context/             # React context providers
+│   └── SecurityProvider/
+├── services/            # API services
+├── roles/               # Role definitions
+├── types/               # TypeScript types
+├── lib/                 # Utilities
+└── index.ts             # Main entry point
 ```
 
 ## License
 
 MIT
+
+---
+
+Made with care by [Academe](https://academe.com.br)

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import React$1 from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { KeycloakLoginOptions } from 'keycloak-js';
+import { KeycloakInitOptions, KeycloakLoginOptions } from 'keycloak-js';
 import * as openapi_fetch from 'openapi-fetch';
 import openapi_fetch__default from 'openapi-fetch';
 import { ClassValue } from 'clsx';
@@ -10185,15 +10185,18 @@ interface AcademeServices {
 
 type AcademeKeycloakContextProps = {
     realm: string;
-    hubUrl: string;
+    hubUrl?: string;
     clientId: string;
     keycloakUrl: string;
     apiBaseUrl?: string;
+    initOptions?: KeycloakInitOptions;
+    skipApiUserFetch?: boolean;
     children: React.ReactElement;
 };
 type SecurityProviderProps = {
-    hubUrl: string;
+    hubUrl?: string;
     apiBaseUrl?: string;
+    skipApiUserFetch?: boolean;
     children: React.ReactElement;
 };
 type KeycloakUser = {
@@ -10216,6 +10219,7 @@ type SecurityContextType = {
     hasClientRole: (role: string, resource?: string) => boolean;
     apiClient: AcademeApiClient | null;
     services: AcademeServices | null;
+    accessToken: string | undefined;
 };
 
 declare const AcademeAuthProvider: React.FC<AcademeKeycloakContextProps>;
@@ -10242,5 +10246,11 @@ declare enum BACKOFFICE_ROLES {
 declare enum DASHBOARD_ROLES {
 }
 
-export { AcademeAuthProvider, BACKOFFICE_ROLES, Button, DASHBOARD_ROLES, GLOBAL_ROLES, ProtectedApp, ProtectedComponent, ProtectedRouter, Spinner, academeApi_d as apiTypes, cn, createAcademeApiClient, index_d as types, useAcademeAuth };
+declare enum APPLICATIONS_ROLES {
+    ACCESS_NINA = "Acesso nina",
+    ACCESS_MIKE = "Acesso mike",
+    VIEW_WIDGET = "Visualizar Widget"
+}
+
+export { APPLICATIONS_ROLES, AcademeAuthProvider, BACKOFFICE_ROLES, Button, DASHBOARD_ROLES, GLOBAL_ROLES, ProtectedApp, ProtectedComponent, ProtectedRouter, Spinner, academeApi_d as apiTypes, cn, createAcademeApiClient, index_d as types, useAcademeAuth };
 export type { AcademeApiClient, AcademeKeycloakContextProps, AcademeUser, ButtonProps, KeycloakUser, SecurityContextType, SecurityProviderProps };

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import * as React from 'react';
-import React__default, { createContext, useContext, useState, useMemo, useEffect, useCallback, forwardRef, createElement } from 'react';
+import React__default, { createContext, useContext, useMemo, useState, useEffect, useCallback, forwardRef, createElement } from 'react';
 
 function r(e){var t,f,n="";if("string"==typeof e||"number"==typeof e)n+=e;else if("object"==typeof e)if(Array.isArray(e)){var o=e.length;for(t=0;t<o;t++)e[t]&&(f=r(e[t]))&&(n&&(n+=" "),n+=f);}else for(f in e)e[f]&&(n&&(n+=" "),n+=f);return n}function clsx(){for(var e,t,f=0,n="",o=arguments.length;f<o;f++)(e=arguments[f])&&(t=r(e))&&(n&&(n+=" "),n+=t);return n}
 
@@ -3259,8 +3259,10 @@ var GLOBAL_ROLES;
     GLOBAL_ROLES["GUARDIAN"] = "guardian";
 })(GLOBAL_ROLES || (GLOBAL_ROLES = {}));
 
-const AcademeAuthProvider = ({ realm, hubUrl, children, clientId, keycloakUrl, apiBaseUrl, }) => {
-    return (jsx(ReactKeycloakProvider, { authClient: new Keycloak({ clientId, realm, url: keycloakUrl }), children: jsx(SecurityProvider, { hubUrl: hubUrl, apiBaseUrl: apiBaseUrl, children: children }) }));
+const AcademeAuthProvider = ({ realm, hubUrl, children, clientId, keycloakUrl, apiBaseUrl, initOptions, skipApiUserFetch, }) => {
+    const keycloakInstance = useMemo(() => new Keycloak({ clientId, realm, url: keycloakUrl }), [clientId, realm, keycloakUrl]);
+    const keycloakInitOptions = useMemo(() => initOptions, [initOptions]);
+    return (jsx(ReactKeycloakProvider, { authClient: keycloakInstance, initOptions: keycloakInitOptions, children: jsx(SecurityProvider, { hubUrl: hubUrl, apiBaseUrl: apiBaseUrl, skipApiUserFetch: skipApiUserFetch, children: children }) }));
 };
 const SecurityContext = createContext({
     isInitialized: false,
@@ -3274,12 +3276,12 @@ const SecurityContext = createContext({
     isAuthenticated: () => false,
     apiClient: null,
     services: null,
+    accessToken: undefined,
 });
-const SecurityProvider = ({ apiBaseUrl = "https://stg-api.academe.com.br", children, }) => {
+const SecurityProvider = ({ apiBaseUrl = "https://stg-api.academe.com.br", skipApiUserFetch = false, children, }) => {
     const [isInitialized, setIsInitialized] = useState(false);
     const [currentUser, setCurrentUser] = useState(null);
     const { initialized, keycloak } = useKeycloak();
-    // Create API client with the provided baseUrl
     const apiClient = useMemo(() => {
         return createAcademeApiClient(apiBaseUrl);
     }, [apiBaseUrl]);
@@ -3310,10 +3312,16 @@ const SecurityProvider = ({ apiBaseUrl = "https://stg-api.academe.com.br", child
             lastName: idTokenParsed?.family_name || "",
         };
     }, [keycloak?.idTokenParsed]);
-    // Fetch user data from API when authenticated
     useEffect(() => {
         const fetchUserData = async () => {
             if (initialized && keycloak?.authenticated && keycloak?.token) {
+                if (skipApiUserFetch) {
+                    const academeUser = {
+                        keycloakUser: getKeycloakUser(),
+                    };
+                    setCurrentUser({ ...academeUser, id: keycloak?.idTokenParsed?.sub });
+                    return;
+                }
                 try {
                     const response = await services.user.getMe();
                     if (response?.data?.data) {
@@ -3339,9 +3347,17 @@ const SecurityProvider = ({ apiBaseUrl = "https://stg-api.academe.com.br", child
         keycloak?.token,
         getKeycloakUser,
         services,
+        skipApiUserFetch,
     ]);
     const refreshUserData = useCallback(async () => {
         if (keycloak?.authenticated) {
+            if (skipApiUserFetch) {
+                const academeUser = {
+                    keycloakUser: getKeycloakUser(),
+                };
+                setCurrentUser(academeUser);
+                return;
+            }
             try {
                 const response = await services.user.getMe();
                 if (response?.data?.data) {
@@ -3356,7 +3372,7 @@ const SecurityProvider = ({ apiBaseUrl = "https://stg-api.academe.com.br", child
                 console.error("Error refreshing user data:", error);
             }
         }
-    }, [keycloak?.authenticated, getKeycloakUser, services]);
+    }, [keycloak?.authenticated, getKeycloakUser, services, skipApiUserFetch]);
     const signOut = () => {
         setCurrentUser(null);
         keycloak?.logout();
@@ -3383,6 +3399,7 @@ const SecurityProvider = ({ apiBaseUrl = "https://stg-api.academe.com.br", child
             goToLogin: keycloak.login,
             hasRealmRole: keycloak?.hasRealmRole,
             hasClientRole: keycloak.hasResourceRole,
+            accessToken: keycloak?.token,
             apiClient,
             services,
         }, children: children }));
@@ -6555,6 +6572,13 @@ var DASHBOARD_ROLES;
 (function (DASHBOARD_ROLES) {
 })(DASHBOARD_ROLES || (DASHBOARD_ROLES = {}));
 
+var APPLICATIONS_ROLES;
+(function (APPLICATIONS_ROLES) {
+    APPLICATIONS_ROLES["ACCESS_NINA"] = "Acesso nina";
+    APPLICATIONS_ROLES["ACCESS_MIKE"] = "Acesso mike";
+    APPLICATIONS_ROLES["VIEW_WIDGET"] = "Visualizar Widget";
+})(APPLICATIONS_ROLES || (APPLICATIONS_ROLES = {}));
+
 var index = /*#__PURE__*/Object.freeze({
     __proto__: null
 });
@@ -6568,5 +6592,5 @@ var academeApi = /*#__PURE__*/Object.freeze({
     __proto__: null
 });
 
-export { AcademeAuthProvider, BACKOFFICE_ROLES, Button, DASHBOARD_ROLES, GLOBAL_ROLES, ProtectedApp, ProtectedComponent, ProtectedRouter, Spinner, academeApi as apiTypes, cn, createAcademeApiClient, index as types, useAcademeAuth };
+export { APPLICATIONS_ROLES, AcademeAuthProvider, BACKOFFICE_ROLES, Button, DASHBOARD_ROLES, GLOBAL_ROLES, ProtectedApp, ProtectedComponent, ProtectedRouter, Spinner, academeApi as apiTypes, cn, createAcademeApiClient, index as types, useAcademeAuth };
 //# sourceMappingURL=index.esm.js.map