@main12/auth-login 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @main12/auth-login
 
-**Payload CMS authentication plugin** — login, signup, OTP, forgot password, branded emails, and "Powered by Main 12" footer. Install once, configure your project name and logo, done.
+**Payload CMS authentication plugin** — login, signup, OTP, forgot password, branded emails, and "Powered by Main 12" footer. Install once, done.
 
 ```ts
 // payload.config.ts
@@ -10,7 +10,8 @@ plugins: [
   authLoginPlugin({
     projectName: 'My SaaS',
     domain: 'https://myapp.com',
-    style: 'hero-ui',        // 'tailwind' (default) | 'hero-ui'
+    logo: 'https://myapp.com/logo.png',  // shown in all auth pages + emails
+    style: 'hero-ui',                     // 'tailwind' (default) | 'hero-ui'
   }),
 ]
 ```
@@ -24,7 +25,8 @@ plugins: [
 - **5 API endpoints** — `check-email`, `otp/send`, `otp/verify`, `set-password`, `signup`
 - **OTP engine** — SHA-256 hashing + `timingSafeEqual` comparison, 10-min expiry, 3 attempts
 - **Email templates** — welcome, OTP login, password reset, password changed (EN/ES)
-- **Powered by Main 12** — bundled inline SVG, linked to main12.com by default
+- **Powered by Main 12** — bundled inline SVG, linked to main12.com by default (URL overridable)
+- **Global logo** — pass once in plugin config, automatically shown on all pages and email headers
 - **Zero runtime deps** (Tailwind mode) — Next.js + React are peer dependencies
 
 ---
@@ -35,9 +37,9 @@ plugins: [
 pnpm add @main12/auth-login
 ```
 
-### Tailwind mode (default, zero UI deps)
+### Tailwind mode (default, zero UI deps — also ShadCN compatible)
 
-No extra dependencies needed.
+No extra dependencies needed. The Tailwind style uses standard utility classes that work in any Tailwind project, including ShadCN-based ones.
 
 ### HeroUI mode
 
@@ -49,191 +51,310 @@ pnpm add @heroui/react framer-motion @iconify/react
 
 ## Quick Start
 
-### 1. Add the plugin to your Payload config
+### 1. Add the plugin + Users collection
 
 ```ts
 import { authLoginPlugin } from '@main12/auth-login'
 
 export default buildConfig({
+  collections: [
+    {
+      slug: 'users',
+      auth: { tokenExpiration: 7200, verify: false, maxLoginAttempts: 5 },
+      fields: [
+        { name: 'name', type: 'text' },
+        { name: 'otpHash', type: 'text', admin: { hidden: true } },
+        { name: 'otpAttempts', type: 'number', admin: { hidden: true } },
+        { name: 'otpExpiresAt', type: 'text', admin: { hidden: true } },
+      ],
+    },
+  ],
   plugins: [
     authLoginPlugin({
       projectName: 'My App',
       domain: 'https://myapp.com',
-      contactEmail: 'support@myapp.com',
-      style: 'tailwind',   // or 'hero-ui'
+      logo: '/logo.png',
+      style: 'hero-ui',
     }),
   ],
-  // ... rest of your config
 })
 ```
 
-### 2. Add auth pages to your app
-
-Create one-line route files under `src/app/(frontend)/(auth)/`:
+### 2. Create one-line route files
 
 ```tsx
-// login/page.tsx
+// src/app/(frontend)/(auth)/login/page.tsx
 export { LoginPage as default } from '@main12/auth-login/client'
 
-// signup/page.tsx
+// src/app/(frontend)/(auth)/signup/page.tsx
 export { SignupPage as default } from '@main12/auth-login/client'
 
-// forgot-password/page.tsx
+// src/app/(frontend)/(auth)/forgot-password/page.tsx
 export { ForgotPasswordPage as default } from '@main12/auth-login/client'
 
-// verify-otp/page.tsx
+// src/app/(frontend)/(auth)/verify-otp/page.tsx
 export { VerifyOtpPage as default } from '@main12/auth-login/client'
 
-// set-password/page.tsx
+// src/app/(frontend)/(auth)/set-password/page.tsx
 export { SetPasswordPage as default } from '@main12/auth-login/client'
 ```
 
 ### 3. Wire up the login action
 
-The plugin needs a `login` function. Pass yours from Payload's `useAuth()`:
-
 ```tsx
 // login/page.tsx
 'use client'
 import { LoginPage } from '@main12/auth-login/client'
 import { useAuth } from '@/providers/Auth'
-import AppLogo from '@/components/Logo/AppLogo'
 
 export default function Page() {
   const { login } = useAuth()
-  return (
-    <LoginPage
-      logo={<AppLogo width={180} height={42} />}
-      onPasswordLogin={login}
-      redirectTo="/dashboard"
-      poweredBy={{ enabled: true }}
-    />
-  )
+  return <LoginPage onPasswordLogin={login} redirectTo="/dashboard" />
 }
 ```
 
+### 4. Visit `/login` — done.
+
 ---
 
-## Configuration Options
+## Configuration
 
 ```ts
 authLoginPlugin({
-  // === Branding ===
-  projectName: 'My App',          // Used in email subjects and footers
+  projectName: 'My App',          // Email subjects + footers
   contactEmail: 'hi@myapp.com',   // Email footer contact
   domain: 'https://myapp.com',    // Links in emails
-
-  // === Style ===
+  logo: '/logo.png',              // All auth pages + email headers
   style: 'tailwind',              // 'tailwind' | 'hero-ui'
-
-  // === Enable/Disable ===
-  enabled: true,                  // Set false to disable the plugin
+  enabled: true,
 })
 ```
 
-Each page component also accepts these props:
+### Per-page overrides
 
-```ts
+```tsx
 <LoginPage
-  logo={...}                    // React node — your brand logo
-  onPasswordLogin={login}       // Required — Payload's login function
-  redirectTo="/dashboard"       // Where to go after login
-  showGoogleOAuth={true}        // Show "Continue with Google" button
-  signupUrl="/signup"           // Link to signup page
-  poweredBy={{                  // Powered by logo config
-    enabled: true,
-    logoUrl: '/custom-logo.png',  // Override the default Main12 logo
-    linkUrl: 'https://your-site.com',
-    width: 28,
-    height: 28,
-  }}
+  logo={<AppLogo width={180} />}  // Override global logo (optional)
+  onPasswordLogin={login}          // Required
+  redirectTo="/dashboard"
+  showGoogleOAuth={true}
+  signupUrl="/signup"
+  poweredBy={{ enabled: true, logoUrl: '/custom.png', linkUrl: 'https://...' }}
 />
 ```
 
 ---
 
-## Using Hooks & Services Directly
+## Building Custom Pages
+
+Use the plugin's hooks to build your own UI with any component library (HeroUI, shadcn, plain Tailwind).
+
+### Hook Quick-Reference
+
+| Hook | Returns | Key inputs |
+|------|---------|------------|
+| `useLoginFlow({ redirectTo, onPasswordLogin })` | `step, email, password, error, isLoading, handleEmailSubmit, handlePasswordSubmit, handleSendOtp, handleEditEmail` | `redirectTo: string`, `onPasswordLogin: (creds) => Promise<void>` |
+| `useSignupFlow()` | `name, email, error, isLoading, setName, setEmail, handleSubmit` | none — manages its own state |
+| `useForgotPasswordFlow()` | `email, error, isLoading, setEmail, handleSubmit` | none |
+| `useVerifyOtpFlow({ email, purpose, redirectTo })` | `otp, error, isLoading, isResending, resendCooldown, setOtp, handleSubmit, handleResendCode` | `email: string`, `purpose: 'login'\|'signup'\|'password-reset'` |
+| `useSetPasswordFlow({ redirectTo })` | `password, confirmPassword, error, isLoading, strength, setPassword, setConfirmPassword, handleSubmit` | `redirectTo: string` |
+| `useAuth()` (from Payload) | `user, login, logout, create` | (your existing Payload auth provider) |
 
-Don't want the pre-built pages? Use the hooks and services to build your own:
+### Full Example: Custom Login Page
 
 ```tsx
-import { useLoginFlow, useVerifyOtpFlow, checkEmail, sendOtp } from '@main12/auth-login/client'
-
-function MyCustomLogin() {
-  const { email, handleEmailSubmit, ... } = useLoginFlow({
-    redirectTo: '/dashboard',
-    onPasswordLogin: login,
-  })
-  // Build your own UI with these values
+'use client'
+import { useLoginFlow } from '@main12/auth-login/client'
+import { useAuth } from '@/providers/Auth'
+
+export default function CustomLogin() {
+  const { login } = useAuth()
+  const {
+    step, email, password, error, isLoading, showPassword,
+    setEmail, setPassword, setShowPassword,
+    handleEmailSubmit, handlePasswordSubmit, handleSendOtp, handleEditEmail,
+  } = useLoginFlow({ redirectTo: '/dashboard', onPasswordLogin: login })
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50">
+      <div className="w-full max-w-md p-8 bg-white rounded-2xl shadow-xl">
+        <img src="/logo.png" className="mx-auto mb-6" width={180} alt="" />
+
+        {/* Step 1: Email */}
+        {step === 'email' && (
+          <form onSubmit={handleEmailSubmit} className="space-y-4">
+            <h1 className="text-xl font-semibold text-center">Welcome Back</h1>
+            {error && <p className="text-red-600 text-sm">{error}</p>}
+            <input type="email" value={email} onChange={e => setEmail(e.target.value)}
+              placeholder="Email" required className="w-full h-12 px-4 border rounded-xl" />
+            <button type="submit" disabled={isLoading}
+              className="w-full h-12 bg-[#D5E855] rounded-full font-semibold">
+              {isLoading ? 'Loading...' : 'Continue'}
+            </button>
+          </form>
+        )}
+
+        {/* Step 2a: Password */}
+        {step === 'password' && (
+          <form onSubmit={handlePasswordSubmit} className="space-y-4">
+            <div className="flex justify-between border rounded-xl px-4 py-3">
+              <span>{email}</span>
+              <button type="button" onClick={handleEditEmail} className="text-sm">Edit</button>
+            </div>
+            {error && <p className="text-red-600 text-sm">{error}</p>}
+            <input type={showPassword ? 'text' : 'password'} value={password}
+              onChange={e => setPassword(e.target.value)} placeholder="Password" required
+              className="w-full h-12 px-4 border rounded-xl" autoFocus />
+            <button type="submit" disabled={isLoading}
+              className="w-full h-12 bg-[#D5E855] rounded-full font-semibold">
+              {isLoading ? 'Loading...' : 'Sign In'}
+            </button>
+          </form>
+        )}
+
+        {/* Step 2b: OTP Prompt (migrated users without password) */}
+        {step === 'otp-prompt' && (
+          <div className="space-y-4">
+            <div className="flex justify-between border rounded-xl px-4 py-3">
+              <span>{email}</span>
+              <button type="button" onClick={handleEditEmail}>Edit</button>
+            </div>
+            {error && <p className="text-red-600 text-sm">{error}</p>}
+            <div className="bg-blue-50 border border-blue-200 rounded-lg p-4 text-sm text-blue-700">
+              We'll send a verification code to this email.
+            </div>
+            <button onClick={handleSendOtp} disabled={isLoading}
+              className="w-full h-12 bg-[#D5E855] rounded-full font-semibold">
+              {isLoading ? 'Sending...' : 'Send Code'}
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  )
 }
 ```
 
-### Exported Hooks
+### Custom Signup
 
-| Hook | Purpose |
-|------|---------|
-| `useLoginFlow` | Multi-step login state machine (email → password/OTP) |
-| `useVerifyOtpFlow` | OTP input, verify, resend with cooldown |
-| `useForgotPasswordFlow` | Email → check → send OTP |
-| `useSetPasswordFlow` | Set password with strength indicator |
+Same pattern — call `onSignup(name, email)` from your form, redirect to `/verify-otp?email=...&purpose=signup` on success.
 
-### Exported Services
+### Custom Verify OTP
 
-| Function | Description |
-|----------|-------------|
-| `checkEmail(email)` | Check if user exists and has password |
-| `sendOtp(email, purpose)` | Send OTP to email |
-| `verifyOtp(email, otp)` | Verify OTP code |
-| `setUserPassword(password, confirm)` | Set/update password |
-| `signup(name, email)` | Create new user |
-| `initiateGoogleLogin(redirect)` | Redirect to Google OAuth |
+Use `useVerifyOtpFlow({ email, purpose, redirectTo })`. It manages the 6-digit input, verification, resend cooldown (60s), and auto-redirect. All you need is an `<input>` or `<InputOtp>` for the code and a verify button.
+
+### Custom Forgot Password
+
+Use `useForgotPasswordFlow()`. Collect email, call `handleSubmit(e)`. It checks user exists, sends OTP, and redirects to `/verify-otp?email=...&purpose=password-reset`.
+
+### Custom Set Password
+
+Use `useSetPasswordFlow({ redirectTo })`. Two password fields (new + confirm). The hook validates strength (≥8 chars, 3/4 criteria) and matches. Returns `strength.score` (0-5) for a visual indicator.
 
 ---
 
-## API Endpoints
+## Custom Email Templates
+
+```ts
+import { generateWelcomeEmail, getEmailTranslations } from '@main12/auth-login/rsc'
+
+// Override translations
+const t = getEmailTranslations('en')
+t.welcome.subject = 'Welcome to My SaaS! 🚀'
+
+// Or wrap template generators
+function myWelcome(params) {
+  const base = generateWelcomeEmail(params)
+  return { ...base, html: base.html.replace('Get Started', 'Launch Now') }
+}
+
+// Use in hooks/endpoints
+await payload.sendEmail({
+  to: user.email,
+  ...myWelcome({ userName: user.name, userEmail: user.email }),
+})
+```
 
-Registered automatically by the plugin:
+---
+
+## API Endpoints
 
 | Method | Path | Description |
 |--------|------|-------------|
 | POST | `/api/auth/check-email` | Check if email is registered |
-| POST | `/api/auth/otp/send` | Generate + send OTP |
-| POST | `/api/auth/otp/verify` | Verify OTP + login |
+| POST | `/api/auth/otp/send` | Generate + send OTP via Payload email adapter |
+| POST | `/api/auth/otp/verify` | Verify OTP + login (sets httpOnly cookie) |
 | POST | `/api/auth/set-password` | Set/update password |
-| POST | `/api/auth/signup` | Create account |
+| POST | `/api/auth/signup` | Create account + send welcome email |
 
 ---
 
-## Email Templates
+## ShadCN Compatibility
 
-Four HTML email templates in EN/ES, using the host project's Payload email adapter:
+The `tailwind` style works in ShadCN projects out of the box. For ShadCN components, build a [custom page](#building-custom-pages) — import the plugin's hooks and use your `@/components/ui/button`, `@/components/ui/input`, etc.
 
-- **Welcome** — sent on signup
-- **OTP** — 6-digit code for login or password reset
-- **Password Reset** — OTP email for forgot password flow
-- **Password Changed** — confirmation after password update
+---
 
-Override translations or template functions via the `emails` option (Phase 2).
+## 🤖 AI Agent Prompts
+
+Copy these prompts into Claude, Cursor, Copilot, or any AI agent.
+
+### Prompt: Set up the auth plugin in a new Payload project
+
+```
+Add @main12/auth-login to this Payload project:
+
+1. Install: pnpm add @main12/auth-login
+2. In payload.config.ts, add:
+   - Users collection with auth enabled + otpHash, otpAttempts, otpExpiresAt fields
+   - Plugin: authLoginPlugin({ projectName: "<PROJECT>", domain: "<URL>", logo: "/logo.png", style: "hero-ui" })
+3. Create route files under src/app/(frontend)/(auth)/:
+   - login/page.tsx      → export { LoginPage as default } from '@main12/auth-login/client'
+   - signup/page.tsx     → export { SignupPage as default } from '@main12/auth-login/client'
+   - forgot-password/page.tsx  → export { ForgotPasswordPage as default } from '@main12/auth-login/client'
+   - verify-otp/page.tsx → export { VerifyOtpPage as default } from '@main12/auth-login/client'
+   - set-password/page.tsx → export { SetPasswordPage as default } from '@main12/auth-login/client'
+4. In login/page.tsx, wrap LoginPage with useAuth() to pass onPasswordLogin={login}.
+5. Verify: visit /login
+```
+
+### Prompt: Build a custom login page with HeroUI components
+
+```
+Build a custom login page using @main12/auth-login hooks and @heroui/react:
+
+- Import useLoginFlow from '@main12/auth-login/client'
+- Use useAuth() from Payload's Auth provider for the login function
+- Render 3 steps: email input → password input / OTP prompt
+- Use HeroUI <Button>, <Input> with variant="bordered", rounded-full
+- Add "Continue with Google" button using initiateGoogleLogin from the plugin
+- Add "Powered by Main12" footer from the plugin's PoweredBy component
+```
+
+### Prompt: Customize email templates for my project
+
+```
+Customize the email templates from @main12/auth-login for my project "<PROJECT_NAME>":
+
+- Import generateWelcomeEmail, generateOtpEmail, generatePasswordResetEmail, generatePasswordChangedEmail from '@main12/auth-login/rsc'
+- Override each to use my brand colors (primary: <COLOR>, accent: <COLOR>)
+- Change the welcome email CTA text to "<CUSTOM_TEXT>"
+- Change the OTP email purpose text to "<CUSTOM_TEXT>"
+- Add my project's social media links to the footer
+```
 
 ---
 
 ## Dev Testing
 
-This repo ships with a dev harness. To test locally:
-
 ```bash
+git clone https://github.com/MAIN-12/auth-login-plugin.git
 cd auth-login-plugin
 pnpm install
 pnpm dev
 ```
 
-Visits:
-- `http://localhost:3000/login` — multi-step login
-- `http://localhost:3000/signup` — create account
-- `http://localhost:3000/forgot-password` — password reset
-- `http://localhost:3000/admin` — Payload admin panel
-
-The dev config uses SQLite (no external DB needed) with a Users collection pre-configured.
+Visit `http://localhost:3000/login` — all 5 auth pages wired with SQLite.
 
 ---
 

package/dist/components/AuthLayout.d.ts

@@ -1,6 +1,7 @@
 import React from 'react';
 export interface AuthLayoutConfig {
-    logo: React.ReactNode;
+    /** Logo as a React node. Falls back to pluginConfig.logoUrl if not provided. */
+    logo?: React.ReactNode;
     title?: string;
     subtitle?: string;
     poweredBy?: {

package/dist/components/AuthLayout.js

@@ -3,7 +3,19 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from 'react';
 import { Card, CardContent, CardFooter } from './ui/index.js';
 import { PoweredBy } from './PoweredBy.js';
+import { pluginConfig } from '../config.js';
+function DefaultLogo() {
+    if (!pluginConfig.logoUrl) return null;
+    return /*#__PURE__*/ _jsx("img", {
+        src: pluginConfig.logoUrl,
+        alt: "",
+        width: 180,
+        height: 42,
+        className: "object-contain"
+    });
+}
 export const AuthLayout = ({ children, logo, title, subtitle, footer, poweredBy, cardClassName = '', backgroundClass = 'bg-white md:bg-[#191919]' })=>{
+    const displayLogo = logo || /*#__PURE__*/ _jsx(DefaultLogo, {});
     return /*#__PURE__*/ _jsx("main", {
         className: `flex flex-col min-h-screen ${backgroundClass}`,
         children: /*#__PURE__*/ _jsx("div", {
@@ -14,12 +26,12 @@ export const AuthLayout = ({ children, logo, title, subtitle, footer, poweredBy,
                     /*#__PURE__*/ _jsxs(Card, {
                         className: cardClassName,
                         children: [
-                            (logo || title) && /*#__PURE__*/ _jsxs("div", {
+                            (displayLogo || title) && /*#__PURE__*/ _jsxs("div", {
                                 className: "flex flex-col items-center gap-2 pt-6 pb-2 px-6",
                                 children: [
-                                    logo && /*#__PURE__*/ _jsx("div", {
+                                    displayLogo && /*#__PURE__*/ _jsx("div", {
                                         className: "flex justify-center mb-2",
-                                        children: logo
+                                        children: displayLogo
                                     }),
                                     title && /*#__PURE__*/ _jsx("h1", {
                                         className: "text-xl font-semibold text-gray-900 text-center",

package/dist/config.d.ts

@@ -5,4 +5,5 @@
 export type AuthStyle = 'tailwind' | 'hero-ui';
 export declare const pluginConfig: {
     style: AuthStyle;
+    logoUrl?: string;
 };

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export interface AuthLoginPluginOptions {
     domain?: string;
     /** UI style for auth pages: 'tailwind' (default) or 'hero-ui' */
     style?: AuthStyle;
+    /** Logo shown in all auth pages and email headers. Can be a URL string. */
+    logo?: string;
 }
 export declare const authLoginPlugin: (options?: AuthLoginPluginOptions) => (config: Config) => Config;
 export { pluginConfig };

package/dist/index.js

@@ -4,6 +4,7 @@ export const authLoginPlugin = (options = {})=>(config)=>{
         if (options.enabled === false) return config;
         // Set global style config — all page components read this at render time
         pluginConfig.style = options.style || 'tailwind';
+        pluginConfig.logoUrl = options.logo;
         // Register auth API endpoints
         config.endpoints = [
             ...config.endpoints || [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@main12/auth-login",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Reusable Payload CMS auth plugin — login, signup, OTP, forgot password, branded emails, Powered by Main12",
   "license": "MIT",
   "type": "module",