@main12/auth-login 0.1.1 → 0.1.3

package/README.md

@@ -1,218 +1,320 @@
-# Payload Plugin Template
+# @main12/auth-login
 
-A template repo to create a [Payload CMS](https://payloadcms.com) plugin.
+**Payload CMS authentication plugin** — login, signup, OTP, forgot password, branded emails, and "Powered by Main 12" footer. Install once, done.
 
-Payload is built with a robust infrastructure intended to support Plugins with ease. This provides a simple, modular, and reusable way for developers to extend the core capabilities of Payload.
-
-To build your own Payload plugin, all you need is:
+```ts
+// payload.config.ts
+import { authLoginPlugin } from '@main12/auth-login'
 
-- An understanding of the basic Payload concepts
-- And some JavaScript/Typescript experience
+plugins: [
+  authLoginPlugin({
+    projectName: 'My SaaS',
+    domain: 'https://myapp.com',
+    logo: 'https://myapp.com/logo.png',  // shown in all auth pages + emails
+    style: 'hero-ui',                     // 'tailwind' (default) | 'hero-ui'
+  }),
+]
+```
 
-## Background
+---
 
-Here is a short recap on how to integrate plugins with Payload, to learn more visit the [plugin overview page](https://payloadcms.com/docs/plugins/overview).
+## Features
 
-### How to install a plugin
+- **5 auth pages** — login (multi-step), signup, forgot password, verify OTP, set password
+- **Multi-style** — `tailwind` (zero UI deps) or `hero-ui` (HeroUI + framer-motion). Set once in config
+- **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 (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
 
-To install any plugin, simply add it to your payload.config() in the Plugin array.
+---
 
-```ts
-import myPlugin from 'my-plugin'
+## Installation
 
-export const config = buildConfig({
-  plugins: [
-    // You can pass options to the plugin
-    myPlugin({
-      enabled: true,
-    }),
-  ],
-})
+```bash
+pnpm add @main12/auth-login
 ```
 
-### Initialization
-
-The initialization process goes in the following order:
+### Tailwind mode (default, zero UI deps — also ShadCN compatible)
 
-1. Incoming config is validated
-2. **Plugins execute**
-3. Default options are integrated
-4. Sanitization cleans and validates data
-5. Final config gets initialized
+No extra dependencies needed. The Tailwind style uses standard utility classes that work in any Tailwind project, including ShadCN-based ones.
 
-## Building the Plugin
+### HeroUI mode
 
-When you build a plugin, you are purely building a feature for your project and then abstracting it outside of the project.
-
-### Template Files
+```bash
+pnpm add @heroui/react framer-motion @iconify/react
+```
 
-In the Payload [plugin template](https://github.com/payloadcms/payload/tree/main/templates/plugin), you will see a common file structure that is used across all plugins:
+---
 
-1. root folder
-2. /src folder
-3. /dev folder
+## Quick Start
 
-#### Root
+### 1. Add the plugin + Users collection to your Payload config
 
-In the root folder, you will see various files that relate to the configuration of the plugin. We set up our environment in a similar manner in Payload core and across other projects, so hopefully these will look familiar:
+```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' },
+        // OTP fields required by the plugin:
+        { 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',
+      logo: '/logo.png',          // shown automatically on all auth pages
+      style: 'hero-ui',           // or 'tailwind'
+    }),
+  ],
+})
+```
 
-- **README**.md\* - This contains instructions on how to use the template. When you are ready, update this to contain instructions on how to use your Plugin.
-- **package**.json\* - Contains necessary scripts and dependencies. Overwrite the metadata in this file to describe your Plugin.
-- .**eslint**.config.js - Eslint configuration for reporting on problematic patterns.
-- .**gitignore** - List specific untracked files to omit from Git.
-- .**prettierrc**.json - Configuration for Prettier code formatting.
-- **tsconfig**.json - Configures the compiler options for TypeScript
-- .**swcrc** - Configuration for SWC, a fast compiler that transpiles and bundles TypeScript.
-- **vitest**.config.js - Config file for Vitest, defining how tests are run and how modules are resolved
+### 2. Add auth pages to your app
 
-**IMPORTANT\***: You will need to modify these files.
+Create one-line route files under `src/app/(frontend)/(auth)/`:
 
-#### Dev
+```tsx
+// login/page.tsx
+export { LoginPage as default } from '@main12/auth-login/client'
 
