cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skill-library/stack/notifications/fcm/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: fcm
+description: "Firebase Cloud Messaging patterns covering push notification setup, topic messaging, data messages, notification payloads, service worker handling, and multicast sending. Use when implementing push notifications with FCM."
+version: 1.0.0
+source: self
+date_added: "2026-03-14"
+---
+
+# Firebase Cloud Messaging (FCM)
+
+Push notification service for web, Android, and iOS. Send targeted notifications via device tokens, topics, or conditions with customizable payloads.
+
+## When to Use
+
+- Sending push notifications to web browsers or mobile apps
+- Need topic-based pub/sub for notification channels
+- Using Firebase ecosystem (Auth, Firestore, etc.)
+- Need cross-platform push (web + Android + iOS)
+
+## When NOT to Use
+
+- Sending email or SMS (use SendGrid, Twilio)
+- In-app real-time messaging (use WebSockets or Firestore)
+- Need guaranteed delivery for critical alerts (FCM is best-effort)
+
+## Setup
+
+### Server SDK (Firebase Admin)
+
+```bash
+npm install firebase-admin
+```
+
+```typescript
+import * as admin from 'firebase-admin';
+
+admin.initializeApp({
+  credential: admin.credential.cert({
+    projectId: process.env.FIREBASE_PROJECT_ID,
+    clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
+    privateKey: process.env.FIREBASE_PRIVATE_KEY?.replace(/\\n/g, '\n'),
+  }),
+});
+
+const messaging = admin.messaging();
+```
+
+### Web Client Setup
+
+```typescript
+// firebase-messaging-sw.js (Service Worker)
+importScripts('https://www.gstatic.com/firebasejs/10.12.0/firebase-app-compat.js');
+importScripts('https://www.gstatic.com/firebasejs/10.12.0/firebase-messaging-compat.js');
+
+firebase.initializeApp({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id',
+  messagingSenderId: 'your-sender-id',
+  appId: 'your-app-id',
+});
+
+const messaging = firebase.messaging();
+
+// Handle background messages
+messaging.onBackgroundMessage((payload) => {
+  const { title, body, icon } = payload.notification ?? {};
+  self.registration.showNotification(title ?? 'Notification', {
+    body,
+    icon: icon ?? '/icon-192.png',
+  });
+});
+```
+
+```typescript
+// Client-side: request permission and get token
+import { getMessaging, getToken, onMessage } from 'firebase/messaging';
+
+const messaging = getMessaging();
+
+async function requestNotificationPermission(): Promise<string | null> {
+  const permission = await Notification.requestPermission();
+  if (permission !== 'granted') return null;
+
+  const token = await getToken(messaging, {
+    vapidKey: process.env.NEXT_PUBLIC_FIREBASE_VAPID_KEY,
+  });
+
+  // Save token to your server
+  await fetch('/api/push/register', {
+    method: 'POST',
+    body: JSON.stringify({ token }),
+  });
+
+  return token;
+}
+
+// Handle foreground messages
+onMessage(messaging, (payload) => {
+  console.log('Foreground message:', payload);
+  // Show in-app notification UI
+});
+```
+
+## Send Notifications
+
+### To Single Device
+
+```typescript
+await messaging.send({
+  token: deviceToken,
+  notification: {
+    title: 'Order Shipped',
+    body: 'Your order #1234 has been shipped!',
+    imageUrl: 'https://example.com/order-shipped.png',
+  },
+  data: {
+    orderId: '1234',
+    type: 'order_update',
+    url: '/orders/1234',
+  },
+  webpush: {
+    fcmOptions: { link: 'https://example.com/orders/1234' },
+  },
+});
+```
+
+### To Multiple Devices (Multicast)
+
+```typescript
+const response = await messaging.sendEachForMulticast({
+  tokens: deviceTokens, // Up to 500 tokens
+  notification: {
+    title: 'New Feature Available',
+    body: 'Check out our new dashboard!',
+  },
+});
+
+// Handle failures
+response.responses.forEach((resp, i) => {
+  if (!resp.success) {
+    const failedToken = deviceTokens[i];
+    if (resp.error?.code === 'messaging/registration-token-not-registered') {
+      removeStaleToken(failedToken); // Token expired, clean up
+    }
+  }
+});
+```
+
+### Topic Messaging
+
+```typescript
+// Subscribe device to topic (server-side)
+await messaging.subscribeToTopic(deviceTokens, 'news-updates');
+
+// Send to all subscribers of a topic
+await messaging.send({
+  topic: 'news-updates',
+  notification: { title: 'Breaking News', body: 'Important update...' },
+});
+
+// Condition-based targeting
+await messaging.send({
+  condition: "'news-updates' in topics && !('muted' in topics)",
+  notification: { title: 'News', body: 'For unmuted news subscribers' },
+});
+```
+
+## Data-Only Messages (Silent Push)
+
+```typescript
+// No notification shown — app processes data in background
+await messaging.send({
+  token: deviceToken,
+  data: {
+    type: 'sync_required',
+    resource: 'conversations',
+    timestamp: Date.now().toString(),
+  },
+  // Android: set priority for background delivery
+  android: { priority: 'high' },
+  // APNs: required for background delivery on iOS
+  apns: {
+    headers: { 'apns-priority': '10' },
+    payload: { aps: { contentAvailable: true } },
+  },
+});
+```
+
+## Token Management
+
+```typescript
+// API route to register/update tokens
+export async function POST(request: Request) {
+  const { userId, token, platform } = await request.json();
+
+  await db.pushTokens.upsert({
+    where: { token },
+    create: { userId, token, platform, createdAt: new Date() },
+    update: { userId, updatedAt: new Date() },
+  });
+
+  return new Response('OK');
+}
+
+// Clean up stale tokens
+async function cleanStaleTokens() {
+  const tokens = await db.pushTokens.findMany();
+  const results = await messaging.sendEachForMulticast({
+    tokens: tokens.map(t => t.token),
+    data: { type: 'ping' }, // Dry run
+  });
+
+  const staleTokens = tokens.filter((_, i) => !results.responses[i].success);
+  await db.pushTokens.deleteMany({ where: { token: { in: staleTokens.map(t => t.token) } } });
+}
+```
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Store device tokens without a user association | Link tokens to user IDs for targeted messaging |
+| Ignore `registration-token-not-registered` errors | Remove stale tokens to keep your token list clean |
+| Send notifications without user consent | Request permission explicitly, respect denials |
+| Put sensitive data in notification payload | Notification payloads are visible — use data messages for secrets |
+| Use `sendAll` (deprecated) | Use `sendEachForMulticast` for batch sends |
+| Hardcode VAPID keys in client code | Use environment variables for VAPID and project config |
+| Skip the service worker for web push | `firebase-messaging-sw.js` is required for background web messages |
+| Trust device tokens indefinitely | Tokens rotate — implement refresh and cleanup logic |

