@krutai/auth 0.2.3 → 0.4.2

package/README.md

@@ -1,16 +1,17 @@
 # @krutai/auth
 
-Authentication package for KrutAI powered by [Better Auth](https://www.better-auth.com/).
+Authentication package for KrutAI — a fetch-based HTTP client that calls your server's `/lib-auth` routes (powered by [Better Auth](https://www.better-auth.com/) on the server side).
+
+> **Architecture Note:** This package is a **pure HTTP client** — it has no local database or Better Auth dependency. All auth logic (including database connections) lives on your server. This package simply makes authenticated HTTP calls to your server's auth routes.
 
 ## Features
 
 - 🔐 **API Key Protection** — Requires a valid KrutAI API key (validated via `krutai`)
-- 🚀 **Better Auth Integration** — Built on top of Better Auth
-- 📦 **Auto-installs everything** — `krutai`, `better-auth`, `better-sqlite3` install automatically
-- 🗄️ **Auto-migrates SQLite** — Database tables are created automatically on install
-- 🎯 **Next.js Ready** — First-class support via `@krutai/auth/next-js`
+- 🚀 **Better Auth Integration** — Calls your server's Better Auth routes
+- 🐘 **PostgreSQL Ready** — Your server can use any Better Auth-supported database (PostgreSQL, MySQL, etc.)
 - ⚡ **Dual Format** — Supports both ESM and CommonJS
 - 🔷 **TypeScript First** — Full type safety and IntelliSense
+- 🌐 **Zero DB Dependencies** — No local database driver needed
 
 ## Installation
 
@@ -18,135 +19,214 @@ Authentication package for KrutAI powered by [Better Auth](https://www.better-au
 npm install @krutai/auth
 ```
 
-> **Note:** `krutai`, `better-auth`, `better-sqlite3`, and `@types/better-sqlite3` are all installed automatically. SQLite tables are migrated automatically after install.
+## How It Works
+
+```
+Your App
+  └── @krutai/auth (HTTP client)
+        └── POST /lib-auth/api/auth/sign-up/email  ──► Your Server
+                                                          └── better-auth
+                                                                └── PostgreSQL
+```
+
+All database operations (user storage, session management, etc.) happen on your server. This package is just a thin, type-safe HTTP wrapper.
 
 ## Quick Start
 
-### Server-side setup (Next.js)
+### 1. Server-side setup (PostgreSQL + Better Auth)
 
-```typescript
-// lib/auth.ts
-import { krutAuth } from "@krutai/auth";
-import Database from "better-sqlite3";
+Set up Better Auth on your server with a PostgreSQL database:
 
-export const auth = krutAuth({
-  database: new Database("./sqlite.db"),
+```typescript
+// server: lib/auth.ts
+import { betterAuth } from "better-auth";
+import { Pool } from "pg";
+
+export const auth = betterAuth({
+  database: new Pool({
+    connectionString: process.env.DATABASE_URL,
+    // e.g. postgresql://user:password@localhost:5432/mydb
+  }),
   emailAndPassword: {
     enabled: true,
   },
-  baseURL: process.env.BETTER_AUTH_BASE_URL ?? "http://localhost:3000",
+  basePath: "/lib-auth",
+  baseURL: process.env.BETTER_AUTH_BASE_URL ?? "http://localhost:8000",
+  secret: process.env.BETTER_AUTH_SECRET,
 });
 ```
 
-> **Required:** Set `BETTER_AUTH_BASE_URL` in your `.env` file (e.g. `http://localhost:3000` for dev, `https://yourdomain.com` for production). Without this, redirects and callbacks will not work.
+> **Required env vars on your server:**
+> - `DATABASE_URL` — PostgreSQL connection string
+> - `BETTER_AUTH_BASE_URL` — Your server's base URL (e.g. `http://localhost:8000`)
+> - `BETTER_AUTH_SECRET` — Secret for signing sessions
 
-### API Route handler
+### 2. Mount the auth handler on your server
 
 ```typescript
-// app/api/auth/[...all]/route.ts
-import { auth } from "@/lib/auth";
-import { toNextJsHandler } from "@krutai/auth/next-js";
+// server: routes/auth.ts (Express example)
+import { toNodeHandler } from "better-auth/node";
+import { auth } from "./lib/auth";
 
-export const { GET, POST } = toNextJsHandler(auth);
+app.use("/lib-auth", toNodeHandler(auth));
 ```
 
-### Client-side (React / Next.js)
+### 3. Use `@krutai/auth` in your client/consumer app
 
 ```typescript
-// lib/auth-client.ts
-import { createAuthClient } from "@krutai/auth/react";
+import { krutAuth } from "@krutai/auth";
 
-export const authClient = createAuthClient({
-  baseURL: process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000",
+const auth = krutAuth({
+  apiKey: process.env.KRUTAI_API_KEY!,
+  serverUrl: "https://your-server.com", // points to the server above
 });
 
-export const { signIn, signUp, signOut, useSession } = authClient;
-```
-
-### With API Key Validation (KrutAuth class)
+await auth.initialize(); // validates API key against server
 
-```typescript
-import { KrutAuth } from "@krutai/auth";
+// Sign up
+const { token, user } = await auth.signUpEmail({
+  email: "user@example.com",
+  password: "secret123",
+  name: "Alice",
+});
 
-const auth = new KrutAuth({
-  apiKey: "your-krutai-api-key",
-  betterAuthOptions: {
-    database: { /* your database config */ },
-  },
+// Sign in
+const result = await auth.signInEmail({
+  email: "user@example.com",
+  password: "secret123",
 });
 
-await auth.initialize();
-```
+// Get session
+const session = await auth.getSession(result.token);
 
-## Environment Variables
+// Sign out
+await auth.signOut(result.token);
+```
 
-| Variable | Required | Description |
-|---|---|---|
-| `BETTER_AUTH_BASE_URL` | ✅ | Your app's base URL (e.g. `http://localhost:3000`) |
-| `BETTER_AUTH_SECRET` | recommended | Secret for signing sessions |
+## Configuration
 
-## Exports
+```typescript
+const auth = krutAuth({
+  apiKey: "krut_...",          // Required (or set KRUTAI_API_KEY env var)
+  serverUrl: "https://...",    // Default: "http://localhost:8000"
+  authPrefix: "/lib-auth",     // Default: "/lib-auth"
+  validateOnInit: true,        // Default: true — set false to skip in tests
+});
+```
 
-| Import path | What it provides |
-|---|---|
-| `@krutai/auth` | `krutAuth`, `KrutAuth`, validators |
-| `@krutai/auth/react` | `createAuthClient`, `useSession`, etc. |
-| `@krutai/auth/next-js` | `toNextJsHandler` |
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | `process.env.KRUTAI_API_KEY` | Your KrutAI API key |
+| `serverUrl` | `string` | `http://localhost:8000` | Base URL of your server |
+| `authPrefix` | `string` | `/lib-auth` | Path prefix for auth routes |
+| `validateOnInit` | `boolean` | `true` | Validate API key on `initialize()` |
 
 ## API Reference
 
-### `krutAuth(options)`
+### `krutAuth(config)` — Factory (recommended)
 
-Drop-in replacement for `betterAuth`. Accepts the same options.
+Creates a `KrutAuth` instance.
 
 ```typescript
 import { krutAuth } from "@krutai/auth";
+const auth = krutAuth({ apiKey: "...", serverUrl: "https://..." });
+await auth.initialize();
+```
+
+### `KrutAuth` class — Methods
 
-export const auth = krutAuth({ /* Better Auth options */ });
+| Method | HTTP Call | Description |
+|---|---|---|
+| `initialize()` | validates API key | **Must be called before other methods** |
+| `signUpEmail(params)` | `POST /lib-auth/api/auth/sign-up/email` | Register a new user |
+| `signInEmail(params)` | `POST /lib-auth/api/auth/sign-in/email` | Authenticate a user |
+| `getSession(token)` | `GET /lib-auth/api/auth/get-session` | Retrieve session info |
+| `signOut(token)` | `POST /lib-auth/api/auth/sign-out` | Invalidate a session |
+| `request(method, path, body?)` | Any | Generic helper for custom endpoints |
+| `isInitialized()` | — | Returns `boolean` |
+
+### Types
+
+```typescript
+interface SignUpEmailParams { email: string; password: string; name: string; }
+interface SignInEmailParams { email: string; password: string; }
+
+interface AuthResponse  { token: string; user: AuthUser; }
+interface AuthSession   { user: AuthUser; session: AuthSessionRecord; }
+
+interface AuthUser {
+  id: string; email: string; name?: string;
+  emailVerified: boolean; createdAt: string; updatedAt: string;
+}
 ```
 
-### `KrutAuth` class
+## Environment Variables
 
-For API-key-protected authentication.
+### Client app (where `@krutai/auth` is used)
 
-| Option | Type | Required | Description |
-|---|---|---|---|
-| `apiKey` | `string` | ✅ | Your KrutAI API key |
-| `betterAuthOptions` | `object` | — | Better Auth configuration |
-| `validateOnInit` | `boolean` | — | Validate API key on init (default: `true`) |
+| Variable | Required | Description |
+|---|---|---|
+| `KRUTAI_API_KEY` | ✅ | Your KrutAI API key |
 
-#### Methods
+### Server (where Better Auth + PostgreSQL runs)
 
-- `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
+| Variable | Required | Description |
+|---|---|---|
+| `DATABASE_URL` | ✅ | PostgreSQL connection string |
+| `BETTER_AUTH_BASE_URL` | ✅ | Your server's base URL |
+| `BETTER_AUTH_SECRET` | recommended | Secret for signing sessions |
 
 ## Error Handling
 
 ```typescript
-import { KrutAuth, ApiKeyValidationError } from "@krutai/auth";
+import { krutAuth, KrutAuthKeyValidationError } from "@krutai/auth";
 
 try {
-  const auth = new KrutAuth({ apiKey: "invalid" });
+  const auth = krutAuth({ apiKey: "invalid-key" });
   await auth.initialize();
-} catch (error) {
-  if (error instanceof ApiKeyValidationError) {
-    console.error("API key validation failed:", error.message);
+} catch (e) {
+  if (e instanceof KrutAuthKeyValidationError) {
+    console.error("Invalid API key:", e.message);
+  } else {
+    console.error("Auth error:", e);
   }
 }
 ```
 
+## Custom Endpoints
+
+Use the `request()` method to call any Better Auth endpoint not covered by the convenience methods:
+
+```typescript
+const data = await auth.request("POST", "/api/auth/some-custom-endpoint", {
+  someParam: "value",
+});
+```
+
+## Skipping Validation in Tests
+
+```typescript
+const auth = krutAuth({
+  apiKey: "test-api-key",
+  serverUrl: "http://localhost:8000",
+  validateOnInit: false, // Skip server round-trip in tests
+});
+// No need to call initialize()
+```
+
 ## Architecture
 
 ```
-@krutai/auth@0.1.9
-├── dependency: krutai          ← API key validation
-├── dependency: better-auth     ← auth engine
-├── dependency: better-sqlite3  ← default database adapter
-└── dependency: @types/better-sqlite3
+@krutai/auth@0.4.0
+└── dependency: krutai   ← API key format validation (also peerDep)
+
+Your Server
+├── better-auth          ← Auth engine
+└── pg / postgres        ← PostgreSQL adapter
 ```
 
+For Better Auth PostgreSQL setup, see: https://www.better-auth.com/docs/adapters/postgresql
+
 For Better Auth documentation, visit: https://www.better-auth.com/docs
 
 ## License

package/dist/index.d.mts

@@ -1,150 +1,280 @@
-import * as better_auth from 'better-auth';
-import { BetterAuthOptions, Auth } from 'better-auth';
-export { BetterAuthOptions } from 'better-auth';
-export { ApiKeyValidationError, validateApiKeyFormat, validateApiKeyWithService } from 'krutai';
+export { KrutAIKeyValidationError, validateApiKey, validateApiKeyFormat } from 'krutai';
 
+/**
+ * Types for @krutai/auth
+ *
+ * Pure fetch-based auth client — no local better-auth dependency.
+ */
+/**
+ * Default base URL for the KrutAI server.
+ * Used when no serverUrl is provided in the config.
+ */
+declare const DEFAULT_SERVER_URL: "http://localhost:8000";
+/**
+ * Default path prefix for the auth routes on the server.
+ * The server mounts better-auth under this prefix.
+ */
+declare const DEFAULT_AUTH_PREFIX: "/lib-auth";
 /**
  * Configuration options for KrutAuth
  */
 interface KrutAuthConfig {
     /**
-     * API key for authentication with KrutAI services
+     * KrutAI API key.
+     * Validated against the server before use.
      * Optional: defaults to process.env.KRUTAI_API_KEY
      */
     apiKey?: string;
     /**
-     * Better Auth configuration options
-     * @see https://www.better-auth.com/docs
-     */
-    betterAuthOptions?: Partial<BetterAuthOptions>;
-    /**
-     * Whether to validate the API key on initialization
-     * @default true
-     */
-    validateOnInit?: boolean;
-    /**
-     * Base URL of your deployed LangChain backend/validation server
+     * Base URL of your deployed KrutAI server.
      * @default "http://localhost:8000"
+     * @example "https://krut.ai"
      */
     serverUrl?: string;
     /**
-     * Custom API validation endpoint
+     * Path prefix for the auth routes on the server.
+     * @default "/lib-auth"
      */
-    validationEndpoint?: string;
+    authPrefix?: string;
+    /**
+     * Whether to validate the API key against the server on initialization.
+     * Set to false to skip the validation round-trip (e.g. in tests).
+     * @default true
+     */
+    validateOnInit?: boolean;
 }
 /**
- * Authentication session interface
+ * Parameters for email/password sign-up
+ */
+interface SignUpEmailParams {
+    /** User email */
+    email: string;
+    /** User password */
+    password: string;
+    /** Display name */
+    name: string;
+}
+/**
+ * Parameters for email/password sign-in
+ */
+interface SignInEmailParams {
+    /** User email */
+    email: string;
+    /** User password */
+    password: string;
+}
+/**
+ * A user record returned by the auth server
+ */
+interface AuthUser {
+    id: string;
+    email: string;
+    name?: string;
+    emailVerified: boolean;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+/**
+ * A session record returned by the auth server
+ */
+interface AuthSessionRecord {
+    id: string;
+    userId: string;
+    token: string;
+    expiresAt: string;
+    [key: string]: unknown;
+}
+/**
+ * Combined session + user response
  */
 interface AuthSession {
-    user: {
-        id: string;
-        email: string;
-        name?: string;
-        [key: string]: unknown;
-    };
-    session: {
-        id: string;
-        expiresAt: Date;
-        [key: string]: unknown;
-    };
+    user: AuthUser;
+    session: AuthSessionRecord;
+}
+/**
+ * Sign-up / sign-in response (contains token + user)
+ */
+interface AuthResponse {
+    token: string;
+    user: AuthUser;
+    [key: string]: unknown;
 }
 
 /**
- * KrutAuth - Authentication client for KrutAI
+ * KrutAuth — fetch-based authentication client for KrutAI
  *
- * This class wraps Better Auth and adds API key validation
- * to ensure only authorized users can access authentication features.
+ * Calls your deployed server's `/lib-auth` routes for all auth operations.
+ * The API key is validated against the server before use.
  *
  * @example
  * ```typescript
  * import { KrutAuth } from '@krutai/auth';
  *
  * const auth = new KrutAuth({
- *   apiKey: 'your-api-key-here',
- *   betterAuthOptions: {
- *     // Better Auth configuration
- *   }
+ *   apiKey: process.env.KRUTAI_API_KEY!,
+ *   serverUrl: 'https://krut.ai',
  * });
  *
- * // Initialize the client (validates API key)
- * await auth.initialize();
+ * await auth.initialize(); // validates key against server
  *
- * // Use authentication features
- * const betterAuth = auth.getBetterAuth();
+ * // Sign up
+ * const { token, user } = await auth.signUpEmail({
+ *   email: 'user@example.com',
+ *   password: 'secret123',
+ *   name: 'Alice',
+ * });
+ *
+ * // Sign in
+ * const result = await auth.signInEmail({
+ *   email: 'user@example.com',
+ *   password: 'secret123',
+ * });
+ *
+ * // Get session
+ * const session = await auth.getSession(result.token);
  * ```
  */
 declare class KrutAuth {
-    private config;
-    private apiKey;
-    private betterAuthInstance;
+    private readonly apiKey;
+    private readonly serverUrl;
+    private readonly authPrefix;
+    private readonly config;
     private initialized;
-    /**
-     * Creates a new KrutAuth instance
-     * @param config - Configuration options
-     * @throws {ApiKeyValidationError} If API key is invalid
-     */
     constructor(config: KrutAuthConfig);
     /**
-     * Initialize the authentication client
-     * Validates the API key and sets up Better Auth
-     * @throws {ApiKeyValidationError} If API key validation fails
+     * Initialize the auth client.
+     * Validates the API key against the server, then marks client as ready.
+     *
+     * @throws {KrutAuthKeyValidationError} if the key is rejected or the server is unreachable
      */
     initialize(): Promise<void>;
     /**
-     * Initialize Better Auth instance
-     * @private
+     * Returns whether the client has been initialized.
      */
-    private initializeBetterAuth;
+    isInitialized(): boolean;
+    private assertInitialized;
+    /** Common request headers sent to the server on every auth call. */
+    private authHeaders;
     /**
-     * Get the Better Auth instance
-     * @throws {Error} If not initialized
+     * Build the full URL for an auth endpoint.
+     * @param path - The better-auth sub-path, e.g. `/api/auth/sign-up/email`
      */
-    getBetterAuth(): Auth;
+    private url;
     /**
-     * Check if the client is initialized
+     * Generic request helper for any better-auth endpoint.
+     *
+     * Use this to call endpoints not covered by the convenience methods.
+     *
+     * @param method - HTTP method (GET, POST, etc.)
+     * @param path - The better-auth endpoint path (e.g. `/api/auth/sign-up/email`)
+     * @param body - Optional JSON body
+     * @returns The parsed JSON response
      */
-    isInitialized(): boolean;
+    request<T = unknown>(method: string, path: string, body?: Record<string, unknown> | object): Promise<T>;
     /**
-     * Get the API key (useful for making authenticated requests)
-     * @returns The API key
+     * Sign up a new user with email and password.
+     *
+     * Calls: POST {serverUrl}/lib-auth/api/auth/sign-up/email
+     *
+     * @param params - Sign-up parameters (email, password, name)
+     * @returns The auth response containing token and user
      */
-    getApiKey(): string;
+    signUpEmail(params: SignUpEmailParams): Promise<AuthResponse>;
     /**
-     * Sign in a user
-     * This is a convenience method that wraps Better Auth
-     * You can access the full Better Auth API via getBetterAuth()
+     * Sign in with email and password.
+     *
+     * Calls: POST {serverUrl}/lib-auth/api/auth/sign-in/email
+     *
+     * @param params - Sign-in parameters (email, password)
+     * @returns The auth response containing token and user
      */
-    signIn(): Promise<Auth>;
+    signInEmail(params: SignInEmailParams): Promise<AuthResponse>;
     /**
-     * Sign out the current user
-     * You can access the full Better Auth API via getBetterAuth()
+     * Get the current session for a user.
+     *
+     * Calls: GET {serverUrl}/lib-auth/api/auth/get-session
+     *
+     * @param sessionToken - The session token (Bearer token from sign-in)
+     * @returns The session containing user and session data
      */
-    signOut(): Promise<Auth>;
+    getSession(sessionToken: string): Promise<AuthSession>;
     /**
-     * Get the current session
-     * You can access the full Better Auth API via getBetterAuth()
+     * Sign out the current user.
+     *
+     * Calls: POST {serverUrl}/lib-auth/api/auth/sign-out
+     *
+     * @param sessionToken - The session token to invalidate
      */
-    getSession(): Promise<Auth>;
+    signOut(sessionToken: string): Promise<void>;
 }
 
 /**
- * krutAuth — drop-in replacement for betterAuth.
+ * @krutai/auth — Authentication package for KrutAI
  *
- * Use this instead of importing betterAuth directly.
+ * A fetch-based wrapper that calls your deployed server's `/lib-auth` routes.
+ * The user's API key is validated against the server before any auth call is made.
  *
- * @example
+ * @example Basic usage
  * ```typescript
- * import { krutAuth } from "@krutai/auth";
- * import Database from "better-sqlite3";
+ * import { krutAuth } from '@krutai/auth';
  *
- * export const auth = krutAuth({
- *   database: new Database("./sqlite.db"),
- *   emailAndPassword: { enabled: true },
+ * const auth = krutAuth({
+ *   apiKey: process.env.KRUTAI_API_KEY!,
+ *   serverUrl: 'https://krut.ai',
+ * });
+ *
+ * await auth.initialize(); // validates key with server
+ *
+ * const { token, user } = await auth.signUpEmail({
+ *   email: 'user@example.com',
+ *   password: 'secret123',
+ *   name: 'Alice',
  * });
  * ```
+ *
+ * @example Sign in
+ * ```typescript
+ * const auth = krutAuth({
+ *   apiKey: process.env.KRUTAI_API_KEY!,
+ *   serverUrl: 'https://krut.ai',
+ * });
+ * await auth.initialize();
+ *
+ * const { token, user } = await auth.signInEmail({
+ *   email: 'user@example.com',
+ *   password: 'secret123',
+ * });
+ * ```
+ *
+ * @packageDocumentation
  */
-declare function krutAuth(options: BetterAuthOptions): better_auth.Auth<BetterAuthOptions>;
 
-declare const VERSION = "0.1.9";
+/**
+ * krutAuth — convenience factory.
+ *
+ * Creates a `KrutAuth` instance configured to call your server's `/lib-auth` routes.
+ *
+ * @param config - Auth configuration (`apiKey` and `serverUrl` are required)
+ * @returns A `KrutAuth` instance — call `.initialize()` before use
+ *
+ * @example
+ * ```typescript
+ * import { krutAuth } from '@krutai/auth';
+ *
+ * const auth = krutAuth({
+ *   apiKey: process.env.KRUTAI_API_KEY!,
+ *   serverUrl: 'https://krut.ai',
+ * });
+ *
+ * await auth.initialize();
+ * const { token, user } = await auth.signInEmail({
+ *   email: 'user@example.com',
+ *   password: 'secret123',
+ * });
+ * ```
+ */
+declare function krutAuth(config: KrutAuthConfig): KrutAuth;
+declare const VERSION = "0.4.0";
 
-export { type AuthSession, KrutAuth, type KrutAuthConfig, VERSION, krutAuth };
+export { type AuthResponse, type AuthSession, type AuthSessionRecord, type AuthUser, DEFAULT_AUTH_PREFIX, DEFAULT_SERVER_URL, KrutAuth, type KrutAuthConfig, type SignInEmailParams, type SignUpEmailParams, VERSION, krutAuth };