@krutai/auth 0.1.2 → 0.1.4

package/AI_REFERENCE.md

@@ -1,33 +1,53 @@
-# @krutai/auth - AI Assistant Reference Guide
+# @krutai/auth — AI Assistant Reference Guide
 
 ## Package Overview
 
-`@krutai/auth` is an authentication package for KrutAI that wraps Better Auth with mandatory API key validation. This package requires users to provide a valid API key to access authentication features.
+- **Name**: `@krutai/auth`
+- **Version**: `0.1.4`
+- **Purpose**: Authentication package for KrutAI — wraps Better Auth with mandatory API key validation
+- **Entry**: `src/index.ts` → `dist/index.{js,mjs,d.ts}`
+- **Build**: `tsup` (CJS + ESM, `better-auth` bundled, `krutai` external peer dep)
 
-## Installation
+## Dependency Architecture
 
-```bash
-npm install @krutai/auth
 ```
+@krutai/auth@0.1.4
+├── peerDependency: krutai >=0.1.2   ← auto-installed, provides API validation
+├── dependency:    better-sqlite3    ← auto-installed
+└── bundled:       better-auth       ← included in dist (noExternal)
+```
+
+> **Important for AI**: The validator (`validateApiKeyFormat`, `ApiKeyValidationError`, etc.) is NOT defined in this package. It is imported from `krutai` and re-exported. Do NOT add a local `validator.ts` here.
 
-## Core Concepts
+## File Structure
+
+```
+packages/auth/
+├── src/
+│   ├── index.ts     # Barrel export — re-exports from krutai for validator
+│   ├── client.ts    # KrutAuth class
+│   ├── types.ts     # KrutAuthConfig, AuthSession, BetterAuthOptions
+│   ├── react.ts     # createAuthClient (better-auth/react)
+│   └── next-js.ts   # toNextJsHandler (better-auth/next-js)
+├── package.json
+├── tsconfig.json
+└── tsup.config.ts
+```
 
-### API Key Requirement
-- **MANDATORY**: All users must provide a valid API key
-- API key is validated on initialization (can be disabled with `validateOnInit: false`)
-- Throws `ApiKeyValidationError` if API key is missing or invalid
+## Sub-path Exports
 
-### Better Auth Integration
-- Wraps the Better Auth library
-- Provides access to full Better Auth API via `getBetterAuth()`
-- See Better Auth docs: https://www.better-auth.com/docs
+| Import | File | Purpose |
+|---|---|---|
+| `@krutai/auth` | `dist/index.js` | Server-side: `betterAuth`, `KrutAuth`, validator re-exports |
+| `@krutai/auth/react` | `dist/react.js` | Client-side: `createAuthClient`, hooks |
+| `@krutai/auth/next-js` | `dist/next-js.js` | Next.js handler: `toNextJsHandler` |
 
 ## Main Exports
 
 ### Classes
 
 #### `KrutAuth`
-Main authentication client class.
+Main authentication client.
 
 **Constructor:**
 ```typescript
@@ -35,13 +55,11 @@ new KrutAuth(config: KrutAuthConfig)
 ```
 
 **Methods:**
-- `initialize(): Promise<void>` - Validates API key and initializes Better Auth
-- `getBetterAuth(): ReturnType<typeof betterAuth>` - Returns Better Auth instance
-- `isInitialized(): boolean` - Check if initialized
-- `getApiKey(): string` - Get the API key
-- `signIn()` - Convenience method (returns Better Auth instance)
-- `signOut()` - Convenience method (returns Better Auth instance)
-- `getSession()` - Convenience method (returns Better Auth instance)
+- `initialize(): Promise<void>` — validates API key + initializes Better Auth
+- `getBetterAuth()` — returns the Better Auth instance
+- `isInitialized(): boolean`
+- `getApiKey(): string`
+- `signIn()`, `signOut()`, `getSession()` — convenience wrappers
 
 ### Types
 
@@ -58,185 +76,115 @@ interface KrutAuthConfig {
 #### `AuthSession`
 ```typescript
 interface AuthSession {
-  user: {
-    id: string;
-    email: string;
-    name?: string;
-    [key: string]: unknown;
-  };
-  session: {
-    id: string;
-    expiresAt: Date;
-    [key: string]: unknown;
-  };
+  user: { id: string; email: string; name?: string; [key: string]: unknown };
+  session: { id: string; expiresAt: Date; [key: string]: unknown };
 }
 ```
 
-### Errors
+### Validator Re-exports (from `krutai`)
 
-#### `ApiKeyValidationError`
-Thrown when API key validation fails.
+```typescript
+// These are re-exported from krutai — NOT defined here
+export { validateApiKeyFormat, validateApiKeyWithService, createApiKeyChecker, ApiKeyValidationError } from 'krutai';
+```
 
-**Common causes:**
-- API key is missing or empty
-- API key is too short (< 10 characters)
-- API key validation fails against backend
+### Other Re-exports
+
+```typescript
+export { betterAuth } from 'better-auth';
+```
 
 ## Usage Examples
 
-### Example 1: Basic Usage with Async Validation
+### Example 1: Basic Server Setup
+```typescript
+import { betterAuth } from '@krutai/auth';
 
