vybekiit 0.7.0 → 0.7.2

package/dist/global-skills/email-best-practices/references/email-types.md

@@ -1,173 +0,0 @@
-# Email Types: Transactional vs Marketing
-
-Understanding the difference between transactional and marketing emails is crucial for compliance, deliverability, and user experience. This guide explains the distinctions and provides a catalog of transactional emails your app should include.
-
-## When to Use This
-
-- Deciding whether an email should be transactional or marketing
-- Understanding legal distinctions between email types
-- Planning what transactional emails your app needs
-- Ensuring compliance with email regulations
-- Setting up separate sending infrastructure
-
-## Transactional vs Marketing: Key Differences
-
-### Transactional Emails
-
-**Definition:** Emails that facilitate or confirm a transaction the user initiated or expects. They're directly related to an action the user took or are legal notices you're required to serve.
-
-**Characteristics:**
-- User-initiated or expected
-- Time-sensitive and actionable
-- Required for the user to complete an action
-- Does not include promotional material or offers
-- Can be sent without explicit opt-in (with limitations)
-
-**Examples:**
-- Password reset links
-- Order confirmations
-- Account verification
-- OTP/2FA codes
-- Shipping notifications
-
-**Analogy:**
-Think of transactional emails for everything that would leave you with a paper receipt in the real world: invoices, parking ticket, booking confirmation, etc.
-
-### Marketing Emails
-
-**Definition:** Emails sent for promotional, advertising, or informational purposes that are not directly related to a specific transaction or legal requirement.
-
-**Characteristics:**
-- Promotional or informational content
-- Not time-sensitive to complete a transaction
-- Require explicit opt-in (consent)
-- Must include unsubscribe options
-- Subject to stricter compliance requirements
-
-**Examples:**
-- Newsletters
-- Abandoned cart
-- Product announcements
-- Promotional offers
-- Company updates
-- Educational content
-
-## Legal Distinctions
-
-### CAN-SPAM Act (US)
-
-**Transactional emails:**
-- Can be sent without opt-in
-- Must be related to a transaction
-- Cannot contain promotional content (with exceptions)
-- Must identify sender and provide contact information
-
-**Marketing emails:**
-- Require opt-out mechanism (not opt-in in US)
-- Must include clear sender identification
-- Must include physical mailing address
-- Must honor opt-out requests within 10 business days
-
-### GDPR (EU)
-
-**Transactional emails:**
-- Can be sent based on legitimate interest or contract fulfillment
-- Must be necessary for service delivery
-- Cannot contain marketing content without consent
-
-**Marketing emails:**
-- Require explicit opt-in consent
-- Must clearly state purpose of data collection
-- Must provide easy unsubscribe
-- Subject to data protection requirements
-
-### CASL (Canada)
-
-**Transactional emails:**
-- Can be sent without consent if related to ongoing business relationship
-- Must be factual and not promotional
-
-**Marketing emails:**
-- Require express or implied consent
-- Must include unsubscribe mechanism
-- Must identify sender clearly
-
-## When to Use Each Type
-
-### Use Transactional When:
-
-- User needs the email to complete an action
-- Email confirms a transaction or account change
-- Email provides security-related information
-- Email is expected based on user action
-- Content is time-sensitive and actionable
-- You're required to serve a notification for compliance
-
-### Use Marketing When:
-
-- Promoting products or services
-- Sending newsletters or updates
-- Sharing educational content
-- Announcing features or company news
-- Content is not required for a transaction
-
-## Hybrid Emails: The Gray Area
-
-Some emails mix transactional and marketing content. This isn't best practice and should be avoided.
-
-**Best practice:** Keep transactional and marketing separate. 
-
-**Example of problematic hybrid:**
-- Newsletter (marketing) with a small order status update (transactional)
-
-## Transactional Email Catalog
-
-For a complete catalog of transactional emails and recommended combinations by app type, see [Transactional Email Catalog](./transactional-email-catalog.md).
-
-**Quick reference - Essential emails for most apps:**
-1. **Email verification** - Required for account creation
-2. **Password reset** - Required for account recovery
-3. **Welcome email** - Good user experience
-
-The catalog includes detailed guidance for:
-- Authentication-focused apps
-- Newsletter / content platforms
-- E-commerce / marketplaces
-- SaaS / subscription services
-- Financial / fintech apps
-- Social / community platforms
-- Developer tools / API platforms
-- Healthcare / HIPAA-compliant apps
-
-## Sending Infrastructure
-
-### Separate subdomains
-
-**Best practice:** Use separate sending subdomains for transactional and marketing emails.
-
-**Benefits:**
-- Protect transactional deliverability
-- Different authentication domains
-- Independent reputation
-- Easier compliance management
-
-**Implementation:**
-- Use different subdomains (e.g., `t.example.com` for transactional, `m.example.com` for marketing)
-
-### Email Service Considerations
-
-Choose an email service that:
-- Provides reliable delivery for transactional emails
-- Offers separate sending domains
-- Has good API for programmatic sending
-- Provides webhooks for delivery events
-- Supports authentication setup (SPF, DKIM, DMARC)
-
-Services like Resend are designed for transactional emails and provide the infrastructure and tools needed for reliable delivery. They also offer powerful marketing features.
-
-## Related Topics
-
-- [Transactional Emails](./transactional-emails.md) - Best practices for sending transactional emails
-- [Marketing Emails](./marketing-emails.md) - Best practices for marketing emails
-- [Compliance](./compliance.md) - Legal requirements for each email type
-- [Deliverability](./deliverability.md) - Ensuring transactional emails are delivered

