@artim-academy/lms-lesson-sdk

SDK zum Bauen externer Lesson-Apps für das Artim Academy LMS. Eine externe App wird im LMS als App registriert (Trainer → Apps → New App bzw. Course → Add Lesson → Apply), vom Platform-Administrator approved und dann als Lesson vom Typ External in einen Kurs eingebunden.

Ablauf

1. Student öffnet die External Lesson im LMS.
2. Beim ersten Mal erscheint ein Authorization-Screen (pro User, pro Tenant) mit den Scopes der App.
3. Nach Autorisierung stellt das LMS ein kurzlebiges Launch-Token aus und leitet auf die hinterlegte URL weiter:

https://deine-app.example.com/lesson?lms_token=…&lms_tenant_id=…&lms_course_id=…&lms_lesson_id=…&lms_client_id=…

4. Deine App nutzt das Token über dieses SDK, um Daten zu lesen und die Lesson zu steuern.

Installation

npm install @artim-academy/lms-lesson-sdk

Nutzung (Next.js)

Client Component

"use client"
import { LmsLessonClient } from "@artim-academy/lms-lesson-sdk"

const lms = LmsLessonClient.fromCurrentUrl()

const ctx = await lms.getContext()     // App, Tenant, Lesson, User-Id, Scopes
const lesson = await lms.getLesson()   // scope: lesson:read
const user = await lms.getUser()       // scope: user:profile
const progress = await lms.getProgress() // scope: progress:read

// Wenn der Student fertig ist:
await lms.completeLesson()             // scope: lesson:complete
lms.returnToLms()                      // zurück zur Lesson-Seite im LMS

Server (App Router)

import { LmsLessonClient } from "@artim-academy/lms-lesson-sdk"

export default async function Page({ searchParams }: { searchParams: Record<string, string> }) {
  if (!LmsLessonClient.isLaunchRequest(searchParams)) return <p>Bitte über das LMS öffnen.</p>
  const lms = LmsLessonClient.fromSearchParams(searchParams)
  const ctx = await lms.getContext()
  return <h1>Hallo, Lesson {ctx.lessonId}</h1>
}

Scopes

| Scope | Erlaubt | | --- | --- | | lesson:read | Lesson-Details lesen (getLesson) | | lesson:complete | Lesson als abgeschlossen markieren (completeLesson) | | course:read | Kursdaten lesen (getCourse) | | user:profile | Basisprofil des Studenten lesen (getUser) | | progress:read | Kursfortschritt lesen (getProgress) |

getContext() funktioniert immer (nur mit gültigem Token), unabhängig von Scopes.

Token-Lebensdauer

Launch-Tokens sind opak, an genau eine Lesson + einen User gebunden und laufen nach 2 Stunden ab. Eine abgelaufene Session erkennt man an LmsSdkError mit status === 403 — dann den Studenten über returnToLms() zurückschicken, ein erneutes Öffnen erzeugt ein frisches Token.

Build

npm install
npm run build   # dist/ (ESM + CJS + Typen)