+export const auth = betterAuth({
+  database: { /* config */ },
+});
+```
+
+### Example 2: KrutAuth with API Key
 ```typescript
 import { KrutAuth } from '@krutai/auth';
 
 const auth = new KrutAuth({
-  apiKey: 'your-api-key-here',
+  apiKey: process.env.KRUTAI_API_KEY!,
   betterAuthOptions: {
-    database: {
-      // your database config
-    }
-  }
+    database: { provider: 'postgres', url: process.env.DATABASE_URL },
+    emailAndPassword: { enabled: true },
+  },
 });
 
-// Initialize and validate API key
 await auth.initialize();
-
-// Get Better Auth instance
 const betterAuth = auth.getBetterAuth();
 ```
 
-### Example 2: Skip Async Validation
-
+### Example 3: Skip Async Validation
 ```typescript
-import { KrutAuth } from '@krutai/auth';
-
 const auth = new KrutAuth({
-  apiKey: 'your-api-key-here',
+  apiKey: process.env.KRUTAI_API_KEY!,
   validateOnInit: false,
-  betterAuthOptions: {
-    // config
-  }
+  betterAuthOptions: { /* config */ },
 });
-
 // No need to call initialize()
 const betterAuth = auth.getBetterAuth();
 ```
 
-### Example 3: Error Handling
-
+### Example 4: Error Handling
 ```typescript
 import { KrutAuth, ApiKeyValidationError } from '@krutai/auth';
 
 try {
-  const auth = new KrutAuth({
-    apiKey: 'invalid-key'
-  });
+  const auth = new KrutAuth({ apiKey: 'bad' });
   await auth.initialize();
-} catch (error) {
-  if (error instanceof ApiKeyValidationError) {
-    console.error('API key validation failed:', error.message);
+} catch (e) {
+  if (e instanceof ApiKeyValidationError) {
+    console.error('Invalid API key:', e.message);
   }
 }
 ```
 
-### Example 4: Using Better Auth Features
-
+### Example 5: Next.js Route Handler
 ```typescript
-import { KrutAuth } from '@krutai/auth';
-
-const auth = new KrutAuth({
-  apiKey: process.env.KRUTAI_API_KEY!,
-  betterAuthOptions: {
-    database: {
-      provider: 'postgres',
-      url: process.env.DATABASE_URL
-    },
-    emailAndPassword: {
-      enabled: true
-    }
-  }
-});
-
-await auth.initialize();
-
-// Access full Better Auth API
-const betterAuth = auth.getBetterAuth();
+// app/api/auth/[...all]/route.ts
+import { auth } from '@/lib/auth';
+import { toNextJsHandler } from '@krutai/auth/next-js';
 
-// Use Better Auth methods directly
-// See: https://www.better-auth.com/docs
-```
-
-## Common Patterns
-
-### Pattern 1: Environment Variable API Key
-
-```typescript
-const auth = new KrutAuth({
-  apiKey: process.env.KRUTAI_API_KEY || '',
-  betterAuthOptions: {
-    // config
-  }
-});
+export const { GET, POST } = toNextJsHandler(auth);
 ```
 
-### Pattern 2: Singleton Instance
-
+### Example 6: React Client
 ```typescript
-// auth.ts
-let authInstance: KrutAuth | null = null;
-
-export async function getAuth(): Promise<KrutAuth> {
-  if (!authInstance) {
-    authInstance = new KrutAuth({
-      apiKey: process.env.KRUTAI_API_KEY!,
-      betterAuthOptions: {
-        // config
-      }
-    });
-    await authInstance.initialize();
-  }
-  return authInstance;
-}
-```
-
-### Pattern 3: Conditional Initialization
+import { createAuthClient } from '@krutai/auth/react';
 
-```typescript
-const auth = new KrutAuth({
-  apiKey: process.env.KRUTAI_API_KEY!,
-  validateOnInit: process.env.NODE_ENV === 'production'
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL ?? 'http://localhost:3000',
 });
-
-if (process.env.NODE_ENV === 'production') {
-  await auth.initialize();
-}
+export const { signIn, signUp, signOut, useSession } = authClient;
 ```
 
-## TypeScript Support
+## tsup Configuration Notes
 
-Full TypeScript support with exported types:
-
-```typescript
-import type { 
-  KrutAuthConfig, 
-  AuthSession, 
-  BetterAuthOptions 
-} from '@krutai/auth';
-```
+- `better-auth` → `noExternal` (bundled into dist)
+- `krutai` → external (peer dep, NOT bundled)
+- `react`, `react-dom`, `next`, `better-sqlite3` → external
 
 ## Important Notes
 
-1. **API Key is Required**: The package will not work without a valid API key
-2. **Better Auth Wrapper**: This is a wrapper around Better Auth, not a replacement
-3. **Validation**: By default, API key is validated on `initialize()` call
-4. **Error Handling**: Always catch `ApiKeyValidationError` for proper error handling
+1. **Validator lives in `krutai`**: Never add a local `validator.ts` — import from `krutai`
+2. **`krutai` must be external in tsup**: Do NOT add it to `noExternal`
+3. **`krutai` in devDependencies**: Needed for local TypeScript compilation during development
+4. **API key validation**: Format check is synchronous (constructor), service check is async (`initialize()`)
 
 ## Related Packages
 
-- `krutai` - Main KrutAI package with core utilities
-- Future packages: `@krutai/analytics`, `@krutai/roles`, `@krutai/llm`
+- `krutai` — Core utilities and API validation (peer dep)
+- `@krutai/rbac` — Role-Based Access Control
 
 ## Links
 
-- Better Auth Documentation: https://www.better-auth.com/docs
-- GitHub Repository: https://github.com/yourusername/krut_packages
+- Better Auth Docs: https://www.better-auth.com/docs
+- GitHub: https://github.com/AccountantAIOrg/krut_packages
+- npm: https://www.npmjs.com/package/@krutai/auth

package/README.md

@@ -1,14 +1,15 @@
 # @krutai/auth
 
-Authentication package for KrutAI powered by [Krut AI](https://www.krut.ai/).
+Authentication package for KrutAI powered by [Better Auth](https://www.better-auth.com/).
 
 ## Features
 
-- 🔐 **API Key Protection** - Requires valid API key for access
-- 🚀 **Better Auth Integration** - Built on top of Better Auth
-- 📦 **TypeScript First** - Full type safety and IntelliSense support
-- 🎯 **Simple API** - Easy to use authentication client
-- ⚡ **Dual Format** - Supports both ESM and CommonJS
+- 🔐 **API Key Protection** — Requires a valid KrutAI API key (validated via `krutai`)
+- 🚀 **Better Auth Integration** — Built on top of Better Auth
+- 📦 **Auto-installs `krutai`** — The core `krutai` package is installed automatically as a peer dependency
+- 🎯 **Next.js Ready** — First-class support via `@krutai/auth/next-js`
+- ⚡ **Dual Format** — Supports both ESM and CommonJS
+- 🔷 **TypeScript First** — Full type safety and IntelliSense
 
 ## Installation
 
@@ -16,190 +17,119 @@ Authentication package for KrutAI powered by [Krut AI](https://www.krut.ai/).
 npm install @krutai/auth
 ```
 
-> **Note:** Installing `@krutai/auth` automatically installs the parent `krutai` package, which provides centralized API key validation for all KrutAI packages.
+> **Note:** `krutai` is automatically installed as a peer dependency. `better-sqlite3` is included as a dependency and `better-auth` is bundled — no additional packages required.
 
 ## Quick Start
 
-### Basic Usage
+### Server-side setup (Next.js)
 
 ```typescript
-import { KrutAuth } from '@krutai/auth';
+// lib/auth.ts
+import { betterAuth } from "@krutai/auth";
 
-// Initialize with your API key
-const auth = new KrutAuth({
-  apiKey: 'your-krutai-api-key',
-  betterAuthOptions: {
-    // Better Auth configuration
-    database: {
-      // Your database configuration
-    },
+export const auth = betterAuth({
+  database: {
+    // your database config
   },
 });
-
-// Initialize the client (validates API key)
-await auth.initialize();
-
-// Use authentication features
-const session = await auth.getSession();
 ```
 
-### Without Async Initialization
-
-If you want to skip async validation on initialization:
+### API Route handler
 
 ```typescript
-const auth = new KrutAuth({
-  apiKey: 'your-krutai-api-key',
-  validateOnInit: false,
-  betterAuthOptions: {
-    // Better Auth configuration
-  },
-});
-
-// No need to call initialize()
-const betterAuth = auth.getBetterAuth();
-```
-
-## API Reference
-
-### `KrutAuth`
+// app/api/auth/[...all]/route.ts
+import { auth } from "@/lib/auth";
+import { toNextJsHandler } from "@krutai/auth/next-js";
 
-Main authentication client class.
-
-#### Constructor
-
-```typescript
-new KrutAuth(config: KrutAuthConfig)
+export const { GET, POST } = toNextJsHandler(auth);
 ```
 
-**Parameters:**
-
-- `config.apiKey` (required): Your KrutAI API key
-- `config.betterAuthOptions` (optional): Better Auth configuration options
-- `config.validateOnInit` (optional): Whether to validate API key on initialization (default: `true`)
-- `config.validationEndpoint` (optional): Custom API validation endpoint
-
-**Throws:**
-
-- `ApiKeyValidationError` if the API key format is invalid
-
-#### Methods
-
-##### `initialize()`
-
-Validates the API key and initializes the Better Auth instance.
+### Client-side (React / Next.js)
 
 ```typescript
-await auth.initialize();
-```
+// lib/auth-client.ts
+import { createAuthClient } from "@krutai/auth/react";
 
-**Returns:** `Promise<void>`
-
-**Throws:** `ApiKeyValidationError` if validation fails
-
-##### `getBetterAuth()`
-
-Gets the underlying Better Auth instance for advanced usage.
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000",
+});
 
