scorm-player 1.2.3 → 1.2.4

package/README.md

@@ -4,11 +4,15 @@ A lightweight SCORM 2004 unpacker + manifest parser + storage adapter system.
 
 This package allows you to:
 
--   Upload SCORM 2004 ZIP packages
--   Unpack them server-side (Node.js, Next.js server actions)
--   Parse imsmanifest.xml (using a Node-compatible DOM parser)
--   Save unpacked files to any storage (Supabase included)
--   Render SCORM content inside a React <ScormPlayer /> component
+Upload SCORM 2004 ZIP packages
+
+Unpack them server-side (Node.js, Next.js server actions)
+
+Parse imsmanifest.xml (using a Node-compatible DOM parser)
+
+Save unpacked files to any storage (Supabase included)
+
+Render SCORM content inside a React <ScormPlayer /> component or as a full-page course
 
 ## 🚀 Features
 
@@ -29,7 +33,7 @@ npm install scorm-player
 
 The package requires:
 
--   react >= 18
+react >= 18
 
 React is declared as a peer dependency, so it will use whatever version the project already has.
 
@@ -60,54 +64,81 @@ import { unpackSCORM, parseManifest, SupabaseAdapter } from "scorm-player";
 import { ScormPlayer } from "scorm-player";
 ```
 
-## 🧭 Usage — Upload SCORM Package (Next.js Server Action)
+## 🧭 Usage — Upload a SCORM Package (Next.js Server Action)
 
-### Client Component (upload button)
+### Client Component (Upload Button + Get Launch Link)
 
 ```typescript
 "use client";
 
 import { useState } from "react";
 import { uploadSCORMCourse } from "./actions/uploadSCORMCourse";
+import { ScormPlayer } from "scorm-player";
 
 export default function ScormPage() {
 	const [file, setFile] = useState<File | null>(null);
+	const [link, setLink] = useState<string>("");
+
+	const handleUpload = async () => {
+		if (!file) return;
+
+		// Get the SCORM launch link after uploading
+		const launchLink = await uploadSCORMCourse(file, "tests");
+		setLink(launchLink);
+		console.log("SCORM launch link:", launchLink);
+	};
 
 	return (
-		<div>
-			<input
-				type='file'
-				onChange={(e) => setFile(e.target.files?.[0] || null)}
-			/>
-			<button onClick={() => file && uploadSCORMCourse(file)}>
-				Upload
-			</button>
-		</div>
+		<>
+			<div>
+				<input
+					type='file'
+					onChange={(e) => setFile(e.target.files?.[0] || null)}
+				/>
+				<button onClick={handleUpload}>Upload</button>
+			</div>
+
+			{/* Embed SCORM in an iframe */}
+			{link && (
+				<ScormPlayer
+					launchUrl={link}
+					saveProgress={(data) =>
+						console.log("SCORM Progress:", data)
+					}
+				/>
+			)}
+		</>
 	);
 }
 ```
 
-### Server Action (unpack + save SCORM)
+### Server Action (Unpack + Save SCORM)
 
 ```typescript
 "use server";
 
 import { unpackSCORM, parseManifest, SupabaseAdapter } from "scorm-player";
 
