@digilogiclabs/create-saas-app 2.1.0 → 2.2.0

package/dist/templates/shared/security/web/lib/api-security.ts

@@ -0,0 +1,318 @@
+/**
+ * Shared API security utilities.
+ *
+ * Built on platform-core/auth building blocks — no local reimplementations.
+ * Uses constantTimeEqual, classifyError, rate limiting, and audit from the package.
+ *
+ * Two usage patterns:
+ *   1. Wrappers: withPublicApi / withAuthenticatedApi / withAdminApi (recommended)
+ *   2. Primitives: enforceRateLimit, isAdminRequest, errorResponse (manual composition)
+ */
+import 'server-only';
+import { NextRequest, NextResponse } from 'next/server';
+import { randomUUID } from 'crypto';
+import {
+  // Security primitives
+  constantTimeEqual,
+  // Rate limiting
+  CommonRateLimits,
+  type RateLimitRule,
+  type RateLimitOptions,
+  // Next.js API helpers
+  enforceRateLimit as _enforceRateLimit,
+  errorResponse,
+  zodErrorResponse,
+  classifyError,
+} from '@digilogiclabs/platform-core/auth';
+
+// Trigger env validation on first import (fail-fast in production)
+import { config } from '@/lib/config';
+
+// Re-export for convenience in routes
+export { escapeHtml } from '@digilogiclabs/platform-core/auth';
+export { errorResponse, zodErrorResponse };
+
+// ---------------------------------------------------------------------------
+// Request ID / Correlation ID
+// ---------------------------------------------------------------------------
+
+/** Generate or extract a request ID for correlation. */
+export function getRequestId(request: NextRequest): string {
+  return request.headers.get('x-request-id') || randomUUID();
+}
+
+/**
+ * Rate-limit a request using Redis-backed store (if REDIS_URL is set)
+ * or in-memory fallback. Wraps platform-core's enforceRateLimit to
+ * automatically inject the store.
+ */
+export async function enforceRateLimit(
+  request: { headers: { get(name: string): string | null } },
+  operation: string,
+  rule: RateLimitRule,
+  options?: {
+    identifier?: string;
+    userId?: string;
+    rateLimitOptions?: RateLimitOptions;
+  }
+): Promise<Response | null> {
+  const { getRateLimitStore } = await import('@/lib/rate-limit-store');
+  const store = getRateLimitStore();
+  return _enforceRateLimit(request, operation, rule, {
+    ...options,
+    rateLimitOptions: { ...options?.rateLimitOptions, ...(store ? { store } : {}) },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Admin / Cron auth helpers
+// ---------------------------------------------------------------------------
+
+/** Extract bearer token from Authorization header. */
+function extractBearerToken(request: NextRequest): string | null {
+  const header = request.headers.get('authorization');
+  if (!header?.startsWith('Bearer ')) return null;
+  return header.slice(7);
+}
+
+/** Check if request has a valid admin bearer token (ADMIN_SECRET). Timing-safe. */
+export function isAdminRequest(request: NextRequest): boolean {
+  const secret = config.adminSecret;
+  if (!secret) return false;
+  const token = extractBearerToken(request);
+  if (!token) return false;
+  return constantTimeEqual(token, secret);
+}
+
+/** Check if request has a valid cron bearer token (CRON_SECRET). Timing-safe. */
+export function isCronRequest(request: NextRequest): boolean {
+  const secret = config.cronSecret;
+  if (!secret) return false;
+  const token = extractBearerToken(request);
+  if (!token) return false;
+  return constantTimeEqual(token, secret);
+}
+
+// ---------------------------------------------------------------------------
+// Rate limiting presets — tune for your app's traffic patterns
+// ---------------------------------------------------------------------------
+
+/** App-specific rate limit presets. Extend or override as needed. */
+export const AppRateLimits = {
+  /** Public read endpoints */
+  publicRead: { limit: 60, windowSeconds: 60 } satisfies RateLimitRule,
+  /** Authenticated mutations */
+  authMutation: { limit: 30, windowSeconds: 60 } satisfies RateLimitRule,
+  /** Admin endpoints */
+  admin: CommonRateLimits.adminAction,
+  /** Beta code validation */
+  betaValidation: CommonRateLimits.betaValidation,
+  /** Webhook endpoints (generous — Stripe retries) */
+  webhook: { limit: 100, windowSeconds: 60 } satisfies RateLimitRule,
+} as const;
+
+// ---------------------------------------------------------------------------
+// API Wrapper Types
+// ---------------------------------------------------------------------------
+
+interface ApiWrapperConfig {
+  /** Rate limit rule (defaults to preset based on wrapper type) */
+  rateLimit?: RateLimitRule;
+  /** Operation name for rate limiting and logging */
+  operation?: string;
+}
+
+interface AuthenticatedApiContext {
+  /** The authenticated session */
+  session: { user: { id: string; email: string; roles?: string[] } };
+  /** Request correlation ID */
+  requestId: string;
+}
+
+interface PublicApiContext {
+  /** Request correlation ID */
+  requestId: string;
+}
+
+type PublicApiHandler = (request: NextRequest, context: PublicApiContext) => Promise<NextResponse>;
+
+type AuthenticatedApiHandler = (
+  request: NextRequest,
+  context: AuthenticatedApiContext
+) => Promise<NextResponse>;
+
+type AdminApiHandler = (request: NextRequest, context: PublicApiContext) => Promise<NextResponse>;
+
+type CronApiHandler = (request: NextRequest, context: PublicApiContext) => Promise<NextResponse>;
+
+// ---------------------------------------------------------------------------
+// API Wrappers — compose auth, rate limiting, error handling automatically
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a public API route with rate limiting and error handling.
+ * No authentication required.
+ *
+ * @example
+ * export const GET = withPublicApi({ operation: 'list-items' }, async (req, ctx) => {
+ *   return NextResponse.json({ items: [] });
+ * });
+ */
+export function withPublicApi(
+  handlerConfig: ApiWrapperConfig,
+  handler: PublicApiHandler
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    const requestId = getRequestId(request);
+    const operation = handlerConfig.operation || 'public';
+
+    try {
+      // Rate limiting
+      const rateLimited = await enforceRateLimit(
+        request,
+        operation,
+        handlerConfig.rateLimit || AppRateLimits.publicRead
+      );
+      if (rateLimited) return rateLimited as NextResponse;
+
+      const response = await handler(request, { requestId });
+      response.headers.set('x-request-id', requestId);
+      return response;
+    } catch (error) {
+      const { status, body } = classifyError(error, process.env.NODE_ENV === 'development');
+      return NextResponse.json({ ...body, requestId }, { status });
+    }
+  };
+}
+
+/**
+ * Wrap an authenticated API route with session validation, rate limiting, and error handling.
+ * Requires a valid Auth.js session.
+ *
+ * @example
+ * export const POST = withAuthenticatedApi({ operation: 'create-item' }, async (req, ctx) => {
+ *   const { session, requestId } = ctx;
+ *   return NextResponse.json({ userId: session.user.id });
+ * });
+ */
+export function withAuthenticatedApi(
+  handlerConfig: ApiWrapperConfig,
+  handler: AuthenticatedApiHandler
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    const requestId = getRequestId(request);
+    const operation = handlerConfig.operation || 'authenticated';
+
+    try {
+      // Dynamic import to avoid Edge runtime issues
+      const { auth } = await import('@/auth');
+      const session = await auth();
+
+      if (!session?.user?.id) {
+        return NextResponse.json({ error: 'Unauthorized', requestId }, { status: 401 });
+      }
+
+      // Rate limiting (per-user)
+      const rateLimited = await enforceRateLimit(
+        request,
+        operation,
+        handlerConfig.rateLimit || AppRateLimits.authMutation,
+        { userId: session.user.id }
+      );
+      if (rateLimited) return rateLimited as NextResponse;
+
+      const response = await handler(request, {
+        session: session as AuthenticatedApiContext['session'],
+        requestId,
+      });
+      response.headers.set('x-request-id', requestId);
+      return response;
+    } catch (error) {
+      const { status, body } = classifyError(error, process.env.NODE_ENV === 'development');
+      return NextResponse.json({ ...body, requestId }, { status });
+    }
+  };
+}
+
+/**
+ * Wrap an admin API route with Bearer token auth, rate limiting, and error handling.
+ * Requires ADMIN_SECRET Bearer token.
+ *
+ * @example
+ * export const POST = withAdminApi({ operation: 'admin-action' }, async (req, ctx) => {
+ *   return NextResponse.json({ success: true });
+ * });
+ */
+export function withAdminApi(
+  handlerConfig: ApiWrapperConfig,
+  handler: AdminApiHandler
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    const requestId = getRequestId(request);
+    const operation = handlerConfig.operation || 'admin';
+
+    try {
+      if (!isAdminRequest(request)) {
+        return NextResponse.json({ error: 'Forbidden', requestId }, { status: 403 });
+      }
+
+      // Rate limiting
+      const rateLimited = await enforceRateLimit(
+        request,
+        operation,
+        handlerConfig.rateLimit || AppRateLimits.admin
+      );
+      if (rateLimited) return rateLimited as NextResponse;
+
+      const response = await handler(request, { requestId });
+      response.headers.set('x-request-id', requestId);
+      return response;
+    } catch (error) {
+      const { status, body } = classifyError(error, process.env.NODE_ENV === 'development');
+      return NextResponse.json({ ...body, requestId }, { status });
+    }
+  };
+}
+
+/**
+ * Wrap a cron/scheduled API route with CRON_SECRET Bearer token auth,
+ * falling back to admin session check. Uses generous rate limits since
+ * cron jobs are server-to-server.
+ *
+ * @example
+ * export const POST = withCronApi({ operation: 'daily-digest' }, async (req, ctx) => {
+ *   // Run scheduled task...
+ *   return NextResponse.json({ processed: 42 });
+ * });
+ */
+export function withCronApi(
+  handlerConfig: ApiWrapperConfig,
+  handler: CronApiHandler
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    const requestId = getRequestId(request);
+    const operation = handlerConfig.operation || 'cron';
+
+    try {
+      // Accept CRON_SECRET Bearer token or fall back to ADMIN_SECRET
+      if (!isCronRequest(request) && !isAdminRequest(request)) {
+        return NextResponse.json({ error: 'Forbidden', requestId }, { status: 403 });
+      }
+
+      // Rate limiting (generous — cron jobs are server-to-server)
+      const rateLimited = await enforceRateLimit(
+        request,
+        operation,
+        handlerConfig.rateLimit || AppRateLimits.webhook
+      );
+      if (rateLimited) return rateLimited as NextResponse;
+
+      const response = await handler(request, { requestId });
+      response.headers.set('x-request-id', requestId);
+      return response;
+    } catch (error) {
+      const { status, body } = classifyError(error, process.env.NODE_ENV === 'development');
+      return NextResponse.json({ ...body, requestId }, { status });
+    }
+  };
+}

