@lime1/esprit-ts 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# @lime1/esprit-ts
+
+A TypeScript client library for the ESPRIT student portal. Scrape grades, absences, credits, schedules, and student information with full type safety.
+
+## Installation
+
+```bash
+npm install @lime1/esprit-ts
+# or
+pnpm add @lime1/esprit-ts
+# or
+yarn add @lime1/esprit-ts
+```
+
+## Usage
+
+```typescript
+import { EspritClient } from '@lime1/esprit-ts';
+
+
+async function main() {
+  // Create client (optionally enable debug mode)
+  const client = new EspritClient({ debug: false });
+
+  // Login with your ESPRIT credentials
+  const result = await client.login('your-student-id', 'your-password');
+
+  if (!result.success) {
+    console.error('Login failed:', result.message);
+    return;
+  }
+
+  console.log('Login successful!');
+
+  // Get student info
+  const info = await client.getStudentInfo();
+  console.log(`Name: ${info.name}`);
+  console.log(`Class: ${info.className}`);
+
+  // Get grades
+  const grades = await client.getGrades();
+  console.log('Grades:', grades);
+
+  // Get grades with calculated averages
+  const summary = await client.getGradesWithAverage();
+  if (summary) {
+    console.log(`Total Average: ${summary.totalAverage?.toFixed(2)}`);
+  }
+
+  // Get absences
+  const absences = await client.getAbsences();
+  console.log('Absences:', absences);
+
+  // Get credit history
+  const credits = await client.getCredits();
+  console.log('Credits:', credits);
+
+  // Get schedules
+  const schedules = await client.getSchedules();
+  console.log('Schedules:', schedules);
+
+  // Logout when done
+  await client.logout();
+}
+
+main().catch(console.error);
+```
+
+## API Reference
+
+### `EspritClient`
+
+#### Constructor
+
+```typescript
+new EspritClient(config?: EspritClientConfig)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `userAgent` | `string` | Chrome UA | Custom user agent string |
+| `timeout` | `number` | `30000` | Request timeout in ms |
+
+#### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `login(id, password)` | `Promise<LoginResult>` | Login to the portal |
+| `logout()` | `Promise<boolean>` | Logout from the portal |
+| `getGrades()` | `Promise<Grade[] \| null>` | Get student grades |
+| `getGradesWithAverage()` | `Promise<GradeSummary \| null>` | Get grades with calculated averages |
+| `getAbsences()` | `Promise<Absence[] \| null>` | Get student absences |
+| `getCredits()` | `Promise<Credit[] \| null>` | Get credit history |
+| `getSchedules()` | `Promise<Schedule[] \| null>` | Get available schedules |
+| `getStudentName()` | `Promise<string \| null>` | Get student name |
+| `getStudentClass()` | `Promise<string \| null>` | Get student class |
+| `getStudentInfo()` | `Promise<StudentInfo>` | Get name and class |
+| `getCookies()` | `Promise<Cookie[]>` | Get session cookies |
+
+### Types
+
+```typescript
+interface Grade {
+  designation: string;
+  coefficient: number | null;
+  noteCC: number | null;
+  noteTP: number | null;
+  noteExam: number | null;
+}
+
+interface GradeSummary {
+  grades: GradeWithAverage[];
+  totalAverage: number | null;
+  totalCoefficient: number;
+}
+
+interface LoginResult {
+  success: boolean;
+  cookies: Cookie[];
+  message?: string;
+}
+
+interface StudentInfo {
+  name: string | null;
+  className: string | null;
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Type check
+npm run typecheck
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+MIT