vybekiit 0.7.4 → 0.7.7

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

@@ -0,0 +1,155 @@
+# 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

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

@@ -0,0 +1,418 @@
+# Transactional Email Catalog
+
+A comprehensive catalog of transactional emails organized by category, plus recommended email combinations for different app types.
+
+## When to Use This
+
+- Planning what transactional emails your app needs
+- Choosing the right emails for your app type
+- Understanding what content each email type should include
+- Implementing transactional email features
+
+## Email Combinations by App Type
+
+Use these combinations as a starting point based on what you're building.
+
+### Authentication-Focused App
+
+Apps where user accounts and security are core (login systems, identity providers, account management).
+
+**Essential:**
+- Email verification
+- Password reset
+- OTP / 2FA codes
+- Security alerts (new device, password change)
+- Account update notifications
+
+**Optional:**
+- Welcome email (must not be promotional)
+- Account deletion confirmation
+
+### Newsletter / Content Platform
+
+Apps focused on content delivery and subscriptions.
+
+**Essential:**
+- Email verification
+- Password reset
+- Welcome email (must not be promotional)
+- Subscription confirmation
+
+**Optional:**
+- OTP / 2FA codes
+- Account update notifications
+
+### E-commerce / Marketplace
+
+Apps where users buy products or services.
+
+**Essential:**
+- Email verification
+- Password reset
+- Welcome email (must not be promotional)
+- Order confirmation
+- Shipping notifications
+- Invoice / receipt
+- Payment failed notices
+
+**Optional:**
+- OTP / 2FA codes
+- Security alerts
+- Subscription confirmations (for recurring orders)
+
+### SaaS / Subscription Service
+
+Apps with paid subscription tiers and ongoing billing.
+
+**Essential:**
+- Email verification
+- Password reset
+- Welcome email (must not be promotional)
+- OTP / 2FA codes
+- Security alerts
+- Subscription confirmation
+- Subscription renewal notice
+- Payment failed notices
+- Invoice / receipt
+
+**Optional:**
+- Account update notifications
+- Feature change notifications (for breaking changes)
+
+### Financial / Fintech App
+
+Apps handling money, payments, or sensitive financial data.
+
+**Essential:**
+- Email verification
+- Password reset
+- OTP / 2FA codes (required for sensitive actions)
+- Security alerts (all types)
+- Account update notifications
+- Transaction confirmations
+- Invoice / receipt
+- Payment failed notices
+
+**Optional:**
+- Welcome email (must not be promotional)
+- Compliance notices
+
+### Social / Community Platform
+
+Apps focused on user interaction and community features.
+
+**Essential:**
+- Email verification
+- Password reset
+- Welcome email (must not be promotional)
+- Security alerts
+
+**Optional:**
+- OTP / 2FA codes
+- Account update notifications
+- Activity notifications (mentions, replies)
+
+### Developer Tools / API Platform
+
+Apps targeting developers with API access and integrations.
+
+**Essential:**
+- Email verification
+- Password reset
+- OTP / 2FA codes
+- Security alerts
+- API key notifications (creation, expiration)
+- Subscription confirmation
+- Payment failed notices
+
+**Optional:**
+- Welcome email (must not be promotional)
+- Usage alerts (approaching limits)
+- Feature change notifications
+
+### Healthcare / HIPAA-Compliant App
+
+Apps handling protected health information.
+
+**Essential:**
+- Email verification
+- Password reset
+- OTP / 2FA codes (required)
+- Security alerts (all types, detailed)
+- Account update notifications
+- Appointment confirmations
+
+**Optional:**
+- Welcome email (must not be promotional)
+- Compliance notices
+
+**Note:** Healthcare apps have strict requirements. Emails should contain minimal PHI and link to secure portals for sensitive information.
+
+---
+
+## Full Email Catalog
+
+### Authentication & Security
+
+#### Email Verification / Account Verification
+
+**When to send:** Immediately after user signs up or changes email address.
+
+**Purpose:** Verify the email address belongs to the user.
+
+**Content should include:**
+- Clear verification link or code
+- Expiration time (typically 24-48 hours)
+- Instructions on what to do
+- Security notice if link is clicked by mistake
+
+**Best practices:**
+- Send immediately (within seconds)
+- Include expiration notice
+- Provide resend option
+- Link to support if issues
+
+#### OTP / 2FA Codes
+
+**When to send:** When user requests two-factor authentication code.
+
+**Purpose:** Provide time-sensitive authentication code.
+
+**Content should include:**
+- The OTP code (clearly displayed)
+- Expiration time (typically 5-10 minutes)
+- Security warnings
+- Instructions on what to do if not requested
+
+**Best practices:**
+- Send immediately
+- Code should be large and easy to read
+- Include expiration prominently
+- Warn about sharing codes
+- Provide "I didn't request this" link
+
+#### Password Reset
+
+**When to send:** When user requests password reset.
+
+**Purpose:** Allow user to securely reset forgotten password.
+
+**Content should include:**
+- Reset link (with token)
+- Expiration time (typically 1 hour)
+- Security warnings
+- Instructions if not requested
+
+**Best practices:**
+- Send immediately
+- Link expires quickly (1 hour)
+- Include IP address and location if available
+- Provide "I didn't request this" link
+- Don't include the old password
+
+#### Security Alerts
+
+**When to send:** When security-relevant events occur (login from new device, password change, etc.).
+
+**Purpose:** Notify user of account security events.
+
+**Content should include:**
+- What happened (clear description)
+- When it happened
+- Location/IP if available
+- Action to take if suspicious
+- Link to security settings
+
+**Best practices:**
+- Send immediately
+- Be clear and specific
+- Include actionable steps
+- Provide way to report suspicious activity
+
+### Account Management
+
+#### Welcome Email
+
+**When to send:** Immediately after successful account creation and verification.
+
+**Purpose:** Welcome new users and guide them to next steps (must not be promotional).
+
+**Content should include:**
+- Welcome message
+- Key features or next steps
+- Links to important resources
+- Support contact information
+
+**Best practices:**
+- Send after email verification
+- Keep it focused and actionable
+- Don't overwhelm with information
+- Set expectations about future emails
+
+#### Account Update Notifications
+
+**When to send:** When user changes account settings (email, password, profile, etc.).
+
+**Purpose:** Confirm account changes and provide security notice.
+
+**Content should include:**
+- What changed
+- When it changed
+- Action to take if unauthorized
+- Link to account settings
+
+**Best practices:**
+- Send immediately after change
+- Be specific about what changed
+- Include security notice
+- Provide easy way to revert if needed
+
+### E-commerce & Transactions
+
+#### Order Confirmations
+
+**When to send:** Immediately after order is placed.
+
+**Purpose:** Confirm order details and provide receipt.
+
+**Content should include:**
+- Order number
+- Items ordered with quantities
+- Pricing breakdown
+- Shipping address
+- Estimated delivery date
+- Order tracking link (if available)
+
+**Best practices:**
+- Send within minutes of order
+- Include all order details
+- Make it easy to print or save
+- Provide customer service contact
+
+#### Shipping Notifications
+
+**When to send:** When order ships, with tracking updates.
+
+**Purpose:** Notify user that order has shipped and provide tracking.
+
+**Content should include:**
+- Order number
+- Tracking number
+- Carrier information
+- Expected delivery date
+- Tracking link
+- Shipping address confirmation
+
+**Best practices:**
+- Send when order ships
+- Include tracking number prominently
+- Provide carrier tracking link
+- Update on major tracking milestones
+
+#### Invoices and Receipts
+
+**When to send:** After payment is processed.
+
+**Purpose:** Provide payment confirmation and receipt.
+
+**Content should include:**
+- Invoice/receipt number
+- Payment amount
+- Payment method
+- Items/services purchased
+- Payment date
+- Downloadable PDF (if applicable)
+
+**Best practices:**
+- Send immediately after payment
+- Include all payment details
+- Make it easy to download/save
+- Include tax information if applicable
+
+### Subscriptions & Billing
+
+#### Subscription Confirmations
+
+**When to send:** When user subscribes or changes subscription.
+
+**Purpose:** Confirm subscription details and billing information.
+
+**Content should include:**
+- Subscription plan details
+- Billing amount and frequency
+- Next billing date
+- Payment method
+- Link to manage subscription
+
+**Best practices:**
+- Send immediately after subscription
+- Clearly state billing terms
+- Provide easy cancellation option
+- Include support contact
+
+#### Subscription Renewal Notices
+
+**When to send:** Before subscription renews (typically 3-7 days before).
+
+**Purpose:** Notify user of upcoming renewal and charge.
+
+**Content should include:**
+- Renewal date
+- Amount to be charged
+- Payment method on file
+- Link to update payment method
+- Link to cancel if desired
+
+**Best practices:**
+- Send with enough notice (3-7 days)
+- Be clear about amount and date
+- Make it easy to update payment method
+- Provide cancellation option
+
+#### Payment Failed Notices
+
+**When to send:** When subscription payment fails.
+
+**Purpose:** Notify user of payment failure and provide resolution steps.
+
+**Content should include:**
+- What happened
+- Amount that failed
+- Reason for failure (if available)
+- Steps to resolve
+- Link to update payment method
+- Consequences if not resolved
+
+**Best practices:**
+- Send immediately after failure
+- Be clear about consequences
+- Provide easy resolution path
+- Include support contact
+
+### Notifications & Updates
+
+#### Feature Announcements (Transactional)
+
+**When to send:** When a feature the user is using changes significantly.
+
+**Purpose:** Notify users of changes that affect their use of the service.
+
+**Content should include:**
+- What changed
+- How it affects the user
+- What action (if any) is needed
+- Link to more information
+
+**Best practices:**
+- Only for significant changes
+- Focus on user impact
+- Provide clear next steps
+- Link to documentation
+
+**Note:** General feature announcements are marketing emails. Only send as transactional if the change directly affects an active feature the user is using.
+
+## Related Topics
+
+- [Email Types](./email-types.md) - Understanding transactional vs marketing
+- [Transactional Emails](./transactional-emails.md) - Best practices for sending transactional emails
+- [Compliance](./compliance.md) - Legal requirements for each email type

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

