@amirulabu/create-recurring-rabbit-app 0.0.0-alpha

package/templates/default/src/components/ui/input.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {}
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, ...props }, ref) => {
+    return (
+      <input
+        type={type}
+        className={cn(
+          'flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Input.displayName = 'Input'
+
+export { Input }

package/templates/default/src/lib/api.ts

@@ -0,0 +1,42 @@
+/**
+ * tRPC client configuration module for @trpc/tanstack-react-query v11.
+ *
+ * This module sets up tRPC React client for type-safe API communication between
+ * frontend and backend. tRPC provides end-to-end type safety without requiring
+ * separate API contracts or code generation steps.
+ *
+ * Key patterns and conventions:
+ * - Use `useTRPC()` hook to get the tRPC proxy in components
+ * - Use `useQuery(trpc.procedure.queryOptions({ input }))` for queries
+ * - Use `useMutation(trpc.procedure.mutationOptions())` for mutations
+ * - Type definitions are inferred from backend AppRouter
+ * - Uses TanStack React Query under the hood for caching and deduplication
+ *
+ * @example
+ * // Query usage in a component
+ * function Dashboard() {
+ *   const trpc = useTRPC()
+ *   const { data: stats } = useQuery(trpc.dashboard.getStats.queryOptions())
+ *   return <div>{stats?.totalUsers}</div>
+ * }
+ *
+ * @example
+ * // Mutation usage in a component
+ * function ProfileSettings() {
+ *   const trpc = useTRPC()
+ *   const { data: user } = useQuery(trpc.user.getProfile.queryOptions())
+ *   const updateProfile = useMutation(trpc.user.updateProfile.mutationOptions())
+ *
+ *   const handleSubmit = async () => {
+ *     await updateProfile.mutateAsync({ name: 'New Name' })
+ *   }
+ *   return <form onSubmit={handleSubmit}>...</form>
+ * }
+ */
+
+import { createTRPCContext } from '@trpc/tanstack-react-query'
+import type { AppRouter } from '@/server/api/root'
+
+export const { TRPCProvider, useTRPC, useTRPCClient } =
+  createTRPCContext<AppRouter>()
+export type { AppRouter }

package/templates/default/src/lib/auth.ts

@@ -0,0 +1,292 @@
+/**
+ * Client-Side Authentication Module
+ *
+ * This module provides the React hooks and client functions for authentication
+ * operations in the browser. It communicates with the server-side auth API
+ * to handle user sessions, sign in, sign out, and password recovery.
+ *
+ * KEY AUTHENTICATION FLOWS:
+ * 1. Sign In - Authenticate with credentials (email/password or OAuth)
+ * 2. Sign Up - Create new user account
+ * 3. Sign Out - Terminate current session
+ * 4. Session Management - Query and react to session state changes
+ * 5. Password Recovery - Request and complete password reset
+ *
+ * SECURITY CONSIDERATIONS:
+ * - All authentication requests go through the server (never directly to database)
+ * - Session tokens are stored in HTTP-only cookies (inaccessible to JavaScript)
+ * - Client only maintains session state, never raw credentials
+ * - Session state is reactive and automatically updates from server
+ * - SSR (Server-Side Rendering) safe: checks window object before accessing browser APIs
+ *
+ * SSR/SSG COMPATIBILITY:
+ * - Checks for window object before accessing browser-only APIs
+ * - Falls back to PUBLIC_APP_URL for server-side rendering
+ * - Default to localhost:3000 for development
+ */
+
+import { createAuthClient } from 'better-auth/react'
+
+/**
+ * Authentication client instance configured for the application.
+ *
+ * This client is the main entry point for all client-side authentication operations.
+ * It's initialized with the appropriate base URL depending on whether it's running
+ * in the browser or on the server (for SSR).
+ *
+ * BASE URL RESOLUTION:
+ * 1. Browser context: Uses window.location.origin (current domain)
+ * 2. Server context (SSR): Uses PUBLIC_APP_URL environment variable
+ * 3. Fallback: Uses localhost:3000 for local development
+ *
+ * SECURITY:
+ * - Base URL must match the server auth endpoint to prevent origin errors
+ * - In production, ensure PUBLIC_APP_URL is set correctly
+ *
+ * @example
+ * ```tsx
+ * import { authClient } from '@/lib/auth'
+ *
+ * // Sign in with email and password
+ * const result = await authClient.signIn.email({
+ *   email: 'user@example.com',
+ *   password: 'password123'
+ * })
+ * ```
+ */
+export const authClient = createAuthClient({
+  /**
+   * Base URL for authentication API endpoints.
+   *
+   * Dynamically determined based on execution context:
+   * - Browser: Current origin (domain + protocol + port)
+   * - Server: PUBLIC_APP_URL environment variable
+   * - Fallback: http://localhost:3000
+   *
+   * SECURITY: Must match the actual auth server URL. Mismatched origins
+   * will cause CORS errors and prevent authentication from working.
+   */
+  baseURL:
+    typeof window !== 'undefined'
+      ? window.location.origin
+      : process.env.PUBLIC_APP_URL || 'http://localhost:3000',
+})
+
+/**
+ * Destructured authentication client methods for easier imports.
+ *
+ * These functions and hooks provide the primary authentication interface
+ * for React components. Each method is typed and ready to use throughout
+ * the application.
+ *
+ * EXPORTED METHODS:
+ * - signIn: General sign-in function (supports OAuth and other providers)
+ * - signUp: Create new user account
+ * - signOut: Terminate current user session
+ * - useSession: React hook for accessing session state
+ * - signInEmail: Sign in specifically with email/password
+ * - signUpEmail: Create account with email/password
+ * - forgotPassword: Request password reset email
+ * - resetPassword: Complete password reset with token
+ */
+
+/**
+ * Sign in with credentials.
+ *
+ * Authenticates a user with email/password or OAuth providers.
+ *
+ * @param credentials - User credentials (email, password, provider)
+ * @returns Promise resolving to session data and user object
+ *
+ * SECURITY:
+ * - Credentials are sent over HTTPS in production
+ * - Server validates credentials before creating session
+ * - Session token stored in HTTP-only cookie after success
+ *
+ * @example
+ * ```tsx
+ * const { data, error } = await signIn({
+ *   email: 'user@example.com',
+ *   password: 'password123'
+ * })
+ * ```
+ */
+export const { signIn } = authClient
+
+/**
+ * Sign up new user account.
+ *
+ * Creates a new user account with the provided credentials.
+ * Email verification is required before sign in is allowed.
+ *
+ * @param credentials - Registration credentials (email, password)
+ * @returns Promise resolving to created user data
+ *
+ * SECURITY:
+ * - Password is hashed on the server before storage
+ * - Email verification required prevents spam accounts
+ * - Same password rules apply as sign-in
+ *
+ * @example
+ * ```tsx
+ * const { data, error } = await signUp({
+ *   email: 'user@example.com',
+ *   password: 'securePassword123'
+ * })
+ * ```
+ */
+export const { signUp } = authClient
+
+/**
+ * Sign out current user.
+ *
+ * Terminates the current user session and clears authentication state.
+ *
+ * @returns Promise resolving when sign out is complete
+ *
+ * SECURITY:
+ * - Invalidates session token on server
+ * - Clears session cookie
+ * - All subsequent requests will be unauthenticated
+ *
+ * @example
+ * ```tsx
+ * await signOut()
+ * // User is now signed out
+ * ```
+ */
+export const { signOut } = authClient
+
+/**
+ * React hook for accessing session state.
+ *
+ * Provides reactive access to the current user's session and user data.
+ * Automatically updates when session changes (sign in, sign out, expiry).
+ *
+ * @returns Object containing:
+ *   - data: Current session and user data (null if not authenticated)
+ *   - error: Error object if session check failed
+ *   - isLoading: Boolean indicating if session is being fetched
+ *   - isPending: Boolean indicating if session is being refreshed
+ *
+ * SECURITY:
+ * - Only exposes non-sensitive user data
+ * - Automatically handles session expiry
+ * - Safe to call from any component
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const { data: session, isLoading } = useSession()
+ *
+ *   if (isLoading) return <LoadingSpinner />
+ *   if (!session) return <SignInButton />
+ *
+ *   return <div>Welcome, {session.user.name}</div>
+ * }
+ * ```
+ */
+export const { useSession } = authClient
+
+/**
+ * Sign in with email and password.
+ *
+ * In better-auth v1.0.0+, signIn is an object with provider-specific
+ * methods. Use signIn.email() for email/password authentication.
+ *
+ * @param credentials - Object containing email and password
+ * @returns Promise resolving to session data
+ *
+ * SECURITY:
+ * - Validates email format and password strength on server
+ * - Rate limiting prevents brute force attacks
+ * - Failed attempts are logged for security monitoring
+ *
+ * @example
+ * ```tsx
+ * const { data, error } = await authClient.signIn.email({
+ *   email: 'user@example.com',
+ *   password: 'password123'
+ * })
+ * ```
+ */
+// Note: signIn.email() is the method for email/password auth
+// Example usage: await authClient.signIn.email({ email, password })
+
+/**
+ * Sign up with email and password.
+ *
+ * In better-auth v1.0.0+, signUp is an object with provider-specific
+ * methods. Use signUp.email() for email/password registration.
+ *
+ * @param credentials - Object containing email, password, and name
+ * @returns Promise resolving to created user data
+ *
+ * SECURITY:
+ * - Password must meet strength requirements
+ * - Email is sent to verify ownership
+ * - User cannot sign in until email is verified
+ *
+ * @example
+ * ```tsx
+ * const { data, error } = await authClient.signUp.email({
+ *   email: 'user@example.com',
+ *   password: 'securePassword123',
+ *   name: 'John Doe'
+ * })
+ * // Email verification required before sign-in
+ * ```
+ */
+// Note: signUp.email() is the method for email/password registration
+// Example usage: await authClient.signUp.email({ email, password, name })
+
+/**
+ * Request password reset email.
+ *
+ * Initiates password reset flow by sending a reset link to user's email.
+ * The link contains a single-use token that expires after a set time.
+ *
+ * @param email - User's registered email address
+ * @returns Promise resolving when email is sent
+ *
+ * SECURITY:
+ * - Only reveals if email exists in timing-attack-resistant way
+ * - Reset link is single-use and time-limited
+ * - Old password remains valid until reset is completed
+ *
+ * @example
+ * ```tsx
+ * const { data, error } = await authClient.forgetPassword({
+ *   email: 'user@example.com'
+ * })
+ * // Email sent with reset link
+ * ```
+ */
+// Note: forgetPassword() is the method for password reset (not forgotPassword)
+// Example usage: await authClient.forgetPassword({ email })
+
+/**
+ * Complete password reset.
+ *
+ * Finalizes the password reset process using the token sent to the user's email.
+ *
+ * @param resetData - Object containing newPassword and the reset token
+ * @returns Promise resolving when password is reset
+ *
+ * SECURITY:
+ * - Token is validated against server records
+ * - Token is single-use and expires automatically
+ * - Old password is immediately invalidated
+ * - New password must meet strength requirements
+ *
+ * @example
+ * ```tsx
+ * const { data, error } = await resetPassword({
+ *   newPassword: 'newSecurePassword123',
+ *   token: 'reset-token-from-email'
+ * })
+ * // User can now sign in with new password
+ * ```
+ */
+// Note: resetPassword() completes the password reset flow
+// Example usage: await authClient.resetPassword({ newPassword, token })

package/templates/default/src/lib/email.ts

@@ -0,0 +1,221 @@
+/**
+ * Email sending module using Resend API.
+ *
+ * This module provides functions to send transactional emails for user authentication
+ * flows including email verification and password reset. It uses the Resend service
+ * for reliable email delivery with built-in bounce handling and analytics.
+ *
+ * Key patterns and conventions:
+ * - All email sending is async and non-blocking for the main application flow
+ * - Errors are logged but don't expose detailed error messages to users
+ * (to prevent information leakage about email infrastructure)
+ * - HTML emails use inline styles for maximum client compatibility
+ * - Responsive design with max-width 600px for optimal mobile rendering
+ * - Verification/reset links are included both as buttons and plain text URLs
+ * to handle cases where buttons are blocked by email clients
+ *
+ * Security considerations:
+ * - RESEND_API_KEY is loaded from environment and never exposed to client
+ * - Email content is HTML-escaped by template literals to prevent XSS
+ * - Verification and reset URLs should be generated server-side with
+ * short-lived tokens (24 hours for verification, 1 hour for password reset)
+ * - From address uses noreply@yourdomain.com to prevent confusion
+ * - No user data beyond what's necessary is included in emails
+ * - Rate limiting should be implemented at the route level to prevent email spam
+ *
+ * Configuration decisions:
+ * - Short token expiration times (24h for verify, 1h for reset) balance security
+ *   with user experience. Password reset tokens expire faster because they grant
+ *   access to accounts.
+ * - Inline CSS styles instead of external stylesheets because many email clients
+ *   block external stylesheets and the <style> tag
+ * - System font stack (Arial, sans-serif) for best rendering across all clients
+ * without loading external fonts
+ * - 600px max-width is industry standard for email newsletters and ensures good
+ *   readability on both desktop and mobile devices
+ * - Blue (#0070f3) is used for CTA buttons as it has high contrast and is
+ *   commonly recognized as an interactive element color
+ *
+ * Performance implications:
+ * - Email sending is I/O-bound and can take 200-1000ms per email
+ * - These functions should be called after database operations complete,
+ *   so email failures don't prevent user actions
+ * - Consider using a queue system for high-volume email sending to avoid blocking
+ * - Errors are caught and re-thrown with generic messages to prevent information
+ * leakage while still allowing upstream handlers to take action
+ *
+ * Error handling strategy:
+ * - Errors are logged with context for debugging
+ * - Generic error messages are thrown to prevent exposing email service details
+ * - This allows the calling code to show user-friendly messages while
+ *   maintaining security
+ *
+ * @example
+ * // Send verification email after user registration
+ * await sendVerificationEmail('user@example.com', 'https://app.com/verify/abc123')
+ *
+ * @example
+ * // Send password reset email after request
+ * await sendPasswordResetEmail('user@example.com', 'https://app.com/reset/xyz789')
+ */
+
+import { Resend } from 'resend'
+import { env } from '@/lib/env'
+
+/**
+ * Resend API client instance.
+ *
+ * Initialized with the RESEND_API_KEY from environment variables.
+ * This instance is reused across all email sending operations to maintain
+ * a single connection and avoid multiple initializations.
+ */
+const resend = new Resend(env.RESEND_API_KEY)
+
+/**
+ * Sends a verification email to a newly registered user.
+ *
+ * This function sends an HTML email with a verification link that the user must
+ * click to confirm their email address. The link should be generated by the
+ * backend with a short-lived token (typically 24 hours).
+ *
+ * Performance characteristics:
+ * - Network latency: 200-1000ms typically
+ * - Non-blocking: Should be called after database write completes
+ * - No retry logic: Resend handles retries internally
+ *
+ * Security implications:
+ * - Verification URL should contain a cryptographically signed token
+ * - Token should expire after 24 hours to limit window for exploitation
+ * - Email content contains no sensitive data beyond the verification URL
+ * - URL is truncated in display to prevent layout issues with long URLs
+ *
+ * @param email - The recipient's email address. Should be validated before calling.
+ * @param verificationUrl - The full URL the user must click to verify their email.
+ *                          Should include a token with expiration.
+ *                          Example: https://app.com/verify/abc123token
+ * @returns Promise that resolves when email is sent successfully.
+ * @throws {Error} If email sending fails (network error, API error, etc.).
+ *                  Error message is generic to prevent information leakage.
+ *
+ * @example
+ * try {
+ *   await sendVerificationEmail('user@example.com', 'https://app.com/verify/token123')
+ *   console.log('Verification email sent')
+ * } catch (error) {
+ *   console.error('Failed to send verification email')
+ *   // Show user-friendly message: "Email sent. Please check your inbox."
+ * }
+ */
+export async function sendVerificationEmail(
+  email: string,
+  verificationUrl: string
+) {
+  try {
+    await resend.emails.send({
+      from: 'noreply@yourdomain.com',
+      to: email,
+      subject: 'Verify your email address',
+      html: `
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title>Verify Your Email</title>
+        </head>
+        <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
+          <div style="background: #f4f4f4; padding: 30px; border-radius: 8px;">
+            <h1 style="color: #333; margin-bottom: 20px;">Welcome!</h1>
+            <p style="margin-bottom: 20px;">Thank you for signing up. Please click the button below to verify your email address:</p>
+            <div style="text-align: center; margin: 30px 0;">
+              <a href="${verificationUrl}" style="display: inline-block; padding: 12px 30px; background: #0070f3; color: #fff; text-decoration: none; border-radius: 5px; font-weight: bold;">Verify Email</a>
+            </div>
+            <p style="color: #666; font-size: 14px;">If the button doesn't work, you can copy and paste this link into your browser:</p>
+            <p style="color: #666; font-size: 12px; word-break: break-all;">${verificationUrl}</p>
+            <p style="margin-top: 30px; color: #999; font-size: 12px;">This link will expire in 24 hours.</p>
+          </div>
+        </body>
+        </html>
+      `,
+    })
+  } catch (error) {
+    console.error('Failed to send verification email:', error)
+    throw new Error('Failed to send verification email')
+  }
+}
+
+/**
+ * Sends a password reset email to a user who requested a password reset.
+ *
+ * This function sends an HTML email with a password reset link. The link should be
+ * generated by the backend with a short-lived token (typically 1 hour) to limit
+ * the window for potential account takeover attempts.
+ *
+ * Performance characteristics:
+ * - Network latency: 200-1000ms typically
+ * - Non-blocking: Should be called after database write completes
+ * - No retry logic: Resend handles retries internally
+ *
+ * Security implications:
+ * - Reset URL should contain a cryptographically signed token
+ * - Token should expire after 1 hour to limit account takeover window
+ * - Email confirms that a reset was requested (prevents silent resets)
+ * - If the user didn't request a reset, this serves as an early warning
+ *   of potential unauthorized access attempts
+ * - No account details are revealed to prevent email enumeration attacks
+ *   (email is sent even if the account doesn't exist in production)
+ *
+ * @param email - The recipient's email address. May not exist in the system.
+ *                In production, send even for non-existent accounts to prevent
+ *                email enumeration attacks.
+ * @param resetUrl - The full URL the user must click to reset their password.
+ *                   Should include a token with short expiration (1 hour recommended).
+ *                   Example: https://app.com/reset/xyz789token
+ * @returns Promise that resolves when email is sent successfully.
+ * @throws {Error} If email sending fails (network error, API error, etc.).
+ *                  Error message is generic to prevent information leakage.
+ *
+ * @example
+ * try {
+ *   await sendPasswordResetEmail('user@example.com', 'https://app.com/reset/token456')
+ *   console.log('Password reset email sent')
+ * } catch (error) {
+ *   console.error('Failed to send password reset email')
+ *   // Show user-friendly message: "If an account exists with this email,
+ *   // you will receive a password reset link."
+ * }
+ */
+export async function sendPasswordResetEmail(email: string, resetUrl: string) {
+  try {
+    await resend.emails.send({
+      from: 'noreply@yourdomain.com',
+      to: email,
+      subject: 'Reset Your Password',
+      html: `
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title>Reset Your Password</title>
+        </head>
+        <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
+          <div style="background: #f4f4f4; padding: 30px; border-radius: 8px;">
+            <h1 style="color: #333; margin-bottom: 20px;">Reset Password</h1>
+            <p style="margin-bottom: 20px;">We received a request to reset your password. Click the button below to set a new password:</p>
+            <div style="text-align: center; margin: 30px 0;">
+              <a href="${resetUrl}" style="display: inline-block; padding: 12px 30px; background: #0070f3; color: #fff; text-decoration: none; border-radius: 5px; font-weight: bold;">Reset Password</a>
+            </div>
+            <p style="color: #666; font-size: 14px;">If the button doesn't work, you can copy and paste this link into your browser:</p>
+            <p style="color: #666; font-size: 12px; word-break: break-all;">${resetUrl}</p>
+            <p style="margin-top: 30px; color: #999; font-size: 12px;">This link will expire in 1 hour. If you didn't request a password reset, you can safely ignore this email.</p>
+          </div>
+        </body>
+        </html>
+      `,
+    })
+  } catch (error) {
+    console.error('Failed to send password reset email:', error)
+    throw new Error('Failed to send password reset email')
+  }
+}