Skip to main content

​
Overview

The @timeback/case package provides a client for the CASE (Competency and Academic Standards Exchange) API, enabling:
  • Documents: List and retrieve curriculum framework documents
  • Items: List and retrieve individual competencies and learning objectives
  • Associations: Retrieve relationships between CASE entities
  • Packages: Upload, update, and retrieve complete framework bundles

​
Installation

npm install @timeback/case

​
Quick Start

import { CaseClient } from '@timeback/case'

const client = new CaseClient({
	env: 'staging',
	auth: {
		clientId: process.env.CASE_CLIENT_ID!,
		clientSecret: process.env.CASE_CLIENT_SECRET!,
	},
})

// List all framework documents
const { CFDocuments } = await client.documents.list()

// Get a specific item
const { CFItem } = await client.items.get('item-sourced-id')

// Upload a framework package
const result = await client.packages.create(packageInput)

​
Documents

Curriculum framework documents — the top-level containers for standards. 
client.documents.list()
client.documents.list({ limit: 50, offset: 0 })
client.documents.get(sourcedId)
MethodReturnsDescription
list(){ CFDocuments: CFDocument[] }List all framework documents
get(){ CFDocument: CFDocument }Get a document by sourcedId

​
Items

Individual competencies, standards, and learning objectives within a framework. 
client.items.list()
client.items.list({ limit: 100, offset: 0 })
client.items.get(sourcedId)
MethodReturnsDescription
list(){ CFItems: CFItem[] }List all framework items
get(){ CFItem: CFItem }Get an item by sourcedId

​
Associations

Relationships between CASE entities (e.g., “is child of”, “is related to”). 
client.associations.get(sourcedId)
MethodReturnsDescription
get(){ CFAssociation: CFAssociation }Get an association by sourcedId

​
Packages

Complete framework bundles containing documents, items, and associations. Supports Zod schema validation on inputs.

​
Upload a Package

const result = await client.packages.create({
	CFDocument: {
		identifier: 'doc-id',
		uri: 'https://example.edu/frameworks/math-k12',
		title: 'K-12 Math Standards',
		creator: 'Example District',
		// ... additional document fields
	},
	CFItems: [
		{
			identifier: 'item-1',
			uri: 'https://example.edu/frameworks/math-k12/items/1',
			fullStatement: 'Understand addition within 20',
			// ... additional item fields
		},
	],
	CFAssociations: [
		// ... relationships between items
	],
})

​
All Package Methods

client.packages.create(packageInput)
client.packages.update(sourcedId, packageInput)
client.packages.upsert(sourcedId, packageInput)
client.packages.get(sourcedId)
client.packages.getGroups(sourcedId)
MethodReturnsDescription
create()CFPackageUploadResultUpload a complete framework package
update()CFPackageUploadResultReplace a package by sourcedId
upsert()CFPackageUploadResultCreate or replace a package
get(){ CFPackage: CFPackage }Get a package by sourcedId
getGroups(){ CFPackageWithGroups: CFPackageWithGroups }Get a package with hierarchical groups

​
Standalone vs Composed

The client works standalone or composed into @timeback/core: 
// Standalone
import { CaseClient } from '@timeback/case'
const client = new CaseClient({ env: 'staging', auth })

// Composed
import { TimebackClient } from '@timeback/core'
const timeback = new TimebackClient({ env: 'staging', auth })
timeback.case.documents.list()

​
Error Handling

import { CaseError, NotFoundError } from '@timeback/case/errors'

try {
	await client.documents.get('invalid-id')
} catch (error) {
	if (error instanceof NotFoundError) {
		console.log('Document not found')
	} else if (error instanceof CaseError) {
		console.log(error.statusCode)
		console.log(error.message)
	}
}

​
Configuration

new CaseClient({
	// Environment mode (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)
})

​
Next Steps

CLR

Comprehensive Learner Records

OneRoster

Rostering and enrollments

Types

CASE type definitions