@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/notification-patterns.md

@@ -0,0 +1,348 @@
+---
+name: notification-patterns
+description: Notification patterns for push, email, SMS, in-app notifications, user preference management, and batching strategies.
+---
+
+# Notification Patterns
+
+## When to Use
+Implement a notification system when your application needs to inform users about events through multiple channels: push notifications, email, SMS, and in-app alerts. These patterns cover channel abstraction, user preference management, batching to prevent notification fatigue, and reliable delivery with retry logic. Apply these patterns early to avoid building channel-specific silos that are hard to unify later.
+
+## How It Works
+
+### Notification Service Architecture
+
+```typescript
+// src/notifications/types.ts
+export interface Notification {
+  id: string;
+  userId: string;
+  type: NotificationType;
+  title: string;
+  body: string;
+  data?: Record<string, unknown>;
+  channels: Channel[];
+  priority: 'urgent' | 'high' | 'normal' | 'low';
+  groupKey?: string;  // for batching related notifications
+}
+
+export type NotificationType =
+  | 'order.confirmed' | 'order.shipped' | 'order.delivered'
+  | 'comment.reply' | 'comment.mention'
+  | 'billing.invoice' | 'billing.failed'
+  | 'security.login' | 'security.password_changed';
+
+export type Channel = 'push' | 'email' | 'sms' | 'in_app';
+
+export interface ChannelProvider {
+  send(notification: Notification, recipient: Recipient): Promise<DeliveryResult>;
+}
+
+export interface DeliveryResult {
+  channel: Channel;
+  success: boolean;
+  externalId?: string;
+  error?: string;
+}
+
+export interface Recipient {
+  userId: string;
+  email?: string;
+  phone?: string;
+  pushTokens?: string[];
+}
+```
+
+### Channel Providers
+
+```typescript
+// src/notifications/channels/email.ts
+import { Resend } from 'resend';
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export const emailProvider: ChannelProvider = {
+  async send(notification, recipient) {
+    if (!recipient.email) {
+      return { channel: 'email', success: false, error: 'No email address' };
+    }
+
+    try {
+      const result = await resend.emails.send({
+        from: 'MyApp <notifications@myapp.com>',
+        to: recipient.email,
+        subject: notification.title,
+        html: renderEmailTemplate(notification),
+      });
+
+      return { channel: 'email', success: true, externalId: result.id };
+    } catch (err) {
+      return { channel: 'email', success: false, error: (err as Error).message };
+    }
+  },
+};
+
+// src/notifications/channels/push.ts
+import admin from 'firebase-admin';
+
+export const pushProvider: ChannelProvider = {
+  async send(notification, recipient) {
+    if (!recipient.pushTokens?.length) {
+      return { channel: 'push', success: false, error: 'No push tokens' };
+    }
+
+    try {
+      const response = await admin.messaging().sendEachForMulticast({
+        tokens: recipient.pushTokens,
+        notification: { title: notification.title, body: notification.body },
+        data: notification.data as Record<string, string> ?? {},
+        android: { priority: notification.priority === 'urgent' ? 'high' : 'normal' },
+        apns: {
+          payload: { aps: { sound: notification.priority === 'urgent' ? 'default' : undefined } },
+        },
+      });
+
+      return {
+        channel: 'push',
+        success: response.successCount > 0,
+        error: response.failureCount > 0 ? `${response.failureCount} tokens failed` : undefined,
+      };
+    } catch (err) {
+      return { channel: 'push', success: false, error: (err as Error).message };
+    }
+  },
+};
+
+// src/notifications/channels/sms.ts
+import twilio from 'twilio';
+
+const client = twilio(process.env.TWILIO_SID, process.env.TWILIO_AUTH_TOKEN);
+
+export const smsProvider: ChannelProvider = {
+  async send(notification, recipient) {
+    if (!recipient.phone) {
+      return { channel: 'sms', success: false, error: 'No phone number' };
+    }
+
+    try {
+      const msg = await client.messages.create({
+        body: `${notification.title}: ${notification.body}`,
+        from: process.env.TWILIO_PHONE_NUMBER,
+        to: recipient.phone,
+      });
+
+      return { channel: 'sms', success: true, externalId: msg.sid };
+    } catch (err) {
+      return { channel: 'sms', success: false, error: (err as Error).message };
+    }
+  },
+};
+```
+
+### User Preference Management
+
+```typescript
+// src/notifications/preferences.ts
+interface NotificationPreferences {
+  userId: string;
+  channels: {
+    email: boolean;
+    push: boolean;
+    sms: boolean;
+    in_app: boolean;
+  };
+  types: Partial<Record<NotificationType, {
+    enabled: boolean;
+    channels?: Channel[];
+  }>>;
+  quietHours?: { start: string; end: string; timezone: string };
+  batchDigest?: 'none' | 'hourly' | 'daily';
+}
+
+export async function getEffectiveChannels(
+  userId: string,
+  type: NotificationType,
+  requestedChannels: Channel[]
+): Promise<Channel[]> {
+  const prefs = await getPreferences(userId);
+
+  return requestedChannels.filter((channel) => {
+    // Global channel toggle
+    if (!prefs.channels[channel]) return false;
+
+    // Per-type override
+    const typePrefs = prefs.types[type];
+    if (typePrefs?.enabled === false) return false;
+    if (typePrefs?.channels && !typePrefs.channels.includes(channel)) return false;
+
+    // Quiet hours (skip push/sms, keep email/in_app)
+    if (prefs.quietHours && (channel === 'push' || channel === 'sms')) {
+      if (isInQuietHours(prefs.quietHours)) return false;
+    }
+
+    return true;
+  });
+}
+
+function isInQuietHours(qh: { start: string; end: string; timezone: string }): boolean {
+  const now = new Date().toLocaleTimeString('en-US', {
+    hour12: false, timeZone: qh.timezone,
+  });
+  return now >= qh.start || now <= qh.end;
+}
+```
+
+### Notification Dispatcher
+
+```typescript
+// src/notifications/dispatcher.ts
+import { emailProvider, pushProvider, smsProvider } from './channels';
+
+const providers: Record<Channel, ChannelProvider> = {
+  email: emailProvider,
+  push: pushProvider,
+  sms: smsProvider,
+  in_app: inAppProvider,
+};
+
+export async function dispatch(notification: Notification): Promise<DeliveryResult[]> {
+  const recipient = await getRecipient(notification.userId);
+  const channels = await getEffectiveChannels(
+    notification.userId,
+    notification.type,
+    notification.channels
+  );
+
+  if (channels.length === 0) {
+    await logDelivery(notification.id, [{ channel: 'none' as Channel, success: false, error: 'All channels filtered by preferences' }]);
+    return [];
+  }
+
+  const results = await Promise.allSettled(
+    channels.map(async (channel) => {
+      const provider = providers[channel];
+      const result = await provider.send(notification, recipient);
+
+      await logDelivery(notification.id, [result]);
+      return result;
+    })
+  );
+
+  return results.map((r) =>
+    r.status === 'fulfilled' ? r.value : { channel: 'unknown' as Channel, success: false, error: (r.reason as Error).message }
+  );
+}
+```
+
+### In-App Notifications with Real-Time
+
+```typescript
+// src/notifications/channels/in-app.ts
+export const inAppProvider: ChannelProvider = {
+  async send(notification, recipient) {
+    // Store in database
+    const stored = await db.query(
+      `INSERT INTO notifications (id, user_id, type, title, body, data, read, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6, false, NOW()) RETURNING id`,
+      [notification.id, recipient.userId, notification.type, notification.title, notification.body, JSON.stringify(notification.data)]
+    );
+
+    // Push via WebSocket/SSE
+    emitToUser(recipient.userId, 'notification:new', {
+      id: stored.rows[0].id,
+      type: notification.type,
+      title: notification.title,
+      body: notification.body,
+      createdAt: new Date().toISOString(),
+    });
+
+    return { channel: 'in_app', success: true, externalId: stored.rows[0].id };
+  },
+};
+
+// API endpoints
+app.get('/api/notifications', async (req, res) => {
+  const userId = req.userId;
+  const { cursor, limit = 20 } = req.query;
+
+  const notifications = await db.query(
+    `SELECT * FROM notifications WHERE user_id = $1
+     ${cursor ? 'AND created_at < $3' : ''}
+     ORDER BY created_at DESC LIMIT $2`,
+    cursor ? [userId, limit, cursor] : [userId, limit]
+  );
+
+  res.json({
+    items: notifications.rows,
+    unreadCount: await getUnreadCount(userId),
+  });
+});
+
+app.post('/api/notifications/:id/read', async (req, res) => {
+  await db.query('UPDATE notifications SET read = true WHERE id = $1 AND user_id = $2',
+    [req.params.id, req.userId]);
+  res.json({ success: true });
+});
+
+app.post('/api/notifications/read-all', async (req, res) => {
+  await db.query('UPDATE notifications SET read = true WHERE user_id = $1 AND read = false',
+    [req.userId]);
+  res.json({ success: true });
+});
+```
+
+### Notification Batching
+
+```typescript
+// src/notifications/batcher.ts
+const pendingBatches = new Map<string, Notification[]>();
+
+export function addToBatch(notification: Notification) {
+  const key = `${notification.userId}:${notification.groupKey}`;
+  const batch = pendingBatches.get(key) ?? [];
+  batch.push(notification);
+  pendingBatches.set(key, batch);
+}
+
+// Flush batches periodically
+setInterval(async () => {
+  for (const [key, batch] of pendingBatches.entries()) {
+    if (batch.length === 0) continue;
+
+    pendingBatches.delete(key);
+
+    if (batch.length === 1) {
+      await dispatch(batch[0]);
+    } else {
+      // Merge into digest
+      const digest: Notification = {
+        ...batch[0],
+        title: `${batch.length} new ${batch[0].groupKey} notifications`,
+        body: batch.map((n) => n.title).join('\n'),
+        data: { count: batch.length, items: batch.map((n) => n.data) },
+      };
+      await dispatch(digest);
+    }
+  }
+}, 5 * 60_000); // flush every 5 minutes
+```
+
+## Examples
+
+| Notification Type | Channels | Priority | Batching |
+|------------------|----------|----------|----------|
+| `security.login` | push, email | urgent | Never |
+| `order.shipped` | push, email, sms | high | Never |
+| `comment.reply` | push, in_app | normal | 5-minute window |
+| `comment.mention` | push, email, in_app | normal | 5-minute window |
+| `billing.invoice` | email | normal | Never |
+
+## Checklist
+- [ ] Channel abstraction allows adding new providers without changing dispatch logic
+- [ ] User preferences control which channels and notification types are enabled
+- [ ] Quiet hours suppress push and SMS during configured periods
+- [ ] In-app notifications stored in database with real-time WebSocket delivery
+- [ ] Batching groups related notifications to prevent alert fatigue
+- [ ] Delivery results logged for debugging and analytics
+- [ ] Failed deliveries retried via queue with exponential backoff
+- [ ] Unsubscribe links included in all email notifications

