@teacharium/embed-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Teacharium Embed SDK
 
-A lightweight JavaScript SDK for embedding Teacharium lessons into any website using secure iframe-based embedding.
+A lightweight JavaScript SDK for embedding Teacharium lessons into any website using secure iframe-based embedding with signed JWT tokens.
 
 ## Installation
 
@@ -16,54 +16,69 @@ Or use directly via CDN:
 
 ## Quick Start
 
-### 1. Obtain a JWT Token
+### 1. Publish a Lesson Version
 
-First, generate a signed token from your backend using the Teacharium API:
+In the Teacharium editor, publish a version of your lesson:
+
+1. Open your lesson in the editor
+2. Go to the **Lesson Delivery** tab
+3. Click **Publish New Version**
+4. Expand the published version and click **Embed** to get the Lesson ID and Version ID
+
+### 2. Generate a JWT Token (Server-Side)
+
+Generate a signed token from your backend using the Teacharium API. The token must include both a `lessonId` and a `versionId` to embed a specific published version:
 
 ```javascript
-const response = await fetch('https://www.teacharium.io/api/public/sign-token', {
-  method: 'POST',
-  headers: {
-    'Authorization': `Bearer ${publicKey}.${secretKey}`,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    lessonId: 'your-lesson-id',
-    userAttributes: {
-      userId: 'user_12345',
-      organizationRole: 'student'
+const response = await fetch(
+  "https://www.teacharium.io/api/public/sign-token",
+  {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${publicKey}.${secretKey}`,
+      "Content-Type": "application/json",
     },
-    timeout: 3600
-  })
-});
+    body: JSON.stringify({
+      lessonId: "your-lesson-id",
+      versionId: "your-published-version-id",
+      learnerId: "learner_anonymous_id",
+      userAttributes: {
+        userId: "user_12345",
+        organizationRole: "student",
+      },
+      timeout: 3600,
+    }),
+  },
+);
 
 const { token } = await response.json();
 ```
 
-**Important:** Do not include personally identifiable information (PII) such as email addresses, full names, or phone numbers in `userAttributes`. Use anonymous identifiers like user IDs or session IDs instead.
+**Important:** Always generate tokens server-side to protect your API credentials. Do not include personally identifiable information (PII) such as email addresses, full names, or phone numbers in `learnerId` or `userAttributes`. Use anonymous identifiers instead.
 
-### 2. Embed the Lesson
+### 3. Embed the Lesson (Client-Side)
 
 ```html
 <div id="lesson-container"></div>
 
 <script type="module">
-  import { embedLesson } from '@teacharium/embed-sdk';
+  import { embedLesson } from "@teacharium/embed-sdk";
 
   const embed = embedLesson({
-    container: '#lesson-container',
-    token: 'your-jwt-token-here',
-    // baseUrl and lessonId are optional - defaults to www.teacharium.io and extracts lessonId from token
-    width: '100%',
-    height: '600px',
-    onLoad: () => console.log('Lesson loaded'),
-    onComplete: (data) => console.log('Lesson completed', data),
-    onProgress: (data) => console.log('Progress update', data),
-    onError: (error) => console.error('Error', error)
+    container: "#lesson-container",
+    token: token, // JWT token from your server
+    width: "100%",
+    height: "600px",
+    onLoad: () => console.log("Lesson loaded"),
+    onComplete: (data) => console.log("Lesson completed", data),
+    onProgress: (data) => console.log("Progress update", data),
+    onError: (error) => console.error("Error", error),
   });
 </script>
 ```
 
+The SDK automatically extracts the `lessonId` and `versionId` from the JWT token -- you do not need to pass them separately.
+
 ### Using UMD (Browser Global)
 
 ```html
