@eduware/oneroster 1.2.5 → 1.2.7

package/README.md

@@ -22,13 +22,13 @@ Type-safe TypeScript SDK for the OneRoster API with LMS-specific client profiles
 
 ## Features
 
-- **OneRoster v1.1 & v1.2 support** - Complete implementation of both 1EdTech OneRoster specifications
-- **LMS-specific profiles** - Pre-built profiles for ClassLink with type-safe method restrictions
-- **Custom profiles** - Create your own profiles using TypeScript's `Pick<>` types
-- **OAuth 2.0 & OAuth 1.0a authentication** - OAuth 2.0 for v1.2 (default), OAuth 1.0a for v1.1
-- **Automatic pagination** - Async iterables for seamless data fetching
-- **TypeScript-first** - Full type safety with comprehensive type definitions
-- **Tree-shakeable** - Standalone functions for optimal bundle sizes
+- 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
 
@@ -46,9 +46,15 @@ yarn add @eduware/oneroster zod
 bun add @eduware/oneroster
 ```
 
-> **Note:** Yarn does not install peer dependencies automatically. You will need to install `zod` manually.
+> Note: Yarn does not install peer dependencies automatically. Install `zod` manually.
 
-## Quick Start
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release notes and breaking changes.
+
+## Quick Start (recommended)
+
+The main entry point is the full client:
 
 ```typescript
 import { OneRoster } from '@eduware/oneroster';
@@ -62,21 +68,19 @@ const client = new OneRoster({
     },
 });
 
-// Fetch all users with automatic pagination
-const result = await client.usersManagement.getAllUsers({});
+const user = await client.usersManagement.getUser({
+    sourcedId: 'user-id',
+});
 
-for await (const page of result) {
-    console.log(page.result.users);
+const schools = await client.schoolsManagement.getAllSchools({});
+for await (const page of schools) {
+    console.log(page.result.orgs);
 }
 ```
 
-## LMS Profiles
-
-The SDK provides LMS-specific client profiles that restrict available methods to match what each provider supports. This gives you compile-time safety and prevents calling unsupported endpoints.
-
-### ClassLink Client
+## ClassLink Example (read-only profile)
 
-ClassLink provides read-only rostering data. The `ClassLink` client is typed to only expose supported methods:
+Show LMS integrations explicitly by using the ClassLink client, which only exposes read endpoints:
 
 ```typescript
 import { ClassLink } from '@eduware/oneroster/clients';
@@ -89,248 +93,208 @@ const client = new ClassLink({
     },
 });
 
-// ✅ Read operations work
+// Read operations are available
 const users = await client.usersManagement.getAllUsers({});
-const schools = await client.schoolsManagement.getAllSchools({});
 
-// ❌ Write operations are not available (TypeScript error)
-// client.usersManagement.createUser({});  // Error: Property 'createUser' does not exist
+// Write operations are not available (TypeScript error)
+// await client.usersManagement.createUser({ ... });
 ```
 
-### Full Client
+## Custom Profile Example (your LMS)
 
-For full OneRoster access with all methods available:
+Define a profile that matches your LMS contract by picking only the methods you need:
 
 ```typescript
 import { OneRoster } from '@eduware/oneroster';
+import type { OneRosterClient } from '@eduware/oneroster/clients';
+import type { UsersManagement, ClassesManagement } from '@eduware/oneroster';
 
-const client = new OneRoster({
-    serverURL: 'https://your-oneroster-server.com',
+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-oneroster-server.com/oauth/token',
+        tokenURL: 'https://your-roster-server.com/oauth/token',
     },
 });
 
-// All operations available
 const users = await client.usersManagement.getAllUsers({});
-await client.usersManagement.createUser({
-    user: {
-        /* ... */
-    },
-});
 ```
 
-### Custom Profiles
+This SDK works with any OneRoster-compliant LMS and includes profiles for common integrations.
 
-Create your own profiles by defining an interface that uses `Pick<>` to select specific methods:
+## Recommended Import Path
+
+Most users only need the main client:
 
 ```typescript
 import { OneRoster } from '@eduware/oneroster';
