scorm-player 1.0.1 → 1.2.0

package/README.md

@@ -1,128 +1,159 @@
-# SCORM Player 2004
+# SCORM Player 2004 — Node/Browser Compatible Loader & Parser
 
-scorm-player is a universal module for working with SCORM 2004 packages. It works with Next.js, React, and any Node.js project.
+A lightweight SCORM 2004 unpacker + manifest parser + storage adapter system.
 
-## Features
+This package allows you to:
 
--   Upload and unpack SCORM 2004 packages on the server
--   Save files to Supabase Storage with a customizable folder
--   Generate launch URLs for lessons or tests
--   React component ScormPlayer to embed SCORM content
--   Track user progress and save it to a database
+-   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
 
-## Installation
+## 🚀 Features
+
+✔ Supports SCORM 2004 ZIP packages
+✔ Works in Node.js (backend) and Browser (frontend)
+✔ SCORM ZIP unpacking using JSZip
+✔ Manifest parsing using xmldom (no browser APIs)
+✔ Supabase storage adapter included
+✔ Ready for Next.js — Server Actions + Client Components
+✔ Works with React 18 and React 19
+✔ Published as a reusable NPM module
+
+## 📦 Installation
 
 ```bash
 npm install scorm-player
 ```
 
-React and ReactDOM must be installed in your project:
+The package requires:
 
-```bash
-npm install react react-dom
-npm install --save-dev @types/react @types/react-dom
+-   react >= 18
+
+React is declared as a peer dependency, so it will use whatever version the project already has.
+
+## 📁 Package Structure
+
+```
+src/
+  backend/
+    unpackSCORM.ts
+    parseManifest.ts
+    storageAdapters/
+      supabaseAdapter.ts
+  frontend/
+    ScormPlayer.tsx
+```
+
+You can import backend utilities or frontend components separately:
+
+### Backend
+
+```typescript
+import { unpackSCORM, parseManifest, SupabaseAdapter } from "scorm-player";
+```
+
+### Frontend
+
+```typescript
+import { ScormPlayer } from "scorm-player";
+```
+
+## 🧭 Usage — Upload SCORM Package (Next.js Server Action)
+
+### Client Component (upload button)
+
+```typescript
+"use client";
+
+import { useState } from "react";
+import { uploadSCORMCourse } from "./actions/uploadSCORMCourse";
+
+export default function ScormPage() {
+	const [file, setFile] = useState<File | null>(null);
+
+	return (
+		<div>
+			<input
+				type='file'
+				onChange={(e) => setFile(e.target.files?.[0] || null)}
+			/>
+			<button onClick={() => file && uploadSCORMCourse(file)}>
+				Upload
+			</button>
+		</div>
+	);
+}
 ```
 
-## Backend: SCORM unpacking and uploading
+### Server Action (unpack + save SCORM)
 
 ```typescript
-import { unpackSCORM, parseManifest } from "scorm-player/backend";
-import { SupabaseAdapter } from "scorm-player/backend/storageAdapters/supabaseAdapter";
+"use server";
+
+import { unpackSCORM, parseManifest, SupabaseAdapter } from "scorm-player";
 
