@teacharium/embed-sdk 0.1.0

package/README.md

@@ -0,0 +1,252 @@
+# Teacharium Embed SDK
+
+A lightweight JavaScript SDK for embedding Teacharium lessons into any website using secure iframe-based embedding.
+
+## Installation
+
+```bash
+npm install @teacharium/embed-sdk
+```
+
+Or use directly via CDN:
+
+```html
+<script src="https://unpkg.com/@teacharium/embed-sdk@latest/dist/teacharium-embed-sdk.umd.js"></script>
+```
+
+## Quick Start
+
+### 1. Obtain a JWT Token
+
+First, generate a signed token from your backend using the Teacharium API:
+
+```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'
+    },
+    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.
+
+### 2. Embed the Lesson
+
+```html
+<div id="lesson-container"></div>
+
+<script type="module">
+  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)
+  });
+</script>
+```
+
+### Using UMD (Browser Global)
+
+```html
+<div id="lesson-container"></div>
+
+<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',
+    onComplete: (data) => {
+      console.log('Lesson completed!', data);
+    }
+  });
+</script>
+```
+
+## API Reference
+
+### `embedLesson(options: EmbedOptions)`
+
+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)
+- `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"
+- `className` (optional): Additional CSS classes for the iframe
+- `onLoad` (optional): Callback when lesson loads
+- `onComplete` (optional): Callback when lesson is completed
+- `onProgress` (optional): Callback for progress updates
+- `onError` (optional): Callback for errors
+
+**Returns:** `TeachariumEmbed` instance
+
+### `TeachariumEmbed` Methods
+
+#### `destroy()`
+Removes the embedded lesson from the page.
+
+```javascript
+embed.destroy();
+```
+
+#### `reload()`
+Reloads the embedded lesson.
+
+```javascript
+embed.reload();
+```
+
+#### `postMessage(type: string, payload?: any)`
+Send a custom message to the embedded lesson.
+
+```javascript
+embed.postMessage('custom:action', { data: 'value' });
+```
+
+#### `getIframe()`
+Get the iframe element.
+
+```javascript
+const iframe = embed.getIframe();
+```
+
+## Events
+
+### onLoad
+Fired when the lesson iframe has loaded.
+
+```javascript
+onLoad: () => {
+  console.log('Lesson is ready');
+}
+```
+
+### onComplete
+Fired when the user completes the lesson.
+
+```javascript
+onComplete: (data) => {
+  // data.lessonId - The lesson ID
+  // data.completedAt - ISO timestamp
+  // data.score - Optional score
+  // data.totalSteps - Total number of steps
+}
+```
+
+### onProgress
+Fired when the user progresses through the lesson.
+
+```javascript
+onProgress: (data) => {
+  // data.currentStep - Current step number
+  // 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);
+}
+```
+
+## Security
+
+- Always generate tokens on your backend, never expose API keys in client-side code
+- Tokens expire based on the `timeout` parameter (default 2 hours, max 24 hours)
+- Tokens are tied to specific lessons 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}%`;
+  }
+});
+```
+
+### React Example
+
+```jsx
+import { useEffect, useRef } from 'react';
+import { embedLesson } from '@teacharium/embed-sdk';
+
+function LessonEmbed({ token }) {
+  const containerRef = useRef(null);
+  const embedRef = useRef(null);
+
+  useEffect(() => {
+    if (containerRef.current && token) {
+      embedRef.current = embedLesson({
+        container: containerRef.current,
+        token: token,
+        // lessonId and baseUrl are automatically handled
+        onComplete: (data) => {
+          console.log('Lesson completed!', data);
+        }
+      });
+    }
+
+    return () => {
+      if (embedRef.current) {
+        embedRef.current.destroy();
+      }
+    };
+  }, [token]);
+
+  return <div ref={containerRef} style={{ width: '100%', height: '600px' }} />;
+}
+```
+
+## License
+
+MIT

package/dist/main.d.ts

@@ -0,0 +1 @@
+export {}

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

@@ -0,0 +1,127 @@
+function a(o) {
+  try {
+    const e = o.split(".");
+    if (e.length !== 3)
+      throw new Error("Invalid token format");
+    const t = e[1].replace(/-/g, "+").replace(/_/g, "/"), r = decodeURIComponent(
+      atob(t).split("").map((n) => "%" + ("00" + n.charCodeAt(0).toString(16)).slice(-2)).join("")
+    );
+    return JSON.parse(r);
+  } catch {
+    throw new Error("Failed to decode JWT token");
+  }
+}
+class i {
+  iframe = null;
+  container = null;
+  options;
+  constructor(e) {
+    let s;
+    try {
+      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;
+    }
+    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);
+        }
+    });
+  }
+  /**
+   * Remove the embedded lesson from the page
+   */
+  destroy() {
+    this.iframe && this.iframe.parentNode && (this.iframe.parentNode.removeChild(this.iframe), this.iframe = null);
+  }
+  /**
+   * Send a message to the embedded lesson
+   * @param type The message type
+   * @param payload The message payload
+   */
+  postMessage(e, s) {
+    if (!this.iframe || !this.iframe.contentWindow) {
+      console.warn("Cannot post message: iframe not ready");
+      return;
+    }
+    const t = { type: e, payload: s }, r = new URL(this.options.baseUrl).origin;
+    this.iframe.contentWindow.postMessage(t, r);
+  }
+  /**
+   * Reload the embedded lesson
+   */
+  reload() {
+    this.iframe && (this.iframe.src = this.iframe.src);
+  }
+  /**
+   * Get the iframe element
+   */
+  getIframe() {
+    return this.iframe;
+  }
+}
+function h(o) {
+  return new i(o);
+}
+const l = {
+  TeachariumEmbed: i,
+  embedLesson: h
+};
+export {
+  i as TeachariumEmbed,
+  l as default,
+  h as embedLesson
+};

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

@@ -0,0 +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"}})}));

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@teacharium/embed-sdk",
+  "version": "0.1.0",
+  "description": "SDK for embedding Teacharium lessons via iframe",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/teacharium-embed-sdk.umd.js",
+  "module": "dist/teacharium-embed-sdk.es.js",
+  "types": "dist/main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/teacharium-embed-sdk.es.js",
+      "require": "./dist/teacharium-embed-sdk.umd.js"
+    }
+  },
+  "keywords": [
+    "teacharium",
+    "embed",
+    "iframe",
+    "lessons",
+    "elearning"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "eslint": "^9.35.0",
+    "globals": "^16.4.0",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.43.0",
+    "vite": "^7.1.5",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "scripts": {
+    "dev": "tsc -b && vite build --watch",
+    "build:watch": "tsc -b && vite build --watch",
+    "build": "tsc -b && vite build",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}