-import type { UsersManagement, ClassesManagement } from '@eduware/oneroster/sdk';
-import type { OneRosterClient } from '@eduware/oneroster/clients';
+```
 
-// Define a custom profile with only the methods you need
-interface IMyCustomProfile {
-    usersManagement: Pick<UsersManagement, 'getAllUsers' | 'getUser'>;
-    classesManagement: Pick<ClassesManagement, 'getAllClasses' | 'getClass'>;
-}
+Operation types use `@eduware/oneroster/types`:
 
-// Create a typed client
-type MyCustomClient = OneRosterClient<IMyCustomProfile>;
+```typescript
+import type { GetAllUsersUser, GetAllSchoolsOrg } from '@eduware/oneroster/types';
+```
 
-const client: MyCustomClient = new OneRoster({
-    serverURL: 'https://your-server.com',
-    security: {
-        /* ... */
-    },
-});
+Model types live at `@eduware/oneroster/models`:
 
-// Only picked methods are available
-const users = await client.usersManagement.getAllUsers({});
-// client.usersManagement.createUser({});  // TypeScript error!
-```
-
-## Management Modules & LMS Support
-
-The SDK provides management modules for all OneRoster resources. Each module supports CRUD (Create, Read, Update, Delete) operations as defined by the OneRoster specification. However, **not all LMS providers support all operations** - some providers offer read-only access to rostering data.
-
-> **⚠️ Important:** The availability of operations depends on your LMS provider's implementation. The table below shows which operations are supported by each LMS. Operations marked with ❌ will result in API errors if called against providers that don't support them.
-
-### Management Modules Overview
-
-| Module                               | Description                                | Primary Resources                       |
-| ------------------------------------ | ------------------------------------------ | --------------------------------------- |
-| `usersManagement`                    | User accounts (students, teachers, admins) | Users                                   |
-| `studentsManagement`                 | Student-specific operations                | Users (role: student)                   |
-| `teachersManagement`                 | Teacher-specific operations                | Users (role: teacher)                   |
-| `classesManagement`                  | Class/section management                   | Classes                                 |
-| `coursesManagement`                  | Course catalog management                  | Courses                                 |
-| `enrollmentsManagement`              | Class enrollment records                   | Enrollments                             |
-| `schoolsManagement`                  | School/organization management             | Orgs (type: school)                     |
-| `organizationsManagement`            | All organization types                     | Orgs                                    |
-| `academicSessionsManagement`         | School years, semesters, terms             | Academic Sessions                       |
-| `termsManagement`                    | Term-specific operations                   | Academic Sessions (type: term)          |
-| `gradingPeriodsManagement`           | Grading period management                  | Academic Sessions (type: gradingPeriod) |
-| `demographicsManagement`             | Student demographic data                   | Demographics                            |
-| `lineItemsManagement`                | Gradebook assignments                      | Line Items                              |
-| `resultsManagement`                  | Student grades/scores                      | Results                                 |
-| `categoriesManagement`               | Grade categories                           | Categories                              |
-| `scoreScalesManagement`              | Grading scales                             | Score Scales                            |
-| `resourcesManagement`                | Learning resources                         | Resources                               |
-| `courseComponentsManagement`         | Course modules/units                       | Course Components                       |
-| `courseComponentResourcesManagement` | Resources linked to components             | Component Resources                     |
-| `assessmentLineItemsManagement`      | Assessment definitions                     | Assessment Line Items                   |
-| `assessmentResultsManagement`        | Assessment scores                          | Assessment Results                      |
+```typescript
+import type { User } from '@eduware/oneroster/models';
+```
 
-### CRUD Operations by Module
+Enums live at `@eduware/oneroster/enums`:
 