package/dist/global-skills/email-best-practices/references/list-management.md

@@ -1,157 +0,0 @@
-# List Management
-
-Maintaining clean email lists through suppression, hygiene, and data retention.
-
-## Suppression Lists
-
-A suppression list prevents sending to addresses that should never receive email.
-
-### What to Suppress
-
-| Reason | Action | Can Unsuppress? |
-|--------|--------|-----------------|
-| Hard bounce | Add immediately | No (address invalid) |
-| Complaint (spam) | Add immediately | No (legal requirement) |
-| Soft bounce (3x) | Add after threshold | Yes, after 30-90 days |
-| Manual removal | Add on request | Only if user requests |
-
-### Implementation
-
-```typescript
-// Suppression list schema
-interface SuppressionEntry {
-  email: string;
-  reason: 'hard_bounce' | 'complaint' | 'unsubscribe' | 'soft_bounce' | 'manual';
-  created_at: Date;
-  source_email_id?: string; // Which email triggered this
-}
-
-// Check before every send
-async function canSendTo(email: string): Promise<boolean> {
-  const suppressed = await db.suppressions.findOne({ email });
-  return !suppressed;
-}
-
-// Add to suppression list
-async function suppressEmail(email: string, reason: string, sourceId?: string) {
-  await db.suppressions.upsert({
-    email: email.toLowerCase(),
-    reason,
-    created_at: new Date(),
-    source_email_id: sourceId,
-  });
-}
-```
-
-### Pre-Send Check
-
-**Always check suppression before sending:**
-
-```typescript
-async function sendEmail(to: string, emailData: EmailData) {
-  if (!await canSendTo(to)) {
-    console.log(`Skipping suppressed email: ${to}`);
-    return { skipped: true, reason: 'suppressed' };
-  }
-
-  return await resend.emails.send({ to, ...emailData });
-}
-```
-
-## List Hygiene
-
-Regular maintenance to keep lists healthy.
-
-### Automated Cleanup
-
-| Task | Frequency | Action |
-|------|-----------|--------|
-| Remove hard bounces | Real-time (via webhook) | Immediate suppression |
-| Remove complaints | Real-time (via webhook) | Immediate suppression |
-| Process unsubscribes | Real-time | Remove from marketing lists |
-| Review soft bounces | Daily | Suppress after 3 failures |
-| Remove inactive | Monthly | Re-engagement → remove |
-
-Learn more: https://resend.com/docs/knowledge-base/audience-hygiene
-
-### Re-engagement Campaigns
-
-Before removing inactive subscribers:
-
-1. **Identify inactive:** No opens/clicks in 45-90 days
-2. **Send re-engagement:** "We miss you" or "Still interested?"
-3. **Wait 14-30 days** for response
-4. **Remove non-responders** from active lists
-
-```typescript
-async function runReengagement() {
-  const inactive = await getInactiveSubscribers(90); // 90 days
-
-  for (const subscriber of inactive) {
-    if (!subscriber.reengagement_sent) {
-      await sendReengagementEmail(subscriber);
-      await markReengagementSent(subscriber.email);
-    } else if (daysSince(subscriber.reengagement_sent) > 30) {
-      await removeFromMarketingLists(subscriber.email);
-    }
-  }
-}
-```
-
-## Data Retention
-
-### Email Logs
-
-| Data Type | Recommended Retention | Notes |
-|-----------|----------------------|-------|
-| Send attempts | 90 days | Debugging, analytics |
-| Delivery status | 90 days | Compliance, reporting |
-| Bounce/complaint events | 3 years | Required for CASL |
-| Suppression list | Indefinite | Never delete |
-| Email content | 30 days | Storage costs |
-| Consent records | 3 years after expiry | Legal requirement |
-
-### Retention Policy Implementation
-
-```typescript
-// Daily cleanup job
-async function cleanupOldData() {
-  const now = new Date();
-
-  // Delete old email logs (keep 90 days)
-  await db.emailLogs.deleteMany({
-    created_at: { $lt: subDays(now, 90) }
-  });
-
-  // Delete old email content (keep 30 days)
-  await db.emailContent.deleteMany({
-    created_at: { $lt: subDays(now, 30) }
-  });
-
-  // Never delete: suppressions, consent records
-}
-```
-
-## Metrics to Monitor
-
-| Metric | Target | Alert Threshold |
-|--------|--------|-----------------|
-| Bounce rate | <2% | >2% |
-| Complaint rate | <0.05% | >0.05% |
-| Suppression list growth | Stable | Sudden spike |
-
-## Transactional vs Marketing Lists
-
-**Keep separate:**
-- Transactional: Can send to anyone with account relationship
-- Marketing: Only opted-in subscribers
-
-**Suppression applies to both:** Hard bounces and complaints suppress across all email types.
-
-**Unsubscribe is marketing-only:** User unsubscribing from marketing can still receive transactional emails (password resets, order confirmations).
-
-## Related
-
-- [Webhooks & Events](./webhooks-events.md) - Receive bounce/complaint notifications
-- [Deliverability](./deliverability.md) - How list hygiene affects sender reputation
-- [Compliance](./compliance.md) - Legal requirements for data retention