package/template/.codex/skill-library/stack/notifications/sendgrid/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: sendgrid
+description: "SendGrid email patterns covering transactional email, dynamic templates, email validation, webhook events, and suppression management. Use when implementing email delivery with SendGrid."
+version: 1.0.0
+source: self
+date_added: "2026-03-14"
+---
+
+# SendGrid
+
+Email delivery platform for transactional and marketing email. REST API with dynamic template support, event webhooks, and deliverability analytics.
+
+## When to Use
+
+- Sending transactional email (password resets, receipts, notifications)
+- Building email campaigns with dynamic templates
+- Need email delivery tracking (opens, clicks, bounces)
+- Need email address validation
+
+## When NOT to Use
+
+- Need a simpler developer experience with React email templates (use Resend)
+- Building in-app chat or real-time messaging (use a messaging SDK)
+- SMS/voice communications (use Twilio)
+
+## Setup
+
+### Installation
+
+```bash
+npm install @sendgrid/mail
+```
+
+### Client Initialization
+
+```typescript
+import sgMail from '@sendgrid/mail';
+sgMail.setApiKey(process.env.SENDGRID_API_KEY!);
+```
+
+### Environment Variables
+
+```env
+SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+SENDGRID_FROM_EMAIL=noreply@example.com
+SENDGRID_FROM_NAME=MyApp
+```
+
+## Sending Email
+
+### Simple Email
+
+```typescript
+await sgMail.send({
+  to: 'user@example.com',
+  from: { email: process.env.SENDGRID_FROM_EMAIL!, name: 'MyApp' },
+  subject: 'Your order has shipped',
+  text: 'Order #1234 shipped via FedEx. Tracking: ABC123',
+  html: '<p>Order <strong>#1234</strong> shipped via FedEx.</p>',
+});
+```
+
+### Dynamic Template
+
+```typescript
+await sgMail.send({
+  to: 'user@example.com',
+  from: { email: process.env.SENDGRID_FROM_EMAIL!, name: 'MyApp' },
+  templateId: 'd-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+  dynamicTemplateData: {
+    name: 'Jane Doe',
+    orderNumber: '1234',
+    items: [
+      { name: 'Widget', qty: 2, price: '$19.99' },
+      { name: 'Gadget', qty: 1, price: '$49.99' },
+    ],
+    total: '$89.97',
+    trackingUrl: 'https://tracking.example.com/ABC123',
+  },
+});
+```
+
+### Batch Send (Multiple Recipients)
+
+```typescript
+const messages = users.map(user => ({
+  to: user.email,
+  from: { email: process.env.SENDGRID_FROM_EMAIL!, name: 'MyApp' },
+  templateId: 'd-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+  dynamicTemplateData: { name: user.name, code: user.resetCode },
+}));
+
+// Send up to 1000 per batch
+await sgMail.send(messages);
+```
+
+### Send with Attachments
+
+```typescript
+await sgMail.send({
+  to: 'user@example.com',
+  from: process.env.SENDGRID_FROM_EMAIL!,
+  subject: 'Your invoice',
+  html: '<p>Please find your invoice attached.</p>',
+  attachments: [
+    {
+      content: base64EncodedPdf,
+      filename: 'invoice-1234.pdf',
+      type: 'application/pdf',
+      disposition: 'attachment',
+    },
+  ],
+});
+```
+
+## Event Webhooks
+
+### Setup Webhook Handler
+
+```typescript
+// POST /api/webhooks/sendgrid
+export async function POST(request: Request) {
+  const events = await request.json();
+
+  for (const event of events) {
+    switch (event.event) {
+      case 'delivered':
+        await markEmailDelivered(event.sg_message_id);
+        break;
+      case 'open':
+        await trackEmailOpen(event.sg_message_id, event.timestamp);
+        break;
+      case 'click':
+        await trackEmailClick(event.sg_message_id, event.url);
+        break;
+      case 'bounce':
+        await handleBounce(event.email, event.type); // 'bounce' or 'blocked'
+        break;
+      case 'spam_report':
+        await addToSuppressionList(event.email);
+        break;
+      case 'unsubscribe':
+        await unsubscribeUser(event.email);
+        break;
+    }
+  }
+
+  return new Response('OK', { status: 200 });
+}
+```
+
+### Verify Webhook Signature
+
+```typescript
+import { EventWebhook } from '@sendgrid/eventwebhook';
+
+export async function POST(request: Request) {
+  const publicKey = process.env.SENDGRID_WEBHOOK_VERIFICATION_KEY!;
+  const signature = request.headers.get('x-twilio-email-event-webhook-signature') ?? '';
+  const timestamp = request.headers.get('x-twilio-email-event-webhook-timestamp') ?? '';
+  const body = await request.text();
+
+  const ew = new EventWebhook();
+  const key = ew.convertPublicKeyToECDSA(publicKey);
+  const isValid = ew.verifySignature(key, body, signature, timestamp);
+
+  if (!isValid) {
+    return new Response('Invalid signature', { status: 403 });
+  }
+
+  const events = JSON.parse(body);
+  // Process events...
+}
+```
+
+## Email Validation
+
+```typescript
+import Client from '@sendgrid/client';
+Client.setApiKey(process.env.SENDGRID_API_KEY!);
+
+async function validateEmail(email: string) {
+  const [response] = await Client.request({
+    url: '/v3/validations/email',
+    method: 'POST',
+    body: { email },
+  });
+
+  const result = response.body.result;
+  return {
+    valid: result.verdict === 'Valid',
+    score: result.score,           // 0-1 confidence
+    suggestion: result.suggestion, // e.g., "Did you mean user@gmail.com?"
+  };
+}
+```
+
+## Key Limits
+
+| Limit | Value |
+|-------|-------|
+| Free tier | 100 emails/day |
+| Max recipients per API call | 1,000 |
+| Max email size (with attachments) | 30 MB |
+| Template dynamic data | 10,000 bytes |
+| Rate limit (default) | 600 requests/min |
+| Webhook events batch size | Up to 1,000 events per POST |
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Hardcode `from` email in every send call | Use a shared constant or env var for `from` |
+| Send HTML without a text fallback | Always provide both `text` and `html` content |
+| Ignore bounce events | Handle bounces — suppress future sends to bounced addresses |
+| Use personal email as sender | Use a domain you own with proper SPF/DKIM/DMARC |
+| Skip webhook signature verification | Always verify `x-twilio-email-event-webhook-signature` |
+| Send bulk email via the Mail Send API | Use Marketing Campaigns API for bulk/marketing sends |
+| Store API key in client-side code | Keep `SENDGRID_API_KEY` server-side only |
+| Log full email content | Never log email bodies — they may contain PII |