-| Module                               | Create | Read | Update | Delete |
-| ------------------------------------ | :----: | :--: | :----: | :----: |
-| `usersManagement`                    |   ✅   |  ✅  |   ✅   |   ✅   |
-| `studentsManagement`                 |   —    |  ✅  |   —    |   —    |
-| `teachersManagement`                 |   —    |  ✅  |   —    |   —    |
-| `classesManagement`                  |   ✅   |  ✅  |   ✅   |   ✅   |
-| `coursesManagement`                  |   ✅   |  ✅  |   ✅   |   ✅   |
-| `enrollmentsManagement`              |   ✅   |  ✅  |   ✅   |   ✅   |
-| `schoolsManagement`                  |   ✅   |  ✅  |   ✅   |   ✅   |
-| `organizationsManagement`            |   ✅   |  ✅  |   ✅   |   ✅   |
-| `academicSessionsManagement`         |   ✅   |  ✅  |   ✅   |   ✅   |
-| `termsManagement`                    |   —    |  ✅  |   —    |   —    |
-| `gradingPeriodsManagement`           |   ✅   |  ✅  |   ✅   |   ✅   |
-| `demographicsManagement`             |   ✅   |  ✅  |   ✅   |   ✅   |
-| `lineItemsManagement`                |   ✅   |  ✅  |   ✅   |   ✅   |
-| `resultsManagement`                  |   ✅   |  ✅  |   ✅   |   ✅   |
-| `categoriesManagement`               |   ✅   |  ✅  |   ✅   |   ✅   |
-| `scoreScalesManagement`              |   ✅   |  ✅  |   ✅   |   ✅   |
-| `resourcesManagement`                |   ✅   |  ✅  |   ✅   |   ✅   |
-| `courseComponentsManagement`         |   ✅   |  ✅  |   ✅   |   ✅   |
-| `courseComponentResourcesManagement` |   ✅   |  ✅  |   ✅   |   ✅   |
-| `assessmentLineItemsManagement`      |   ✅   |  ✅  |   ✅   |   ✅   |
-| `assessmentResultsManagement`        |   ✅   |  ✅  |   ✅   |   ✅   |
+```typescript
+import { UserRole } from '@eduware/oneroster/enums';
+```
 
-_Note: — indicates the module uses parent module operations (e.g., students/teachers use usersManagement for CUD)_
+Advanced import paths (standalone functions) are documented later in this README.
 
-### LMS Provider Support
+## Client Structure
 
-Different LMS providers implement different subsets of the OneRoster specification. Use this table to understand what's available for your provider:
+The SDK is organized by management modules, grouped by domain:
 
-| Module                               | OneRoster (Full) | ClassLink |
-| ------------------------------------ | :--------------: | :-------: |
-| **Core Rostering**                   |                  |           |
-| `usersManagement`                    |     ✅ CRUD      |  ✅ Read  |
-| `studentsManagement`                 |     ✅ Read      |  ✅ Read  |
-| `teachersManagement`                 |     ✅ Read      |  ✅ Read  |
-| `classesManagement`                  |     ✅ CRUD      |  ✅ Read  |
-| `coursesManagement`                  |     ✅ CRUD      |  ✅ Read  |
-| `enrollmentsManagement`              |     ✅ CRUD      |  ✅ Read  |
-| `schoolsManagement`                  |     ✅ CRUD      |  ✅ Read  |
-| `organizationsManagement`            |     ✅ CRUD      |  ✅ Read  |
-| **Academic Calendar**                |                  |           |
-| `academicSessionsManagement`         |     ✅ CRUD      |  ✅ Read  |
-| `termsManagement`                    |     ✅ Read      |  ✅ Read  |
-| `gradingPeriodsManagement`           |     ✅ CRUD      |  ✅ Read  |
-| **Demographics**                     |                  |           |
-| `demographicsManagement`             |     ✅ CRUD      |    ❌     |
-| **Gradebook**                        |                  |           |
-| `lineItemsManagement`                |     ✅ CRUD      |    ❌     |
-| `resultsManagement`                  |     ✅ CRUD      |    ❌     |
-| `categoriesManagement`               |     ✅ CRUD      |    ❌     |
-| `scoreScalesManagement`              |     ✅ CRUD      |    ❌     |
-| **Resources**                        |                  |           |
-| `resourcesManagement`                |     ✅ CRUD      |    ❌     |
-| `courseComponentsManagement`         |     ✅ CRUD      |    ❌     |
-| `courseComponentResourcesManagement` |     ✅ CRUD      |    ❌     |
-| **Assessments**                      |                  |           |
-| `assessmentLineItemsManagement`      |     ✅ CRUD      |    ❌     |
-| `assessmentResultsManagement`        |     ✅ CRUD      |    ❌     |
+### Rostering
+
+- `usersManagement`
+- `studentsManagement`
+- `teachersManagement`
+- `classesManagement`
+- `coursesManagement`
+- `enrollmentsManagement`
+- `schoolsManagement`
+- `organizationsManagement`
+
+### Academic Calendar
+
+- `academicSessionsManagement`
+- `termsManagement`
+- `gradingPeriodsManagement`
 
-**Legend:**
+### Gradebook
 
-- ✅ CRUD = Create, Read, Update, Delete all supported
-- ✅ Read = Read-only access (GET operations)
-- ❌ = Not supported by this provider
+- `lineItemsManagement`
+- `resultsManagement`
+- `categoriesManagement`
+- `scoreScalesManagement`
 
