hazo_auth 1.6.0 → 1.6.1

package/README.md

@@ -26,32 +26,61 @@ npm install hazo_auth
 
 ## Quick Start
 
-### 1. Install the package
+The fastest way to get started is using the CLI commands:
 
 ```bash
+# 1. Install the package
 npm install hazo_auth
+
+# 2. Initialize your project (creates directories, copies config files)
+npx hazo_auth init
+
+# 3. Generate API routes and pages
+npx hazo_auth generate-routes --pages
+
+# 4. Set up environment variables
+cp .env.local.example .env.local
+# Edit .env.local and add your ZEPTOMAIL_API_KEY
+
+# 5. Start your dev server
+npm run dev
 ```
 
-### 2. Copy configuration files
+That's it! Visit `http://localhost:3000/hazo_auth/login` to see the login page.
+
+### CLI Commands
 
 ```bash
-cp node_modules/hazo_auth/hazo_auth_config.example.ini ./hazo_auth_config.ini
-cp node_modules/hazo_auth/hazo_notify_config.example.ini ./hazo_notify_config.ini
+npx hazo_auth init                  # Initialize project (creates dirs, copies config)
+npx hazo_auth generate-routes       # Generate API routes only
+npx hazo_auth generate-routes --pages  # Generate API routes + pages
+npx hazo_auth validate              # Check your setup and configuration
+npx hazo_auth --help                # Show all commands
 ```
 
-### 3. Set up environment variables
+### Using Zero-Config Page Components
 
-Create a `.env.local` file:
+The generated pages import from `hazo_auth/pages/*` which provides zero-config components:
 
-```env
-ZEPTOMAIL_API_KEY=your_api_key_here
+```typescript
+// Generated app/hazo_auth/login/page.tsx
+import { LoginPage } from "hazo_auth/pages/login";
+export default LoginPage;
 ```
 
-### 4. Set up the database
+Available zero-config pages:
+- `LoginPage` - Login form with sensible defaults
+- `RegisterPage` - Registration with password requirements
+- `ForgotPasswordPage` - Password reset request
+- `ResetPasswordPage` - Set new password
+- `VerifyEmailPage` - Email verification
+- `MySettingsPage` - User profile and settings
 
-Run the database setup SQL script (see [Database Setup](#database-setup)).
+All pages work out-of-the-box with no props required!
 
-### 5. Import and use components
+### Manual Setup (Advanced)
+
+If you prefer manual control, you can use the layout components directly:
 
 ```typescript
 // Import layout components
@@ -415,7 +444,25 @@ The package exports components through these paths:
 // Main entry point - exports all public APIs
 import { ... } from "hazo_auth";
 
-// Layout components - one export per auth flow
+// Zero-config page components (recommended for quick setup)
+import { LoginPage } from "hazo_auth/pages/login";
+import { RegisterPage } from "hazo_auth/pages/register";
+import { ForgotPasswordPage } from "hazo_auth/pages/forgot_password";
+import { ResetPasswordPage } from "hazo_auth/pages/reset_password";
+import { VerifyEmailPage } from "hazo_auth/pages/verify_email";
+import { MySettingsPage } from "hazo_auth/pages/my_settings";
+
+// Or import all pages at once
+import { 
+  LoginPage, 
+  RegisterPage, 
+  ForgotPasswordPage,
+  ResetPasswordPage,
+  VerifyEmailPage,
+  MySettingsPage 
+} from "hazo_auth/pages";
+
+// Layout components - for custom implementations
 import { LoginLayout } from "hazo_auth/components/layouts/login";
 import { RegisterLayout } from "hazo_auth/components/layouts/register";
 import { ForgotPasswordLayout } from "hazo_auth/components/layouts/forgot_password";
@@ -903,22 +950,21 @@ This compiles the `src/` directory to `dist/` with:
 
 ### Package Exports
 
-The `package.json` exports field defines the public API. The package exposes only the main entry points:
+The `package.json` exports field defines the public API:
 
 ```json
 {
   "exports": {
     ".": "./dist/index.js",
+    "./pages": "./dist/page_components/index.js",
+    "./pages/login": "./dist/page_components/login.js",
+    "./pages/register": "./dist/page_components/register.js",
     "./components/layouts/login": "./dist/components/layouts/login/index.js",
     "./components/layouts/register": "./dist/components/layouts/register/index.js",
-    "./components/layouts/forgot_password": "./dist/components/layouts/forgot_password/index.js",
-    "./components/layouts/reset_password": "./dist/components/layouts/reset_password/index.js",
-    "./components/layouts/email_verification": "./dist/components/layouts/email_verification/index.js",
-    "./components/layouts/my_settings": "./dist/components/layouts/my_settings/index.js",
-    "./components/layouts/user_management": "./dist/components/layouts/user_management/index.js",
     "./components/layouts/shared": "./dist/components/layouts/shared/index.js",
     "./lib/auth/hazo_get_auth.server": "./dist/lib/auth/hazo_get_auth.server.js",
-    "./server": "./dist/server/index.js"
+    "./server": "./dist/server/index.js",
+    "./server/routes": "./dist/server/routes/index.js"
   }
 }
 ```

