timeback 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,26 @@
 # Timeback SDK
 
-TypeScript SDK for integrating with Timeback, providing both server-side BFF logic and client-side React components.
+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)
 
 ## Installation
 
@@ -10,210 +30,418 @@ npm install timeback
 bun add timeback
 ```
 
-## Server-Side Setup
+## Quick Start
 
-The server SDK auto-discovers your `timeback.config.ts` file and provides route handlers for Next.js.
+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
 
-### Configuration
+## Server Adapters
 
-```typescript
-// app/lib/timeback.ts
-import { createTimeback } from 'timeback'
+All server adapters use the same core configuration:
 
-export const timeback = await createTimeback({
-	env: 'production', // 'development' | 'staging' | 'production'
+```typescript
+// lib/timeback.ts
+import { createServer } from 'timeback'
 
-	// API credentials for Timeback API calls
+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 configuration
 	identity: {
-		// Option A: Timeback SSO
 		mode: 'sso',
-		clientId: process.env.TIMEBACK_SSO_CLIENT_ID!,
-		clientSecret: process.env.TIMEBACK_SSO_CLIENT_SECRET!,
-
-		// Option B: Custom identity provider (Clerk, Auth0, Supabase, etc.)
-		mode: 'custom',
-		getUser: async req => {
-			const session = await getSession(req)
-			return {
-				id: session.userId,
-				email: session.user.email,
-				name: session.user.name,
-			}
+		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 Route Handlers
+### Next.js
 
 ```typescript
 // app/api/timeback/[...timeback]/route.ts
+import { toNextjsHandler } from 'timeback/nextjs'
+
 import { timeback } from '@/lib/timeback'
 
-export const { GET, POST } = timeback.handlers()
+export const { GET, POST } = toNextjsHandler(timeback)
 ```
 
-This exposes:
+### Nuxt
+
+```typescript
+// server/middleware/timeback.ts
+import { nuxtHandler } from 'timeback/nuxt'
 
-- `POST /api/timeback/activity` - Receives activity events from client
-- `GET /api/timeback/identity/session` - Returns current user
-- `GET /api/timeback/identity/signin` - Initiates SSO flow (SSO mode only)
-- `GET /api/timeback/identity/callback` - SSO callback (SSO mode only)
+import { timeback } from '../lib/timeback'
 
-## Client-Side Setup
+export default defineEventHandler(async event => {
+	const response = await nuxtHandler({
+		timeback,
+		event,
+	})
+	if (response) return response
+})
+```
 
-### Configuration
+### SvelteKit
 
 ```typescript
-// app/lib/timeback-client.ts
-import { createTimebackClient } from 'timeback/client/react'
+// 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,
+	})
+}
+```
 
-// Zero config - baseURL defaults to window.location.origin + '/api/timeback'
-export const timebackClient = createTimebackClient()
+### SolidStart
 
-// Or with explicit URL
-export const timebackClient = createTimebackClient({
-	baseURL: 'https://myapp.com/api/timeback',
+```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
+		},
+	],
 })
 ```
 
-### React Provider
+### 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
-import { TimebackProvider } from 'timeback/client/react'
+'use client'
 
-import { timebackClient } from '@/lib/timeback-client'
+import { TimebackProvider } from 'timeback/react'
 
-export function Providers({ children }) {
-	return <TimebackProvider client={timebackClient}>{children}</TimebackProvider>
+export function Providers({ children }: { children: React.ReactNode }) {
+	return <TimebackProvider>{children}</TimebackProvider>
 }
 ```
 
-### Hooks
-
 ```tsx
-import { useActivity, useTimeback } from 'timeback/client/react'
+// components/ActivityTracker.tsx
+import { useEffect } from 'react'
+import { SignInButton, useTimeback } from 'timeback/react'
 
-function UserMenu() {
-	const { user, isLoading, identityMode, signIn, signOut } = useTimeback()
+function MyComponent() {
+	const timeback = useTimeback()
 
-	if (isLoading) return <Spinner />
+	useEffect(() => {
+		if (!timeback) return
 
-	if (!user) {
-		return <button onClick={signIn}>Sign In</button>
-	}
+		const activity = timeback.activity
+			.new({ id: 'lesson-1', name: 'Intro', courseCode: 'MATH-101' })
+			.start()
 
-	return (
-		<div>
-			<span>{user.name}</span>
-			<button onClick={signOut}>Sign Out</button>
-		</div>
-	)
+		return () => {
+			activity.end()
+		}
+	}, [timeback])
+
+	return <SignInButton size="lg" />
 }
 ```
 
