create-nextdevtpl 2.6.0

package/template/src/lib/auth/index.ts

@@ -0,0 +1,159 @@
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+
+import { db } from "@/db";
+import * as schema from "@/db/schema/auth";
+import {
+  ResetPasswordEmail,
+  VerifyEmailEmail,
+  sendEmail,
+} from "@/features/mail/server";
+import { isMailServiceConfigured } from "@/services/mail";
+
+const isEmailConfigured = isMailServiceConfigured();
+
+/**
+ * Better Auth 服务端配置
+ *
+ * 此文件配置 Better Auth 的核心功能:
+ * - 数据库适配器 (Drizzle + PostgreSQL)
+ * - OAuth 提供商 (GitHub, Google)
+ * - 会话配置
+ * - 用户自定义字段
+ */
+export const auth = betterAuth({
+  /**
+   * 基础 URL 配置
+   * 用于 OAuth 回调和邮件链接
+   */
+  baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000",
+
+  /**
+   * 信任的来源
+   * 允许从这些来源发起认证请求
+   */
+  trustedOrigins: [process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000"],
+
+  /**
+   * 数据库配置
+   * 使用 Drizzle 适配器连接 PostgreSQL
+   */
+  database: drizzleAdapter(db, {
+    provider: "pg",
+    schema: {
+      user: schema.user,
+      session: schema.session,
+      account: schema.account,
+      verification: schema.verification,
+    },
+  }),
+
+  /**
+   * 用户自定义字段配置
+   * 将 role, banned, bannedReason 字段包含在会话用户中
+   */
+  user: {
+    additionalFields: {
+      role: {
+        type: "string",
+        required: false,
+        defaultValue: "user",
+        input: false, // 用户不能通过注册/更新设置此字段
+      },
+      banned: {
+        type: "boolean",
+        required: false,
+        defaultValue: false,
+        input: false, // 用户不能通过注册/更新设置此字段
+      },
+      bannedReason: {
+        type: "string",
+        required: false,
+        input: false, // 用户不能通过注册/更新设置此字段
+      },
+    },
+  },
+
+  /**
+   * 邮箱密码认证配置
+   */
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: isEmailConfigured,
+    sendResetPassword: async ({ user, url }) => {
+      await sendEmail({
+        to: user.email,
+        subject: "Reset your password - NextDevTpl",
+        react: ResetPasswordEmail({
+          resetUrl: url,
+          name: user.name || "there",
+        }),
+      });
+    },
+  },
+
+  /**
+   * 邮箱验证配置
+   */
+  ...(isEmailConfigured
+    ? {
+        emailVerification: {
+          sendOnSignUp: true,
+          sendVerificationEmail: async ({ user, url }) => {
+            await sendEmail({
+              to: user.email,
+              subject: "Verify your email - NextDevTpl",
+              react: VerifyEmailEmail({
+                verifyUrl: url,
+                name: user.name || "there",
+              }),
+            });
+          },
+        },
+      }
+    : {}),
+
+  /**
+   * OAuth 社交登录提供商配置
+   * 需要在 .env 中配置相应的 Client ID 和 Secret
+   */
+  socialProviders: {
+    /**
+     * GitHub OAuth 配置
+     * 获取凭证: https://github.com/settings/developers
+     */
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID || "",
+      clientSecret: process.env.GITHUB_CLIENT_SECRET || "",
+    },
+
+    /**
+     * Google OAuth 配置
+     * 获取凭证: https://console.cloud.google.com/apis/credentials
+     */
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID || "",
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET || "",
+    },
+  },
+
+  /**
+   * 会话配置
+   */
+  session: {
+    // 会话过期时间: 7 天
+    expiresIn: 60 * 60 * 24 * 7,
+    // 刷新阈值: 1 天 (会话剩余不足 1 天时自动刷新)
+    updateAge: 60 * 60 * 24,
+    // 使用 Cookie 存储会话
+    cookieCache: {
+      enabled: true,
+      maxAge: 60 * 5, // 5 分钟缓存
+    },
+  },
+});
+
+/**
+ * 导出类型以供其他模块使用
+ */
+export type Auth = typeof auth;

