Core

Overview

The Core client (@timeback/core for TypeScript, timeback-core for Python) provides a unified client that aggregates all Timeback API clients with shared OAuth authentication:

OneRoster: Rostering and gradebook data
EduBridge: Simplified enrollments and analytics
Caliper: Learning analytics events
QTI: Assessment content management
PowerPath: Placement tests and adaptive learning
CASE: Competencies and standards
CLR: Comprehensive Learner Records
Webhooks: Webhook management and filters
MasteryTrack: Test inventory and assignments

All sub-clients share a single OAuth token, reducing authentication overhead.

Installation

npm install @timeback/core

pnpm add @timeback/core

yarn add @timeback/core

bun add @timeback/core

pip install timeback-core

uv add timeback-core

Quick Start

import { TimebackClient } from '@timeback/core'

const timeback = new TimebackClient({
	env: 'staging',
	auth: {
		clientId: process.env.TIMEBACK_CLIENT_ID!,
		clientSecret: process.env.TIMEBACK_CLIENT_SECRET!,
	},
})

// Access any API through the unified client
const { data: schools } = await timeback.oneroster.schools.list()
const { data: users } = await timeback.oneroster.users.list({ where: { role: 'student' } })
await timeback.caliper.events.sendActivity(sensorUrl, activityInput)

from timeback_core import TimebackClient

timeback = TimebackClient(
    env="staging",
    client_id=os.environ["TIMEBACK_CLIENT_ID"],
    client_secret=os.environ["TIMEBACK_CLIENT_SECRET"],
)

# Access any API through the unified client
schools = await timeback.oneroster.schools.list()
users = await timeback.oneroster.users.list(where={"role": "student"})
await timeback.caliper.events.send_activity(sensor_url, activity_input)

Configuration

Environment Mode

Connect to Timeback’s hosted APIs:

const timeback = new TimebackClient({
	env: 'staging', // or 'production'
	auth: {
		clientId: process.env.TIMEBACK_CLIENT_ID!,
		clientSecret: process.env.TIMEBACK_CLIENT_SECRET!,
	},
})

timeback = TimebackClient(
    env="staging",  # or "production"
    client_id=os.environ["TIMEBACK_CLIENT_ID"],
    client_secret=os.environ["TIMEBACK_CLIENT_SECRET"],
)

Base URL Mode

Connect to a self-hosted or custom endpoint:

const timeback = new TimebackClient({
	baseUrl: 'https://timeback.myschool.edu',
	auth: {
		clientId: process.env.CLIENT_ID!,
		clientSecret: process.env.CLIENT_SECRET!,
		authUrl: 'https://timeback.myschool.edu/oauth/token',
	},
})

timeback = TimebackClient(
    services={
        "oneroster": "https://timeback.myschool.edu",
        "edubridge": "https://timeback.myschool.edu",
        "caliper": "https://timeback.myschool.edu",
    },
    auth_url="https://timeback.myschool.edu/oauth/token",
    client_id=os.environ["CLIENT_ID"],
    client_secret=os.environ["CLIENT_SECRET"],
)

Explicit Services Mode

Full control over each service URL. Only configure the services you need:

const timeback = new TimebackClient({
	services: {
		oneroster: 'https://roster.example.com',
		caliper: 'https://analytics.example.com',
		// edubridge not configured — accessing it will throw
	},
	auth: {
		clientId: '...',
		clientSecret: '...',
		authUrl: 'https://auth.example.com/oauth/token',
	},
})

timeback = TimebackClient(
    services={
        "oneroster": "https://roster.example.com",
        "caliper": "https://analytics.example.com",
        "qti": "https://qti.example.com",
        "powerpath": "https://roster.example.com",
        "case": "https://roster.example.com",
        "clr": "https://roster.example.com",
        "webhooks": "https://analytics.example.com",
    },
    auth_url="https://auth.example.com/oauth/token",
    client_id="...",
    client_secret="...",
)

Each service can optionally override the default token URL (TypeScript):

const timeback = new TimebackClient({
	services: {
		oneroster: 'https://roster.example.com',
		caliper: {
			baseUrl: 'https://analytics.example.com',
			authUrl: 'https://analytics-auth.example.com/token',
		},
	},
	auth: {
		clientId: '...',
		clientSecret: '...',
		authUrl: 'https://auth.example.com/oauth/token',
	},
})

Accessing APIs

Each API is lazily initialized on first access:

// OneRoster - rostering and gradebook
timeback.oneroster.users.list()
timeback.oneroster.schools.get(schoolId)
timeback.oneroster.enrollments.list({ where: { role: 'student' } })

// EduBridge - simplified enrollments and analytics
timeback.edubridge.enrollments.list({ userId })
timeback.edubridge.analytics.getActivity({ studentId, startDate, endDate })

// Caliper - learning analytics
timeback.caliper.events.list()
timeback.caliper.events.sendActivity(sensor, input)

// QTI - assessment content
timeback.qti.assessmentItems.list()
timeback.qti.assessmentTests.get(testId)