package/assets/skills/oauth-patterns.md

@@ -0,0 +1,246 @@
+---
+name: oauth-patterns
+description: OAuth 2.0 patterns with authorization code flow, PKCE, scopes, token refresh, and social login.
+---
+
+# OAuth 2.0 Patterns
+
+## When to Use
+Apply when implementing "Sign in with Google/GitHub/etc." social login, building an API that third parties will authenticate against, or integrating with any service that uses OAuth 2.0. Always use Authorization Code flow with PKCE for web and mobile apps. Never use the Implicit flow -- it is deprecated and insecure.
+
+## How It Works
+
+### Authorization Code Flow with PKCE
+
+The standard flow for web apps and SPAs:
+
+```typescript
+import crypto from "crypto";
+
+// Step 1: Generate PKCE verifier and challenge
+function generatePKCE() {
+  const verifier = crypto.randomBytes(32).toString("base64url");
+  const challenge = crypto
+    .createHash("sha256")
+    .update(verifier)
+    .digest("base64url");
+  return { verifier, challenge };
+}
+
+// Step 2: Redirect user to authorization endpoint
+app.get("/auth/login/google", (req, res) => {
+  const { verifier, challenge } = generatePKCE();
+  const state = crypto.randomBytes(16).toString("hex");
+
+  // Store verifier and state in session (not in URL)
+  req.session.pkceVerifier = verifier;
+  req.session.oauthState = state;
+
+  const params = new URLSearchParams({
+    client_id: process.env.GOOGLE_CLIENT_ID!,
+    redirect_uri: `${process.env.APP_URL}/auth/callback/google`,
+    response_type: "code",
+    scope: "openid email profile",
+    state,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+  });
+
+  res.redirect(`https://accounts.google.com/o/oauth2/v2/auth?${params}`);
+});
+
+// Step 3: Handle the callback
+app.get("/auth/callback/google", async (req, res) => {
+  const { code, state } = req.query;
+
+  // Verify state to prevent CSRF
+  if (state !== req.session.oauthState) {
+    return res.status(403).send("Invalid state parameter");
+  }
+
+  // Exchange code for tokens
+  const tokenResponse = await fetch("https://oauth2.googleapis.com/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: process.env.GOOGLE_CLIENT_ID!,
+      client_secret: process.env.GOOGLE_CLIENT_SECRET!,
+      code: code as string,
+      grant_type: "authorization_code",
+      redirect_uri: `${process.env.APP_URL}/auth/callback/google`,
+      code_verifier: req.session.pkceVerifier,
+    }),
+  });
+
+  const tokens = await tokenResponse.json();
+  // tokens: { access_token, refresh_token, id_token, expires_in }
+
+  // Step 4: Get user info from ID token or userinfo endpoint
+  const userInfo = await fetch("https://www.googleapis.com/oauth2/v3/userinfo", {
+    headers: { Authorization: `Bearer ${tokens.access_token}` },
+  }).then((r) => r.json());
+
+  // Step 5: Find or create user in your database
+  let user = await db.users.findByEmail(userInfo.email);
+  if (!user) {
+    user = await db.users.create({
+      email: userInfo.email,
+      name: userInfo.name,
+      avatarUrl: userInfo.picture,
+      provider: "google",
+      providerId: userInfo.sub,
+    });
+  }
+
+  // Step 6: Create your own session
+  req.session.userId = user.id;
+  res.redirect("/dashboard");
+});
+```
+
+### Social Login with NextAuth.js (Auth.js)
+
+```typescript
+// app/api/auth/[...nextauth]/route.ts
+import NextAuth from "next-auth";
+import GoogleProvider from "next-auth/providers/google";
+import GitHubProvider from "next-auth/providers/github";
+import { PrismaAdapter } from "@auth/prisma-adapter";
+import { prisma } from "@/lib/prisma";
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  adapter: PrismaAdapter(prisma),
+  providers: [
+    GoogleProvider({
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    }),
+    GitHubProvider({
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    }),
+  ],
+  callbacks: {
+    async session({ session, user }) {
+      session.user.id = user.id;
+      session.user.role = user.role;
+      return session;
+    },
+  },
+});
+```
+
+### Token Refresh
+
+```typescript
+async function refreshAccessToken(refreshToken: string): Promise<TokenSet> {
+  const response = await fetch("https://oauth2.googleapis.com/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: process.env.GOOGLE_CLIENT_ID!,
+      client_secret: process.env.GOOGLE_CLIENT_SECRET!,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error("Token refresh failed -- user must re-authenticate");
+  }
+
+  return response.json();
+}
+
+// Middleware that auto-refreshes expired tokens
+async function ensureValidToken(req: Request): Promise<string> {
+  const session = await getSession(req);
+  if (session.accessTokenExpires > Date.now()) {
+    return session.accessToken;
+  }
+
+  const newTokens = await refreshAccessToken(session.refreshToken);
+  await updateSession(req, {
+    accessToken: newTokens.access_token,
+    accessTokenExpires: Date.now() + newTokens.expires_in * 1000,
+    refreshToken: newTokens.refresh_token ?? session.refreshToken,
+  });
+  return newTokens.access_token;
+}
+```
+
+### Scopes -- Request Only What You Need
+
+```typescript
+// Minimal scopes for login
+const LOGIN_SCOPES = "openid email profile";
+
+// Additional scopes requested later (progressive consent)
+const CALENDAR_SCOPES = "https://www.googleapis.com/auth/calendar.readonly";
+const DRIVE_SCOPES = "https://www.googleapis.com/auth/drive.file";
+
+// Request additional scopes when the user needs the feature
+app.get("/auth/connect/calendar", (req, res) => {
+  const params = new URLSearchParams({
+    client_id: process.env.GOOGLE_CLIENT_ID!,
+    redirect_uri: `${process.env.APP_URL}/auth/callback/google`,
+    response_type: "code",
+    scope: `${LOGIN_SCOPES} ${CALENDAR_SCOPES}`,
+    access_type: "offline",
+    prompt: "consent",     // force consent screen for new scopes
+    login_hint: req.user.email,
+  });
+  res.redirect(`https://accounts.google.com/o/oauth2/v2/auth?${params}`);
+});
+```
+
+### Building Your Own OAuth Provider
+
+```typescript
+// Issue authorization codes and access tokens for your API
+import { randomBytes } from "crypto";
+
+app.get("/oauth/authorize", async (req, res) => {
+  const { client_id, redirect_uri, scope, state, code_challenge } = req.query;
+
+  const client = await db.oauthClients.findById(client_id as string);
+  if (!client || !client.redirectUris.includes(redirect_uri as string)) {
+    return res.status(400).json({ error: "invalid_client" });
+  }
+
+  // Show consent screen, then on approval:
+  const code = randomBytes(32).toString("hex");
+  await db.authCodes.create({
+    code,
+    clientId: client_id as string,
+    userId: req.user.id,
+    scope: scope as string,
+    codeChallenge: code_challenge as string,
+    expiresAt: new Date(Date.now() + 10 * 60 * 1000),
+  });
+
+  const callbackUrl = new URL(redirect_uri as string);
+  callbackUrl.searchParams.set("code", code);
+  callbackUrl.searchParams.set("state", state as string);
+  res.redirect(callbackUrl.toString());
+});
+```
+
+## Examples
+
+| Flow | When | Security |
+|------|------|----------|
+| Authorization Code + PKCE | Web apps, SPAs, mobile | Best -- prevents code interception |
+| Client Credentials | Server-to-server (no user) | Service accounts |
+| Device Authorization | Smart TV, CLI tools | Limited input devices |
+| Refresh Token | Long-lived sessions | Silent re-auth without login |
+
+## Checklist
+- [ ] Authorization Code flow with PKCE used for all user-facing auth
+- [ ] State parameter validated to prevent CSRF attacks
+- [ ] PKCE verifier stored server-side (session), never in URL
+- [ ] Refresh tokens stored securely (encrypted, httpOnly cookie or DB)
+- [ ] Token refresh happens automatically before expiration
+- [ ] Scopes requested incrementally (progressive consent)
+- [ ] OAuth client secrets never exposed to the browser
+- [ ] Redirect URIs validated against registered allowlist