@timeback/masterytrack 0.1.1-beta.20260219190739

package/README.md

@@ -0,0 +1,225 @@
+# @timeback/masterytrack
+
+TypeScript client for the MasteryTrack API — test inventory, assignment delivery, and student assessment management.
+
+## Installation
+
+```bash
+bun add @timeback/masterytrack
+```
+
+## Quick Start
+
+```typescript
+import { MasteryTrackClient } from '@timeback/masterytrack'
+
+const client = new MasteryTrackClient({
+	env: 'staging', // or 'production'
+	auth: {
+		apiKey: 'your-api-key',
+		email: 'your-registered-email@example.com',
+	},
+})
+
+// Search available tests
+const { data: tests } = await client.inventory.search({ subject: 'Math' })
+
+// Assign a test to a student
+const result = await client.assignments.assign({
+	student_email: 'student@example.com',
+	timeback_id: '_677e37c49e904cafcc66fdb4',
+})
+
+// Invalidate an assignment
+await client.assignments.invalidate({
+	student_email: 'student@example.com',
+	assignment_id: 123,
+})
+```
+
+## Client Structure
+
+```typescript
+const client = new MasteryTrackClient(options)
+
+// Authentication
+client.authorizer.getToken(email?)       // Get a fresh JWT
+
+// Inventory
+client.inventory.search(params?)         // Search and filter available tests
+
+// Assignments
+client.assignments.assign(input)         // Assign a test to a student
+client.assignments.invalidate(input)     // Invalidate student assignments
+
+// Utilities
+client.checkAuth()                       // Verify credentials are valid
+client.getTransport()                    // Access the underlying transport
+```
+
+### Inventory Search
+
+Search and filter tests with optional parameters:
+
+```typescript
+// List all supported tests
+const { data } = await client.inventory.search()
+
+// Filter by criteria
+const { data } = await client.inventory.search({
+	name: 'Math',
+	grade: 'Third Grade',
+	subject: 'Math',
+	timeback_id: '_677e37c49e904cafcc66fdb4',
+	all: true, // include non-supported tests
+})
+```
+
+### Assignments
+
+Assign tests by `timeback_id` or by `subject` (optionally with `grade_rank`):
+
+```typescript
+// Assign by timeback_id
+await client.assignments.assign({
+	student_email: 'student@example.com',
+	timeback_id: '_677e37c49e904cafcc66fdb4',
+})
+
+// Assign by subject and grade
+await client.assignments.assign({
+	student_email: 'student@example.com',
+	subject: 'Math',
+	grade_rank: 3,
+})
+
+// Invalidate by assignment ID
+await client.assignments.invalidate({
+	student_email: 'student@example.com',
+	assignment_id: 123,
+})
+
+// Invalidate by timeback_id
+await client.assignments.invalidate({
+	student_email: 'student@example.com',
+	timeback_id: '_677e37c49e904cafcc66fdb4',
+})
+```
+
+### Authentication
+
+MasteryTrack uses API key + email authentication (not OAuth2). The client handles JWT token acquisition and caching automatically:
+
+```typescript
+// Environment mode (recommended)
+const client = new MasteryTrackClient({
+	env: 'staging', // or 'production'
+	auth: {
+		apiKey: 'your-api-key',
+		email: 'your-registered-email@example.com',
+	},
+})
+
+// Explicit URL mode
+const client = new MasteryTrackClient({
+	baseUrl: 'https://custom-api.example.com',
+	auth: {
+		apiKey: 'your-api-key',
+		email: 'your-registered-email@example.com',
+	},
+})
+
+// Verify credentials
+const result = await client.checkAuth()
+if (result.ok) {
+	console.log(`Auth OK (${result.latencyMs}ms)`)
+}
+```
+
+JWTs are cached and automatically refreshed before expiry.
+
+### Error Handling
+
+```typescript
+import { MasteryTrackError, NotFoundError, UnauthorizedError } from '@timeback/masterytrack/errors'
+
+try {
+	await client.assignments.assign(input)
+} catch (error) {
+	if (error instanceof UnauthorizedError) {
+		console.log('Invalid API key or email')
+	} else if (error instanceof MasteryTrackError) {
+		console.log(error.statusCode) // HTTP status
+		console.log(error.message)    // Error message
+	}
+}
+```
+
+### Custom Transport
+
+For advanced use cases, provide your own transport and authenticator:
+
+```typescript
+const client = new MasteryTrackClient({
+	transport: {
+		baseUrl: 'https://custom.example.com',
+		request: async (path, options) => { /* ... */ },
+		requestRaw: async (path, options) => { /* ... */ },
+	},
+	authenticator: {
+		getToken: async () => 'your-jwt',
+		invalidate: () => {},
+		checkAuth: async () => ({ ok: true, latencyMs: 0, checks: {} }),
+	},
+})
+```
+
+## Configuration
+
+```typescript
+new MasteryTrackClient({
+	// Environment mode (recommended)
+	env: 'staging' | 'production',
+	auth: {
+		apiKey: string,
+		email: string,
+	},
+
+	// OR Explicit URL mode
+	baseUrl: string,
+	auth: {
+		apiKey: string,
+		email: string,
+	},
+
+	// OR Custom transport mode
+	transport: MasteryTrackTransportLike,
+	authenticator: MasteryTrackAuthenticatorLike,
+
+	// Optional
+	timeout?: number, // Request timeout in ms (default: 30000)
+})
+```
+
+Environment variables fallback:
+
+- `TIMEBACK_MASTERYTRACK_API_KEY` / `MASTERYTRACK_API_KEY`
+- `TIMEBACK_MASTERYTRACK_EMAIL` / `MASTERYTRACK_EMAIL`
+- `TIMEBACK_MASTERYTRACK_BASE_URL` / `MASTERYTRACK_BASE_URL`
+
+## 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
+[2026-02-17T10:30:00.000Z] DEBUG [masterytrack:http] → POST https://api.example.com/authorizer
+[2026-02-17T10:30:00.500Z] DEBUG [masterytrack:http] ← 200 OK (500ms)
+[2026-02-17T10:30:00.501Z] DEBUG [masterytrack:http] → GET https://api.example.com/authoring/inventory/search
+[2026-02-17T10:30:00.800Z] DEBUG [masterytrack:http] ← 200 OK (299ms)
+```

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MasteryTrack Client
+ *
+ * Main entry point for the MasteryTrack SDK.
+ */
+/**
+ * MasteryTrack API client.
+ *
+ * @example
+ * ```typescript
+ * const client = new MasteryTrackClient({
+ *   env: 'staging',
+ *   auth: {
+ *     apiKey: 'your-api-key',
+ *     email: 'your-registered-email@example.com',
+ *   },
+ * })
+ * ```
+ */
+export declare const MasteryTrackClient: {
+    new (config?: import("./types").MasteryTrackClientConfig): {
+        readonly transport: import("./types").MasteryTrackTransportLike;
+        readonly authenticator: import("./types").MasteryTrackAuthenticatorLike;
+        readonly authorizer: import("./resources").AuthorizerResource;
+        readonly inventory: import("./resources").InventoryResource;
+        readonly assignments: import("./resources").AssignmentsResource;
+        getTransport(): import("./types").MasteryTrackTransportLike;
+        checkAuth(): Promise<import("@timeback/internal-client-infra").AuthCheckResult>;
+    };
+};
+export type { MasteryTrackClientInstance } 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;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;CAA6B,CAAA;AAE5D,YAAY,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA"}

package/dist/constants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MasteryTrack Constants
+ *
+ * Configuration constants for the MasteryTrack client.
+ */
+export declare const MASTERYTRACK_BASE_URLS: {
+    readonly staging: "https://l407b3xadi.execute-api.us-east-1.amazonaws.com/dev";
+    readonly production: "https://l407b3xadi.execute-api.us-east-1.amazonaws.com/prod";
+};
+/**
+ * Environment variable names for MasteryTrack configuration fallback.
+ * Priority: TIMEBACK_MASTERYTRACK_* > MASTERYTRACK_*
+ */
+export declare const MASTERYTRACK_ENV_VARS: {
+    readonly baseUrl: readonly ["TIMEBACK_MASTERYTRACK_BASE_URL", "MASTERYTRACK_BASE_URL"];
+    readonly apiKey: readonly ["TIMEBACK_MASTERYTRACK_API_KEY", "MASTERYTRACK_API_KEY"];
+    readonly email: readonly ["TIMEBACK_MASTERYTRACK_EMAIL", "MASTERYTRACK_EMAIL"];
+};
+//# 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;AAEH,eAAO,MAAM,sBAAsB;;;CAGzB,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;CAIxB,CAAA"}

package/dist/errors.d.ts

@@ -0,0 +1 @@
+export { ForbiddenError, InputValidationError, ApiError as MasteryTrackError, NotFoundError, UnauthorizedError, ValidationError } from '@timeback/internal-client-infra';

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,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACN,QAAQ,IAAI,iBAAiB,EAC7B,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,eAAe,GACf,CAAA"}