-export async function uploadSCORMCourse(file: File) {
-	const arrayBuffer = await file.arrayBuffer();
-	const buffer = Buffer.from(arrayBuffer);
-
+export async function uploadSCORMCourse(
+	file: File,
+	baseFolder: string = "course"
+) {
+	const buffer = Buffer.from(await file.arrayBuffer());
 	const { files, manifestXml } = await unpackSCORM(buffer);
-	const launchUrl = parseManifest(manifestXml);
+
+	const launchPath = parseManifest(manifestXml); // path to index.html
 
 	const adapter = new SupabaseAdapter(
-		process.env.SUPABASE_URL!,
-		process.env.SUPABASE_KEY!,
-		"courses"
+		process.env.NEXT_PUBLIC_SUPABASE_URL!,
+		process.env.NEXT_PUBLIC_SUPABASE_SERVICE_KEY!,
+		baseFolder
 	);
 
-	await adapter.uploadFolder("courses", files);
+	// Upload SCORM files and get a unique folder
+	const uniqueFolder = await adapter.uploadFolder(files, baseFolder);
+
+	// Form the full launch URL via API route
+	const launchUrl = `/api/scorm/${uniqueFolder}/${launchPath}`;
 
 	return launchUrl;
 }
@@ -115,45 +146,84 @@ export async function uploadSCORMCourse(file: File) {
 
 ## 🖥️ Displaying SCORM Content
 
+### 1️⃣ In an iframe (embedded mode)
+
 ```typescript
 import { ScormPlayer } from "scorm-player";
 
 export default function PlayerPage() {
-	return <ScormPlayer launchUrl='courses/index.html' />;
+	const launchUrl = "/api/scorm/abc123/index.html";
+
+	return (
+		<ScormPlayer
+			launchUrl={launchUrl}
+			saveProgress={(data) => console.log("SCORM Progress:", data)}
+		/>
+	);
 }
 ```
 
-The component uses an <iframe /> to show SCORM content.
+### 2️⃣ Full-page mode (open in a separate tab)
 
-## 🗃️ Supabase Storage Adapter
+Simply redirect the user to the SCORM API route:
 
-Uploads all extracted SCORM files:
+```typescript
+"use client";
+import { useEffect } from "react";
+
+export default function LaunchScormPage({
+	searchParams,
+}: {
+	searchParams: { launch: string };
+}) {
+	useEffect(() => {
+		if (searchParams.launch) {
+			// Add query param ?mode=page for full-page mode
+			window.location.href = `${searchParams.launch}?mode=page`;
+		}
+	}, [searchParams.launch]);
+
+	return <p>Loading SCORM course...</p>;
+}
+```
+
+Usage example:
 
 ```typescript
-const adapter = new SupabaseAdapter(SUPABASE_URL, SUPABASE_KEY, "folderName");
+// After uploading
+const launchLink = await uploadSCORMCourse(file, "tests");
+
+// Embedded mode
+<ScormPlayer launchUrl={launchLink} saveProgress={...} />
 
-await adapter.uploadFolder("folderName", files);
+// Full-page mode
+window.open(`${launchLink}?mode=page`, "_blank");
 ```
 
-You can also write your own adapters (S3, GCP, local FS, etc.).
+In full-page mode, no additional Next.js component is required — the SCORM content renders directly through the /api/scorm/... route.
+
+## 🗃️ Supabase Storage Adapter
+
+```typescript
+const adapter = new SupabaseAdapter(SUPABASE_URL, SUPABASE_KEY, "folderName");
+await adapter.uploadFolder(files, "folderName");
+```
+
+You can also write your own adapters for S3, GCP, local FS, etc.
 
 ## 🧩 API Reference
 
--   `unpackSCORM(zipData: Buffer | Uint8Array)` - Unpacks a SCORM ZIP file into a dictionary of files.
--   `parseManifest(manifestXml: string)` - Locates the SCORM launch URL from imsmanifest.xml.
--   `SupabaseAdapter` - Uploads unpacked files into Supabase Storage.
--   `<ScormPlayer launchUrl="..." />` - Renders SCORM content inside an iframe.
+-   `unpackSCORM(zipData: Buffer | Uint8Array)` — Unpacks a SCORM ZIP file into a dictionary of files.
+-   `parseManifest(manifestXml: string)` — Locates the SCORM launch URL from imsmanifest.xml.
+-   `SupabaseAdapter` — Uploads unpacked files into Supabase Storage.
+-   `<ScormPlayer launchUrl="..." />` — Renders SCORM content inside an iframe.
 
 ## 🛠️ Requirements
 
 -   Node.js 18+
--   React 18 or newer
--   Next.js (optional but supported)
+-   React 18+
+-   Next.js 15+ (App Router)
 
 ## 📄 License
 
 MIT License.
-
-## 🎉 Done
-
-Your SCORM Player is ready to use.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scorm-player",
-	"version": "1.2.3",
+	"version": "1.2.4",
 	"description": "SCORM 2004 player, unpacker and manifest parser for Node.js / Next.js with storage adapters and React iframe renderer.",
 	"main": "dist/index.js",
 	"module": "dist/index.mjs",