perspectapi-ts-sdk 6.5.7 → 7.0.0

package/docs/v1-deprecated/legacy-docs/newsletter.md

@@ -0,0 +1,811 @@
+# Newsletter Subscription API Documentation
+
+> Deprecated v1 material. Do not copy these examples into new code. v1 sunsets
+> on 2026-06-01; use `createPerspectApiV2Client` from
+> `perspectapi-ts-sdk/v2` and `/api/v2`.
+
+The PerspectAPI SDK provides comprehensive newsletter support with GDPR-compliant double opt-in, list segmentation, preference management, and a strict split between public and management surfaces:
+
+- `client.newsletter`: public subscription flows only.
+- `client.newsletterManagement`: authenticated management APIs under `/newsletter/management/*`.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Core Features](#core-features)
+- [Subscription Flow](#subscription-flow)
+- [API Reference](#api-reference)
+  - [Public Methods](#public-methods)
+  - [Management Methods](#management-methods)
+- [Best Practices](#best-practices)
+- [Caching and Webhook Invalidation](#caching-and-webhook-invalidation)
+- [Examples](#examples)
+
+## Quick Start
+
+```typescript
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+
+// Browser-based subscription with CSRF protection
+const csrfResponse = await client.getCsrfToken('my-site');
+const csrfToken = csrfResponse.data.token;
+
+await client.newsletter.subscribe('my-site', {
+  email: 'user@example.com',
+  name: 'John Doe'
+}, csrfToken); // Pass CSRF token for security
+```
+
+## Core Features
+
+- **Double Opt-in**: GDPR-compliant email confirmation system
+- **One-click Unsubscribe**: Permanent tokens for easy unsubscription
+- **List Management**: Multiple segmented lists per site
+- **Preference Center**: User-controlled frequency, topics, and privacy settings
+- **Engagement Tracking**: Opens, clicks, bounces, and complaints
+- **Rate Limiting**: Built-in abuse prevention
+- **Import/Export**: Bulk operations for migration
+- **Statistics**: Comprehensive analytics and reporting
+
+## Subscription Flow
+
+### 1. Initial Subscription
+
+```typescript
+// For browser-based forms, always use CSRF protection
+const csrfResponse = await client.getCsrfToken('my-site');
+const csrfToken = csrfResponse.data.token;
+
+const result = await client.newsletter.subscribe('my-site', {
+  email: 'subscriber@example.com',
+  name: 'Jane Smith',
+  list_ids: ['list_weekly_digest', 'list_product_updates'],
+  frequency: 'weekly',
+  topics: ['tech', 'business'],
+  double_opt_in: true,  // Default: true
+  turnstile_token: 'cf-turnstile-response',  // Optional CAPTCHA
+  metadata: {
+    source: 'homepage-footer',
+    campaign: 'summer-2024'
+  }
+}, csrfToken); // Pass CSRF token
+
+// Response
+{
+  success: true,
+  code: "PENDING_CONFIRMATION",
+  message: "Please check your email to confirm your subscription",
+  status: "pending_confirmation"
+}
+```
+
+### 2. Email Confirmation
+
+User receives email with confirmation link containing a unique token:
+
+```typescript
+// When user clicks confirmation link
+const confirmed = await client.newsletter.confirmSubscription(
+  'my-site',
+  'confirmation-token-from-email'
+);
+
+// Response
+{
+  success: true,
+  code: "SUBSCRIPTION_CONFIRMED",
+  message: "Subscription confirmed successfully",
+  status: "confirmed",
+  subscription: {
+    email: "subscriber@example.com",
+    name: "Jane Smith",
+    frequency: "weekly"
+  }
+}
+```
+
+### 3. Managing Preferences
+
+```typescript
+// Update subscription preferences (requires CSRF in browser)
+const csrfToken = (await client.getCsrfToken('my-site')).data.token;
+
+await client.newsletter.updatePreferences('my-site', 'subscriber@example.com', {
+  frequency: 'monthly',
+  topics: ['product-updates', 'company-news'],
+  email_format: 'html',
+  timezone: 'Europe/London',
+  track_opens: true,
+  track_clicks: true
+}, csrfToken);
+```
+
+### 4. Unsubscription
+
+```typescript
+// Method 1: Unsubscribe by email (requires CSRF in browser)
+const csrfToken = (await client.getCsrfToken('my-site')).data.token;
+await client.newsletter.unsubscribe('my-site', {
+  email: 'subscriber@example.com',
+  reason: 'Too frequent'
+}, csrfToken);
+
+// Method 2: One-click unsubscribe (from email link, no CSRF needed)
+await client.newsletter.unsubscribeByToken('my-site', 'unsubscribe-token');
+```
+
+## Response Format
+
+All newsletter API methods return responses in a standardized format with consistent success/error handling:
+
+### Success Responses
+
+All successful responses include:
+- `success: true` - Indicates the operation completed successfully
+- `code: string` - Machine-readable status code for programmatic handling
+- `message: string` - Human-readable message for display to users
+- `status?: string` - Operation-specific status (e.g., "pending_confirmation", "confirmed")
+
+```typescript
+// Successful subscription (pending confirmation)
+{
+  success: true,
+  code: "PENDING_CONFIRMATION",
+  message: "Please check your email to confirm your subscription",
+  status: "pending_confirmation"
+}
+
+// Already subscribed
+{
+  success: true,
+  code: "ALREADY_SUBSCRIBED", 
+  message: "This email is already subscribed to our newsletter",
+  status: "confirmed"
+}
+
+// Subscription confirmed
+{
+  success: true,
+  code: "SUBSCRIPTION_CONFIRMED",
+  message: "Subscription confirmed successfully",
+  status: "confirmed",
+  subscription: { /* subscription details */ }
+}
+```
+
+### Error Responses
+
+Failed operations include:
+- `success: false` - Indicates the operation failed
+- `code: string` - Machine-readable error code
+- `error: string` - Error message describing what went wrong
+- `details?: any` - Additional error details (for validation errors)
+
+```typescript
+// Rate limiting
+{
+  success: false,
+  code: "RATE_LIMITED",
+  error: "Too many subscription attempts. Please try again later."
+}
+
+// Validation error
+{
+  success: false,
+  code: "VALIDATION_ERROR", 
+  error: "Invalid subscription data",
+  details: { /* validation error details */ }
+}
+
+// Invalid token
+{
+  success: false,
+  code: "CONFIRMATION_FAILED",
+  error: "Invalid or expired confirmation token"
+}
+```
+
+### Response Codes
+
+#### Success Codes (`success: true`)
+- `PENDING_CONFIRMATION` - Confirmation email sent
+- `SUBSCRIBED` - Subscription confirmed immediately  
+- `ALREADY_SUBSCRIBED` - Email already subscribed
+- `CONFIRMATION_RESENT` - Confirmation email resent
+- `SUBSCRIPTION_CONFIRMED` - Token confirmation successful
+- `UNSUBSCRIBED` - Successfully unsubscribed
+- `UNSUBSCRIBE_CONFIRMATION_SENT` - Unsubscribe email sent
+
+#### Error Codes (`success: false`)
+- `VALIDATION_ERROR` - Invalid input data
+- `RATE_LIMITED` - Too many requests
+- `MISSING_TOKEN` - Required token not provided
+- `CONFIRMATION_FAILED` - Token validation failed
+- `SUBSCRIPTION_NOT_FOUND` - Subscription doesn't exist
+- `UNSUBSCRIBE_FAILED` - Unsubscribe operation failed
+- `SERVER_ERROR` - Internal server error
+
+### Handling Responses
+
+```typescript
+const result = await client.newsletter.subscribe('my-site', {
+  email: 'user@example.com',
+  name: 'John Doe'
+}, csrfToken);
+
+// Type-safe response handling
+if (result.data?.success) {
+  switch (result.data.code) {
+    case 'PENDING_CONFIRMATION':
+      showMessage('Please check your email to confirm subscription');
+      break;
+    case 'ALREADY_SUBSCRIBED':
+      showMessage('You are already subscribed!');
+      break;
+    case 'SUBSCRIBED':
+      showMessage('Welcome! You have been subscribed.');
+      break;
+  }
+} else {
+  switch (result.data?.code) {
+    case 'RATE_LIMITED':
+      showError('Please slow down and try again later');
+      break;
+    case 'VALIDATION_ERROR':
+      showError('Please check your email address');
+      break;
+    default:
+      showError(result.data?.error || 'Something went wrong');
+  }
+}
+```
+
+## API Reference
+
+### Public Methods
+
+#### `subscribe(siteName, data)`
+
+Subscribe a new email to the newsletter.
+
+```typescript
+interface CreateNewsletterSubscriptionRequest {
+  email: string;                    // Required
+  name?: string;                    // Subscriber's name
+  list_ids?: string[];              // List IDs to subscribe to
+  frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
+  topics?: string[];                // Content topics of interest
+  language?: string;                // Preferred language (default: 'en')
+  source?: string;                  // Source of subscription
+  source_url?: string;              // URL where subscription occurred
+  double_opt_in?: boolean;          // Require email confirmation (default: true)
+  turnstile_token?: string;         // Cloudflare Turnstile token
+  metadata?: Record<string, any>;   // Custom metadata
+}
+```
+
+#### `confirmSubscription(siteName, token)`
+
+Confirm a pending subscription using the token from confirmation email.
+
+#### `unsubscribe(siteName, data)`
+
+Unsubscribe an email address.
+
+```typescript
+interface NewsletterUnsubscribeRequest {
+  token?: string;      // Unsubscribe token (for one-click)
+  email?: string;      // Email address (alternative to token)
+  reason?: string;     // Optional feedback
+}
+```
+
+#### `updatePreferences(siteName, email, preferences)`
+
+Update subscription preferences.
+
+```typescript
+interface NewsletterPreferences {
+  frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
+  topics?: string[];
+  language?: string;
+  email_format?: 'html' | 'text' | 'both';
+  timezone?: string;
+  track_opens?: boolean;
+  track_clicks?: boolean;
+}
+```
+
+#### `getStatus(siteName, email)`
+
+Check if an email is subscribed.
+
+#### `getLists(siteName)`
+
+Get all public newsletter lists available for subscription.
+
+#### `getPublishedCampaigns(siteName, params?, cachePolicy?)`
+
+Get publicly available newsletter campaigns (published only).
+
+```typescript
+const campaigns = await client.newsletter.getPublishedCampaigns('my-site', {
+  page: 1,
+  limit: 20,
+  search: 'spring launch'
+});
+```
+
+#### `getPublishedCampaignBySlug(siteName, slug, optionsOrPolicy?, cachePolicy?)`
+
+Get a single published newsletter campaign by bare slug.
+If your URL uses a prefix segment, pass it via `slugPrefix`.
+
+```typescript
+const campaign = await client.newsletter.getPublishedCampaignBySlug(
+  'my-site',
+  'spring-launch',
+  { slugPrefix: 'updates' }
+);
+```
+
+#### `invalidatePublishedCampaignCacheFromWebhook(payload, fallbackSiteName?)`
+
+Convert a webhook payload into newsletter cache tags and invalidate matching entries.
+
+This helper only invalidates for publish events. Create or draft updates are ignored.
+
+```typescript
+const result = await client.newsletter.invalidatePublishedCampaignCacheFromWebhook(
+  webhookPayload,
+  'my-site'
+);
+
+if (result.invalidated) {
+  console.log(result.tags); // tags that were invalidated
+}
+```
+
+### Management Methods
+
+All management methods are on `client.newsletterManagement`.
+
+#### `syncSubscription(siteName, data)`
+
+Canonical app-side upsert by email:
+
+```typescript
+const sync = await client.newsletterManagement.syncSubscription('my-site', {
+  email: 'user@example.com',
+  name: 'User Name',
+  list_ids: ['list_default'],
+  resubscribe_override: false
+});
+
+console.log(sync.data.code);
+// CREATED | UPDATED | RESUBSCRIBED | ALREADY_UNSUBSCRIBED
+```
+
+#### `listSubscriptions(siteName, params)`
+
+List and filter subscribers.
+
+```typescript
+const subscriptions = await client.newsletterManagement.listSubscriptions('my-site', {
+  page: 1,
+  limit: 100,
+  status: 'confirmed',
+  list_id: 'list_default'
+});
+```
+
+#### `importSubscriptions(siteName, data)`
+
+Bulk import with request-level and row-level `resubscribe_override` (row-level wins).
+
+```typescript
+const result = await client.newsletterManagement.importSubscriptions('my-site', {
+  resubscribe_override: false,
+  rows: [
+    { email: 'user1@example.com', list_ids: ['list_default'] },
+    { email: 'user2@example.com', resubscribe_override: true }
+  ]
+});
+
+console.log(result.data.applied, result.data.skipped_unsubscribed);
+```
+
+#### `createList`, `updateList`, `deleteList`
+
+Manage segmented lists:
+
+```typescript
+const list = await client.newsletterManagement.createList('my-site', {
+  list_name: 'Premium Members',
+  slug: 'premium-members',
+  is_public: false
+});
+```
+
+#### `createCampaign`, `updateCampaign`, `deleteCampaign`, `sendCampaignTest`
+
+Manage campaigns and send permission-gated test sends:
+
+```typescript
+await client.newsletterManagement.createCampaign('my-site', {
+  campaign_name: 'Spring Launch',
+  subject: 'Spring Launch',
+  markdown_content: '# Hello',
+  status: 'draft'
+});
+```
+
+#### `createExport(siteName, data)` and `downloadExport(siteName, exportId)`
+
+Exports support `csv` and `json`. `xlsx` is explicitly unsupported.
+
+```typescript
+const exportInfo = await client.newsletterManagement.createExport('my-site', {
+  format: 'csv'
+});
+
+const csv = await client.newsletterManagement.downloadExport(
+  'my-site',
+  exportInfo.data.exportId
+);
+```
+
+## Best Practices
+
+### 1. Always Use Double Opt-in
+
+```typescript
+// Good: Explicit double opt-in
+await client.newsletter.subscribe('my-site', {
+  email: 'user@example.com',
+  double_opt_in: true  // Default, but be explicit
+});
+
+// Only skip for imports from verified sources
+await client.newsletterManagement.importSubscriptions('my-site', {
+  rows: verifiedUsers,
+  resubscribe_override: true  // Only for trusted data
+});
+```
+
+### 2. Handle Rate Limiting
+
+The API includes built-in rate limiting. Handle 429 responses gracefully:
+
+```typescript
+try {
+  await client.newsletter.subscribe('my-site', data);
+} catch (error) {
+  if (error.status === 429) {
+    // Too many requests - implement exponential backoff
+    await wait(5000);
+    // Retry
+  }
+}
+```
+
+### 3. Segment with Lists
+
+Create targeted lists for better engagement:
+
+```typescript
+// Create segmented lists
+await client.newsletterManagement.createList('my-site', {
+  list_name: 'Tech Enthusiasts',
+  slug: 'tech-news',
+  description: 'Latest technology updates'
+});
+
+await client.newsletterManagement.createList('my-site', {
+  list_name: 'Business Updates',
+  slug: 'business-news',
+  description: 'Business and finance news'
+});
+
+// Subscribe to specific lists
+await client.newsletter.subscribe('my-site', {
+  email: 'techie@example.com',
+  list_ids: ['list_tech_news']
+});
+```
+
+### 4. Respect User Preferences
+
+```typescript
+// Check preferences before sending
+const status = await client.newsletter.getStatus('my-site', email);
+
+if (status.data.subscribed && status.data.frequency === 'instant') {
+  // OK to send immediate notification
+} else {
+  // Queue for digest based on frequency
+}
+```
+
+### 5. Monitor Engagement
+
+```typescript
+// Regular monitoring
+const stats = await client.newsletterManagement.getStats('my-site', {
+  startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
+  endDate: new Date().toISOString()
+});
+
+if ((stats.data.byStatus.unsubscribed || 0) > stats.data.total * 0.05) {
+  // High unsubscribe rate - investigate
+}
+```
+
+## Caching and Webhook Invalidation
+
+Published newsletter endpoints are cache-aware, including:
+
+- `getLists(siteName)`
+- `getPublishedCampaigns(siteName, params?)`
+- `getPublishedCampaignBySlug(siteName, slug, { slugPrefix? })`
+
+Recommended webhook flow:
+
+1. Receive and verify webhook payload.
+2. Call `invalidatePublishedCampaignCacheFromWebhook(payload, fallbackSiteName?)`.
+3. Only if `result.invalidated === true`, log/use `result.tags`.
+
+```typescript
+const result = await client.newsletter.invalidatePublishedCampaignCacheFromWebhook(
+  payload,
+  'my-site'
+);
+
+if (result.invalidated) {
+  console.log('Invalidated newsletter tags:', result.tags);
+}
+```
+
+The helper intentionally invalidates on publish transitions (for example `newsletter.published` or `content.published` with `origin_type = newsletter_campaign`) and does not invalidate on draft creation.
+
+## Examples
+
+### React Newsletter Signup Form with CSRF Protection
+
+```tsx
+import { useState, useEffect } from 'react';
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+function NewsletterSignup() {
+  const [email, setEmail] = useState('');
+  const [status, setStatus] = useState('idle');
+  const [csrfToken, setCsrfToken] = useState<string | null>(null);
+  
+  const client = createPerspectApiClient({ 
+    baseUrl: process.env.REACT_APP_API_URL,
+    apiKey: process.env.REACT_APP_API_KEY
+  });
+
+  // Fetch CSRF token when component mounts
+  useEffect(() => {
+    async function fetchCsrfToken() {
+      try {
+        const response = await client.getCsrfToken('my-site');
+        setCsrfToken(response.data.token || '');
+      } catch (error) {
+        console.error('Failed to fetch CSRF token:', error);
+      }
+    }
+    fetchCsrfToken();
+  }, []);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    if (!csrfToken) {
+      alert('Security token not loaded. Please refresh and try again.');
+      return;
+    }
+    
+    setStatus('subscribing');
+    
+    try {
+      const result = await client.newsletter.subscribe('my-site', {
+        email,
+        source: 'website-footer',
+        source_url: window.location.href
+      }, csrfToken); // Pass CSRF token
+      
+      setStatus('success');
+      setEmail('');
+      alert('Please check your email to confirm subscription!');
+    } catch (error) {
+      setStatus('error');
+      console.error('Subscription failed:', error);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Enter your email"
+        required
+        disabled={status === 'subscribing' || !csrfToken}
+      />
+      <button type="submit" disabled={status === 'subscribing' || !csrfToken}>
+        {status === 'subscribing' ? 'Subscribing...' : 'Subscribe'}
+      </button>
+      {status === 'success' && <p>Check your email to confirm!</p>}
+      {status === 'error' && <p>Something went wrong. Please try again.</p>}
+    </form>
+  );
+}
+```
+
+### Cloudflare Worker for Newsletter Confirmation
+
+```typescript
+// Handle confirmation links in a Cloudflare Worker
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    
+    // Match /newsletter/confirm/:token
+    const match = url.pathname.match(/^\/newsletter\/confirm\/([^\/]+)$/);
+    if (!match) {
+      return new Response('Not found', { status: 404 });
+    }
+
+    const token = match[1];
+    const client = createPerspectApiClient({
+      baseUrl: env.API_URL,
+      apiKey: env.API_KEY
+    });
+
+    try {
+      const result = await client.newsletter.confirmSubscription(
+        env.SITE_NAME,
+        token
+      );
+
+      // Redirect to success page
+      return Response.redirect(
+        `${env.SITE_URL}/newsletter-confirmed?email=${result.data.subscription.email}`,
+        302
+      );
+    } catch (error) {
+      // Redirect to error page
+      return Response.redirect(
+        `${env.SITE_URL}/newsletter-error?reason=invalid-token`,
+        302
+      );
+    }
+  }
+};
+```
+
+### Management Dashboard Integration
+
+```typescript
+// Newsletter admin dashboard
+async function NewsletterDashboard() {
+  const client = createPerspectApiClient({
+    baseUrl: API_URL,
+    jwt: adminToken
+  });
+
+  // Get overview statistics
+  const stats = await client.newsletterManagement.getStats('my-site');
+  
+  // Get recent subscriptions
+  const recent = await client.newsletterManagement.listSubscriptions('my-site', {
+    limit: 10,
+    status: 'confirmed',
+    startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString()
+  });
+
+  // Export for email campaign
+  const exportData = await client.newsletterManagement.createExport('my-site', {
+    format: 'csv',
+    status: 'confirmed',
+    list_id: 'list_marketing'
+  });
+
+  // Handle bounces from email provider webhook
+  await client.newsletterManagement.bulkUpdateSubscriptions('my-site', {
+    ids: bouncedEmailIds,
+    action: 'unsubscribe'
+  });
+}
+```
+
+## Error Handling
+
+```typescript
+import { createApiError } from 'perspectapi-ts-sdk';
+
+try {
+  await client.newsletter.subscribe('my-site', data);
+} catch (error) {
+  const apiError = createApiError(error);
+  
+  switch (apiError.status) {
+    case 400:
+      // Validation error
+      console.error('Invalid data:', apiError.details);
+      break;
+    case 409:
+      // Already subscribed
+      console.log('Email already subscribed');
+      break;
+    case 429:
+      // Rate limited
+      console.warn('Too many requests, please wait');
+      break;
+    default:
+      console.error('Subscription failed:', apiError.message);
+  }
+}
+```
+
+## Security Considerations
+
+1. **Always validate emails server-side**
+2. **Use Turnstile tokens for public forms**
+3. **Implement rate limiting (handled by API)**
+4. **Store unsubscribe tokens securely**
+5. **Never expose management methods to public users**
+6. **Use HTTPS for all API calls**
+7. **Validate webhook signatures for email provider callbacks**
+
+## Migration Guide
+
+If migrating from another newsletter system:
+
+```typescript
+// 1. Export from old system
+const oldSubscribers = await exportFromOldSystem();
+
+// 2. Transform data
+const formatted = oldSubscribers.map(sub => ({
+  email: sub.email,
+  name: `${sub.firstName} ${sub.lastName}`,
+  status: sub.isActive ? 'confirmed' : 'unsubscribed',
+  list_ids: mapOldListsToNew(sub.segments)
+}));
+
+// 3. Import in batches
+const BATCH_SIZE = 500;
+for (let i = 0; i < formatted.length; i += BATCH_SIZE) {
+  const batch = formatted.slice(i, i + BATCH_SIZE);
+  
+  const result = await client.newsletterManagement.importSubscriptions('my-site', {
+    rows: batch,
+    resubscribe_override: true  // Already confirmed in old system
+  });
+  
+  console.log(`Batch ${i/BATCH_SIZE + 1}: Applied ${result.data.applied}`);
+  
+  // Rate limit between batches
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+```
+
+## Compliance
+
+The newsletter system is designed to be compliant with:
+
+- **GDPR**: Double opt-in, right to erasure, data portability
+- **CAN-SPAM**: Easy unsubscribe, clear sender identification
+- **CASL**: Express consent, unsubscribe mechanism
+- **PECR**: Consent for electronic marketing
+
+Always consult with legal counsel for your specific requirements.