@eduware/oneroster

v1.2.6

Published

8 hours ago

A TypeScript/JavaScript SDK for the OneRoster API standard - manage students, teachers, classes, enrollments, and academic data for K-12 education systems

@eduware/oneroster

Type-safe TypeScript SDK for the OneRoster API with LMS-specific client profiles.

Features

OneRoster v1.1 and v1.2 support
LMS-specific client profiles (read-only vs full CRUD)
Custom profiles: create your own profiles with TypeScript Pick<>
OAuth 2.0 (v1.2) and OAuth 1.0a (v1.1)
Automatic pagination with async iterables
TypeScript-first with comprehensive types
Tree-shakeable standalone functions for small bundles

Installation

# npm
npm add @eduware/oneroster

# pnpm
pnpm add @eduware/oneroster

# yarn
yarn add @eduware/oneroster zod

# bun
bun add @eduware/oneroster

Note: Yarn does not install peer dependencies automatically. Install zod manually.

Changelog

See CHANGELOG.md for release notes and breaking changes.

Quick Start (recommended)

The main entry point is the full client:

import { OneRoster } from '@eduware/oneroster';

const client = new OneRoster({
    serverURL: 'https://your-oneroster-server.com',
    security: {
        clientID: process.env.ONEROSTER_CLIENT_ID!,
        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
        tokenURL: 'https://your-oneroster-server.com/oauth/token',
    },
});

const user = await client.usersManagement.getUser({
    sourcedId: 'user-id',
});

const schools = await client.schoolsManagement.getAllSchools({});
for await (const page of schools) {
    console.log(page.result.orgs);
}

ClassLink Example (read-only profile)

Show LMS integrations explicitly by using the ClassLink client, which only exposes read endpoints:

import { ClassLink } from '@eduware/oneroster/clients';

const client = new ClassLink({
    serverURL: 'https://example.classlink.com',
    security: {
        authType: 'bearer',
        bearerToken: process.env.CLASSLINK_BEARER_TOKEN!,
    },
});

// Read operations are available
const users = await client.usersManagement.getAllUsers({});

// Write operations are not available (TypeScript error)
// await client.usersManagement.createUser({ ... });

Custom Profile Example (your LMS)

Define a profile that matches your LMS contract by picking only the methods you need:

import { OneRoster } from '@eduware/oneroster';
import type { OneRosterClient } from '@eduware/oneroster/clients';
import type { UsersManagement, ClassesManagement } from '@eduware/oneroster';

interface CustomProfile {
    usersManagement: Pick<UsersManagement, 'getAllUsers' | 'getUser'>;
    classesManagement: Pick<ClassesManagement, 'getAllClasses' | 'getClass'>;
}

const client: OneRosterClient<CustomProfile> = new OneRoster({
    serverURL: 'https://your-roster-server.com',
    security: {
        clientID: process.env.ONEROSTER_CLIENT_ID!,
        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
        tokenURL: 'https://your-roster-server.com/oauth/token',
    },
});

const users = await client.usersManagement.getAllUsers({});

This SDK works with any OneRoster-compliant LMS and includes profiles for common integrations.

Recommended Import Path

Most users only need the main client:

import { OneRoster } from '@eduware/oneroster';

Operation types use @eduware/oneroster/types:

import type { GetAllUsersUser, GetAllSchoolsOrg } from '@eduware/oneroster/types';

Model types live at @eduware/oneroster/models:

import type { User } from '@eduware/oneroster/models';

Enums live at @eduware/oneroster/enums:

import { UserRole } from '@eduware/oneroster/enums';

Advanced import paths (standalone functions) are documented later in this README.

Client Structure

The SDK is organized by management modules, grouped by domain:

Rostering

usersManagement
studentsManagement
teachersManagement
classesManagement
coursesManagement
enrollmentsManagement
schoolsManagement
organizationsManagement

Academic Calendar

academicSessionsManagement
termsManagement
gradingPeriodsManagement

Gradebook

lineItemsManagement
resultsManagement
categoriesManagement
scoreScalesManagement

Resources

resourcesManagement
courseComponentsManagement
courseComponentResourcesManagement

Assessments

assessmentLineItemsManagement
assessmentResultsManagement

Demographics

demographicsManagement

Common Operations

// List with pagination
const users = await client.usersManagement.getAllUsers({ limit: 100 });
for await (const page of users) {
    console.log(page.result.users);
}

