timeback 0.0.0-alpha.2 → 0.1.1

package/README.md

@@ -1,15 +1,386 @@
-# timeback
+# Timeback SDK
 
-To install dependencies:
+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)
+- [Activity Tracking](#activity-tracking)
+
+## Installation
 
 ```bash
-bun install
+npm install timeback
+# or
+bun add timeback
 ```
 
-To run:
+## Quick Start
 
-```bash
-bun run index.ts
+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)
+```
+
+### 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()}
+```
+
+```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 }
+	},
+}
+```
+
+## 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,
+})
 ```
 
-This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+The SDK automatically sends activity data to your server, which forwards it to the Timeback API.

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"}

package/dist/client/adapters/react/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * React Client Module
+ *
+ * React-specific exports for Timeback SDK.
+ *
+ * @example
+ * ```tsx
+ * import { TimebackProvider, useTimeback, SignInButton } from 'timeback/react'
+ *
+ * function App() {
+ *   return (
+ *     <TimebackProvider>
+ *       <MyComponent />
+ *     </TimebackProvider>
+ *   )
+ * }
+ *
+ * function MyComponent() {
+ *   const timeback = useTimeback()
+ *
+ *   const handleSignIn = () => timeback?.auth.signIn()
+ *
+ *   const handleFetchProfile = async () => {
+ *     const profile = await timeback?.user.fetch()
+ *   }
+ *
+ *   const handleStartActivity = () => {
+ *     const activity = timeback?.activity.new({ id: 'lesson-1', name: 'Intro', courseCode: 'MATH' })
+ *     activity?.start()
+ *   }
+ *
+ *   return <SignInButton />
+ * }
+ * ```
+ */
+export { createClient } from '../../timeback-client';
+export { TimebackClient } from '../../timeback-client.class';
+export { Activity } from '../../lib/activity';
+export { TimebackProvider, useTimeback } from './provider';
+export { SignInButton } from './SignInButton';
+export type { SignInButtonProps } from './SignInButton';
+export type { TimebackUser, ActivityParams, ActivityMetrics } from '../../../shared/types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAG7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAGvD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}