@@ -72,11 +87,11 @@ const { token } = await response.json();
 <script src="https://unpkg.com/@teacharium/embed-sdk@latest/dist/teacharium-embed-sdk.umd.js"></script>
 <script>
   const embed = TeachariumEmbed.embedLesson({
-    container: '#lesson-container',
-    token: 'your-jwt-token-here',
+    container: "#lesson-container",
+    token: "your-jwt-token-here",
     onComplete: (data) => {
-      console.log('Lesson completed!', data);
-    }
+      console.log("Lesson completed!", data);
+    },
   });
 </script>
 ```
@@ -90,7 +105,7 @@ Creates and embeds a lesson iframe.
 **Options:**
 
 - `container` (required): HTMLElement or CSS selector string for the container
-- `token` (required): JWT token from `/api/public/sign-token` (lessonId is automatically extracted from this token)
+- `token` (required): JWT token from `/api/public/sign-token` (lessonId and versionId are automatically extracted)
 - `baseUrl` (optional): Base URL of your Teacharium instance, default: "https://www.teacharium.io"
 - `width` (optional): Iframe width, default: "100%"
 - `height` (optional): Iframe height, default: "600px"
@@ -105,6 +120,7 @@ Creates and embeds a lesson iframe.
 ### `TeachariumEmbed` Methods
 
 #### `destroy()`
+
 Removes the embedded lesson from the page.
 
 ```javascript
@@ -112,20 +128,23 @@ embed.destroy();
 ```
 
 #### `reload()`
+
 Reloads the embedded lesson.
 
 ```javascript
 embed.reload();
 ```
 
-#### `postMessage(type: string, payload?: any)`
+#### `postMessage(type: string, payload?: unknown)`
+
 Send a custom message to the embedded lesson.
 
 ```javascript
-embed.postMessage('custom:action', { data: 'value' });
+embed.postMessage("custom:action", { data: "value" });
 ```
 
 #### `getIframe()`
+
 Get the iframe element.
 
 ```javascript
@@ -135,15 +154,17 @@ const iframe = embed.getIframe();
 ## Events
 
 ### onLoad
+
 Fired when the lesson iframe has loaded.
 
 ```javascript
 onLoad: () => {
-  console.log('Lesson is ready');
-}
+  console.log("Lesson is ready");
+};
 ```
 
 ### onComplete
+
 Fired when the user completes the lesson.
 
 ```javascript
@@ -152,10 +173,11 @@ onComplete: (data) => {
   // data.completedAt - ISO timestamp
   // data.score - Optional score
   // data.totalSteps - Total number of steps
-}
+};
 ```
 
 ### onProgress
+
 Fired when the user progresses through the lesson.
 
 ```javascript
@@ -164,61 +186,36 @@ onProgress: (data) => {
   // data.totalSteps - Total steps
   // data.sectionIndex - Current section index
   // data.stepIndex - Current step index
-}
+};
 ```
 
 ### onError
+
 Fired when an error occurs.
 
 ```javascript
 onError: (error) => {
-  console.error('Lesson error:', error.message);
-}
+  console.error("Lesson error:", error.message);
+};
 ```
 
 ## Security
 
 - Always generate tokens on your backend, never expose API keys in client-side code
+- Tokens are tied to specific lesson versions, ensuring users see the exact content you published
 - Tokens expire based on the `timeout` parameter (default 2 hours, max 24 hours)
-- Tokens are tied to specific lessons and organizations
+- Tokens are tied to specific lessons, versions, and organizations
 - User attributes in tokens cannot be modified without re-signing
 
 ## Examples
 
-### Responsive Embed
-
-```javascript
-embedLesson({
-  container: '#lesson',
-  token: token,
-  baseUrl: 'https://your-domain.com',
-  lessonId: lessonId,
-  width: '100%',
-  height: '80vh',
-  className: 'lesson-iframe'
-});
-```
-
-### With Progress Tracking
-
-```javascript
-const embed = embedLesson({
-  container: '#lesson',
-  token: token,
-  baseUrl: 'https://your-domain.com',
-  lessonId: lessonId,
-  onProgress: (data) => {
-    const percent = (data.currentStep / data.totalSteps) * 100;
-    document.querySelector('#progress-bar').style.width = `${percent}%`;
-  }
-});
-```
+See the [Express.js example](../../examples/embed-sdk-express/) for a complete working integration.
 
 ### React Example
 
 ```jsx
-import { useEffect, useRef } from 'react';
-import { embedLesson } from '@teacharium/embed-sdk';
+import { useEffect, useRef } from "react";
+import { embedLesson } from "@teacharium/embed-sdk";
 
 function LessonEmbed({ token }) {
   const containerRef = useRef(null);
@@ -229,10 +226,9 @@ function LessonEmbed({ token }) {
       embedRef.current = embedLesson({
         container: containerRef.current,
         token: token,
-        // lessonId and baseUrl are automatically handled
         onComplete: (data) => {
-          console.log('Lesson completed!', data);
-        }
+          console.log("Lesson completed!", data);
+        },
       });
     }
 
@@ -243,7 +239,7 @@ function LessonEmbed({ token }) {
     };
   }, [token]);
 
-  return <div ref={containerRef} style={{ width: '100%', height: '600px' }} />;
+  return <div ref={containerRef} style={{ width: "100%", height: "600px" }} />;
 }
 ```
 