-> **Note:** This table reflects the typical capabilities of each provider. Actual availability may vary based on your specific contract, configuration, or API version. Always consult your provider's documentation for the most accurate information.
+### Resources
 
-### Nested Queries
+- `resourcesManagement`
+- `courseComponentsManagement`
+- `courseComponentResourcesManagement`
 
-Many modules support nested queries to fetch related data efficiently:
+### Assessments
+
+- `assessmentLineItemsManagement`
+- `assessmentResultsManagement`
+
+### Demographics
+
+- `demographicsManagement`
+
+## Common Operations
 
 ```typescript
-// Get all students in a specific class
-const students = await client.classesManagement.getStudentsForClass({
-    classSourcedId: 'class-123',
-});
+// List with pagination
+const users = await client.usersManagement.getAllUsers({ limit: 100 });
+for await (const page of users) {
+    console.log(page.result.users);
+}
 
-// Get all classes for a specific school
-const classes = await client.schoolsManagement.getClassesForSchool({
-    schoolSourcedId: 'school-456',
+// 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' },
+    },
 });
 
-// Get all enrollments for a class
-const enrollments = await client.classesManagement.getEnrollmentsForClass({
-    classSourcedId: 'class-123',
+// Update
+await client.classesManagement.updateClass({
+    sourcedId: 'class-id',
+    class: { title: 'Math 101 - Period 2' },
 });
+
+// Delete
+await client.organizationsManagement.deleteOrg({ sourcedId: 'org-id' });
 ```
 
-Common nested query patterns:
+## Filtering and Sorting
 
-- `schools/{id}/classes`, `schools/{id}/students`, `schools/{id}/teachers`
-- `classes/{id}/students`, `classes/{id}/teachers`, `classes/{id}/enrollments`
-- `users/{id}/classes`, `students/{id}/classes`, `teachers/{id}/classes`
-- `terms/{id}/classes`, `courses/{id}/classes`
+```typescript
+import { OrderBy } from '@eduware/oneroster/enums';
 
-## OneRoster Versions
+const activeUsers = await client.usersManagement.getAllUsers({
+    filter: "status='active'",
+    sort: 'familyName',
+    orderBy: OrderBy.Asc,
+});
 
-The SDK supports both OneRoster v1.1 and v1.2 specifications. The default is v1.2.
+const teachers = await client.usersManagement.getAllUsers({
+    filter: "role='teacher' AND status='active'",
+});
 
-### Version 1.2 (Default)
+const searchByEmail = await client.usersManagement.getAllUsers({
+    search: 'teacher@district.edu',
+    fields: 'sourcedId,username,email',
+});
+```
 
-OneRoster v1.2 uses OAuth 2.0 authentication and the `/ims/oneroster/rostering/v1p2/` path format:
+## Pagination and Total Count
+
+List operations return an async iterator. If the provider sets `X-Total-Count`, it is exposed as `totalCount`.
 
 ```typescript
-import { OneRoster } from '@eduware/oneroster';
+const pages = await client.usersManagement.getAllUsers({ limit: 200, offset: 0 });
 
-const client = new OneRoster({
-    serverURL: 'https://your-server.com',
-    // oneRosterVersion defaults to '1.2'
-    security: {
-        clientID: process.env.ONEROSTER_CLIENT_ID!,
-        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
-        tokenURL: 'https://your-server.com/oauth/token',
-    },
-});
+for await (const page of pages) {
+    console.log('page count', page.result.users.length);
+    console.log('total count', page.totalCount);
+}
 ```
 
-### Version 1.1
+## Nested Query Patterns
 
-OneRoster v1.1 uses OAuth 1.0a authentication and the `/ims/oneroster/v1p1/` path format:
+Use the module methods that reflect OneRoster relationships:
 
 ```typescript
-import { OneRoster } from '@eduware/oneroster';
+// School -> class -> enrollments
+const classes = await client.schoolsManagement.getClassesForSchool({ sourcedId: 'school-id' });
+const enrollments = await client.schoolsManagement.getEnrollmentsForClassInSchool({
+    schoolSourcedId: 'school-id',
+    classSourcedId: 'class-id',
+});
 
-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!,
-    },
+// 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',
 });
 ```
 
-> **Note:** OAuth 1.0a is only supported in OneRoster v1.1. Per the 1EdTech specification, v1.2 requires OAuth 2.0.
+## OneRoster Versions
 
-## Authentication
+The SDK supports both OneRoster v1.1 and v1.2. Default is v1.2.
 