// PowerPath - adaptive learning
timeback.powerpath.placement.getCurrentLevel({ student, subject })

// CASE - competencies and standards
timeback.case.documents.list()

// CLR - comprehensive learner records
timeback.clr.credentials.upsert(credential)

// Webhooks - webhook management
timeback.webhooks.webhooks.list()

# OneRoster - rostering and gradebook
await timeback.oneroster.users.list()
await timeback.oneroster.schools.get(school_id)
await timeback.oneroster.enrollments.list(where={"role": "student"})

# EduBridge - simplified enrollments and analytics
await timeback.edubridge.enrollments.list(user_id=user_id)
await timeback.edubridge.analytics.get_activity(student_id=user_id, start_date="...", end_date="...")

# Caliper - learning analytics
await timeback.caliper.events.list()
await timeback.caliper.events.send_activity(sensor, input)

# QTI - assessment content
await timeback.qti.assessment_items.list()
await timeback.qti.assessment_tests.get(test_id)

# PowerPath - adaptive learning
await timeback.powerpath.placement.get_current_level({"student": student_id, "subject": "Math"})

# CASE - competencies and standards (note: case_ avoids Python keyword conflict)
await timeback.case_.documents.list()

# CLR - comprehensive learner records
await timeback.clr.credentials.upsert(credential_input)

# Webhooks - webhook management
await timeback.webhooks.webhooks.list()

Managing Multiple Clients

For applications that need to manage multiple TimebackClient instances, use TimebackManager:

import { TimebackManager } from '@timeback/core'

const manager = new TimebackManager()
	.register('alpha', {
		env: 'production',
		auth: { clientId: '...', clientSecret: '...' },
	})
	.register('beta', {
		env: 'production',
		auth: { clientId: '...', clientSecret: '...' },
	})

// Target a specific platform
const users = await manager.get('alpha').oneroster.users.list()

// Sync a user across all platforms (uses Promise.allSettled — never throws)
const results = await manager.broadcast(client => client.oneroster.users.create(user))

// Direct property access
if (results.alpha.ok) {
	console.log('Created on alpha:', results.alpha.value.id)
}

// Convenience methods
if (results.allSucceeded) {
	console.log('Synced to all platforms!')
}

results.succeeded.forEach(([name, user]) => {
	console.log(`Created on ${name}:`, user.id)
})

results.failed.forEach(([name, error]) => {
	console.error(`Failed on ${name}:`, error.message)
})

Manager API

Method	Description
`register(name, config)`	Add a named client
`get(name)`	Retrieve a client by name
`has(name)`	Check if a client is registered
`names`	Get all registered client names
`size`	Get number of registered clients
`broadcast(fn)`	Execute on all clients (never throws), returns `BroadcastResults<T>`
`unregister(name)`	Remove and close a client
`close()`	Close all clients

BroadcastResults API

Property/Method	Description
`succeeded`	Get successful results as `[name, value][]`
`failed`	Get failed results as `[name, error][]`
`allSucceeded`	`true` if all operations succeeded
`anyFailed`	`true` if any operation failed
`values()`	Get all values (throws if any failed)

Lifecycle

Check Authentication

Verify OAuth credentials are working:

const result = await timeback.checkAuth()

if (result.ok) {
	console.log('Auth OK, latency:', result.latencyMs, 'ms')
} else {
	console.error('Auth failed:', result.error)
}

result = await timeback.check_auth()

if result["ok"]:
    print("Auth OK, latency:", result["latency_ms"], "ms")
else:
    print("Auth failed:", result.get("error"))

Close the Client

Release resources when done:

timeback.close()

// After close(), further API calls will throw
console.log(timeback.closed) // true

await timeback.close()

# Or use as an async context manager
async with TimebackClient(...) as timeback:
    schools = await timeback.oneroster.schools.list()

Next Steps

OneRoster

Rostering and gradebook API

EduBridge

Simplified enrollments and analytics

Caliper

Learning analytics events

SDK

Full-stack SDK with SSO and activity tracking

Getting Started

CLI

SDK

Reference

Overview

Installation

Quick Start

Configuration

Environment Mode

Base URL Mode

Explicit Services Mode

Accessing APIs

Managing Multiple Clients

Manager API

BroadcastResults API

Lifecycle

Check Authentication

Close the Client

Next Steps

OneRoster

EduBridge

Caliper

SDK

​Overview

​Installation

​Quick Start

​Configuration

​Environment Mode

​Base URL Mode

​Explicit Services Mode

​Accessing APIs

​Managing Multiple Clients

​Manager API

​BroadcastResults API

​Lifecycle

​Check Authentication

​Close the Client

​Next Steps

OneRoster

EduBridge

Caliper

SDK

Overview

Installation

Quick Start

Configuration

Environment Mode

Base URL Mode

Explicit Services Mode

Accessing APIs

Managing Multiple Clients

Manager API

BroadcastResults API

Lifecycle

Check Authentication

Close the Client

Next Steps