-### Activity Tracking
+### Vue
 
-#### React Hook
+```vue
+<!-- app.vue -->
+<script setup>
+import { TimebackProvider } from 'timeback/vue'
+</script>
 
-```tsx
-function LessonPlayer({ lessonId, courseCode }) {
-	// Starts on mount, ends on unmount, restarts if deps change
-	const activity = useActivity({
-		type: 'lesson',
-		objectId: lessonId,
-		courseCode,
+<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 (
-		<>
-			<button onClick={() => activity.pause()}>Pause</button>
-			<button onClick={() => activity.resume()}>Resume</button>
-			<span>Time: {activity.elapsedMs}ms</span>
-		</>
+		<TimebackProvider>
+			<Router root={props => <Suspense>{props.children}</Suspense>}>
+				<FileRoutes />
+			</Router>
+		</TimebackProvider>
 	)
 }
 ```
 
-#### Vanilla API
+```tsx
+// components/ActivityTracker.tsx
+import { onCleanup, onMount } from 'solid-js'
+import { SignInButton, useTimeback } from 'timeback/solid'
 
-```typescript
-import { createTimebackClient } from 'timeback/client'
+function MyComponent() {
+	const timeback = useTimeback()
+	let activity
 
-const client = createTimebackClient()
+	onMount(() => {
+		if (!timeback) return
 
-// Start tracking
-const activity = client.startActivity({
-	type: 'lesson',
-	objectId: 'lesson-123',
-	courseCode: 'FASTMATH-1',
-})
+		activity = timeback.activity
+			.new({ id: 'lesson-1', name: 'Intro', courseCode: 'MATH-101' })
+			.start()
+	})
 
-// Pause/resume as needed
-activity.pause()
-activity.resume()
+	onCleanup(() => activity?.end())
 
-// End tracking - sends ActivityCompletedEvent + TimeSpentEvent to server
-await activity.end()
+	return <SignInButton size="lg" />
+}
 ```
 
 ## Identity Modes
 
-### Timeback SSO
+### SSO Mode
 
-Uses Timeback as the identity provider via OIDC. Users sign in through Timeback's authentication flow.
+Uses Timeback as the identity provider via OIDC:
 
 ```typescript
 identity: {
-  mode: 'sso',
-  clientId: process.env.TIMEBACK_SSO_CLIENT_ID!,
-  clientSecret: process.env.TIMEBACK_SSO_CLIENT_SECRET!,
+	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 Identity
+### Custom Mode
 
-For apps with existing authentication (Clerk, Auth0, Supabase, etc.), provide a `getUser` function that returns the current user.
+For apps with existing auth (Clerk, Auth0, Supabase, etc.):
 
 ```typescript
 identity: {
-  mode: 'custom',
-  getUser: async (req) => {
-    // Use your existing auth system
-    const session = await clerk.getSession(req)
-    return {
-      id: session.userId,
-      email: session.user.email,
-      name: session.user.name,
-    }
-  },
+	mode: 'custom',
+	getUser: async (req) => {
+		const session = await getSession(req)
+		if (!session) return undefined
+		return { id: session.userId, email: session.email, name: session.name }
+	},
 }
 ```
 
-## API Reference
+## Identity-Only Integration
 
-### Server
+If you only need Timeback SSO authentication without activity tracking or Timeback API integration, use `createIdentityServer()`. This is a lightweight alternative that:
 
-- `createTimeback(config)` - Create a Timeback server instance
-- `timeback.handlers()` - Get Next.js route handlers
+- Does not require Timeback API credentials
+- Does not require `timeback.config.ts`
+- Only exposes identity routes (sign-in, callback, sign-out)
 
-### Client
+### Server Setup
 
-- `createTimebackClient(config?)` - Create a Timeback client
-- `client.startActivity(params)` - Start tracking an activity
-- `client.signIn()` - Initiate SSO sign-in
-- `client.signOut()` - Sign out
-- `client.fetchSession()` - Fetch current session
+```typescript
+// lib/timeback.ts
+import { createIdentityServer } from 'timeback'
 
-### React
+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'
+
+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,
+})
+```
 
-- `TimebackProvider` - Context provider
-- `useTimeback()` - Hook for identity state and actions
-- `useActivity(params)` - Hook for activity tracking with lifecycle management
+The SDK automatically sends activity data to your server, which forwards it to the Timeback API.