package/SETUP_CHECKLIST.md

@@ -2,6 +2,33 @@
 
 This checklist provides step-by-step instructions for setting up the `hazo_auth` package in your Next.js project. AI assistants can follow this guide to ensure complete and correct setup.
 
+## Quick Start (Recommended)
+
+The fastest way to set up hazo_auth:
+
+```bash
+# 1. Install the package
+npm install hazo_auth
+
+# 2. Initialize project (creates directories, copies config files)
+npx hazo_auth init
+
+# 3. Generate API routes and pages
+npx hazo_auth generate-routes --pages
+
+# 4. Set up environment variables
+cp .env.local.example .env.local
+# Edit .env.local and add ZEPTOMAIL_API_KEY
+
+# 5. Start dev server and test
+npm run dev
+# Visit http://localhost:3000/hazo_auth/login
+```
+
+If this works, skip to [Phase 6: Verification Tests](#phase-6-verification-tests).
+
+---
+
 ## Pre-flight Checks
 
 Before starting, verify your project meets these requirements:
@@ -33,7 +60,25 @@ ls node_modules/hazo_auth/package.json
 # Expected: file exists
 ```
 
-### Step 1.2: Copy configuration files
+### Step 1.2: Initialize project (Recommended)
+
+Use the CLI to automatically set up directories and copy config files:
+
+```bash
+npx hazo_auth init
+```
+
+This command:
+- Creates `public/profile_pictures/library/` directory
+- Creates `public/profile_pictures/uploads/` directory
+- Creates `data/` directory (for SQLite database)
+- Copies `hazo_auth_config.ini` and `hazo_notify_config.ini`
+- Copies profile picture library images
+- Creates `.env.local.example` template
+
+### Step 1.2b: Manual config setup (Alternative)
+
+If you prefer manual setup:
 
 ```bash
 cp node_modules/hazo_auth/hazo_auth_config.example.ini ./hazo_auth_config.ini
@@ -424,86 +469,92 @@ export { GET } from "hazo_auth/server/routes/profile_picture_filename";
 
 Create page files for each auth flow.
 
-### Step 5.1: Create auth pages
+### Step 5.1: Generate pages automatically (Recommended)
 
-**Login page** - `app/(auth)/login/page.tsx`:
-```typescript
-import { LoginLayout } from "hazo_auth/components/layouts/login";
-
-export default function LoginPage() {
-  return <LoginLayout />;
-}
+```bash
+npx hazo_auth generate-routes --pages
 ```
 
-**Register page** - `app/(auth)/register/page.tsx`:
-```typescript
-import { RegisterLayout } from "hazo_auth/components/layouts/register";
+This generates both API routes and page routes. The generated pages use zero-config components that work out of the box.
 
-export default function RegisterPage() {
-  return <RegisterLayout />;
-}
+**Generated pages:**
+```
+app/hazo_auth/
+├── login/page.tsx
+├── register/page.tsx
+├── forgot_password/page.tsx
+├── reset_password/page.tsx
+├── verify_email/page.tsx
+└── my_settings/page.tsx
 ```
 
-**Forgot password page** - `app/(auth)/forgot-password/page.tsx`:
-```typescript
-import { ForgotPasswordLayout } from "hazo_auth/components/layouts/forgot_password";
+### Step 5.2: Manual page creation (Alternative)
 
-export default function ForgotPasswordPage() {
-  return <ForgotPasswordLayout />;
-}
-```
+If you prefer manual setup or need custom paths, create these files:
 
-**Reset password page** - `app/(auth)/reset-password/page.tsx`:
+**Login page** - `app/hazo_auth/login/page.tsx`:
 ```typescript
-import { ResetPasswordLayout } from "hazo_auth/components/layouts/reset_password";
+import { LoginPage } from "hazo_auth/pages/login";
+export default LoginPage;
+```
 
-export default function ResetPasswordPage() {
-  return <ResetPasswordLayout />;
-}
+**Register page** - `app/hazo_auth/register/page.tsx`:
+```typescript
+import { RegisterPage } from "hazo_auth/pages/register";
+export default RegisterPage;
 ```
 
-**Email verification page** - `app/(auth)/verify-email/page.tsx`:
+**Forgot password page** - `app/hazo_auth/forgot_password/page.tsx`:
 ```typescript
-import { EmailVerificationLayout } from "hazo_auth/components/layouts/email_verification";
+import { ForgotPasswordPage } from "hazo_auth/pages/forgot_password";
+export default ForgotPasswordPage;
+```
 
-export default function VerifyEmailPage() {
-  return <EmailVerificationLayout />;
-}
+**Reset password page** - `app/hazo_auth/reset_password/page.tsx`:
+```typescript
+import { ResetPasswordPage } from "hazo_auth/pages/reset_password";
+export default ResetPasswordPage;
 ```
 
-**My settings page** - `app/(auth)/my-settings/page.tsx`:
+**Email verification page** - `app/hazo_auth/verify_email/page.tsx`:
 ```typescript
-import { MySettingsLayout } from "hazo_auth/components/layouts/my_settings";
+import { VerifyEmailPage } from "hazo_auth/pages/verify_email";
+export default VerifyEmailPage;
+```
 
-export default function MySettingsPage() {
-  return <MySettingsLayout />;
-}
+**My settings page** - `app/hazo_auth/my_settings/page.tsx`:
+```typescript
+import { MySettingsPage } from "hazo_auth/pages/my_settings";
+export default MySettingsPage;
 ```
 
-### Step 5.2: Create layout for auth pages (optional)
+### Step 5.3: Custom page routes (Advanced)
+
+If you need custom paths or want to wrap pages with your own layout:
 
-`app/(auth)/layout.tsx`:
 ```typescript
-export default function AuthLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
+// app/(auth)/login/page.tsx
+import { LoginPage } from "hazo_auth/pages/login";
+
+export default function CustomLoginPage() {
   return (
-    <div className="min-h-screen flex items-center justify-center bg-background">
-      {children}
+    <div className="min-h-screen flex items-center justify-center">
+      <LoginPage 
+        redirectRoute="/dashboard"
+        successMessage="Welcome back!"
+      />
     </div>
   );
 }
 ```
 
 **Checklist:**
-- [ ] Login page created (`/login`)
-- [ ] Register page created (`/register`)
-- [ ] Forgot password page created (`/forgot-password`)
-- [ ] Reset password page created (`/reset-password`)
-- [ ] Email verification page created (`/verify-email`)
-- [ ] My settings page created (`/my-settings`)
+- [ ] Login page created (`/hazo_auth/login`)
+- [ ] Register page created (`/hazo_auth/register`)
+- [ ] Forgot password page created (`/hazo_auth/forgot_password`)
+- [ ] Reset password page created (`/hazo_auth/reset_password`)
+- [ ] Email verification page created (`/hazo_auth/verify_email`)
+- [ ] My settings page created (`/hazo_auth/my_settings`)
 
 ---
 
@@ -578,15 +629,22 @@ curl -s http://localhost:3000/api/hazo_auth/library_photos | jq
 **Expected response:**
 ```json
 {
-  "photos": [
-    {"url": "/profile_pictures/library/...", "name": "..."},
-    ...
-  ]
+  "success": true,
+  "categories": ["Cars", "Young Cartoons"],
+  "source": "project"
 }
 ```
 
-**If library photos not showing:**
-- Copy profile pictures from `node_modules/hazo_auth/public/profile_pictures/library/` to `public/profile_pictures/library/`
+The `source` field indicates where photos are served from:
+- `"project"` - Photos are in your project's `public/profile_pictures/library/`
+- `"node_modules"` - Photos are served from `node_modules/hazo_auth/public/` via API route
+
+**Test paginated photos:**
+```bash
+curl -s "http://localhost:3000/api/hazo_auth/library_photos?category=Cars&page=1&page_size=5" | jq
+```
+
+**Note:** Library photos work automatically whether they're copied to your project or still in node_modules. The API will serve them from node_modules as a fallback.
 
 ### Test 6: Visit Pages in Browser
 
@@ -596,10 +654,10 @@ npm run dev
 ```
 
 Visit each page and verify it loads:
-- [ ] `http://localhost:3000/login` - Login form displays
-- [ ] `http://localhost:3000/register` - Registration form displays
-- [ ] `http://localhost:3000/forgot-password` - Forgot password form displays
-- [ ] `http://localhost:3000/my-settings` - Settings page displays (after login)
+- [ ] `http://localhost:3000/hazo_auth/login` - Login form displays
+- [ ] `http://localhost:3000/hazo_auth/register` - Registration form displays
+- [ ] `http://localhost:3000/hazo_auth/forgot_password` - Forgot password form displays
+- [ ] `http://localhost:3000/hazo_auth/my_settings` - Settings page displays (after login)
 
 ---
 
@@ -620,13 +678,26 @@ Visit each page and verify it loads:
 **Symptoms:** Avatar shows fallback initials, library photos empty.
 
 **Solutions:**
-1. Copy library photos:
+1. **Run init command** (copies library photos automatically):
+   ```bash
+   npx hazo_auth init
+   ```
+
+2. **Or manually copy library photos:**
    ```bash
    mkdir -p public/profile_pictures/library
    cp -r node_modules/hazo_auth/public/profile_pictures/library/* public/profile_pictures/library/
    ```
-2. Verify `library_photos` API route exists
-3. Check file permissions on `public/profile_pictures/`
+
+3. **Check API response source:**
+   ```bash
+   curl -s http://localhost:3000/api/hazo_auth/library_photos | jq '.source'
+   ```
+   - If `"node_modules"` - Photos are being served from the package (slower but works)
+   - If `"project"` - Photos are in your public folder (optimal)
+
+4. Verify `library_photos` and `library_photo` API routes exist
+5. Check file permissions on `public/profile_pictures/`
 
 ### Issue: Database connection failed
 

package/dist/app/api/hazo_auth/library_photo/[category]/[filename]/route.d.ts

@@ -0,0 +1,9 @@
+import { NextRequest, NextResponse } from "next/server";
+export declare const dynamic = "force-dynamic";
+export declare function GET(request: NextRequest, { params }: {
+    params: {
+        category: string;
+        filename: string;
+    };
+}): Promise<NextResponse<unknown>>;
+//# sourceMappingURL=route.d.ts.map

package/dist/app/api/hazo_auth/library_photo/[category]/[filename]/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../../src/app/api/hazo_auth/library_photo/[category]/[filename]/route.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AASxD,eAAO,MAAM,OAAO,kBAAkB,CAAC;AAevC,wBAAsB,GAAG,CACvB,OAAO,EAAE,WAAW,EACpB,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,kCA4E/D"}

package/dist/app/api/hazo_auth/library_photo/[category]/[filename]/route.js

@@ -0,0 +1,82 @@
+// file_description: API route to serve library photos from node_modules fallback
+// This route is used when library photos haven't been copied to the project's public folder
+// section: imports
+import { NextResponse } from "next/server";
+import { get_library_photo_path } from "../../../../../../lib/services/profile_picture_service";
+import { create_app_logger } from "../../../../../../lib/app_logger";
+import { get_filename, get_line_number } from "../../../../../../lib/utils/api_route_helpers";
+import fs from "fs";
+import path from "path";
+// section: route_config
+// Cache library photos for 1 hour (they don't change)
+export const dynamic = 'force-dynamic';
+// section: constants
+const MIME_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+const CACHE_MAX_AGE = 3600; // 1 hour in seconds
+// section: api_handler
+export async function GET(request, { params }) {
+    const logger = create_app_logger();
+    const { category, filename } = params;
+    try {
+        // Validate inputs to prevent path traversal
+        if (category.includes("..") ||
+            category.includes("/") ||
+            category.includes("\\") ||
+            filename.includes("..") ||
+            filename.includes("/") ||
+            filename.includes("\\")) {
+            logger.warn("library_photo_invalid_path", {
+                filename: get_filename(),
+                line_number: get_line_number(),
+                category,
+                requested_filename: filename,
+            });
+            return NextResponse.json({ error: "Invalid path" }, { status: 400 });
+        }
+        // Get the physical file path
+        const photo_path = get_library_photo_path(category, filename);
+        if (!photo_path) {
+            logger.warn("library_photo_not_found", {
+                filename: get_filename(),
+                line_number: get_line_number(),
+                category,
+                requested_filename: filename,
+            });
+            return NextResponse.json({ error: "Photo not found" }, { status: 404 });
+        }
+        // Read the file
+        const file_buffer = fs.readFileSync(photo_path);
+        const ext = path.extname(filename).toLowerCase();
+        const content_type = MIME_TYPES[ext] || "application/octet-stream";
+        // Return the image with caching headers
+        return new NextResponse(file_buffer, {
+            status: 200,
+            headers: {
+                "Content-Type": content_type,
+                "Content-Length": file_buffer.length.toString(),
+                "Cache-Control": `public, max-age=${CACHE_MAX_AGE}, immutable`,
+                "X-Library-Source": "node_modules",
+            },
+        });
+    }
+    catch (error) {
+        const error_message = error instanceof Error ? error.message : "Unknown error";
+        const error_stack = error instanceof Error ? error.stack : undefined;
+        logger.error("library_photo_error", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            category,
+            requested_filename: filename,
+            error_message,
+            error_stack,
+        });
+        return NextResponse.json({ error: "Failed to serve photo" }, { status: 500 });
+    }
+}