// Get by sourcedId
const student = await client.studentsManagement.getStudent({ sourcedId: 'student-id' });

// Create
await client.coursesManagement.createCourse({
    course: {
        title: 'Algebra I',
        org: { sourcedId: 'school-id' },
    },
});

// Update
await client.classesManagement.updateClass({
    sourcedId: 'class-id',
    class: { title: 'Math 101 - Period 2' },
});

// Delete
await client.organizationsManagement.deleteOrg({ sourcedId: 'org-id' });

Filtering and Sorting

import { OrderBy } from '@eduware/oneroster/enums';

const activeUsers = await client.usersManagement.getAllUsers({
    filter: "status='active'",
    sort: 'familyName',
    orderBy: OrderBy.Asc,
});

const teachers = await client.usersManagement.getAllUsers({
    filter: "role='teacher' AND status='active'",
});

const searchByEmail = await client.usersManagement.getAllUsers({
    search: '[email protected]',
    fields: 'sourcedId,username,email',
});

Pagination and Total Count

List operations return an async iterator. If the provider sets X-Total-Count, it is exposed as totalCount.

const pages = await client.usersManagement.getAllUsers({ limit: 200, offset: 0 });

for await (const page of pages) {
    console.log('page count', page.result.users.length);
    console.log('total count', page.totalCount);
}

Nested Query Patterns

Use the module methods that reflect OneRoster relationships:

// School -> class -> enrollments
const classes = await client.schoolsManagement.getClassesForSchool({ sourcedId: 'school-id' });
const enrollments = await client.schoolsManagement.getEnrollmentsForClassInSchool({
    schoolSourcedId: 'school-id',
    classSourcedId: 'class-id',
});

// Teacher -> classes
const teaching = await client.teachersManagement.getClassesForTeacher({
    sourcedId: 'teacher-id',
});

// Class -> line items -> results
const lineItems = await client.classesManagement.getLineItemsForClass({ sourcedId: 'class-id' });
const results = await client.classesManagement.getResultsForLineItemForClass({
    classSourcedId: 'class-id',
    lineItemSourcedId: 'line-item-id',
});

OneRoster Versions

The SDK supports both OneRoster v1.1 and v1.2. Default is v1.2.

v1.2 (OAuth 2.0)

const client = new OneRoster({
    serverURL: 'https://your-server.com',
    security: {
        clientID: process.env.ONEROSTER_CLIENT_ID!,
        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
        tokenURL: 'https://your-server.com/oauth/token',
    },
});

v1.1 (OAuth 1.0a)

const client = new OneRoster({
    serverURL: 'https://your-server.com',
    oneRosterVersion: '1.1',
    security: {
        authType: 'oauth1',
        clientID: process.env.ONEROSTER_CLIENT_ID!,
        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
    },
});

Bearer Token (provider-specific)

const client = new OneRoster({
    serverURL: 'https://your-server.com',
    security: {
        authType: 'bearer',
        bearerToken: process.env.ONEROSTER_BEARER_TOKEN!,
    },
});

Error Handling

import { OneRoster, OneRosterError, NotFoundResponseError } from '@eduware/oneroster';

const client = new OneRoster({
    /* ... */
});

try {
    await client.usersManagement.getUser({ sourcedId: 'missing-id' });
} catch (error) {
    if (error instanceof NotFoundResponseError) {
        console.log('User not found');
    } else if (error instanceof OneRosterError) {
        console.log('HTTP Error:', error.statusCode, error.message);
    }
}

Standalone Functions (tree-shaking)

Use standalone functions for minimal bundles or serverless environments:

import { OneRosterCore } from '@eduware/oneroster/core.js';
import { usersManagementGetAllUsers } from '@eduware/oneroster/funcs/usersManagementGetAllUsers.js';

const core = new OneRosterCore({
    security: {
        clientID: process.env.ONEROSTER_CLIENT_ID!,
        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
    },
});

const result = await usersManagementGetAllUsers(core, {});
if (result.ok) {
    for await (const page of result.value) {
        console.log(page.result.users);
    }
}

See FUNCTIONS.md for the full list.

Function Index (by Module)

Each function maps to @eduware/oneroster/funcs/<name>.js.

academicSessionsManagement

academicSessionsManagementDeleteAcademicSession
academicSessionsManagementGetAcademicSession
academicSessionsManagementGetAllAcademicSessions
academicSessionsManagementPostAcademicSession
academicSessionsManagementPutAcademicSession