package/dist/templates/shared/seo/web/app/api/og/route.tsx

@@ -0,0 +1,97 @@
+import { ImageResponse } from 'next/og';
+import { NextRequest } from 'next/server';
+
+export const runtime = 'edge';
+
+/**
+ * Dynamic Open Graph image generator.
+ *
+ * Usage: /api/og?title=My+Page&subtitle=Description+here
+ *
+ * Customize the colors and branding below to match your app.
+ */
+
+// ─── Customize these ────────────────────────────────────────
+const APP_NAME = 'My App';
+const BG_FROM = '#1e3a5f';
+const BG_TO = '#0f172a';
+const ACCENT = '#3b82f6';
+// ─────────────────────────────────────────────────────────────
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = request.nextUrl;
+  const title = searchParams.get('title') || APP_NAME;
+  const subtitle = searchParams.get('subtitle') || '';
+
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'center',
+          padding: '60px 80px',
+          background: `linear-gradient(135deg, ${BG_FROM} 0%, ${BG_TO} 100%)`,
+          color: 'white',
+          fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        }}
+      >
+        {/* App branding */}
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            marginBottom: 40,
+            fontSize: 24,
+            opacity: 0.8,
+            letterSpacing: '0.05em',
+          }}
+        >
+          {APP_NAME}
+        </div>
+
+        {/* Title */}
+        <div
+          style={{
+            fontSize: title.length > 40 ? 48 : 64,
+            fontWeight: 700,
+            lineHeight: 1.1,
+            maxWidth: '90%',
+            marginBottom: subtitle ? 24 : 0,
+          }}
+        >
+          {title.length > 80 ? title.slice(0, 77) + '...' : title}
+        </div>
+
+        {/* Subtitle */}
+        {subtitle && (
+          <div
+            style={{
+              fontSize: 28,
+              opacity: 0.7,
+              maxWidth: '80%',
+              lineHeight: 1.3,
+            }}
+          >
+            {subtitle.length > 120 ? subtitle.slice(0, 117) + '...' : subtitle}
+          </div>
+        )}
+
+        {/* Accent bar */}
+        <div
+          style={{
+            position: 'absolute',
+            bottom: 0,
+            left: 0,
+            right: 0,
+            height: 6,
+            background: ACCENT,
+          }}
+        />
+      </div>
+    ),
+    { width: 1200, height: 630 },
+  );
+}

