@eduware/oneroster 1.0.1 → 1.2.0

package/README.md

@@ -97,19 +97,6 @@ const schools = await client.schoolsManagement.getAllSchools({});
 // client.usersManagement.createUser({});  // Error: Property 'createUser' does not exist
 ```
 
-**ClassLink supports:**
-
-- Academic Sessions, Classes, Courses, Enrollments
-- Grading Periods, Organizations, Schools
-- Students, Teachers, Terms, Users
-- All read operations and nested queries (e.g., `getStudentsForClass`)
-
-**ClassLink does NOT support:**
-
-- Demographics, Line Items, Results, Categories, Score Scales
-- Course Components, Component Resources
-- Any create/update/delete operations
-
 ### Full Client
 
 For full OneRoster access with all methods available:
@@ -165,6 +152,136 @@ 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                      |
+
+### 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 (e.g., students/teachers use usersManagement for CUD)_
+
+### LMS Provider Support
+
+Different LMS providers implement different subsets of the OneRoster specification. Use this table to understand what's available for your provider:
+
+| 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      |    ❌     |
+
+**Legend:**
+
+- ✅ CRUD = Create, Read, Update, Delete all supported
+- ✅ Read = Read-only access (GET operations)
+- ❌ = Not supported by this provider
+
+> **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.
+
+### Nested Queries
+
+Many modules support nested queries to fetch related data efficiently:
+
+```typescript
+// Get all students in a specific class
+const students = await client.classesManagement.getStudentsForClass({
+    classSourcedId: 'class-123',
+});
+
+// Get all classes for a specific school
+const classes = await client.schoolsManagement.getClassesForSchool({
+    schoolSourcedId: 'school-456',
+});
+
+// Get all enrollments for a class
+const enrollments = await client.classesManagement.getEnrollmentsForClass({
+    classSourcedId: 'class-123',
+});
+```
+
+Common nested query patterns:
+
+- `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`
+
 ## OneRoster Versions
 
 The SDK supports both OneRoster v1.1 and v1.2 specifications. The default is v1.2.
@@ -280,6 +397,29 @@ for await (const page of result) {
 }
 ```
 
+### Total Count
+
+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:
+
+```typescript
+const result = await client.usersManagement.getAllUsers({});
+
+// Access total count from the first page
+if (result.ok) {
+    console.log(`Total users: ${result.value.totalCount}`);
+}
+
+// Or during iteration
+for await (const page of result) {
+    if (page.ok) {
+        console.log(`Page has ${page.value.users?.length ?? 0} users`);
+        console.log(`Total: ${page.totalCount}`);
+    }
+}
+```
+
+> **Note:** The `totalCount` property is `undefined` if the server does not return the `X-Total-Count` header.
+
 ## Filtering & Sorting
 
 ```typescript
@@ -373,7 +513,9 @@ See [FUNCTIONS.md](./FUNCTIONS.md) for the complete list of standalone functions
 
 ## MCP Server
 
-This SDK includes an MCP (Model Context Protocol) server for AI applications:
+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.
+
+### Basic Configuration (OAuth 2.0)
 
 ```json
 {
@@ -387,6 +529,8 @@ This SDK includes an MCP (Model Context Protocol) server for AI applications:
                 "--",
                 "mcp",
                 "start",
+                "--server-url",
+                "https://your-oneroster-server.com",
                 "--client-id",
                 "your-client-id",
                 "--client-secret",
@@ -399,6 +543,95 @@ This SDK includes an MCP (Model Context Protocol) server for AI applications:
 }
 ```
 
+### ClassLink Configuration (Bearer Token)
+
+For ClassLink's proxy mode with pre-authenticated bearer tokens:
+
+```json
+{
+    "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 (OneRoster v1.1)
+
+For OneRoster v1.1 servers using OAuth 1.0a:
+
+```json
+{
+    "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"
+            ]
+        }
+    }
+}
+```
+
+### Command Line 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                |
+
+### 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)