@timeback/edubridge 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# @timeback/edubridge
+
+TypeScript client for the Edubridge API — simplified course enrollment and analytics, abstracting OneRoster complexity.
+
+## Installation
+
+```bash
+bun add @timeback/edubridge
+```
+
+## Quick Start
+
+```typescript
+import { EdubridgeClient } from '@timeback/edubridge'
+
+const edubridge = new EdubridgeClient({
+	env: 'staging', // or 'production'
+	auth: {
+		clientId: 'your-client-id',
+		clientSecret: 'your-client-secret',
+	},
+})
+
+const enrollment = await edubridge.enrollments.enroll(userId, courseId)
+const enrollments = await edubridge.enrollments.getByUser(userId)
+const students = await edubridge.users.listStudents()
+```
+
+## API Design
+
+### Standalone vs Composed
+
+```typescript
+// Composed
+import { TimebackClient } from '@timeback/core'
+
+// Standalone
+const edubridge = new EdubridgeClient({ env: 'staging', auth })
+
+const client = new TimebackClient({ env: 'staging', auth })
+client.edubridge.enrollments.enroll(userId, courseId)
+```
+
+### Client Structure
+
+```typescript
+const client = new EdubridgeClient(options)
+
+// Enrollments
+client.enrollments.getByUser(userId)
+client.enrollments.enroll(userId, courseId, schoolId?, options?)
+client.enrollments.unenroll(userId, courseId, schoolId?)
+client.enrollments.resetGoals(courseId)
+client.enrollments.resetProgress(userId, courseId)
+client.enrollments.getDefaultClass(courseId, schoolId?)
+
+// Users
+client.users.listByRole(params)
+client.users.listStudents(params?)
+client.users.listTeachers(params?)
+client.users.search(roles, searchTerm, limit?)
+
+// Analytics
+client.analytics.getActivity(params)
+client.analytics.getWeeklyFacts(params)
+client.analytics.getEnrollmentFacts(params)
+client.analytics.getHighestGradeMastered(studentId, subject)
+
+// Applications
+client.applications.list()
+client.applications.getMetrics(applicationSourcedId)
+
+// Subject Tracks
+client.subjectTracks.list()
+client.subjectTracks.get(id)
+client.subjectTracks.create(data)
+client.subjectTracks.update(id, data)
+client.subjectTracks.delete(id)
+client.subjectTracks.listGroups()
+
+// Learning Reports
+client.learningReports.getMapProfile(userId)
+client.learningReports.getTimeSaved(userId)
+```
+
+### Enrollments
+
+The enrollments resource handles OneRoster complexity automatically:
+
+```typescript
+// Enroll a student in a course (creates class, term, etc. automatically)
+const enrollment = await client.enrollments.enroll(userId, courseId, schoolId, {
+	role: 'student',
+	metadata: {
+		goals: {
+			dailyXp: 100,
+			dailyActiveMinutes: 30,
+		},
+	},
+})
+
+// Get all enrollments for a user
+const enrollments = await client.enrollments.getByUser(userId)
+
+// Unenroll from a course
+await client.enrollments.unenroll(userId, courseId)
+
+// Reset goals for all users in a course
+const result = await client.enrollments.resetGoals(courseId)
+console.log(`Updated ${result.updated} enrollments`)
+```
+
+### Analytics
+
+```typescript
+// Get activity for a date range
+const activity = await client.analytics.getActivity({
+	userId: 'user-id',
+	startDate: '2025-01-01',
+	endDate: '2025-01-31',
+	timezone: 'America/New_York',
+})
+
+// Get weekly facts
+const facts = await client.analytics.getWeeklyFacts({
+	userId: 'user-id',
+})
+
+// Get highest grade mastered
+const gradeData = await client.analytics.getHighestGradeMastered('student-id', 'math')
+```
+
+### Authentication
+
+The client handles OAuth2 token management automatically:
+
+```typescript
+// Environment mode (recommended for Timeback APIs)
+const client = new EdubridgeClient({
+	env: 'staging', // or 'production'
+	auth: {
+		clientId: 'xxx',
+		clientSecret: 'xxx',
+	},
+})
+
+// Explicit mode (custom API)
+const client = new EdubridgeClient({
+	baseUrl: 'https://api.example.com',
+	auth: {
+		clientId: 'xxx',
+		clientSecret: 'xxx',
+		authUrl: 'https://auth.example.com/oauth2/token',
+	},
+})
+```
+
+Tokens are cached and refreshed automatically before expiry.
+
+### Error Handling
+
+```typescript
+import { EdubridgeError, NotFoundError } from '@timeback/edubridge'
+
+try {
+	await client.enrollments.getByUser('invalid-id')
+} catch (error) {
+	if (error instanceof NotFoundError) {
+		console.log('User not found')
+	} else if (error instanceof EdubridgeError) {
+		console.log(error.statusCode) // HTTP status
+		console.log(error.message)
+	}
+}
+```
+
+## Configuration
+
+```typescript
+new EdubridgeClient({
+	// 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,
+	},
+
+	// Optional
+	fetch?: typeof fetch, // Custom fetch implementation
+	timeout?: number, // Request timeout in ms (default: 30000)
+
+	// Internal (for composition with @timeback/core)
+	transport?: Transport, // Shared HTTP transport
+})
+```
+
+## 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 and authentication:
+
+```bash
+[2025-01-15T10:30:00.000Z] DEBUG [edubridge:auth] Fetching new access token...
+[2025-01-15T10:30:00.500Z] DEBUG [edubridge:auth] Token acquired (500ms, expires in 3600s)
+[2025-01-15T10:30:00.501Z] DEBUG [edubridge:http] → POST https://api.example.com/edubridge/enrollments/enroll/...
+[2025-01-15T10:30:00.800Z] DEBUG [edubridge:http] ← 201 Created (299ms)
+```

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Edubridge Client
+ *
+ * Main entry point for the Edubridge SDK.
+ */
+/**
+ * Edubridge API client for simplified enrollment and analytics operations.
+ *
+ * Provides access to Edubridge endpoints including course-centric enrollments,
+ * user management, analytics, and learning reports.
+ *
+ * @example Environment mode (Timeback APIs)
+ * ```typescript
+ * const client = new EdubridgeClient({
+ *   env: 'staging', // or 'production'
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *   },
+ * })
+ * ```
+ *
+ * @example Provider mode (shared tokens)
+ * ```typescript
+ * import { TimebackProvider } from '@timeback/internal-client-infra'
+ *
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ *
+ * const client = new EdubridgeClient({ provider })
+ * ```
+ *
+ * @example Explicit mode (custom API)
+ * ```typescript
+ * const client = new EdubridgeClient({
+ *   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 EDUBRIDGE_BASE_URL, EDUBRIDGE_TOKEN_URL,
+ * // EDUBRIDGE_CLIENT_ID, EDUBRIDGE_CLIENT_SECRET
+ * const client = new EdubridgeClient()
+ * ```
+ */
+export declare const EdubridgeClient: {
+    new (config?: import("./types").EdubridgeClientConfig): {
+        readonly transport: import("./types").EdubridgeTransportLike;
+        readonly _provider?: import("@timeback/internal-client-infra").TimebackProvider | undefined;
+        readonly enrollments: import("./resources").EnrollmentsResource;
+        readonly users: import("./resources").UsersResource;
+        readonly analytics: import("./resources").AnalyticsResource;
+        readonly applications: import("./resources").ApplicationsResource;
+        readonly subjectTracks: import("./resources").SubjectTrackResource;
+        readonly learningReports: import("./resources").LearningReportsResource;
+        getTransport(): import("./types").EdubridgeTransportLike;
+        checkAuth(): Promise<import("@timeback/internal-client-infra").AuthCheckResult>;
+    };
+};
+export type { EdubridgeClientInstance } 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;CAA0B,CAAA;AAEtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA"}

