@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-notifications/SKILL.md

@@ -0,0 +1,569 @@
+# Skill: Configure Notifications
+
+Add an in-app notification system with Prisma storage, API routes, client components, and optional email digests to a MARS application.
+
+## When to Use
+
+Use this skill when the user asks to add notifications, alerts, an activity feed, a notification bell, unread badges, or user messaging.
+
+## Prerequisites
+
+- `appConfig.features.notifications` set to `true` (add it if missing)
+- Prisma configured with a PostgreSQL database
+- Auth system set up (notifications are user-scoped)
+
+## Step 1: Prisma Schema
+
+```prisma
+// prisma/schema/notification.prisma
+model Notification {
+  id           String    @id @default(cuid())
+  userId       String
+  type         String
+  title        String
+  body         String?
+  resourceId   String?
+  resourceType String?
+  read         Boolean   @default(false)
+  readAt       DateTime?
+  createdAt    DateTime  @default(now())
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId, read])
+  @@index([userId, createdAt])
+}
+```
+
+Update the `User` model in `prisma/schema/auth.prisma` to add the relation:
+
+```prisma
+model User {
+  // ... existing fields
+  notifications Notification[]
+}
+```
+
+Run `yarn db:push` to sync.
+
+## Step 2: Define Notification Types
+
+```typescript
+// src/features/notifications/types.ts
+
+export const NOTIFICATION_TYPES = {
+  WELCOME: 'welcome',
+  BILLING_SUCCESS: 'billing_success',
+  BILLING_FAILED: 'billing_failed',
+  PASSWORD_CHANGED: 'password_changed',
+  ROLE_CHANGED: 'role_changed',
+  SYSTEM_ANNOUNCEMENT: 'system_announcement',
+} as const;
+
+export type NotificationType = (typeof NOTIFICATION_TYPES)[keyof typeof NOTIFICATION_TYPES];
+
+export interface NotificationPayload {
+  type: NotificationType;
+  title: string;
+  body?: string;
+  resourceId?: string;
+  resourceType?: string;
+}
+```
+
+## Step 3: Server Functions
+
+```typescript
+// src/features/notifications/server/index.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import type { NotificationType } from '../types';
+
+export async function createNotification(
+  userId: string,
+  type: NotificationType,
+  title: string,
+  body?: string,
+  resourceId?: string,
+  resourceType?: string,
+) {
+  return prisma.notification.create({
+    data: { userId, type, title, body, resourceId, resourceType },
+  });
+}
+
+export async function listNotifications(
+  userId: string,
+  options: { page?: number; limit?: number; unreadOnly?: boolean } = {},
+) {
+  const { page = 1, limit = 20, unreadOnly = false } = options;
+  const skip = (page - 1) * limit;
+
+  const where = {
+    userId,
+    ...(unreadOnly && { read: false }),
+  };
+
+  const [notifications, total] = await prisma.$transaction([
+    prisma.notification.findMany({
+      where,
+      orderBy: { createdAt: 'desc' },
+      skip,
+      take: limit,
+    }),
+    prisma.notification.count({ where }),
+  ]);
+
+  return {
+    notifications,
+    pagination: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+    },
+  };
+}
+
+export async function markAsRead(notificationId: string, userId: string) {
+  return prisma.notification.updateMany({
+    where: { id: notificationId, userId },
+    data: { read: true, readAt: new Date() },
+  });
+}
+
+export async function markAllAsRead(userId: string) {
+  return prisma.notification.updateMany({
+    where: { userId, read: false },
+    data: { read: true, readAt: new Date() },
+  });
+}
+
+export async function getUnreadCount(userId: string): Promise<number> {
+  return prisma.notification.count({
+    where: { userId, read: false },
+  });
+}
+```
+
+## Step 4: Validation Schemas
+
+```typescript
+// src/features/notifications/validation/schemas.ts
+import { z } from 'zod';
+
+export const notificationSchemas = {
+  list: z.object({
+    page: z.coerce.number().int().positive().default(1),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    unreadOnly: z.coerce.boolean().default(false),
+  }),
+};
+```
+
+## Step 5: API Routes
+
+### List Notifications
+
+```typescript
+// src/app/api/protected/notifications/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { listNotifications } from '@/features/notifications/server';
+import { notificationSchemas } from '@/features/notifications/validation/schemas';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const url = new URL(request.url);
+    const params = notificationSchemas.list.parse({
+      page: url.searchParams.get('page'),
+      limit: url.searchParams.get('limit'),
+      unreadOnly: url.searchParams.get('unreadOnly'),
+    });
+
+    const result = await listNotifications(request.session.userId, params);
+    return NextResponse.json(result);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/notifications' });
+  }
+});
+```
+
+### Mark One as Read
+
+```typescript
+// src/app/api/protected/notifications/[id]/read/route.ts
+import { handleApiError, withAuth, type AuthenticatedRequest } from '@/lib/mars';
+import { markAsRead } from '@/features/notifications/server';
+import { NextResponse } from 'next/server';
+
+export const PATCH = withAuth(
+  async (request: AuthenticatedRequest, { params }: { params: { id: string } }) => {
+    try {
+      await markAsRead(params.id, request.session.userId);
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      return handleApiError(error, { endpoint: '/api/protected/notifications/[id]/read' });
+    }
+  },
+);
+```
+
+### Mark All as Read
+
+```typescript
+// src/app/api/protected/notifications/read-all/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { markAllAsRead } from '@/features/notifications/server';
+import { NextResponse } from 'next/server';
+
+export const PATCH = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    await markAllAsRead(request.session.userId);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/notifications/read-all' });
+  }
+});
+```
+
+### Unread Count
+
+```typescript
+// src/app/api/protected/notifications/count/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { getUnreadCount } from '@/features/notifications/server';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const count = await getUnreadCount(request.session.userId);
+    return NextResponse.json({ count });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/notifications/count' });
+  }
+});
+```
+
+## Step 6: Client Components
+
+### useNotifications Hook
+
+```typescript
+// src/features/notifications/hooks/use-notifications.ts
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+
+interface Notification {
+  id: string;
+  type: string;
+  title: string;
+  body: string | null;
+  resourceId: string | null;
+  resourceType: string | null;
+  read: boolean;
+  readAt: string | null;
+  createdAt: string;
+}
+
+interface UseNotificationsOptions {
+  pollInterval?: number;
+}
+
+export function useNotifications(options: UseNotificationsOptions = {}) {
+  const { pollInterval = 30_000 } = options;
+  const [notifications, setNotifications] = useState<Notification[]>([]);
+  const [unreadCount, setUnreadCount] = useState(0);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const fetchNotifications = useCallback(async () => {
+    try {
+      const res = await fetch('/api/protected/notifications?limit=20');
+      if (!res.ok) return;
+      const data = await res.json();
+      setNotifications(data.notifications);
+    } catch {
+      // Silently fail — polling will retry
+    }
+  }, []);
+
+  const fetchUnreadCount = useCallback(async () => {
+    try {
+      const res = await fetch('/api/protected/notifications/count');
+      if (!res.ok) return;
+      const data = await res.json();
+      setUnreadCount(data.count);
+    } catch {
+      // Silently fail
+    }
+  }, []);
+
+  const markAsRead = useCallback(async (id: string) => {
+    await fetch(`/api/protected/notifications/${id}/read`, { method: 'PATCH' });
+    setNotifications((prev) =>
+      prev.map((n) => (n.id === id ? { ...n, read: true, readAt: new Date().toISOString() } : n)),
+    );
+    setUnreadCount((prev) => Math.max(0, prev - 1));
+  }, []);
+
+  const markAllAsRead = useCallback(async () => {
+    await fetch('/api/protected/notifications/read-all', { method: 'PATCH' });
+    setNotifications((prev) => prev.map((n) => ({ ...n, read: true, readAt: new Date().toISOString() })));
+    setUnreadCount(0);
+  }, []);
+
+  useEffect(() => {
+    setIsLoading(true);
+    Promise.all([fetchNotifications(), fetchUnreadCount()]).finally(() => setIsLoading(false));
+
+    const interval = setInterval(() => {
+      fetchUnreadCount();
+    }, pollInterval);
+
+    return () => clearInterval(interval);
+  }, [fetchNotifications, fetchUnreadCount, pollInterval]);
+
+  return { notifications, unreadCount, isLoading, markAsRead, markAllAsRead, refetch: fetchNotifications };
+}
+```
+
+### NotificationBell Component
+
+```typescript
+// src/features/notifications/components/notification-bell.tsx
+'use client';
+
+import { useNotifications } from '../hooks/use-notifications';
+import { Button } from '@mars-stack/ui';
+
+interface NotificationBellProps {
+  onOpen: () => void;
+}
+
+export function NotificationBell({ onOpen }: NotificationBellProps) {
+  const { unreadCount } = useNotifications();
+
+  return (
+    <Button variant="ghost" size="icon" onClick={onOpen} aria-label="Notifications" className="relative">
+      <BellIcon className="h-5 w-5" />
+      {unreadCount > 0 && (
+        <span className="absolute -top-1 -right-1 flex h-5 w-5 items-center justify-center rounded-full bg-brand-primary text-xs text-white">
+          {unreadCount > 99 ? '99+' : unreadCount}
+        </span>
+      )}
+    </Button>
+  );
+}
+
+function BellIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor" className={className}>
+      <path strokeLinecap="round" strokeLinejoin="round" d="M14.857 17.082a23.848 23.848 0 0 0 5.454-1.31A8.967 8.967 0 0 1 18 9.75V9A6 6 0 0 0 6 9v.75a8.967 8.967 0 0 1-2.312 6.022c1.733.64 3.56 1.085 5.455 1.31m5.714 0a24.255 24.255 0 0 1-5.714 0m5.714 0a3 3 0 1 1-5.714 0" />
+    </svg>
+  );
+}
+```
+
+### NotificationPanel Component
+
+```typescript
+// src/features/notifications/components/notification-panel.tsx
+'use client';
+
+import { useNotifications } from '../hooks/use-notifications';
+import { Button } from '@mars-stack/ui';
+import { formatDistanceToNow } from 'date-fns';
+
+interface NotificationPanelProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export function NotificationPanel({ isOpen, onClose }: NotificationPanelProps) {
+  const { notifications, isLoading, markAsRead, markAllAsRead } = useNotifications();
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="absolute right-0 top-full mt-2 w-96 rounded-lg border border-border-default bg-surface-card shadow-lg z-50">
+      <div className="flex items-center justify-between border-b border-border-default p-4">
+        <h3 className="text-sm font-semibold text-text-primary">Notifications</h3>
+        <Button variant="ghost" size="sm" onClick={markAllAsRead}>
+          Mark all as read
+        </Button>
+      </div>
+
+      <div className="max-h-96 overflow-y-auto">
+        {isLoading ? (
+          <div className="p-4 text-center text-text-muted text-sm">Loading…</div>
+        ) : notifications.length === 0 ? (
+          <div className="p-8 text-center text-text-muted text-sm">No notifications</div>
+        ) : (
+          notifications.map((notification) => (
+            <button
+              key={notification.id}
+              onClick={() => markAsRead(notification.id)}
+              className={`w-full text-left p-4 border-b border-border-default hover:bg-ghost-hover transition-colors ${
+                !notification.read ? 'bg-surface-input/50' : ''
+              }`}
+            >
+              <div className="flex items-start gap-3">
+                {!notification.read && (
+                  <span className="mt-1.5 h-2 w-2 shrink-0 rounded-full bg-brand-primary" />
+                )}
+                <div className="flex-1 min-w-0">
+                  <p className="text-sm font-medium text-text-primary truncate">
+                    {notification.title}
+                  </p>
+                  {notification.body && (
+                    <p className="text-sm text-text-secondary mt-0.5 line-clamp-2">
+                      {notification.body}
+                    </p>
+                  )}
+                  <p className="text-xs text-text-muted mt-1">
+                    {formatDistanceToNow(new Date(notification.createdAt), { addSuffix: true })}
+                  </p>
+                </div>
+              </div>
+            </button>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+## Step 7: Trigger Notifications from Other Features
+
+```typescript
+import { createNotification } from '@/features/notifications/server';
+import { NOTIFICATION_TYPES } from '@/features/notifications/types';
+
+// After a successful password change
+await createNotification(
+  userId,
+  NOTIFICATION_TYPES.PASSWORD_CHANGED,
+  'Password changed',
+  'Your password was successfully updated. If this wasn't you, contact support immediately.',
+);
+
+// After a billing event
+await createNotification(
+  userId,
+  NOTIFICATION_TYPES.BILLING_SUCCESS,
+  'Payment successful',
+  `Your subscription payment of $${amount} was processed.`,
+  subscriptionId,
+  'subscription',
+);
+```
+
+## Step 8: Email Digest (Optional)
+
+If the `configure-jobs` skill is set up, add a daily digest job:
+
+```typescript
+// src/features/notifications/server/digest.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import { sendEmail } from '@/lib/mars';
+
+export async function sendNotificationDigest(userId: string): Promise<void> {
+  const since = new Date(Date.now() - 24 * 60 * 60 * 1000);
+
+  const unread = await prisma.notification.findMany({
+    where: { userId, read: false, createdAt: { gte: since } },
+    orderBy: { createdAt: 'desc' },
+    take: 20,
+  });
+
+  if (unread.length === 0) return;
+
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { email: true, name: true },
+  });
+
+  if (!user) return;
+
+  const summaryItems = unread.map((n) => `• ${n.title}${n.body ? `: ${n.body}` : ''}`).join('\n');
+
+  await sendEmail({
+    to: user.email,
+    subject: `You have ${unread.length} unread notification${unread.length > 1 ? 's' : ''}`,
+    text: `Hi ${user.name ?? 'there'},\n\nHere's your daily notification summary:\n\n${summaryItems}\n\nView all notifications in your dashboard.`,
+  });
+}
+```
+
+## Step 9: Feature Directory Structure
+
+```
+src/features/notifications/
+├── types.ts                    # NotificationType, NotificationPayload
+├── server/
+│   ├── index.ts                # CRUD functions (createNotification, listNotifications, etc.)
+│   └── digest.ts               # Email digest sender (optional)
+├── hooks/
+│   └── use-notifications.ts    # Client-side hook with polling
+├── components/
+│   ├── notification-bell.tsx   # Bell icon with unread badge
+│   └── notification-panel.tsx  # Dropdown notification list
+└── validation/
+    └── schemas.ts              # Zod schemas for API input
+
+src/app/api/protected/notifications/
+├── route.ts                    # GET - list notifications
+├── [id]/
+│   └── read/
+│       └── route.ts            # PATCH - mark one as read
+├── read-all/
+│   └── route.ts                # PATCH - mark all as read
+└── count/
+    └── route.ts                # GET - unread count
+```
+
+## Tests
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GET } from './route';
+import { mockAuth } from '@mars-stack/core/test-utils';
+
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    notification: {
+      findMany: vi.fn(),
+      count: vi.fn(),
+      create: vi.fn(),
+      updateMany: vi.fn(),
+    },
+    $transaction: vi.fn((fns: (() => unknown)[]) => Promise.all(fns.map((fn) => fn()))),
+  },
+}));
+
+vi.mock('@/lib/mars', () => ({
+  verifySessionForAPI: vi.fn(() => Promise.resolve(mockAuth)),
+  handleApiError: vi.fn((error: Error) => Response.json({ error: error.message }, { status: 500 })),
+}));
+```
+
+## Checklist
+
+- [ ] Prisma `Notification` model added and `db:push` run
+- [ ] User model updated with `notifications` relation
+- [ ] Notification types defined in `types.ts`
+- [ ] Server functions import `'server-only'`
+- [ ] All queries scoped by session `userId`
+- [ ] API routes use `withAuth` / `withAuthNoParams` and `handleApiError`
+- [ ] Zod validation on list parameters
+- [ ] `useNotifications` hook with polling
+- [ ] `NotificationBell` and `NotificationPanel` components created
+- [ ] Bell integrated into the authenticated layout header
+- [ ] Feature flag checked (`appConfig.features.notifications`)
+- [ ] Email digest function created (optional, requires email provider)
+- [ ] Tests written for API routes