Lesson discovery

This guide covers how to discover available lessons and start a lesson session. By the end, you will have a LessonSession object ready for the question loop.

List available lessons

Lessons are resolved from the courses defined in your config file. Call lessons.list() to fetch lessons across all configured courses:

const lessons = await timeback.lessons.list()

Each lesson includes id, name, type, and courseId. questionCount and metadata are optional.

See the reference for the full return type.

If your app configures multiple courses, you can narrow to a specific one:

const mathLessons = await timeback.lessons.list({
    course: { subject: 'Math', grade: 5 },
})

The course parameter matches against your configured courses; in other words, it’s a filter, not an override.

Where lessons come from

Lessons are derived from your course structure in OneRoster:

The SDK resolves course IDs from timeback.config.json
It lists active course components
For each component, it lists active component resources
Each resource maps to a Lesson object

This structure is created during the setup phase. Course builder tooling to manage it is in development.

Courses must be set up before lessons.list() returns results. See the onboarding guide for how to get started.

Start a lesson

Call lessons.start() with the lesson you want to begin:

const session = await timeback.lessons.start({
    lessonId: lesson.id,
    lessonType: lesson.type,
    course: { subject: 'Math', grade: 5 },
    name: lesson.name,
    forceNew: true,
})

This returns a LessonSession, a stateful object that manages the entire lesson lifecycle.

See the reference for full parameter documentation.

What happens under the hood

When you call lessons.start(), two things happen:

Server: the SDK calls PowerPath to check for an existing attempt or create a new one
Client: the SDK starts an activity tracker automatically, so TimeSpentEvent heartbeats begin immediately

The returned LessonSession retains the starting attempt metadata. Its score updates after submission and its finalized flag after completion. Provide a course or client-level defaultCourse; the SDK needs it for heartbeat attribution. The single-activity limit also applies to lessons.

See the reference for all properties and methods.

Resume vs new attempt

By default, lessons.start() resumes an existing in-progress attempt if one exists. Set forceNew: true to request a fresh attempt. The reviewed SDK catches errors while creating the attempt and can return existing progress; inspect the returned attempt before relying on this transition:

const session = await timeback.lessons.start({
    lessonId: lesson.id,
    course: { subject: 'Math', grade: 5 },
})

const session = await timeback.lessons.start({
    lessonId: lesson.id,
    course: { subject: 'Math', grade: 5 },
    forceNew: true,
})

Framework integration

Use your framework’s client adapter to initialize the client and verify the user. Load lessons from an event handler or a cancellable effect. Keep the selected course aligned with the course returned by discovery, and disable the start control while a start request is in progress. Retain the returned session in component state. Serialize transitions with the single-activity lifecycle; starting another managed lesson while a tracker remains active throws. The LessonSession is a mutable object, not framework-reactive state: trigger a render when an awaited operation returns. Your application supplies its question renderer and persistence/navigation behavior.

Getting Started

CLI

SDK

Reference

List available lessons

Where lessons come from

Start a lesson

What happens under the hood

Resume vs new attempt

Framework integration

Next steps

Question loop

Reference

Getting Started

CLI

SDK

Reference

​List available lessons

​Where lessons come from

​Start a lesson

​What happens under the hood

​Resume vs new attempt

​Framework integration

​Next steps

Question loop

Reference

List available lessons

Where lessons come from

Start a lesson

What happens under the hood

Resume vs new attempt

Framework integration

Next steps