package/dist/constants.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Edubridge Constants
+ *
+ * Configuration constants for the Edubridge client.
+ */
+import type { ClientUrlMaps, Platform } from '@timeback/internal-client-infra';
+/**
+ * Environment variable names for fallback config.
+ */
+export declare const EDUBRIDGE_ENV_VARS: {
+    readonly baseUrl: "EDUBRIDGE_BASE_URL";
+    readonly clientId: "EDUBRIDGE_CLIENT_ID";
+    readonly clientSecret: "EDUBRIDGE_CLIENT_SECRET";
+    readonly authUrl: "EDUBRIDGE_TOKEN_URL";
+};
+/**
+ * Get URL maps for a specific platform.
+ * Defaults to 'BEYOND_AI' for backwards compatibility.
+ *
+ * Note: Edubridge uses the main API server (same as OneRoster).
+ * @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;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAE,QAA2B,GAAG,aAAa,CAM1F"}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Edubridge Error Classes
+ *
+ * Re-exports common errors from `@timeback/internal-client-infra`.
+ * Edubridge uses the same error format as other Timeback clients.
+ */
+import { ApiError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError } from '@timeback/internal-client-infra';
+export { ApiError as EdubridgeError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError, };
+//# 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;;;;;GAKG;AAEH,OAAO,EACN,QAAQ,EACR,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACN,QAAQ,IAAI,cAAc,EAC1B,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,GACf,CAAA"}