Academe Kit

Official React SDK for the Academe ecosystem. Provides authentication, protected routes, API services, and UI components for building educational management applications.


Table of Contents

- Features
- Installation
- Quick Start
- Authentication
- AcademeAuthProvider
- useAcademeAuth Hook
- Protected Components
- ProtectedApp
- ProtectedComponent
- ProtectedRouter
- API Services
- UserService
- InstitutionService
- ClassroomService
- ShiftService
- SerieService
- OrganizationService
- ReportService
- GuardianService
- Roles
- UI Components
- Types
- Development
- 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

``bash
npm install academe-kit
`

Peer Dependencies:

`bash
npm install react react-dom
`

Quick Start

`tsx
import { AcademeAuthProvider, ProtectedApp, useAcademeAuth } from 'academe-kit';
import 'academe-kit/dist/index.css';

function App() {
return (
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"
>




);
}

function MainApp() {
const { user, services } = useAcademeAuth();

return (



);
}
`

Authentication

$3

The main provider that wraps your application and handles authentication with Keycloak.

`tsx
import { AcademeAuthProvider } from 'academe-kit';

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}

`

$3

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 - Refresh user data from API

// Role checks
hasRealmRole, // (role: string) => boolean
hasClientRole, // (role: string, resource?: string) => boolean
hasSchool, // (schoolId: string) => boolean
} = useAcademeAuth();

return (



);
}
`

#### 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

$3

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';

requiredRealmRoles={['school_admin']} // Optional: Required realm roles
requiredClientRoles={['manage-users']} // Optional: Required client roles
>


`

$3

Conditionally renders children based on user roles. Returns empty fragment if user lacks required permissions.

`tsx
import { ProtectedComponent } from 'academe-kit';

function Dashboard() {
return (



);
}
`

$3

Route-level protection that shows an unauthorized message instead of hiding content.

`tsx
import { ProtectedRouter } from 'academe-kit';

function AdminPage() {
return (
requiredClientRoles={['admin-access']}
unauthorizedMessage="You don't have permission to access this page."
>


);
}
`

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();
`

$3

`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
`

$3

`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)
`

$3

`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
`

$3

`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
`

$3

`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
`

$3

`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
`

$3

`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)
`

$3

`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';




`

UI Components

$3

`tsx
import { Button } from 'academe-kit';


Click me


// Variants: 'primary' | 'secondary' | 'outline'
// Sizes: 'sm' | 'md' | 'lg'
`

$3

`tsx
import { Spinner } from 'academe-kit';


`

$3

Class name utility combining clsx and tailwind-merge:

`tsx
import { cn } from 'academe-kit';