-### OAuth 2.0 (Default for v1.2)
+### v1.2 (OAuth 2.0)
 
 ```typescript
-import { OneRoster } from '@eduware/oneroster';
-
 const client = new OneRoster({
     serverURL: 'https://your-server.com',
     security: {
@@ -341,17 +305,9 @@ const client = new OneRoster({
 });
 ```
 
-You can also use environment variables:
-
-- `ONEROSTER_CLIENT_ID`
-- `ONEROSTER_CLIENT_SECRET`
-- `ONEROSTER_TOKEN_URL`
-
-### OAuth 1.0a (v1.1 only)
+### v1.1 (OAuth 1.0a)
 
 ```typescript
-import { OneRoster } from '@eduware/oneroster';
-
 const client = new OneRoster({
     serverURL: 'https://your-server.com',
     oneRosterVersion: '1.1',
@@ -363,170 +319,388 @@ const client = new OneRoster({
 });
 ```
 
-### Bearer Token
-
-If you already have a token:
+### Bearer Token (provider-specific)
 
 ```typescript
-import { OneRoster } from '@eduware/oneroster';
-
 const client = new OneRoster({
     serverURL: 'https://your-server.com',
     security: {
         authType: 'bearer',
-        bearerToken: 'your-access-token',
+        bearerToken: process.env.ONEROSTER_BEARER_TOKEN!,
     },
 });
 ```
 
-## Pagination
-
-All list endpoints support automatic pagination using async iterables:
+## Error Handling
 
 ```typescript
-const result = await client.usersManagement.getAllUsers({
-    limit: 100, // Items per page (default: 100)
-    offset: 0, // Starting offset
+import { OneRoster, OneRosterError, NotFoundResponseError } from '@eduware/oneroster';
+
+const client = new OneRoster({
+    /* ... */
 });
 
-// Iterate through all pages automatically
-for await (const page of result) {
-    for (const user of page.result.users ?? []) {
-        console.log(user.givenName, user.familyName);
+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);
     }
 }
 ```
 
-### Total Count
+## Standalone Functions (tree-shaking)
 
-The OneRoster API returns the total number of records in the `X-Total-Count` HTTP header. This value is automatically extracted and exposed on each page result:
+Use standalone functions for minimal bundles or serverless environments:
 
 ```typescript
-const result = await client.usersManagement.getAllUsers({});
+import { OneRosterCore } from '@eduware/oneroster/core.js';
+import { usersManagementGetAllUsers } from '@eduware/oneroster/funcs/usersManagementGetAllUsers.js';
 
-// Or during iteration
-for await (const page of result) {
-    console.log(`Page has ${page.result.users?.length ?? 0} users`);
-    console.log(`Total: ${page.totalCount}`);
+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);
+    }
 }
 ```
 
-> **Note:** The `totalCount` property is `undefined` if the server does not return the `X-Total-Count` header.
+See [FUNCTIONS.md](./FUNCTIONS.md) for the full list.
 
-## Filtering & Sorting
+## Function Index (by Module)
 
-```typescript
-// Filter by status
-const activeUsers = await client.usersManagement.getAllUsers({
-    filter: "status='active'",
-});
+Each function maps to `@eduware/oneroster/funcs/<name>.js`.
 
-// Multiple filters
-const filteredUsers = await client.usersManagement.getAllUsers({
-    filter: "status='active' AND role='student'",
-});
+### academicSessionsManagement
 
-// Sorting
-const sortedUsers = await client.usersManagement.getAllUsers({
-    sort: 'familyName',
-    orderBy: 'asc',
-});
+```text
+academicSessionsManagementDeleteAcademicSession
+academicSessionsManagementGetAcademicSession
+academicSessionsManagementGetAllAcademicSessions
+academicSessionsManagementPostAcademicSession
+academicSessionsManagementPutAcademicSession
+```
 
-// Select specific fields
-const partialUsers = await client.usersManagement.getAllUsers({
-    fields: 'sourcedId,givenName,familyName,email',
-});
+### assessmentLineItemsManagement
+
+```text
+assessmentLineItemsManagementCreateAssessmentLineItem
+assessmentLineItemsManagementDeleteAssessmentLineItem
+assessmentLineItemsManagementGetAllAssessmentLineItems
+assessmentLineItemsManagementGetAssessmentLineItem
+assessmentLineItemsManagementUpdateAssessmentLineItem
 ```
 
-## Error Handling
+### assessmentResultsManagement
 
-Error classes are exported directly from the main package for convenience:
+```text
+assessmentResultsManagementCreateAssessmentResult
+assessmentResultsManagementDeleteAssessmentResult
+assessmentResultsManagementGetAllAssessmentResults
+assessmentResultsManagementGetAssessmentResult
+assessmentResultsManagementUpdateAssessmentResult
+```
 
-```typescript
-import {
-    OneRoster,
-    OneRosterError,
-    NotFoundResponseError,
-    UnauthorizedRequestResponseError,
-} from '@eduware/oneroster';
+### categoriesManagement
 