package/dist/templates/shared/seo/web/app/robots.ts

@@ -0,0 +1,53 @@
+import { MetadataRoute } from 'next';
+
+const BASE_URL = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000';
+
+/**
+ * Robots.txt configuration.
+ *
+ * Controls which paths search engines and AI crawlers can access.
+ * Adjust the rules to match your app's public and private routes.
+ *
+ * @see https://nextjs.org/docs/app/api-reference/file-conventions/metadata/robots
+ */
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      // ─── Main search engines (Google, Bing, etc.) ──────────────
+      {
+        userAgent: ['Googlebot', 'Bingbot', 'Slurp', 'DuckDuckBot', 'Baiduspider', 'YandexBot'],
+        allow: '/',
+        disallow: ['/api/', '/dashboard/', '/admin/', '/auth/'],
+      },
+
+      // ─── AI crawlers (allow indexing, block private routes) ────
+      {
+        userAgent: [
+          'GPTBot',
+          'Google-Extended',
+          'ChatGPT-User',
+          'ClaudeBot',
+          'PerplexityBot',
+          'Amazonbot',
+          'YouBot',
+        ],
+        allow: '/',
+        disallow: ['/api/', '/dashboard/', '/admin/', '/auth/'],
+      },
+
+      // ─── Training-only crawlers (block entirely) ───────────────
+      {
+        userAgent: ['CCBot', 'anthropic-ai'],
+        disallow: '/',
+      },
+
+      // ─── Default (allow public content) ────────────────────────
+      {
+        userAgent: '*',
+        allow: '/',
+        disallow: ['/api/', '/dashboard/', '/admin/', '/auth/'],
+      },
+    ],
+    sitemap: `${BASE_URL}/sitemap.xml`,
+  };
+}

