@schoolio/player 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# @schoolio/player
+
+A React component for loading and playing quizzes from Quiz Engine.
+
+## Installation
+
+```bash
+npm install @schoolio/player
+```
+
+## Usage
+
+```tsx
+import { QuizPlayer } from '@schoolio/player';
+
+function MyQuizPage() {
+  return (
+    <QuizPlayer
+      quizId="QZ123"
+      lessonId="L12"
+      assignLessonId="assignLesson123"
+      courseId="course456"
+      childId="child789"
+      parentId="parent012"
+      apiBaseUrl="https://your-quiz-engine-url.com"
+      onComplete={(result) => {
+        console.log('Quiz completed!', result);
+        // result contains: attemptId, score, correctAnswers, totalQuestions, answers, timeSpentSeconds
+      }}
+      onError={(error) => {
+        console.error('Quiz error:', error);
+      }}
+      onProgress={(progress) => {
+        console.log(`Question ${progress.currentQuestion} of ${progress.totalQuestions}`);
+      }}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `quizId` | string | Yes | The ID of the quiz to load |
+| `lessonId` | string | Yes | Lesson ID from your app |
+| `assignLessonId` | string | Yes | Assigned lesson ID for tracking |
+| `courseId` | string | Yes | Course ID for tracking |
+| `childId` | string | Yes | Student/child ID |
+| `parentId` | string | Yes | Parent ID |
+| `apiBaseUrl` | string | Yes | Base URL of your Quiz Engine API |
+| `authToken` | string | No | Optional auth token for API requests |
+| `onComplete` | function | No | Callback when quiz is completed |
+| `onError` | function | No | Callback when an error occurs |
+| `onProgress` | function | No | Callback on question navigation |
+| `className` | string | No | CSS class for the container |
+
+## Quiz Result
+
+When the quiz is completed, the `onComplete` callback receives:
+
+```typescript
+interface QuizResult {
+  attemptId: string;          // Unique attempt ID
+  score: number;              // Percentage score (0-100)
+  correctAnswers: number;     // Number of correct answers
+  totalQuestions: number;     // Total questions in quiz
+  answers: QuizAnswerDetail[]; // Detailed answer data
+  timeSpentSeconds: number;   // Time taken to complete
+}
+```
+
+## Attempt Tracking
+
+The component automatically:
+- Creates a new attempt when started
+- Saves progress as the student answers questions
+- Resumes from where the student left off if they return
+- Tracks attempt number (1st, 2nd, 3rd attempt, etc.)
+- Records time spent on the quiz
+
+## API Endpoints
+
+The component expects these endpoints on your Quiz Engine:
+
+- `GET /api/external/quizzes/:id` - Get quiz by ID
+- `POST /api/external/quiz-attempts` - Create new attempt
+- `PATCH /api/external/quiz-attempts/:id` - Update attempt
+- `GET /api/external/quiz-attempts/:id` - Get attempt by ID
+- `GET /api/external/quiz-attempts?assignLessonId=X&childId=Y` - Get attempts
+
+## Customization
+
+You can provide custom styling via the `className` prop and CSS:
+
+```css
+.my-quiz-player {
+  /* Custom container styles */
+}
+
+.my-quiz-player .quiz-question {
+  /* Custom question styles */
+}
+```
+
+## Using the API Client Directly
+
+For more control, you can use the API client directly:
+
+```typescript
+import { QuizApiClient } from '@schoolio/player';
+
+const client = new QuizApiClient({
+  baseUrl: 'https://your-quiz-engine-url.com',
+  authToken: 'optional-auth-token',
+});
+
+// Fetch a quiz
+const quiz = await client.getQuiz('quiz-id');
+
+// Create an attempt
+const attempt = await client.createAttempt({
+  quizId: 'quiz-id',
+  lessonId: 'lesson-id',
+  assignLessonId: 'assign-lesson-id',
+  courseId: 'course-id',
+  childId: 'child-id',
+  parentId: 'parent-id',
+});
+
+// Update attempt with answers
+await client.updateAttempt(attempt.id, {
+  answers: [...],
+  status: 'completed',
+  score: 80,
+  correctAnswers: 8,
+  timeSpentSeconds: 300,
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,146 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type QuestionType = "single" | "multiple" | "true-false" | "free" | "essay" | "fill" | "sorting" | "matrix" | "assessment";
+interface QuizQuestion {
+    id: string;
+    question: string;
+    type: QuestionType;
+    points: number;
+    explanation?: string;
+    hint?: string;
+    imageUrl?: string;
+    options?: string[];
+    correctAnswer?: string | string[] | Record<string, string>;
+    blanks?: string[];
+    items?: string[];
+    correctOrder?: number[];
+    leftItems?: string[];
+    rightItems?: string[];
+    correctMatches?: Record<string, string>;
+    scaleType?: "likert" | "rating" | "yes-no";
+    scaleMin?: number;
+    scaleMax?: number;
+}
+interface Quiz {
+    id: string;
+    title: string;
+    grade: number;
+    questions: QuizQuestion[];
+    status: string;
+}
+interface QuizAnswerDetail {
+    questionId: string;
+    questionText: string;
+    questionType: QuestionType;
+    points: number;
+    pointsEarned: number;
+    selectedAnswer?: string | string[] | number[] | Record<string, string> | number;
+    correctAnswer?: string | string[] | Record<string, string>;
+    isCorrect: boolean;
+    explanation?: string;
+    hint?: string;
+}
+type AttemptStatus = "in_progress" | "completed" | "abandoned";
+interface ExternalQuizAttempt {
+    id: string;
+    quizId: string;
+    lessonId: string;
+    assignLessonId: string;
+    courseId: string;
+    childId: string;
+    parentId: string;
+    attemptNumber: number;
+    status: AttemptStatus;
+    score?: number;
+    correctAnswers?: number;
+    totalQuestions: number;
+    answers: QuizAnswerDetail[];
+    startedAt: string;
+    completedAt?: string;
+    timeSpentSeconds?: number;
+}
+interface QuizPlayerProps {
+    quizId: string;
+    lessonId: string;
+    assignLessonId: string;
+    courseId: string;
+    childId: string;
+    parentId: string;
+    apiBaseUrl: string;
+    authToken?: string;
+    onComplete?: (result: QuizResult) => void;
+    onError?: (error: Error) => void;
+    onProgress?: (progress: QuizProgress) => void;
+    className?: string;
+    styles?: QuizPlayerStyles;
+}
+interface QuizResult {
+    attemptId: string;
+    score: number;
+    correctAnswers: number;
+    totalQuestions: number;
+    answers: QuizAnswerDetail[];
+    timeSpentSeconds: number;
+}
+interface QuizProgress {
+    currentQuestion: number;
+    totalQuestions: number;
+    answeredQuestions: number;
+}
+interface QuizPlayerStyles {
+    containerClassName?: string;
+    questionClassName?: string;
+    optionClassName?: string;
+    buttonClassName?: string;
+    progressClassName?: string;
+}
+
+declare function QuizPlayer({ quizId, lessonId, assignLessonId, courseId, childId, parentId, apiBaseUrl, authToken, onComplete, onError, onProgress, className, }: QuizPlayerProps): react_jsx_runtime.JSX.Element;
+
+interface ApiClientConfig {
+    baseUrl: string;
+    authToken?: string;
+}
+declare class QuizApiClient {
+    private baseUrl;
+    private authToken?;
+    constructor(config: ApiClientConfig);
+    private request;
+    getQuiz(quizId: string): Promise<Quiz>;
+    createAttempt(params: {
+        quizId: string;
+        lessonId: string;
+        assignLessonId: string;
+        courseId: string;
+        childId: string;
+        parentId: string;
+    }): Promise<ExternalQuizAttempt>;
+    updateAttempt(attemptId: string, data: {
+        answers?: QuizAnswerDetail[];
+        status?: 'in_progress' | 'completed' | 'abandoned';
+        score?: number;
+        correctAnswers?: number;
+        timeSpentSeconds?: number;
+    }): Promise<ExternalQuizAttempt>;
+    getAttempt(attemptId: string): Promise<ExternalQuizAttempt>;
+    getAttempts(params: {
+        assignLessonId?: string;
+        childId?: string;
+        quizId?: string;
+    }): Promise<ExternalQuizAttempt[]>;
+}
+
+declare function checkAnswer(question: QuizQuestion, selectedAnswer: unknown): {
+    isCorrect: boolean;
+    pointsEarned: number;
+};
+declare function createAnswerDetail(question: QuizQuestion, selectedAnswer: unknown): QuizAnswerDetail;
+declare function calculateScore(answers: QuizAnswerDetail[]): {
+    score: number;
+    correctAnswers: number;
+    totalPoints: number;
+    earnedPoints: number;
+};
+declare function formatTime(seconds: number): string;
+
+export { type ApiClientConfig, type AttemptStatus, type ExternalQuizAttempt, type QuestionType, type Quiz, type QuizAnswerDetail, QuizApiClient, QuizPlayer, type QuizPlayerProps, type QuizPlayerStyles, type QuizProgress, type QuizQuestion, type QuizResult, calculateScore, checkAnswer, createAnswerDetail, formatTime };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type QuestionType = "single" | "multiple" | "true-false" | "free" | "essay" | "fill" | "sorting" | "matrix" | "assessment";
+interface QuizQuestion {
+    id: string;
+    question: string;
+    type: QuestionType;
+    points: number;
+    explanation?: string;
+    hint?: string;
+    imageUrl?: string;
+    options?: string[];
+    correctAnswer?: string | string[] | Record<string, string>;
+    blanks?: string[];
+    items?: string[];
+    correctOrder?: number[];
+    leftItems?: string[];
+    rightItems?: string[];
+    correctMatches?: Record<string, string>;
+    scaleType?: "likert" | "rating" | "yes-no";
+    scaleMin?: number;
+    scaleMax?: number;
+}
+interface Quiz {
+    id: string;
+    title: string;
+    grade: number;
+    questions: QuizQuestion[];
+    status: string;
+}
+interface QuizAnswerDetail {
+    questionId: string;
+    questionText: string;
+    questionType: QuestionType;
+    points: number;
+    pointsEarned: number;
+    selectedAnswer?: string | string[] | number[] | Record<string, string> | number;
+    correctAnswer?: string | string[] | Record<string, string>;
+    isCorrect: boolean;
+    explanation?: string;
+    hint?: string;
+}
+type AttemptStatus = "in_progress" | "completed" | "abandoned";
+interface ExternalQuizAttempt {
+    id: string;
+    quizId: string;
+    lessonId: string;
+    assignLessonId: string;
+    courseId: string;
+    childId: string;
+    parentId: string;
+    attemptNumber: number;
+    status: AttemptStatus;
+    score?: number;
+    correctAnswers?: number;
+    totalQuestions: number;
+    answers: QuizAnswerDetail[];
+    startedAt: string;
+    completedAt?: string;
+    timeSpentSeconds?: number;
+}
+interface QuizPlayerProps {
+    quizId: string;
+    lessonId: string;
+    assignLessonId: string;
+    courseId: string;
+    childId: string;
+    parentId: string;
+    apiBaseUrl: string;
+    authToken?: string;
+    onComplete?: (result: QuizResult) => void;
+    onError?: (error: Error) => void;
+    onProgress?: (progress: QuizProgress) => void;
+    className?: string;
+    styles?: QuizPlayerStyles;
+}
+interface QuizResult {
+    attemptId: string;
+    score: number;
+    correctAnswers: number;
+    totalQuestions: number;
+    answers: QuizAnswerDetail[];
+    timeSpentSeconds: number;
+}
+interface QuizProgress {
+    currentQuestion: number;
+    totalQuestions: number;
+    answeredQuestions: number;
+}
+interface QuizPlayerStyles {
+    containerClassName?: string;
+    questionClassName?: string;
+    optionClassName?: string;
+    buttonClassName?: string;
+    progressClassName?: string;
+}
+
+declare function QuizPlayer({ quizId, lessonId, assignLessonId, courseId, childId, parentId, apiBaseUrl, authToken, onComplete, onError, onProgress, className, }: QuizPlayerProps): react_jsx_runtime.JSX.Element;
+
+interface ApiClientConfig {
+    baseUrl: string;
+    authToken?: string;
+}
+declare class QuizApiClient {
+    private baseUrl;
+    private authToken?;
+    constructor(config: ApiClientConfig);
+    private request;
+    getQuiz(quizId: string): Promise<Quiz>;
+    createAttempt(params: {
+        quizId: string;
+        lessonId: string;
+        assignLessonId: string;
+        courseId: string;
+        childId: string;
+        parentId: string;
+    }): Promise<ExternalQuizAttempt>;
+    updateAttempt(attemptId: string, data: {
+        answers?: QuizAnswerDetail[];
+        status?: 'in_progress' | 'completed' | 'abandoned';
+        score?: number;
+        correctAnswers?: number;
+        timeSpentSeconds?: number;
+    }): Promise<ExternalQuizAttempt>;
+    getAttempt(attemptId: string): Promise<ExternalQuizAttempt>;
+    getAttempts(params: {
+        assignLessonId?: string;
+        childId?: string;
+        quizId?: string;
+    }): Promise<ExternalQuizAttempt[]>;
+}
+
+declare function checkAnswer(question: QuizQuestion, selectedAnswer: unknown): {
+    isCorrect: boolean;
+    pointsEarned: number;
+};
+declare function createAnswerDetail(question: QuizQuestion, selectedAnswer: unknown): QuizAnswerDetail;
+declare function calculateScore(answers: QuizAnswerDetail[]): {
+    score: number;
+    correctAnswers: number;
+    totalPoints: number;
+    earnedPoints: number;
+};
+declare function formatTime(seconds: number): string;
+
+export { type ApiClientConfig, type AttemptStatus, type ExternalQuizAttempt, type QuestionType, type Quiz, type QuizAnswerDetail, QuizApiClient, QuizPlayer, type QuizPlayerProps, type QuizPlayerStyles, type QuizProgress, type QuizQuestion, type QuizResult, calculateScore, checkAnswer, createAnswerDetail, formatTime };