timeback 0.1.2 → 0.1.4

package/README.md

@@ -1,447 +1,59 @@
-# 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)
+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 { createServer } from 'timeback'
-
-export const timeback = await createServer({
-	env: 'staging', // 'development' | '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: ({ user, redirect }) => {
-			// Set session, then redirect
-			return redirect('/')
-		},
-		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)
+bunx 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>
+## Usage
 
-<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()}
-```
-
-```svelte
-<!-- +page.svelte -->
-<script>
-	import { onMount, onDestroy } from 'svelte'
-	import { SignInButton, timeback } from 'timeback/svelte'
-
-	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:
-
-```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: ({ user, state, redirect }) => redirect('/'),
-	onCallbackError: ({ error, redirect }) => redirect('/?error=sso_failed'),
-	getUser: () => getCurrentSession(),
-}
-```
-
-### Custom Mode
-
-For apps with existing auth (Clerk, Auth0, Supabase, etc.):
-
-```typescript
-identity: {
-	mode: 'custom',
-	getUser: async (req) => {
-		const session = await getSession(req)
-		if (!session) return undefined
-		return { id: session.userId, email: session.email, name: session.name }
-	},
-}
+```bash
+timeback <command> [options]
+timeback --help
 ```
 
-## Identity-Only Integration
+## Commands
 
-If you only need Timeback SSO authentication without activity tracking or Timeback API integration, use `createIdentityServer()`. This is a lightweight alternative that:
+### `timeback api`
 
-- Does not require Timeback API credentials
-- Does not require `timeback.config.ts`
-- Only exposes identity routes (sign-in, callback, sign-out)
+Interact with education data APIs.
 
-### Server Setup
-
-```typescript
-// lib/timeback.ts
-import { createIdentityServer } from 'timeback'
-
-export const timeback = createIdentityServer({
-	env: 'production',
-	identity: {
-		mode: 'sso',
-		clientId: process.env.AWS_COGNITO_CLIENT_ID!,
-		clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
-		onCallbackSuccess: async ({ user, tokens, redirect }) => {
-			// Create your own session, then redirect
-			await createSession(user)
-			return redirect('/')
-		},
-		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'
+```bash
+# Discovery
+timeback api describe --service oneroster
 
-import { timeback } from '@/lib/timeback'
+# 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>
 
-export const { GET, POST } = toNextjsHandler(timeback)
+# Filtering
+timeback api oneroster enrollments list --active --classes id1,id2
+timeback api oneroster users list --role teacher --max 100
 ```
 
-### Express
+See `timeback api oneroster --help` for all resources and options.
 
-```typescript
-// server.ts
-import express from 'express'
-import { toExpressMiddleware } from 'timeback/express'
+## Configuration
 
-import { timeback } from './lib/timeback'
+API clients read credentials from environment variables:
 
-const app = express()
-app.use('/api/timeback', toExpressMiddleware(timeback))
+```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"
 ```
 
-All other framework adapters (Nuxt, SvelteKit, SolidStart, TanStack Start) work identically with identity-only instances.
+## Debug Mode
 
-## 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,
-})
+```bash
+DEBUG=1 timeback api oneroster schools list
 ```
-
-The SDK automatically sends activity data to your server, which forwards it to the Timeback API.

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';