@prmichaelsen/acp-visualizer 0.1.0 → 0.1.2

package/agent/patterns/tanstack-cloudflare.email-service.md

@@ -1,431 +0,0 @@
-# Email Service Pattern
-
-**Category**: Architecture
-**Applicable To**: TanStack Start + Cloudflare Workers applications that send transactional emails
-**Status**: Stable
-
----
-
-## Overview
-
-This pattern provides a lightweight, provider-agnostic email service for sending transactional emails (notifications, digests, confirmations, password resets) from Cloudflare Workers. It wraps email API providers (Mandrill, SendGrid, Resend, etc.) behind a simple `sendEmail({ to, subject, html })` interface and includes HTML template builders for common email types.
-
-The pattern enforces non-blocking email sending — email failures are logged but never crash the calling operation. A user creating a post should never fail because the notification email couldn't be sent.
-
----
-
-## When to Use This Pattern
-
-✅ **Use this pattern when:**
-- Need to send transactional emails (confirmations, notifications, digests)
-- Using a third-party email API (Mandrill, SendGrid, Resend, Mailgun)
-- Want a simple, mockable email interface
-- Need HTML email templates
-
-❌ **Don't use this pattern when:**
-- Only sending emails via a marketing platform (Mailchimp campaigns)
-- Using a full email framework (Nodemailer with SMTP — not available on Workers)
-- Email is not a feature of your application
-
----
-
-## Core Principles
-
-1. **Simple Interface**: `sendEmail({ to, subject, html })` — nothing more
-2. **Non-Blocking**: Email failures logged but never thrown — don't crash user flows
-3. **Provider-Agnostic**: Wrap any email API behind the same interface
-4. **Template Builders**: Separate functions build HTML content
-5. **Server-Side Only**: Email sending only from API routes, cron jobs, and server functions
-6. **Secrets via Environment**: API keys stored as Cloudflare secrets, never hardcoded
-
----
-
-## Implementation
-
-### Structure
-
-```
-src/lib/
-├── email/
-│   ├── send-email.ts          # Core send function
-│   ├── templates/
-│   │   ├── base.ts            # Base HTML wrapper
-│   │   ├── welcome.ts         # Welcome email template
-│   │   ├── daily-digest.ts    # Daily digest template
-│   │   ├── appointment.ts     # Appointment notification
-│   │   └── password-reset.ts  # Password reset template
-│   └── index.ts               # Barrel export
-```
-
-### Code Example
-
-#### Step 1: Core Send Function
-
-```typescript
-// src/lib/email/send-email.ts
-
-const MANDRILL_API_URL = 'https://mandrillapp.com/api/1.0/messages/send'
-
-interface SendEmailParams {
-  to: string | string[]
-  subject: string
-  html: string
-  from?: string
-  fromName?: string
-}
-
-interface SendEmailResult {
-  success: boolean
-  error?: string
-}
-
-/**
- * Send a transactional email via Mandrill.
- * Non-blocking: logs errors but never throws.
- */
-export async function sendEmail(params: SendEmailParams): Promise<SendEmailResult> {
-  const apiKey = process.env.MANDRILL_API_KEY
-
-  if (!apiKey) {
-    console.error('[Email] Mandrill API key not configured')
-    return { success: false, error: 'API key not configured' }
-  }
-
-  const recipients = Array.isArray(params.to)
-    ? params.to.map(email => ({ email, type: 'to' as const }))
-    : [{ email: params.to, type: 'to' as const }]
-
-  try {
-    const response = await fetch(MANDRILL_API_URL, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        key: apiKey,
-        message: {
-          html: params.html,
-          subject: params.subject,
-          from_email: params.from || 'noreply@example.com',
-          from_name: params.fromName || 'My App',
-          to: recipients,
-          important: true,
-          track_opens: true,
-          track_clicks: true,
-          auto_text: true,
-        },
-      }),
-    })
-
-    if (!response.ok) {
-      const error = await response.text()
-      console.error('[Email] Send failed:', error)
-      return { success: false, error }
-    }
-
-    const data = await response.json()
-    console.log(`[Email] Sent "${params.subject}" to ${recipients.length} recipient(s)`)
-    return { success: true }
-  } catch (error) {
-    console.error('[Email] Send error:', error)
-    return { success: false, error: error instanceof Error ? error.message : 'Unknown error' }
-  }
-}
-```
-
-#### Step 2: Base HTML Template
-
-```typescript
-// src/lib/email/templates/base.ts
-
-interface BaseTemplateParams {
-  title: string
-  body: string
-  footerText?: string
-}
-
-/**
- * Base HTML email wrapper with consistent styling
- */
-export function baseTemplate({ title, body, footerText }: BaseTemplateParams): string {
-  return `<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${title}</title>
-  <style>
-    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 0; background: #f5f5f5; }
-    .container { max-width: 600px; margin: 0 auto; padding: 20px; }
-    .card { background: #ffffff; border-radius: 8px; padding: 32px; margin: 20px 0; }
-    .header { text-align: center; padding-bottom: 20px; border-bottom: 1px solid #eee; margin-bottom: 20px; }
-    .footer { text-align: center; color: #888; font-size: 12px; padding: 20px 0; }
-    h1 { color: #333; font-size: 24px; margin: 0; }
-    p { color: #555; line-height: 1.6; }
-    .btn { display: inline-block; background: #3b82f6; color: #fff; padding: 12px 24px; border-radius: 6px; text-decoration: none; font-weight: 600; }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <div class="card">
-      <div class="header">
-        <h1>${title}</h1>
-      </div>
-      ${body}
-    </div>
-    <div class="footer">
-      ${footerText || 'You are receiving this because you have an account with us.'}
-    </div>
-  </div>
-</body>
-</html>`
-}
-```
-
-#### Step 3: Domain-Specific Template
-
-```typescript
-// src/lib/email/templates/daily-digest.ts
-
-import { baseTemplate } from './base'
-
-interface DigestData {
-  checkIns: { guestName: string; property: string }[]
-  checkOuts: { guestName: string; property: string }[]
-  unclaimedCleans: { property: string; date: string }[]
-}
-
-export function dailyDigestTemplate(data: DigestData): string {
-  const sections: string[] = []
-
-  if (data.checkIns.length > 0) {
-    sections.push(`
-      <h2>Check-Ins Today (${data.checkIns.length})</h2>
-      <ul>
-        ${data.checkIns.map(c => `<li><strong>${c.guestName}</strong> at ${c.property}</li>`).join('')}
-      </ul>
-    `)
-  }
-
-  if (data.checkOuts.length > 0) {
-    sections.push(`
-      <h2>Check-Outs Today (${data.checkOuts.length})</h2>
-      <ul>
-        ${data.checkOuts.map(c => `<li><strong>${c.guestName}</strong> at ${c.property}</li>`).join('')}
-      </ul>
-    `)
-  }
-
-  if (data.unclaimedCleans.length > 0) {
-    sections.push(`
-      <h2>Unclaimed Cleans (${data.unclaimedCleans.length})</h2>
-      <ul>
-        ${data.unclaimedCleans.map(c => `<li>${c.property} — ${c.date}</li>`).join('')}
-      </ul>
-    `)
-  }
-
-  if (sections.length === 0) {
-    sections.push('<p>No activity to report today.</p>')
-  }
-
-  return baseTemplate({
-    title: `Daily Digest — ${new Date().toLocaleDateString()}`,
-    body: sections.join(''),
-  })
-}
-```
-
-#### Step 4: Use in Application Code
-
-```typescript
-// src/lib/scheduled/daily-digest.ts
-
-import { sendEmail } from '@/lib/email'
-import { dailyDigestTemplate } from '@/lib/email/templates/daily-digest'
-
-export async function handleDailyDigest(): Promise<void> {
-  const checkIns = await ReservationDatabaseService.getTodayCheckIns()
-  const checkOuts = await ReservationDatabaseService.getTodayCheckOuts()
-  const unclaimedCleans = await AppointmentDatabaseService.getUnclaimedNextWeek()
-
-  const html = dailyDigestTemplate({ checkIns, checkOuts, unclaimedCleans })
-
-  await sendEmail({
-    to: ['manager@example.com', 'ops@example.com'],
-    subject: `Daily Digest — ${new Date().toLocaleDateString()}`,
-    html,
-  })
-}
-```
-
-#### Step 5: Use in API Route (Non-Blocking)
-
-```typescript
-// routes/api/posts/create.tsx
-
-POST: async ({ request }) => {
-  const user = await getAuthSession()
-  const body = await request.json()
-  const post = await PostDatabaseService.create(user.uid, body)
-
-  // Send notification email (non-blocking)
-  sendEmail({
-    to: 'admin@example.com',
-    subject: `New post: ${body.title}`,
-    html: baseTemplate({
-      title: 'New Post Created',
-      body: `<p>${user.displayName} created a new post: <strong>${body.title}</strong></p>`,
-    }),
-  }).catch(error => console.error('[Email] Notification failed:', error))
-  // Note: not awaited — fire and forget
-
-  return new Response(JSON.stringify(post), {
-    status: 201,
-    headers: { 'Content-Type': 'application/json' },
-  })
-}
-```
-
----
-
-## Swapping Providers
-
-The `sendEmail` function wraps a single provider. To swap providers, change only that file:
-
-### Mandrill → SendGrid
-
-```typescript
-// src/lib/email/send-email.ts (SendGrid version)
-export async function sendEmail(params: SendEmailParams): Promise<SendEmailResult> {
-  const response = await fetch('https://api.sendgrid.com/v3/mail/send', {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      personalizations: [{ to: [{ email: params.to }] }],
-      from: { email: params.from || 'noreply@example.com' },
-      subject: params.subject,
-      content: [{ type: 'text/html', value: params.html }],
-    }),
-  })
-  // ...
-}
-```
-
-### Mandrill → Resend
-
-```typescript
-// src/lib/email/send-email.ts (Resend version)
-export async function sendEmail(params: SendEmailParams): Promise<SendEmailResult> {
-  const response = await fetch('https://api.resend.com/emails', {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${process.env.RESEND_API_KEY}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      from: params.from || 'noreply@example.com',
-      to: params.to,
-      subject: params.subject,
-      html: params.html,
-    }),
-  })
-  // ...
-}
-```
-
----
-
-## Benefits
-
-### 1. Simple Interface
-`sendEmail({ to, subject, html })` — no provider-specific knowledge needed in calling code.
-
-### 2. Non-Blocking
-Email failures never crash user operations. Fire-and-forget pattern for notifications.
-
-### 3. Provider Swappable
-Change email provider by editing one file. No impact on templates or callers.
-
-### 4. Testable
-`sendEmail` is easily mockable for testing. Templates are pure functions returning strings.
-
----
-
-## Trade-offs
-
-### 1. HTML Templates as Strings
-**Downside**: Building HTML in template literals is error-prone and hard to preview.
-**Mitigation**: Use the base template for consistent structure. Test templates by rendering in a browser.
-
-### 2. No MJML/React Email
-**Downside**: Not using modern email frameworks (MJML, React Email).
-**Mitigation**: These can be added later. The `sendEmail` interface stays the same — only template builders change.
-
----
-
-## Anti-Patterns
-
-### ❌ Anti-Pattern: Throwing on Email Failure
-
-```typescript
-// ❌ BAD: Email failure crashes the post creation
-const post = await PostService.create(data)
-await sendEmail({ to, subject, html })  // If this throws, post appears to fail!
-return post
-
-// ✅ GOOD: Fire and forget
-const post = await PostService.create(data)
-sendEmail({ to, subject, html }).catch(err => console.error('[Email]', err))
-return post
-```
-
-### ❌ Anti-Pattern: Inline HTML in Route Handlers
-
-```typescript
-// ❌ BAD: HTML template inline in route
-await sendEmail({
-  to: user.email,
-  subject: 'Welcome',
-  html: `<html><body><h1>Welcome ${user.name}!</h1><p>...</p></body></html>`
-})
-
-// ✅ GOOD: Use template function
-import { welcomeTemplate } from '@/lib/email/templates/welcome'
-await sendEmail({
-  to: user.email,
-  subject: 'Welcome',
-  html: welcomeTemplate({ name: user.name })
-})
-```
-
----
-
-## Related Patterns
-
-- **[Scheduled Tasks](./tanstack-cloudflare.scheduled-tasks.md)**: Cron-triggered emails (daily digests, reminders)
-- **[Third-Party API Integration](./tanstack-cloudflare.third-party-api-integration.md)**: Email provider as an integration
-- **[API Route Handlers](./tanstack-cloudflare.api-route-handlers.md)**: Email sent from API routes
-
----
-
-## Checklist for Implementation
-
-- [ ] `sendEmail()` function with `{ to, subject, html }` interface
-- [ ] Returns `{ success, error? }` — never throws
-- [ ] API key stored as Cloudflare secret
-- [ ] Base HTML template with consistent styling
-- [ ] Domain-specific template functions (digest, notification, etc.)
-- [ ] Templates are pure functions (string input → string output)
-- [ ] Non-critical emails sent fire-and-forget (`.catch()`)
-- [ ] Critical emails awaited but wrapped in try/catch
-- [ ] Multiple recipients supported (string or string array)
-- [ ] Provider can be swapped by editing one file
-
----
-
-**Status**: Stable - Production-ready email service for Cloudflare Workers
-**Recommendation**: Use for all transactional email needs
-**Last Updated**: 2026-02-28
-**Contributors**: Patrick Michaelsen

package/agent/patterns/tanstack-cloudflare.expander.md

@@ -1,98 +0,0 @@
-# Expander Component
-
-**Category**: Design
-**Applicable To**: Expandable/collapsible sections with smooth height animation and 10 visual variants
-**Status**: Stable
-
----
-
-## Overview
-
-A polymorphic expandable section component with 10 distinct visual variants (gradient-glow, neon-accent, glass-float, slide-arrow, border-sweep, stacked-lift, visibility, thread, highlight, segmented). Uses a `useCollapse` hook for CSS-transition-based height animation (300ms cubic-bezier). Controlled open/close state with consistent API across all variants.
-
----
-
-## Implementation
-
-**File**: `src/components/Expander.tsx`
-
-```typescript
-interface ExpanderProps {
-  title: string
-  count?: number           // Optional count badge (border-sweep variant)
-  open: boolean            // Controlled state
-  onToggle: () => void
-  children: ReactNode
-}
-
-function Expander({ variant = 'gradient-glow', ...props }: ExpanderProps & { variant?: ExpanderVariant })
-```
-
-### useCollapse Hook (Height Animation)
-
-```typescript
-function useCollapse(open: boolean) {
-  const ref = useRef<HTMLDivElement>(null)
-  const [height, setHeight] = useState<number | undefined>(open ? undefined : 0)
-
-  useEffect(() => {
-    const el = ref.current
-    if (!el) return
-    if (open) {
-      setHeight(el.scrollHeight)
-      const id = setTimeout(() => setHeight(undefined), 300)  // Auto after animation
-      return () => clearTimeout(id)
-    } else {
-      setHeight(el.scrollHeight)
-      requestAnimationFrame(() => requestAnimationFrame(() => setHeight(0)))
-    }
-  }, [open])
-
-  return {
-    ref,
-    style: {
-      height: height != null ? `${height}px` : 'auto',
-      overflow: 'hidden' as const,
-      transition: 'height 300ms cubic-bezier(0.4, 0, 0.2, 1)',
-    },
-  }
-}
-```
-
-### Variants
-
-| Variant | Visual |
-|---|---|
-| `gradient-glow` | Blue text title with chevron, minimal |
-| `neon-accent` | Left green border (glows on open), plus/minus icon |
-| `glass-float` | Frosted glass blur effect when open, sparkle icon |
-| `slide-arrow` | Arrow rotates 90° on open, indented content |
-| `border-sweep` | Bottom amber gradient border sweeps in, count badge |
-| `stacked-lift` | Layered border effects above title when open |
-| `visibility` | iOS-style toggle switch, eye/eye-off icon |
-| `thread` | Gradient vertical line with nested indentation |
-| `highlight` | Indigo ring + background highlight, zap icon with scale |
-| `segmented` | 3 animated dots (staggered timing), fuchsia color |
-
-Exported as `EXPANDER_VARIANTS: Array<{ id: string; label: string }>`.
-
-**Usage**:
-
-```typescript
-const [open, setOpen] = useState(false)
-
-<Expander
-  variant="glass-float"
-  title="Advanced Settings"
-  open={open}
-  onToggle={() => setOpen(!open)}
->
-  <p>Expanded content here</p>
-</Expander>
-```
-
----
-
-**Status**: Stable
-**Last Updated**: 2026-03-14
-**Contributors**: Community

package/agent/patterns/tanstack-cloudflare.fcm-push.md

@@ -1,115 +0,0 @@
-# FCM Push Notifications
-
-**Category**: Architecture
-**Applicable To**: Multi-device push notifications via Firebase Cloud Messaging with automatic stale token cleanup
-**Status**: Stable
-
----
-
-## Overview
-
-Server-side FCM push notification delivery to all registered devices for a user. Tokens stored in Firestore per-user with hash-based document IDs for upsert. Invalid/expired tokens (`UNREGISTERED`, `INVALID_ARGUMENT`) are automatically removed on send failure. Integrated with the notification triggers service as the offline fallback when WebSocket is unavailable.
-
----
-
-## Implementation
-
-### FcmService
-
-**File**: `src/services/fcm.service.ts`
-
-```typescript
-interface PushNotificationPayload {
-  title: string
-  body: string
-  data?: Record<string, string>
-}
-
-class FcmService {
-  static async sendToUser(userId: string, payload: PushNotificationPayload): Promise<number> {
-    const tokens = await FcmTokenDatabaseService.getTokens(userId)
-    if (tokens.length === 0) return 0
-
-    let successCount = 0
-    await Promise.all(tokens.map(async (token) => {
-      try {
-        await sendMessage({
-          token: token.fcm_token,
-          notification: { title: payload.title, body: payload.body },
-          data: payload.data,
-        })
-        successCount++
-      } catch (error) {
-        if (errMsg.includes('UNREGISTERED') || errMsg.includes('INVALID_ARGUMENT')) {
-          await FcmTokenDatabaseService.removeTokenById(userId, token.id)  // Auto-cleanup
-        }
-      }
-    }))
-    return successCount
-  }
-}
-```
-
-### FcmTokenDatabaseService
-
-**File**: `src/services/fcm-token-database.service.ts`
-
-```typescript
-interface FcmToken {
-  id: string                          // Hash of fcm_token
-  fcm_token: string
-  platform: 'ios' | 'android' | 'web'
-  created_at: string
-  updated_at: string
-}
-// Collection: users/{userId}/fcm_tokens
-// Document ID: hashToken(fcmToken)
-
-class FcmTokenDatabaseService {
-  static async upsertToken(userId, fcmToken, platform): Promise<FcmToken>
-  static async removeToken(userId, fcmToken): Promise<void>
-  static async removeTokenById(userId, tokenId): Promise<void>
-  static async getTokens(userId): Promise<FcmToken[]>
-}
-```
-
-### Client Registration
-
-```typescript
-// POST /api/mobile/register-fcm-token
-// Body: { token: string, platform: 'ios' | 'android' | 'web' }
-await FcmTokenDatabaseService.upsertToken(userId, token, platform)
-```
-
-### Delivery Strategy (with NotificationTriggers)
-
-```typescript
-// WebSocket-first, FCM-fallback
-if (await NotificationHubService.isUserConnected(env, recipientId)) {
-  await NotificationHubService.pushNotification(env, recipientId, notification)
-} else {
-  await FcmService.sendToUser(recipientId, { title, body, data })
-}
-```
-
----
-
-## Checklist
-
-- [ ] Token doc ID is hash of FCM token (enables upsert without duplicates)
-- [ ] `sendToUser` sends to ALL registered tokens (multiple devices)
-- [ ] Invalid tokens auto-removed on UNREGISTERED/INVALID_ARGUMENT errors
-- [ ] Client registers token on app launch / permission grant
-- [ ] Delivery strategy checks WebSocket first, falls back to FCM
-
----
-
-## Related Patterns
-
-- **[Notifications Engine](./tanstack-cloudflare.notifications-engine.md)**: WebSocket-first delivery that FCM falls back from
-
----
-
-**Status**: Stable
-**Last Updated**: 2026-03-14
-**Contributors**: Community