-const client = new OneRoster({
-    /* ... */
-});
+```text
+categoriesManagementCreateCategory
+categoriesManagementDeleteCategory
+categoriesManagementGetAllCategories
+categoriesManagementGetCategory
+categoriesManagementUpdateCategory
+```
 
-try {
-    const user = await client.usersManagement.getUser({
-        sourcedId: 'non-existent-id',
-    });
-} catch (error) {
-    if (error instanceof NotFoundResponseError) {
-        console.log('User not found');
-    } else if (error instanceof UnauthorizedRequestResponseError) {
-        console.log('Authentication failed');
-    } else if (error instanceof OneRosterError) {
-        // Base class for all HTTP errors
-        console.log('HTTP Error:', error.statusCode, error.message);
-    }
-}
+### classesManagement
+
+```text
+classesManagementAddStudentToClass
+classesManagementAddTeacherToClass
+classesManagementCreateClass
+classesManagementDeleteClass
+classesManagementGetAllClasses
+classesManagementGetCategoriesForClass
+classesManagementGetClass
+classesManagementGetClassesForStudent
+classesManagementGetClassesForTeacher
+classesManagementGetClassesForTerm
+classesManagementGetClassesForUser
+classesManagementGetLineItemsForClass
+classesManagementGetResultsForClass
+classesManagementGetResultsForLineItemForClass
+classesManagementGetResultsForStudentForClass
+classesManagementGetScoreScalesForClass
+classesManagementGetStudentsForClass
+classesManagementGetTeachersForClass
+classesManagementPostResultsForAcademicSessionForClass
+classesManagementUpdateClass
 ```
 
-You can also import all errors as a namespace:
+### coursesManagement
+
+```text
+coursesManagementCreateComponentResource
+coursesManagementCreateCourse
+coursesManagementCreateCourseComponent
+coursesManagementDeleteComponentResource
+coursesManagementDeleteCourse
+coursesManagementDeleteCourseComponent
+coursesManagementGetAllComponentResources
+coursesManagementGetAllCourseComponents
+coursesManagementGetAllCourses
+coursesManagementGetClassesForCourse
+coursesManagementGetComponentResource
+coursesManagementGetCourse
+coursesManagementGetCourseComponent
+coursesManagementPutComponentResource
+coursesManagementPutCourse
+coursesManagementPutCourseComponent
+```
 
-```typescript
-import { OneRoster, errors } from '@eduware/oneroster';
-// Or from the dedicated subpath
-import * as errors from '@eduware/oneroster/models/errors';
+### demographicsManagement
 
-if (error instanceof errors.NotFoundResponseError) {
-    // ...
-}
+```text
+demographicsManagementDeleteDemographics
+demographicsManagementGetAllDemographics
+demographicsManagementGetDemographics
+demographicsManagementPostDemographics
+demographicsManagementPutDemographics
 ```
 
-### Error Classes
+### enrollmentsManagement
 
-| Error                              | Status Code | Description                |
-| ---------------------------------- | ----------- | -------------------------- |
-| `BadRequestResponseError`          | 400         | Invalid request parameters |
-| `UnauthorizedRequestResponseError` | 401         | Authentication failed      |
-| `ForbiddenResponseError`           | 403         | Access denied              |
-| `NotFoundResponseError`            | 404         | Resource not found         |
-| `UnprocessableEntityResponseError` | 422         | Validation error           |
-| `TooManyRequestsResponseError`     | 429         | Rate limit exceeded        |
-| `InternalServerErrorResponse`      | 500         | Server error               |
+```text
+enrollmentsManagementCreateEnrollment
+enrollmentsManagementDeleteEnrollment
+enrollmentsManagementGetAllEnrollments
+enrollmentsManagementGetEnrollment
+enrollmentsManagementUpdateEnrollment
+```
 
-## Standalone Functions
+### gradingPeriodsManagement
 
-For optimal bundle sizes in browser and serverless environments, use standalone functions:
+```text
+gradingPeriodsManagementCreateGradingPeriod
+gradingPeriodsManagementDeleteGradingPeriod
+gradingPeriodsManagementGetAllGradingPeriods
+gradingPeriodsManagementGetGradingPeriod
+gradingPeriodsManagementUpdateGradingPeriod
+```
 
-```typescript
-import { OneRosterCore } from '@eduware/oneroster/core.js';
-import { usersManagementGetAllUsers } from '@eduware/oneroster/funcs/usersManagementGetAllUsers.js';
+### lineItemsManagement
 
