@timeback/core 0.1.0

package/README.md

@@ -0,0 +1,216 @@
+# @timeback/core
+
+Unified client for Timeback education APIs.
+
+## Installation
+
+```bash
+bun add @timeback/core
+```
+
+## Quick Start
+
+```typescript
+import { TimebackClient } from '@timeback/core'
+
+const timeback = new TimebackClient({
+	env: 'staging', // or 'production'
+	auth: {
+		clientId: process.env.CLIENT_ID,
+		clientSecret: process.env.CLIENT_SECRET,
+	},
+})
+
+// OneRoster - rostering and gradebook
+for await (const school of timeback.oneroster.schools.list()) {
+	console.log(school.name)
+}
+
+// Edubridge - simplified enrollments and analytics
+const analytics = await timeback.edubridge.analytics.summary()
+
+// Caliper - learning analytics events
+await timeback.caliper.events.send(event)
+```
+
+## Managing Multiple Clients
+
+For applications that need to manage multiple `TimebackClient` instances, use `TimebackManager`:
+
+```typescript
+import { TimebackManager } from '@timeback/core'
+
+const manager = new TimebackManager()
+	.register('alpha', {
+		env: 'production',
+		auth: { clientId: '...', clientSecret: '...' },
+	})
+	.register('beta', {
+		env: 'production',
+		auth: { clientId: '...', clientSecret: '...' },
+	})
+
+// Target a specific platform
+const users = await manager.get('alpha').oneroster.users.list()
+
+// Sync a user across all platforms (uses Promise.allSettled — never throws)
+const results = await manager.broadcast(client => client.oneroster.users.create(user))
+
+// Direct property access (like a plain object)
+if (results.alpha.ok) {
+	console.log('Created on alpha:', results.alpha.value.id)
+}
+
+// Convenience methods for filtering
+if (results.allSucceeded) {
+	console.log('Synced to all platforms!')
+}
+
+results.succeeded.forEach(([name, user]) => {
+	console.log(`Created on ${name}:`, user.id)
+})
+
+results.failed.forEach(([name, error]) => {
+	console.error(`Failed on ${name}:`, error.message)
+})
+```
+
+### Manager API
+
+| Method                   | Description                                                          |
+| ------------------------ | -------------------------------------------------------------------- |
+| `register(name, config)` | Add a named client                                                   |
+| `get(name)`              | Retrieve a client by name                                            |
+| `has(name)`              | Check if a client is registered                                      |
+| `names`                  | Get all registered client names                                      |
+| `size`                   | Get number of registered clients                                     |
+| `broadcast(fn)`          | Execute on all clients (never throws), returns `BroadcastResults<T>` |
+| `unregister(name)`       | Remove and close a client                                            |
+| `close()`                | Close all clients                                                    |
+
+### BroadcastResults API
+
+The `broadcast()` method returns a hybrid object — use it like a plain `Record<string, BroadcastResult<T>>` with added convenience methods:
+
+```typescript
+// Direct property access
+results.alpha.ok // true or false
+results['beta'].value // the value if ok
+results.gamma.error // the error if not ok
+
+// Standard object methods work
+Object.keys(results) // ['alpha', 'beta', 'gamma']
+Object.entries(results) // [[name, result], ...]
+```
+
+| Property/Method | Description                                 |
+| --------------- | ------------------------------------------- |
+| `succeeded`     | Get successful results as `[name, value][]` |
+| `failed`        | Get failed results as `[name, error][]`     |
+| `allSucceeded`  | `true` if all operations succeeded          |
+| `anyFailed`     | `true` if any operation failed              |
+| `values()`      | Get all values (throws if any failed)       |
+
+## Configuration
+
+The client supports three configuration modes:
+
+### Environment Mode (Recommended)
+
+Derive all URLs from `staging` or `production`:
+
+```typescript
+const client = new TimebackClient({
+	env: 'staging', // or 'production'
+	auth: { clientId: '...', clientSecret: '...' },
+})
+```
+
+| Environment  | API Base URL                   |
+| ------------ | ------------------------------ |
+| `staging`    | `api.staging.alpha-1edtech.ai` |
+| `production` | `api.alpha-1edtech.ai`         |
+
+### Base URL Mode
+
+For self-hosted or custom deployments with a single base URL:
+
+```typescript
+const client = new TimebackClient({
+	baseUrl: 'https://timeback.myschool.edu',
+	auth: {
+		clientId: '...',
+		clientSecret: '...',
+		authUrl: 'https://timeback.myschool.edu/oauth/token',
+	},
+})
+```
+
+### Explicit Services Mode
+
+Full control over each service URL. Only configure the services you need:
+
+```typescript
+const client = new TimebackClient({
+	services: {
+		oneroster: 'https://roster.example.com',
+		caliper: 'https://analytics.example.com',
+		// edubridge not configured — accessing it will throw
+	},
+	auth: {
+		clientId: '...',
+		clientSecret: '...',
+		authUrl: 'https://auth.example.com/oauth/token',
+	},
+})
+```
+
+Each service can optionally override the default token URL:
+
+```typescript
+const client = new TimebackClient({
+	services: {
+		oneroster: 'https://roster.example.com',
+		caliper: {
+			baseUrl: 'https://analytics.example.com',
+			authUrl: 'https://analytics-auth.example.com/token', // different auth provider
+		},
+	},
+	auth: {
+		clientId: '...',
+		clientSecret: '...',
+		authUrl: 'https://auth.example.com/oauth/token', // default for services without override
+	},
+})
+```
+
+OAuth tokens are shared across sub-clients that use the same token URL.
+
+## Individual Clients
+
+For standalone usage, install individual packages:
+
+```bash
+bun add @timeback/oneroster
+bun add @timeback/edubridge
+bun add @timeback/caliper
+```
+
+```typescript
+import { OneRosterClient } from '@timeback/oneroster'
+
+const client = new OneRosterClient({
+	env: 'staging',
+	auth: { clientId: '...', clientSecret: '...' },
+})
+```
+
+## Debug Mode
+
+Enable debug logging with `DEBUG=1`:
+
+```bash
+DEBUG=1 bun run my-script.ts
+```
+
+This outputs detailed logs for HTTP requests and authentication:

package/dist/client.d.ts

@@ -0,0 +1,147 @@
+import type { CaliperClientInstance } from '@timeback/caliper';
+import type { AuthCheckResult, TimebackProvider } from '@timeback/internal-client-infra';
+import type { EdubridgeClientInstance } from '@timeback/edubridge';
+import type { OneRosterClientInstance } from '@timeback/oneroster';
+import type { TimebackClientConfig } from './types/index';
+/**
+ * Timeback Client
+ *
+ * Unified client for all Timeback education APIs.
+ */
+/**
+ * Unified client for Timeback education APIs.
+ *
+ * Provides access to all Timeback APIs with shared authentication:
+ * - **OneRoster**: Rostering and gradebook data
+ * - **Edubridge**: Simplified enrollments and analytics
+ * - **Caliper**: Learning analytics events
+ *
+ * All sub-clients share a single OAuth token, reducing auth requests.
+ *
+ * @example Environment mode
+ * ```typescript
+ * const timeback = new TimebackClient({
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ * ```
+ *
+ * @example Platform selection
+ * ```typescript
+ * const timeback = new TimebackClient({
+ *   platform: 'LEARNWITH_AI',
+ *   env: 'production',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ * ```
+ *
+ * @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 timeback = new TimebackClient({ provider })
+ * ```
+ *
+ * @example Base URL mode (self-hosted)
+ * ```typescript
+ * const timeback = new TimebackClient({
+ *   baseUrl: 'https://timeback.myschool.edu',
+ *   auth: {
+ *     clientId: '...',
+ *     clientSecret: '...',
+ *     authUrl: 'https://timeback.myschool.edu/oauth/token',
+ *   },
+ * })
+ * ```
+ */
+export declare class TimebackClient {
+    private readonly provider;
+    private _closed;
+    private _oneroster?;
+    private _edubridge?;
+    private _caliper?;
+    /**
+     * Creates a new Timeback client.
+     *
+     * @param config - Client configuration (env, baseUrl, provider, or services mode).
+     *                 If omitted, reads from TIMEBACK_ENV, TIMEBACK_CLIENT_ID,
+     *                 and TIMEBACK_CLIENT_SECRET environment variables.
+     */
+    constructor(config?: TimebackClientConfig);
+    /**
+     * OneRoster API client for rostering and gradebook operations.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The OneRoster client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get oneroster(): OneRosterClientInstance;
+    /**
+     * Edubridge API client for simplified enrollments and analytics.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The Edubridge client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get edubridge(): EdubridgeClientInstance;
+    /**
+     * Caliper API client for learning analytics events.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The Caliper client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get caliper(): CaliperClientInstance;
+    /**
+     * Verify that OAuth authentication is working.
+     *
+     * Attempts to acquire a token using the provider's credentials.
+     * Returns a health check result with success/failure and latency info.
+     *
+     * @returns Auth check result
+     * @throws {Error} If client has been closed
+     */
+    checkAuth(): Promise<AuthCheckResult>;
+    /**
+     * Close the client and release resources.
+     *
+     * After calling close():
+     * - Cached OAuth tokens are invalidated
+     * - Sub-client references are cleared
+     * - Further API calls will throw an error
+     */
+    close(): void;
+    /**
+     * Check if the client has been closed.
+     * @returns True if closed
+     */
+    get closed(): boolean;
+    /**
+     * Get the underlying provider for advanced use cases.
+     *
+     * @returns The TimebackProvider instance used by this client
+     */
+    getProvider(): TimebackProvider;
+    /**
+     * Throw if the client has been closed.
+     */
+    private assertOpen;
+    /**
+     * Throw if a service is not configured.
+     * @param service - Service name to check
+     */
+    private assertService;
+}
+//# 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":"AAOA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AACxF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAEzD;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,OAAO,CAAQ;IAEvB,OAAO,CAAC,UAAU,CAAC,CAAyB;IAC5C,OAAO,CAAC,UAAU,CAAC,CAAyB;IAC5C,OAAO,CAAC,QAAQ,CAAC,CAAuB;IAExC;;;;;;OAMG;IACH,YAAY,MAAM,CAAC,EAAE,oBAAoB,EAUxC;IAED;;;;;;;;OAQG;IACH,IAAI,SAAS,IAAI,uBAAuB,CASvC;IAED;;;;;;;;OAQG;IACH,IAAI,SAAS,IAAI,uBAAuB,CASvC;IAED;;;;;;;;OAQG;IACH,IAAI,OAAO,IAAI,qBAAqB,CASnC;IAMD;;;;;;;;OAQG;IACH,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC,CAGpC;IAED;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI,CAUZ;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACH,WAAW,IAAI,gBAAgB,CAE9B;IAED;;OAEG;IACH,OAAO,CAAC,UAAU;IAMlB;;;OAGG;IACH,OAAO,CAAC,aAAa;CAKrB"}

package/dist/constants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Timeback API Endpoints
+ *
+ * Re-exports URL constants from `@timeback/internal-constants`.
+ */
+import type { ResolveEnvVars } from '@timeback/internal-client-infra';
+import type { Environment, EnvServiceUrls, Platform } from './types';
+/**
+ * Environment variable names for Timeback client configuration.
+ */
+export declare const TIMEBACK_ENV_VARS: ResolveEnvVars;
+/**
+ * Get all service URLs for a given platform and environment.
+ *
+ * @param env - Target environment (staging or production)
+ * @param platform - Target platform (defaults to 'BEYOND_AI')
+ * @returns Service URLs for the environment
+ */
+export declare function getServiceUrlsForEnv(env: Environment, platform?: Platform): EnvServiceUrls;
+//# 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,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAMpE;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAM/B,CAAA;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,WAAW,EAChB,QAAQ,GAAE,QAA2B,GACnC,cAAc,CAQhB"}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Error Classes
+ *
+ * Re-exported from `@timeback/internal-client-infra`.
+ */
+export { ApiError, 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,EACR,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,GACf,MAAM,iCAAiC,CAAA"}