usegamigameapi 1.0.14 → 1.0.15

package/README.md

@@ -1,6 +1,9 @@
 # useGameAPI
 
-A React hook for managing interactive quiz/game flows through iframe communication using postMessage. This hook handles question flow, answer submission, result tracking, and seamless communication between a parent window and an iframe.
+A React hook for managing interactive quiz/game flows through iframe
+communication using postMessage. This hook handles question flow, answer
+submission, result tracking, and seamless communication between a parent window
+and an iframe.
 
 ## Installation
 
@@ -15,25 +18,26 @@ npm install usegamigameapi
 ## Basic Usage
 
 ```tsx
-import { useGameAPI } from 'usegamigameapi';
+import { useGameAPI } from "usegamigameapi";
 
 function QuizComponent() {
   const {
     quiz,
+    username,
     selectedAnswer,
     handleAnswerSelect,
     updateAnswer,
     handleContinue,
     isCompleted,
-    currentResult
+    currentResult,
   } = useGameAPI({
     onAnswerCorrect: ({ currentQuestionIndex }) => {
-      console.log('Correct answer at question', currentQuestionIndex);
+      console.log("Correct answer at question", currentQuestionIndex);
       // Trigger confetti or other celebrations
     },
     onAnswerIncorrect: () => {
-      console.log('Incorrect answer');
-    }
+      console.log("Incorrect answer");
+    },
   });
 
   // Render your quiz UI using the returned state and methods
@@ -46,9 +50,9 @@ function QuizComponent() {
 
 The `useGameAPI` hook accepts an object with the following optional callbacks:
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `onAnswerCorrect` | `(params: { currentQuestionIndex: number; correctAnswerId?: number; incorrectAnswerId?: number }) => void` | Callback fired when the user submits a correct answer |
+| Parameter           | Type                                                                                                       | Description                                              |
+| ------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `onAnswerCorrect`   | `(params: { currentQuestionIndex: number; correctAnswerId?: number; incorrectAnswerId?: number }) => void` | Callback fired when the user submits a correct answer    |
 | `onAnswerIncorrect` | `(params: { currentQuestionIndex: number; correctAnswerId?: number; incorrectAnswerId?: number }) => void` | Callback fired when the user submits an incorrect answer |
 
 ### Return Values
@@ -57,42 +61,44 @@ The hook returns an object with the following properties:
 
 #### State Data
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `quiz` | `any` | The current question data received from the parent window (contains text, audio URL, answers array, etc.) |
-| `currentResult` | `any` | The result object after submitting an answer (contains `isCorrect`, `isLastQuestion`, `correctAnswerId`, `incorrectAnswerId`, and explanation) |
-| `answers` | `(boolean \| null)[]` | Array of answer history where each index corresponds to a question (true = correct, false = incorrect, null = unanswered) |
-| `correctCount` | `number` | Total count of correctly answered questions |
-| `currentQuestionIndex` | `number` | Zero-based index of the current question |
+| Property               | Type                  | Description                                                                                                                                    |
+| ---------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `quiz`                 | `any`                 | The current question data received from the parent window (contains text, audio URL, answers array, etc.)                                      |
+| `currentResult`        | `any`                 | The result object after submitting an answer (contains `isCorrect`, `isLastQuestion`, `correctAnswerId`, `incorrectAnswerId`, and explanation) |
+| `answers`              | `(boolean \| null)[]` | Array of answer history where each index corresponds to a question (true = correct, false = incorrect, null = unanswered)                      |
+| `correctCount`         | `number`              | Total count of correctly answered questions                                                                                                    |
+| `currentQuestionIndex` | `number`              | Zero-based index of the current question                                                                                                       |
+| `username`             | `string`              | The username received from the parent window during initialization                                                                             |
 
 #### State Status
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `selectedAnswer` | `{ id: number; content: string } \| null` | The currently selected answer object |
-| `isSubmitting` | `boolean` | Indicates whether an answer submission is in progress |
-| `hasSubmitted` | `boolean` | Indicates whether the current question has been submitted and is waiting for the Continue action |
-| `isCompleted` | `boolean` | Indicates whether all questions have been completed |
+| Property         | Type                                      | Description                                                                                      |
+| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `selectedAnswer` | `{ id: number; content: string } \| null` | The currently selected answer object                                                             |
+| `isSubmitting`   | `boolean`                                 | Indicates whether an answer submission is in progress                                            |
+| `hasSubmitted`   | `boolean`                                 | Indicates whether the current question has been submitted and is waiting for the Continue action |
+| `isCompleted`    | `boolean`                                 | Indicates whether all questions have been completed                                              |
 
 #### Methods
 
-| Method | Type | Description |
-|--------|------|-------------|
-| `handleAnswerSelect` | `(answer: { id: number; content: string }) => void` | Selects an answer for the current question. Only works if not submitting and not already submitted |
-| `updateAnswer` | `() => Promise<void>` | Submits the selected answer to the parent window. Returns a promise that resolves immediately |
-| `handleContinue` | `() => void` | Moves to the next question or marks the quiz as completed if it's the last question. Only works after an answer has been submitted |
-| `finish` | `() => void` | Sends a finish signal to the parent window (typically used to resize iframe) |
+| Method               | Type                                                | Description                                                                                                                        |
+| -------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `handleAnswerSelect` | `(answer: { id: number; content: string }) => void` | Selects an answer for the current question. Only works if not submitting and not already submitted                                 |
+| `updateAnswer`       | `() => Promise<void>`                               | Submits the selected answer to the parent window. Returns a promise that resolves immediately                                      |
+| `handleContinue`     | `() => void`                                        | Moves to the next question or marks the quiz as completed if it's the last question. Only works after an answer has been submitted |
+| `finish`             | `() => void`                                        | Sends a finish signal to the parent window (typically used to resize iframe)                                                       |
 
 ## Usage Examples
 
 ### Complete Quiz Flow Example
 
 ```tsx
