@timeback/oneroster 0.1.0

package/README.md

@@ -0,0 +1,295 @@
+# @timeback/oneroster
+
+TypeScript client for the OneRoster 1.2 API.
+
+## Installation
+
+```bash
+bun add @timeback/oneroster
+```
+
+## Quick Start
+
+```typescript
+import { OneRosterClient } from '@timeback/oneroster'
+
+const client = new OneRosterClient({
+	env: 'production',
+	auth: {
+		clientId: 'your-client-id',
+		clientSecret: 'your-client-secret',
+	},
+})
+
+const students = await client.students.list()
+const user = await client.users.get('user-sourced-id')
+const course = await client.courses.create({
+	title: 'Algebra I',
+	org: { sourcedId: 'school-id' },
+})
+```
+
+## API Design
+
+### Standalone vs Composed
+
+The client works standalone or composed into `@timeback/core`:
+
+```typescript
+// Composed
+import { TimebackClient } from '@timeback/core'
+
+// Standalone
+const oneroster = new OneRosterClient({ env: 'production', auth })
+
+const client = new TimebackClient({ baseUrl, auth })
+client.oneroster.users.list()
+```
+
+### Client Structure
+
+```typescript
+const client = new OneRosterClient(options)
+
+// Rostering
+client.users // Users (all roles)
+client.students // Students (filtered users)
+client.teachers // Teachers (filtered users)
+client.classes // Classes
+client.courses // Courses
+client.enrollments // Enrollments
+client.orgs // Organizations
+client.schools // Schools (filtered orgs)
+client.terms // Academic terms
+client.academicSessions
+client.gradingPeriods
+client.demographics
+
+// Gradebook
+client.results // Grade results
+client.lineItems // Line items (assignments)
+client.categories // Grading categories
+client.scoreScales // Score scales
+client.assessmentLineItems
+client.assessmentResults
+
+// Resources
+client.resources
+```
+
+Resources serve dual purposes — as properties for top-level operations, and as functions for accessing nested resources:
+
+```typescript
+// As property → top-level CRUD
+client.schools.list()
+client.schools.get('id')
+
+// As function → scoped operations
+client.schools('id').classes()
+client.schools('id').students()
+```
+
+### Common Methods
+
+Each resource supports:
+
+```typescript
+// List with type-safe filtering
+const activeUsers = await client.users.list({
+	where: { status: 'active' },
+	sort: 'familyName',
+	orderBy: 'asc',
+})
+
+// Filter with operators
+const teachers = await client.users.list({
+	where: { role: 'teacher', status: 'active' },
+})
+
+// Stream for large datasets (lazy pagination)
+for await (const user of client.users.stream()) {
+	console.log(user.givenName)
+}
+
+// Get by sourcedId
+client.users.get('sourced-id')
+
+// Create (where supported)
+client.courses.create({ title: 'Math 101', org: { sourcedId: '...' } })
+
+// Update (where supported)
+client.courses.update('sourced-id', { title: 'Math 102' })
+
+// Delete (where supported)
+client.courses.delete('sourced-id')
+
+// Patch (enrollments, assessmentLineItems, assessmentResults)
+client.enrollments.patch('sourced-id', { status: 'tobedeleted' })
+```
+
+### Nested Resources
+
+The API exposes many nested relationships:
+
+```typescript
+// ── Schools ──────────────────────────────────────────────────────────────────
+client.schools('school-id').classes()
+client.schools('school-id').courses()
+client.schools('school-id').terms()
+client.schools('school-id').teachers()
+client.schools('school-id').students()
+client.schools('school-id').enrollments()
+client.schools('school-id').scoreScales()
+client.schools('school-id').lineItems()
+
+// Deeply nested
+client.schools('school-id').classes('class-id').teachers()
+client.schools('school-id').classes('class-id').students()
+client.schools('school-id').classes('class-id').enrollments()
+
+// ── Classes ──────────────────────────────────────────────────────────────────
+client.classes('class-id').teachers()
+client.classes('class-id').students()
+client.classes('class-id').lineItems()
+client.classes('class-id').results()
+client.classes('class-id').categories()
+client.classes('class-id').scoreScales()
+client.classes('class-id').resources()
+client.classes('class-id').enroll('user-id', 'student')
+
+// Deeply nested gradebook
+client.classes('class-id').lineItems('line-item-id').results()
+client.classes('class-id').students('student-id').results()
+
+// ── Users ────────────────────────────────────────────────────────────────────
+client.users('user-id').classes()
+client.users('user-id').demographics()
+client.users('user-id').agents()
+client.users('user-id').addAgent('agent-id')
+client.users('user-id').removeAgent('agent-id')
+client.users('user-id').agentFor()
+client.users('user-id').credentials()
+client.users('user-id').createCredential({ ... })
+client.users('user-id').credentials('cred-id').decrypt()
+
+// ── Students/Teachers ────────────────────────────────────────────────────────
+client.students('student-id').classes()
+client.teachers('teacher-id').classes()
+
+// ── Courses ──────────────────────────────────────────────────────────────────
+client.courses('course-id').classes()
+client.courses('course-id').resources()
+client.courses.components()
+client.courses.getComponent('component-id')
+client.courses.componentResources()
+client.courses.getComponentResource('id')
+client.courses.createStructure({ ... })
+
+// ── Terms ────────────────────────────────────────────────────────────────────
+client.terms('term-id').classes()
+client.terms('term-id').gradingPeriods()
+
+// ── Line Items ───────────────────────────────────────────────────────────────
+client.lineItems('line-item-id').results()
+
+// ── Resources ────────────────────────────────────────────────────────────────
+client.resources.list()
+client.resources.create({ ... })
+client.resources('resource-id').export()
+```
+
+### Response Types
+
+```typescript
+// List responses include pagination info
+const response = await client.users.list()
+// {
+//   users: User[],
+//   offset: number,
+//   limit: number,
+// }
+
+// Single resource responses
+const user = await client.users.get('id')
+// { user: User }
+
+// Create responses
+const created = await client.courses.create(payload)
+// { sourcedIdPairs: { suppliedSourcedId, allocatedSourcedId } }
+```
+
+### Authentication
+
+The client handles OAuth2 token management automatically:
+
+```typescript
+const client = new OneRosterClient({
+	baseUrl: 'https://api.timeback.dev',
+	auth: {
+		clientId: 'xxx',
+		clientSecret: 'xxx',
+		// Optional: custom token endpoint
+		authUrl: 'https://auth.example.com/oauth2/token',
+	},
+})
+```
+
+Tokens are cached and refreshed automatically before expiry.
+
+### Error Handling
+
+```typescript
+import { OneRosterError } from '@timeback/oneroster'
+
+try {
+	await client.users.get('invalid-id')
+} catch (error) {
+	if (error instanceof OneRosterError) {
+		console.log(error.status) // 404
+		console.log(error.message) // 'Not Found'
+		console.log(error.imsx_codeMajor) // 'failure'
+	}
+}
+```
+
+## Configuration
+
+```typescript
+new OneRosterClient({
+  // Environment-based (recommended)
+  env: 'production' | 'staging',
+  auth: {
+    clientId: string,
+    clientSecret: string,
+  },
+
+  // Or explicit URLs
+  baseUrl: string,
+  auth: {
+    clientId: string,
+    clientSecret: string,
+    authUrl?: string,
+  },
+
+  // Optional
+  timeout?: number,      // Request timeout in ms (default: 30000)
+})
+```
+
+## Debug Mode
+
+Enable debug logging by setting `DEBUG=1` or `DEBUG=true`:
+
+```bash
+DEBUG=1 bun run my-script.ts
+```
+
+This outputs detailed logs for HTTP requests, authentication, and pagination:
+
+```bash
+[2025-01-15T10:30:00.000Z] DEBUG [oneroster:auth] Fetching new access token...
+[2025-01-15T10:30:00.500Z] DEBUG [oneroster:auth] Token acquired (500ms, expires in 3600s)
+[2025-01-15T10:30:00.501Z] DEBUG [oneroster:http] → GET https://api.example.com/ims/oneroster/.../schools
+[2025-01-15T10:30:00.800Z] DEBUG [oneroster:http] ← 200 OK (299ms)
+[2025-01-15T10:30:00.801Z] DEBUG [oneroster:pagination] First page: 5 items, total: 20, hasMore: true
+```