-const client = new OneRosterCore({
-    security: {
-        clientID: process.env.ONEROSTER_CLIENT_ID!,
-        clientSecret: process.env.ONEROSTER_CLIENT_SECRET!,
-    },
-});
+```text
+lineItemsManagementCreateLineItem
+lineItemsManagementCreateResultForLineItem
+lineItemsManagementDeleteLineItem
+lineItemsManagementGetAllLineItems
+lineItemsManagementGetLineItem
+lineItemsManagementUpdateLineItem
+```
 
-const result = await usersManagementGetAllUsers(client, {});
+### organizationsManagement
 
-if (result.ok) {
-    for await (const page of result.value) {
-        console.log(page.result.users);
-    }
-} else {
-    console.error('Error:', result.error);
-}
+```text
+organizationsManagementCreateOrg
+organizationsManagementDeleteOrg
+organizationsManagementGetAllOrgs
+organizationsManagementGetOrg
+organizationsManagementUpdateOrg
+```
+
+### resourcesManagement
+
+```text
+resourcesManagementCreateResource
+resourcesManagementDeleteResource
+resourcesManagementExportResourceToCommonCartridge
+resourcesManagementGetAllResources
+resourcesManagementGetResource
+resourcesManagementGetResourcesForClass
+resourcesManagementGetResourcesForCourse
+resourcesManagementGetResourcesForUser
+resourcesManagementUpdateResource
+```
+
+### resultsManagement
+
+```text
+resultsManagementCreateResult
+resultsManagementDeleteResult
+resultsManagementGetAllResults
+resultsManagementGetResult
+resultsManagementUpdateResult
+```
+
+### schoolsManagement
+
+```text
+schoolsManagementCreateLineItemsForSchool
+schoolsManagementCreateSchool
+schoolsManagementDeleteSchool
+schoolsManagementGetAllSchools
+schoolsManagementGetClassesForSchool
+schoolsManagementGetCoursesForSchool
+schoolsManagementGetEnrollmentsForClassInSchool
+schoolsManagementGetEnrollmentsForSchool
+schoolsManagementGetLineItemsForSchool
+schoolsManagementGetSchool
+schoolsManagementGetStudentsForClassInSchool
+schoolsManagementGetStudentsForSchool
+schoolsManagementGetTeachersForClassInSchool
+schoolsManagementGetTeachersForSchool
+schoolsManagementGetTermsForSchool
+schoolsManagementUpdateSchool
+```
+
+### scoreScalesManagement
+
+```text
+scoreScalesManagementCreateScoreScale
+scoreScalesManagementDeleteScoreScale
+scoreScalesManagementGetAllScoreScales
+scoreScalesManagementGetScoreScale
+scoreScalesManagementGetScoreScalesForSchool
+scoreScalesManagementUpdateScoreScale
+```
+
+### studentsManagement
+
+```text
+studentsManagementGetAllStudents
+studentsManagementGetStudent
+```
+
+### teachersManagement
+
+```text
+teachersManagementGetAllTeachers
+teachersManagementGetTeacher
+```
+
+### termsManagement
+
+```text
+termsManagementCreateGradingPeriodForTerm
+termsManagementGetAllTerms
+termsManagementGetGradingPeriodsForTerm
+termsManagementGetTerm
+```
+
+### usersManagement
+
+```text
+usersManagementCreateUser
+usersManagementDeleteUser
+usersManagementGetAllUsers
+usersManagementGetUser
+usersManagementGetUserWithDemographics
+usersManagementUpdateUser
 ```
 