package/template/src/lib/auth/server.ts

@@ -0,0 +1,46 @@
+import { headers } from "next/headers";
+
+import { auth } from "./index";
+
+/**
+ * 服务器端获取当前用户会话
+ *
+ * 用于 Server Components 和 Server Actions 中获取用户信息
+ *
+ * @example
+ * ```tsx
+ * // 在 Server Component 中使用
+ * export default async function Page() {
+ *   const session = await getServerSession();
+ *   if (!session) {
+ *     redirect("/sign-in");
+ *   }
+ *   return <div>Welcome, {session.user.name}</div>;
+ * }
+ * ```
+ */
+export async function getServerSession() {
+  return auth.api.getSession({
+    headers: await headers(),
+  });
+}
+
+/**
+ * 获取当前用户
+ *
+ * 便捷方法，直接返回用户对象或 null
+ */
+export async function getCurrentUser() {
+  const session = await getServerSession();
+  return session?.user ?? null;
+}
+
+/**
+ * 检查用户是否已认证
+ *
+ * @returns boolean - 用户是否已登录
+ */
+export async function isAuthenticated() {
+  const session = await getServerSession();
+  return !!session?.user;
+}

package/template/src/lib/auth/session-context.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { createContext, type ReactNode, useContext } from "react";
+
+import { useSession } from "./client";
+
+/**
+ * 会话用户类型
+ */
+interface SessionUser {
+  id: string;
+  name: string;
+  email: string;
+  image?: string | null | undefined;
+  emailVerified: boolean;
+}
+
+/**
+ * 会话上下文类型
+ */
+interface SessionContextType {
+  /** 当前用户，未登录时为 null */
+  user: SessionUser | null;
+  /** 是否正在加载会话 */
+  isLoading: boolean;
+  /** 是否已认证 */
+  isAuthenticated: boolean;
+}
+
+/**
+ * 会话上下文
+ */
+const SessionContext = createContext<SessionContextType | undefined>(undefined);
+
+/**
+ * 会话提供者组件
+ *
+ * 包裹应用根组件，提供全局会话状态
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { SessionProvider } from "@/lib/auth/session-context";
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <SessionProvider>{children}</SessionProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export function SessionProvider({ children }: { children: ReactNode }) {
+  const { data: session, isPending } = useSession();
+
+  const value: SessionContextType = {
+    user: session?.user ?? null,
+    isLoading: isPending,
+    isAuthenticated: !!session?.user,
+  };
+
+  return (
+    <SessionContext.Provider value={value}>{children}</SessionContext.Provider>
+  );
+}
+
+/**
+ * 使用会话上下文的 Hook
+ *
+ * @returns 会话上下文值
+ * @throws 如果在 SessionProvider 外部使用
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const { user, isLoading, isAuthenticated } = useSessionContext();
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (!isAuthenticated) return <LoginButton />;
+ *
+ *   return <div>Welcome, {user.name}</div>;
+ * }
+ * ```
+ */
+export function useSessionContext() {
+  const context = useContext(SessionContext);
+
+  if (context === undefined) {
+    throw new Error("useSessionContext 必须在 SessionProvider 内部使用");
+  }
+
+  return context;
+}

package/template/src/lib/cloudflare/bindings.ts

@@ -0,0 +1,31 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+function getBinding<T extends object>(bindingName: string): T {
+  const env = getCloudflareContext().env;
+  const binding: unknown = Reflect.get(env, bindingName);
+  if (typeof binding !== "object" || binding === null) {
+    throw new Error(`Cloudflare binding is not configured: ${bindingName}`);
+  }
+  return binding as T;
+}
+
+export function createLazyCloudflareBinding<T extends object>(
+  bindingName: string
+): T {
+  return new Proxy({} as T, {
+    get(_target, property) {
+      const binding = getBinding<T>(bindingName);
+      const value = Reflect.get(binding, property, binding) as unknown;
+      return typeof value === "function" ? value.bind(binding) : value;
+    },
+  });
+}
+
+export function createCloudflareBindingMap<T extends object>(
+  bindingName: string
+): Readonly<Record<string, T>> {
+  const binding = createLazyCloudflareBinding<T>(bindingName);
+  return new Proxy(Object.create(null) as Record<string, T>, {
+    get: () => binding,
+  });
+}

