perspectapi-ts-sdk 6.5.9 → 7.0.1

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

@@ -0,0 +1,1396 @@
+# Contact Form 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 a robust contact form system with spam prevention, rate limiting, CAPTCHA support, and comprehensive admin management capabilities.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Core Features](#core-features)
+- [API Reference](#api-reference)
+  - [Public Methods](#public-methods)
+  - [Admin Methods](#admin-methods)
+- [Security Features](#security-features)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+- [Error Handling](#error-handling)
+
+## Quick Start
+
+```typescript
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+
+// Browser-based submission with CSRF protection
+const csrfResponse = await client.getCsrfToken('my-site');
+const csrfToken = csrfResponse.data.token;
+
+// Submit a contact form with CSRF token
+const submission = await client.contact.submitContact('my-site', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  subject: 'Product Inquiry',
+  message: 'I would like to know more about your products.'
+}, csrfToken); // Pass CSRF token for security
+```
+
+## Core Features
+
+- **Spam Prevention**: Multiple layers including honeypot fields, rate limiting, and CAPTCHA
+- **Cloudflare Turnstile**: Built-in support for privacy-focused CAPTCHA
+- **Rate Limiting**: Automatic prevention of abuse (5 submissions per 15 minutes per IP/email)
+- **Email Notifications**: Automatic notifications to site owners
+- **Status Tracking**: Track submission status (pending, read, archived)
+- **Admin Management**: Complete admin interface for managing submissions
+- **Bulk Operations**: Process multiple submissions at once
+- **Export Capability**: Export submissions in various formats
+- **Custom Fields**: Support for additional metadata
+
+## API Reference
+
+### Public Methods
+
+#### `submitContact(siteName, data)`
+
+Submit a contact form to a specific site.
+
+```typescript
+interface CreateContactRequest {
+  name: string;                 // Required: Full name
+  email: string;                // Required: Valid email address
+  subject?: string;             // Optional: Subject line
+  message: string;              // Required: Message content
+  phone?: string;               // Optional: Phone number
+  company?: string;             // Optional: Company name
+  turnstileToken?: string;      // Optional: Cloudflare Turnstile response
+  metadata?: Record<string, any>; // Optional: Additional custom data
+}
+
+// Example with CSRF token (for browser-based forms)
+const csrfToken = (await client.getCsrfToken('my-site')).data.token;
+
+const submission = await client.contact.submitContact('my-site', {
+  name: 'Jane Smith',
+  email: 'jane@company.com',
+  subject: 'Partnership Opportunity',
+  message: 'We are interested in partnering with your company...',
+  phone: '+1-555-0123',
+  company: 'Tech Corp',
+  turnstileToken: 'turnstile-response-token',
+  metadata: {
+    source: 'contact-page',
+    campaign: 'q4-2024'
+  }
+}, csrfToken); // Pass CSRF token
+
+// Response
+{
+  success: true,
+  code: "CONTACT_SUBMITTED",
+  contact_id: "contact_abc123",
+  message: "Contact form submitted successfully",
+  status: "submitted"
+}
+```
+
+#### `getContactStatus(siteName, id)`
+
+Check the status of a contact submission.
+
+```typescript
+const status = await client.contact.getContactStatus('my-site', 'contact_abc123');
+
+// Response
+{
+  success: true,
+  code: "CONTACT_FOUND",
+  contact_id: "contact_abc123",
+  status: "pending",  // or "read", "replied", "archived"
+  submitted_at: "2024-01-15T10:30:00Z",
+  processed_at: null,
+  metadata: {}
+}
+```
+
+### Admin Methods
+
+#### `getContactSubmissions(siteName, params)`
+
+Get all contact submissions with filtering and pagination.
+
+```typescript
+const submissions = await client.contact.getContactSubmissions('my-site', {
+  page: 1,
+  limit: 50,
+  status: 'unread',        // Filter by status
+  startDate: '2024-01-01', // Date range start
+  endDate: '2024-01-31',   // Date range end
+  search: 'product'        // Search in name, email, subject, message
+});
+
+// Response includes paginated list of submissions
+{
+  data: [
+    {
+      id: "contact_123",
+      name: "John Doe",
+      email: "john@example.com",
+      subject: "Product Question",
+      message: "...",
+      status: "unread",
+      createdAt: "2024-01-15T10:30:00Z"
+    }
+    // ...
+  ],
+  pagination: {
+    page: 1,
+    limit: 50,
+    total: 234,
+    totalPages: 5
+  }
+}
+```
+
+#### `getContactSubmissionById(siteName, id)`
+
+Get detailed information about a specific submission.
+
+```typescript
+const submission = await client.contact.getContactSubmissionById(
+  'my-site',
+  'contact_abc123'
+);
+
+// Response includes full details
+{
+  id: "contact_abc123",
+  name: "Jane Smith",
+  email: "jane@example.com",
+  subject: "Partnership Inquiry",
+  message: "Full message content...",
+  phone: "+1-555-0123",
+  company: "Tech Corp",
+  status: "pending",
+  ipAddress: "203.0.113.0",
+  userAgent: "Mozilla/5.0...",
+  metadata: {
+    source: "contact-page",
+    campaign: "q4-2024"
+  },
+  createdAt: "2024-01-15T10:30:00Z"
+}
+```
+
+#### `updateContactStatus(siteName, id, status, notes?)`
+
+Update the status of a contact submission.
+
+```typescript
+await client.contact.updateContactStatus(
+  'my-site',
+  'contact_abc123',
+  'replied',
+  'Responded via email on Jan 16'
+);
+```
+
+#### `markContactAsRead(siteName, id)`
+
+Mark a submission as read.
+
+```typescript
+await client.contact.markContactAsRead('my-site', 'contact_abc123');
+```
+
+#### `markContactAsUnread(siteName, id)`
+
+Mark a submission as unread.
+
+```typescript
+await client.contact.markContactAsUnread('my-site', 'contact_abc123');
+```
+
+#### `archiveContact(siteName, id)`
+
+Archive a contact submission.
+
+```typescript
+await client.contact.archiveContact('my-site', 'contact_abc123');
+```
+
+#### `deleteContact(siteName, id)`
+
+Permanently delete a contact submission.
+
+```typescript
+await client.contact.deleteContact('my-site', 'contact_abc123');
+```
+
+#### `bulkUpdateContacts(siteName, data)`
+
+Perform bulk operations on multiple submissions.
+
+```typescript
+const result = await client.contact.bulkUpdateContacts('my-site', {
+  ids: ['contact_1', 'contact_2', 'contact_3'],
+  action: 'mark_read'  // or 'mark_unread', 'archive', 'delete'
+});
+
+// Response
+{
+  success: true,
+  updatedCount: 3,
+  failedCount: 0
+}
+```
+
+#### `getContactStats(siteName, params)`
+
+Get contact form statistics.
+
+```typescript
+const stats = await client.contact.getContactStats('my-site', {
+  startDate: '2024-01-01',
+  endDate: '2024-01-31'
+});
+
+// Response
+{
+  totalSubmissions: 234,
+  unreadSubmissions: 12,
+  readSubmissions: 200,
+  archivedSubmissions: 22,
+  submissionsByDay: [
+    { date: "2024-01-01", count: 8 },
+    { date: "2024-01-02", count: 12 },
+    // ...
+  ],
+  submissionsByStatus: {
+    pending: 12,
+    read: 200,
+    archived: 22
+  },
+  averageResponseTime: 3600000  // milliseconds
+}
+```
+
+#### `exportContacts(siteName, params)`
+
+Export contact submissions to various formats.
+
+```typescript
+const exportData = await client.contact.exportContacts('my-site', {
+  format: 'csv',           // or 'json', 'xlsx'
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+  status: 'all'
+});
+
+// Response
+{
+  downloadUrl: "https://api.example.com/exports/contacts_export_123.csv",
+  expiresAt: "2024-01-16T10:30:00Z"
+}
+```
+
+#### `getContactConfig(siteName)`
+
+Get contact form configuration.
+
+```typescript
+const config = await client.contact.getContactConfig('my-site');
+
+// Response
+{
+  turnstileEnabled: true,
+  rateLimitEnabled: true,
+  rateLimitWindow: 900,    // seconds (15 minutes)
+  rateLimitMax: 5,
+  requiredFields: ['name', 'email', 'message'],
+  customFields: [
+    {
+      name: 'department',
+      type: 'select',
+      required: false,
+      label: 'Department'
+    }
+  ]
+}
+```
+
+#### `updateContactConfig(siteName, config)`
+
+Update contact form configuration (admin only).
+
+```typescript
+await client.contact.updateContactConfig('my-site', {
+  turnstileEnabled: true,
+  rateLimitEnabled: true,
+  rateLimitWindow: 600,  // 10 minutes
+  rateLimitMax: 3,
+  requiredFields: ['name', 'email', 'message', 'phone'],
+  customFields: [
+    {
+      name: 'urgency',
+      type: 'select',
+      required: true,
+      label: 'How urgent is your request?'
+    }
+  ]
+});
+```
+
+## Response Format
+
+All contact 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 (optional)
+- Additional response-specific data
+
+```typescript
+// Successful contact submission
+{
+  success: true,
+  code: "CONTACT_SUBMITTED",
+  contact_id: "contact_abc123",
+  message: "Contact form submitted successfully",
+  status: "submitted"
+}
+
+// Contact status lookup
+{
+  success: true,
+  code: "CONTACT_FOUND",
+  contact_id: "contact_abc123",
+  status: "pending",
+  submitted_at: "2024-01-15T10:30:00Z",
+  processed_at: null,
+  metadata: {}
+}
+
+// Bulk operations
+{
+  success: true,
+  code: "CONTACTS_UPDATED",
+  updatedCount: 5,
+  failedCount: 0
+}
+```
+
+### 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: "Rate limit exceeded. Please try again later.",
+  remaining_submissions: 0
+}
+
+// Validation error
+{
+  success: false,
+  code: "VALIDATION_ERROR", 
+  error: "Validation failed",
+  details: {
+    fieldErrors: {
+      email: ["Invalid email format"],
+      message: ["Message is required"]
+    }
+  }
+}
+
+// Contact not found
+{
+  success: false,
+  code: "CONTACT_NOT_FOUND",
+  error: "Contact not found"
+}
+```
+
+### Response Codes
+
+#### Success Codes (`success: true`)
+- `CONTACT_SUBMITTED` - Contact form submitted successfully
+- `CONTACT_FOUND` - Contact record retrieved
+- `CONTACTS_LISTED` - Contact list retrieved
+- `CONTACTS_UPDATED` - Bulk update completed
+
+#### Error Codes (`success: false`)
+- `INVALID_BODY` - Malformed request data
+- `VALIDATION_ERROR` - Field validation failed
+- `SITE_NOT_FOUND` - Site not found
+- `RATE_LIMITED` - Too many submissions
+- `CONTACT_NOT_FOUND` - Contact record not found
+- `MISSING_SITE_ID` - Site ID parameter missing
+- `UNAUTHORIZED` - Invalid authentication
+- `DATABASE_ERROR` - Database operation failed
+- `SERVER_ERROR` - Internal server error
+
+### Handling Responses
+
+```typescript
+const result = await client.contact.submitContact('my-site', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  message: 'Hello world'
+}, csrfToken);
+
+// Type-safe response handling
+if (result.data?.success) {
+  switch (result.data.code) {
+    case 'CONTACT_SUBMITTED':
+      showSuccess('Your message has been sent successfully!');
+      // Redirect to thank you page
+      break;
+  }
+} else {
+  switch (result.data?.code) {
+    case 'RATE_LIMITED':
+      showError('Please wait before sending another message');
+      break;
+    case 'VALIDATION_ERROR':
+      showValidationErrors(result.data.details);
+      break;
+    default:
+      showError(result.data?.error || 'Something went wrong');
+  }
+}
+```
+
+## Security Features
+
+### 1. Cloudflare Turnstile Integration
+
+```typescript
+// Client-side: Get Turnstile token
+const turnstileToken = await getTurnstileResponse();
+
+// Include token in submission
+const submission = await client.contact.submitContact('my-site', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  message: 'Hello',
+  turnstileToken  // Required when Turnstile is enabled
+});
+```
+
+### 2. Honeypot Field
+
+The API automatically handles honeypot fields to catch bots:
+
+```typescript
+// In your HTML form
+<input type="text" name="hp" style="display: none" />
+
+// The SDK handles this automatically
+// If honeypot is filled, submission is silently rejected
+```
+
+### 3. Rate Limiting
+
+Built-in rate limiting prevents abuse:
+- 5 submissions per 15 minutes per IP/email combination
+- Returns 429 status when limit exceeded
+- Automatic cleanup of old rate limit records
+
+### 4. CSRF Protection
+
+The API requires CSRF tokens for browser-based submissions:
+
+```typescript
+// Fetch CSRF token with proper credentials
+const csrfResponse = await fetch('https://api.example.com/api/v1/csrf/token/my-site', {
+  credentials: 'same-origin', // Include cookies for session
+  headers: {
+    'X-API-Key': 'your-api-key'
+  }
+});
+const csrfData = await csrfResponse.json();
+const csrfToken = csrfData.token;
+
+// Use token in SDK
+const submission = await client.contact.submitContact('my-site', formData, csrfToken);
+```
+
+**Important**: Never auto-fetch CSRF tokens in the SDK itself, as this defeats the security purpose. The client application must fetch and provide the token.
+
+## Best Practices
+
+### 1. Always Use Turnstile for Public Forms
+
+```typescript
+// React component example
+function ContactForm() {
+  const [turnstileToken, setTurnstileToken] = useState('');
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Form fields */}
+      
+      <Turnstile
+        sitekey={process.env.REACT_APP_TURNSTILE_SITE_KEY}
+        onVerify={(token) => setTurnstileToken(token)}
+      />
+      
+      <button type="submit">Send Message</button>
+    </form>
+  );
+}
+```
+
+### 2. Implement Proper Error Handling
+
+```typescript
+try {
+  const submission = await client.contact.submitContact('my-site', formData);
+  showSuccess('Message sent successfully!');
+} catch (error) {
+  if (error.status === 429) {
+    showError('Too many submissions. Please wait before trying again.');
+  } else if (error.status === 400) {
+    showError('Please check your input and try again.');
+  } else {
+    showError('Something went wrong. Please try again later.');
+  }
+}
+```
+
+### 3. Validate on Both Client and Server
+
+```typescript
+// Client-side validation
+function validateForm(data) {
+  const errors = {};
+  
+  if (!data.name || data.name.length < 2) {
+    errors.name = 'Name must be at least 2 characters';
+  }
+  
+  if (!isValidEmail(data.email)) {
+    errors.email = 'Please enter a valid email';
+  }
+  
+  if (!data.message || data.message.length < 10) {
+    errors.message = 'Message must be at least 10 characters';
+  }
+  
+  return errors;
+}
+
+// Server validates automatically via the API
+```
+
+### 4. Implement Admin Notifications
+
+```typescript
+// Set up webhook or polling for new submissions
+async function checkNewSubmissions() {
+  const submissions = await client.contact.getContactSubmissions('my-site', {
+    status: 'unread',
+    limit: 10
+  });
+  
+  if (submissions.data.length > 0) {
+    // Send notification to admin
+    notifyAdmin(`You have ${submissions.data.length} new messages`);
+  }
+}
+
+// Run every 5 minutes
+setInterval(checkNewSubmissions, 5 * 60 * 1000);
+```
+
+## Examples
+
+### React Contact Form Component
+
+```tsx
+import React, { useState } from 'react';
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+import { Turnstile } from '@marsidev/react-turnstile';
+
+interface FormData {
+  name: string;
+  email: string;
+  subject: string;
+  message: string;
+  phone?: string;
+  company?: string;
+}
+
+export function ContactForm() {
+  const [formData, setFormData] = useState<FormData>({
+    name: '',
+    email: '',
+    subject: '',
+    message: ''
+  });
+  const [turnstileToken, setTurnstileToken] = useState('');
+  const [csrfToken, setCsrfToken] = useState<string | null>(null);
+  const [status, setStatus] = useState<'idle' | 'submitting' | 'success' | 'error'>('idle');
+  const [errorMessage, setErrorMessage] = useState('');
+
+  const client = createPerspectApiClient({
+    baseUrl: process.env.REACT_APP_API_URL!,
+    apiKey: process.env.REACT_APP_API_KEY!
+  });
+
+  // Fetch CSRF token on component mount
+  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 handleInputChange = (
+    e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>
+  ) => {
+    const { name, value } = e.target;
+    setFormData(prev => ({ ...prev, [name]: value }));
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    if (!csrfToken) {
+      setErrorMessage('Security token not loaded. Please refresh and try again.');
+      return;
+    }
+    
+    setStatus('submitting');
+    setErrorMessage('');
+
+    try {
+      const result = await client.contact.submitContact('my-site', {
+        ...formData,
+        turnstileToken,
+        metadata: {
+          source: 'contact-page',
+          timestamp: new Date().toISOString()
+        }
+      }, csrfToken); // Pass CSRF token
+
+      setStatus('success');
+      setFormData({
+        name: '',
+        email: '',
+        subject: '',
+        message: ''
+      });
+      
+      // Show success message
+      alert('Thank you for your message! We\'ll get back to you soon.');
+    } catch (error: any) {
+      setStatus('error');
+      
+      if (error.status === 429) {
+        setErrorMessage('Too many submissions. Please wait a few minutes.');
+      } else if (error.status === 400) {
+        setErrorMessage('Please check your input and try again.');
+      } else {
+        setErrorMessage('Something went wrong. Please try again later.');
+      }
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="contact-form">
+      <div className="form-group">
+        <label htmlFor="name">Name *</label>
+        <input
+          type="text"
+          id="name"
+          name="name"
+          value={formData.name}
+          onChange={handleInputChange}
+          required
+          disabled={status === 'submitting'}
+        />
+      </div>
+
+      <div className="form-group">
+        <label htmlFor="email">Email *</label>
+        <input
+          type="email"
+          id="email"
+          name="email"
+          value={formData.email}
+          onChange={handleInputChange}
+          required
+          disabled={status === 'submitting'}
+        />
+      </div>
+
+      <div className="form-group">
+        <label htmlFor="phone">Phone</label>
+        <input
+          type="tel"
+          id="phone"
+          name="phone"
+          value={formData.phone || ''}
+          onChange={handleInputChange}
+          disabled={status === 'submitting'}
+        />
+      </div>
+
+      <div className="form-group">
+        <label htmlFor="company">Company</label>
+        <input
+          type="text"
+          id="company"
+          name="company"
+          value={formData.company || ''}
+          onChange={handleInputChange}
+          disabled={status === 'submitting'}
+        />
+      </div>
+
+      <div className="form-group">
+        <label htmlFor="subject">Subject</label>
+        <input
+          type="text"
+          id="subject"
+          name="subject"
+          value={formData.subject}
+          onChange={handleInputChange}
+          disabled={status === 'submitting'}
+        />
+      </div>
+
+      <div className="form-group">
+        <label htmlFor="message">Message *</label>
+        <textarea
+          id="message"
+          name="message"
+          value={formData.message}
+          onChange={handleInputChange}
+          rows={5}
+          required
+          disabled={status === 'submitting'}
+        />
+      </div>
+
+      {/* Honeypot field - hidden from users */}
+      <input
+        type="text"
+        name="hp"
+        style={{ display: 'none' }}
+        tabIndex={-1}
+        autoComplete="off"
+      />
+
+      {/* Turnstile CAPTCHA */}
+      <div className="form-group">
+        <Turnstile
+          sitekey={process.env.REACT_APP_TURNSTILE_SITE_KEY!}
+          onVerify={(token) => setTurnstileToken(token)}
+        />
+      </div>
+
+      {errorMessage && (
+        <div className="error-message">{errorMessage}</div>
+      )}
+
+      <button 
+        type="submit" 
+        disabled={status === 'submitting' || !turnstileToken || !csrfToken}
+      >
+        {status === 'submitting' ? 'Sending...' : 'Send Message'}
+      </button>
+
+      {status === 'success' && (
+        <div className="success-message">
+          Message sent successfully!
+        </div>
+      )}
+    </form>
+  );
+}
+```
+
+### Vue.js Contact Form
+
+```vue
+<template>
+  <form @submit.prevent="submitForm" class="contact-form">
+    <div class="form-group">
+      <label for="name">Name *</label>
+      <input
+        v-model="formData.name"
+        type="text"
+        id="name"
+        required
+        :disabled="isSubmitting"
+      />
+    </div>
+
+    <div class="form-group">
+      <label for="email">Email *</label>
+      <input
+        v-model="formData.email"
+        type="email"
+        id="email"
+        required
+        :disabled="isSubmitting"
+      />
+    </div>
+
+    <div class="form-group">
+      <label for="message">Message *</label>
+      <textarea
+        v-model="formData.message"
+        id="message"
+        rows="5"
+        required
+        :disabled="isSubmitting"
+      ></textarea>
+    </div>
+
+    <!-- Honeypot -->
+    <input
+      type="text"
+      name="hp"
+      v-model="honeypot"
+      style="display: none"
+    />
+
+    <!-- Turnstile -->
+    <div ref="turnstileContainer"></div>
+
+    <div v-if="errorMessage" class="error">
+      {{ errorMessage }}
+    </div>
+
+    <button type="submit" :disabled="isSubmitting || !turnstileToken">
+      {{ isSubmitting ? 'Sending...' : 'Send Message' }}
+    </button>
+  </form>
+</template>
+
+<script>
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+export default {
+  data() {
+    return {
+      formData: {
+        name: '',
+        email: '',
+        message: ''
+      },
+      honeypot: '',
+      turnstileToken: '',
+      csrfToken: null,
+      isSubmitting: false,
+      errorMessage: ''
+    };
+  },
+  async mounted() {
+    // Fetch CSRF token
+    const client = createPerspectApiClient({
+      baseUrl: process.env.VUE_APP_API_URL,
+      apiKey: process.env.VUE_APP_API_KEY
+    });
+    
+    try {
+      const response = await client.getCsrfToken('my-site');
+      this.csrfToken = response.data.token;
+    } catch (error) {
+      console.error('Failed to fetch CSRF token:', error);
+    }
+    
+    // Initialize Turnstile
+    window.turnstile.render(this.$refs.turnstileContainer, {
+      sitekey: process.env.VUE_APP_TURNSTILE_SITE_KEY,
+      callback: (token) => {
+        this.turnstileToken = token;
+      }
+    });
+  },
+  methods: {
+    async submitForm() {
+      if (this.honeypot) return; // Bot detected
+      
+      if (!this.csrfToken) {
+        this.errorMessage = 'Security token not loaded. Please refresh.';
+        return;
+      }
+
+      this.isSubmitting = true;
+      this.errorMessage = '';
+
+      const client = createPerspectApiClient({
+        baseUrl: process.env.VUE_APP_API_URL,
+        apiKey: process.env.VUE_APP_API_KEY
+      });
+
+      try {
+        await client.contact.submitContact('my-site', {
+          ...this.formData,
+          turnstileToken: this.turnstileToken
+        }, this.csrfToken); // Pass CSRF token
+
+        // Reset form
+        this.formData = {
+          name: '',
+          email: '',
+          message: ''
+        };
+        window.turnstile.reset();
+        
+        alert('Message sent successfully!');
+      } catch (error) {
+        this.handleError(error);
+      } finally {
+        this.isSubmitting = false;
+      }
+    },
+    handleError(error) {
+      if (error.status === 429) {
+        this.errorMessage = 'Too many attempts. Please wait.';
+      } else {
+        this.errorMessage = 'Failed to send message. Please try again.';
+      }
+    }
+  }
+};
+</script>
+```
+
+### Next.js API Route Handler
+
+```typescript
+// pages/api/contact.ts or app/api/contact/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  
+  // Initialize SDK with server-side credentials
+  const client = createPerspectApiClient({
+    baseUrl: process.env.PERSPECT_API_URL!,
+    apiKey: process.env.PERSPECT_API_KEY!
+  });
+
+  try {
+    // Server-side validation
+    if (!body.name || !body.email || !body.message) {
+      return NextResponse.json(
+        { error: 'Missing required fields' },
+        { status: 400 }
+      );
+    }
+
+    // Submit to PerspectAPI
+    const result = await client.contact.submitContact(
+      process.env.SITE_NAME!,
+      {
+        name: body.name,
+        email: body.email,
+        subject: body.subject,
+        message: body.message,
+        phone: body.phone,
+        company: body.company,
+        turnstileToken: body.turnstileToken,
+        metadata: {
+          ip: request.ip,
+          userAgent: request.headers.get('user-agent'),
+          source: 'website'
+        }
+      }
+    );
+
+    return NextResponse.json({
+      success: true,
+      id: result.data.id,
+      message: 'Contact form submitted successfully'
+    });
+  } catch (error: any) {
+    console.error('Contact form error:', error);
+    
+    if (error.status === 429) {
+      return NextResponse.json(
+        { error: 'Too many submissions. Please wait.' },
+        { status: 429 }
+      );
+    }
+    
+    return NextResponse.json(
+      { error: 'Failed to submit contact form' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Admin Dashboard Component
+
+```typescript
+// Admin dashboard for managing contact submissions
+import { useState, useEffect } from 'react';
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+export function ContactAdmin() {
+  const [submissions, setSubmissions] = useState([]);
+  const [stats, setStats] = useState(null);
+  const [filter, setFilter] = useState('unread');
+  
+  const client = createPerspectApiClient({
+    baseUrl: process.env.REACT_APP_API_URL!,
+    jwt: localStorage.getItem('adminToken')!
+  });
+
+  useEffect(() => {
+    loadSubmissions();
+    loadStats();
+  }, [filter]);
+
+  const loadSubmissions = async () => {
+    const result = await client.contact.getContactSubmissions('my-site', {
+      status: filter === 'all' ? undefined : filter,
+      limit: 50,
+      page: 1
+    });
+    setSubmissions(result.data);
+  };
+
+  const loadStats = async () => {
+    const stats = await client.contact.getContactStats('my-site');
+    setStats(stats.data);
+  };
+
+  const markAsRead = async (id: string) => {
+    await client.contact.markContactAsRead('my-site', id);
+    await loadSubmissions();
+  };
+
+  const archiveSubmission = async (id: string) => {
+    await client.contact.archiveContact('my-site', id);
+    await loadSubmissions();
+  };
+
+  const exportSubmissions = async () => {
+    const result = await client.contact.exportContacts('my-site', {
+      format: 'csv',
+      status: filter === 'all' ? undefined : filter
+    });
+    
+    // Download the export
+    window.open(result.data.downloadUrl, '_blank');
+  };
+
+  const bulkMarkRead = async () => {
+    const unreadIds = submissions
+      .filter(s => s.status === 'unread')
+      .map(s => s.id);
+    
+    if (unreadIds.length > 0) {
+      await client.contact.bulkUpdateContacts('my-site', {
+        ids: unreadIds,
+        action: 'mark_read'
+      });
+      await loadSubmissions();
+    }
+  };
+
+  return (
+    <div className="contact-admin">
+      <div className="stats">
+        {stats && (
+          <>
+            <div>Total: {stats.totalSubmissions}</div>
+            <div>Unread: {stats.unreadSubmissions}</div>
+            <div>Archived: {stats.archivedSubmissions}</div>
+          </>
+        )}
+      </div>
+
+      <div className="actions">
+        <select value={filter} onChange={(e) => setFilter(e.target.value)}>
+          <option value="all">All</option>
+          <option value="unread">Unread</option>
+          <option value="read">Read</option>
+          <option value="archived">Archived</option>
+        </select>
+        
+        <button onClick={bulkMarkRead}>Mark All Read</button>
+        <button onClick={exportSubmissions}>Export CSV</button>
+      </div>
+
+      <div className="submissions">
+        {submissions.map(submission => (
+          <div key={submission.id} className="submission-card">
+            <div className="header">
+              <strong>{submission.name}</strong>
+              <span>{submission.email}</span>
+              <span>{new Date(submission.createdAt).toLocaleDateString()}</span>
+            </div>
+            
+            <div className="subject">{submission.subject}</div>
+            <div className="message">{submission.message}</div>
+            
+            <div className="actions">
+              {submission.status === 'unread' && (
+                <button onClick={() => markAsRead(submission.id)}>
+                  Mark Read
+                </button>
+              )}
+              <button onClick={() => archiveSubmission(submission.id)}>
+                Archive
+              </button>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Cloudflare Worker for Contact Processing
+
+```typescript
+// Cloudflare Worker to handle contact forms
+import { createPerspectApiClient } from 'perspectapi-ts-sdk';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.method !== 'POST') {
+      return new Response('Method not allowed', { status: 405 });
+    }
+
+    const client = createPerspectApiClient({
+      baseUrl: env.API_URL,
+      apiKey: env.API_KEY
+    });
+
+    try {
+      const formData = await request.json();
+      
+      // Get client IP for rate limiting
+      const clientIp = request.headers.get('CF-Connecting-IP');
+      
+      const result = await client.contact.submitContact(env.SITE_NAME, {
+        ...formData,
+        metadata: {
+          ip: clientIp,
+          country: request.cf?.country,
+          source: 'cloudflare-worker'
+        }
+      });
+
+      // Send email notification (optional)
+      await env.EMAIL_QUEUE.send({
+        to: env.ADMIN_EMAIL,
+        subject: `New Contact: ${formData.subject}`,
+        text: `New contact form submission from ${formData.name}`
+      });
+
+      return new Response(JSON.stringify({
+        success: true,
+        id: result.data.id
+      }), {
+        headers: { 'Content-Type': 'application/json' }
+      });
+    } catch (error: any) {
+      return new Response(JSON.stringify({
+        error: error.message
+      }), {
+        status: error.status || 500,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+  }
+};
+```
+
+## Error Handling
+
+```typescript
+import { createApiError } from 'perspectapi-ts-sdk';
+
+try {
+  await client.contact.submitContact('my-site', data);
+} catch (error) {
+  const apiError = createApiError(error);
+  
+  switch (apiError.status) {
+    case 400:
+      // Validation error
+      console.error('Invalid input:', apiError.details);
+      break;
+    case 429:
+      // Rate limited
+      console.warn('Too many requests, please wait');
+      break;
+    case 500:
+      // Server error
+      console.error('Server error, please try again');
+      break;
+    default:
+      console.error('Unexpected error:', apiError.message);
+  }
+}
+```
+
+## Rate Limiting
+
+The API enforces rate limits to prevent abuse:
+
+- **Default**: 5 submissions per 15 minutes per IP/email combination
+- **Response**: HTTP 429 when limit exceeded
+- **Reset**: Limits reset after the time window expires
+
+Handle rate limits gracefully:
+
+```typescript
+async function submitWithRetry(data: any, maxRetries = 3) {
+  let attempts = 0;
+  
+  while (attempts < maxRetries) {
+    try {
+      return await client.contact.submitContact('my-site', data);
+    } catch (error) {
+      if (error.status === 429 && attempts < maxRetries - 1) {
+        // Wait before retry (exponential backoff)
+        const delay = Math.pow(2, attempts) * 1000;
+        await new Promise(resolve => setTimeout(resolve, delay));
+        attempts++;
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+```
+
+## Testing
+
+```typescript
+// Jest test example
+describe('Contact Form', () => {
+  const client = createPerspectApiClient({
+    baseUrl: 'http://localhost:8787',
+    apiKey: 'test-key'
+  });
+
+  test('should submit contact form', async () => {
+    const result = await client.contact.submitContact('test-site', {
+      name: 'Test User',
+      email: 'test@example.com',
+      message: 'This is a test message'
+    });
+
+    expect(result.data.id).toBeDefined();
+    expect(result.data.status).toBe('pending');
+  });
+
+  test('should handle rate limiting', async () => {
+    // Submit multiple times to trigger rate limit
+    for (let i = 0; i < 5; i++) {
+      await client.contact.submitContact('test-site', {
+        name: 'Test User',
+        email: 'test@example.com',
+        message: `Message ${i}`
+      });
+    }
+
+    // 6th submission should fail
+    await expect(
+      client.contact.submitContact('test-site', {
+        name: 'Test User',
+        email: 'test@example.com',
+        message: 'This should fail'
+      })
+    ).rejects.toThrow('Too many requests');
+  });
+});
+```
+
+## Migration from Other Systems
+
+If migrating from another contact form system:
+
+```typescript
+// Example: Migrate from WordPress Contact Form 7
+async function migrateContacts(oldContacts: any[]) {
+  const client = createPerspectApiClient({
+    baseUrl: process.env.API_URL!,
+    apiKey: process.env.API_KEY!
+  });
+
+  for (const contact of oldContacts) {
+    // Transform old format to new
+    const submission = {
+      name: contact.your_name,
+      email: contact.your_email,
+      subject: contact.your_subject,
+      message: contact.your_message,
+      metadata: {
+        migrated: true,
+        originalId: contact.id,
+        originalDate: contact.date
+      }
+    };
+
+    try {
+      await client.contact.submitContact('my-site', submission);
+      console.log(`Migrated contact ${contact.id}`);
+    } catch (error) {
+      console.error(`Failed to migrate ${contact.id}:`, error);
+    }
+    
+    // Rate limit prevention
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+}
+```
+
+## Security Best Practices
+
+1. **Always use HTTPS** for API calls
+2. **Implement Turnstile** on public forms
+3. **Validate input** on both client and server
+4. **Use honeypot fields** for additional bot protection
+5. **Monitor rate limits** and adjust as needed
+6. **Sanitize output** when displaying submissions
+7. **Implement access controls** for admin functions
+8. **Log all submissions** for audit purposes
+9. **Regular backups** of contact data
+10. **GDPR compliance** - provide data export/deletion
+
+## Compliance
+
+The contact system helps with compliance:
+
+- **GDPR**: Data export, deletion capabilities
+- **CAN-SPAM**: Clear identification, no deceptive practices
+- **Privacy**: IP addresses stored for security, deletable on request
+- **Accessibility**: Form fields properly labeled for screen readers