assessmentLineItemsManagement

assessmentLineItemsManagementCreateAssessmentLineItem
assessmentLineItemsManagementDeleteAssessmentLineItem
assessmentLineItemsManagementGetAllAssessmentLineItems
assessmentLineItemsManagementGetAssessmentLineItem
assessmentLineItemsManagementUpdateAssessmentLineItem

assessmentResultsManagement

assessmentResultsManagementCreateAssessmentResult
assessmentResultsManagementDeleteAssessmentResult
assessmentResultsManagementGetAllAssessmentResults
assessmentResultsManagementGetAssessmentResult
assessmentResultsManagementUpdateAssessmentResult

categoriesManagement

categoriesManagementCreateCategory
categoriesManagementDeleteCategory
categoriesManagementGetAllCategories
categoriesManagementGetCategory
categoriesManagementUpdateCategory

classesManagement

classesManagementAddStudentToClass
classesManagementAddTeacherToClass
classesManagementCreateClass
classesManagementDeleteClass
classesManagementGetAllClasses
classesManagementGetCategoriesForClass
classesManagementGetClass
classesManagementGetClassesForStudent
classesManagementGetClassesForTeacher
classesManagementGetClassesForTerm
classesManagementGetClassesForUser
classesManagementGetLineItemsForClass
classesManagementGetResultsForClass
classesManagementGetResultsForLineItemForClass
classesManagementGetResultsForStudentForClass
classesManagementGetScoreScalesForClass
classesManagementGetStudentsForClass
classesManagementGetTeachersForClass
classesManagementPostResultsForAcademicSessionForClass
classesManagementUpdateClass

coursesManagement

coursesManagementCreateComponentResource
coursesManagementCreateCourse
coursesManagementCreateCourseComponent
coursesManagementDeleteComponentResource
coursesManagementDeleteCourse
coursesManagementDeleteCourseComponent
coursesManagementGetAllComponentResources
coursesManagementGetAllCourseComponents
coursesManagementGetAllCourses
coursesManagementGetClassesForCourse
coursesManagementGetComponentResource
coursesManagementGetCourse
coursesManagementGetCourseComponent
coursesManagementPutComponentResource
coursesManagementPutCourse
coursesManagementPutCourseComponent

demographicsManagement

demographicsManagementDeleteDemographics
demographicsManagementGetAllDemographics
demographicsManagementGetDemographics
demographicsManagementPostDemographics
demographicsManagementPutDemographics

enrollmentsManagement

enrollmentsManagementCreateEnrollment
enrollmentsManagementDeleteEnrollment
enrollmentsManagementGetAllEnrollments
enrollmentsManagementGetEnrollment
enrollmentsManagementUpdateEnrollment

gradingPeriodsManagement

gradingPeriodsManagementCreateGradingPeriod
gradingPeriodsManagementDeleteGradingPeriod
gradingPeriodsManagementGetAllGradingPeriods
gradingPeriodsManagementGetGradingPeriod
gradingPeriodsManagementUpdateGradingPeriod

lineItemsManagement

lineItemsManagementCreateLineItem
lineItemsManagementCreateResultForLineItem
lineItemsManagementDeleteLineItem
lineItemsManagementGetAllLineItems
lineItemsManagementGetLineItem
lineItemsManagementUpdateLineItem

organizationsManagement

organizationsManagementCreateOrg
organizationsManagementDeleteOrg
organizationsManagementGetAllOrgs
organizationsManagementGetOrg
organizationsManagementUpdateOrg

resourcesManagement

resourcesManagementCreateResource
resourcesManagementDeleteResource
resourcesManagementExportResourceToCommonCartridge
resourcesManagementGetAllResources
resourcesManagementGetResource
resourcesManagementGetResourcesForClass
resourcesManagementGetResourcesForCourse
resourcesManagementGetResourcesForUser
resourcesManagementUpdateResource

resultsManagement

resultsManagementCreateResult
resultsManagementDeleteResult
resultsManagementGetAllResults
resultsManagementGetResult
resultsManagementUpdateResult

schoolsManagement