-In the dev folder, you’ll find a basic payload project, created with `npx create-payload-app` and the blank template.
+// signup/page.tsx
+export { SignupPage as default } from '@main12/auth-login/client'
 
-**IMPORTANT**: Make a copy of the `.env.example` file and rename it to `.env`. Update the `DATABASE_URL` to match the database you are using and your plugin name. Update `PAYLOAD_SECRET` to a unique string.
-**You will not be able to run `pnpm/yarn dev` until you have created this `.env` file.**
+// forgot-password/page.tsx
+export { ForgotPasswordPage as default } from '@main12/auth-login/client'
 
-`myPlugin` has already been added to the `payload.config()` file in this project.
+// verify-otp/page.tsx
+export { VerifyOtpPage as default } from '@main12/auth-login/client'
 
-```ts
-plugins: [
-  myPlugin({
-    collections: {
-      posts: true,
-    },
-  }),
-]
+// set-password/page.tsx
+export { SetPasswordPage as default } from '@main12/auth-login/client'
 ```
 
-Later when you rename the plugin or add additional options, **make sure to update it here**.
+The logo is already handled — no need to pass it. The plugin reads it from the global config.
 
-You may wish to add collections or expand the test project depending on the purpose of your plugin. Just make sure to keep this dev environment as simplified as possible - users should be able to install your plugin without additional configuration required.
+### 3. Wire up the login action
 
