timeback 0.1.3 → 0.1.5

package/README.md

@@ -1,584 +1,99 @@
-# Timeback SDK
+# timeback
 
-TypeScript SDK for integrating Timeback into your application. Provides server-side route handlers and client-side components for activity tracking and SSO authentication.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Server Adapters](#server-adapters)
-    - [Next.js](#nextjs)
-    - [Nuxt](#nuxt)
-    - [SvelteKit](#sveltekit)
-    - [SolidStart](#solidstart)
-    - [TanStack Start](#tanstack-start)
-    - [Express](#express)
-- [Client Adapters](#client-adapters)
-    - [React](#react)
-    - [Vue](#vue)
-    - [Svelte](#svelte)
-    - [Solid](#solid)
-- [Identity Modes](#identity-modes)
-- [Identity-Only Integration](#identity-only-integration)
-- [Activity Tracking](#activity-tracking)
-- [Advanced: Direct API Access](#advanced-direct-api-access)
+CLI for the Timeback platform.
 
 ## Installation
 
 ```bash
-npm install timeback
+bun add -g timeback
 # or
-bun add timeback
-```
-
-## Quick Start
-
-1. Create a server instance with your credentials
-2. Mount the route handlers for your framework
-3. Wrap your app with the client provider
-4. Use hooks/composables to track activities
-
-## Server Adapters
-
-All server adapters use the same core configuration:
-
-```typescript
-// lib/timeback.ts
-import { createTimeback } from 'timeback'
-
-export const timeback = await createTimeback({
-	env: 'staging', // 'local' | 'staging' | 'production'
-	api: {
-		clientId: process.env.TIMEBACK_API_CLIENT_ID!,
-		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
-	},
-	identity: {
-		mode: 'sso',
-		clientId: process.env.AWS_COGNITO_CLIENT_ID!,
-		clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
-		redirectUri: 'http://localhost:3000/api/auth/sso/callback/timeback',
-		onCallbackSuccess: async ({ user, state, redirect }) => {
-			// user.id is the timebackId (canonical stable identifier)
-			await setSession({ id: user.id, email: user.email })
-			return redirect(state?.returnTo ?? '/')
-		},
-		onCallbackError: ({ error, redirect }) => {
-			console.error('SSO Error:', error)
-			return redirect('/?error=sso_failed')
-		},
-		getUser: () => getSession(), // Return current user or undefined
-	},
-})
-```
-
-### Next.js
-
-```typescript
-// app/api/timeback/[...timeback]/route.ts
-import { toNextjsHandler } from 'timeback/nextjs'
-
-import { timeback } from '@/lib/timeback'
-
-export const { GET, POST } = toNextjsHandler(timeback)
-```
-
-### Nuxt
-
-```typescript
-// server/middleware/timeback.ts
-import { nuxtHandler } from 'timeback/nuxt'
-
-import { timeback } from '../lib/timeback'
-
-export default defineEventHandler(async event => {
-	const response = await nuxtHandler({
-		timeback,
-		event,
-	})
-	if (response) return response
-})
-```
-
-### SvelteKit
-
-```typescript
-// src/hooks.server.ts
-import { building } from '$app/environment'
-import { timeback } from '$lib/timeback'
-import { svelteKitHandler } from 'timeback/svelte-kit'
-
-import type { Handle } from '@sveltejs/kit'
-
-export const handle: Handle = ({ event, resolve }) => {
-	return svelteKitHandler({
-		timeback,
-		event,
-		resolve,
-		building,
-	})
-}
-```
-
-### SolidStart
-
-```typescript
-// src/middleware.ts
-import { createMiddleware } from '@solidjs/start/middleware'
-import { timeback } from '~/lib/timeback'
-import { solidStartHandler } from 'timeback/solid-start'
-
-export default createMiddleware({
-	onRequest: [
-		async event => {
-			const response = await solidStartHandler({
-				timeback,
-				event,
-			})
-			if (response) return response
-		},
-	],
-})
-```
-
-### TanStack Start
-
-```typescript
-// src/routes/api/timeback/$.ts
-import { createFileRoute } from '@tanstack/react-router'
-import { toTanStackStartHandler } from 'timeback/tanstack-start'
-
-import { timeback } from '@/lib/timeback'
-
-const handlers = toTanStackStartHandler(timeback)
-
-export const Route = createFileRoute('/api/timeback/$')({
-	server: { handlers },
-})
-```
-
-### Express
-
-```typescript
-// server.ts
-import express from 'express'
-import { toExpressMiddleware } from 'timeback/express'
-
-import { timeback } from './lib/timeback'
-
-const app = express()
-app.use(express.json())
-app.use('/api/timeback', toExpressMiddleware(timeback))
-```
-
-## Client Adapters
-
-### React
-
-```tsx
-// app/providers.tsx
-'use client'
-
-import { TimebackProvider } from 'timeback/react'
-
-export function Providers({ children }: { children: React.ReactNode }) {
-	return <TimebackProvider>{children}</TimebackProvider>
-}
-```
-
-```tsx
-// components/ActivityTracker.tsx
-import { useEffect } from 'react'
-import { SignInButton, useTimeback } from 'timeback/react'
-
-function MyComponent() {
-	const timeback = useTimeback()
-
-	useEffect(() => {
-		if (!timeback) return
-
-		const activity = timeback.activity
-			.new({ id: 'lesson-1', name: 'Intro', courseCode: 'MATH-101' })
-			.start()
-
-		return () => {
-			activity.end()
-		}
-	}, [timeback])
-
-	return <SignInButton size="lg" />
-}
-```
-
-### Vue
-
-```vue
-<!-- app.vue -->
-<script setup>
-import { TimebackProvider } from 'timeback/vue'
-</script>
-
-<template>
-	<TimebackProvider>
-		<NuxtPage />
-	</TimebackProvider>
-</template>
-```
-
-```vue
-<!-- components/ActivityTracker.vue -->
-<script setup>
-import { SignInButton, useTimeback } from 'timeback/vue'
-import { onMounted, onUnmounted } from 'vue'
-
-const timeback = useTimeback()
-let activity
-
-onMounted(() => {
-	if (timeback.value) {
-		activity = timeback.value.activity
-			.new({ id: 'lesson-1', name: 'Intro', courseCode: 'MATH-101' })
-			.start()
-	}
-})
-
-onUnmounted(() => activity?.end())
-</script>
-
-<template>
-	<SignInButton size="lg" />
-</template>
-```
-
-### Svelte
-
-```svelte
-<!-- +layout.svelte -->
-<script>
-	import { initTimeback } from 'timeback/svelte'
-
-	initTimeback()
-
-	let { children } = $props()
-</script>
-
-{@render children()}
+bunx timeback
 ```
 
-```svelte
-<!-- +page.svelte -->
-<script>
-	import { onMount, onDestroy } from 'svelte'
-	import { SignInButton, timeback } from 'timeback/svelte'
+## Usage
 
-	let activity
-
-	onMount(() => {
-		if ($timeback) {
-			activity = $timeback.activity
-				.new({ id: 'lesson-1', name: 'Intro', courseCode: 'MATH-101' })
-				.start()
-		}
-	})
-
-	onDestroy(() => activity?.end())
-</script>
-
-<SignInButton size="lg" />
-```
-
-### Solid
-
-```tsx
-// app.tsx
-import { TimebackProvider } from 'timeback/solid'
-
-export default function App() {
-	return (
-		<TimebackProvider>
-			<Router root={props => <Suspense>{props.children}</Suspense>}>
-				<FileRoutes />
-			</Router>
-		</TimebackProvider>
-	)
-}
-```
-
-```tsx
-// components/ActivityTracker.tsx
-import { onCleanup, onMount } from 'solid-js'
-import { SignInButton, useTimeback } from 'timeback/solid'
-
-function MyComponent() {
-	const timeback = useTimeback()
-	let activity
-
-	onMount(() => {
-		if (!timeback) return
-
-		activity = timeback.activity
-			.new({ id: 'lesson-1', name: 'Intro', courseCode: 'MATH-101' })
-			.start()
-	})
-
-	onCleanup(() => activity?.end())
-
-	return <SignInButton size="lg" />
-}
-```
-
-## Identity Modes
-
-### SSO Mode
-
-Uses Timeback as the identity provider via OIDC. When using `createTimeback()`, the SDK automatically resolves the Timeback user by email and returns an enriched `TimebackAuthUser` with `user.id` being the canonical `timebackId` (stable identifier).
-
-```typescript
-identity: {
-	mode: 'sso',
-	clientId: process.env.AWS_COGNITO_CLIENT_ID!,
-	clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
-	redirectUri: 'http://localhost:3000/api/auth/sso/callback/timeback',
-	onCallbackSuccess: async ({ user, idp, state, redirect }) => {
-		// user.id is the timebackId (canonical stable identifier)
-		// user.email, user.name come from Timeback profile
-		// user.claims contains IdP data (sub, firstName, lastName, pictureUrl)
-		// idp.tokens and idp.userInfo contain raw OIDC data if needed
-		await setSession({ id: user.id, email: user.email })
-		return redirect(state?.returnTo ?? '/')
-	},
-	onCallbackError: ({ error, errorCode, redirect }) => {
-		// errorCode may be: missing_email, timeback_user_not_found,
-		// timeback_user_ambiguous, timeback_user_lookup_failed
-		console.error('SSO Error:', errorCode, error.message)
-		return redirect('/?error=sso_failed')
-	},
-	getUser: () => getCurrentSession(),
-}
+```bash
+timeback <command> [options]
+timeback --help
 ```
 
-#### TimebackAuthUser Shape
-
-The `user` in `onCallbackSuccess` is a `TimebackAuthUser` with this structure:
+## Commands
 
-```typescript
-interface TimebackAuthUser {
-	id: string // Timeback user ID
-	email: string
-	name?: string
-	school?: { id: string; name: string }
-	grade?: number
-	claims: {
-		sub: string // OIDC subject identifier
-		email: string
-		firstName?: string
-		lastName?: string
-		pictureUrl?: string
-	}
-}
-```
+### `timeback api`
 
-#### Session Storage Guidance
+Interact with education data APIs.
 
-For cookie-only sessions, store only the minimal payload to avoid cookie size limits:
+```bash
+# Discovery
+timeback api describe --service oneroster
 
-```typescript
-// Recommended: store minimal session
-await setSession({ id: user.id, email: user.email })
+# CRUD
+timeback api oneroster schools list --env production
+timeback api oneroster users get <id>
+timeback api oneroster users create --file user.json
+timeback api oneroster users delete <id>
 
-// Then in getUser, return what you stored:
-getUser: req => {
-	const session = getSessionFromCookie(req)
-	return session ? { id: session.id, email: session.email } : undefined
-}
+# Filtering
+timeback api oneroster enrollments list --active --classes id1,id2
+timeback api oneroster users list --role teacher --max 100
 ```
 
-For DB-backed sessions, you can store the full `TimebackAuthUser` if desired.
+See `timeback api oneroster --help` for all resources and options.
 
-### Custom Mode
+## Configuration
 
-For apps with existing auth (Clerk, Auth0, Supabase, etc.):
+API clients read credentials from environment variables:
 
-```typescript
-identity: {
-	mode: 'custom',
-	getUser: async (req) => {
-		const session = await getSession(req)
-		if (!session) return undefined
-		// Return user with timebackId as the id
-		return { id: session.timebackId, email: session.email, name: session.name }
-	},
-}
+```bash
+# OneRoster
+export ONEROSTER_BASE_URL="https://api.example.com"
+export ONEROSTER_TOKEN_URL="https://auth.example.com/oauth2/token"
+export ONEROSTER_CLIENT_ID="your-client-id"
+export ONEROSTER_CLIENT_SECRET="your-client-secret"
 ```
 
-## Identity-Only Integration
-
-If you only need Timeback SSO authentication without activity tracking or Timeback API integration, use `createTimebackIdentity()`. This is a lightweight alternative that:
-
-- Does not require Timeback API credentials
-- Does not require `timeback.config.ts`
-- Only exposes identity routes (sign-in, callback, sign-out)
-- Returns raw OIDC user info (no Timeback profile enrichment)
-
-**Note:** Unlike `createTimeback()`, the identity-only callback returns raw OIDC user info (`sub`, `email`, `name`, etc.) without resolving a Timeback user. Use `createTimeback()` if you need the canonical `timebackId`.
-
-### Cloudflare Workers / workerd compatibility
+### `timeback.config.ts`
 
-`createTimebackIdentity()` is runtime-agnostic, but the main `timeback` entrypoint also includes
-Node-oriented functionality (notably config loading via `jiti`). Some edge runtimes
-(Cloudflare Workers / workerd) do not support the Node modules that `jiti` depends on.
+Many CLI commands (notably `timeback init`, `timeback import`, `timeback edit`, `timeback sync`) read/write a `timeback.config.ts` file.
 
-If you're deploying identity-only SSO on Workers/workerd, import from the worker-safe entrypoint:
+For fields that can differ per environment (staging vs production), use `course.overrides`:
 
 ```ts
-import { createTimebackIdentity, toNativeHandler } from 'timeback/edge'
-```
-
-### Server Setup
-
-```typescript
-// lib/timeback.ts
-import { createTimebackIdentity } from 'timeback'
-
-export const timeback = createTimebackIdentity({
-	env: 'production',
-	identity: {
-		mode: 'sso',
-		clientId: process.env.AWS_COGNITO_CLIENT_ID!,
-		clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
-		onCallbackSuccess: async ({ user, tokens, redirect }) => {
-			// user is raw OIDC userInfo (sub, email, name, picture, etc.)
-			// No Timeback profile enrichment in identity-only mode
-			await createSession({
-				sub: user.sub,
-				email: user.email,
-				name: user.name,
-			})
-			return redirect('/')
+export default {
+	name: 'My App',
+	// Default Caliper sensor (lowest priority)
+	sensor: 'https://my-app.example.com/sensors/default',
+	courses: [
+		{
+			subject: 'Math',
+			grade: 3,
+			courseCode: 'MATH-3',
+			// Base values (apply to all envs unless overridden)
+			level: 'Elementary',
+			metadata: { publishStatus: 'testing' },
+			// Env-specific overrides (applied when syncing/editing in that env)
+			overrides: {
+				staging: {
+					level: 'Staging Level',
+					sensor: 'https://staging.my-app.example.com/sensors/math',
+					metadata: { publishStatus: 'draft' },
+				},
+				production: {
+					metadata: { publishStatus: 'published' },
+				},
+			},
 		},
-		onCallbackError: ({ error, redirect }) => {
-			console.error('SSO Error:', error)
-			return redirect('/login?error=sso_failed')
-		},
-		getUser: req => getSessionFromRequest(req),
-	},
-})
-```
-
-### Next.js
-
-```typescript
-// app/api/timeback/[...timeback]/route.ts
-import { toNextjsHandler } from 'timeback/nextjs'
-
-import { timeback } from '@/lib/timeback'
-
-export const { GET, POST } = toNextjsHandler(timeback)
-```
-
-### Express
-
-```typescript
-// server.ts
-import express from 'express'
-import { toExpressMiddleware } from 'timeback/express'
-
-import { timeback } from './lib/timeback'
-
-const app = express()
-app.use('/api/timeback', toExpressMiddleware(timeback))
-```
-
-All other framework adapters (Nuxt, SvelteKit, SolidStart, TanStack Start) work identically with identity-only instances.
-
-## Activity Tracking
-
-Activities track time spent on learning content:
-
-```typescript
-// Start an activity
-const activity = timeback.activity
-	.new({
-		id: 'lesson-123',
-		name: 'Introduction to Fractions',
-		courseCode: 'MATH-101',
-	})
-	.start()
-
-// Pause/resume
-activity.pause()
-activity.resume()
-
-// End with metrics
-await activity.end({
-	totalQuestions: 10,
-	correctQuestions: 8,
-	xpEarned: 80,
-	masteredUnits: 1,
-})
-```
-
-The SDK automatically sends activity data to your server, which forwards it to the Timeback API.
-
-## Advanced: Direct API Access
-
-For advanced use cases that need to call Timeback services (OneRoster, Edubridge, Caliper, QTI) beyond what the SDK handlers provide, use `timeback.api`:
-
-```typescript
-// Access via the timeback instance (lazy-initialized on first access)
-const { data: users } = await timeback.api.oneroster.users.list({
-	limit: 10,
-	where: { role: 'student' },
-})
-
-// Access any Timeback service
-const { data: orgs } = await timeback.api.oneroster.orgs.list()
-await timeback.api.caliper.emit(caliperEvent)
+	],
+}
 ```
 
-### Access Patterns
-
-```typescript
-// lib/timeback.ts
-import { createTimeback } from 'timeback'
-
-export const timeback = await createTimeback({
-	env: 'staging',
-	api: {
-		clientId: process.env.TIMEBACK_API_CLIENT_ID!,
-		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
-	},
-	identity: { mode: 'custom', getUser: () => getSession() },
-})
+Override merge rules:
 
-// Access the API client via timeback.api
-const { data: users } = await timeback.api.oneroster.users.list()
-```
+- `defaults` → course → `overrides[env]` (for `level`, `sensor`, `metadata`)
+- `metadata` is merged (not replaced); `goals` and `metrics` are deep-merged
 
-```typescript
-// Elsewhere in your app
-import { timeback } from './lib/timeback'
+## Debug Mode
 
-// The client is available at timeback.api
-const { data: orgs } = await timeback.api.oneroster.orgs.list()
+```bash
+DEBUG=1 timeback api oneroster schools list
 ```
-
-### Environment Mapping
-
-The SDK's `env` config controls runtime mode, but for outbound API calls:
-
-| SDK `env`    | API calls use |
-| ------------ | ------------- |
-| `local`      | `staging`     |
-| `staging`    | `staging`     |
-| `production` | `production`  |
-
-This means `env: 'local'` uses staging Timeback services, so you can develop locally against real (staging) data without additional configuration.
-
-### When to Use
-
-- Fetching data not exposed by SDK handlers (e.g., listing orgs, courses, enrollments)
-- Emitting custom Caliper events
-- Building admin dashboards or reporting tools
-- Any direct Timeback API integration
-
-**Note:** `timeback.api` is only available on the full SDK (`createTimeback()`), not on identity-only instances (`createTimebackIdentity()`).

package/dist/cli/src/config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Config types for timeback.config.ts files.
+ *
+ * Re-exported from `@timeback/types` so users can import `timeback/config`
+ * for editor IntelliSense in TS config files. SDK users can also use
+ * `@timeback/sdk/config` which exports the same types.
+ */
+export type { CourseConfig, CourseDefaults, CourseGoals, CourseIds, CourseMetadata, CourseMetrics, CourseType, PublishStatus, TimebackConfig, } from '@timeback/types';