@timeback/sdk 0.1.4

package/README.md

@@ -0,0 +1,612 @@
+# Timeback SDK
+
+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)
+
+## Installation
+
+```bash
+npm install 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/sdk'
+
+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/sdk/nextjs'
+
+import { timeback } from '@/lib/timeback'
+
+export const { GET, POST } = toNextjsHandler(timeback)
+```
+
+### Nuxt
+
+```typescript
+// server/middleware/timeback.ts
+import { nuxtHandler } from '@timeback/sdk/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/sdk/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/sdk/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/sdk/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/sdk/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/sdk/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/sdk/react'
+
+function MyComponent() {
+	const timeback = useTimeback()
+
+	useEffect(() => {
+		if (!timeback) return
+
+		const activity = timeback.activity
+			.new({ id: 'lesson-1', name: 'Intro', course: { subject: 'Math', grade: 3 } })
+			.start()
+
+		return () => {
+			activity.end()
+		}
+	}, [timeback])
+
+	return <SignInButton size="lg" />
+}
+```
+
+### Vue
+
+```vue
+<!-- app.vue -->
+<script setup>
+import { TimebackProvider } from '@timeback/sdk/vue'
+</script>
+
+<template>
+	<TimebackProvider>
+		<NuxtPage />
+	</TimebackProvider>
+</template>
+```
+
+```vue
+<!-- components/ActivityTracker.vue -->
+<script setup>
+import { SignInButton, useTimeback } from '@timeback/sdk/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', course: { subject: 'Math', grade: 3 } })
+			.start()
+	}
+})
+
+onUnmounted(() => activity?.end())
+</script>
+
+<template>
+	<SignInButton size="lg" />
+</template>
+```
+
+### Svelte
+
+```svelte
+<!-- +layout.svelte -->
+<script>
+	import { initTimeback } from '@timeback/sdk/svelte'
+
+	initTimeback()
+
+	let { children } = $props()
+</script>
+
+{@render children()}
+```
+
+```svelte
+<!-- +page.svelte -->
+<script>
+	import { onMount, onDestroy } from 'svelte'
+	import { SignInButton, timeback } from '@timeback/sdk/svelte'
+
+	let activity
+
+	onMount(() => {
+		if ($timeback) {
+			activity = $timeback.activity
+				.new({ id: 'lesson-1', name: 'Intro', course: { subject: 'Math', grade: 3 } })
+				.start()
+		}
+	})
+
+	onDestroy(() => activity?.end())
+</script>
+
+<SignInButton size="lg" />
+```
+
+### Solid
+
+```tsx
+// app.tsx
+import { TimebackProvider } from '@timeback/sdk/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/sdk/solid'
+
+function MyComponent() {
+	const timeback = useTimeback()
+	let activity
+
+	onMount(() => {
+		if (!timeback) return
+
+		activity = timeback.activity
+			.new({ id: 'lesson-1', name: 'Intro', course: { subject: 'Math', grade: 3 } })
+			.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(),
+}
+```
+
+#### TimebackAuthUser Shape
+
+The `user` in `onCallbackSuccess` is a `TimebackAuthUser` with this structure:
+
+```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
+	}
+}
+```
+
+#### Session Storage Guidance
+
+For cookie-only sessions, store only the minimal payload to avoid cookie size limits:
+
+```typescript
+// Recommended: store minimal session
+await setSession({ id: user.id, email: user.email })
+
+// Then in getUser, return what you stored:
+getUser: req => {
+	const session = getSessionFromCookie(req)
+	return session ? { id: session.id, email: session.email } : undefined
+}
+```
+
+For DB-backed sessions, you can store the full `TimebackAuthUser` if desired.
+
+### 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 user with timebackId as the id
+		return { id: session.timebackId, email: session.email, name: session.name }
+	},
+}
+```
+
+## 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
+
+`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.
+
+If you're deploying identity-only SSO on Workers/workerd, import from the worker-safe entrypoint:
+
+```ts
+import { createTimebackIdentity, toNativeHandler } from '@timeback/sdk/edge'
+```
+
+### Server Setup
+
+```typescript
+// lib/timeback.ts
+import { createTimebackIdentity } from '@timeback/sdk'
+
+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('/')
+		},
+		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/sdk/nextjs'
+
+import { timeback } from '@/lib/timeback'
+
+export const { GET, POST } = toNextjsHandler(timeback)
+```
+
+### Express
+
+```typescript
+// server.ts
+import express from 'express'
+import { toExpressMiddleware } from '@timeback/sdk/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.
+
+## User Profile
+
+Use `timeback.user.fetch()` to retrieve the enriched Timeback profile for the
+current user (identity + school/grade + courses + goals + XP):
+
+```typescript
+const profile = await timeback.user.fetch()
+console.log(profile.school?.name)
+console.log(profile.xp?.today, profile.xp?.all)
+```
+
+`profile.xp` has the shape `{ today, all }`, where:
+
+- `today` is computed over the current **UTC day**.
+- `all` is computed over a long-range analytics window (starting `2000-01-01`).
+
+## 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',
+		course: { subject: 'FastMath', grade: 3 },
+	})
+	.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.
+
+**Note:** Activity ingestion requires **exactly one** Caliper sensor URL in `timeback.config.ts`:
+
+```typescript
+export default {
+	name: 'My App',
+	courses: [
+		/* ... */
+	],
+	sensors: ['https://my-app.example.com/sensors/main'],
+}
+```
+
+## 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/sdk'
+
+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() },
+})
+
+// Access the API client via timeback.api
+const { data: users } = await timeback.api.oneroster.users.list()
+```
+
+```typescript
+// Elsewhere in your app
+import { timeback } from './lib/timeback'
+
+// The client is available at timeback.api
+const { data: orgs } = await timeback.api.oneroster.orgs.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/client/adapters/react/SignInButton.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Sign In with Timeback Button
+ *
+ * A pre-styled button for Timeback SSO authentication.
+ * Fully customizable via CSS variables.
+ */
+import * as React from 'react';
+/**
+ * Props for SignInButton component.
+ */
+export interface SignInButtonProps {
+    /** Button text (default: "Sign in with Timeback") */
+    children?: React.ReactNode;
+    /** Additional CSS class names */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Show loading spinner when clicked */
+    showLoading?: boolean;
+    /** Called before redirect (can prevent with e.preventDefault()) */
+    onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+    /** Button variant */
+    variant?: 'default' | 'outline' | 'minimal';
+    /** Button size */
+    size?: 'sm' | 'md' | 'lg';
+    /** Show Timeback logo */
+    showLogo?: boolean;
+}
+/**
+ * Sign In with Timeback button component.
+ *
+ * Triggers SSO authentication flow when clicked.
+ *
+ * @param props - Component props
+ * @returns Button element
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <SignInButton />
+ *
+ * // Custom text
+ * <SignInButton>Continue with Timeback</SignInButton>
+ *
+ * // Outline variant
+ * <SignInButton variant="outline" />
+ *
+ * // Custom styling via CSS variables
+ * <SignInButton
+ *   style={{
+ *     '--tb-btn-bg': '#6366f1',
+ *     '--tb-btn-bg-hover': '#4f46e5',
+ *   } as React.CSSProperties}
+ * />
+ * ```
+ */
+export declare function SignInButton(props: SignInButtonProps): React.ReactElement;
+//# sourceMappingURL=SignInButton.d.ts.map

package/dist/client/adapters/react/SignInButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SignInButton.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/react/SignInButton.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wCAAwC;IACxC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAA;IAC1D,qBAAqB;IACrB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;IAC3C,kBAAkB;IAClB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB;AA8MD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,CAAC,YAAY,CA4DzE"}