package/dist/global-skills/email-best-practices/references/marketing-emails.md

@@ -1,115 +0,0 @@
-# Marketing Email Best Practices
-
-Promotional emails that require explicit consent and provide value to recipients.
-
-## Core Principles
-
-1. **Consent first** - Explicit opt-in required (especially GDPR/CASL)
-2. **Value-driven** - Provide useful content, not just promotions
-3. **Respect preferences** - Let users control frequency and content types
-
-## Opt-In Requirements
-
-### Explicit Opt-In
-
-**What counts:**
-- User checks unchecked box
-- User clicks "Subscribe" button
-- User completes form with clear subscription intent
-
-**What doesn't count:**
-- Pre-checked boxes
-- Opt-out model
-- Assumed consent from purchase
-- Purchased/rented lists
-
-### Informed Consent
-
-Disclose: email types, frequency, sender identity, how to unsubscribe.
-
-✅ "Subscribe to our weekly newsletter with product updates and tips"
-❌ "Sign up for emails"
-
-### Double Opt-In (Recommended)
-
-1. User submits email
-2. Send confirmation email with verification link
-3. User clicks to confirm
-4. Add to list only after confirmation
-
-Benefits: Verifies deliverability, confirms intent, reduces complaints, required in some regions (Germany).
-
-## Unsubscribe Requirements
-
-**Must be:**
-- Prominent in every email
-- One-click (preferred)
-- Immediate (GDPR) or within 10 days (CAN-SPAM) (immediate preferred)
-- Free, no login required
-
-**Preference center options:** Frequency (daily/weekly/monthly), content types, complete unsubscribe.
-
-## Content and Design
-
-### Subject Lines
-
-- Clear and specific (50 chars or less for mobile)
-- Create curiosity without misleading
-- A/B test regularly
-
-✅ "Your weekly digest: 5 productivity tips"
-❌ "You won't believe what happened!"
-
-### Structure
-
-**Above fold:** Value proposition, primary CTA, engaging visual
-
-**Body:** Scannable (short paragraphs, bullets), clear hierarchy, multiple CTAs
-
-**Footer:** Unsubscribe link, company info, physical address (CAN-SPAM), social links
-
-### Mobile-First
-
-- Single column layout
-- 44x44px minimum buttons
-- 16px minimum text
-- Test on iOS, Android, dark mode
-
-## Segmentation
-
-**Segment by:** Behavior (purchases, activity), demographics, preferences, engagement level, signup source.
-
-Benefits: Higher open/click rates, lower unsubscribes, better experience.
-
-## Personalization
-
-**Options:** Name in subject/greeting, location-specific content, behavior-based recommendations, purchase history.
-
-**Don't over-personalize** - can feel intrusive. Use data you have permission to use.
-
-## Frequency and Timing
-
-**Frequency:** Start conservative, increase based on engagement, let users set preferences, monitor unsubscribe rates.
-
-**Timing:** Weekday mornings (9-11 AM local), Tuesday-Thursday often best. Test your specific audience.
-
-## List Hygiene
-
-**Remove immediately:** Hard bounces, unsubscribes, complaints
-
-**Remove after inactivity:** Send re-engagement campaign first, then remove non-responders
-
-**Monitor:** Bounce rate <2%, complaint rate <0.05%
-
-## Required Elements (All Marketing Emails)
-
-- Clear sender identification
-- Physical mailing address (CAN-SPAM)
-- Unsubscribe mechanism
-- Indication it's marketing (GDPR)
-
-## Related
-
-- [Compliance](./compliance.md) - Detailed legal requirements by region
-- [Email Capture](./email-capture.md) - Collecting consent properly
-- [List Management](./list-management.md) - Maintaining list hygiene