package/dist/app/api/hazo_auth/library_photos/route.d.ts

@@ -4,9 +4,18 @@ export declare function GET(request: NextRequest): Promise<NextResponse<{
     success: boolean;
     category: string;
     photos: string[];
+    pagination: {
+        page: number;
+        page_size: number;
+        total: number;
+        has_more: boolean;
+        total_pages: number;
+    };
+    source: "project" | "node_modules";
 }> | NextResponse<{
     success: boolean;
     categories: string[];
+    source: "project" | "node_modules" | null;
 }> | NextResponse<{
     error: string;
 }>>;

package/dist/app/api/hazo_auth/library_photos/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/app/api/hazo_auth/library_photos/route.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMxD,eAAO,MAAM,OAAO,kBAAkB,CAAC;AAGvC,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;;;;;;;;IA4D7C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/app/api/hazo_auth/library_photos/route.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAUxD,eAAO,MAAM,OAAO,kBAAkB,CAAC;AAOvC,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;;;;;;;;;;;;;;;;;IAmF7C"}

package/dist/app/api/hazo_auth/library_photos/route.js

@@ -1,43 +1,68 @@
-// file_description: API route for listing library photo categories and photos in categories
+// file_description: API route for listing library photo categories and photos in categories with pagination support
 // section: imports
 import { NextResponse } from "next/server";