package/dist/templates/shared/seo/web/app/sitemap.ts

@@ -0,0 +1,53 @@
+import { MetadataRoute } from 'next';
+
+const BASE_URL = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000';
+
+/**
+ * Dynamic sitemap generator.
+ *
+ * Generates a sitemap for search engine crawlers.
+ * Add your app's dynamic routes (e.g., user profiles, blog posts)
+ * alongside the static pages.
+ *
+ * @see https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap
+ */
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const now = new Date();
+
+  // ─── Static Pages ────────────────────────────────────────────
+  const staticPages: MetadataRoute.Sitemap = [
+    {
+      url: BASE_URL,
+      lastModified: now,
+      changeFrequency: 'daily',
+      priority: 1.0,
+    },
+    {
+      url: `${BASE_URL}/terms`,
+      lastModified: now,
+      changeFrequency: 'monthly',
+      priority: 0.3,
+    },
+    {
+      url: `${BASE_URL}/privacy`,
+      lastModified: now,
+      changeFrequency: 'monthly',
+      priority: 0.3,
+    },
+  ];
+
+  // ─── Dynamic Pages ───────────────────────────────────────────
+  // TODO: Add your dynamic routes here. Example:
+  //
+  // const { data: posts } = await db.from('posts').select('slug, updated_at');
+  // const postPages = (posts || []).map((post) => ({
+  //   url: `${BASE_URL}/blog/${post.slug}`,
+  //   lastModified: new Date(post.updated_at),
+  //   changeFrequency: 'weekly' as const,
+  //   priority: 0.7,
+  // }));
+  //
+  // return [...staticPages, ...postPages];
+
+  return staticPages;
+}

package/dist/templates/shared/utils/web/lib/api-response.ts