package/dist/global-skills/email-best-practices/references/sending-reliability.md

@@ -1,155 +0,0 @@
-# Sending Reliability
-
-Ensuring emails are sent exactly once and handling failures gracefully.
-
-## Idempotency
-
-Prevent duplicate emails when retrying failed requests.
-
-### The Problem
-
-Network issues, timeouts, or server errors can leave you uncertain if an email was sent. Retrying without idempotency risks sending duplicates.
-
-### Solution: Idempotency Keys
-
-Send a unique key with each request. If the same key is sent again, the server returns the original response instead of sending another email.
-
-```typescript
-// Generate deterministic key based on the business event
-const idempotencyKey = `password-reset-${userId}-${resetRequestId}`;
-
-await resend.emails.send({
-  from: 'noreply@example.com',
-  to: user.email,
-  subject: 'Reset your password',
-  html: emailHtml,
-}, {
-  headers: {
-    'Idempotency-Key': idempotencyKey
-  }
-});
-```
-
-### Key Generation Strategies
-
-| Strategy | Example | Use When |
-|----------|---------|----------|
-| Event-based | `order-confirm-${orderId}` | One email per event (recommended) |
-| Request-scoped | `reset-${userId}-${resetRequestId}` | Retries within same request |
-| UUID | `crypto.randomUUID()` | No natural key (generate once, reuse on retry) |
-
-**Best practice:** Use deterministic keys based on the business event. If you retry the same logical send, the same key must be generated. Avoid `Date.now()` or random values generated fresh on each attempt.
-
-**Key expiration:** Idempotency keys are typically cached for 24 hours. Retries within this window return the original response. After expiration, the same key triggers a new send—so complete your retry logic well within 24 hours.
-
-## Retry Logic
-
-Handle transient failures with exponential backoff.
-
-### When to Retry
-
-| Error Type | Retry? | Notes |
-|------------|--------|-------|
-| 5xx (server error) | ✅ Yes | Transient, likely to resolve |
-| 429 (rate limit) | ✅ Yes | Wait for rate limit window |
-| 4xx (client error) | ❌ No | Fix the request first |
-| Network timeout | ✅ Yes | Transient |
-| DNS failure | ✅ Yes | May be transient |
-
-### Exponential Backoff
-
-```typescript
-async function sendWithRetry(emailData, maxRetries = 3) {
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await resend.emails.send(emailData);
-    } catch (error) {
-      if (!isRetryable(error) || attempt === maxRetries - 1) {
-        throw error;
-      }
-      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
-      await sleep(delay + Math.random() * 1000); // Add jitter
-    }
-  }
-}
-
-function isRetryable(error) {
-  return error.statusCode >= 500 ||
-         error.statusCode === 429 ||
-         error.code === 'ETIMEDOUT';
-}
-```
-
-**Backoff schedule:** 1s → 2s → 4s → 8s (with jitter to prevent thundering herd)
-
-## Error Handling
-
-### Common Error Codes
-
-| Code | Meaning | Action |
-|------|---------|--------|
-| 400 | Bad request | Fix payload (invalid email, missing field) |
-| 401 | Unauthorized | Check API key |
-| 403 | Forbidden | Check permissions, domain verification |
-| 404 | Not found | Check endpoint URL |
-| 422 | Validation error | Fix request data |
-| 429 | Rate limited | Back off, retry after delay |
-| 500 | Server error | Retry with backoff |
-| 503 | Service unavailable | Retry with backoff |
-
-### Error Handling Pattern
-
-```typescript
-try {
-  const result = await resend.emails.send(emailData);
-  await logSuccess(result.id, emailData);
-} catch (error) {
-  if (error.statusCode === 429) {
-    await queueForRetry(emailData, error.retryAfter);
-  } else if (error.statusCode >= 500) {
-    await queueForRetry(emailData);
-  } else {
-    await logFailure(error, emailData);
-    await alertOnCriticalEmail(emailData); // For password resets, etc.
-  }
-}
-```
-
-## Queuing for Reliability
-
-For critical emails, use a queue to ensure delivery even if the initial send fails.
-
-**Benefits:**
-- Survives application restarts
-- Automatic retry handling
-- Rate limit management
-- Audit trail
-
-**Simple pattern:**
-1. Write email to queue/database with "pending" status
-2. Process queue, attempt send
-3. On success: mark "sent", store message ID
-4. On retryable failure: increment retry count, schedule retry
-5. On permanent failure: mark "failed", alert
-
-## Timeouts
-
-Set appropriate timeouts to avoid hanging requests.
-
-```typescript
-const controller = new AbortController();
-const timeout = setTimeout(() => controller.abort(), 10000);
-
-try {
-  await resend.emails.send(emailData, { signal: controller.signal });
-} finally {
-  clearTimeout(timeout);
-}
-```
-
-**Recommended:** 10-30 seconds for email API calls.
-
-## Related
-
-- [Webhooks & Events](./webhooks-events.md) - Process delivery confirmations and failures
-- [List Management](./list-management.md) - Handle bounces and suppress invalid addresses