CASE

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

pnpm add @timeback/case

yarn add @timeback/case

bun add @timeback/case

pip install timeback-case

uv add 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)

from timeback_case import CaseClient

client = CaseClient(
    env="staging",
    client_id=os.environ["CASE_CLIENT_ID"],
    client_secret=os.environ["CASE_CLIENT_SECRET"],
)

# List all framework documents
documents = await client.documents.list()

# Get a specific item
item = await client.items.get("item-sourced-id")

# Upload a framework package
result = await client.packages.create(package_input)

Documents

Curriculum framework documents — the top-level containers for standards.

client.documents.list()
client.documents.list({ limit: 50, offset: 0 })
client.documents.get(sourcedId)

await client.documents.list()
await client.documents.list({"limit": 50, "offset": 0})
await client.documents.get(sourced_id)

Method	Returns	Description
`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)

await client.items.list()
await client.items.list({"limit": 100, "offset": 0})
await client.items.get(sourced_id)

Method	Returns	Description
`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)

await client.associations.get(sourced_id)

Method	Returns	Description
`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
	],
})

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)

await client.packages.create(package_input)
await client.packages.update(sourced_id, package_input)
await client.packages.upsert(sourced_id, package_input)
await client.packages.get(sourced_id)
await client.packages.get_groups(sourced_id)

Method	Returns	Description
`create()`	`CFPackageUploadResult`	Upload a complete framework package
`update()`	`CFPackageUploadResult`	Replace a package by sourcedId
`upsert()`	`CFPackageUploadResult`	Create 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()

# Standalone
from timeback_case import CaseClient
client = CaseClient(env="staging", client_id=client_id, client_secret=client_secret)

# Composed (note: case_ avoids Python keyword conflict)
from timeback_core import TimebackClient
timeback = TimebackClient(env="staging", client_id=client_id, client_secret=client_secret)
await 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)
	}
}

from timeback_case import CaseError, NotFoundError

try:
    await client.documents.get("invalid-id")
except NotFoundError:
    print("Document not found")
except CaseError as error:
    print(error)

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

# Environment mode (Timeback APIs)
client = CaseClient(
    env="staging",  # or "production"
    client_id="...",
    client_secret="...",
)

# Explicit mode (custom API)
client = CaseClient(
    base_url="https://custom.example.com",
    auth_url="https://auth.example.com/oauth2/token",
    client_id="...",
    client_secret="...",
)

# Provider mode (shared auth)
from timeback_common import TimebackProvider
provider = TimebackProvider(env="staging", client_id="...", client_secret="...")
client = CaseClient(provider=provider)

# Optional
# timeout: float = 30.0 (request timeout in seconds)

Next Steps

CLR

Comprehensive Learner Records

OneRoster

Rostering and enrollments

Types

CASE type definitions

Getting Started

CLI

SDK

Reference

Overview

Installation

Quick Start

Documents

Items

Associations

Packages

Upload a Package

All Package Methods

Standalone vs Composed

Error Handling

Configuration

Next Steps

CLR

OneRoster

Types

​Overview

​Installation

​Quick Start

​Documents

​Items

​Associations

​Packages

​Upload a Package

​All Package Methods

​Standalone vs Composed

​Error Handling

​Configuration

​Next Steps

CLR

OneRoster

Types

Overview

Installation

Quick Start

Documents

Items

Associations

Packages

Upload a Package

All Package Methods

Standalone vs Composed

Error Handling

Configuration

Next Steps