@branchtrack/scorm-client 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2026 Philip Hutchison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,440 @@
+# scorm-client
+
+A modern, class-based JavaScript client for communicating with SCORM 1.2 and SCORM 2004 Learning Management Systems (LMS).
+
+> Based on the original [scorm-api-wrapper](https://github.com/pipwerks/scorm-api-wrapper) by Philip Hutchison.
+
+## Installation
+
+Install directly from GitHub:
+
+```bash
+npm install github:branchtrack/scorm-client
+```
+
+Or copy `dist/index.js` directly into your project.
+
+## Quick start
+
+```js
+import ScormClient from 'scorm-client';
+
+const client = new ScormClient();
+
+client.init();
+const saved = client.resume(); // restore previous session state
+client.score({ raw: 85, min: 0, max: 100 });
+client.status('completed');
+client.suspend({ page: 3 }); // persist state for next session
+client.save();
+client.quit();
+```
+
+## Constructor
+
+```js
+const client = new ScormClient(options);
+```
+
+| Option                   | Type                      | Default | Description                                                                                                                  |
+| ------------------------ | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `version`                | `'1.2' \| '2004' \| null` | `null`  | SCORM version to use. When `null`, the client auto-detects by looking for `window.API` (1.2) or `window.API_1484_11` (2004). |
+| `handleCompletionStatus` | `boolean`                 | `true`  | On `init()`, if the current status is `not attempted` (1.2) or `unknown` (2004), automatically sets it to `incomplete`.      |
+| `handleExitMode`         | `boolean`                 | `true`  | On `quit()`, automatically sets the exit CMI field to `suspend` (incomplete) or `logout`/`normal` (completed/passed).        |
+| `handleSessionTime`      | `boolean`                 | `true`  | On `quit()`, automatically computes elapsed session time and writes it to the appropriate CMI field before committing.       |
+| `debug`                  | `boolean`                 | `false` | Logs trace messages to `console.log`.                                                                                        |
+
+```js
+// Auto-detect version (recommended)
+const client = new ScormClient();
+
+// Pin to a specific version
+const client = new ScormClient({ version: '2004' });
+
+// Debug mode
+const client = new ScormClient({ debug: true });
+
+// All options
+const client = new ScormClient({
+  version: '1.2',
+  handleCompletionStatus: true,
+  handleExitMode: true,
+  handleSessionTime: true,
+  debug: false,
+});
+```
+
+## Properties
+
+| Property          | Type             | Description                                                                   |
+| ----------------- | ---------------- | ----------------------------------------------------------------------------- |
+| `client.version`  | `string \| null` | Detected or pre-set SCORM version (`'1.2'`, `'2004'`, or `null` before init). |
+| `client.isActive` | `boolean`        | Whether the LMS session is currently open.                                    |
+
+```js
+client.init();
+console.log(client.version); // '1.2' or '2004'
+console.log(client.isActive); // true
+```
+
+## Methods
+
+### `init()` → `boolean`
+
+Opens a communication session with the LMS. Returns `true` on success.
+
+Must be called before any data operations. Calling `init()` on an already-active connection returns `false` without making an LMS call.
+
+```js
+const ok = client.init();
+if (!ok) {
+  console.error('Could not connect to LMS');
+}
+```
+
+---
+
+### `quit()` → `boolean`
+
+Closes the LMS session. Returns `true` on success.
+
+When `handleExitMode` is enabled (default), automatically sets the exit field before terminating:
+
+| Completion status       | SCORM 1.2 `cmi.core.exit` | SCORM 2004 `cmi.exit` |
+| ----------------------- | ------------------------- | --------------------- |
+| `completed` or `passed` | `logout`                  | `normal`              |
+| anything else           | `suspend`                 | `suspend`             |
+
+When `handleSessionTime` is enabled (default), automatically computes the time elapsed since `init()` and writes it to the version-appropriate CMI field before the final commit:
+
+| Version    | Field                   | Format                | Example      |
+| ---------- | ----------------------- | --------------------- | ------------ |
+| SCORM 1.2  | `cmi.core.session_time` | `HH:MM:SS`            | `00:45:12`   |
+| SCORM 2004 | `cmi.session_time`      | ISO 8601 (`PTxHxMxS`) | `PT0H45M12S` |
+
+For SCORM 1.2, a `save()` is performed automatically before `LMSFinish`.
+
+```js
+client.quit();
+
+// Opt out of automatic session time reporting
+const client = new ScormClient({ handleSessionTime: false });
+```
+
+---
+
+### `get(parameter)` → `string`
+
+Retrieves a value from the LMS data model. Always returns a string (`"null"` if the connection is inactive).
+
+Parameters are automatically normalized — see [Field name shortcuts](#field-name-shortcuts) below.
+
+```js
+// Short keys (version-agnostic)
+const status = client.get('lesson_status');
+const score = client.get('score');
+const name = client.get('student_name');
+
+// Full CMI paths (passed through unchanged)
+const status = client.get('cmi.core.lesson_status'); // SCORM 1.2
+const status = client.get('cmi.completion_status'); // SCORM 2004
+```
+
+---
+
+### `set(parameter, value)` → `boolean`
+
+Writes a value to the LMS data model. Returns `true` on success.
+
+Parameters are automatically normalized — see [Field name shortcuts](#field-name-shortcuts) below.
+
+```js
+// Short keys (version-agnostic)
+client.set('score', '95');
+client.set('lesson_status', 'completed');
+client.set('success_status', 'passed'); // 2004 only
+
+// Full CMI paths (passed through unchanged)
+client.set('cmi.core.score.raw', '95'); // SCORM 1.2
+client.set('cmi.completion_status', 'completed'); // SCORM 2004
+```
+
+---
+
+### `save()` → `boolean`
+
+Persists all data to the LMS (calls `LMSCommit` / `Commit`). Returns `true` on success.
+
+Useful to checkpoint progress mid-session. For SCORM 1.2 this is required — `quit()` calls it automatically when `handleExitMode` is enabled.
+
+```js
+client.set('cmi.core.score.raw', '72');
+client.save(); // persist now, before the user navigates away
+```
+
+---
+
+### `status(value?)` → `string | boolean`
+
+Shortcut for reading or writing the version-appropriate completion status field.
+
+Internally maps to `cmi.core.lesson_status` (1.2) or `cmi.completion_status` (2004).
+
+`completion()` is an alias — both methods are identical.
+
+- Called with no argument → returns the current status string
+- Called with a string → sets the status, returns `true`/`false`
+
+```js
+const current = client.status(); // returns e.g. 'incomplete'
+client.status('completed');
+client.completion('completed'); // same as above
+```
+
+**Valid status values**
+
+| SCORM 1.2       | SCORM 2004      |
+| --------------- | --------------- |
+| `not attempted` | `not attempted` |
+| `incomplete`    | `incomplete`    |
+| `completed`     | `completed`     |
+| `passed`        | —               |
+| `failed`        | —               |
+| `browsed`       | —               |
+| —               | `unknown`       |
+
+---
+
+### `score(value?)` → `string | boolean`
+
+Shortcut for reading or writing score fields. Abstracts the version difference between `cmi.core.score.*` (1.2) and `cmi.score.*` (2004).
+
+- Called with no argument → returns the raw score string
+- Called with a number → sets `score.raw`, returns `true`/`false`
+- Called with an object → sets each present key (`raw`, `min`, `max`, `scaled`); `scaled` is silently ignored on SCORM 1.2
+
+```js
+const raw = client.score(); // get raw score
+client.score(85); // set raw score
+client.score({ raw: 85, min: 0, max: 100 }); // set multiple fields
+client.score({ raw: 85, min: 0, max: 100, scaled: 0.85 }); // 2004: also sets scaled
+```
+
+---
+
+### `suspend(data)` → `boolean`
+
+Serializes data and writes it to `cmi.suspend_data`. Strings are stored as-is; any other value is `JSON.stringify`'d first.
+
+```js
+client.suspend({ page: 3, answers: [1, 0, 2] }); // stored as JSON string
+client.suspend('raw string'); // stored as-is
+```
+
+---
+
+### `resume()` → `any | null`
+
+Reads `cmi.suspend_data` and attempts to parse it as JSON.
+
+- Returns `null` if the field is empty
+- Returns the parsed value if the content is valid JSON
+- Returns the raw string if JSON parsing fails
+
+```js
+client.suspend({ page: 3 });
+// ... later session ...
+const state = client.resume(); // → { page: 3 }
+```
+
+---
+
+### `location(value?)` → `string | boolean`
+
+Shortcut for reading or writing the learner's bookmark position.
+
+Maps to `cmi.core.lesson_location` (1.2) or `cmi.location` (2004).
+
+- Called with no argument → returns the current location string
+- Called with a string → sets the location, returns `true`/`false`
+
+```js
+const bookmark = client.location(); // get current position
+client.location('slide-12'); // save position
+```
+
+---
+
+### `success(value?)` → `string | boolean`
+
+Shortcut for reading or writing the version-appropriate success status field.
+
+Maps to `cmi.core.success_status` (1.2) or `cmi.success_status` (2004).
+
+- Called with no argument → returns the current value string (`'passed'`, `'failed'`, or `'unknown'`)
+- Called with `true` → sets `'passed'`
+- Called with `false` → sets `'failed'`
+- Called with a string → sets the value directly
+
+```js
+client.success(true); // sets 'passed'
+client.success(false); // sets 'failed'
+client.success('unknown'); // sets directly
+const result = client.success(); // → 'passed' / 'failed' / 'unknown'
+```
+
+---
+
+### `getLastError()` → `number`
+
+Returns the last LMS error code as an integer. Returns `0` if there is no error or the API is unavailable.
+
+```js
+const code = client.getLastError();
+if (code !== 0) {
+  console.error('LMS error code:', code);
+}
+```
+
+---
+
+### `getErrorInfo(errorCode)` → `string`
+
+Returns the human-readable description for a given error code.
+
+```js
+const code = client.getLastError();
+const info = client.getErrorInfo(code);
+console.error(info); // e.g. 'Invalid argument error'
+```
+
+---
+
+### `getDiagnosticInfo(errorCode)` → `string`
+
+Returns LMS-specific diagnostic details for a given error code. Content is LMS-defined.
+
+```js
+const code = client.getLastError();
+console.debug(client.getDiagnosticInfo(code));
+```
+
+---
+
+### `isAvailable()` → `true`
+
+Always returns `true`. Allows external runtimes to confirm the wrapper is loaded.
+
+---
+
+## Typical session lifecycle
+
+```js
+import ScormClient from 'scorm-client';
+
+const client = new ScormClient();
+
+// 1. Open session
+if (!client.init()) {
+  throw new Error('LMS connection failed');
+}
+
+// 2. Read learner data
+const studentName = client.get('student_name'); // cmi.core.student_name (1.2) / cmi.learner_name (2004)
+// or equivalently:
+const learnerName = client.get('learner_name'); // same result, both forms accepted
+
+// 3. Restore saved state
+const saved = client.resume(); // null on first launch, object on return
+
+// 4. Update progress
+client.set('score', '88'); // resolves per version
+
+// 5. Mark complete
+client.status('completed');
+
+// 6. Save bookmark and close
+client.location('slide-12');
+client.suspend({ page: 5, completed: true });
+client.save();
+client.quit();
+```
+
+## Field name shortcuts
+
+`get()` and `set()` accept short field names that are resolved to the correct CMI path for the active SCORM version. Pass a full `cmi.*` path to bypass normalization entirely.
+
+**Resolution rules (applied in order):**
+
+1. Key starts with `cmi.` → passed through unchanged
+2. Key matches an exception entry → use the mapped path
+3. Otherwise → prepend the default prefix (`cmi.core.` for 1.2, `cmi.` for 2004)
+
+**Exception mappings (keys that deviate from the default prefix):**
+
+| Short key         | SCORM 1.2                  | SCORM 2004              |
+| ----------------- | -------------------------- | ----------------------- |
+| `score`           | `cmi.core.score.raw`       | `cmi.score.raw`         |
+| `lesson_status`   | `cmi.core.lesson_status`   | `cmi.completion_status` |
+| `lesson_location` | `cmi.core.lesson_location` | `cmi.location`          |
+| `location`        | `cmi.core.lesson_location` | `cmi.location`          |
+| `suspend_data`    | `cmi.suspend_data`         | `cmi.suspend_data`      |
+
+**Cross-version learner identity aliases:**
+
+SCORM 1.2 uses `student_*` field names; SCORM 2004 uses `learner_*`. Both short forms are accepted in either version and resolve to the correct underlying field.
+
+| Short key      | SCORM 1.2               | SCORM 2004         |
+| -------------- | ----------------------- | ------------------ |
+| `learner_id`   | `cmi.core.student_id`   | `cmi.learner_id`   |
+| `learner_name` | `cmi.core.student_name` | `cmi.learner_name` |
+| `student_id`   | `cmi.core.student_id`   | `cmi.learner_id`   |
+| `student_name` | `cmi.core.student_name` | `cmi.learner_name` |
+
+**Default prefix examples (no exception needed):**
+
+```js
+client.get('success_status'); // → cmi.core.success_status (1.2) / cmi.success_status (2004)
+client.get('completion_threshold'); // → cmi.core.completion_threshold (1.2) / cmi.completion_threshold (2004)
+client.set('exit', 'suspend'); // → cmi.core.exit (1.2) / cmi.exit (2004)
+```
+
+---
+
+## SCORM 1.2 vs SCORM 2004 field reference
+
+| Concept           | SCORM 1.2                                    | SCORM 2004              |
+| ----------------- | -------------------------------------------- | ----------------------- |
+| Completion status | `cmi.core.lesson_status`                     | `cmi.completion_status` |
+| Success status    | `cmi.core.lesson_status` (`passed`/`failed`) | `cmi.success_status`    |
+| Score (raw)       | `cmi.core.score.raw`                         | `cmi.score.raw`         |
+| Score (min)       | `cmi.core.score.min`                         | `cmi.score.min`         |
+| Score (max)       | `cmi.core.score.max`                         | `cmi.score.max`         |
+| Session time      | `cmi.core.session_time`                      | `cmi.session_time`      |
+| Learner name      | `cmi.core.student_name`                      | `cmi.learner_name`      |
+| Learner ID        | `cmi.core.student_id`                        | `cmi.learner_id`        |
+| Exit              | `cmi.core.exit`                              | `cmi.exit`              |
+| Suspend data      | `cmi.suspend_data`                           | `cmi.suspend_data`      |
+
+## Browser support
+
+Built with Vite (Oxc) targeting ES2015+. Supports all modern browsers:
+
+- Last 2 Chrome versions
+- Last 2 Edge versions
+- Last 2 Firefox versions + Firefox ESR
+- Last 2 Safari versions
+- Last 2 iOS Safari versions
+
+## Development
+
+```bash
+npm install       # install dependencies
+npm run build     # compile + minify → dist/index.js
+npm test          # run tests (Vitest)
+npm run test:watch  # watch mode
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,154 @@
+import { formatSessionTime as e, normalizeField as t, stringToBoolean as n } from "./utils.js";
+//#region src/scorm_client.js
+var r = class {
+	#e;
+	#t;
+	#n;
+	#r;
+	#i;
+	#a;
+	#o;
+	#s;
+	#c;
+	#l;
+	#u;
+	constructor({ version: e = null, handleCompletionStatus: t = !0, handleExitMode: n = !0, handleSessionTime: r = !0, debug: i = !1 } = {}) {
+		this.#e = e, this.#t = t, this.#n = n, this.#r = r, this.#i = i, this.#a = null, this.#o = !1, this.#s = !1, this.#c = null, this.#l = null, this.#u = null;
+	}
+	get version() {
+		return this.#e;
+	}
+	get isActive() {
+		return this.#s;
+	}
+	isAvailable() {
+		return !0;
+	}
+	init() {
+		if (this.#s) return this.#m("connection.initialize aborted: Connection already active."), !1;
+		let e = this.#p();
+		if (!e) return this.#m("connection.initialize failed: API is null."), !1;
+		let t = this.#e === "1.2" ? n(e.LMSInitialize("")) : n(e.Initialize(""));
+		if (t) {
+			let e = this.getLastError();
+			if (e === 0) {
+				if (this.#s = !0, this.#u = Date.now(), this.#t) {
+					let e = this.status();
+					(e === "not attempted" || e === "unknown") && (this.status("incomplete"), this.save());
+				}
+			} else t = !1, this.#m(`connection.initialize failed. Error code: ${e} | Info: ${this.getErrorInfo(e)}`);
+		} else {
+			let e = this.getLastError();
+			this.#m(e && e !== 0 ? `connection.initialize failed. Error code: ${e} | Info: ${this.getErrorInfo(e)}` : "connection.initialize failed: No response from server.");
+		}
+		return t;
+	}
+	quit() {
+		if (!this.#s) return this.#m("connection.terminate aborted: Connection already terminated."), !1;
+		let t = this.#p();
+		if (!t) return this.#m("connection.terminate failed: API is null."), !1;
+		if (this.#n && !this.#l) {
+			let e = this.#c === "completed" || this.#c === "passed";
+			this.set("exit", e ? this.#e === "1.2" ? "logout" : "normal" : "suspend");
+		}
+		if (this.#r && this.#u) {
+			let t = Math.round((Date.now() - this.#u) / 1e3);
+			this.set("session_time", e(this.#e, t));
+		}
+		if (!(this.#e !== "1.2" || this.save())) return !1;
+		let r = this.#e === "1.2" ? n(t.LMSFinish("")) : n(t.Terminate(""));
+		if (r) this.#s = !1, this.#u = null;
+		else {
+			let e = this.getLastError();
+			this.#m(`connection.terminate failed. Error code: ${e} | Info: ${this.getErrorInfo(e)}`);
+		}
+		return r;
+	}
+	get(e) {
+		if (e = t(this.#e, e), !this.#s) return this.#m(`data.get('${e}') failed: API connection is inactive.`), "null";
+		let n = this.#p();
+		if (!n) return this.#m(`data.get('${e}') failed: API is null.`), "null";
+		let r = this.#e === "1.2" ? n.LMSGetValue(e) : n.GetValue(e), i = this.getLastError();
+		return r !== "" || i === 0 ? ((e === "cmi.core.lesson_status" || e === "cmi.completion_status") && (this.#c = r), (e === "cmi.core.exit" || e === "cmi.exit") && (this.#l = r)) : this.#m(`data.get('${e}') failed. Error code: ${i} | Info: ${this.getErrorInfo(i)}`), String(r);
+	}
+	set(e, r) {
+		if (e = t(this.#e, e), !this.#s) return this.#m(`data.set('${e}') failed: API connection is inactive.`), !1;
+		let i = this.#p();
+		if (!i) return this.#m(`data.set('${e}') failed: API is null.`), !1;
+		let a = this.#e === "1.2" ? n(i.LMSSetValue(e, r)) : n(i.SetValue(e, r));
+		if (a) (e === "cmi.core.lesson_status" || e === "cmi.completion_status") && (this.#c = r);
+		else {
+			let t = this.getLastError();
+			this.#m(`data.set('${e}') failed. Error code: ${t} | Info: ${this.getErrorInfo(t)}`);
+		}
+		return a;
+	}
+	save() {
+		if (!this.#s) return this.#m("data.save failed: API connection is inactive."), !1;
+		let e = this.#p();
+		return e ? this.#e === "1.2" ? n(e.LMSCommit("")) : n(e.Commit("")) : (this.#m("data.save failed: API is null."), !1);
+	}
+	status(e) {
+		return e === void 0 ? this.get("lesson_status") : e ? this.set("lesson_status", e) : (this.#m("status failed: status value was not specified."), !1);
+	}
+	completion(e) {
+		return this.status(e);
+	}
+	success(e) {
+		return e === void 0 ? this.get("success_status") : e === !0 ? this.set("success_status", "passed") : e === !1 ? this.set("success_status", "failed") : this.set("success_status", e);
+	}
+	location(e) {
+		return e === void 0 ? this.get("location") : this.set("location", e);
+	}
+	score(e) {
+		if (e === void 0) return this.get("score");
+		if (typeof e == "number") return this.set("score", String(e));
+		if (typeof e == "object" && e) {
+			let t = !0;
+			return e.raw !== void 0 && (t = this.set("score.raw", String(e.raw)) && t), e.min !== void 0 && (t = this.set("score.min", String(e.min)) && t), e.max !== void 0 && (t = this.set("score.max", String(e.max)) && t), e.scaled !== void 0 && this.#e === "2004" && (t = this.set("score.scaled", String(e.scaled)) && t), t;
+		}
+		return this.#m("score failed: invalid value type."), !1;
+	}
+	suspend(e) {
+		let t = typeof e == "string" ? e : JSON.stringify(e);
+		return this.set("suspend_data", t);
+	}
+	resume() {
+		let e = this.get("suspend_data");
+		if (!e || e === "null") return null;
+		try {
+			return JSON.parse(e);
+		} catch {
+			return e;
+		}
+	}
+	getLastError() {
+		let e = this.#p();
+		return e ? this.#e === "1.2" ? parseInt(e.LMSGetLastError(), 10) : parseInt(e.GetLastError(), 10) : (this.#m("getLastError failed: API is null."), 0);
+	}
+	getErrorInfo(e) {
+		let t = this.#p();
+		return t ? String(this.#e === "1.2" ? t.LMSGetErrorString(String(e)) : t.GetErrorString(String(e))) : (this.#m("getErrorInfo failed: API is null."), "");
+	}
+	getDiagnosticInfo(e) {
+		let t = this.#p();
+		return t ? String(this.#e === "1.2" ? t.LMSGetDiagnostic(e) : t.GetDiagnostic(e)) : (this.#m("getDiagnosticInfo failed: API is null."), "");
+	}
+	#d(e) {
+		let t = 0;
+		for (; !e.API && !e.API_1484_11 && e.parent && e.parent !== e && t <= 500;) t++, e = e.parent;
+		return this.#e ? this.#e === "2004" ? e.API_1484_11 ?? null : this.#e === "1.2" ? e.API ?? null : null : e.API_1484_11 ? (this.#e = "2004", e.API_1484_11) : e.API ? (this.#e = "1.2", e.API) : (this.#m(`API.find: no API found after ${t} attempts.`), null);
+	}
+	#f() {
+		let e = this.#d(window);
+		return !e && window.parent && window.parent !== window && (e = this.#d(window.parent)), !e && window.top?.opener && (e = this.#d(window.top.opener)), !e && window.top?.opener?.document && (e = this.#d(window.top.opener.document)), e ? this.#o = !0 : this.#m("API.get: Can't find the API!"), e;
+	}
+	#p() {
+		return !this.#a && !this.#o && (this.#a = this.#f()), this.#a;
+	}
+	#m(e) {
+		this.#i && window.console?.log && window.console.log(e);
+	}
+};
+//#endregion
+export { r as ScormClient, r as default };

package/dist/utils.js

@@ -0,0 +1,41 @@
+//#region src/utils.js
+function e(e, t) {
+	if (t.startsWith("cmi.")) return t;
+	let n = {
+		"1.2": {
+			suspend_data: "cmi.suspend_data",
+			score: "cmi.core.score.raw",
+			location: "cmi.core.lesson_location",
+			learner_id: "cmi.core.student_id",
+			learner_name: "cmi.core.student_name"
+		},
+		2004: {
+			score: "cmi.score.raw",
+			lesson_status: "cmi.completion_status",
+			lesson_location: "cmi.location",
+			student_id: "cmi.learner_id",
+			student_name: "cmi.learner_name"
+		}
+	}[e] ?? {};
+	return t in n ? n[t] : (e === "1.2" ? "cmi.core." : "cmi.") + t;
+}
+function t(e) {
+	switch (typeof e) {
+		case "object":
+		case "string": return /(true|1)/i.test(e);
+		case "number": return !!e;
+		case "boolean": return e;
+		case "undefined": return null;
+		default: return !1;
+	}
+}
+function n(e, t) {
+	let n = Math.floor(t / 3600), r = Math.floor(t % 3600 / 60), i = t % 60;
+	return e === "1.2" ? [
+		n,
+		r,
+		i
+	].map((e) => String(e).padStart(2, "0")).join(":") : `PT${n}H${r}M${i}S`;
+}
+//#endregion
+export { n as formatSessionTime, e as normalizeField, t as stringToBoolean };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@branchtrack/scorm-client",
+  "version": "1.0.0-beta.1",
+  "description": "The SCORM API Client",
+  "keywords": [
+    "SCORM",
+    "elearning",
+    "lms"
+  ],
+  "homepage": "https://github.com/branchtrack/scorm-client",
+  "bugs": {
+    "url": "https://github.com/branchtrack/scorm-client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/branchtrack/scorm-client.git"
+  },
+  "license": "MIT",
+  "author": "Sergey Margaritov (attenzione)",
+  "contributors": [
+    {
+      "name": "Philip Hutchison (pipwerks)",
+      "url": "https://github.com/pipwerks/scorm-api-wrapper"
+    }
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./utils": "./dist/utils.js"
+  },
+  "main": "dist/index.js",
+  "directories": {
+    "test": "tests"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vite build --config vite.config.build.js",
+    "prepublishOnly": "npm run build",
+    "release": "release-it",
+    "release:major": "release-it major",
+    "release:minor": "release-it minor",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "browserslist-to-esbuild": "^2.1.1",
+    "chai": "^6.2.2",
+    "jsdom": "^29.0.1",
+    "release-it": "^19.2.4",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/scorm_client.js

@@ -0,0 +1,482 @@
+import { normalizeField, stringToBoolean, formatSessionTime } from './utils.js';
+
+/*
+  ScormClient — modern class-based SCORM 1.2 / 2004 API wrapper
+  Replaces the pipwerks singleton with a proper instantiable client.
+
+  Usage:
+    import ScormClient from 'scorm-client';
+
+    const client = new ScormClient();
+    // or pre-set the version and options:
+    const client = new ScormClient({ version: '1.2', debug: true });
+
+    client.init();
+    client.set('cmi.core.score.raw', '95');
+    client.quit();
+*/
+
+export class ScormClient {
+  // Private state
+  #version;
+  #handleCompletionStatus;
+  #handleExitMode;
+  #handleSessionTime;
+  #debugActive;
+  #apiHandle;
+  #apiFound;
+  #connectionActive;
+  #completionStatus;
+  #exitStatus;
+  #sessionStartTime;
+
+  /**
+   * @param {object}      [options]
+   * @param {string|null} [options.version]                - Pre-set SCORM version ('1.2' or '2004'). Auto-detected when null.
+   * @param {boolean}     [options.handleCompletionStatus] - Automatically set 'incomplete' on first launch (default: true).
+   * @param {boolean}     [options.handleExitMode]         - Automatically set exit mode on terminate (default: true).
+   * @param {boolean}     [options.handleSessionTime]      - Automatically write session time on quit (default: true).
+   * @param {boolean}     [options.debug]                  - Enable console trace logging (default: false).
+   */
+  constructor({ version = null, handleCompletionStatus = true, handleExitMode = true, handleSessionTime = true, debug = false } = {}) {
+    this.#version = version;
+    this.#handleCompletionStatus = handleCompletionStatus;
+    this.#handleExitMode = handleExitMode;
+    this.#handleSessionTime = handleSessionTime;
+    this.#debugActive = debug;
+    this.#apiHandle = null;
+    this.#apiFound = false;
+    this.#connectionActive = false;
+    this.#completionStatus = null;
+    this.#exitStatus = null;
+    this.#sessionStartTime = null;
+  }
+
+  // ── Public read-only accessors ──────────────────────────────────────────── //
+
+  get version() { return this.#version; }
+  get isActive() { return this.#connectionActive; }
+
+  /** Allows Flash / other runtimes to confirm the wrapper is present. */
+  isAvailable() { return true; }
+
+  // ── Connection ───────────────────────────────────────────────────────────── //
+
+  /** Initialize the LMS session. Returns true on success. */
+  init() {
+    if (this.#connectionActive) {
+      this.#trace('connection.initialize aborted: Connection already active.');
+      return false;
+    }
+
+    const api = this.#getApiHandle();
+    if (!api) {
+      this.#trace('connection.initialize failed: API is null.');
+      return false;
+    }
+
+    let success =
+      this.#version === '1.2'
+        ? stringToBoolean(api.LMSInitialize(''))
+        : stringToBoolean(api.Initialize(''));
+
+    if (success) {
+      const errorCode = this.getLastError();
+      if (errorCode === 0) {
+        this.#connectionActive = true;
+        this.#sessionStartTime = Date.now();
+
+        if (this.#handleCompletionStatus) {
+          const currentStatus = this.status();
+          if (currentStatus === 'not attempted' || currentStatus === 'unknown') {
+            this.status('incomplete');
+            this.save();
+          }
+        }
+      } else {
+        success = false;
+        this.#trace(`connection.initialize failed. Error code: ${errorCode} | Info: ${this.getErrorInfo(errorCode)}`);
+      }
+    } else {
+      const errorCode = this.getLastError();
+      this.#trace(
+        errorCode && errorCode !== 0
+          ? `connection.initialize failed. Error code: ${errorCode} | Info: ${this.getErrorInfo(errorCode)}`
+          : 'connection.initialize failed: No response from server.'
+      );
+    }
+
+    return success;
+  }
+
+  /** Terminate the LMS session. Returns true on success. */
+  quit() {
+    if (!this.#connectionActive) {
+      this.#trace('connection.terminate aborted: Connection already terminated.');
+      return false;
+    }
+
+    const api = this.#getApiHandle();
+    if (!api) {
+      this.#trace('connection.terminate failed: API is null.');
+      return false;
+    }
+
+    if (this.#handleExitMode && !this.#exitStatus) {
+      const finished = this.#completionStatus === 'completed' || this.#completionStatus === 'passed';
+      this.set('exit', finished ? (this.#version === '1.2' ? 'logout' : 'normal') : 'suspend');
+    }
+
+    // Write session time before committing.
+    if (this.#handleSessionTime && this.#sessionStartTime) {
+      const elapsedSeconds = Math.round((Date.now() - this.#sessionStartTime) / 1000);
+      this.set('session_time', formatSessionTime(this.#version, elapsedSeconds));
+    }
+
+    // SCORM 1.2 requires an explicit commit before LMSFinish; 2004 commits implicitly on Terminate.
+    const saved = this.#version === '1.2' ? this.save() : true;
+    if (!saved) return false;
+
+    const success =
+      this.#version === '1.2'
+        ? stringToBoolean(api.LMSFinish(''))
+        : stringToBoolean(api.Terminate(''));
+
+    if (success) {
+      this.#connectionActive = false;
+      this.#sessionStartTime = null;
+    } else {
+      const errorCode = this.getLastError();
+      this.#trace(`connection.terminate failed. Error code: ${errorCode} | Info: ${this.getErrorInfo(errorCode)}`);
+    }
+
+    return success;
+  }
+
+  // ── Data ─────────────────────────────────────────────────────────────────── //
+
+  /** Get a SCORM data model value. Returns a string. */
+  get(parameter) {
+    parameter = normalizeField(this.#version, parameter);
+
+    if (!this.#connectionActive) {
+      this.#trace(`data.get('${parameter}') failed: API connection is inactive.`);
+      return String(null);
+    }
+
+    const api = this.#getApiHandle();
+    if (!api) {
+      this.#trace(`data.get('${parameter}') failed: API is null.`);
+      return String(null);
+    }
+
+    const value =
+      this.#version === '1.2'
+        ? api.LMSGetValue(parameter)
+        : api.GetValue(parameter);
+
+    const errorCode = this.getLastError();
+    if (value !== '' || errorCode === 0) {
+      if (parameter === 'cmi.core.lesson_status' || parameter === 'cmi.completion_status') {
+        this.#completionStatus = value;
+      }
+      if (parameter === 'cmi.core.exit' || parameter === 'cmi.exit') {
+        this.#exitStatus = value;
+      }
+    } else {
+      this.#trace(`data.get('${parameter}') failed. Error code: ${errorCode} | Info: ${this.getErrorInfo(errorCode)}`);
+    }
+
+    return String(value);
+  }
+
+  /** Set a SCORM data model value. Returns true on success. */
+  set(parameter, value) {
+    parameter = normalizeField(this.#version, parameter);
+
+    if (!this.#connectionActive) {
+      this.#trace(`data.set('${parameter}') failed: API connection is inactive.`);
+      return false;
+    }
+
+    const api = this.#getApiHandle();
+    if (!api) {
+      this.#trace(`data.set('${parameter}') failed: API is null.`);
+      return false;
+    }
+
+    const success =
+      this.#version === '1.2'
+        ? stringToBoolean(api.LMSSetValue(parameter, value))
+        : stringToBoolean(api.SetValue(parameter, value));
+
+    if (success) {
+      if (parameter === 'cmi.core.lesson_status' || parameter === 'cmi.completion_status') {
+        this.#completionStatus = value;
+      }
+    } else {
+      const errorCode = this.getLastError();
+      this.#trace(`data.set('${parameter}') failed. Error code: ${errorCode} | Info: ${this.getErrorInfo(errorCode)}`);
+    }
+
+    return success;
+  }
+
+  /** Persist all data to the LMS. Returns true on success. */
+  save() {
+    if (!this.#connectionActive) {
+      this.#trace('data.save failed: API connection is inactive.');
+      return false;
+    }
+
+    const api = this.#getApiHandle();
+    if (!api) {
+      this.#trace('data.save failed: API is null.');
+      return false;
+    }
+
+    return this.#version === '1.2'
+      ? stringToBoolean(api.LMSCommit(''))
+      : stringToBoolean(api.Commit(''));
+  }
+
+  // ── Status shortcut ──────────────────────────────────────────────────────── //
+
+  /**
+   * Get or set the SCORM completion status.
+   * @param {'get'|'set'} action
+   * @param {string} [value] - Required when action is 'set'.
+   */
+  status(value) {
+    if (value === undefined) return this.get('lesson_status');
+
+    if (!value) {
+      this.#trace('status failed: status value was not specified.');
+      return false;
+    }
+
+    return this.set('lesson_status', value);
+  }
+
+  /** Alias for {@link status}. */
+  completion(value) { return this.status(value); }
+
+  // ── Success shortcut ─────────────────────────────────────────────────────── //
+
+  /**
+   * Get or set the SCORM success status.
+   * Maps to cmi.core.success_status (1.2) or cmi.success_status (2004).
+   *
+   * - Called with no argument → returns the current value string
+   * - Called with true/false  → sets 'passed' / 'failed'
+   * - Called with a string    → sets the value directly
+   *
+   * @param {boolean|string} [value]
+   * @returns {string|boolean}
+   */
+  success(value) {
+    if (value === undefined) return this.get('success_status');
+    if (value === true)  return this.set('success_status', 'passed');
+    if (value === false) return this.set('success_status', 'failed');
+
+    return this.set('success_status', value);
+  }
+
+  // ── Location shortcut ────────────────────────────────────────────────────── //
+
+  /**
+   * Get or set the learner's bookmark location.
+   * Maps to cmi.core.lesson_location (1.2) or cmi.location (2004).
+   * @param {string} [value]
+   * @returns {string|boolean}
+   */
+  location(value) {
+    if (value === undefined) return this.get('location');
+
+    return this.set('location', value);
+  }
+
+  // ── Score shortcut ──────────────────────────────────────────────────────── //
+
+  /**
+   * Get or set SCORM score fields.
+   *
+   * @overload
+   * @returns {string} Raw score value.
+   *
+   * @overload
+   * @param {number} value - Sets score.raw.
+   * @returns {boolean}
+   *
+   * @overload
+   * @param {{ raw?: number, min?: number, max?: number, scaled?: number }} value
+   *   Sets each present key. `scaled` is silently ignored on SCORM 1.2.
+   * @returns {boolean}
+   */
+  score(value) {
+    if (value === undefined) {
+      return this.get('score');
+    }
+
+    if (typeof value === 'number') {
+      return this.set('score', String(value));
+    }
+
+    if (typeof value === 'object' && value !== null) {
+      let success = true;
+      if (value.raw !== undefined) success = this.set('score.raw', String(value.raw)) && success;
+      if (value.min !== undefined) success = this.set('score.min', String(value.min)) && success;
+      if (value.max !== undefined) success = this.set('score.max', String(value.max)) && success;
+      if (value.scaled !== undefined && this.#version === '2004') {
+        success = this.set('score.scaled', String(value.scaled)) && success;
+      }
+      return success;
+    }
+
+    this.#trace('score failed: invalid value type.');
+
+    return false;
+  }
+
+  // ── Suspend data helpers ─────────────────────────────────────────────────── //
+
+  /**
+   * Serialize and store data in cmi.suspend_data.
+   * @param {string|object} data - String stored as-is; anything else is JSON.stringify'd.
+   * @returns {boolean}
+   */
+  suspend(data) {
+    const raw = typeof data === 'string' ? data : JSON.stringify(data);
+
+    return this.set('suspend_data', raw);
+  }
+
+  /**
+   * Retrieve and deserialize cmi.suspend_data.
+   * @returns {any|null} Parsed JSON if possible, raw string if not, null if empty.
+   */
+  resume() {
+    const raw = this.get('suspend_data');
+
+    if (!raw || raw === 'null') return null;
+
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+
+  // ── Debug ────────────────────────────────────────────────────────────────── //
+
+  /** Returns the last LMS error code as an integer. */
+  getLastError() {
+    const api = this.#getApiHandle();
+    if (!api) {
+      this.#trace('getLastError failed: API is null.');
+      return 0;
+    }
+
+    return this.#version === '1.2'
+      ? parseInt(api.LMSGetLastError(), 10)
+      : parseInt(api.GetLastError(), 10);
+  }
+
+  /** Returns the error string for a given error code. */
+  getErrorInfo(errorCode) {
+    const api = this.#getApiHandle();
+    if (!api) {
+      this.#trace('getErrorInfo failed: API is null.');
+      return '';
+    }
+
+    return String(
+      this.#version === '1.2'
+        ? api.LMSGetErrorString(String(errorCode))
+        : api.GetErrorString(String(errorCode))
+    );
+  }
+
+  /** Returns LMS-specific diagnostic info for a given error code. */
+  getDiagnosticInfo(errorCode) {
+    const api = this.#getApiHandle();
+    if (!api) {
+      this.#trace('getDiagnosticInfo failed: API is null.');
+      return '';
+    }
+
+    return String(
+      this.#version === '1.2'
+        ? api.LMSGetDiagnostic(errorCode)
+        : api.GetDiagnostic(errorCode)
+    );
+  }
+
+  // ── Private: API discovery ───────────────────────────────────────────────── //
+
+  #findApi(win) {
+    let attempts = 0;
+    const limit = 500;
+
+    while (
+      !win.API && !win.API_1484_11 &&
+      win.parent && win.parent !== win &&
+      attempts <= limit
+    ) {
+      attempts++;
+      win = win.parent;
+    }
+
+    if (this.#version) {
+      if (this.#version === '2004') return win.API_1484_11 ?? null;
+      if (this.#version === '1.2')  return win.API ?? null;
+      return null;
+    }
+
+    if (win.API_1484_11) { this.#version = '2004'; return win.API_1484_11; }
+    if (win.API)         { this.#version = '1.2';  return win.API; }
+
+    this.#trace(`API.find: no API found after ${attempts} attempts.`);
+
+    return null;
+  }
+
+  #getApi() {
+    let api = this.#findApi(window);
+
+    if (!api && window.parent && window.parent !== window) {
+      api = this.#findApi(window.parent);
+    }
+    if (!api && window.top?.opener) {
+      api = this.#findApi(window.top.opener);
+    }
+    if (!api && window.top?.opener?.document) {
+      api = this.#findApi(window.top.opener.document);
+    }
+
+    if (api) {
+      this.#apiFound = true;
+    } else {
+      this.#trace("API.get: Can't find the API!");
+    }
+
+    return api;
+  }
+
+  #getApiHandle() {
+    if (!this.#apiHandle && !this.#apiFound) {
+      this.#apiHandle = this.#getApi();
+    }
+    return this.#apiHandle;
+  }
+
+
+
+  #trace(msg) {
+    if (this.#debugActive && window.console?.log) {
+      window.console.log(msg);
+    }
+  }
+}
+
+export default ScormClient;

package/src/utils.js

@@ -0,0 +1,82 @@
+// ── Field normalisation ───────────────────────────────────────────────────── //
+
+/**
+ * Resolve a short field name (e.g. 'score', 'lesson_status') to its full
+ * CMI path for the given SCORM version.
+ *
+ * Rules:
+ *  - If key already starts with 'cmi.' it is returned unchanged.
+ *  - A small exceptions map covers fields that deviate from the default prefix.
+ *  - Everything else gets the default prefix: 'cmi.core.' for 1.2, 'cmi.' for 2004.
+ *
+ * @param {string} version - '1.2' or '2004'
+ * @param {string} key
+ * @returns {string}
+ */
+export function normalizeField(version, key) {
+  if (key.startsWith('cmi.')) return key;
+
+  const exceptions = {
+    '1.2': {
+      suspend_data:    'cmi.suspend_data',
+      score:           'cmi.core.score.raw',
+      location:        'cmi.core.lesson_location',
+      learner_id:      'cmi.core.student_id',
+      learner_name:    'cmi.core.student_name',
+    },
+    '2004': {
+      score:           'cmi.score.raw',
+      lesson_status:   'cmi.completion_status',
+      lesson_location: 'cmi.location',
+      student_id:      'cmi.learner_id',
+      student_name:    'cmi.learner_name',
+    },
+  };
+
+  const map = exceptions[version] ?? {};
+  if (key in map) return map[key];
+
+  const prefix = version === '1.2' ? 'cmi.core.' : 'cmi.';
+  return prefix + key;
+}
+
+// ── Type coercion ─────────────────────────────────────────────────────────── //
+
+/**
+ * Convert various LMS response types to a boolean.
+ *
+ * @param {*} value
+ * @returns {boolean|null}
+ */
+export function stringToBoolean(value) {
+  switch (typeof value) {
+    case 'object':
+    case 'string':  return /(true|1)/i.test(value);
+    case 'number':  return !!value;
+    case 'boolean': return value;
+    case 'undefined': return null;
+    default: return false;
+  }
+}
+
+// ── Session time formatting ───────────────────────────────────────────────── //
+
+/**
+ * Format elapsed seconds as a SCORM session time string.
+ *
+ * - SCORM 1.2  → HH:MM:SS
+ * - SCORM 2004 → PTxHxMxS
+ *
+ * @param {string} version - '1.2' or '2004'
+ * @param {number} totalSeconds
+ * @returns {string}
+ */
+export function formatSessionTime(version, totalSeconds) {
+  const h = Math.floor(totalSeconds / 3600);
+  const m = Math.floor((totalSeconds % 3600) / 60);
+  const s = totalSeconds % 60;
+  if (version === '1.2') {
+    return [h, m, s].map(v => String(v).padStart(2, '0')).join(':');
+  }
+  return `PT${h}H${m}M${s}S`;
+}