package/dist/client.d.ts

@@ -0,0 +1,125 @@
+/**
+ * OneRoster Client
+ *
+ * Main entry point for the OneRoster SDK.
+ */
+/**
+ * OneRoster API client for rostering and gradebook operations.
+ *
+ * Provides access to all OneRoster v1.2 resources including users, classes,
+ * enrollments, courses, grades, and assessments.
+ *
+ * @example Environment mode (Timeback APIs)
+ * ```typescript
+ * const client = new OneRosterClient({
+ *   env: 'staging', // or 'production'
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *   },
+ * })
+ * ```
+ *
+ * @example Platform selection
+ * ```typescript
+ * const client = new OneRosterClient({
+ *   platform: 'LEARNWITH_AI', // or 'BEYOND_AI' (default)
+ *   env: 'production',
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *   },
+ * })
+ * ```
+ *
+ * @example Provider mode (pre-built provider)
+ * ```typescript
+ * import { TimebackProvider } from '@timeback/internal-client-infra'
+ *
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ *
+ * const client = new OneRosterClient({ provider })
+ * ```
+ *
+ * @example Explicit mode (custom OneRoster API)
+ * ```typescript
+ * const client = new OneRosterClient({
+ *   baseUrl: 'https://api.example.com',
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *     authUrl: 'https://auth.example.com/oauth2/token',
+ *   },
+ * })
+ * ```
+ *
+ * @example Environment variables fallback
+ * ```typescript
+ * // Set ONEROSTER_BASE_URL, ONEROSTER_TOKEN_URL,
+ * // ONEROSTER_CLIENT_ID, ONEROSTER_CLIENT_SECRET
+ * const client = new OneRosterClient()
+ * ```
+ *
+ * @example Nested resources
+ * ```typescript
+ * const classes = await client.schools.for('school-id').classes()
+ * const students = await client.classes.for('class-id').students()
+ * ```
+ *
+ * @remarks
+ * The client supports four configuration modes:
+ *
+ * 1. **Provider mode**: `{ provider: TimebackProvider }` — Use a pre-built provider
+ * 2. **Environment mode**: `{ env, auth }` — Connect to Timeback platforms
+ * 3. **Explicit mode**: `{ baseUrl, auth: { authUrl } }` — Custom OneRoster API
+ * 4. **Transport mode**: `{ transport }` — Use existing transport instance
+ *
+ * If no config is provided, the client reads from environment variables.
+ *
+ * @see {@link createOneRosterClient} for creating platform-specific clients
+ */
+export declare const OneRosterClient: {
+    new (config?: import("./types").OneRosterClientConfig): {
+        readonly transport: import("./types").OneRosterTransportLike;
+        readonly _provider?: import("@timeback/internal-client-infra").TimebackProvider | undefined;
+        readonly users: import("./types").UsersCallable;
+        readonly students: import("./types").StudentsCallable;
+        readonly teachers: import("./types").TeachersCallable;
+        readonly orgs: import("./resources").OrgsResource;
+        readonly schools: import("./types").SchoolsCallable;
+        readonly classes: import("./types").ClassesCallable;
+        readonly courses: import("./types").CoursesCallable;
+        readonly enrollments: import("./resources").EnrollmentsResource;
+        readonly academicSessions: import("./resources").AcademicSessionsResource;
+        readonly terms: import("./types").TermsCallable;
+        readonly gradingPeriods: import("./resources").GradingPeriodsResource;
+        readonly demographics: import("./resources").DemographicsResource;
+        readonly lineItems: import("./types").LineItemsCallable;
+        readonly results: import("./resources").ResultsResource;
+        readonly categories: import("./resources").CategoriesResource;
+        readonly scoreScales: import("./resources").ScoreScalesResource;
+        readonly assessmentLineItems: import("./types").AssessmentLineItemsCallable;
+        readonly assessmentResults: import("./resources").AssessmentResultsResource;
+        readonly resources: import("./types").ResourcesCallable;
+        getTransport(): import("./types").OneRosterTransportLike;
+        checkAuth(): Promise<import("@timeback/internal-client-infra").AuthCheckResult>;
+    };
+};
+/**
+ * Type representing an instance of OneRosterClient.
+ *
+ * Use this when you need to type a variable that holds a client instance.
+ *
+ * @example
+ * ```typescript
+ * function doSomething(client: OneRosterClientInstance) {
+ *   return client.users.list()
+ * }
+ * ```
+ */
+export type { OneRosterClientInstance } from './types';
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;CAA0B,CAAA;AAEtD;;;;;;;;;;;GAWG;AACH,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA"}