package/template/src/lib/cookie-consent.ts

@@ -0,0 +1,33 @@
+/**
+ * Cookie 同意相关常量
+ *
+ * 集中管理 Cookie 同意功能的常量，确保类型安全
+ */
+
+/**
+ * Cookie 同意类型
+ */
+export type CookieConsentType = "all" | "essential" | null;
+
+/**
+ * Cookie 偏好设置
+ */
+export interface CookiePreferences {
+  analytics: boolean;
+  marketing: boolean;
+}
+
+/**
+ * localStorage 存储键名
+ */
+export const COOKIE_CONSENT_KEY = "cookie-consent";
+
+/**
+ * Cookie 偏好存储键名
+ */
+export const COOKIE_PREFERENCES_KEY = "cookie-preferences";
+
+/**
+ * Cookie 同意变更事件名
+ */
+export const COOKIE_CONSENT_CHANGE_EVENT = "cookie-consent-change";

package/template/src/lib/file-utils.ts

@@ -0,0 +1,45 @@
+/**
+ * 支持的文件类型
+ */
+export type SupportedFileType = "pdf" | "docx" | "md" | "txt";
+
+/**
+ * 文件类型 MIME 映射
+ */
+export const FILE_MIME_TYPES: Record<string, SupportedFileType> = {
+  "application/pdf": "pdf",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document":
+    "docx",
+  "text/markdown": "md",
+  "text/plain": "txt",
+};
+
+/**
+ * 文件扩展名映射
+ */
+export const FILE_EXTENSIONS: Record<string, SupportedFileType> = {
+  ".pdf": "pdf",
+  ".docx": "docx",
+  ".md": "md",
+  ".txt": "txt",
+};
+
+/**
+ * 从文件名获取文件类型
+ */
+export function getFileTypeFromName(
+  filename: string
+): SupportedFileType | null {
+  const ext = filename.toLowerCase().match(/\.[^.]+$/)?.[0];
+  if (!ext) return null;
+  return FILE_EXTENSIONS[ext] || null;
+}
+
+/**
+ * 从 MIME 类型获取文件类型
+ */
+export function getFileTypeFromMime(
+  mimeType: string
+): SupportedFileType | null {
+  return FILE_MIME_TYPES[mimeType] || null;
+}

package/template/src/lib/fingerprint/index.ts

@@ -0,0 +1,73 @@
+"use client";
+
+import FingerprintJS, { type GetResult } from "@fingerprintjs/fingerprintjs";
+
+// Singleton promise for the fingerprint agent
+let fpPromise: Promise<GetResult> | null = null;
+
+/**
+ * Initialize and get the device fingerprint
+ *
+ * Uses FingerprintJS open source library to generate a visitor ID
+ * based on browser characteristics.
+ *
+ * @returns Promise resolving to the visitor ID string
+ */
+export async function getDeviceFingerprint(): Promise<string> {
+  if (typeof window === "undefined") {
+    return "";
+  }
+
+  try {
+    // Initialize the agent at application startup
+    if (!fpPromise) {
+      fpPromise = FingerprintJS.load().then((fp) => fp.get());
+    }
+
+    const result = await fpPromise;
+    return result.visitorId;
+  } catch (error) {
+    console.error("Failed to get device fingerprint:", error);
+    return "";
+  }
+}
+
+/**
+ * Get fingerprint and add it to request headers
+ *
+ * @param headers - Existing headers object to extend
+ * @returns Headers object with X-Device-Fingerprint added
+ */
+export async function addFingerprintHeader(
+  headers: Record<string, string> = {}
+): Promise<Record<string, string>> {
+  const fingerprint = await getDeviceFingerprint();
+  if (fingerprint) {
+    return {
+      ...headers,
+      "X-Device-Fingerprint": fingerprint,
+    };
+  }
+  return headers;
+}
+
+/**
+ * React hook to get the device fingerprint
+ *
+ * Usage:
+ * ```tsx
+ * const fingerprint = useDeviceFingerprint();
+ * ```
+ */
+export function useDeviceFingerprint(): string | null {
+  const [fingerprint, setFingerprint] = useState<string | null>(null);
+
+  useEffect(() => {
+    getDeviceFingerprint().then(setFingerprint);
+  }, []);
+
+  return fingerprint;
+}
+
+// Need to import useState and useEffect for the hook
+import { useEffect, useState } from "react";

