create-xani-agentic-app 1.0.0

package/template/src/lib/env.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+
+/**
+ * Server-side environment variables schema.
+ * These variables are only available on the server.
+ */
+const serverEnvSchema = z.object({
+  // Database
+  POSTGRES_URL: z.string().url("Invalid database URL"),
+
+  // Authentication
+  BETTER_AUTH_SECRET: z
+    .string()
+    .min(32, "BETTER_AUTH_SECRET must be at least 32 characters"),
+
+  // OAuth
+  GOOGLE_CLIENT_ID: z.string().optional(),
+  GOOGLE_CLIENT_SECRET: z.string().optional(),
+
+  // AI
+  OPENROUTER_API_KEY: z.string().optional(),
+  OPENROUTER_MODEL: z.string().default("openai/gpt-5-mini"),
+
+  // Storage
+  BLOB_READ_WRITE_TOKEN: z.string().optional(),
+
+  // App
+  NODE_ENV: z
+    .enum(["development", "production", "test"])
+    .default("development"),
+});
+
+/**
+ * Client-side environment variables schema.
+ * These variables are exposed to the browser via NEXT_PUBLIC_ prefix.
+ */
+const clientEnvSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url().default("http://localhost:3000"),
+});
+
+export type ServerEnv = z.infer<typeof serverEnvSchema>;
+export type ClientEnv = z.infer<typeof clientEnvSchema>;
+
+/**
+ * Validates and returns server-side environment variables.
+ * Throws an error if validation fails.
+ */
+export function getServerEnv(): ServerEnv {
+  const parsed = serverEnvSchema.safeParse(process.env);
+
+  if (!parsed.success) {
+    console.error(
+      "Invalid server environment variables:",
+      parsed.error.flatten().fieldErrors
+    );
+    throw new Error("Invalid server environment variables");
+  }
+
+  return parsed.data;
+}
+
+/**
+ * Validates and returns client-side environment variables.
+ * Throws an error if validation fails.
+ */
+export function getClientEnv(): ClientEnv {
+  const parsed = clientEnvSchema.safeParse({
+    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+  });
+
+  if (!parsed.success) {
+    console.error(
+      "Invalid client environment variables:",
+      parsed.error.flatten().fieldErrors
+    );
+    throw new Error("Invalid client environment variables");
+  }
+
+  return parsed.data;
+}
+
+/**
+ * Checks if required environment variables are set.
+ * Logs warnings for missing optional variables.
+ */
+export function checkEnv(): void {
+  const warnings: string[] = [];
+
+  // Check required variables
+  if (!process.env.POSTGRES_URL) {
+    throw new Error("POSTGRES_URL is required");
+  }
+
+  if (!process.env.BETTER_AUTH_SECRET) {
+    throw new Error("BETTER_AUTH_SECRET is required");
+  }
+
+  // Check optional variables and warn
+  if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET) {
+    warnings.push("Google OAuth is not configured. Social login will be disabled.");
+  }
+
+  if (!process.env.OPENROUTER_API_KEY) {
+    warnings.push("OPENROUTER_API_KEY is not set. AI chat will not work.");
+  }
+
+  if (!process.env.BLOB_READ_WRITE_TOKEN) {
+    warnings.push("BLOB_READ_WRITE_TOKEN is not set. Using local storage for file uploads.");
+  }
+
+  // Log warnings in development
+  if (process.env.NODE_ENV === "development" && warnings.length > 0) {
+    console.warn("\n⚠️  Environment warnings:");
+    warnings.forEach((w) => console.warn(`   - ${w}`));
+    console.warn("");
+  }
+}

package/template/src/lib/schema.ts

