PowerPath

Overview

The @timeback/powerpath package provides a client for the PowerPath API, enabling:

Assessments: Create tests, attempts, and submit responses
Placement Tests: Determine appropriate grade level
Screening: Session management and test assignment
Lesson Plans: Course progress and lesson plan operations
Test Assignments: CRUD operations for test assignments

Installation

npm install @timeback/powerpath

pnpm add @timeback/powerpath

yarn add @timeback/powerpath

bun add @timeback/powerpath

pip install timeback-powerpath

uv add timeback-powerpath

Quick Start

import { PowerPathClient } from '@timeback/powerpath'

const client = new PowerPathClient({
	env: 'staging',
	auth: {
		clientId: process.env.POWERPATH_CLIENT_ID!,
		clientSecret: process.env.POWERPATH_CLIENT_SECRET!,
	},
})

const level = await client.placement.getCurrentLevel({ student: 'student-123', subject: 'Math' })

from timeback_powerpath import PowerPathClient

client = PowerPathClient(
    env="staging",
    client_id=os.environ["POWERPATH_CLIENT_ID"],
    client_secret=os.environ["POWERPATH_CLIENT_SECRET"],
)

level = await client.placement.get_current_level({"student": "student-123", "subject": "Math"})

Client Structure

const client = new PowerPathClient(options)

client.assessments // Tests, attempts, and responses
client.lessonPlans // Course lesson plans and progress
client.placement // Placement testing
client.screening // MAP test sessions
client.syllabus // Course structure
client.testAssignments // Test assignment CRUD

client = PowerPathClient(options)

client.assessments        # Tests, attempts, and responses
client.lesson_plans       # Course lesson plans and progress
client.placement          # Placement testing
client.screening          # MAP test sessions
client.syllabus           # Course structure
client.test_assignments   # Test assignment CRUD

Typed Responses

All methods return typed responses:

import type { ExternalTestCreateResponse, GetNextPlacementTestResponse } from '@timeback/powerpath'

const test: ExternalTestCreateResponse = await client.assessments.createExternalTestOut({
	courseId: 'course-123',
	lessonType: 'test-out',
	toolProvider: 'mastery-track',
	grades: [3],
	xp: 10,
	resourceMetadata: { subject: 'Math' },
})
console.log(test.lessonId, test.resourceId)

const next: GetNextPlacementTestResponse = await client.placement.getNextPlacementTest({
	student: 'student-123',
	subject: 'Math',
})
console.log(`${next.availableTests} tests available, next: ${next.lesson}`)

from timeback_powerpath import ExternalTestCreateResponse, GetNextPlacementTestResponse

test = await client.assessments.create_external_test_out({
    "course_id": "course-123",
    "lesson_type": "test-out",
    "tool_provider": "mastery-track",
    "grades": [3],
    "xp": 10,
    "resource_metadata": {"subject": "Math"},
})
print(test.lesson_id, test.resource_id)

next_test = await client.placement.get_next_placement_test({
    "student": "student-123",
    "subject": "Math",
})
print(f"{next_test.available_tests} tests available, next: {next_test.lesson}")

Assessments

Create and manage assessments, attempts, and responses.

Create Tests

client.assessments.createInternalTest({ studentId, subject, gradeLevel })
client.assessments.createExternalTestOut({
	courseId,
	lessonType,
	toolProvider,
	grades,
	xp,
	resourceMetadata,
})
client.assessments.createExternalPlacementTest({ studentId, subject })

await client.assessments.create_internal_test({
    "course_id": course_id,
    "lesson_type": lesson_type,
    "test_type": test_type,
    "grades": grades,
    "xp": xp,
})
await client.assessments.create_external_test_out({
    "course_id": course_id,
    "lesson_type": lesson_type,
    "tool_provider": tool_provider,
    "grades": grades,
    "xp": xp,
    "resource_metadata": resource_metadata,
})
await client.assessments.create_external_placement_test({
    "course_id": course_id,
    "tool_provider": tool_provider,
    "grades": grades,
})

Manage Attempts

client.assessments.createNewAttempt({ studentId, testId })
client.assessments.getAttempts({ studentId, testId })
client.assessments.resetAttempt({ attemptId })

await client.assessments.create_new_attempt({"student": student_id, "lesson": lesson_id})
await client.assessments.get_attempts({"student": student_id, "lesson": lesson_id})
await client.assessments.reset_attempt({"student": student_id, "lesson": lesson_id})

Questions and Responses

client.assessments.getNextQuestion({ attemptId })
client.assessments.updateStudentQuestionResponse({ attemptId, questionId, response })
client.assessments.finalStudentAssessmentResponse({ attemptId })
client.assessments.getAssessmentProgress({ studentId, testId })

await client.assessments.get_next_question({"student": student_id, "lesson": lesson_id})
await client.assessments.update_student_question_response({"student": student_id, "question": question_id, "response": response, "lesson": lesson_id})
await client.assessments.final_student_assessment_response({"student": student_id, "lesson": lesson_id})
await client.assessments.get_assessment_progress({"student": student_id, "lesson": lesson_id})

Placement

Manage placement testing and determine appropriate grade levels. All query methods take { student, subject }:

client.placement.getCurrentLevel({ student, subject })
client.placement.getAllPlacementTests({ student, subject })
client.placement.getNextPlacementTest({ student, subject })
client.placement.getSubjectProgress({ student, subject })
client.placement.resetUserPlacement({ student, subject })

await client.placement.get_current_level({"student": student, "subject": subject})
await client.placement.get_all_placement_tests({"student": student, "subject": subject})
await client.placement.get_next_placement_test({"student": student, "subject": subject})
await client.placement.get_subject_progress({"student": student, "subject": subject})
await client.placement.reset_user_placement({"student": student, "subject": subject})