package/dist/main.d.ts

@@ -1 +1,108 @@
-export {}
+/**
+ * Teacharium Embed SDK
+ *
+ * This SDK provides an easy way to embed Teacharium lessons into any website
+ * using an iframe with JWT-based authentication.
+ *
+ * Tokens are generated server-side via the Teacharium Sign Token API and
+ * contain both the lessonId and versionId (published version) to embed.
+ */
+export interface EmbedOptions {
+    /**
+     * The container element or selector where the lesson should be embedded
+     */
+    container: HTMLElement | string;
+    /**
+     * The JWT token obtained from /api/public/sign-token.
+     * The token contains the lessonId and versionId, which are extracted automatically.
+     */
+    token: string;
+    /**
+     * The base URL of your Teacharium instance
+     * Defaults to "https://www.teacharium.io"
+     * @example "https://your-domain.com"
+     */
+    baseUrl?: string;
+    /**
+     * Width of the iframe (default: "100%")
+     */
+    width?: string;
+    /**
+     * Height of the iframe (default: "600px")
+     */
+    height?: string;
+    /**
+     * Additional CSS classes to apply to the iframe
+     */
+    className?: string;
+    /**
+     * Callback function called when the lesson is loaded
+     */
+    onLoad?: () => void;
+    /**
+     * Callback function called when the lesson is completed
+     */
+    onComplete?: (data: LessonCompleteData) => void;
+    /**
+     * Callback function called on lesson progress updates
+     */
+    onProgress?: (data: LessonProgressData) => void;
+    /**
+     * Callback function called when an error occurs
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Callback function called for every message received from the embedded lesson.
+     * Useful for logging or handling custom event types.
+     */
+    onEvent?: (type: string, payload: unknown) => void;
+}
+export interface LessonCompleteData {
+    lessonId: string;
+    completedAt: string;
+    score?: number;
+    totalSteps: number;
+}
+export interface LessonProgressData {
+    lessonId: string;
+    currentStep: number;
+    totalSteps: number;
+    sectionIndex: number;
+    stepIndex: number;
+}
+export declare class TeachariumEmbed {
+    private iframe;
+    private container;
+    private options;
+    constructor(options: EmbedOptions);
+    private init;
+    private createIframe;
+    private setupMessageListener;
+    /**
+     * Remove the embedded lesson from the page
+     */
+    destroy(): void;
+    /**
+     * Send a message to the embedded lesson
+     * @param type The message type
+     * @param payload The message payload
+     */
+    postMessage(type: string, payload?: unknown): void;
+    /**
+     * Reload the embedded lesson
+     */
+    reload(): void;
+    /**
+     * Get the iframe element
+     */
+    getIframe(): HTMLIFrameElement | null;
+}
+/**
+ * Factory function to create a new embedded lesson
+ */
+export declare function embedLesson(options: EmbedOptions): TeachariumEmbed;
+declare const _default: {
+    TeachariumEmbed: typeof TeachariumEmbed;
+    embedLesson: typeof embedLesson;
+};
+export default _default;

package/dist/teacharium-embed-sdk.es.js