@@ -0,0 +1,82 @@
+import { pgTable, text, timestamp, boolean, index } from "drizzle-orm/pg-core";
+
+// IMPORTANT! ID fields should ALWAYS use UUID types, EXCEPT the BetterAuth tables.
+
+
+export const user = pgTable(
+  "user",
+  {
+    id: text("id").primaryKey(),
+    name: text("name").notNull(),
+    email: text("email").notNull().unique(),
+    emailVerified: boolean("email_verified").default(false).notNull(),
+    image: text("image"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at")
+      .defaultNow()
+      .$onUpdate(() => /* @__PURE__ */ new Date())
+      .notNull(),
+  },
+  (table) => [index("user_email_idx").on(table.email)]
+);
+
+export const session = pgTable(
+  "session",
+  {
+    id: text("id").primaryKey(),
+    expiresAt: timestamp("expires_at").notNull(),
+    token: text("token").notNull().unique(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at")
+      .$onUpdate(() => /* @__PURE__ */ new Date())
+      .notNull(),
+    ipAddress: text("ip_address"),
+    userAgent: text("user_agent"),
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+  },
+  (table) => [
+    index("session_user_id_idx").on(table.userId),
+    index("session_token_idx").on(table.token),
+  ]
+);
+
+export const account = pgTable(
+  "account",
+  {
+    id: text("id").primaryKey(),
+    accountId: text("account_id").notNull(),
+    providerId: text("provider_id").notNull(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    idToken: text("id_token"),
+    accessTokenExpiresAt: timestamp("access_token_expires_at"),
+    refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+    scope: text("scope"),
+    password: text("password"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at")
+      .$onUpdate(() => /* @__PURE__ */ new Date())
+      .notNull(),
+  },
+  (table) => [
+    index("account_user_id_idx").on(table.userId),
+    index("account_provider_account_idx").on(table.providerId, table.accountId),
+  ]
+);
+
+export const verification = pgTable("verification", {
+  id: text("id").primaryKey(),
+  identifier: text("identifier").notNull(),
+  value: text("value").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .defaultNow()
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+});

package/template/src/lib/session.ts

@@ -0,0 +1,48 @@
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { auth } from "@/lib/auth";
+
+/**
+ * Protected routes that require authentication.
+ * These are also configured in src/proxy.ts for optimistic redirects.
+ */
+export const protectedRoutes = ["/chat", "/dashboard", "/profile"];
+
+/**
+ * Checks if the current request is authenticated.
+ * Should be called in Server Components for protected routes.
+ *
+ * @returns The session object if authenticated
+ * @throws Redirects to home page if not authenticated
+ */
+export async function requireAuth() {
+  const session = await auth.api.getSession({ headers: await headers() });
+
+  if (!session) {
+    redirect("/");
+  }
+
+  return session;
+}
+
+/**
+ * Gets the current session without requiring authentication.
+ * Returns null if not authenticated.
+ *
+ * @returns The session object or null
+ */
+export async function getOptionalSession() {
+  return await auth.api.getSession({ headers: await headers() });
+}
+
+/**
+ * Checks if a given path is a protected route.
+ *
+ * @param path - The path to check
+ * @returns True if the path requires authentication
+ */
+export function isProtectedRoute(path: string): boolean {
+  return protectedRoutes.some(
+    (route) => path === route || path.startsWith(`${route}/`)
+  );
+}

package/template/src/lib/storage.ts

@@ -0,0 +1,225 @@
+import { existsSync } from "fs";
+import { writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+import { put, del } from "@vercel/blob";
+
+/**
+ * Result from uploading a file to storage
+ */
+export interface StorageResult {
+  url: string; // Public URL to access the file
+  pathname: string; // Path/key of the stored file
+}
+
+/**
+ * Storage configuration
+ */
+export interface StorageConfig {
+  /** Maximum file size in bytes (default: 5MB) */
+  maxSize?: number;
+  /** Allowed MIME types (default: images and documents) */
+  allowedTypes?: string[];
+}
+
+/**
+ * Default storage configuration
+ */
+const DEFAULT_CONFIG: Required<StorageConfig> = {
+  maxSize: 5 * 1024 * 1024, // 5MB
+  allowedTypes: [
+    // Images
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "image/svg+xml",
+    // Documents
+    "application/pdf",
+    "text/plain",
+    "text/csv",
+    "application/json",
+  ],
+};
+
+/**
+ * Allowed file extensions mapped from MIME types
+ */
+const ALLOWED_EXTENSIONS = new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".webp",
+  ".svg",
+  ".pdf",
+  ".txt",
+  ".csv",
+  ".json",
+]);
+
+/**
+ * Sanitize a filename by removing dangerous characters and path traversal attempts
+ */
+export function sanitizeFilename(filename: string): string {
+  // Remove path components (prevent directory traversal)
+  const basename = filename.split(/[/\\]/).pop() || filename;
+
+  // Remove or replace dangerous characters
+  const sanitized = basename
+    .replace(/[<>:"|?*\x00-\x1f]/g, "") // Remove dangerous chars
+    .replace(/\.{2,}/g, ".") // Collapse multiple dots
+    .replace(/^\.+/, "") // Remove leading dots
+    .trim();
+
+  // Ensure filename is not empty
+  if (!sanitized || sanitized.length === 0) {
+    throw new Error("Invalid filename");
+  }
+
+  // Limit filename length
+  if (sanitized.length > 255) {
+    const ext = sanitized.slice(sanitized.lastIndexOf("."));
+    const name = sanitized.slice(0, 255 - ext.length);
+    return name + ext;
+  }
+
+  return sanitized;
+}
+
+/**
+ * Validate file for upload
+ */
+export function validateFile(
+  buffer: Buffer,
+  filename: string,
+  config: StorageConfig = {}
+): { valid: true } | { valid: false; error: string } {
+  const { maxSize } = { ...DEFAULT_CONFIG, ...config };
+
+  // Check file size
+  if (buffer.length > maxSize) {
+    return {
+      valid: false,
+      error: `File too large. Maximum size is ${Math.round(maxSize / 1024 / 1024)}MB`,
+    };
+  }
+
+  // Check file extension
+  const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase();
+  if (!ALLOWED_EXTENSIONS.has(ext)) {
+    return {
+      valid: false,
+      error: `File type not allowed. Allowed extensions: ${Array.from(ALLOWED_EXTENSIONS).join(", ")}`,
+    };
+  }
+
+  // Optionally check MIME type if provided
+  // Note: For full MIME type validation, consider using a library like 'file-type'
+
+  return { valid: true };
+}
+
+/**
+ * Uploads a file to storage (Vercel Blob or local filesystem)
+ *
+ * @param buffer - File contents as a Buffer
+ * @param filename - Name of the file (e.g., "image.png")
+ * @param folder - Optional folder/prefix (e.g., "avatars")
+ * @param config - Optional storage configuration
+ * @returns StorageResult with url and pathname
+ *
+ * @example
+ * ```ts
+ * const result = await upload(fileBuffer, "avatar.png", "avatars");
+ * console.log(result.url); // https://blob.vercel.io/... or /uploads/avatars/avatar.png
+ * ```
+ */
+export async function upload(
+  buffer: Buffer,
+  filename: string,
+  folder?: string,
+  config?: StorageConfig
+): Promise<StorageResult> {
+  // Sanitize filename
+  const sanitizedFilename = sanitizeFilename(filename);
+
+  // Validate file
+  const validation = validateFile(buffer, sanitizedFilename, config);
+  if (!validation.valid) {
+    throw new Error(validation.error);
+  }
+
+  const hasVercelBlob = Boolean(process.env.BLOB_READ_WRITE_TOKEN);
+
+  if (hasVercelBlob) {
+    // Use Vercel Blob storage
+    const pathname = folder ? `${folder}/${sanitizedFilename}` : sanitizedFilename;
+    const blob = await put(pathname, buffer, {
+      access: "public",
+    });
+
+    return {
+      url: blob.url,
+      pathname: blob.pathname,
+    };
+  } else {
+    // Use local filesystem storage
+    const uploadsDir = join(process.cwd(), "public", "uploads");
+    const targetDir = folder ? join(uploadsDir, folder) : uploadsDir;
+
+    // Ensure the directory exists
+    if (!existsSync(targetDir)) {
+      await mkdir(targetDir, { recursive: true });
+    }
+
+    // Write the file
+    const filepath = join(targetDir, sanitizedFilename);
+    await writeFile(filepath, buffer);
+
+    // Return local URL
+    const pathname = folder ? `${folder}/${sanitizedFilename}` : sanitizedFilename;
+    const url = `/uploads/${pathname}`;
+
+    return {
+      url,
+      pathname,
+    };
+  }
+}
+
+/**
+ * Deletes a file from storage
+ * 
+ * @param url - The URL of the file to delete
+ * 
+ * @example
+ * ```ts
+ * await deleteFile("https://blob.vercel.io/...");
+ * // or
+ * await deleteFile("/uploads/avatars/avatar.png");
+ * ```
+ */
+export async function deleteFile(url: string): Promise<void> {
+  const hasVercelBlob = Boolean(process.env.BLOB_READ_WRITE_TOKEN);
+
+  if (hasVercelBlob) {
+    // Delete from Vercel Blob
+    await del(url);
+  } else {
+    // Delete from local filesystem
+    // Extract pathname from URL (e.g., /uploads/avatars/avatar.png -> avatars/avatar.png)
+    const pathname = url.replace(/^\/uploads\//, "");
+    const filepath = join(process.cwd(), "public", "uploads", pathname);
+
+    // Only attempt to delete if file exists
+    if (existsSync(filepath)) {
+      const { unlink } = await import("fs/promises");
+      await unlink(filepath);
+    }
+  }
+}
+
+
+
+
+

package/template/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/template/src/proxy.ts

@@ -0,0 +1,25 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getSessionCookie } from "better-auth/cookies";
+
+/**
+ * Next.js 16 Proxy for auth protection.
+ * Uses cookie-based checks for fast, optimistic redirects.
+ *
+ * Note: This only checks for cookie existence, not validity.
+ * Full session validation should be done in each protected page/route.
+ */
+export async function proxy(request: NextRequest) {
+  const sessionCookie = getSessionCookie(request);
+
+  // Optimistic redirect - cookie existence check only
+  // Full validation happens in page components via auth.api.getSession()
+  if (!sessionCookie) {
+    return NextResponse.redirect(new URL("/", request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/dashboard", "/chat", "/profile"], // Protected routes
+};

package/template/tsconfig.json

@@ -0,0 +1,48 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "types": ["react", "react-dom", "node"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules", "create-xani-agentic-app"]
+}