-See [FUNCTIONS.md](./FUNCTIONS.md) for the complete list of standalone functions.
+## 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                               | Create | Read | Update | Delete |
+| ------------------------------------ | :----: | :--: | :----: | :----: |
+| `usersManagement`                    |   ✅   |  ✅  |   ✅   |   ✅   |
+| `studentsManagement`                 |   —    |  ✅  |   —    |   —    |
+| `teachersManagement`                 |   —    |  ✅  |   —    |   —    |
+| `classesManagement`                  |   ✅   |  ✅  |   ✅   |   ✅   |
+| `coursesManagement`                  |   ✅   |  ✅  |   ✅   |   ✅   |
+| `enrollmentsManagement`              |   ✅   |  ✅  |   ✅   |   ✅   |
+| `schoolsManagement`                  |   ✅   |  ✅  |   ✅   |   ✅   |
+| `organizationsManagement`            |   ✅   |  ✅  |   ✅   |   ✅   |
+| `academicSessionsManagement`         |   ✅   |  ✅  |   ✅   |   ✅   |
+| `termsManagement`                    |   —    |  ✅  |   —    |   —    |
+| `gradingPeriodsManagement`           |   ✅   |  ✅  |   ✅   |   ✅   |
+| `demographicsManagement`             |   ✅   |  ✅  |   ✅   |   ✅   |
+| `lineItemsManagement`                |   ✅   |  ✅  |   ✅   |   ✅   |
+| `resultsManagement`                  |   ✅   |  ✅  |   ✅   |   ✅   |
+| `categoriesManagement`               |   ✅   |  ✅  |   ✅   |   ✅   |
+| `scoreScalesManagement`              |   ✅   |  ✅  |   ✅   |   ✅   |
+| `resourcesManagement`                |   ✅   |  ✅  |   ✅   |   ✅   |
+| `courseComponentsManagement`         |   ✅   |  ✅  |   ✅   |   ✅   |
+| `courseComponentResourcesManagement` |   ✅   |  ✅  |   ✅   |   ✅   |
+| `assessmentLineItemsManagement`      |   ✅   |  ✅  |   ✅   |   ✅   |
+| `assessmentResultsManagement`        |   ✅   |  ✅  |   ✅   |   ✅   |
+
+_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
+
+```text
+@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)
+
+```text
+@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. The MCP server exposes OneRoster API operations as tools that can be used by AI assistants.
+This SDK includes an MCP (Model Context Protocol) server for AI applications.
 
-### Basic Configuration (OAuth 2.0)
+### OAuth 2.0 Configuration
 
 ```json
 {
@@ -556,8 +730,6 @@ This SDK includes an MCP (Model Context Protocol) server for AI applications. Th
 
 ### ClassLink Configuration (Bearer Token)
 
-For ClassLink's proxy mode with pre-authenticated bearer tokens:
-
 ```json
 {
     "mcpServers": {
@@ -584,9 +756,7 @@ For ClassLink's proxy mode with pre-authenticated bearer tokens:
 }
 ```
 
-### OAuth 1.0a Configuration (OneRoster v1.1)
-
-For OneRoster v1.1 servers using OAuth 1.0a:
+### OAuth 1.0a Configuration (v1.1)
 
 ```json
 {
@@ -616,7 +786,7 @@ For OneRoster v1.1 servers using OAuth 1.0a:
 }
 ```
 
-### Command Line Arguments
+### MCP Arguments
 
 | Argument              | Description                                                   | Default   | Required          |
 | --------------------- | ------------------------------------------------------------- | --------- | ----------------- |
@@ -634,31 +804,9 @@ For OneRoster v1.1 servers using OAuth 1.0a:
 | `--log-level`         | Log level: `debug`, `info`, `warn`, `error`                   | `info`    | No                |
 | `--env`               | Environment variables (format: `KEY=value`, repeatable)       | —         | No                |
 
-### Client Profiles
-
-The `--client-profile` flag restricts which tools are available:
-
-- **`full`** (default): All OneRoster tools including create, update, and delete operations
-- **`classlink`**: Read-only tools matching ClassLink's supported endpoints
-
-Using the appropriate profile prevents AI assistants from attempting unsupported operations.
-
-## Runtime Support
-
-- **Browsers:** Chrome, Safari, Edge, Firefox (evergreen)
-- **Node.js:** v18+ (LTS)
-- **Bun:** v1+
-- **Deno:** v1.39+
-
-See [RUNTIMES.md](./RUNTIMES.md) for detailed runtime information.
-
 ## API Reference
 
-For the complete list of available methods, see [FUNCTIONS.md](./FUNCTIONS.md).
-
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
+See [FUNCTIONS.md](./FUNCTIONS.md) for the full method list.
 
 ## License