academe-kit 0.2.9 → 0.3.1

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/package.json

@@ -1,8 +1,8 @@
 {
   "name": "academe-kit",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "type": "module",
-  "description": "A React component library with Tailwind CSS and Storybook",
+  "description": "Official React SDK for Academe ecosystem - Authentication, protected routes, API services, and UI components for educational management applications",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
@@ -28,10 +28,18 @@
   },
   "keywords": [
     "react",
-    "components",
+    "academe",
+    "authentication",
+    "keycloak",
+    "education",
+    "sdk",
+    "protected-routes",
+    "rbac",
+    "role-based-access-control",
     "tailwind",
-    "ui",
-    "academe"
+    "components",
+    "api-client",
+    "typescript"
   ],
   "author": "tecnologia@academe.com.br",
   "license": "MIT",