coursecode 0.1.17 → 0.1.19

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -525,12 +525,12 @@ When cloud meta tags are present, they **always win** — even if `course-config
 | Utility | Config Key | Meta Tag | Transport | Events |
 |---------|-----------|----------|-----------|--------|
 | `error-reporter.js` | `environment.errorReporting` | `cc-error-endpoint` | POST per error (60s dedup) | `*:error` (14 event types) |
-| `data-reporter.js` | `environment.dataReporting` | `cc-data-endpoint` | Batched POST + `sendBeacon` on unload | `assessment:submitted`, `objective:updated`, `interaction:recorded` |
+| `data-reporter.js` | `environment.dataReporting` | `cc-data-endpoint` | Batched POST + `sendBeacon` on unload | `assessment:submitted`, `objective:updated`, `interaction:recorded`, `course:statusChanged`, `channel:message` |
 | `course-channel.js` | `environment.channel` | `cc-channel-endpoint` + `cc-channel-id` | POST to send, SSE to receive | `channel:message`, `channel:connected`, `channel:disconnected` |
 
 **Error Reporter** — Subscribes to all `*:error` events, deduplicates by domain+operation+message (60s window), POSTs to endpoint. Optional `enableUserReports: true` adds "Report Issue" to settings menu. `submitUserReport()` for programmatic user reports.
 
-**Data Reporter** — Queues assessment/objective/interaction records, flushes on batch size (default 10) or timer (default 30s). `sendBeacon` fallback on page unload.
+**Data Reporter** — Queues assessment/objective/interaction/session/channel records, flushes on batch size (default 10) or timer (default 30s). `sendBeacon` fallback on page unload. Also listens to `course:statusChanged` (queues a `session` record on completion) and `channel:message` (queues a `channel` record). Exposes `CourseCode.reportData(type, data)` for course authors to send custom event types.
 
 **Course Channel** — Generic pub/sub pipe. `sendChannelMessage(data)` POSTs any JSON to `endpoint/channelId`. SSE listener on same URL bridges incoming messages to EventBus. Exponential backoff reconnect (1s → 30s cap). Content-agnostic — the relay is a dumb fan-out router.
 

package/framework/js/drivers/cmi5-driver.js

@@ -68,7 +68,11 @@ export class Cmi5Driver extends HttpDriverBase {
 
         // Check for cmi5 dev API (stub player or standalone preview)
         // Search current window and parent frame (stub player injects on parent)
-        const devApi = typeof window !== 'undefined' && (window.cmi5 || (window.parent !== window && window.parent.cmi5));
+        // Try/catch guards against DOMException in cross-origin iframes
+        let devApi = typeof window !== 'undefined' && window.cmi5;
+        if (!devApi && typeof window !== 'undefined' && window.parent !== window) {
+            try { devApi = window.parent.cmi5; } catch (_e) { /* cross-origin parent */ }
+        }
         if (devApi) {
             logger.info('[Cmi5Driver] Using cmi5 development API');
             this._mock = true;
@@ -82,12 +86,15 @@ export class Cmi5Driver extends HttpDriverBase {
 
         // Check for cmi5 launch parameters
         if (!this._hasLaunchParameters()) {
-            logger.info('[Cmi5Driver] No cmi5 launch parameters. Using localStorage mock.');
-            this._mock = true;
-            this._loadMockState();
-            this._isConnected = true;
-            this._logMockStatement('initialized', { verb: 'initialized' });
-            return true;
+            if (import.meta.env.DEV) {
+                logger.info('[Cmi5Driver] No cmi5 launch parameters. Using localStorage mock.');
+                this._mock = true;
+                this._loadMockState();
+                this._isConnected = true;
+                this._logMockStatement('initialized', { verb: 'initialized' });
+                return true;
+            }
+            throw new Error('[Cmi5Driver] No cmi5 launch parameters detected. Expected fetch, endpoint, actor, registration, and activityId URL parameters.');
         }
 
         // Production mode: dynamically import @xapi/cmi5

package/framework/js/drivers/lti-driver.js

@@ -70,7 +70,11 @@ export class LtiDriver extends HttpDriverBase {
 
         // Check for LTI dev API (stub player)
         // Search current window and parent frame (stub player injects on parent)
-        const devApi = typeof window !== 'undefined' && (window.lti || (window.parent !== window && window.parent.lti));
+        // Try/catch guards against DOMException in cross-origin iframes (LMS embeds)
+        let devApi = typeof window !== 'undefined' && window.lti;
+        if (!devApi && typeof window !== 'undefined' && window.parent !== window) {
+            try { devApi = window.parent.lti; } catch (_e) { /* cross-origin parent */ }
+        }
         if (devApi) {
             logger.info('[LtiDriver] Using LTI development API');
             this._mock = true;
@@ -84,12 +88,15 @@ export class LtiDriver extends HttpDriverBase {
 
         // Check for LTI launch parameters
         if (!this._hasLaunchParameters()) {
-            logger.info('[LtiDriver] No LTI launch parameters. Using localStorage mock.');
-            this._mock = true;
-            this._loadMockState();
-            this._isConnected = true;
-            this._logMockStatement('initialized', { verb: 'initialized' });
-            return true;
+            if (import.meta.env.DEV) {
+                logger.info('[LtiDriver] No LTI launch parameters. Using localStorage mock.');
+                this._mock = true;
+                this._loadMockState();
+                this._isConnected = true;
+                this._logMockStatement('initialized', { verb: 'initialized' });
+                return true;
+            }
+            throw new Error('[LtiDriver] No LTI launch context detected. Expected <meta name="lms-format" content="lti"> or id_token/state URL parameters.');
         }
 
         // Production mode: validate JWT and extract claims
@@ -248,6 +255,11 @@ export class LtiDriver extends HttpDriverBase {
     _hasLaunchParameters() {
         if (typeof window === 'undefined') return false;
 
+        // Cloud-hosted: engine handles OIDC server-side, signals via meta tag
+        const formatMeta = document.querySelector('meta[name="lms-format"]');
+        if (formatMeta?.content === 'lti') return true;
+
+        // Self-hosted: JWT params in URL from OIDC redirect
         const params = new URLSearchParams(window.location.search);
         return Boolean(
             params.get('id_token') ||
@@ -257,15 +269,27 @@ export class LtiDriver extends HttpDriverBase {
     }
 
     async _processLaunch() {
-        const { jwtVerify, createRemoteJWKSet } = await import('jose');
-
         const params = new URLSearchParams(window.location.search);
         const idToken = params.get('id_token');
 
+        // Cloud-hosted path: OIDC handled server-side, no JWT in URL
         if (!idToken) {
-            throw new Error('No id_token found in launch parameters');
+            this._claims = this._resolveCloudClaims();
+            this._stateEndpoint = this._resolveStateEndpoint();
+
+            const agsUrl = this._resolveCloudAgsEndpoint();
+            if (agsUrl) {
+                this._agsLineItemUrl = agsUrl;
+                logger.debug('[LtiDriver] Cloud AGS endpoint:', agsUrl);
+            }
+
+            logger.debug('[LtiDriver] Cloud-hosted launch. User:', this._claims?.sub || 'unknown');
+            return;
         }
 
+        // Self-hosted path: validate JWT from URL params
+        const { jwtVerify, createRemoteJWKSet } = await import('jose');
+
         const [headerB64] = idToken.split('.');
         const header = JSON.parse(atob(headerB64));
 
@@ -332,6 +356,37 @@ export class LtiDriver extends HttpDriverBase {
         return '/api/lti/state';
     }
 
+    /**
+     * Resolves LTI claims from cloud-injected meta tags or config object.
+     * Used when OIDC is handled server-side (no JWT in URL).
+     */
+    _resolveCloudClaims() {
+        const meta = document.querySelector('meta[name="cc-lti-claims"]');
+        if (meta?.content) {
+            try {
+                return JSON.parse(meta.content);
+            } catch (e) {
+                logger.warn('[LtiDriver] Failed to parse cc-lti-claims meta tag:', e.message);
+            }
+        }
+
+        if (window.__LTI_CONFIG__?.claims) return window.__LTI_CONFIG__.claims;
+
+        throw new Error('[LtiDriver] Cloud LTI launch detected but no claims provided. Expected <meta name="cc-lti-claims"> or window.__LTI_CONFIG__.claims.');
+    }
+
+    /**
+     * Resolves AGS lineitem URL from cloud-injected meta tags or config object.
+     */
+    _resolveCloudAgsEndpoint() {
+        const meta = document.querySelector('meta[name="cc-lti-ags"]');
+        if (meta?.content) return meta.content;
+
+        if (window.__LTI_CONFIG__?.agsEndpoint) return window.__LTI_CONFIG__.agsEndpoint;
+
+        return null;
+    }
+
     _getStateKey() {
         if (this._claims) {
             const resourceLink = this._claims['https://purl.imsglobal.org/spec/lti/claim/resource_link']?.id;

package/framework/js/main.js

@@ -48,7 +48,7 @@ import { logger } from './utilities/logger.js';
 import { iconManager } from './utilities/icons.js';
 import { breakpointManager } from './utilities/breakpoint-manager.js';
 import { initErrorReporter } from './utilities/error-reporter.js';
-import { initDataReporter } from './utilities/data-reporter.js';
+import { initDataReporter, reportData } from './utilities/data-reporter.js';
 import { initCourseChannel } from './utilities/course-channel.js';
 import { canvasSlide } from './utilities/canvas-slide.js';
 
@@ -98,7 +98,10 @@ window.CourseCode = {
 
     // Core
     eventBus,
-    courseConfig
+    courseConfig,
+
+    // Data reporting public API
+    reportData,
 };
 
 // --- Conditional Automation Module Loading ---

package/framework/js/utilities/data-reporter.js

@@ -1,8 +1,9 @@
 /**
  * Data Reporter - Optional external learning data reporting via webhook
  * 
- * Batches important learning records (assessments, objectives, interactions) and
- * sends them to a configured endpoint. Works across all LMS formats.
+ * Batches important learning records (assessments, objectives, interactions,
+ * session completion, channel messages, and custom events) and sends them
+ * to a configured endpoint. Works across all LMS formats.
  * 
  * Configuration in course-config.js:
  *   environment: {
@@ -13,6 +14,9 @@
  *           includeContext: true     // Include course metadata (default: true)
  *       }
  *   }
+ * 
+ * Public API:
+ *   CourseCode.reportData(type, data) — Queue a custom record for reporting
  */
 
 import { eventBus } from '../core/event-bus.js';
@@ -39,7 +43,7 @@ const DEFAULT_FLUSH_INTERVAL = 30000; // 30 seconds
 
 /**
  * Queue a record for batched sending
- * @param {string} type - Record type: 'assessment', 'objective', 'interaction', 'session'
+ * @param {string} type - Record type (assessment, objective, interaction, session, channel, or custom)
  * @param {Object} data - Record data
  */
 function queueRecord(type, data) {
@@ -230,6 +234,26 @@ function handleInteractionRecorded(interaction) {
     });
 }
 
+/**
+ * Handle course completion / status change
+ * Only reports when the course reaches 'completed' status.
+ */
+function handleCourseStatusChanged({ completionStatus, successStatus }) {
+    if (completionStatus !== 'completed') return;
+
+    queueRecord('session', {
+        completionStatus,
+        successStatus: successStatus || 'unknown'
+    });
+}
+
+/**
+ * Handle incoming channel messages — log them as 'channel' records
+ */
+function handleChannelMessage(data) {
+    queueRecord('channel', data);
+}
+
 /**
  * Handle session termination - flush remaining records
  */
@@ -282,10 +306,12 @@ export function initDataReporter(courseConfig) {
 
     logger.info('[DataReporter] Initialized with endpoint:', config.endpoint);
 
-    // Subscribe to important events
+    // Subscribe to learning events
     eventBus.on('assessment:submitted', handleAssessmentSubmitted);
     eventBus.on('objective:updated', handleObjectiveUpdated);
     eventBus.on('interaction:recorded', handleInteractionRecorded);
+    eventBus.on('course:statusChanged', handleCourseStatusChanged);
+    eventBus.on('channel:message', handleChannelMessage);
     eventBus.on('session:beforeTerminate', handleBeforeTerminate);
 
     // Emergency flush on page hide (catches tab close, navigation away)
@@ -294,3 +320,23 @@ export function initDataReporter(courseConfig) {
         window.addEventListener('beforeunload', emergencyFlush);
     }
 }
+
+/**
+ * Public API: Queue a custom data record for reporting.
+ * Exposed on window.CourseCode.reportData so course authors can send
+ * arbitrary events to the configured data endpoint.
+ *
+ * @param {string} type - Record type name (e.g. 'custom-metric', 'survey-response')
+ * @param {Object} data - Record data payload
+ */
+export function reportData(type, data) {
+    if (!type || typeof type !== 'string') {
+        logger.warn('[DataReporter] reportData: type must be a non-empty string');
+        return;
+    }
+    if (!data || typeof data !== 'object') {
+        logger.warn('[DataReporter] reportData: data must be an object');
+        return;
+    }
+    queueRecord(type, data);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecode",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Multi-format course authoring framework with CLI tools (SCORM 2004, SCORM 1.2, cmi5, LTI 1.3)",
   "type": "module",
   "bin": {