Method	Returns	Description
`getCurrentLevel()`	`PlacementLevel`	Current placement grade level
`getAllPlacementTests()`	`PlacementTest[]`	All placement tests for student
`getNextPlacementTest()`	`PlacementTest`	Next recommended test
`getSubjectProgress()`	`SubjectProgress`	Progress in subject
`resetUserPlacement()`	`void`	Reset placement to start over

Screening

Manage screening sessions and results.

client.screening.getResults(userId)
client.screening.getSession(userId)
client.screening.resetSession({ userId })
client.screening.assignTest({ userId, subject })

await client.screening.get_results(user_id)
await client.screening.get_session(user_id)
await client.screening.reset_session({"user_id": user_id})
await client.screening.assign_test({"user_id": user_id, "subject": subject})

Lesson Plans

Manage lesson plans and course progress.

client.lessonPlans.get(courseId, userId)
client.lessonPlans.create({ courseId, userId, classId? })
client.lessonPlans.getCourseProgress(courseId, studentId)
client.lessonPlans.getTree(lessonPlanId)
client.lessonPlans.getStructure(lessonPlanId)
client.lessonPlans.listOperations(lessonPlanId)
client.lessonPlans.createOperations(lessonPlanId, { operation: [{ type: 'set-skipped', payload: { target: { type: 'resource', id: itemId }, value: true } }] })
client.lessonPlans.sync(lessonPlanId)
client.lessonPlans.recreate(lessonPlanId)
client.lessonPlans.deleteAll(courseId)

await client.lesson_plans.get(course_id, user_id)
await client.lesson_plans.create({"course_id": course_id, "user_id": user_id, "class_id": class_id})
await client.lesson_plans.get_course_progress(course_id, student_id)
await client.lesson_plans.get_tree(lesson_plan_id)
await client.lesson_plans.get_structure(lesson_plan_id)
await client.lesson_plans.list_operations(lesson_plan_id)
await client.lesson_plans.create_operations(lesson_plan_id, {"operation": [{"type": "set-skipped", "payload": {"target": {"type": "resource", "id": item_id}, "value": True}}]})
await client.lesson_plans.sync(lesson_plan_id)
await client.lesson_plans.recreate(lesson_plan_id)
await client.lesson_plans.delete_all(course_id)

Syllabus

client.syllabus.get(courseSourcedId)

await client.syllabus.get(course_sourced_id)

Test Assignments

CRUD operations for test assignments.

client.testAssignments.list({ studentId })
client.testAssignments.create({ studentId, testId, dueDate })
client.testAssignments.get(assignmentId)
client.testAssignments.update(assignmentId, { status })
client.testAssignments.delete(assignmentId)
client.testAssignments.bulk({ assignments: [{ studentId, testId }] })

await client.test_assignments.list({"student": student_id})
await client.test_assignments.create({"student": student_id, "subject": subject, "grade": grade})
await client.test_assignments.get(assignment_id)
await client.test_assignments.update(assignment_id, {"test_name": test_name})
await client.test_assignments.delete(assignment_id)
await client.test_assignments.bulk({"items": [{"student": student_id, "subject": subject, "grade": grade}]})

Error Handling

import { NotFoundError, PowerPathError } from '@timeback/powerpath/errors'

try {
	await client.testAssignments.get('missing-id')
} catch (error) {
	if (error instanceof NotFoundError) {
		console.log('Assignment not found')
	} else if (error instanceof PowerPathError) {
		console.log(error.statusCode)
		console.log(error.message)
	}
}

from timeback_powerpath import NotFoundError, PowerPathError

try:
    await client.test_assignments.get("missing-id")
except NotFoundError:
    print("Assignment not found")
except PowerPathError as error:
    print(error)

SDK Integration

When using the full SDK:

import { createTimeback } from '@timeback/sdk'

const timeback = await createTimeback({
	/* ... */
})

const level = await timeback.api.powerpath.placement.getCurrentLevel({
	student: 'student-123',
	subject: 'Math',
})

from timeback.server import create_server, TimebackConfig, ApiCredentials

timeback = create_server(TimebackConfig(
    env="staging",
    api=ApiCredentials(
        client_id=os.environ["TIMEBACK_API_CLIENT_ID"],
        client_secret=os.environ["TIMEBACK_API_CLIENT_SECRET"],
    ),
))

level = await timeback.api.powerpath.placement.get_current_level({
    "student": "student-123",
    "subject": "Math",
})

Next Steps

QTI

Standard assessments

Caliper

Track learning events

Types

PowerPath type definitions

Getting Started

CLI

SDK

Reference

Overview

Installation

Quick Start

Client Structure

Typed Responses

Assessments

Create Tests

Manage Attempts

Questions and Responses

Placement

Screening

Lesson Plans

Syllabus

Test Assignments

Error Handling

SDK Integration

Next Steps

QTI

Caliper

Types

​Overview

​Installation

​Quick Start

​Client Structure

​Typed Responses

​Assessments

​Create Tests

​Manage Attempts

​Questions and Responses

​Placement

​Screening

​Lesson Plans

​Syllabus

​Test Assignments

​Error Handling

​SDK Integration

​Next Steps

QTI

Caliper

Types

Overview

Installation

Quick Start

Client Structure

Typed Responses

Assessments

Create Tests

Manage Attempts

Questions and Responses

Placement

Screening

Lesson Plans

Syllabus

Test Assignments

Error Handling

SDK Integration

Next Steps