package/template/src/lib/health/checks.ts

@@ -0,0 +1,6 @@
+import { sql } from "drizzle-orm";
+
+export async function probeDatabase(): Promise<void> {
+  const { db } = await import("@/db");
+  await db.execute(sql`SELECT 1`);
+}

package/template/src/lib/health/core.ts

@@ -0,0 +1,86 @@
+import type { HealthCheckResult, HealthReport } from "./types";
+
+const REQUIRED_ENVIRONMENT_KEYS = [
+  "DATABASE_URL",
+  "BETTER_AUTH_SECRET",
+  "BETTER_AUTH_URL",
+  "NEXT_PUBLIC_APP_URL",
+] as const;
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const protocol = new URL(value).protocol;
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function isPostgresUrl(value: string): boolean {
+  try {
+    const protocol = new URL(value).protocol;
+    return protocol === "postgres:" || protocol === "postgresql:";
+  } catch {
+    return false;
+  }
+}
+
+export function validateDeploymentEnvironment(
+  environment: Readonly<Record<string, string | undefined>>
+): readonly string[] {
+  const invalid = REQUIRED_ENVIRONMENT_KEYS.filter(
+    (key) => !environment[key]?.trim()
+  );
+  const databaseUrl = environment.DATABASE_URL?.trim();
+  const authUrl = environment.BETTER_AUTH_URL?.trim();
+  const appUrl = environment.NEXT_PUBLIC_APP_URL?.trim();
+
+  if (databaseUrl && !isPostgresUrl(databaseUrl)) invalid.push("DATABASE_URL");
+  if (authUrl && !isHttpUrl(authUrl)) invalid.push("BETTER_AUTH_URL");
+  if (appUrl && !isHttpUrl(appUrl)) invalid.push("NEXT_PUBLIC_APP_URL");
+
+  return [...new Set(invalid)];
+}
+
+export function createHealthReport(input: {
+  checks: Readonly<Record<string, HealthCheckResult>>;
+  now?: Date;
+  version: string;
+}): HealthReport {
+  const healthy = Object.values(input.checks).every(
+    (check) => check.status === "pass"
+  );
+
+  return {
+    status: healthy ? "healthy" : "unhealthy",
+    version: input.version,
+    timestamp: (input.now ?? new Date()).toISOString(),
+    checks: input.checks,
+  };
+}
+
+export async function runHealthProbe(
+  probe: () => Promise<void>,
+  options: { now?: () => number; timeoutMs: number }
+): Promise<HealthCheckResult> {
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    await Promise.race([
+      probe(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("Health probe timed out")),
+          options.timeoutMs
+        );
+      }),
+    ]);
+    return { status: "pass", durationMs: Math.max(0, now() - startedAt) };
+  } catch {
+    return { status: "fail", durationMs: Math.max(0, now() - startedAt) };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/template/src/lib/health/index.ts

@@ -0,0 +1,11 @@
+export { probeDatabase } from "./checks";
+export {
+  createHealthReport,
+  runHealthProbe,
+  validateDeploymentEnvironment,
+} from "./core";
+export type {
+  HealthCheckResult,
+  HealthCheckStatus,
+  HealthReport,
+} from "./types";

package/template/src/lib/health/types.ts

@@ -0,0 +1,13 @@
+export type HealthCheckStatus = "fail" | "pass";
+
+export interface HealthCheckResult {
+  durationMs: number;
+  status: HealthCheckStatus;
+}
+
+export interface HealthReport {
+  checks: Readonly<Record<string, HealthCheckResult>>;
+  status: "healthy" | "unhealthy";
+  timestamp: string;
+  version: string;
+}

package/template/src/lib/index.ts

@@ -0,0 +1,2 @@
+// Utility functions and configurations
+export {};