-import { useGameAPI } from 'usegamigameapi';
+import { useGameAPI } from "usegamigameapi";
 
 function GameQuiz() {
   const {
     quiz,
+    username,
     selectedAnswer,
     currentResult,
     answers,
@@ -104,16 +110,22 @@ function GameQuiz() {
     handleAnswerSelect,
     updateAnswer,
     handleContinue,
-    finish
+    finish,
   } = useGameAPI({
     onAnswerCorrect: ({ currentQuestionIndex, correctAnswerId }) => {
       // Show success animation or confetti
-      console.log(`Question ${currentQuestionIndex + 1} answered correctly!`, { correctAnswerId });
+      console.log(`Question ${currentQuestionIndex + 1} answered correctly!`, {
+        correctAnswerId,
+      });
     },
-    onAnswerIncorrect: ({ currentQuestionIndex, correctAnswerId, incorrectAnswerId }) => {
+    onAnswerIncorrect: ({
+      currentQuestionIndex,
+      correctAnswerId,
+      incorrectAnswerId,
+    }) => {
       // Show error feedback
-      console.log('Incorrect answer', { correctAnswerId, incorrectAnswerId });
-    }
+      console.log("Incorrect answer", { correctAnswerId, incorrectAnswerId });
+    },
   });
 
   // Show loading state while waiting for first question
@@ -126,7 +138,9 @@ function GameQuiz() {
     return (
       <div>
         <h2>Quiz Completed!</h2>
-        <p>You got {correctCount} out of {answers.length} questions correct.</p>
+        <p>
+          You got {correctCount} out of {answers.length} questions correct.
+        </p>
         <button onClick={finish}>Finish</button>
       </div>
     );
@@ -137,14 +151,15 @@ function GameQuiz() {
       {/* Progress bar */}
       <div>
         Question {currentQuestionIndex + 1} of {answers.length + 1}
-        <div style={{ display: 'flex', gap: '4px' }}>
+        <div style={{ display: "flex", gap: "4px" }}>
           {answers.map((answer, idx) => (
             <div
               key={idx}
               style={{
-                width: '20px',
-                height: '4px',
-                backgroundColor: answer === true ? 'green' : answer === false ? 'red' : 'gray'
+                width: "20px",
+                height: "4px",
+                backgroundColor:
+                  answer === true ? "green" : answer === false ? "red" : "gray",
               }}
             />
           ))}
@@ -163,10 +178,10 @@ function GameQuiz() {
             onClick={() => handleAnswerSelect(answer)}
             disabled={isSubmitting || hasSubmitted}
             style={{
-              backgroundColor: selectedAnswer?.id === answer.id ? '#007bff' : '#f0f0f0',
-              opacity: hasSubmitted ? 0.6 : 1
-            }}
-          >
+              backgroundColor:
+                selectedAnswer?.id === answer.id ? "#007bff" : "#f0f0f0",
+              opacity: hasSubmitted ? 0.6 : 1,
+            }}>
             {answer.content}
           </button>
         ))}