-```typescript
-const betterAuth = auth.getBetterAuth();
+export const { signIn, signUp, signOut, useSession } = authClient;
 ```
 
-**Returns:** `BetterAuth`
-
-**Throws:** `Error` if not initialized
-
-##### `isInitialized()`
-
-Checks if the client is initialized.
+### With API Key Validation
 
 ```typescript
-const ready = auth.isInitialized();
-```
-
-**Returns:** `boolean`
+import { KrutAuth } from "@krutai/auth";
 
-##### `getApiKey()`
-
-Gets the API key (useful for making authenticated requests).
+const auth = new KrutAuth({
+  apiKey: "your-krutai-api-key",
+  betterAuthOptions: {
+    database: { /* your database config */ },
+  },
+});
 
-```typescript
-const apiKey = auth.getApiKey();
+await auth.initialize();
 ```
 
-**Returns:** `string`
+## Exports
 
-## Architecture
+| Import path | What it provides |
+|---|---|
+| `@krutai/auth` | `betterAuth`, `KrutAuth`, validator re-exports from `krutai` |
+| `@krutai/auth/react` | `createAuthClient`, `useSession`, etc. |
+| `@krutai/auth/next-js` | `toNextJsHandler` |
 
-### Dependency on Parent Package
+## API Reference
 