schoolsManagementCreateLineItemsForSchool
schoolsManagementCreateSchool
schoolsManagementDeleteSchool
schoolsManagementGetAllSchools
schoolsManagementGetClassesForSchool
schoolsManagementGetCoursesForSchool
schoolsManagementGetEnrollmentsForClassInSchool
schoolsManagementGetEnrollmentsForSchool
schoolsManagementGetLineItemsForSchool
schoolsManagementGetSchool
schoolsManagementGetStudentsForClassInSchool
schoolsManagementGetStudentsForSchool
schoolsManagementGetTeachersForClassInSchool
schoolsManagementGetTeachersForSchool
schoolsManagementGetTermsForSchool
schoolsManagementUpdateSchool

scoreScalesManagement

scoreScalesManagementCreateScoreScale
scoreScalesManagementDeleteScoreScale
scoreScalesManagementGetAllScoreScales
scoreScalesManagementGetScoreScale
scoreScalesManagementGetScoreScalesForSchool
scoreScalesManagementUpdateScoreScale

studentsManagement

studentsManagementGetAllStudents
studentsManagementGetStudent

teachersManagement

teachersManagementGetAllTeachers
teachersManagementGetTeacher

termsManagement

termsManagementCreateGradingPeriodForTerm
termsManagementGetAllTerms
termsManagementGetGradingPeriodsForTerm
termsManagementGetTerm

usersManagement

usersManagementCreateUser
usersManagementDeleteUser
usersManagementGetAllUsers
usersManagementGetUser
usersManagementGetUserWithDemographics
usersManagementUpdateUser

LMS Provider Support

Support varies by LMS provider and contract. The profile you choose reflects LMS capabilities, not library limitations.

LMS Profiles

| Provider | Profile | Notes | | --------- | ----------- | -------------------------- | | OneRoster | full | All endpoints available | | ClassLink | classlink | Read-only rostering access | | (future) | coming soon | Add new LMS profiles here |

CRUD Operations by Module

| Module | ------------------------------------ | usersManagement | studentsManagement | teachersManagement | classesManagement | coursesManagement | enrollmentsManagement | schoolsManagement | organizationsManagement | academicSessionsManagement | termsManagement | gradingPeriodsManagement | demographicsManagement | lineItemsManagement | resultsManagement | categoriesManagement | scoreScalesManagement | resourcesManagement | courseComponentsManagement | courseComponentResourcesMan | assessmentLineItemsManagement | assessmentResultsManagement | Create | Read | Update | Delete | | :----: | :--: | :----: | :----: | | ✅ | ✅ | ✅ | ✅ | | — | ✅ | — | — | | — | ✅ | — | — | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | — | ✅ | — | — | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | agement | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | ✅ |

Note: — indicates the module uses parent module operations (students/teachers map to usersManagement for create/update/delete).

Example Provider Matrix (LMS-Specific)

| Module | OneRoster (Full) | ClassLink | | ------------------------------------ | :--------------: | :-------: | | usersManagement | ✅ CRUD | ✅ Read | | studentsManagement | ✅ Read | ✅ Read | | teachersManagement | ✅ Read | ✅ Read | | classesManagement | ✅ CRUD | ✅ Read | | coursesManagement | ✅ CRUD | ✅ Read | | enrollmentsManagement | ✅ CRUD | ✅ Read | | schoolsManagement | ✅ CRUD | ✅ Read | | organizationsManagement | ✅ CRUD | ✅ Read | | academicSessionsManagement | ✅ CRUD | ✅ Read | | termsManagement | ✅ Read | ✅ Read | | gradingPeriodsManagement | ✅ CRUD | ✅ Read | | demographicsManagement | ✅ CRUD | ❌ | | lineItemsManagement | ✅ CRUD | ❌ | | resultsManagement | ✅ CRUD | ❌ | | categoriesManagement | ✅ CRUD | ❌ | | scoreScalesManagement | ✅ CRUD | ❌ | | resourcesManagement | ✅ CRUD | ❌ | | courseComponentsManagement | ✅ CRUD | ❌ | | courseComponentResourcesManagement | ✅ CRUD | ❌ | | assessmentLineItemsManagement | ✅ CRUD | ❌ | | assessmentResultsManagement | ✅ CRUD | ❌ |

This matrix reflects typical provider behavior. Actual availability may vary by contract or configuration.

Advanced Import Paths

Use these only when you need them.

Runtime entrypoints