@@ -176,8 +191,7 @@ function GameQuiz() {
       {!hasSubmitted && (
         <button
           onClick={updateAnswer}
-          disabled={!selectedAnswer || isSubmitting}
-        >
+          disabled={!selectedAnswer || isSubmitting}>
           Submit Answer
         </button>
       )}
@@ -185,12 +199,10 @@ function GameQuiz() {
       {/* Result display and Continue button */}
       {hasSubmitted && currentResult && (
         <div>
-          <p>
-            {currentResult.isCorrect ? '✓ Correct!' : '✗ Incorrect'}
-          </p>
+          <p>{currentResult.isCorrect ? "✓ Correct!" : "✗ Incorrect"}</p>
           {currentResult.explanation && <p>{currentResult.explanation}</p>}
           <button onClick={handleContinue}>
-            {currentResult.isLastQuestion ? 'Finish Quiz' : 'Next Question'}
+            {currentResult.isLastQuestion ? "Finish Quiz" : "Next Question"}
           </button>
         </div>
       )}
@@ -205,10 +217,17 @@ function GameQuiz() {
 ### Minimal Example
 
 ```tsx
-import { useGameAPI } from 'usegamigameapi';
+import { useGameAPI } from "usegamigameapi";
 
 function SimpleQuiz() {
-  const { quiz, handleAnswerSelect, updateAnswer, handleContinue, selectedAnswer, hasSubmitted } = useGameAPI();
+  const {
+    quiz,
+    handleAnswerSelect,
+    updateAnswer,
+    handleContinue,
+    selectedAnswer,
+    hasSubmitted,
+  } = useGameAPI();
 
   return (
     <div>
@@ -217,8 +236,7 @@ function SimpleQuiz() {
         <button
           key={answer.id}
           onClick={() => handleAnswerSelect(answer)}
-          disabled={hasSubmitted}
-        >
+          disabled={hasSubmitted}>
           {answer.content}
         </button>
       ))}
@@ -227,9 +245,7 @@ function SimpleQuiz() {
           Submit
         </button>
       )}
-      {hasSubmitted && (
-        <button onClick={handleContinue}>Continue</button>
-      )}
+      {hasSubmitted && <button onClick={handleContinue}>Continue</button>}
     </div>
   );
 }
@@ -237,21 +253,34 @@ function SimpleQuiz() {
 
 ## Architecture
 
-This hook uses a **bridge pattern** to facilitate communication between a parent window (Main Web) and a child iframe (Sub Web) through `window.postMessage`. The communication flow works as follows:
+This hook uses a **bridge pattern** to facilitate communication between a parent
+window (Main Web) and a child iframe (Sub Web) through `window.postMessage`. The
+communication flow works as follows:
 
 ### Communication Flow
 
-1. **Initialization**: When the hook mounts, it sends `SHOW_LO5` to request the first question
-2. **Question Received**: Parent responds with `RETURN_LO5` containing question data
-3. **Answer Submission**: User selects an answer and calls `updateAnswer()`, which sends `UPDATE_ANSWER` with the answer ID
-4. **Result Received**: Parent responds with `RETURN_UPDATE_ANSWER` containing `isCorrect`, `isLastQuestion`, `correctAnswerId`, `incorrectAnswerId`, and result data
-5. **Continue**: User calls `handleContinue()` which either requests the next question (`SHOW_LO5`) or marks the quiz as completed
-6. **Finish**: When complete, `finish()` sends `FINISH` to signal completion (typically for iframe resizing)
+1. **Initialization**: When the hook mounts, it listens for `INIT` message from
+   the parent window containing game information (including `username`)
+2. **Start Game**: After initialization, the hook sends `SHOW_LO5` to request
+   the first question
+3. **Question Received**: Parent responds with `RETURN_LO5` containing question
+   data
+4. **Answer Submission**: User selects an answer and calls `updateAnswer()`,
+   which sends `UPDATE_ANSWER` with the answer ID
+5. **Result Received**: Parent responds with `RETURN_UPDATE_ANSWER` containing
+   `isCorrect`, `isLastQuestion`, `correctAnswerId`, `incorrectAnswerId`, and
+   result data
+6. **Continue**: User calls `handleContinue()` which either requests the next
+   question (`SHOW_LO5`) or marks the quiz as completed
+7. **Finish**: When complete, `finish()` sends `FINISH` to signal completion
+   (typically for iframe resizing)
 
 ### Action Types
 
 The bridge uses the following action constants (defined internally):
 
+- `INIT`: Main → Sub - Initialize game with user information (includes
+  `username`)
 - `SHOW_LO5`: Sub → Main - Request a question
 - `RETURN_LO5`: Main → Sub - Send question data
 - `UPDATE_ANSWER`: Sub → Main - Submit selected answer
@@ -260,11 +289,15 @@ The bridge uses the following action constants (defined internally):
 
 ## Notes
 
-- The hook automatically requests the first question when mounted
+- The hook automatically listens for `INIT` message from the parent window when
+  mounted to receive game initialization data (including username)
+- The hook automatically requests the first question after initialization
 - Answer history is tracked in the `answers` array, indexed by question number
-- The hook uses both `useState` and `useRef` to ensure correct closure behavior across renders
+- The hook uses both `useState` and `useRef` to ensure correct closure behavior
+  across renders
 - All communication is asynchronous through postMessage events
-- Make sure your parent window is set up to handle the corresponding postMessage events
+- Make sure your parent window is set up to send `INIT` message with game data
+  and handle the corresponding postMessage events
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usegamigameapi",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",