-`@krutai/auth` depends on the parent `krutai` package for API key validation:
+### `KrutAuth`
 
-```
-@krutai/auth
-└── krutai (parent)
-    └── Provides: validateApiKeyFormat, validateApiKeyWithService, etc.
-```
+#### Constructor options
 
-**Benefits:**
-- ✅ All `@krutai/*` packages use the same validation logic from `krutai`
-- ✅ No code duplication across packages
-- ✅ Consistent API key handling
-- ✅ Centralized validation updates benefit all packages
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | ✅ | Your KrutAI API key |
+| `betterAuthOptions` | `object` | — | Better Auth configuration |
+| `validateOnInit` | `boolean` | — | Validate API key on init (default: `true`) |
+| `validationEndpoint` | `string` | — | Custom validation endpoint |
 
-You can also use the validation utilities directly:
+#### Methods
 
-```typescript
-import { validateApiKeyFormat, ApiKeyValidationError } from '@krutai/auth';
-// or
-import { validateApiKeyFormat, ApiKeyValidationError } from 'krutai';
-```
+- `initialize()` — Validates API key and sets up Better Auth
+- `getBetterAuth()` — Returns the underlying Better Auth instance
+- `isInitialized()` — Returns `boolean`
+- `getApiKey()` — Returns the API key string
 
 ## Error Handling
 
