scorm-player 1.0.0

package/README.md

@@ -0,0 +1,128 @@
+# SCORM Player 2004
+
+scorm-player is a universal module for working with SCORM 2004 packages. It works with Next.js, React, and any Node.js project.
+
+## Features
+
+-   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
+
+## Installation
+
+```bash
+npm install scorm-player
+```
+
+React and ReactDOM must be installed in your project:
+
+```bash
+npm install react react-dom
+npm install --save-dev @types/react @types/react-dom
+```
+
+## Backend: SCORM unpacking and uploading
+
+```typescript
+import { unpackSCORM, parseManifest } from "scorm-player/backend";
+import { SupabaseAdapter } from "scorm-player/backend/storageAdapters/supabaseAdapter";
+
+export async function uploadSCORMCourse(file: File, folderName: string) {
+	const { files, manifestXml } = await unpackSCORM(file);
+	const launchUrl = parseManifest(manifestXml);
+
+	const adapter = new SupabaseAdapter(
+		process.env.SUPABASE_URL!,
+		process.env.SUPABASE_KEY!,
+		folderName
+	);
+
+	await adapter.uploadFolder(folderName, files);
+
+	return launchUrl;
+}
+```
+
+## Frontend: React ScormPlayer component
+
+```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,
+			}),
+		});
+	}}
+/>;
+```
+
+-   `launchUrl` — public URL to the main SCORM lesson HTML file
+-   `saveProgress` — callback to save user progress
+
+## Supabase Storage
+
+Create a bucket, e.g., scorm-courses
+
+You can set a custom folder name:
+
+```typescript
+const adapter = new SupabaseAdapter(
+	process.env.SUPABASE_URL!,
+	process.env.SUPABASE_KEY!,
+	"my_custom_folder"
+);
+```
+
+-   All SCORM files will be uploaded to the specified folder
+-   `getFileUrl(path)` returns a public link to the file
+
+## TypeScript typings
+
+```typescript
+import { SCORMState } from "scorm-player/types/scorm";
+
+const progress: SCORMState = {
+	"cmi.location": "page_3",
+	"cmi.completion_status": "incomplete",
+	"cmi.score.raw": 80,
+};
+```
+
+## Features
+
+-   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
+
+## Project structure example
+
+```
+src/
+├─ backend/
+│   ├─ unpackSCORM.ts
+│   ├─ parseManifest.ts
+│   └─ storageAdapters/supabaseAdapter.ts
+├─ frontend/
+│   └─ ScormPlayer.tsx
+├─ types/
+│   └─ scorm.ts
+└─ index.ts
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,38 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+
+interface ParsedSCORM {
+    files: Record<string, string>;
+    manifestXml: string;
+}
+declare function unpackSCORM(zipFile: File | Buffer): Promise<ParsedSCORM>;
+
+declare function parseManifest(manifestXml: string): string;
+
+declare class SupabaseAdapter {
+    client: SupabaseClient;
+    rootFolder: string;
+    constructor(supabaseUrl: string, supabaseKey: string, rootFolder?: string);
+    uploadFile(path: string, content: string | Buffer): Promise<string>;
+    uploadFolder(folderPath: string, files: Record<string, string | Buffer>): Promise<void>;
+    getFileUrl(path: string): string;
+}
+
+interface SCORMState {
+    "cmi.location"?: string;
+    "cmi.completion_status"?: string;
+    "cmi.success_status"?: string;
+    "cmi.score.raw"?: number;
+    "cmi.progress_measure"?: number;
+    "cmi.suspend_data"?: string;
+}
+
+interface ScormPlayerProps {
+    launchUrl: string;
+    userId: string;
+    courseId: string;
+    lessonId: string;
+    saveProgress: (data: SCORMState) => void;
+}
+declare function ScormPlayer({ launchUrl, userId, courseId, lessonId, saveProgress, }: ScormPlayerProps): JSX.Element;
+
+export { type ParsedSCORM, type SCORMState, ScormPlayer, SupabaseAdapter, parseManifest, unpackSCORM };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+
+interface ParsedSCORM {
+    files: Record<string, string>;
+    manifestXml: string;
+}
+declare function unpackSCORM(zipFile: File | Buffer): Promise<ParsedSCORM>;
+
+declare function parseManifest(manifestXml: string): string;
+
+declare class SupabaseAdapter {
+    client: SupabaseClient;
+    rootFolder: string;
+    constructor(supabaseUrl: string, supabaseKey: string, rootFolder?: string);
+    uploadFile(path: string, content: string | Buffer): Promise<string>;
+    uploadFolder(folderPath: string, files: Record<string, string | Buffer>): Promise<void>;
+    getFileUrl(path: string): string;
+}
+
+interface SCORMState {
+    "cmi.location"?: string;
+    "cmi.completion_status"?: string;
+    "cmi.success_status"?: string;
+    "cmi.score.raw"?: number;
+    "cmi.progress_measure"?: number;
+    "cmi.suspend_data"?: string;
+}
+
+interface ScormPlayerProps {
+    launchUrl: string;
+    userId: string;
+    courseId: string;
+    lessonId: string;
+    saveProgress: (data: SCORMState) => void;
+}
+declare function ScormPlayer({ launchUrl, userId, courseId, lessonId, saveProgress, }: ScormPlayerProps): JSX.Element;
+
+export { type ParsedSCORM, type SCORMState, ScormPlayer, SupabaseAdapter, parseManifest, unpackSCORM };

package/dist/index.js

@@ -0,0 +1,128 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ScormPlayer: () => ScormPlayer,
+  SupabaseAdapter: () => SupabaseAdapter,
+  parseManifest: () => parseManifest,
+  unpackSCORM: () => unpackSCORM
+});
+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);
+  const files = {};
+  for (const filename of Object.keys(zip.files)) {
+    const fileData = await zip.files[filename].async("string");
+    files[filename] = fileData;
+  }
+  const manifestXml = files["imsmanifest.xml"];
+  if (!manifestXml)
+    throw new Error("imsmanifest.xml not found in SCORM package");
+  return { files, manifestXml };
+}
+
+// src/backend/parseManifest.ts
+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") || "";
+}
+
+// src/backend/storageAdapters/supabaseAdapter.ts
+var import_supabase_js = require("@supabase/supabase-js");
+var SupabaseAdapter = class {
+  constructor(supabaseUrl, supabaseKey, rootFolder = "scorm-courses") {
+    this.client = (0, import_supabase_js.createClient)(supabaseUrl, supabaseKey);
+    this.rootFolder = rootFolder;
+  }
+  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) {
+    for (const [filePath, content] of Object.entries(files)) {
+      const fullPath = `${folderPath}/${filePath}`;
+      await this.uploadFile(fullPath, content);
+    }
+  }
+  getFileUrl(path) {
+    return this.client.storage.from(this.rootFolder).getPublicUrl(path).data.publicUrl;
+  }
+};
+
+// src/frontend/ScormPlayer.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function ScormPlayer({
+  launchUrl,
+  userId,
+  courseId,
+  lessonId,
+  saveProgress
+}) {
+  const iframeRef = (0, import_react.useRef)(null);
+  const [scormState, setScormState] = (0, import_react.useState)({});
+  (0, import_react.useEffect)(() => {
+    window.API_1484_11 = {
+      Initialize: () => "true",
+      Terminate: () => "true",
+      GetValue: (key) => scormState[key] || "",
+      SetValue: (key, value) => {
+        const updatedState = { ...scormState, [key]: value };
+        setScormState(updatedState);
+        saveProgress(updatedState);
+        return "true";
+      },
+      Commit: () => {
+        saveProgress(scormState);
+        return "true";
+      },
+      GetLastError: () => 0,
+      GetErrorString: () => "",
+      GetDiagnostic: () => ""
+    };
+  }, [scormState, saveProgress]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("iframe", { ref: iframeRef, src: launchUrl, width: "100%", height: "600px" });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ScormPlayer,
+  SupabaseAdapter,
+  parseManifest,
+  unpackSCORM
+});

package/dist/index.mjs

@@ -0,0 +1,88 @@
+// src/backend/unpackSCORM.ts
+import JSZip from "jszip";
+async function unpackSCORM(zipFile) {
+  const zip = await JSZip.loadAsync(zipFile);
+  const files = {};
+  for (const filename of Object.keys(zip.files)) {
+    const fileData = await zip.files[filename].async("string");
+    files[filename] = fileData;
+  }
+  const manifestXml = files["imsmanifest.xml"];
+  if (!manifestXml)
+    throw new Error("imsmanifest.xml not found in SCORM package");
+  return { files, manifestXml };
+}
+
+// src/backend/parseManifest.ts
+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") || "";
+}
+
+// src/backend/storageAdapters/supabaseAdapter.ts
+import { createClient } from "@supabase/supabase-js";
+var SupabaseAdapter = class {
+  constructor(supabaseUrl, supabaseKey, rootFolder = "scorm-courses") {
+    this.client = createClient(supabaseUrl, supabaseKey);
+    this.rootFolder = rootFolder;
+  }
+  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) {
+    for (const [filePath, content] of Object.entries(files)) {
+      const fullPath = `${folderPath}/${filePath}`;
+      await this.uploadFile(fullPath, content);
+    }
+  }
+  getFileUrl(path) {
+    return this.client.storage.from(this.rootFolder).getPublicUrl(path).data.publicUrl;
+  }
+};
+
+// src/frontend/ScormPlayer.tsx
+import { useEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+function ScormPlayer({
+  launchUrl,
+  userId,
+  courseId,
+  lessonId,
+  saveProgress
+}) {
+  const iframeRef = useRef(null);
+  const [scormState, setScormState] = useState({});
+  useEffect(() => {
+    window.API_1484_11 = {
+      Initialize: () => "true",
+      Terminate: () => "true",
+      GetValue: (key) => scormState[key] || "",
+      SetValue: (key, value) => {
+        const updatedState = { ...scormState, [key]: value };
+        setScormState(updatedState);
+        saveProgress(updatedState);
+        return "true";
+      },
+      Commit: () => {
+        saveProgress(scormState);
+        return "true";
+      },
+      GetLastError: () => 0,
+      GetErrorString: () => "",
+      GetDiagnostic: () => ""
+    };
+  }, [scormState, saveProgress]);
+  return /* @__PURE__ */ jsx("iframe", { ref: iframeRef, src: launchUrl, width: "100%", height: "600px" });
+}
+export {
+  ScormPlayer,
+  SupabaseAdapter,
+  parseManifest,
+  unpackSCORM
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "scorm-player",
+	"version": "1.0.0",
+	"description": "SCORM 2004 player module for Next.js and other frameworks, with backend unpacking and SCORM API support.",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup src/index.ts --format cjs,esm --dts --out-dir dist",
+		"clean": "rm -rf dist"
+	},
+	"keywords": [
+		"scorm",
+		"scorm2004",
+		"nextjs",
+		"react",
+		"player",
+		"elearning"
+	],
+	"author": "Shmelev Sergei",
+	"license": "MIT",
+	"dependencies": {
+		"@supabase/supabase-js": "^2.9.0",
+		"jszip": "^3.10.1"
+	},
+	"peerDependencies": {
+		"react": "^18.3.1",
+		"react-dom": "^18.3.1"
+	},
+	"devDependencies": {
+		"@types/react": "^18.3.27",
+		"@types/react-dom": "^18.3.7",
+		"tsup": "^7.3.0",
+		"typescript": "^5.2.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/shmelevsergei/scorm-player-2004.git"
+	},
+	"bugs": {
+		"url": "https://github.com/shmelevsergei/scorm-player-2004/issues"
+	},
+	"homepage": "https://github.com/shmelevsergei/scorm-player-2004#readme"
+}