@digilogiclabs/create-saas-app 2.0.0 → 2.2.0

package/dist/templates/shared/loading/web/app/loading.tsx

@@ -0,0 +1,5 @@
+import { LoadingSpinner } from '@/components/skeleton';
+
+export default function Loading() {
+  return <LoadingSpinner />;
+}

package/dist/templates/shared/loading/web/components/skeleton.tsx

@@ -0,0 +1,95 @@
+/**
+ * Reusable skeleton loading components.
+ *
+ * Use these in loading.tsx files for consistent loading states.
+ * All components use Tailwind's animate-pulse for the shimmer effect.
+ */
+
+/** Base skeleton block with customizable dimensions */
+export function Skeleton({
+  className = '',
+}: {
+  className?: string;
+}) {
+  return (
+    <div
+      className={`animate-pulse rounded bg-gray-200 dark:bg-gray-800 ${className}`}
+    />
+  );
+}
+
+/** Skeleton for a card with title, description, and action area */
+export function CardSkeleton() {
+  return (
+    <div className="rounded-lg border border-gray-200 p-6 dark:border-gray-800">
+      <Skeleton className="mb-4 h-4 w-3/4" />
+      <Skeleton className="mb-2 h-3 w-full" />
+      <Skeleton className="mb-4 h-3 w-5/6" />
+      <Skeleton className="h-8 w-24" />
+    </div>
+  );
+}
+
+/** Skeleton for a grid of cards */
+export function CardGridSkeleton({ count = 6 }: { count?: number }) {
+  return (
+    <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+      {Array.from({ length: count }, (_, i) => (
+        <CardSkeleton key={i} />
+      ))}
+    </div>
+  );
+}
+
+/** Skeleton for a table with rows */
+export function TableSkeleton({ rows = 5 }: { rows?: number }) {
+  return (
+    <div className="space-y-3">
+      {/* Header */}
+      <div className="flex gap-4 border-b border-gray-200 pb-3 dark:border-gray-800">
+        <Skeleton className="h-4 w-1/4" />
+        <Skeleton className="h-4 w-1/3" />
+        <Skeleton className="h-4 w-1/4" />
+        <Skeleton className="h-4 w-1/6" />
+      </div>
+      {/* Rows */}
+      {Array.from({ length: rows }, (_, i) => (
+        <div key={i} className="flex gap-4 py-2">
+          <Skeleton className="h-4 w-1/4" />
+          <Skeleton className="h-4 w-1/3" />
+          <Skeleton className="h-4 w-1/4" />
+          <Skeleton className="h-4 w-1/6" />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/** Skeleton for a full page with hero and content */
+export function PageSkeleton() {
+  return (
+    <div className="mx-auto max-w-4xl px-4 py-8">
+      {/* Hero */}
+      <Skeleton className="mb-4 h-8 w-2/3" />
+      <Skeleton className="mb-8 h-4 w-1/2" />
+      {/* Content blocks */}
+      <div className="space-y-4">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-5/6" />
+        <Skeleton className="h-4 w-4/5" />
+        <Skeleton className="h-32 w-full" />
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-3/4" />
+      </div>
+    </div>
+  );
+}
+
+/** Default loading spinner for loading.tsx files */
+export function LoadingSpinner() {
+  return (
+    <div className="flex min-h-[50vh] items-center justify-center">
+      <div className="h-8 w-8 animate-spin rounded-full border-4 border-gray-200 border-t-blue-600 dark:border-gray-700 dark:border-t-blue-400" />
+    </div>
+  );
+}

package/dist/templates/shared/middleware/web/middleware.ts

@@ -0,0 +1,68 @@
+/**
+ * Next.js Middleware (Edge Runtime)
+ *
+ * IMPORTANT: This file runs in the Edge runtime. Do NOT import:
+ * - Server-only modules (ioredis, pg, nodemailer)
+ * - The main platform-core barrel (pulls in node:stream)
+ * - auth.ts (server-only) — use auth.config.ts instead
+ *
+ * Use @digilogiclabs/platform-core/auth subpath for Edge-safe imports.
+ */
+import NextAuth from 'next-auth';
+import { authConfig } from './auth.config';
+
+const { auth } = NextAuth(authConfig);
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+/** Routes that require authentication */
+const protectedRoutes = ['/dashboard', '/settings', '/account'];
+
+/** Routes that are always public */
+const publicRoutes = ['/', '/auth/signin', '/auth/signup', '/api/health', '/api/auth'];
+
+/** Admin-only routes */
+const adminRoutes = ['/admin'];
+
+// ---------------------------------------------------------------------------
+// Middleware handler
+// ---------------------------------------------------------------------------
+
+export default auth((req) => {
+  const { pathname } = req.nextUrl;
+  const session = req.auth;
+
+  // Allow public routes and API routes
+  if (publicRoutes.some((r) => pathname.startsWith(r))) {
+    return;
+  }
+
+  // Allow static files and Next.js internals
+  if (pathname.startsWith('/_next') || pathname.startsWith('/favicon') || pathname.includes('.')) {
+    return;
+  }
+
+  // Check authentication for protected routes
+  const isProtected = protectedRoutes.some((r) => pathname.startsWith(r));
+  const isAdmin = adminRoutes.some((r) => pathname.startsWith(r));
+
+  if ((isProtected || isAdmin) && !session) {
+    const signInUrl = new URL('/auth/signin', req.url);
+    signInUrl.searchParams.set('callbackUrl', pathname);
+    return Response.redirect(signInUrl);
+  }
+
+  // Check admin role
+  if (isAdmin && session) {
+    const roles = (session.user as { roles?: string[] })?.roles || [];
+    if (!roles.includes('admin')) {
+      return Response.redirect(new URL('/dashboard', req.url));
+    }
+  }
+});
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\..*).*)'],
+};

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

@@ -0,0 +1,135 @@
+import { getClientIp } from '@digilogiclabs/platform-core/auth';
+
+/**
+ * Observability helpers — audit logging, error reporting, metrics.
+ *
+ * All functions are fire-and-forget (no await needed) and fail silently.
+ * Uses platform-core adapters when available, falls back to console.
+ *
+ * Customize the SERVICE_NAME and add app-specific audit actions.
+ */
+
+const SERVICE_NAME = 'my-app';
+
+// ─── Lazy Singletons ────────────────────────────────────────
+
+let auditLogPromise: Promise<AuditLogger> | null = null;
+
+interface AuditLogger {
+  log(event: AuditEvent): Promise<void>;
+}
+
+interface AuditEvent {
+  action: string;
+  actor: { id: string; type: string; email?: string };
+  resource?: { type: string; id?: string };
+  outcome: 'success' | 'failure' | 'blocked';
+  metadata?: Record<string, unknown>;
+  category?: string;
+  ip?: string;
+  userAgent?: string;
+}
+
+async function getAuditLog(): Promise<AuditLogger> {
+  if (!auditLogPromise) {
+    auditLogPromise = (async () => {
+      try {
+        const { getPlatform } = await import('@/lib/platform');
+        const platform = await getPlatform();
+        const { DatabaseAuditLog } = await import('@digilogiclabs/platform-core');
+        return new DatabaseAuditLog(platform.db, { serviceName: SERVICE_NAME });
+      } catch {
+        return {
+          log: async (event: AuditEvent) => {
+            console.log(`[Audit] ${event.action}`, JSON.stringify(event));
+          },
+        };
+      }
+    })();
+  }
+  return auditLogPromise;
+}
+
+// ─── Public Helpers ──────────────────────────────────────────
+
+/** Get user agent string from request */
+export function getUserAgent(request: Request): string {
+  return request.headers.get('user-agent') || 'unknown';
+}
+
+// Re-export getClientIp from platform-core
+export { getClientIp } from '@digilogiclabs/platform-core/auth';
+
+/** Log an audit event (fire-and-forget) */
+export function auditAction(params: {
+  action: string;
+  actorId: string;
+  actorEmail?: string;
+  resourceType?: string;
+  resourceId?: string;
+  outcome?: 'success' | 'failure' | 'blocked';
+  metadata?: Record<string, unknown>;
+  request?: Request;
+}): void {
+  const category = inferCategory(params.action);
+  getAuditLog()
+    .then((log) =>
+      log.log({
+        action: params.action,
+        actor: {
+          id: params.actorId,
+          type: params.actorId === 'system' ? 'system' : 'user',
+          email: params.actorEmail,
+        },
+        resource: params.resourceType
+          ? { type: params.resourceType, id: params.resourceId }
+          : undefined,
+        outcome: params.outcome || 'success',
+        metadata: params.metadata,
+        category,
+        ip: params.request ? getClientIp(params.request) : undefined,
+        userAgent: params.request ? getUserAgent(params.request) : undefined,
+      })
+    )
+    .catch(() => {});
+}
+
+/** Log an admin action */
+export function auditAdminAction(
+  params: Omit<Parameters<typeof auditAction>[0], 'action'> & { action: string }
+): void {
+  auditAction({ ...params, action: `admin.${params.action}` });
+}
+
+/** Log a cron job action */
+export function auditCronAction(
+  params: Omit<Parameters<typeof auditAction>[0], 'actorId'> & { action: string }
+): void {
+  auditAction({ ...params, actorId: 'system', action: `cron.${params.action}` });
+}
+
+/** Capture an error (fire-and-forget) */
+export function captureError(error: unknown, context?: Record<string, unknown>): void {
+  try {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[${SERVICE_NAME}] Error:`, message, context || '');
+    if (stack && process.env.NODE_ENV === 'development') {
+      console.error(stack);
+    }
+  } catch {
+    // Silent fail — observability must never crash the app
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+function inferCategory(action: string): string {
+  if (action.startsWith('admin.')) return 'admin';
+  if (action.startsWith('payment.')) return 'billing';
+  if (action.startsWith('account.')) return 'data_mutation';
+  if (action.startsWith('auth.')) return 'authentication';
+  if (action.startsWith('cron.')) return 'system';
+  if (action.startsWith('security.')) return 'security';
+  return 'general';
+}

package/dist/templates/shared/payments/web/app/api/webhooks/stripe/route.ts

@@ -0,0 +1,109 @@
+/**
+ * Stripe Webhook Handler
+ *
+ * Handles Stripe webhook events for subscription lifecycle management.
+ * Uses HMAC signature verification and Redis-based idempotency.
+ *
+ * Required env vars:
+ *   STRIPE_SECRET_KEY      - Stripe API key
+ *   STRIPE_WEBHOOK_SECRET  - Webhook signing secret (whsec_...)
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import Stripe from 'stripe';
+import { getRedisClient } from '@/lib/redis';
+import { enforceRateLimit, AppRateLimits } from '@/lib/api-security';
+
+export const dynamic = 'force-dynamic';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2024-12-18.acacia',
+});
+
+/**
+ * Check if this webhook event has already been processed (idempotency).
+ * Uses Redis SET NX + EX pattern — atomic check-and-set with 24h TTL.
+ * Returns true if already processed, false if new.
+ */
+async function isEventProcessed(eventId: string): Promise<boolean> {
+  const redis = getRedisClient();
+  if (!redis) return false; // No Redis — allow processing (best-effort)
+  try {
+    const result = await redis.set(`webhook:${eventId}`, '1', 'EX', 86400, 'NX');
+    return result === null; // null = key already existed = already processed
+  } catch {
+    return false; // Redis error — allow processing
+  }
+}
+
+export async function POST(request: NextRequest) {
+  // Rate limit webhook calls (generous — Stripe retries on failure)
+  const rateLimited = await enforceRateLimit(request, 'stripe-webhook', AppRateLimits.webhook);
+  if (rateLimited) return rateLimited;
+
+  const body = await request.text();
+  const signature = request.headers.get('stripe-signature');
+
+  if (!signature) {
+    return NextResponse.json({ error: 'Missing signature' }, { status: 400 });
+  }
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+  } catch (err) {
+    console.error('[Stripe Webhook] Signature verification failed:', err);
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
+  }
+
+  // Idempotency check — prevent duplicate processing
+  if (await isEventProcessed(event.id)) {
+    return NextResponse.json({ received: true, duplicate: true });
+  }
+
+  try {
+    switch (event.type) {
+      case 'checkout.session.completed': {
+        const session = event.data.object as Stripe.Checkout.Session;
+        console.log('[Stripe Webhook] Checkout completed:', session.id);
+        // TODO: Activate subscription, provision access, send welcome email
+        break;
+      }
+
+      case 'invoice.paid': {
+        const invoice = event.data.object as Stripe.Invoice;
+        console.log('[Stripe Webhook] Invoice paid:', invoice.id);
+        // TODO: Record payment, extend subscription
+        break;
+      }
+
+      case 'invoice.payment_failed': {
+        const invoice = event.data.object as Stripe.Invoice;
+        console.log('[Stripe Webhook] Payment failed:', invoice.id);
+        // TODO: Notify user, start grace period
+        break;
+      }
+
+      case 'customer.subscription.updated': {
+        const subscription = event.data.object as Stripe.Subscription;
+        console.log('[Stripe Webhook] Subscription updated:', subscription.id);
+        // TODO: Handle plan changes, cancellation scheduling
+        break;
+      }
+
+      case 'customer.subscription.deleted': {
+        const subscription = event.data.object as Stripe.Subscription;
+        console.log('[Stripe Webhook] Subscription deleted:', subscription.id);
+        // TODO: Revoke access, send cancellation email
+        break;
+      }
+
+      default:
+        console.log(`[Stripe Webhook] Unhandled event type: ${event.type}`);
+    }
+
+    return NextResponse.json({ received: true });
+  } catch (error) {
+    console.error('[Stripe Webhook] Handler error:', error);
+    return NextResponse.json({ error: 'Webhook handler failed' }, { status: 500 });
+  }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Platform-Core Singleton
+ *
+ * Lazy-initialized platform instance with adapter auto-selection from env vars.
+ * Uses a promise-based lock to prevent race conditions during initialization.
+ *
+ * Usage:
+ *   import { getPlatform } from '@/lib/platform';
+ *   const platform = await getPlatform();
+ *   await platform.cache.set('key', value, 3600);
+ */
+import 'server-only';
+import { createPlatformAsync, type IPlatform } from '@digilogiclabs/platform-core';
+
+let _platform: IPlatform | null = null;
+let _initPromise: Promise<IPlatform> | null = null;
+
+/**
+ * Get or initialize the platform singleton.
+ * Adapters are selected automatically based on environment variables:
+ * - DATABASE_URL → PostgreSQL adapter
+ * - REDIS_URL → Redis cache adapter
+ * - RESEND_API_KEY → Resend email adapter
+ * Falls back to memory adapters when env vars are not set.
+ */
+export async function getPlatform(): Promise<IPlatform> {
+  if (_platform) return _platform;
+
+  if (!_initPromise) {
+    _initPromise = createPlatformAsync().then((p) => {
+      _platform = p;
+      return p;
+    });
+  }
+
+  return _initPromise;
+}

package/dist/templates/shared/redis/web/lib/rate-limit-store.ts

@@ -0,0 +1,18 @@
+import 'server-only';
+import { createRedisRateLimitStore } from '@digilogiclabs/platform-core/auth';
+import type { RateLimitStore } from '@digilogiclabs/platform-core/auth';
+import { getRedisClient } from './redis';
+
+let _store: RateLimitStore | null = null;
+
+/**
+ * Returns a Redis-backed rate limit store, or undefined to fall back to in-memory.
+ * The store is created lazily on first call and reused thereafter.
+ */
+export function getRateLimitStore(): RateLimitStore | undefined {
+  if (_store) return _store;
+  const redis = getRedisClient();
+  if (!redis) return undefined; // falls back to in-memory in enforceRateLimit
+  _store = createRedisRateLimitStore(redis, { keyPrefix: 'rl:' });
+  return _store;
+}

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

@@ -0,0 +1,48 @@
+import 'server-only';
+
+/**
+ * Minimal Redis client interface matching ioredis.
+ * Avoids importing ioredis at type-check time (may not be installed yet).
+ */
+interface RedisClient {
+  zremrangebyscore(key: string, min: number | string, max: number | string): Promise<number>;
+  zadd(key: string, score: number, member: string): Promise<number>;
+  zcard(key: string): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<string | null>;
+  ttl(key: string): Promise<number>;
+  setex(key: string, seconds: number, value: string): Promise<string>;
+  del(...keys: string[]): Promise<number>;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+}
+
+let _client: RedisClient | null = null;
+
+/**
+ * Lazy Redis client singleton.
+ * Returns null if REDIS_URL is not set or ioredis is not installed.
+ * Graceful degradation — rate limiting falls back to in-memory.
+ */
+export function getRedisClient(): RedisClient | null {
+  if (_client) return _client;
+  const url = process.env.REDIS_URL;
+  if (!url) return null;
+
+  try {
+    // Dynamic require — only loads if ioredis is installed
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const Redis = require('ioredis');
+    _client = new Redis(url, {
+      keyPrefix: process.env.REDIS_KEY_PREFIX || 'app:',
+      maxRetriesPerRequest: 3,
+      lazyConnect: true,
+    }) as RedisClient;
+    _client.connect().catch(() => {});
+    return _client;
+  } catch {
+    // ioredis not installed — graceful fallback
+    return null;
+  }
+}