-The package throws `ApiKeyValidationError` (from parent `krutai` package) when:
-
-- API key is not provided
-- API key is empty or invalid format
-- API key validation fails (if `validateOnInit` is `true`)
-
 ```typescript
-import { KrutAuth, ApiKeyValidationError } from '@krutai/auth';
+import { KrutAuth, ApiKeyValidationError } from "@krutai/auth";
 
 try {
-  const auth = new KrutAuth({
-    apiKey: 'invalid-key',
-  });
+  const auth = new KrutAuth({ apiKey: "invalid" });
   await auth.initialize();
 } catch (error) {
   if (error instanceof ApiKeyValidationError) {
-    console.error('API key validation failed:', error.message);
+    console.error("API key validation failed:", error.message);
   }
 }
 ```
 
-## Better Auth Integration
+> `ApiKeyValidationError` is re-exported from `krutai` — the single source of truth for API validation across the KrutAI ecosystem.
 
-This package wraps [Better Auth](https://www.better-auth.com/) and adds API key validation. You can access the full Better Auth API through the `getBetterAuth()` method:
+## Architecture
 
-```typescript
-const auth = new KrutAuth({ apiKey: 'your-key' });
-await auth.initialize();
+`@krutai/auth` depends on `krutai` (auto-installed as a peer dependency) for API key validation. `better-auth` is bundled into the output and `better-sqlite3` is auto-installed as a dependency.
 
-const betterAuth = auth.getBetterAuth();
-// Use Better Auth features directly
+```
+@krutai/auth@0.1.4
+├── peerDependency: krutai >=0.1.2   (auto-installed)
+├── dependency:    better-sqlite3
+└── bundled:       better-auth
 ```
 
 For Better Auth documentation, visit: https://www.better-auth.com/docs
 
-## TypeScript Support
-
-Full TypeScript support with exported types:
-
-```typescript
-import type { KrutAuthConfig, AuthSession, BetterAuthOptions } from '@krutai/auth';
-```
-
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import * as better_auth from 'better-auth';
 import { BetterAuthOptions, betterAuth } from 'better-auth';
 export { BetterAuthOptions, betterAuth } from 'better-auth';
+export { ApiKeyValidationError, createApiKeyChecker, validateApiKeyFormat, validateApiKeyWithService } from 'krutai';
 
 /**
  * Configuration options for KrutAuth
@@ -121,50 +122,10 @@ declare class KrutAuth {
     getSession(): Promise<better_auth.Auth<better_auth.BetterAuthOptions>>;
 }
 
-/**
- * API Key Validation Module
- *
- * Centralized API key validation for @krutai/auth.
- * This is bundled directly into @krutai/auth so no separate `krutai` package install is needed.
- */
-/**
- * Custom error for API key validation failures
- */
-declare class ApiKeyValidationError extends Error {
-    constructor(message: string);
-}
-/**
- * Validates the format of an API key
- * @param apiKey - The API key to validate
- * @throws {ApiKeyValidationError} If the API key format is invalid
- */
-declare function validateApiKeyFormat(apiKey: string): void;
-/**
- * Validates an API key with the KrutAI service
- * @param apiKey - The API key to validate
- * @returns Promise that resolves to true if valid, false otherwise
- */
-declare function validateApiKeyWithService(apiKey: string): Promise<boolean>;
-/**
- * Creates a validated API key checker function
- * @param apiKey - The API key to validate
- * @returns A function that checks if the API key is valid
- */
-declare function createApiKeyChecker(apiKey: string): {
-    /**
-     * Validates the API key (cached after first call)
-     */
-    validate(): Promise<boolean>;
-    /**
-     * Resets the validation cache
-     */
-    reset(): void;
-};
-
 /**
  * @krutai/auth - Authentication package for KrutAI
  *
- * Everything is bundled — no need to separately install `krutai` or `better-auth`.
+ * Requires `krutai` as a peer dependency (installed automatically).
  *
  * @example Server-side (Next.js API route / server component)
  * ```typescript
@@ -189,4 +150,4 @@ declare function createApiKeyChecker(apiKey: string): {
 
 declare const VERSION = "0.1.2";
 
-export { ApiKeyValidationError, type AuthSession, KrutAuth, type KrutAuthConfig, VERSION, createApiKeyChecker, validateApiKeyFormat, validateApiKeyWithService };
+export { type AuthSession, KrutAuth, type KrutAuthConfig, VERSION };