@eduware/oneroster            # Full client + common exports (recommended)
@eduware/oneroster/clients    # LMS profiles (ClassLink, custom profiles)
@eduware/oneroster/core.js    # Lightweight core client for funcs
@eduware/oneroster/funcs/*    # Standalone functions

Type-first entrypoints (prefer `import type` when you only need types)

@eduware/oneroster/models     # Data models (component schemas)
@eduware/oneroster/enums      # Shared enums (runtime + types)
@eduware/oneroster/types      # Operation request/response types (runtime alias)

MCP Server

This SDK includes an MCP (Model Context Protocol) server for AI applications.

OAuth 2.0 Configuration

{
    "mcpServers": {
        "OneRoster": {
            "command": "npx",
            "args": [
                "-y",
                "--package",
                "@eduware/oneroster",
                "--",
                "mcp",
                "start",
                "--server-url",
                "https://your-oneroster-server.com",
                "--client-id",
                "your-client-id",
                "--client-secret",
                "your-client-secret",
                "--token-url",
                "https://your-server.com/oauth/token"
            ]
        }
    }
}

ClassLink Configuration (Bearer Token)

{
    "mcpServers": {
        "OneRoster": {
            "command": "npx",
            "args": [
                "-y",
                "--package",
                "@eduware/oneroster",
                "--",
                "mcp",
                "start",
                "--server-url",
                "https://oneroster-proxy.apis.classlink.com/YOUR_TENANT_ID",
                "--auth-type",
                "bearer",
                "--bearer-token",
                "your-bearer-token",
                "--client-profile",
                "classlink"
            ]
        }
    }
}

OAuth 1.0a Configuration (v1.1)

{
    "mcpServers": {
        "OneRoster": {
            "command": "npx",
            "args": [
                "-y",
                "--package",
                "@eduware/oneroster",
                "--",
                "mcp",
                "start",
                "--server-url",
                "https://your-oneroster-server.com",
                "--auth-type",
                "oauth1",
                "--oneroster-version",
                "1.1",
                "--client-id",
                "your-client-id",
                "--client-secret",
                "your-client-secret"
            ]
        }
    }
}

MCP Arguments

| Argument | Description | Default | Required | | --------------------- | ------------------------------------------------------------- | --------- | ----------------- | | --server-url | OneRoster API server URL | — | Yes | | --auth-type | Authentication type: oauth1, oauth2, or bearer | oauth2 | No | | --client-id | OAuth client ID | — | For oauth1/oauth2 | | --client-secret | OAuth client secret | — | For oauth1/oauth2 | | --token-url | OAuth 2.0 token endpoint URL | — | For oauth2 | | --bearer-token | Pre-authenticated bearer token | — | For bearer | | --client-profile | Client profile: full (all tools) or classlink (read-only) | full | No | | --oneroster-version | OneRoster API version: 1.1 or 1.2 | 1.2 | No | | --transport | Transport protocol: stdio or sse | stdio | No | | --port | Port for SSE transport | 2718 | No | | --tool | Specific tools to mount (repeatable) | All tools | No | | --log-level | Log level: debug, info, warn, error | info | No | | --env | Environment variables (format: KEY=value, repeatable) | — | No |

API Reference

See FUNCTIONS.md for the full method list.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@eduware/oneroster

Features

Installation

Changelog

Quick Start (recommended)

ClassLink Example (read-only profile)

Custom Profile Example (your LMS)

Recommended Import Path

Client Structure

Rostering

Academic Calendar

Gradebook

Resources

Assessments

Demographics

Common Operations

Filtering and Sorting

Pagination and Total Count

Nested Query Patterns

OneRoster Versions

v1.2 (OAuth 2.0)

v1.1 (OAuth 1.0a)

Bearer Token (provider-specific)

Error Handling

Standalone Functions (tree-shaking)

Function Index (by Module)

academicSessionsManagement

assessmentLineItemsManagement

assessmentResultsManagement

categoriesManagement

classesManagement

coursesManagement

demographicsManagement

enrollmentsManagement

gradingPeriodsManagement

lineItemsManagement

organizationsManagement

resourcesManagement

resultsManagement

schoolsManagement

scoreScalesManagement

studentsManagement

teachersManagement

termsManagement

usersManagement

LMS Provider Support

LMS Profiles

CRUD Operations by Module

Example Provider Matrix (LMS-Specific)

Advanced Import Paths

Runtime entrypoints

Type-first entrypoints (prefer import type when you only need types)

MCP Server

OAuth 2.0 Configuration

ClassLink Configuration (Bearer Token)

OAuth 1.0a Configuration (v1.1)

MCP Arguments

API Reference

License

Type-first entrypoints (prefer `import type` when you only need types)