@@ -0,0 +1,92 @@
+# Transactional Email Best Practices
+
+Clear, actionable emails that users expect and need—password resets, confirmations, OTPs.
+
+## Core Principles
+
+1. **Clarity over creativity** - Users need to understand and act quickly
+2. **Action-oriented** - Clear purpose, obvious primary action
+3. **Time-sensitive** - Send immediately (within seconds)
+
+## Subject Lines
+
+**Be specific and include context:**
+
+| ✅ Good | ❌ Bad |
+|---------|--------|
+| Reset your password for [App] | Action required |
+| Your order #12345 has shipped | Update on your order |
+| Your 2FA code for [App] | Security code: 12345 |
+| Verify your email for [App] | Verify your email |
+
+Include identifiers when helpful: order numbers, account names, expiration times.
+
+## Pre-Header
+
+The text snippet after subject line. Use it to:
+- Reinforce subject ("This link expires in 1 hour")
+- Add urgency or context
+- Call-to-action preview
+
+Keep under 90 characters.
+
+## Content Structure
+
+**Above the fold (first screen):**
+- Clear purpose
+- Primary action button
+- Time-sensitive details (expiration)
+
+**Hierarchy:** Header → Primary message → Details → Action button → Secondary info
+
+**Format:** Short paragraphs (2-3 sentences), bullet points, bold for emphasis, white space.
+
+## Mobile-First Design
+
+60%+ emails are opened on mobile.
+
+- **Layout:** Single column, stack vertically
+- **Buttons:** 44x44px minimum, full-width on mobile
+- **Text:** 16px minimum body, 20-24px headings
+- **OTP codes:** 24-32px, monospace font
+
+## Sender Configuration
+
+| Field | Best Practice | Example |
+|-------|--------------|---------|
+| From Name | App/company name, consistent | [App Name] |
+| From Email | Subdomain, real address | hello@mail.example.com |
+| Reply-To | Monitored inbox | support@example.com |
+
+Avoid `noreply@` - users reply to transactional emails.
+
+## Code and Link Display
+
+**OTP/Verification codes:**
+- Large (24-32px), monospace font
+- Centered, clear label
+- Include expiration nearby
+- Make copyable
+
+**Buttons:**
+- Large, tappable (44x44px+)
+- Contrasting colors
+- Clear action text ("Reset Password", "Verify Email")
+- HTTPS links only
+
+## Error Handling
+
+**Resend functionality:**
+- Allow after 60 seconds
+- Limit attempts (3 per hour)
+- Show countdown timer
+
+**Expired links:**
+- Clear "expired" message
+- Offer to send new link
+- Provide support contact
+
+**"I didn't request this":**
+- Include in password resets, OTPs, security alerts
+- Link to security contact
+- Log clicks for monitoring