-When you’re ready to start development, initiate the project with `pnpm/npm/yarn dev` and pull up [http://localhost:3000](http://localhost:3000) in your browser.
+```tsx
+// login/page.tsx — override with your Payload login function:
+'use client'
+import { LoginPage } from '@main12/auth-login/client'
+import { useAuth } from '@/providers/Auth'
 
-#### Src
+export default function Page() {
+  const { login } = useAuth()
+  return <LoginPage onPasswordLogin={login} redirectTo="/dashboard" />
+}
+```
 
-Now that we have our environment setup and we have a dev project ready to - it’s time to build the plugin!
+### 4. That's it — visit `/login`
 
-**index.ts**
+---
 
-The essence of a Payload plugin is simply to extend the payload config - and that is exactly what we are doing in this file.
+## Configuration Options
 
 ```ts
-export const myPlugin =
-  (pluginOptions: MyPluginConfig) =>
-  (config: Config): Config => {
-    // do cool stuff with the config here
-
-    return config
-  }
+authLoginPlugin({
+  // === Branding ===
+  projectName: 'My App',          // Used in email subjects and footers
+  contactEmail: 'hi@myapp.com',   // Email footer contact
+  domain: 'https://myapp.com',    // Links in emails
+  logo: '/logo.png',              // Shown on all auth pages + email headers
+
+  // === Style ===
+  style: 'tailwind',              // 'tailwind' (default) | 'hero-ui'
+
+  // === Enable/Disable ===
+  enabled: true,                  // Set false to disable the plugin
+})
 ```
 
-First, we receive the existing payload config along with any plugin options.
+### Per-page overrides
+
+Each page component also accepts these props for project-specific customization:
 
-From here, you can extend the config as you wish.
+```ts
+<LoginPage
+  logo={<AppLogo width={180} />}  // Override global logo (optional)
+  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.png',        // Override default Main12 logo
+    linkUrl: 'https://your-site.com',
+  }}
+/>
+```
 
-Finally, you return the config and that is it!
+---
 
-##### Spread Syntax
+## Building Custom Auth Pages
 
-Spread syntax (or the spread operator) is a feature in JavaScript that uses the dot notation **(...)** to spread elements from arrays, strings, or objects into various contexts.
+You can build your own UI while reusing the plugin's hooks, services, and endpoints.
 
-We are going to use spread syntax to allow us to add data to existing arrays without losing the existing data. It is crucial to spread the existing data correctly – else this can cause adverse behavior and conflicts with Payload config and other plugins.
+### Custom login with your own components
 
-Let’s say you want to build a plugin that adds a new collection:
+```tsx
+'use client'
+import { useLoginFlow } from '@main12/auth-login/client'
+import { Button, Input } from '@heroui/react' // or shadcn, or plain HTML
+import { useAuth } from '@/providers/Auth'
 
-```ts
-config.collections = [
-  ...(config.collections || []),
-  // Add additional collections here
-]
+export default function MyCustomLogin() {
+  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">
+      <div className="w-full max-w-md p-8 bg-white rounded-2xl shadow-xl">
+        {step === 'email' && (
+          <form onSubmit={handleEmailSubmit}>
+            <Input type="email" label="Email" value={email} onValueChange={setEmail} />
+            <Button type="submit" isLoading={isLoading}>Continue</Button>
+          </form>
+        )}
+        {step === 'password' && (
+          <form onSubmit={handlePasswordSubmit}>
+            <p>Signing in as {email} <button onClick={handleEditEmail}>Edit</button></p>
+            <Input type="password" label="Password" value={password} onValueChange={setPassword} />
+            <Button type="submit" isLoading={isLoading}>Sign In</Button>
+          </form>
+        )}
+        {step === 'otp-prompt' && (
+          <>
+            <p>{email} <button onClick={handleEditEmail}>Edit</button></p>
+            <Button onPress={handleSendOtp} isLoading={isLoading}>Send Code</Button>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}
 ```
 
-First we spread the `config.collections` to ensure that we don’t lose the existing collections, then you can add any additional collections just as you would in a regular payload config.
+### Custom email templates
 
-This same logic is applied to other properties like admin, hooks, globals:
+Override individual email translations or entire template functions:
 
 ```ts
-config.globals = [
-  ...(config.globals || []),
-  // Add additional globals here
-]
+import { getEmailTranslations } from '@main12/auth-login/rsc'
 
-config.hooks = {
-  ...(incomingConfig.hooks || {}),
-  // Add additional hooks here
+// Option 1: Deep-merge translations
+const myTranslations = getEmailTranslations('en')
+myTranslations.welcome.subject = 'Welcome to My SaaS! 🚀'
+myTranslations.otp.purposeLogin = 'Use this code to access your dashboard:'
+
+// Option 2: Import template generators and wrap them
+import { generateWelcomeEmail, generateOtpEmail } from '@main12/auth-login/rsc'
+
+function myWelcomeEmail(params) {
+  const base = generateWelcomeEmail(params)
+  return {
+    ...base,
+    html: base.html.replace('Get Started', 'Launch Dashboard'),
+  }
 }
+
+// Use in your Payload hooks or custom endpoints
+await payload.sendEmail({
+  to: user.email,
+  subject: myWelcomeEmail({ userName: user.name }).subject,
+  html: myWelcomeEmail({ userName: user.name }).html,
+})
 ```
 
-Some properties will be slightly different to extend, for instance the onInit property:
+---
 
-```ts
-import { onInitExtension } from './onInitExtension' // example file
+## Exported Hooks & Services
 
-config.onInit = async (payload) => {
-  if (incomingConfig.onInit) await incomingConfig.onInit(payload)
-  // Add additional onInit code by defining an onInitExtension function
-  onInitExtension(pluginOptions, payload)
-}
-```
+| Hook / Service | Type | Purpose |
+|---------------|------|---------|
+| `useLoginFlow` | Hook | Multi-step login state machine (email → password/OTP) |
+| `useVerifyOtpFlow` | Hook | OTP input, verify, resend with cooldown |
+| `useForgotPasswordFlow` | Hook | Email → check → send OTP |
+| `useSetPasswordFlow` | Hook | Set password with strength indicator |
+| `checkEmail(email)` | Service | Check if user exists and has password |
+| `sendOtp(email, purpose)` | Service | Send OTP to email |
+| `verifyOtp(email, otp)` | Service | Verify OTP code |
+| `setUserPassword(pw, confirm)` | Service | Set/update password |
+| `signup(name, email)` | Service | Create new user |
+| `initiateGoogleLogin(redirect)` | Service | Redirect to Google OAuth |
 
-If you wish to add to the onInit, you must include the **async/await**. We don’t use spread syntax in this case, instead you must await the existing `onInit` before running additional functionality.
+---
 
-In the template, we have stubbed out some addition `onInit` actions that seeds in a document to the `plugin-collection`, you can use this as a base point to add more actions - and if not needed, feel free to delete it.
+## API Endpoints
 
-##### Types.ts
+Registered automatically by the plugin:
 
-If your plugin has options, you should define and provide types for these options.
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/auth/check-email` | Check if email is registered |
+| 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 + send welcome email |
 
-```ts
-export type MyPluginConfig = {
-  /**
-   * List of collections to add a custom field
-   */
-  collections?: Partial<Record<CollectionSlug, true>>
-  /**
-   * Disable the plugin
-   */
-  disabled?: boolean
-}
-```
+---
 
-If possible, include JSDoc comments to describe the options and their types. This allows a developer to see details about the options in their editor.
+## ShadCN Compatibility
 
-##### Testing
+The `tailwind` style uses standard Tailwind utility classes — it works in ShadCN projects out of the box. If you want ShadCN components instead of plain HTML:
 
-Having a test suite for your plugin is essential to ensure quality and stability. **Vitest** is a fast, modern testing framework that works seamlessly with Vite and supports TypeScript out of the box.
+1. Follow the [Custom Auth Pages](#building-custom-auth-pages) guide above
+2. Import `useLoginFlow`, `useVerifyOtpFlow`, etc. from the plugin
+3. Use your ShadCN `<Button>`, `<Input>`, `<Card>` components with the same hook values
 
-Vitest organizes tests into test suites and cases, similar to other testing frameworks. We recommend creating individual tests based on the expected behavior of your plugin from start to finish.
+No need for a separate `style: 'shadcn'` — the Tailwind style already renders compatible markup, and custom pages give you full ShadCN component control.
 
-Writing tests with Vitest is very straightforward, and you can learn more about how it works in the [Vitest documentation.](https://vitest.dev/)
+---
 
-For this template, we stubbed out `int.spec.ts` in the `dev` folder where you can write your tests.
+## Dev Testing
 
-```ts
-describe('Plugin tests', () => {
-  // Create tests to ensure expected behavior from the plugin
-  it('some condition that must be met', () => {
-   // Write your test logic here
-   expect(...)
-  })
-})
+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
 ```
 
-## Best practices
+Visit `http://localhost:3000/login` — all 5 auth pages wired with SQLite.
+
+---
+
+## Requirements
 
-With this tutorial and the plugin template, you should have everything you need to start building your own plugin.
-In addition to the setup, here are other best practices aim we follow:
+| Dependency | Version | Required |
+|------------|---------|----------|
+| Payload CMS | `^3.82.0` | ✅ |
+| Next.js | `^16.0.0` | ✅ |
+| React | `^19.0.0` | ✅ |
+| HeroUI | `^2.x` | Only for `style: 'hero-ui'` |
+| Framer Motion | `^12.x` | Only for `style: 'hero-ui'` |
 
-- **Providing an enable / disable option:** For a better user experience, provide a way to disable the plugin without uninstalling it. This is especially important if your plugin adds additional webpack aliases, this will allow you to still let the webpack run to prevent errors.
-- **Include tests in your GitHub CI workflow**: If you’ve configured tests for your package, integrate them into your workflow to run the tests each time you commit to the plugin repository. Learn more about [how to configure tests into your GitHub CI workflow.](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs)
-- **Publish your finished plugin to NPM**: The best way to share and allow others to use your plugin once it is complete is to publish an NPM package. This process is straightforward and well documented, find out more [creating and publishing a NPM package here.](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/).
-- **Add payload-plugin topic tag**: Apply the tag **payload-plugin **to your GitHub repository. This will boost the visibility of your plugin and ensure it gets listed with [existing payload plugins](https://github.com/topics/payload-plugin).
-- **Use [Semantic Versioning](https://semver.org/) (SemVar)** - With the SemVar system you release version numbers that reflect the nature of changes (major, minor, patch). Ensure all major versions reference their Payload compatibility.
+---
 
-# Questions
+## License
 
-Please contact [Payload](mailto:dev@payloadcms.com) with any questions about using this plugin template.
+MIT © Main 12

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.1",
+  "version": "0.1.3",
   "description": "Reusable Payload CMS auth plugin — login, signup, OTP, forgot password, branded emails, Powered by Main12",
   "license": "MIT",
   "type": "module",