@krutai/auth 0.1.1 → 0.1.3

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
+- 🚀 **Better Auth Integration** — Built on top of Better Auth
+- 📦 **Self-Contained** — No extra installs needed; `better-auth` and `better-sqlite3` are included automatically
+- 🎯 **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,110 @@ 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:** Installing `@krutai/auth` automatically installs `better-sqlite3` (the default database adapter) and bundles `better-auth` — 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
-  },
-});
+// app/api/auth/[...all]/route.ts
+import { auth } from "@/lib/auth";
+import { toNextJsHandler } from "@krutai/auth/next-js";
 
-// No need to call initialize()
-const betterAuth = auth.getBetterAuth();
+export const { GET, POST } = toNextJsHandler(auth);
 ```
 
-## API Reference
-
-### `KrutAuth`
-
-Main authentication client class.
-
-#### Constructor
+### Client-side (React / Next.js)
 
 ```typescript
-new KrutAuth(config: KrutAuthConfig)
-```
-
-**Parameters:**
+// lib/auth-client.ts
+import { createAuthClient } from "@krutai/auth/react";
 
-- `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.
-
-```typescript
-await auth.initialize();
-```
-
-**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`, validators |
+| `@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
-
-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:
-
-```typescript
-const auth = new KrutAuth({ apiKey: 'your-key' });
-await auth.initialize();
+## Architecture
 
-const betterAuth = auth.getBetterAuth();
-// Use Better Auth features directly
-```
+`@krutai/auth` is fully self-contained — `better-auth` is bundled into the output and `better-sqlite3` is auto-installed as a dependency. Each `@krutai/*` sub-library independently includes its own API key validation, so you never need to install the parent `krutai` package separately.
 
 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,7 +1,6 @@
 import * as better_auth from 'better-auth';
 import { BetterAuthOptions, betterAuth } from 'better-auth';
-export { BetterAuthOptions } from 'better-auth';
-export { ApiKeyValidationError, createApiKeyChecker, validateApiKeyFormat, validateApiKeyWithService } from 'krutai';
+export { BetterAuthOptions, betterAuth } from 'better-auth';
 
 /**
  * Configuration options for KrutAuth
@@ -122,15 +121,72 @@ 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
  *
- * This package provides authentication functionality powered by Better Auth
- * with API key validation to ensure secure access.
+ * Everything is bundled — no need to separately install `krutai` or `better-auth`.
+ *
+ * @example Server-side (Next.js API route / server component)
+ * ```typescript
+ * import { betterAuth } from "@krutai/auth";
+ *
+ * export const auth = betterAuth({ ... });
+ * ```
+ *
+ * @example Client-side (React / Next.js client component)
+ * ```typescript
+ * import { createAuthClient } from "@krutai/auth/react";
+ *
+ * export const authClient = createAuthClient({
+ *   baseURL: process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000",
+ * });
+ *
+ * export const { signIn, signUp, signOut, useSession } = authClient;
+ * ```
  *
  * @packageDocumentation
  */
 
-declare const VERSION = "0.1.1";
+declare const VERSION = "0.1.2";
 
-export { type AuthSession, KrutAuth, type KrutAuthConfig, VERSION };
+export { ApiKeyValidationError, type AuthSession, KrutAuth, type KrutAuthConfig, VERSION, createApiKeyChecker, validateApiKeyFormat, validateApiKeyWithService };

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import * as better_auth from 'better-auth';
 import { BetterAuthOptions, betterAuth } from 'better-auth';
-export { BetterAuthOptions } from 'better-auth';
-export { ApiKeyValidationError, createApiKeyChecker, validateApiKeyFormat, validateApiKeyWithService } from 'krutai';
+export { BetterAuthOptions, betterAuth } from 'better-auth';
 
 /**
  * Configuration options for KrutAuth
@@ -122,15 +121,72 @@ 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
  *
- * This package provides authentication functionality powered by Better Auth
- * with API key validation to ensure secure access.
+ * Everything is bundled — no need to separately install `krutai` or `better-auth`.
+ *
+ * @example Server-side (Next.js API route / server component)
+ * ```typescript
+ * import { betterAuth } from "@krutai/auth";
+ *
+ * export const auth = betterAuth({ ... });
+ * ```
+ *
+ * @example Client-side (React / Next.js client component)
+ * ```typescript
+ * import { createAuthClient } from "@krutai/auth/react";
+ *
+ * export const authClient = createAuthClient({
+ *   baseURL: process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000",
+ * });
+ *
+ * export const { signIn, signUp, signOut, useSession } = authClient;
+ * ```
  *
  * @packageDocumentation
  */
 
-declare const VERSION = "0.1.1";
+declare const VERSION = "0.1.2";
 
-export { type AuthSession, KrutAuth, type KrutAuthConfig, VERSION };
+export { ApiKeyValidationError, type AuthSession, KrutAuth, type KrutAuthConfig, VERSION, createApiKeyChecker, validateApiKeyFormat, validateApiKeyWithService };