npm - hazo_auth - Versions diffs - 1.6.0 → 1.6.2 - Mend

hazo_auth 1.6.0 → 1.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (74) hide show

package/README.md CHANGED Viewed

@@ -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
+All pages work out-of-the-box with no props required!
-Run the database setup SQL script (see [Database Setup](#database-setup)).
+### Manual Setup (Advanced)
-### 5. Import and use components
+If you prefer manual control, you can use the layout components directly:
 ```typescript
 // Import layout components
@@ -77,6 +106,132 @@ import { hazo_get_auth } from "hazo_auth/lib/auth/hazo_get_auth.server";
 ---
+## Required Dependencies
+hazo_auth uses shadcn/ui components. Install the required dependencies in your project:
+```bash
+# Required for all auth pages
+npx shadcn@latest add button input label
+# Required for My Settings page
+npx shadcn@latest add dialog tabs switch avatar dropdown-menu
+# Required for toast notifications
+npx shadcn@latest add sonner
+```
+**Add Toaster to your app layout:**
+```tsx
+// app/layout.tsx
+import { Toaster } from "sonner";
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Toaster />
+      </body>
+    </html>
+  );
+}
+```
+---
+## Client vs Server Imports
+hazo_auth provides separate entry points for client and server code to avoid bundling Node.js modules in the browser:
+### Client Components
+For client components (browser-safe, no Node.js dependencies):
+```typescript
+// Use hazo_auth/client for client components
+import {
+  ProfilePicMenu,
+  use_auth_status,
+  use_hazo_auth,
+  cn
+} from "hazo_auth/client";
+```
+### Server Components / API Routes
+For server-side code (API routes, Server Components):
+```typescript
+// Use the main hazo_auth export for server-side code
+import { hazo_get_auth, get_config_value } from "hazo_auth";
+import { hazo_get_user_profiles } from "hazo_auth";
+```
+### Why This Matters
+If you import from the main `hazo_auth` entry in a client component, you'll get bundling errors like:
+```
+Module not found: Can't resolve 'fs'
+```
+Use `hazo_auth/client` to avoid this.
+---
+## Dark Mode / Theming
+hazo_auth supports dark mode via CSS custom properties. To enable dark mode:
+### 1. Import the theme CSS
+Copy the variables file to your project:
+```bash
+cp node_modules/hazo_auth/src/styles/hazo-auth-variables.css ./app/hazo-auth-theme.css
+```
+Import in your `globals.css`:
+```css
+@import "./hazo-auth-theme.css";
+```
+### 2. CSS Variables Reference
+You can customize the theme by overriding these variables:
+```css
+:root {
+  /* Backgrounds */
+  --hazo-bg-subtle: #f8fafc;      /* Light background */
+  --hazo-bg-muted: #f1f5f9;       /* Slightly darker background */
+  /* Text */
+  --hazo-text-primary: #0f172a;   /* Primary text */
+  --hazo-text-secondary: #334155; /* Secondary text */
+  --hazo-text-muted: #64748b;     /* Muted/subtle text */
+  /* Borders */
+  --hazo-border: #e2e8f0;         /* Standard border */
+}
+.dark {
+  /* Dark mode overrides */
+  --hazo-bg-subtle: #18181b;
+  --hazo-bg-muted: #27272a;
+  --hazo-text-primary: #fafafa;
+  --hazo-text-secondary: #d4d4d8;
+  --hazo-text-muted: #a1a1aa;
+  --hazo-border: #3f3f46;
+}
+```
+The dark class is typically added by next-themes or similar theme providers.
+---
 ## Configuration Setup
 After installing the package, you need to set up configuration files in your project root:
@@ -415,7 +570,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 +1076,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 CHANGED Viewed

@@ -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,79 @@ ls node_modules/hazo_auth/package.json
 # Expected: file exists
 ```
-### Step 1.2: Copy configuration files
+### Step 1.2: Install Required shadcn/ui Components
+hazo_auth uses shadcn/ui components. Install the required dependencies:
+**For all auth pages (login, register, etc.):**
+```bash
+npx shadcn@latest add button input label
+```
+**For My Settings page:**
+```bash
+npx shadcn@latest add dialog tabs switch avatar dropdown-menu
+```
+**For toast notifications:**
+```bash
+npx shadcn@latest add sonner
+```
+**Add Toaster to your app layout:**
+Edit `app/layout.tsx` and add the Toaster component:
+```tsx
+import { Toaster } from "sonner";
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Toaster />
+      </body>
+    </html>
+  );
+}
+```
+### Step 1.4: Enable Dark Mode Support (Optional)
+hazo_auth components support dark mode via CSS custom properties. Add the CSS variables to your global styles:
+**Copy the CSS variables file:**
+```bash
+cp node_modules/hazo_auth/src/styles/hazo-auth-variables.css ./app/hazo-auth-theme.css
+```
+**Import in your global styles (`app/globals.css`):**
+```css
+@import "./hazo-auth-theme.css";
+```
+Or add the variables directly to your CSS - see the file for all available variables.
+### Step 1.5: 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 +523,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 +683,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 +708,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 +732,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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 });
+    }
+}