-export async function uploadSCORMCourse(file: File, folderName: string) {
-	const { files, manifestXml } = await unpackSCORM(file);
+export async function uploadSCORMCourse(file: File) {
+	const arrayBuffer = await file.arrayBuffer();
+	const buffer = Buffer.from(arrayBuffer);
+
+	const { files, manifestXml } = await unpackSCORM(buffer);
 	const launchUrl = parseManifest(manifestXml);
 
 	const adapter = new SupabaseAdapter(
 		process.env.SUPABASE_URL!,
 		process.env.SUPABASE_KEY!,
-		folderName
+		"courses"
 	);
 
-	await adapter.uploadFolder(folderName, files);
+	await adapter.uploadFolder("courses", files);
 
 	return launchUrl;
 }
 ```
 
-## Frontend: React ScormPlayer component
+## 🖥️ Displaying SCORM Content
 
 ```typescript
-import { ScormPlayer } from "scorm-player/frontend";
-
-<ScormPlayer
-	launchUrl='https://xyz.supabase.co/storage/v1/object/public/my_custom_folder/index.html'
-	userId={user.id}
-	courseId={course.id}
-	lessonId={lesson.id}
-	saveProgress={async (data) => {
-		await fetch("/api/scorm/saveProgress", {
-			method: "POST",
-			body: JSON.stringify({
-				userId: user.id,
-				courseId: course.id,
-				lessonId: lesson.id,
-				data,
-			}),
-		});
-	}}
-/>;
-```
+import { ScormPlayer } from "scorm-player";
 
--   `launchUrl` — public URL to the main SCORM lesson HTML file
--   `saveProgress` — callback to save user progress
+export default function PlayerPage() {
+	return <ScormPlayer launchUrl='courses/index.html' />;
+}
+```
 
-## Supabase Storage
+The component uses an <iframe /> to show SCORM content.
 
-Create a bucket, e.g., scorm-courses
+## 🗃️ Supabase Storage Adapter
 
-You can set a custom folder name:
+Uploads all extracted SCORM files:
 
 ```typescript
-const adapter = new SupabaseAdapter(
-	process.env.SUPABASE_URL!,
-	process.env.SUPABASE_KEY!,
-	"my_custom_folder"
-);
+const adapter = new SupabaseAdapter(SUPABASE_URL, SUPABASE_KEY, "folderName");
+
+await adapter.uploadFolder("folderName", files);
 ```
 
--   All SCORM files will be uploaded to the specified folder
--   `getFileUrl(path)` returns a public link to the file
+You can also write your own adapters (S3, GCP, local FS, etc.).
 
-## TypeScript typings
+## 🧩 API Reference
 
-```typescript
-import { SCORMState } from "scorm-player/types/scorm";
+-   `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.
 
-const progress: SCORMState = {
-	"cmi.location": "page_3",
-	"cmi.completion_status": "incomplete",
-	"cmi.score.raw": 80,
-};
-```
+## 🛠️ Requirements
 
-## Features
+-   Node.js 18+
+-   React 18 or newer
+-   Next.js (optional but supported)
 
--   Supports SCORM 2004 API (API_1484_11)
--   Can be used as an NPM package in any React/Next.js project
--   Frontend component and backend functions are fully decoupled
--   Custom folders in Supabase allow organizing courses flexibly
+## 📄 License
 
-## Project structure example
-
-```
-src/
-├─ backend/
-│   ├─ unpackSCORM.ts
-│   ├─ parseManifest.ts
-│   └─ storageAdapters/supabaseAdapter.ts
-├─ frontend/
-│   └─ ScormPlayer.tsx
-├─ types/
-│   └─ scorm.ts
-└─ index.ts
-```
+MIT License.
 
-## License
+## 🎉 Done
 
-MIT
+Your SCORM Player is ready to use.

package/dist/index.d.mts

@@ -4,7 +4,7 @@ interface ParsedSCORM {
     files: Record<string, string>;
     manifestXml: string;
 }
-declare function unpackSCORM(zipFile: File | Buffer): Promise<ParsedSCORM>;
+declare function unpackSCORM(zipData: Buffer | Uint8Array): Promise<ParsedSCORM>;
 
 declare function parseManifest(manifestXml: string): string;
 
@@ -12,9 +12,11 @@ declare class SupabaseAdapter {
     client: SupabaseClient;
     rootFolder: string;
     constructor(supabaseUrl: string, supabaseKey: string, rootFolder?: string);
+    generateUniqueFolder(baseName: string): string;
     uploadFile(path: string, content: string | Buffer): Promise<string>;
-    uploadFolder(folderPath: string, files: Record<string, string | Buffer>): Promise<void>;
+    uploadFolder(files: Record<string, string | Buffer>, baseFolderName?: string): Promise<string>;
     getFileUrl(path: string): string;
+    getLaunchUrl(folderName: string, launchPath: string): string;
 }
 
 interface SCORMState {
@@ -35,4 +37,4 @@ interface ScormPlayerProps {
 }
 declare function ScormPlayer({ launchUrl, userId, courseId, lessonId, saveProgress, }: ScormPlayerProps): JSX.Element;
 
-export { type ParsedSCORM, type SCORMState, ScormPlayer, SupabaseAdapter, parseManifest, unpackSCORM };
+export { type ParsedSCORM, ScormPlayer, SupabaseAdapter, parseManifest, unpackSCORM };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ interface ParsedSCORM {
     files: Record<string, string>;
     manifestXml: string;
 }
-declare function unpackSCORM(zipFile: File | Buffer): Promise<ParsedSCORM>;
+declare function unpackSCORM(zipData: Buffer | Uint8Array): Promise<ParsedSCORM>;
 
 declare function parseManifest(manifestXml: string): string;
 
@@ -12,9 +12,11 @@ declare class SupabaseAdapter {
     client: SupabaseClient;
     rootFolder: string;
     constructor(supabaseUrl: string, supabaseKey: string, rootFolder?: string);
+    generateUniqueFolder(baseName: string): string;
     uploadFile(path: string, content: string | Buffer): Promise<string>;
-    uploadFolder(folderPath: string, files: Record<string, string | Buffer>): Promise<void>;
+    uploadFolder(files: Record<string, string | Buffer>, baseFolderName?: string): Promise<string>;
     getFileUrl(path: string): string;
+    getLaunchUrl(folderName: string, launchPath: string): string;
 }
 
 interface SCORMState {
@@ -35,4 +37,4 @@ interface ScormPlayerProps {
 }
 declare function ScormPlayer({ launchUrl, userId, courseId, lessonId, saveProgress, }: ScormPlayerProps): JSX.Element;
 
-export { type ParsedSCORM, type SCORMState, ScormPlayer, SupabaseAdapter, parseManifest, unpackSCORM };
+export { type ParsedSCORM, ScormPlayer, SupabaseAdapter, parseManifest, unpackSCORM };

package/dist/index.js

@@ -39,50 +39,75 @@ module.exports = __toCommonJS(src_exports);
 
 // src/backend/unpackSCORM.ts
 var import_jszip = __toESM(require("jszip"));
-async function unpackSCORM(zipFile) {
-  const zip = await import_jszip.default.loadAsync(zipFile);
+async function unpackSCORM(zipData) {
+  const zip = await import_jszip.default.loadAsync(zipData);
   const files = {};
   for (const filename of Object.keys(zip.files)) {
-    const fileData = await zip.files[filename].async("string");
-    files[filename] = fileData;
+    const file = zip.files[filename];
+    if (!file)
+      continue;
+    const content = await file.async("string");
+    files[filename] = content;
   }
   const manifestXml = files["imsmanifest.xml"];
-  if (!manifestXml)
+  if (!manifestXml) {
     throw new Error("imsmanifest.xml not found in SCORM package");
+  }
   return { files, manifestXml };
 }
 
 // src/backend/parseManifest.ts
+var import_xmldom = require("xmldom");
 function parseManifest(manifestXml) {
-  const parser = new DOMParser();
-  const xml = parser.parseFromString(manifestXml, "text/xml");
-  const resource = xml.querySelector("resource");
-  if (!resource)
-    throw new Error("No <resource> found in manifest");
-  return resource.getAttribute("href") || "";
+  const xmlDoc = new import_xmldom.DOMParser().parseFromString(manifestXml, "text/xml");
+  const resources = xmlDoc.getElementsByTagName("resource");
+  const firstResource = resources[0];
+  if (!firstResource) {
+    throw new Error("SCORM manifest has no <resource> element");
+  }
+  const launch = firstResource.getAttribute("href");
+  if (!launch) {
+    throw new Error("SCORM launch URL (href) not found in manifest");
+  }
+  return launch;
 }
 
 // src/backend/storageAdapters/supabaseAdapter.ts
 var import_supabase_js = require("@supabase/supabase-js");
+var import_crypto = require("crypto");
 var SupabaseAdapter = class {
   constructor(supabaseUrl, supabaseKey, rootFolder = "scorm-courses") {
     this.client = (0, import_supabase_js.createClient)(supabaseUrl, supabaseKey);
     this.rootFolder = rootFolder;
   }
+  // Генерация уникального имени папки
+  generateUniqueFolder(baseName) {
+    const id = (0, import_crypto.randomUUID)();
+    return `${baseName}-${id}`;
+  }
   async uploadFile(path, content) {
     const fullPath = `${this.rootFolder}/${path}`;
     await this.client.storage.from(this.rootFolder).upload(path, content, { upsert: true });
     return fullPath;
   }
-  async uploadFolder(folderPath, files) {
+  // Принимаем files и optional baseName для папки
+  async uploadFolder(files, baseFolderName = "course") {
+    const uniqueFolder = this.generateUniqueFolder(baseFolderName);
     for (const [filePath, content] of Object.entries(files)) {
-      const fullPath = `${folderPath}/${filePath}`;
+      const fullPath = `${uniqueFolder}/${filePath}`;
       await this.uploadFile(fullPath, content);
     }
+    return uniqueFolder;
   }
+  // Получаем публичный URL полного пути к файлу
   getFileUrl(path) {
     return this.client.storage.from(this.rootFolder).getPublicUrl(path).data.publicUrl;
   }
+  // Удобная функция для получения URL к launch файлу
+  getLaunchUrl(folderName, launchPath) {
+    const fullPath = `${folderName}/${launchPath}`;
+    return this.getFileUrl(fullPath);
+  }
 };
 
 // src/frontend/ScormPlayer.tsx

package/dist/index.mjs

@@ -1,49 +1,74 @@
 // src/backend/unpackSCORM.ts
 import JSZip from "jszip";
-async function unpackSCORM(zipFile) {
-  const zip = await JSZip.loadAsync(zipFile);
+async function unpackSCORM(zipData) {
+  const zip = await JSZip.loadAsync(zipData);
   const files = {};
   for (const filename of Object.keys(zip.files)) {
-    const fileData = await zip.files[filename].async("string");
-    files[filename] = fileData;
+    const file = zip.files[filename];
+    if (!file)
+      continue;
+    const content = await file.async("string");
+    files[filename] = content;
   }
   const manifestXml = files["imsmanifest.xml"];
-  if (!manifestXml)
+  if (!manifestXml) {
     throw new Error("imsmanifest.xml not found in SCORM package");
+  }
   return { files, manifestXml };
 }
 
 // src/backend/parseManifest.ts
+import { DOMParser } from "xmldom";
 function parseManifest(manifestXml) {
-  const parser = new DOMParser();
-  const xml = parser.parseFromString(manifestXml, "text/xml");
-  const resource = xml.querySelector("resource");
-  if (!resource)
-    throw new Error("No <resource> found in manifest");
-  return resource.getAttribute("href") || "";
+  const xmlDoc = new DOMParser().parseFromString(manifestXml, "text/xml");
+  const resources = xmlDoc.getElementsByTagName("resource");
+  const firstResource = resources[0];
+  if (!firstResource) {
+    throw new Error("SCORM manifest has no <resource> element");
+  }
+  const launch = firstResource.getAttribute("href");
+  if (!launch) {
+    throw new Error("SCORM launch URL (href) not found in manifest");
+  }
+  return launch;
 }
 
 // src/backend/storageAdapters/supabaseAdapter.ts
 import { createClient } from "@supabase/supabase-js";
+import { randomUUID } from "crypto";
 var SupabaseAdapter = class {
   constructor(supabaseUrl, supabaseKey, rootFolder = "scorm-courses") {
     this.client = createClient(supabaseUrl, supabaseKey);
     this.rootFolder = rootFolder;
   }
+  // Генерация уникального имени папки
+  generateUniqueFolder(baseName) {
+    const id = randomUUID();
+    return `${baseName}-${id}`;
+  }
   async uploadFile(path, content) {
     const fullPath = `${this.rootFolder}/${path}`;
     await this.client.storage.from(this.rootFolder).upload(path, content, { upsert: true });
     return fullPath;
   }
-  async uploadFolder(folderPath, files) {
+  // Принимаем files и optional baseName для папки
+  async uploadFolder(files, baseFolderName = "course") {
+    const uniqueFolder = this.generateUniqueFolder(baseFolderName);
     for (const [filePath, content] of Object.entries(files)) {
-      const fullPath = `${folderPath}/${filePath}`;
+      const fullPath = `${uniqueFolder}/${filePath}`;
       await this.uploadFile(fullPath, content);
     }
+    return uniqueFolder;
   }
+  // Получаем публичный URL полного пути к файлу
   getFileUrl(path) {
     return this.client.storage.from(this.rootFolder).getPublicUrl(path).data.publicUrl;
   }
+  // Удобная функция для получения URL к launch файлу
+  getLaunchUrl(folderName, launchPath) {
+    const fullPath = `${folderName}/${launchPath}`;
+    return this.getFileUrl(fullPath);
+  }
 };
 
 // src/frontend/ScormPlayer.tsx

package/package.json

@@ -1,39 +1,45 @@
 {
 	"name": "scorm-player",
-	"version": "1.0.1",
-	"description": "SCORM 2004 player module for Next.js and other frameworks, with backend unpacking and SCORM API support.",
+	"version": "1.2.0",
+	"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",
 	"types": "dist/index.d.ts",
 	"files": [
 		"dist"
 	],
 	"scripts": {
 		"build": "tsup src/index.ts --format cjs,esm --dts --out-dir dist",
-		"clean": "rm -rf dist"
+		"clean": "rm -rf dist",
+		"prepublishOnly": "npm run build"
 	},
 	"keywords": [
 		"scorm",
 		"scorm2004",
+		"scorm player",
 		"nextjs",
 		"react",
-		"player",
-		"elearning"
+		"elearning",
+		"lms",
+		"imsmanifest"
 	],
 	"author": "Shmelev Sergei",
 	"license": "MIT",
 	"dependencies": {
 		"@supabase/supabase-js": "^2.9.0",
-		"jszip": "^3.10.1"
+		"jszip": "^3.10.1",
+		"xmldom": "^0.6.0"
 	},
 	"peerDependencies": {
-		"react": ">=18 <20",
-		"react-dom": ">=18 <20"
+		"react": ">=18 <21",
+		"react-dom": ">=18 <21"
 	},
 	"devDependencies": {
 		"@types/react": "^18.3.27",
 		"@types/react-dom": "^18.3.7",
+		"@types/xmldom": "^0.1.34",
 		"tsup": "^7.3.0",
-		"typescript": "^5.2.0"
+		"typescript": "^5.4.5"
 	},
 	"repository": {
 		"type": "git",