timeback 0.0.0-alpha.2 → 0.1.0

package/README.md

@@ -1,15 +1,219 @@
-# timeback
+# Timeback SDK
 
-To install dependencies:
+TypeScript SDK for integrating with Timeback, providing both server-side BFF logic and client-side React components.
+
+## Installation
 
 ```bash
-bun install
+npm install timeback
+# or
+bun add timeback
 ```
 
-To run:
+## Server-Side Setup
 
-```bash
-bun run index.ts
+The server SDK auto-discovers your `timeback.config.ts` file and provides route handlers for Next.js.
+
+### Configuration
+
+```typescript
+// app/lib/timeback.ts
+import { createTimeback } from 'timeback'
+
+export const timeback = await createTimeback({
+	env: 'production', // 'development' | 'staging' | 'production'
+
+	// API credentials for Timeback API calls
+	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,
+			}
+		},
+	},
+})
+```
+
+### Next.js Route Handlers
+
+```typescript
+// app/api/timeback/[...timeback]/route.ts
+import { timeback } from '@/lib/timeback'
+
+export const { GET, POST } = timeback.handlers()
+```
+
+This exposes:
+
+- `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)
+
+## Client-Side Setup
+
+### Configuration
+
+```typescript
+// app/lib/timeback-client.ts
+import { createTimebackClient } from 'timeback/client/react'
+
+// Zero config - baseURL defaults to window.location.origin + '/api/timeback'
+export const timebackClient = createTimebackClient()
+
+// Or with explicit URL
+export const timebackClient = createTimebackClient({
+	baseURL: 'https://myapp.com/api/timeback',
+})
 ```
 
-This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### React Provider
+
+```tsx
+// app/providers.tsx
+import { TimebackProvider } from 'timeback/client/react'
+
+import { timebackClient } from '@/lib/timeback-client'
+
+export function Providers({ children }) {
+	return <TimebackProvider client={timebackClient}>{children}</TimebackProvider>
+}
+```
+
+### Hooks
+
+```tsx
+import { useActivity, useTimeback } from 'timeback/client/react'
+
+function UserMenu() {
+	const { user, isLoading, identityMode, signIn, signOut } = useTimeback()
+
+	if (isLoading) return <Spinner />
+
+	if (!user) {
+		return <button onClick={signIn}>Sign In</button>
+	}
+
+	return (
+		<div>
+			<span>{user.name}</span>
+			<button onClick={signOut}>Sign Out</button>
+		</div>
+	)
+}
+```
+
+### Activity Tracking
+
+#### React Hook
+
+```tsx
+function LessonPlayer({ lessonId, courseCode }) {
+	// Starts on mount, ends on unmount, restarts if deps change
+	const activity = useActivity({
+		type: 'lesson',
+		objectId: lessonId,
+		courseCode,
+	})
+
+	return (
+		<>
+			<button onClick={() => activity.pause()}>Pause</button>
+			<button onClick={() => activity.resume()}>Resume</button>
+			<span>Time: {activity.elapsedMs}ms</span>
+		</>
+	)
+}
+```
+
+#### Vanilla API
+
+```typescript
+import { createTimebackClient } from 'timeback/client'
+
+const client = createTimebackClient()
+
+// Start tracking
+const activity = client.startActivity({
+	type: 'lesson',
+	objectId: 'lesson-123',
+	courseCode: 'FASTMATH-1',
+})
+
+// Pause/resume as needed
+activity.pause()
+activity.resume()
+
+// End tracking - sends ActivityCompletedEvent + TimeSpentEvent to server
+await activity.end()
+```
+
+## Identity Modes
+
+### Timeback SSO
+
+Uses Timeback as the identity provider via OIDC. Users sign in through Timeback's authentication flow.
+
+```typescript
+identity: {
+  mode: 'sso',
+  clientId: process.env.TIMEBACK_SSO_CLIENT_ID!,
+  clientSecret: process.env.TIMEBACK_SSO_CLIENT_SECRET!,
+}
+```
+
+### Custom Identity
+
+For apps with existing authentication (Clerk, Auth0, Supabase, etc.), provide a `getUser` function that returns the current user.
+
+```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,
+    }
+  },
+}
+```
+
+## API Reference
+
+### Server
+
+- `createTimeback(config)` - Create a Timeback server instance
+- `timeback.handlers()` - Get Next.js route handlers
+
+### Client
+
+- `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
+
+### React
+
+- `TimebackProvider` - Context provider
+- `useTimeback()` - Hook for identity state and actions
+- `useActivity(params)` - Hook for activity tracking with lifecycle management

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