@@ -0,0 +1,71 @@
+import { NextResponse } from 'next/server';
+import { classifyError, buildPagination } from '@digilogiclabs/platform-core/auth';
+
+/**
+ * Standardized API response helpers.
+ *
+ * Provides consistent response shapes across all API routes.
+ * Uses classifyError from platform-core for structured error handling.
+ */
+
+/** Success response with optional status code */
+export function successResponse<T>(data: T, status = 200) {
+  return NextResponse.json({ success: true, data }, { status });
+}
+
+/** Success response with a message */
+export function successWithMessage<T>(data: T, message: string, status = 200) {
+  return NextResponse.json({ success: true, message, data }, { status });
+}
+
+/** 201 Created response */
+export function createdResponse<T>(data: T, message = 'Created successfully') {
+  return NextResponse.json({ success: true, message, data }, { status: 201 });
+}
+
+/** 204 No Content response */
+export function noContentResponse() {
+  return new NextResponse(null, { status: 204 });
+}
+
+/** 202 Accepted response (for async operations) */
+export function acceptedResponse<T>(data: T, message = 'Request accepted') {
+  return NextResponse.json({ success: true, message, data }, { status: 202 });
+}
+
+/** Error response with status code */
+export function errorResponse(message: string, status = 500, code?: string) {
+  return NextResponse.json(
+    { success: false, error: { message, ...(code && { code }) } },
+    { status }
+  );
+}
+
+/** Paginated response with metadata */
+export function paginatedResponse<T>(data: T[], page: number, limit: number, total: number) {
+  return NextResponse.json({
+    success: true,
+    data,
+    pagination: buildPagination(page, limit, total),
+  });
+}
+
+/** Handle any error and return a structured response */
+export function handleApiError(error: unknown) {
+  const isDev = process.env.NODE_ENV === 'development';
+  const { status, body } = classifyError(error, isDev);
+  return NextResponse.json({ success: false, error: body }, { status });
+}
+
+/** Wrap a handler with automatic error handling */
+export function withErrorHandler(
+  handler: (request: Request) => Promise<NextResponse>
+): (request: Request) => Promise<NextResponse> {
+  return async (request: Request) => {
+    try {
+      return await handler(request);
+    } catch (error) {
+      return handleApiError(error);
+    }
+  };
+}

package/dist/templates/shared/utils/web/lib/utils.ts

@@ -0,0 +1,85 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/** Merge Tailwind classes with conflict resolution */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+/** Format currency with locale support */
+export function formatCurrency(amount: number, currency = 'USD', locale = 'en-US'): string {
+  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);
+}
+
+/** Format date with locale support */
+export function formatDate(date: Date | string, options?: Intl.DateTimeFormatOptions): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+  return d.toLocaleDateString(
+    'en-US',
+    options || { year: 'numeric', month: 'long', day: 'numeric' }
+  );
+}
+
+/** Get relative time string (e.g., "2 hours ago", "in 3 days") */
+export function getRelativeTime(date: Date | string): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+  const now = new Date();
+  const diffMs = now.getTime() - d.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+
+  if (diffSec < 60) return 'just now';
+  if (diffMin < 60) return `${diffMin}m ago`;
+  if (diffHour < 24) return `${diffHour}h ago`;
+  if (diffDay < 7) return `${diffDay}d ago`;
+  if (diffDay < 30) return `${Math.floor(diffDay / 7)}w ago`;
+  return formatDate(d, {
+    month: 'short',
+    day: 'numeric',
+    year: diffDay > 365 ? 'numeric' : undefined,
+  });
+}
+
+/** Truncate text with ellipsis */
+export function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength).trimEnd() + '...';
+}
+
+/** Get initials from a name (e.g., "John Doe" → "JD") */
+export function getInitials(name: string, maxChars = 2): string {
+  return name
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => part[0]?.toUpperCase() || '')
+    .slice(0, maxChars)
+    .join('');
+}
+
+/** Debounce a function */
+export function debounce<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  delayMs: number
+): (...args: Parameters<T>) => void {
+  let timer: ReturnType<typeof setTimeout>;
+  return (...args: Parameters<T>) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), delayMs);
+  };
+}
+
+/** Sleep for a given number of milliseconds */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Safely parse JSON, returning null on failure */
+export function safeJsonParse<T = unknown>(json: string): T | null {
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return null;
+  }
+}