scorm-again 3.0.4 → 3.1.0

package/dist/types/BaseAPI.d.ts

@@ -1,7 +1,7 @@
 import { StringKeyMap } from "./utilities";
 import { BaseCMI } from "./cmi/common/base_cmi";
 import { ErrorCode } from "./constants";
-import { CommitObject, InternalSettings, LogLevel, ResultObject, Settings } from "./types";
+import { CommitEventContext, CommitObject, CommitTrigger, InternalSettings, LogLevel, ResultObject, Settings } from "./types";
 import { IBaseAPI, ICMIDataService, IErrorHandlingService, IEventService, IHttpService, ILoggingService, IOfflineStorageService, ISerializationService, ScormEventCallback } from "./interfaces";
 export default abstract class BaseAPI implements IBaseAPI {
     private _timeout?;
@@ -15,6 +15,10 @@ export default abstract class BaseAPI implements IBaseAPI {
     private readonly _offlineStorageService?;
     private readonly _cmiValueAccessService;
     private _courseId;
+    private _pendingCommitCount;
+    private _commitSequence;
+    private readonly _commitSettleWaiters;
+    protected readonly _setCMIElements: Set<string>;
     protected constructor(error_codes: ErrorCode, settings?: Settings, httpService?: IHttpService, eventService?: IEventService, serializationService?: ISerializationService, cmiDataService?: ICMIDataService, errorHandlingService?: IErrorHandlingService, loggingService?: ILoggingService, offlineStorageService?: IOfflineStorageService);
     abstract cmi: BaseCMI;
     startingData?: StringKeyMap;
@@ -36,16 +40,21 @@ export default abstract class BaseAPI implements IBaseAPI {
     abstract lmsGetDiagnostic(CMIErrorCode: string | number): string;
     abstract validateCorrectResponse(_CMIElement: string, _value: any): void;
     abstract getChildElement(_CMIElement: string, _value: any, _foundFirstIndex: boolean): BaseCMI | null;
-    abstract storeData(_calculateTotalTime: boolean): ResultObject;
+    abstract storeData(_calculateTotalTime: boolean, _trigger?: CommitTrigger): ResultObject;
     abstract renderCommitCMI(_terminateCommit: boolean, _includeTotalTime?: boolean): StringKeyMap | Array<string>;
     abstract renderCommitObject(_terminateCommit: boolean, _includeTotalTime?: boolean): CommitObject;
     apiLog(functionName: string, logMessage: string, messageLevel: LogLevel, CMIElement?: string): void;
     get settings(): InternalSettings;
     set settings(settings: Settings);
+    get pendingCommitCount(): number;
+    whenCommitsSettled(options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    private _flushCommitSettleWaiters;
     terminate(callbackName: string, checkTerminated: boolean): string;
     getValue(callbackName: string, checkTerminated: boolean, CMIElement: string): string;
     setValue(callbackName: string, commitCallback: string, checkTerminated: boolean, CMIElement: string, value: any): string;
-    commit(callbackName: string, checkTerminated?: boolean): string;
+    commit(callbackName: string, checkTerminated?: boolean, trigger?: CommitTrigger): string;
     getLastError(callbackName: string): string;
     getErrorString(callbackName: string, CMIErrorCode: string | number): string;
     getDiagnostic(callbackName: string, CMIErrorCode: string | number): string;
@@ -56,13 +65,14 @@ export default abstract class BaseAPI implements IBaseAPI {
     setCMIValue(_CMIElement: string, _value: any): string;
     _commonSetCMIValue(methodName: string, scorm2004: boolean, CMIElement: string, value: any): string;
     _commonGetCMIValue(methodName: string, scorm2004: boolean, CMIElement: string): any;
+    protected checkUninitializedGet(_CMIElement: string, _returnValue: any): void;
     isInitialized(): boolean;
     isNotInitialized(): boolean;
     isTerminated(): boolean;
     on(listenerName: string, callback: ScormEventCallback): void;
     off(listenerName: string, callback: ScormEventCallback): void;
     clear(listenerName: string): void;
-    processListeners(functionName: string, CMIElement?: string, value?: any): void;
+    processListeners(functionName: string, CMIElement?: string, value?: any, context?: CommitEventContext): void;
     throwSCORMError(CMIElement: string | undefined, errorNumber: number | undefined, message?: string): void;
     clearSCORMError(success: string): void;
     loadFromFlattenedJSON(json: StringKeyMap, CMIElement?: string): void;
@@ -70,7 +80,7 @@ export default abstract class BaseAPI implements IBaseAPI {
     loadFromJSON(json: StringKeyMap, CMIElement?: string): void;
     renderCMIToJSONString(): string;
     renderCMIToJSONObject(): StringKeyMap;
-    processHttpRequest(url: string, params: CommitObject | StringKeyMap | Array<any>, immediate?: boolean): ResultObject;
+    processHttpRequest(url: string, params: CommitObject | StringKeyMap | Array<any>, immediate?: boolean, trigger?: CommitTrigger): ResultObject;
     scheduleCommit(when: number, callback: string): void;
     clearScheduledCommit(): void;
     private _checkObjectHasProperty;

package/dist/types/Scorm12API.d.ts

@@ -3,7 +3,7 @@ import { StringKeyMap } from "./utilities";
 import { BaseCMI } from "./cmi/common/base_cmi";
 import { CMI } from "./cmi/scorm12/cmi";
 import { NAV } from "./cmi/scorm12/nav";
-import { CommitObject, ResultObject, Settings } from "./types";
+import { CommitObject, CommitTrigger, ResultObject, Settings } from "./types";
 import { IHttpService } from "./interfaces";
 declare class Scorm12API extends BaseAPI {
     private static _globalLearnerPrefs;
@@ -38,7 +38,7 @@ declare class Scorm12API extends BaseAPI {
     replaceWithAnotherScormAPI(newAPI: Scorm12API): void;
     renderCommitCMI(terminateCommit: boolean, includeTotalTime?: boolean): StringKeyMap | Array<string>;
     renderCommitObject(terminateCommit: boolean, includeTotalTime?: boolean): CommitObject;
-    storeData(terminateCommit: boolean): ResultObject;
+    storeData(terminateCommit: boolean, trigger?: CommitTrigger): ResultObject;
     private processCommitData;
 }
 export default Scorm12API;

package/dist/types/Scorm2004API.d.ts

@@ -4,7 +4,7 @@ import { BaseCMI } from "./cmi/common/base_cmi";
 import { CMI } from "./cmi/scorm2004/cmi";
 import { CMIObjectivesObject } from "./cmi/scorm2004/objectives";
 import { ADL } from "./cmi/scorm2004/adl";
-import { CommitObject, ResultObject, SequencingStateMetadata, Settings } from "./types";
+import { CommitObject, CommitTrigger, ResultObject, SequencingStateMetadata, Settings } from "./types";
 import { IHttpService } from "./interfaces";
 import { SequencingConfiguration, SequencingEventListeners, SequencingService } from "./services";
 declare class Scorm2004API extends BaseAPI {
@@ -51,11 +51,12 @@ declare class Scorm2004API extends BaseAPI {
     validateCorrectResponse(CMIElement: string, value: any): void;
     private _peekCMIValue;
     getCMIValue(CMIElement: string): any;
+    protected checkUninitializedGet(CMIElement: string, returnValue: any): void;
     getLmsErrorMessageDetails(errorNumber: string | number, detail: boolean): string;
     replaceWithAnotherScormAPI(newAPI: Scorm2004API): void;
     renderCommitCMI(terminateCommit: boolean, includeTotalTime?: boolean): StringKeyMap | Array<any>;
     renderCommitObject(terminateCommit: boolean, includeTotalTime?: boolean): CommitObject;
-    storeData(terminateCommit: boolean): ResultObject;
+    storeData(terminateCommit: boolean, trigger?: CommitTrigger): ResultObject;
     private configureSequencing;
     private configureActivityTree;
     private configureSequencingRules;

package/dist/types/cmi/common/score.d.ts

@@ -9,6 +9,7 @@ export declare class CMIScore extends BaseCMI {
     private readonly __invalid_range_code;
     private readonly __decimal_regex;
     private readonly __error_class;
+    private readonly __allow_empty_string;
     protected _raw: string;
     protected _min: string;
     protected _max: string;
@@ -22,6 +23,7 @@ export declare class CMIScore extends BaseCMI {
         invalidRangeCode?: number;
         decimalRegex?: string;
         errorClass: typeof BaseScormValidationError;
+        allowEmptyString?: boolean;
     });
     reset(): void;
     get _children(): string;

package/dist/types/cmi/scorm2004/interaction_delimiters.d.ts

@@ -0,0 +1,4 @@
+export declare function stripBrackets(delim: string): string;
+export declare function splitDelimited(value: string, bracketed: string): string[];
+export declare function splitFirstDelimited(value: string, bracketed: string): string[];
+//# sourceMappingURL=interaction_delimiters.d.ts.map

package/dist/types/interfaces/services.d.ts

@@ -1,11 +1,12 @@
-import { CommitObject, LogLevel, ResultObject, Settings } from "../types/api_types";
+import { CommitEventContext, CommitMetadata, CommitObject, LogLevel, ResultObject, Settings } from "../types/api_types";
 import { ErrorCode } from "../constants/error_codes";
 import { LogLevelEnum } from "../constants/enums";
 import { BaseCMI } from "../cmi/common/base_cmi";
 import { ValidationError } from "../exceptions";
 import { StringKeyMap } from "../utilities";
 export interface IHttpService {
-    processHttpRequest(url: string, params: CommitObject | StringKeyMap | Array<any>, immediate: boolean, apiLog: (functionName: string, message: any, messageLevel: LogLevelEnum, CMIElement?: string) => void, processListeners: (functionName: string, CMIElement?: string, value?: any) => void): ResultObject;
+    readonly reportsRequestCompletion?: boolean;
+    processHttpRequest(url: string, params: CommitObject | StringKeyMap | Array<any>, immediate: boolean, apiLog: (functionName: string, message: any, messageLevel: LogLevelEnum, CMIElement?: string) => void, processListeners: (functionName: string, CMIElement?: string, value?: any) => void, metadata?: CommitMetadata, onRequestComplete?: () => void): ResultObject;
     updateSettings(settings: Settings): void;
 }
 export type ScormEventCallback = (...args: any[]) => void;
@@ -13,7 +14,7 @@ export interface IEventService {
     on(listenerName: string, callback: ScormEventCallback): void;
     off(listenerName: string, callback: ScormEventCallback): void;
     clear(listenerName: string): void;
-    processListeners(functionName: string, CMIElement?: string, value?: any): void;
+    processListeners(functionName: string, CMIElement?: string, value?: any, context?: CommitEventContext): void;
     reset(): void;
 }
 export interface ISerializationService {
@@ -49,7 +50,10 @@ export interface ILoggingService {
     debug(logMessage: string): void;
 }
 export interface IOfflineStorageService {
-    storeOffline(courseId: string, commitData: CommitObject): ResultObject;
+    storeOffline(courseId: string, commitData: CommitObject, metadata?: {
+        isTerminateCommit?: boolean;
+        sequence?: number;
+    }): ResultObject;
     getOfflineData(courseId: string): Promise<CommitObject | null>;
     syncOfflineData(): Promise<boolean>;
     hasPendingOfflineData(courseId: string): Promise<boolean>;

package/dist/types/services/AsynchronousHttpService.d.ts

@@ -1,13 +1,14 @@
-import { CommitObject, InternalSettings, ResultObject } from "../types/api_types";
+import { CommitMetadata, CommitObject, InternalSettings, ResultObject } from "../types/api_types";
 import { LogLevelEnum } from "../constants/enums";
 import { IHttpService } from "../interfaces/services";
 import { ErrorCode } from "../constants/error_codes";
 import { StringKeyMap } from "../utilities";
 export declare class AsynchronousHttpService implements IHttpService {
+    readonly reportsRequestCompletion = true;
     private settings;
     private error_codes;
     constructor(settings: InternalSettings, error_codes: ErrorCode);
-    processHttpRequest(url: string, params: CommitObject | StringKeyMap | Array<any>, immediate: boolean | undefined, apiLog: (functionName: string, message: any, messageLevel: LogLevelEnum, CMIElement?: string) => void, processListeners: (functionName: string, CMIElement?: string, value?: any) => void): ResultObject;
+    processHttpRequest(url: string, params: CommitObject | StringKeyMap | Array<any>, immediate: boolean | undefined, apiLog: (functionName: string, message: any, messageLevel: LogLevelEnum, CMIElement?: string) => void, processListeners: (functionName: string, CMIElement?: string, value?: any) => void, metadata?: CommitMetadata, onRequestComplete?: () => void): ResultObject;
     private _performAsyncRequest;
     private _prepareRequestBody;
     private performFetch;

package/dist/types/services/EventService.d.ts

@@ -1,4 +1,4 @@
-import { LogLevel } from "../types/api_types";
+import { CommitEventContext, LogLevel } from "../types/api_types";
 import { IEventService, ScormEventCallback } from "../interfaces/services";
 export declare class EventService implements IEventService {
     private listenerMap;
@@ -9,7 +9,7 @@ export declare class EventService implements IEventService {
     on(listenerName: string, callback: ScormEventCallback): void;
     off(listenerName: string, callback: ScormEventCallback): void;
     clear(listenerName: string): void;
-    processListeners(functionName: string, CMIElement?: string, value?: any): void;
+    processListeners(functionName: string, CMIElement?: string, value?: any, context?: CommitEventContext): void;
     reset(): void;
 }
 //# sourceMappingURL=EventService.d.ts.map

package/dist/types/services/OfflineStorageService.d.ts

@@ -1,6 +1,10 @@
 import { CommitObject, InternalSettings, ResultObject } from "../types/api_types";
 import { LogLevelEnum } from "../constants/enums";
 import { ErrorCode } from "../constants/error_codes";
+type OfflineCommitMetadata = {
+    isTerminateCommit?: boolean;
+    sequence?: number;
+};
 export declare class OfflineStorageService {
     private apiLog;
     private settings;
@@ -14,7 +18,7 @@ export declare class OfflineStorageService {
     constructor(settings: InternalSettings, error_codes: ErrorCode, apiLog: (functionName: string, message: any, messageLevel: LogLevelEnum, CMIElement?: string) => void);
     private handleOnlineStatusChange;
     private handleCustomNetworkStatus;
-    storeOffline(courseId: string, commitData: CommitObject): ResultObject;
+    storeOffline(courseId: string, commitData: CommitObject, metadata?: OfflineCommitMetadata): ResultObject;
     getOfflineData(courseId: string): Promise<CommitObject | null>;
     syncOfflineData(): Promise<boolean>;
     private sendDataToLMS;
@@ -25,4 +29,5 @@ export declare class OfflineStorageService {
     updateSettings(settings: InternalSettings): void;
     destroy(): void;
 }
+export {};
 //# sourceMappingURL=OfflineStorageService.d.ts.map

package/dist/types/services/SynchronousHttpService.d.ts

@@ -1,4 +1,4 @@
-import { CommitObject, InternalSettings, ResultObject } from "../types/api_types";
+import { CommitMetadata, CommitObject, InternalSettings, ResultObject } from "../types/api_types";
 import { IHttpService } from "../interfaces/services";
 import { ErrorCode } from "../constants/error_codes";
 import { StringKeyMap } from "../utilities";
@@ -6,7 +6,7 @@ export declare class SynchronousHttpService implements IHttpService {
     private settings;
     private error_codes;
     constructor(settings: InternalSettings, error_codes: ErrorCode);
-    processHttpRequest(url: string, params: CommitObject | StringKeyMap | Array<any>, immediate: boolean | undefined, _apiLog: (functionName: string, message: any, messageLevel: number, CMIElement?: string) => void, _processListeners: (functionName: string, CMIElement?: string, value?: any) => void): ResultObject;
+    processHttpRequest(url: string, params: CommitObject | StringKeyMap | Array<any>, immediate: boolean | undefined, _apiLog: (functionName: string, message: any, messageLevel: number, CMIElement?: string) => void, _processListeners: (functionName: string, CMIElement?: string, value?: any) => void, metadata?: CommitMetadata, _onRequestComplete?: () => void): ResultObject;
     private _handleImmediateRequest;
     private _performSyncXHR;
     private _prepareRequestBody;

package/dist/types/services/ValidationService.d.ts

@@ -1,6 +1,6 @@
 import { BaseScormValidationError } from "../exceptions";
 export declare class ValidationService {
-    validateScore(CMIElement: string, value: string, decimalRegex: string, scoreRange: string | false, invalidTypeCode: number, invalidRangeCode: number, errorClass: typeof BaseScormValidationError): boolean;
+    validateScore(CMIElement: string, value: string, decimalRegex: string, scoreRange: string | false, invalidTypeCode: number, invalidRangeCode: number, errorClass: typeof BaseScormValidationError, allowEmptyString?: boolean): boolean;
     validateScorm12Audio(CMIElement: string, value: string): boolean;
     validateScorm12Language(CMIElement: string, value: string): boolean;
     validateScorm12Speed(CMIElement: string, value: string): boolean;

package/dist/types/types/api_types.d.ts

@@ -2,6 +2,19 @@ import { CompletionStatus, LogLevelEnum, SuccessStatus } from "../constants/enum
 import { StringKeyMap } from "../utilities";
 import { SequencingSettings } from "./sequencing_types";
 import type { IHttpService } from "../interfaces/services";
+export type CommitTrigger = "autocommit" | "manual" | "terminate" | "offline-replay";
+export type CommitMetadata = {
+    isTerminateCommit: boolean;
+    trigger: CommitTrigger;
+    sequence?: number;
+};
+export type CommitEventContext = {
+    url: string;
+    trigger: CommitTrigger;
+    isTerminateCommit: boolean;
+    sequence?: number;
+    errorCode?: number;
+};
 export type Settings = {
     autocommit?: boolean | undefined;
     autocommitSeconds?: number | undefined;
@@ -22,7 +35,10 @@ export type Settings = {
     fetchMode?: "cors" | "no-cors" | "same-origin" | "navigate" | undefined;
     responseHandler?: ((response: Response) => Promise<ResultObject>) | undefined;
     xhrResponseHandler?: ((xhr: XMLHttpRequest) => ResultObject) | undefined;
-    requestHandler?: ((commitObject: unknown) => unknown) | undefined;
+    requestHandler?: ((commitObject: unknown, metadata?: CommitMetadata) => unknown) | undefined;
+    terminateCommitParam?: string | undefined;
+    terminateCommitPayloadField?: string | undefined;
+    includeCommitSequence?: boolean | undefined;
     onLogMessage?: ((messageLevel: LogLevel, logMessage: string) => void) | undefined;
     mastery_override?: boolean | undefined;
     score_overrides_status?: boolean | undefined;
@@ -66,7 +82,10 @@ export type InternalSettings = {
     fetchMode: "cors" | "no-cors" | "same-origin" | "navigate";
     responseHandler: (response: Response) => Promise<ResultObject>;
     xhrResponseHandler: (xhr: XMLHttpRequest) => ResultObject;
-    requestHandler: (commitObject: unknown) => unknown;
+    requestHandler: (commitObject: unknown, metadata?: CommitMetadata) => unknown;
+    terminateCommitParam?: string | undefined;
+    terminateCommitPayloadField?: string | undefined;
+    includeCommitSequence?: boolean | undefined;
     onLogMessage?: ((messageLevel: LogLevel, logMessage: string) => void) | undefined;
     mastery_override?: boolean | undefined;
     score_overrides_status?: boolean | undefined;
@@ -121,6 +140,7 @@ export type CommitObject = {
     sessionId?: string;
     activityId?: string;
     attempt?: number;
+    commitSequence?: number;
 };
 export type CommitObjectWithScore = CommitObject & {
     score: ScoreObject;

package/dist/types/utilities/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./core";
+export { appendQueryParam } from "./url";
 export { PlayerEventAdapter } from "./PlayerEventAdapter";
 export type { NavigationState, ScoStatus, CourseProgress, ScoDelivery, SessionEndReason, SessionEndData, PlayerEventAdapterCallbacks, PlayerEventAdapterConfig, } from "./PlayerEventAdapter";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/utilities/url.d.ts

@@ -0,0 +1,2 @@
+export declare const appendQueryParam: (url: string, name: string, value: string | number | boolean) => string;
+//# sourceMappingURL=url.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scorm-again",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "A modern SCORM JavaScript run-time library for SCORM 1.2 and SCORM 2004",
   "main": "dist/scorm-again.js",
   "types": "index.d.ts",
@@ -90,46 +90,47 @@
     "test": "test"
   },
   "devDependencies": {
-    "@babel/core": "7.29.0",
-    "@babel/preset-env": "7.29.2",
+    "@babel/core": "<8",
+    "@babel/preset-env": "<8",
+    "@cyclonedx/cyclonedx-npm": "^5.0.0",
     "@eslint/js": "10.0.1",
     "@mo36924/rollup-plugin-cache": "1.6.11",
-    "@playwright/test": "1.59.1",
-    "@rollup/plugin-babel": "7.0.0",
+    "@playwright/test": "1.61.1",
+    "@rollup/plugin-babel": "7.1.0",
     "@rollup/plugin-terser": "1.0.0",
     "@rollup/plugin-typescript": "12.3.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
-    "@vitest/coverage-v8": "4.1.5",
-    "@vitest/ui": "4.1.5",
+    "@vitest/coverage-v8": "4.1.9",
+    "@vitest/ui": "4.1.9",
     "cors": "^2.8.6",
-    "esbuild": "0.28.0",
-    "eslint": "10.2.1",
-    "eslint-plugin-jsdoc": "62.9.0",
+    "esbuild": "0.28.1",
+    "eslint": "10.6.0",
+    "eslint-plugin-jsdoc": "63.0.10",
     "express": "^5.2.1",
     "extract-zip": "2.0.1",
-    "fast-check": "4.7.0",
+    "fast-check": "4.8.0",
     "glob": "13.0.6",
-    "globals": "17.5.0",
-    "jsdom": "29.0.2",
-    "monocart-coverage-reports": "^2.12.11",
-    "monocart-reporter": "^2.10.1",
-    "playwright": "1.59.1",
-    "prettier": "3.8.3",
-    "rollup": "4.60.2",
+    "globals": "17.7.0",
+    "jsdom": "29.1.1",
+    "monocart-coverage-reports": "^2.12.12",
+    "monocart-reporter": "^2.12.1",
+    "playwright": "1.61.1",
+    "prettier": "3.9.4",
+    "rollup": "4.62.2",
     "rollup-plugin-dts": "6.4.1",
     "rollup-plugin-esbuild": "6.2.1",
     "standard-version": "9.5.0",
-    "terser": "5.46.2",
+    "terser": "5.48.0",
     "tslib": "2.8.1",
-    "tsx": "4.21.0",
+    "tsx": "4.22.5",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.59.0",
-    "vite": "8.0.10",
-    "vitest": "4.1.5"
+    "typescript-eslint": "8.62.1",
+    "vite": "8.1.3",
+    "vitest": "4.1.9"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.0"
   },
   "sideEffects": false,
   "scripts": {
@@ -178,7 +179,21 @@
   },
   "keywords": [
     "scorm",
-    "cmi"
+    "scorm-1-2",
+    "scorm-2004",
+    "cmi",
+    "elearning",
+    "e-learning",
+    "lms",
+    "learning-management-system",
+    "edtech",
+    "educational-technology",
+    "learning-standards",
+    "typescript",
+    "javascript",
+    "browser",
+    "cross-frame",
+    "offline-first"
   ],
   "author": "Jonathan Putney <jonathan@putney.io>",
   "license": "MIT",
@@ -191,6 +206,12 @@
       "@actions/github": "^9.0.0",
       "@actions/http-client": "^4.0.0"
     },
+    "@cyclonedx/cyclonedx-library": {
+      "libxmljs2": "npm:noop2@2.0.0"
+    },
+    "@cyclonedx/cyclonedx-npm": {
+      "libxmljs2": "npm:noop2@2.0.0"
+    },
     "ajv": "6.14.0",
     "nodemailer": ">=8.0.4",
     "typescript-eslint": {