@timeback/powerpath

@timeback/powerpath

PowerPath SDK for placement tests, lesson plans, and assessment workflows.

Installation

bun add @timeback/powerpath

Quick Start

import { PowerPathClient } from '@timeback/powerpath'

const client = new PowerPathClient({
	env: 'staging',
	auth: { clientId: 'your-client-id', clientSecret: 'your-client-secret' },
})

const { lessonPlanId } = await client.lessonPlans.create({
	courseId: 'course-123',
	userId: 'teacher-456',
})

API Design

Standalone vs Composed

// Composed
import { TimebackClient } from '@timeback/core'

// Standalone
const powerpath = new PowerPathClient({ env: 'staging', auth })

const client = new TimebackClient({ env: 'staging', auth })
client.powerpath.lessonPlans.create({ courseId, userId })

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

Typed Responses

All methods return typed responses:

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

// Create a test - returns { lessonId, resourceId }
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)

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

Configuration

new PowerPathClient({
	// Environment mode (recommended for Timeback APIs)
	env: 'staging' | 'production',
	auth: {
		clientId: string,
		clientSecret: string,
	},

	// OR explicit mode (custom API)
	baseUrl: string,
	auth: {
		clientId: string,
		clientSecret: string,
		authUrl: string,
	},

	// OR provider mode (shared auth across clients)
	provider: TimebackProvider,

	// Optional
	timeout?: number, // Request timeout in ms (default: 30000)
})

Environment variables fallback:

• POWERPATH_BASE_URL
• POWERPATH_TOKEN_URL
• POWERPATH_CLIENT_ID
• POWERPATH_CLIENT_SECRET

Debug Mode

Enable debug logging by setting DEBUG=1 or DEBUG=true:

DEBUG=1 bun run my-script.ts

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)
	}
}