feat: Use BetterAuth (#17)

Author: LekoArts

.env.example

@@ -1,5 +1,5 @@
 PRIVATE_TRAKT_CLIENT_ID=
 PRIVATE_TRAKT_CLIENT_SECRET=
-PRIVATE_AUTH_SECRET=
+PRIVATE_BETTER_AUTH_SECRET=
 PRIVATE_TMDB_API_KEY=
-NEXTAUTH_URL=http://localhost:4173
+PUBLIC_BETTER_AUTH_URL=http://localhost:5173

AGENTS.md

@@ -1,221 +1,230 @@
 # Agent Guidelines for Annum
 
-This document provides coding agents with essential information about the Annum codebase structure, conventions, and workflows.
+This document provides essential information for AI coding agents working on this codebase.
 
 ## Project Overview
 
-Annum is a SvelteKit application that visualizes Trakt.tv watch history. It uses:
-- **SvelteKit** (v5) with TypeScript
-- **Vite** for bundling
-- **Vitest** for testing
-- **pnpm** as package manager
-- **Auth.js** (@auth/sveltekit) for authentication
-- **Netlify** for deployment
+Annum is a SvelteKit application that visualizes Trakt.tv watch history. It uses Svelte 5, TypeScript, Better Auth for authentication, and is deployed to Netlify.
 
-## Build, Test & Lint Commands
+## Build & Development Commands
 
+### Development
 ```bash
-# Development
-pnpm dev                 # Start dev server on port 5173
-pnpm build               # Create production build
-pnpm preview             # Preview production build locally
-
-# Type Checking & Linting
-pnpm check               # Run svelte-check for type errors
-pnpm check:watch         # Run svelte-check in watch mode
-pnpm typecheck           # Run TypeScript compiler without emitting files
-pnpm lint                # Run ESLint
-pnpm lint:fix             # Run ESLint with auto-fix
-
-# Testing
-pnpm test                # Run tests in watch mode
-pnpm test:ci             # Run tests once (for CI)
-pnpm test:coverage       # Run tests with coverage report
+pnpm dev                # Start development server
+pnpm preview            # Preview production build locally
+```
+
+### Building
+```bash
+pnpm build              # Create production build
+```
+
+### Code Quality
+```bash
+pnpm check              # Run svelte-check for type checking
+pnpm check:watch        # Run svelte-check in watch mode
+pnpm lint               # Run ESLint
+pnpm lint:fix            # Run ESLint with auto-fix
+pnpm typecheck          # Run TypeScript type checking
+```
+
+### Testing
+```bash
+pnpm test               # Run tests in watch mode
+pnpm test:ci            # Run tests once (CI mode)
+pnpm test:coverage      # Run tests with coverage report
 
 # Run a single test file
-pnpm vitest src/lib/utils/__tests__/index.ts
+pnpm vitest run src/lib/utils/__tests__/index.ts
 
-# Run a single test by name pattern
-pnpm vitest -t "chunks"
+# Run a single test file in watch mode
+pnpm vitest watch src/lib/utils/__tests__/index.ts
 ```
 
+**Test Configuration:**
+- Test files: `src/**/__tests__/*.ts`
+- Coverage includes: `src/lib/utils/*.ts` and `src/lib/actions.ts`
+- Test environment: happy-dom
+- Framework: vitest
+
 ## Code Style Guidelines
 
-### ESLint Configuration
+### General Formatting
 
-The project uses `@antfu/eslint-config` with custom overrides:
+**ESLint Config:** Uses `@antfu/eslint-config` with customizations
 
-- **Indentation**: Tabs (not spaces)
-- **Quotes**: Single quotes (avoid escape when necessary)
-- **Semicolons**: No semicolons
-- **Array Types**: Use generic syntax `Array<T>` not `T[]`
+- **Indentation:** Tabs (not spaces)
+- **Quotes:** Single quotes (use `avoidEscape: true` for strings with single quotes)
+- **Semicolons:** No semicolons
+- **Line breaks:** LF (Unix-style)
 
 ### TypeScript
 
-- **Strict mode enabled**: All strict TypeScript checks are on
-- **No `{}` or `object` types**: Use `Record<string, unknown>` instead
-- **Unused variables**: Prefix with underscore `_` to indicate intentionally unused (e.g., `_variable`, `_arg`)
-- **Type imports**: Use `import type` for type-only imports
-- **No `any`**: Avoid using `any` type; use proper types or `unknown`
-
-### Naming Conventions
+**Strict mode enabled** - All TypeScript strict checks are enforced
 
-- **Files**: Use kebab-case for files (e.g., `user-stats.ts`)
-- **Components**: PascalCase for Svelte components (e.g., `Primary.svelte`)
-- **Functions**: camelCase for functions (e.g., `normalizeItem`)
-- **Constants**: SCREAMING_SNAKE_CASE for top-level constants (e.g., `TRAKT_BASE_URL`)
-- **Types/Interfaces**: PascalCase (e.g., `TraktHistoryItem`)
+**Type Definitions:**
+- Use explicit type annotations for function parameters and return types
+- Prefer `interface` over `type` for object shapes (allows `with-single-extends`)
+- Use `Array<T>` generic syntax instead of `T[]`
+- Never use `{}` or `object` - use `Record<string, unknown>` instead
+- No wrapper object types (`String`, `Number`, etc.)
 
-### Imports
+**Type Imports:**
+- Always use `type` keyword for type-only imports:
+  ```typescript
+  import type { Language, NormalizedItemResponse } from '$lib/types'
+  import type { PageData } from './$types'
+  ```
 
-Order imports by:
-1. Type imports (using `import type`)
-2. External dependencies
-3. Internal modules (using SvelteKit aliases)
+**Unused Variables:**
+- Prefix unused variables with underscore: `_variableName` or just `_`
+- Applies to function args, variables, and caught errors
 
-Example:
+### Naming Conventions
 
-```typescript
-import type { Language, NormalizedItemResponse } from '$lib/types'
-import { page } from '$app/state'
-import { normalizeItem } from '$lib/utils'
-import { signIn } from '@auth/sveltekit/client'
-```
+- **Files:** kebab-case for most files (e.g., `custom-media-queries.css`)
+- **Components:** PascalCase for Svelte components (e.g., `Secondary.svelte`)
+- **Functions:** camelCase (e.g., `normalizeItem`, `filterForYear`)
+- **Constants:** SCREAMING_SNAKE_CASE (e.g., `PAGINATION_LIMIT`, `TRAKT_BASE_URL`)
+- **Types/Interfaces:** PascalCase (e.g., `TraktHistoryItem`, `NormalizedItemResponse`)
 
-### SvelteKit Path Aliases
+### Imports
 
-- `$lib/*` → `src/lib/*`
+**Path Aliases:**
+- `$lib` → `src/lib`
 - `$assets` → `src/assets`
 - `$const` → `src/const.ts`
-- `$app/*` → SvelteKit internals (state, navigation, stores, etc.)
+- Use these aliases consistently instead of relative paths
 
-### Environment Variables
-
-- All private environment variables must use `PRIVATE_` prefix (configured in `svelte.config.js`)
-- Example: `PRIVATE_TRAKT_CLIENT_ID`, `PRIVATE_AUTH_SECRET`
-
-## Function Documentation
-
-All utility functions should include JSDoc comments with:
-- Description of what the function does
-- `@example` tag showing usage
+**Import Order:**
+1. Type imports
+2. External dependencies
+3. Internal modules (using path aliases)
+4. Relative imports
 
 Example:
-
 ```typescript
-/**
- * Split an array into chunks of a given size
- * @example chunks([1, 2, 3, 4, 5], 2) => [[1, 2], [3, 4], [5]]
- */
-export function chunks<T>(array: Array<T>, number: number | string): Array<Array<T>>
+import type { Language, TraktMediaType } from '$lib/types'
+import type { RequestHandler } from './$types'
+import { DEFAULT_CACHE_HEADER, PAGINATION_LIMIT } from '$const'
+import { normalizeItem } from '$lib/utils'
+import { error, json } from '@sveltejs/kit'
 ```
 
-## Error Handling
-
-- Use SvelteKit's `error()` helper for HTTP errors
-- Include helpful error messages with context
-- Log warnings to console for non-critical issues (e.g., missing TMDB IDs)
+### Svelte 5 Conventions
 
-Example:
+**Props:**
 ```typescript
-if (!session?.user)
-	error(401, 'You must sign in to access this route.')
-```
-
-## Testing Patterns
+interface Props {
+	data: PageData
+}
 
-- **Test files**: Located in `__tests__/` directories alongside source files
-- **Fixtures**: Store test data in `__fixtures__/` directories
-- **File pattern**: `src/**/__tests__/*.ts`
-- **Coverage**: Includes `src/lib/utils/*.ts` and `src/lib/actions.ts`
+let { data }: Props = $props()
+```
 
-Test structure:
+**Reactivity:**
+- Use `$state` for reactive variables
+- Use `$derived` for computed values
+- Use `$effect` for side effects
 
+**Store Usage:**
 ```typescript
-import { describe, expect, it } from 'vitest'
-
-describe('functionName', () => {
-	it('should describe expected behavior', () => {
-		const result = functionName(input)
-		expect(result).toBe(expected)
-	})
-})
+import { settings } from '$lib/store/settings'
+
+// Access with $
+$settings.hue
+settings.set({ ...$settings, hue: 240 })
 ```
 
-## Svelte 5 Patterns
+### CSS/Styling
+
+**PostCSS:** Uses `postcss-preset-env` with custom media queries
 
-- Use Svelte 5 runes: `$state`, `$derived`, `$effect`, `$props`
-- Access page store with `page` from `$app/state`
-- Use `<script lang='ts'>` for TypeScript in Svelte files
-- For PostCSS in styles: `<style lang='postcss'>`
+**Custom Media Queries:**
+- `--sm` (min-width: 640px)
+- `--md` (min-width: 768px)
+- `--lg` (min-width: 1024px)
+- `--xl` (min-width: 1350px)
 
-## API Routes
+**Usage:**
+```css
+.element {
+  display: block;
 
-- API routes in `src/routes/api/`
-- Use `RequestHandler` type from `./$types`
-- Set cache headers using `setHeaders()`
-- Return responses with `json()` helper
-- Check authentication with `await locals.auth()`
+  @media (--md) {
+    display: flex;
+  }
+}
+```
 
-Example structure:
+**CSS Variables:** Project uses extensive CSS custom properties defined in `src/styles/variables.css`
 
-```typescript
-export const GET: RequestHandler = async ({ locals, url, fetch, setHeaders }) => {
-	const session = await locals.auth()
-	if (!session?.user)
-		error(401, 'You must sign in to access this route.')
+### Error Handling
 
-	setHeaders({ ...DEFAULT_CACHE_HEADER })
+**Server Routes:**
+```typescript
+// Use SvelteKit's error helper
+if (!user)
+	error(401, 'You must sign in to access this route.')
 
-	// Implementation
-	return json({ data })
+// Try-catch for async operations
+try {
+	const res = await fetch(url)
+	if (!res.ok)
+		throw new Error(`Response not OK: ${res.status}`)
+	// ... handle response
+}
+catch (e) {
+	error(404, `Failed to fetch data. ${e}`)
 }
 ```
 
-## Constants
+**Logging:**
+- Use `console.warn()` for non-fatal issues
+- Include context in log messages (IDs, types, titles)
 
-Define all constants in `src/const.ts` using:
-- `as const` for literal types
-- `satisfies` for type checking without widening
+### Documentation
 
-Example:
+**JSDoc Comments:**
+- Add JSDoc for utility functions
+- Include `@example` usage examples
+- Document parameters and return types
 
+Example:
 ```typescript
-export const TMDB_FETCH_DEFAULTS = {
-	method: 'GET',
-	headers: { 'user-agent': 'annum' },
-} satisfies RequestInit
+/**
+ * Split an array into chunks of a given size
+ * @example chunks([1, 2, 3, 4, 5], 2) => [[1, 2], [3, 4], [5]]
+ */
+export function chunks<T>(array: Array<T>, number: number | string): Array<Array<T>>
 ```
 
-## Common Patterns
+## Environment Variables
 
-### Type Guards
+**Private Variables:** Prefix with `PRIVATE_` (configured in `svelte.config.js`)
+- `PRIVATE_TRAKT_CLIENT_ID`
+- `PRIVATE_TRAKT_CLIENT_SECRET`
+- `PRIVATE_AUTH_SECRET`
+- `PRIVATE_TMDB_API_KEY`
 
+**Public Variables:** Prefix with `PUBLIC_`
+- `PUBLIC_BETTER_AUTH_URL`
+
+## Common Patterns
+
+**Type Guards:**
 ```typescript
 function isTraktWatchedItem(item: TraktHistoryItem | TraktWatchedItem): item is TraktWatchedItem {
 	return !('type' in item)
 }
 ```
 
-### Generic Utility Types
-
-```typescript
-type Filter<T> = MapValuesToKeysIfAllowed<T>[keyof T]
-export function groupBy<T extends Record<PropertyKey, any>, Key extends Filter<T>>(
-	arr: Array<T>,
-	key: Key,
-): Record<T[Key], Array<T>>
-```
-
-## Git & Deployment
-
-- Deployed on Netlify (adapter: `@sveltejs/adapter-netlify`)
-- Redirects configured in `_redirects` file
-- Site manifest: `static/site.webmanifest`
-
-## Additional Notes
+**API Responses:**
+- Set cache headers with `setHeaders()`
+- Return JSON with SvelteKit's `json()` helper
+- Use URL search params for query parameters
 
-- Use `enhancedImages()` from `@sveltejs/enhanced-img` for optimized images
-- Custom media queries defined in `src/styles/custom-media-queries.css`
-- CSS variables in `src/styles/variables.css`
-- Reset styles in `src/styles/reset.css`
+**Authentication:**
+- Uses Better Auth with stateless JWT sessions
+- Check `locals.user` for authenticated user
+- Trakt OAuth for provider authentication