-import { get_library_categories, get_library_photos } from "../../../../lib/services/profile_picture_service";
+import { get_library_categories, get_library_photos_paginated, get_library_source } from "../../../../lib/services/profile_picture_service";
 import { create_app_logger } from "../../../../lib/app_logger";
 import { get_filename, get_line_number } from "../../../../lib/utils/api_route_helpers";
 // section: route_config
 export const dynamic = 'force-dynamic';
+// section: constants
+const DEFAULT_PAGE_SIZE = 20;
+const MAX_PAGE_SIZE = 100;
 // section: api_handler
 export async function GET(request) {
     const logger = create_app_logger();
     try {
         const { searchParams } = new URL(request.url);
         const category = searchParams.get("category");
+        const page_param = searchParams.get("page");
+        const page_size_param = searchParams.get("page_size");
+        // Parse pagination parameters
+        const page = page_param ? Math.max(1, parseInt(page_param, 10) || 1) : 1;
+        const page_size = page_size_param
+            ? Math.min(MAX_PAGE_SIZE, Math.max(1, parseInt(page_size_param, 10) || DEFAULT_PAGE_SIZE))
+            : DEFAULT_PAGE_SIZE;
         if (category) {
-            // Return photos in the specified category
-            const photos = get_library_photos(category);
+            // Return photos in the specified category with pagination
+            const result = get_library_photos_paginated(category, page, page_size);
             logger.info("library_photos_category_requested", {
                 filename: get_filename(),
                 line_number: get_line_number(),
                 category,
-                photoCount: photos.length,
+                page,
+                page_size,
+                total: result.total,
+                returned: result.photos.length,
+                source: result.source,
             });
             return NextResponse.json({
                 success: true,
                 category,
-                photos,
+                photos: result.photos,
+                pagination: {
+                    page: result.page,
+                    page_size: result.page_size,
+                    total: result.total,
+                    has_more: result.has_more,
+                    total_pages: Math.ceil(result.total / result.page_size),
+                },
+                source: result.source,
             }, { status: 200 });
         }
         else {
             // Return list of categories
             const categories = get_library_categories();
+            const source = get_library_source();
             logger.info("library_categories_requested", {
                 filename: get_filename(),
                 line_number: get_line_number(),
                 categoryCount: categories.length,
+                source,
             });
             return NextResponse.json({
                 success: true,
                 categories,
+                source,
             }, { status: 200 });
         }
     }

package/dist/cli/generate.d.ts

@@ -1,2 +1,7 @@
-export declare function generate_routes(custom_app_dir?: string): void;
+export type GenerateOptions = {
+    dir?: string;
+    pages?: boolean;
+    all?: boolean;
+};
+export declare function generate_routes(options?: GenerateOptions): void;
 //# sourceMappingURL=generate.d.ts.map

package/dist/cli/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AA0EA,wBAAgB,eAAe,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAwE7D"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAwJF,wBAAgB,eAAe,CAAC,OAAO,GAAE,eAAoB,GAAG,IAAI,CA8DnE"}