@@ -21,8 +21,10 @@ class i {
       if (s = a(e.token).lessonId, !s)
         throw new Error("Token does not contain lessonId");
     } catch {
-      const r = new Error("Failed to extract lessonId from token. Ensure token is valid and contains lessonId.");
-      throw e.onError?.(r), r;
+      const t = new Error(
+        "Failed to extract lessonId from token. Ensure token is valid."
+      );
+      throw e.onError?.(t), t;
     }
     this.options = {
       ...e,
@@ -37,7 +39,9 @@ class i {
     if (typeof this.options.container == "string") {
       const e = document.querySelector(this.options.container);
       if (!e) {
-        const s = new Error(`Container element not found: ${this.options.container}`);
+        const s = new Error(
+          `Container element not found: ${this.options.container}`
+        );
         throw this.options.onError?.(s), s;
       }
       this.container = e;
@@ -65,7 +69,10 @@ class i {
       if (e.origin === s)
         try {
           const t = typeof e.data == "string" ? JSON.parse(e.data) : e.data;
-          switch (t.type) {
+          switch (this.options.onEvent?.(t.type, t.payload), t.type) {
+            case "lesson:loaded":
+              this.options.onLoad?.();
+              break;
             case "lesson:complete":
               this.options.onComplete?.(t.payload);
               break;
@@ -104,7 +111,10 @@ class i {
    * Reload the embedded lesson
    */
   reload() {
-    this.iframe && (this.iframe.src = this.iframe.src);
+    if (this.iframe) {
+      const e = this.iframe.src;
+      this.iframe.src = e;
+    }
   }
   /**
    * Get the iframe element
@@ -116,12 +126,12 @@ class i {
 function h(o) {
   return new i(o);
 }
-const l = {
+const c = {
   TeachariumEmbed: i,
   embedLesson: h
 };
 export {
   i as TeachariumEmbed,
-  l as default,
+  c as default,
   h as embedLesson
 };

package/dist/teacharium-embed-sdk.umd.js

@@ -1 +1 @@
-(function(i,r){typeof exports=="object"&&typeof module<"u"?r(exports):typeof define=="function"&&define.amd?define(["exports"],r):(i=typeof globalThis<"u"?globalThis:i||self,r(i.TeachariumEmbed={}))})(this,(function(i){"use strict";function r(n){try{const e=n.split(".");if(e.length!==3)throw new Error("Invalid token format");const t=e[1].replace(/-/g,"+").replace(/_/g,"/"),o=decodeURIComponent(atob(t).split("").map(c=>"%"+("00"+c.charCodeAt(0).toString(16)).slice(-2)).join(""));return JSON.parse(o)}catch{throw new Error("Failed to decode JWT token")}}class a{iframe=null;container=null;options;constructor(e){let s;try{if(s=r(e.token).lessonId,!s)throw new Error("Token does not contain lessonId")}catch{const o=new Error("Failed to extract lessonId from token. Ensure token is valid and contains lessonId.");throw e.onError?.(o),o}this.options={...e,baseUrl:e.baseUrl||"https://www.teacharium.io",lessonId:s,width:e.width||"100%",height:e.height||"600px",className:e.className||""},this.init()}init(){if(typeof this.options.container=="string"){const e=document.querySelector(this.options.container);if(!e){const s=new Error(`Container element not found: ${this.options.container}`);throw this.options.onError?.(s),s}this.container=e}else this.container=this.options.container;this.createIframe(),this.setupMessageListener()}createIframe(){if(!this.container)throw new Error("Container not initialized");this.iframe=document.createElement("iframe");const e=new URL(`/embed/lesson/${this.options.lessonId}`,this.options.baseUrl);e.searchParams.set("token",this.options.token),this.iframe.src=e.toString(),this.iframe.width=this.options.width,this.iframe.height=this.options.height,this.iframe.style.border="none",this.iframe.style.display="block",this.iframe.setAttribute("allow","autoplay; fullscreen"),this.iframe.setAttribute("allowfullscreen","true"),this.options.className&&(this.iframe.className=this.options.className),this.iframe.addEventListener("load",()=>{this.options.onLoad?.()}),this.container.appendChild(this.iframe)}setupMessageListener(){window.addEventListener("message",e=>{if(this.iframe&&e.source!==this.iframe.contentWindow)return;const s=new URL(this.options.baseUrl).origin;if(e.origin===s)try{const t=typeof e.data=="string"?JSON.parse(e.data):e.data;switch(t.type){case"lesson:complete":this.options.onComplete?.(t.payload);break;case"lesson:progress":this.options.onProgress?.(t.payload);break;case"lesson:error":this.options.onError?.(new Error(t.payload.message));break}}catch(t){console.error("Error parsing message from iframe:",t)}})}destroy(){this.iframe&&this.iframe.parentNode&&(this.iframe.parentNode.removeChild(this.iframe),this.iframe=null)}postMessage(e,s){if(!this.iframe||!this.iframe.contentWindow){console.warn("Cannot post message: iframe not ready");return}const t={type:e,payload:s},o=new URL(this.options.baseUrl).origin;this.iframe.contentWindow.postMessage(t,o)}reload(){this.iframe&&(this.iframe.src=this.iframe.src)}getIframe(){return this.iframe}}function h(n){return new a(n)}const l={TeachariumEmbed:a,embedLesson:h};i.TeachariumEmbed=a,i.default=l,i.embedLesson=h,Object.defineProperties(i,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})}));
+(function(o,i){typeof exports=="object"&&typeof module<"u"?i(exports):typeof define=="function"&&define.amd?define(["exports"],i):(o=typeof globalThis<"u"?globalThis:o||self,i(o.TeachariumEmbed={}))})(this,(function(o){"use strict";function i(r){try{const e=r.split(".");if(e.length!==3)throw new Error("Invalid token format");const t=e[1].replace(/-/g,"+").replace(/_/g,"/"),a=decodeURIComponent(atob(t).split("").map(c=>"%"+("00"+c.charCodeAt(0).toString(16)).slice(-2)).join(""));return JSON.parse(a)}catch{throw new Error("Failed to decode JWT token")}}class n{iframe=null;container=null;options;constructor(e){let s;try{if(s=i(e.token).lessonId,!s)throw new Error("Token does not contain lessonId")}catch{const t=new Error("Failed to extract lessonId from token. Ensure token is valid.");throw e.onError?.(t),t}this.options={...e,baseUrl:e.baseUrl||"https://www.teacharium.io",lessonId:s,width:e.width||"100%",height:e.height||"600px",className:e.className||""},this.init()}init(){if(typeof this.options.container=="string"){const e=document.querySelector(this.options.container);if(!e){const s=new Error(`Container element not found: ${this.options.container}`);throw this.options.onError?.(s),s}this.container=e}else this.container=this.options.container;this.createIframe(),this.setupMessageListener()}createIframe(){if(!this.container)throw new Error("Container not initialized");this.iframe=document.createElement("iframe");const e=new URL(`/embed/lesson/${this.options.lessonId}`,this.options.baseUrl);e.searchParams.set("token",this.options.token),this.iframe.src=e.toString(),this.iframe.width=this.options.width,this.iframe.height=this.options.height,this.iframe.style.border="none",this.iframe.style.display="block",this.iframe.setAttribute("allow","autoplay; fullscreen"),this.iframe.setAttribute("allowfullscreen","true"),this.options.className&&(this.iframe.className=this.options.className),this.iframe.addEventListener("load",()=>{this.options.onLoad?.()}),this.container.appendChild(this.iframe)}setupMessageListener(){window.addEventListener("message",e=>{if(this.iframe&&e.source!==this.iframe.contentWindow)return;const s=new URL(this.options.baseUrl).origin;if(e.origin===s)try{const t=typeof e.data=="string"?JSON.parse(e.data):e.data;switch(this.options.onEvent?.(t.type,t.payload),t.type){case"lesson:loaded":this.options.onLoad?.();break;case"lesson:complete":this.options.onComplete?.(t.payload);break;case"lesson:progress":this.options.onProgress?.(t.payload);break;case"lesson:error":this.options.onError?.(new Error(t.payload.message));break}}catch(t){console.error("Error parsing message from iframe:",t)}})}destroy(){this.iframe&&this.iframe.parentNode&&(this.iframe.parentNode.removeChild(this.iframe),this.iframe=null)}postMessage(e,s){if(!this.iframe||!this.iframe.contentWindow){console.warn("Cannot post message: iframe not ready");return}const t={type:e,payload:s},a=new URL(this.options.baseUrl).origin;this.iframe.contentWindow.postMessage(t,a)}reload(){if(this.iframe){const e=this.iframe.src;this.iframe.src=e}}getIframe(){return this.iframe}}function h(r){return new n(r)}const l={TeachariumEmbed:n,embedLesson:h};o.TeachariumEmbed=n,o.default=l,o.embedLesson=h,Object.defineProperties(o,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teacharium/embed-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK for embedding Teacharium lessons via iframe",
   "type": "module",
   "files": [