package/dist/constants.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OneRoster Constants
+ *
+ * Configuration constants for the OneRoster client.
+ */
+import type { ClientUrlMaps, Platform } from '@timeback/internal-client-infra';
+/**
+ * Environment variable names for OneRoster configuration fallback.
+ */
+export declare const ONEROSTER_ENV_VARS: {
+    readonly baseUrl: "ONEROSTER_BASE_URL";
+    readonly clientId: "ONEROSTER_CLIENT_ID";
+    readonly clientSecret: "ONEROSTER_CLIENT_SECRET";
+    readonly authUrl: "ONEROSTER_TOKEN_URL";
+};
+/**
+ * Get URL maps for a specific platform.
+ * Defaults to 'BEYOND_AI' for backwards compatibility.
+ * @param platform - Platform name
+ * @returns Client URL maps for the platform
+ */
+export declare function getUrlMapsForPlatform(platform?: Platform): ClientUrlMaps;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAM9E;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAA;AAMV;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAE,QAA2B,GAAG,aAAa,CAM1F"}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * OneRoster Error Classes
+ *
+ * Re-exports common API errors with IMS Global parsing.
+ */
+export { ApiError as OneRosterError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError, } from '@timeback/internal-client-infra';
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,QAAQ,IAAI,cAAc,EAC1B,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,GACf,MAAM,iCAAiC,CAAA"}