package/template/.codex/skill-library/stack/notifications/twilio/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: twilio
+description: "Twilio communication patterns covering SMS/MMS sending, voice calls, WhatsApp, webhook handling, phone number management, and verification (Verify API). Use when implementing communications with Twilio."
+version: 1.0.0
+source: self
+date_added: "2026-03-14"
+---
+
+# Twilio
+
+Cloud communications platform for SMS, voice, WhatsApp, and phone verification. Programmable via REST API with webhook-driven inbound message handling.
+
+## When to Use
+
+- Need to send or receive SMS/MMS messages
+- Implementing phone number verification (OTP)
+- Building voice call features (IVR, call forwarding)
+- Sending WhatsApp messages programmatically
+
+## When NOT to Use
+
+- Email-only communications (use SendGrid, Resend)
+- Push notifications to mobile apps (use FCM/APNs)
+- Real-time chat in-app (use websockets or a chat SDK)
+
+## Setup
+
+### Installation
+
+```bash
+npm install twilio
+```
+
+### Client Initialization
+
+```typescript
+import twilio from 'twilio';
+
+const client = twilio(
+  process.env.TWILIO_ACCOUNT_SID,
+  process.env.TWILIO_AUTH_TOKEN
+);
+```
+
+### Environment Variables
+
+```env
+TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+TWILIO_AUTH_TOKEN=your-auth-token
+TWILIO_PHONE_NUMBER=+15551234567
+TWILIO_VERIFY_SERVICE_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## SMS/MMS
+
+### Send SMS
+
+```typescript
+const message = await client.messages.create({
+  body: 'Your order #1234 has shipped!',
+  from: process.env.TWILIO_PHONE_NUMBER,
+  to: '+15559876543',
+});
+console.log(`Sent: ${message.sid} — Status: ${message.status}`);
+```
+
+### Send MMS (with media)
+
+```typescript
+const message = await client.messages.create({
+  body: 'Your receipt is attached',
+  from: process.env.TWILIO_PHONE_NUMBER,
+  to: '+15559876543',
+  mediaUrl: ['https://example.com/receipt.pdf'],
+});
+```
+
+### Receive SMS (Webhook)
+
+```typescript
+// POST /api/webhooks/twilio/sms
+import { twiml } from 'twilio';
+
+export async function POST(request: Request) {
+  const formData = await request.formData();
+  const from = formData.get('From') as string;
+  const body = formData.get('Body') as string;
+
+  // Process inbound message
+  await processInboundSMS(from, body);
+
+  // Respond with TwiML
+  const response = new twiml.MessagingResponse();
+  response.message('Thanks for your message! We\'ll get back to you soon.');
+
+  return new Response(response.toString(), {
+    headers: { 'Content-Type': 'text/xml' },
+  });
+}
+```
+
+## Phone Verification (Verify API)
+
+### Send OTP
+
+```typescript
+const verification = await client.verify.v2
+  .services(process.env.TWILIO_VERIFY_SERVICE_SID!)
+  .verifications.create({
+    to: '+15559876543',
+    channel: 'sms', // or 'call', 'email', 'whatsapp'
+  });
+console.log(`Verification status: ${verification.status}`); // 'pending'
+```
+
+### Check OTP
+
+```typescript
+const check = await client.verify.v2
+  .services(process.env.TWILIO_VERIFY_SERVICE_SID!)
+  .verificationChecks.create({
+    to: '+15559876543',
+    code: '123456',
+  });
+
+if (check.status === 'approved') {
+  // Phone number verified
+} else {
+  // Invalid code
+}
+```
+
+## Voice Calls
+
+```typescript
+const call = await client.calls.create({
+  url: 'https://example.com/api/webhooks/twilio/voice',
+  to: '+15559876543',
+  from: process.env.TWILIO_PHONE_NUMBER,
+});
+
+// Webhook handler responds with TwiML
+export async function POST(request: Request) {
+  const response = new twiml.VoiceResponse();
+  response.say('Hello! Thank you for calling. Press 1 for support.');
+  response.gather({
+    numDigits: 1,
+    action: '/api/webhooks/twilio/voice/menu',
+  });
+  return new Response(response.toString(), {
+    headers: { 'Content-Type': 'text/xml' },
+  });
+}
+```
+
+## Webhook Signature Validation
+
+```typescript
+import { validateRequest } from 'twilio';
+
+export async function POST(request: Request) {
+  const signature = request.headers.get('x-twilio-signature') ?? '';
+  const url = request.url;
+  const body = Object.fromEntries(await request.formData());
+
+  const isValid = validateRequest(
+    process.env.TWILIO_AUTH_TOKEN!,
+    signature,
+    url,
+    body as Record<string, string>
+  );
+
+  if (!isValid) {
+    return new Response('Invalid signature', { status: 403 });
+  }
+
+  // Process webhook...
+}
+```
+
+## Key Limits
+
+| Limit | Value |
+|-------|-------|
+| SMS body max length | 1,600 characters (concatenated) |
+| MMS max media size | 5 MB per media |
+| MMS max media count | 10 per message |
+| Verify OTP expiry | 10 minutes (default) |
+| Messages per second (default) | 1 msg/sec per number |
+| Toll-free throughput | 3 msg/sec |
+| Short code throughput | 100 msg/sec |
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Hardcode phone numbers in source | Use environment variables for all phone numbers |
+| Skip webhook signature validation | Always validate `x-twilio-signature` header |
+| Build your own OTP system | Use Twilio Verify API — handles rate limiting, expiry, retries |
+| Store `TWILIO_AUTH_TOKEN` in client-side code | Keep all Twilio credentials server-side only |
+| Send SMS from a single number at high volume | Use a messaging service with number pool for throughput |
+| Ignore delivery status callbacks | Set `statusCallback` URL to track delivery outcomes |
+| Use long codes for marketing/bulk SMS | Use toll-free or short codes for high-volume messaging |
+| Log full phone numbers | Redact/mask phone numbers in logs (PII) |