perspectapi-ts-sdk 6.5.9 → 7.0.0

package/docs/v1-deprecated/legacy-docs/site-users.md

@@ -0,0 +1,817 @@
+# Site Users Guide
+
+> 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`.
+
+Site Users are per-site customer accounts with OTP-based authentication. Each site can have its own set of users, separate from admin users.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Authentication Flow](#authentication-flow)
+- [Creating Waitlist Users](#creating-waitlist-users)
+- [Managing User Metadata](#managing-user-metadata)
+- [Managing User Profiles](#managing-user-profiles)
+- [Cross-Domain Authentication](#cross-domain-authentication)
+- [User Data Management](#user-data-management)
+- [Orders and Subscriptions](#orders-and-subscriptions)
+- [Admin Operations](#admin-operations)
+
+## Overview
+
+Site Users provide passwordless authentication using One-Time Passwords (OTP) sent via email. Each user belongs to a specific site and can have:
+
+- **Basic profile**: first name, last name, avatar, email verification status
+- **Waitlist flag**: Mark users as waitlist signups before service launch
+- **Metadata**: Arbitrary JSON object for custom per-site fields
+- **Profile key-values**: Structured storage for phone, addresses, preferences, etc.
+- **Order history**: Linked checkout sessions and transactions
+- **Subscriptions**: Payment subscriptions across providers (Stripe, etc.)
+
+## Authentication Flow
+
+### 1. Request OTP
+
+```typescript
+import { PerspectApiClient } from 'perspectapi-ts-sdk';
+
+const client = new PerspectApiClient({
+  baseUrl: 'https://api.yoursite.com'
+});
+
+// Request OTP for login/signup
+const response = await client.siteUsers.requestOtp(
+  'mysite',
+  { email: 'user@example.com' },
+  csrfToken  // Required for browser-based requests
+);
+
+// User receives email with 6-digit code
+```
+
+### 2. Verify OTP and Get Token
+
+```typescript
+// Option 1: Manual token management (recommended for production)
+const response = await client.siteUsers.verifyOtp(
+  'mysite',
+  {
+    email: 'user@example.com',
+    code: '123456'
+  },
+  csrfToken
+);
+
+const { token, user } = response.data;
+
+// Store token securely:
+// - Option A: httpOnly cookie on YOUR domain (recommended)
+await fetch('/your-api/set-auth-cookie', {
+  method: 'POST',
+  body: JSON.stringify({ token })
+});
+client.setAuth(token);
+
+// - Option B: Memory (lost on refresh, most secure)
+client.setAuth(token);
+
+// - Option C: localStorage (vulnerable to XSS, not recommended)
+localStorage.setItem('site_user_token', token);
+client.setAuth(token);
+
+// Option 2: Automatic token management (memory only)
+const response = await client.siteUsers.verifyOtpAndSetAuth(
+  'mysite',
+  { email: 'user@example.com', code: '123456' },
+  csrfToken
+);
+// Token automatically set in SDK, lost on page refresh
+```
+
+### 3. Logout
+
+```typescript
+await client.siteUsers.logout('mysite');
+// Also clear client-side token storage
+client.setAuth(null);
+```
+
+## Creating Waitlist Users
+
+Mark users as waitlist signups before your service launches. You can optionally include metadata during the initial signup:
+
+```typescript
+// Request OTP with waitlist flag and initial metadata
+const response = await client.siteUsers.requestOtp(
+  'mysite',
+  {
+    email: 'earlyuser@example.com',
+    waitlist: true,  // Mark as waitlist signup
+    metadata: {
+      // Capture context at signup time
+      signupSource: 'landing-page',
+      referralCode: 'FRIEND123',
+      interests: ['product-updates', 'beta-features'],
+      utm_campaign: 'launch-2024'
+    }
+  },
+  csrfToken
+);
+
+// After verification, user will have waitlist: true and metadata
+const { user } = await client.siteUsers.verifyOtp(
+  'mysite',
+  { email: 'earlyuser@example.com', code: '123456' },
+  csrfToken
+);
+
+console.log(user.waitlist); // true
+console.log(user.metadata); // { signupSource: 'landing-page', ... }
+```
+
+### Updating Existing Users' Metadata
+
+If a user already exists (returning user requesting OTP again), providing metadata will **update** their existing metadata:
+
+```typescript
+// First signup
+await client.siteUsers.requestOtp('mysite', {
+  email: 'user@example.com',
+  metadata: { signupSource: 'web' }
+}, csrfToken);
+
+// Later, same user requests OTP again with new metadata
+await client.siteUsers.requestOtp('mysite', {
+  email: 'user@example.com',
+  metadata: { lastLoginSource: 'mobile-app' }  // This replaces previous metadata
+}, csrfToken);
+```
+
+Query waitlist users (admin only):
+
+```typescript
+// Get all waitlist users for a site
+const users = await client.siteUsers.listUsers(
+  'mysite',
+  { limit: 100, offset: 0 }
+);
+
+const waitlistUsers = users.data.users.filter(u => u.waitlist);
+
+// Analyze waitlist metadata
+waitlistUsers.forEach(user => {
+  console.log(`${user.email}: ${user.metadata?.signupSource}`);
+});
+```
+
+## Managing User Metadata
+
+Metadata is an arbitrary JSON object for storing custom per-site fields. The client is responsible for merging - the API does **full replacement**.
+
+### Setting Metadata
+
+```typescript
+// Set metadata (full replacement)
+await client.siteUsers.updateMe(
+  'mysite',
+  {
+    metadata: {
+      preferences: {
+        theme: 'dark',
+        notifications: true,
+        language: 'en'
+      },
+      tags: ['premium', 'early-adopter'],
+      customField: 'value',
+      onboardingCompleted: true
+    }
+  },
+  csrfToken
+);
+```
+
+### Merging Metadata (Client-Side Pattern)
+
+```typescript
+// 1. Get current user data
+const { data } = await client.siteUsers.getMe('mysite');
+const currentMetadata = data.user.metadata || {};
+
+// 2. Deep merge with new data (example using lodash or custom logic)
+import { merge } from 'lodash';
+
+const updatedMetadata = merge({}, currentMetadata, {
+  preferences: {
+    theme: 'light'  // Update just this field, keep others
+  }
+});
+
+// 3. Send merged result
+await client.siteUsers.updateMe(
+  'mysite',
+  { metadata: updatedMetadata },
+  csrfToken
+);
+```
+
+### Shallow Merge Pattern
+
+```typescript
+// Simple shallow merge for top-level keys
+const { data } = await client.siteUsers.getMe('mysite');
+
+await client.siteUsers.updateMe(
+  'mysite',
+  {
+    metadata: {
+      ...data.user.metadata,
+      newField: 'value',
+      tags: [...(data.user.metadata?.tags || []), 'new-tag']
+    }
+  },
+  csrfToken
+);
+```
+
+### Clearing Metadata
+
+```typescript
+// Clear all metadata
+await client.siteUsers.updateMe(
+  'mysite',
+  { metadata: null },
+  csrfToken
+);
+```
+
+## Managing User Profiles
+
+User profiles are a **separate** key-value store for structured data like phone numbers, addresses, and preferences. Unlike metadata, each key is stored as a separate database record.
+
+### Setting Profile Values
+
+```typescript
+// Set a simple string value
+await client.siteUsers.setProfileValue(
+  'mysite',
+  'phone',
+  '+1-555-0123',
+  csrfToken
+);
+
+// Set a complex JSON value (addresses, preferences, etc.)
+await client.siteUsers.setProfileValue(
+  'mysite',
+  'address_shipping',
+  JSON.stringify({
+    line1: '123 Main St',
+    city: 'San Francisco',
+    state: 'CA',
+    postal_code: '94102',
+    country: 'US'
+  }),
+  csrfToken
+);
+
+await client.siteUsers.setProfileValue(
+  'mysite',
+  'address_billing',
+  JSON.stringify({
+    line1: '456 Oak Ave',
+    city: 'Portland',
+    state: 'OR',
+    postal_code: '97201',
+    country: 'US'
+  }),
+  csrfToken
+);
+```
+
+### Getting Profile Data
+
+```typescript
+// Get all profile key-values
+const { data } = await client.siteUsers.getProfile('mysite');
+
+// Access profile values
+console.log(data.profile.phone?.value); // '+1-555-0123'
+console.log(data.profile.address_shipping?.value); // { line1: '123 Main St', ... }
+console.log(data.profile.address_shipping?.updated_at); // '2024-01-15T12:00:00Z'
+
+// Or get user with profile in one request
+const response = await client.siteUsers.getMe('mysite');
+console.log(response.data.user); // Basic user fields
+console.log(response.data.profile); // All profile key-values
+```
+
+### Deleting Profile Values
+
+```typescript
+// Delete a specific profile key
+await client.siteUsers.deleteProfileValue(
+  'mysite',
+  'phone',
+  csrfToken
+);
+```
+
+### Common Profile Keys
+
+Suggested key naming conventions:
+
+- `phone` - Primary phone number
+- `whatsapp` - WhatsApp number
+- `address_shipping` - Shipping address (JSON)
+- `address_billing` - Billing address (JSON)
+- `preferences` - User preferences (JSON)
+- `notifications` - Notification settings (JSON)
+- `social_twitter` - Twitter handle
+- `social_linkedin` - LinkedIn URL
+
+## Cross-Domain Authentication
+
+Site users support cross-domain authentication using JWT tokens in the Authorization header.
+
+### Same-Domain Setup (Default)
+
+If your client app is on the **same domain** as the API:
+
+```typescript
+// The API automatically sets httpOnly cookies
+await client.siteUsers.verifyOtp('mysite', { email, code }, csrfToken);
+
+// Cookie is automatically sent with subsequent requests
+await client.siteUsers.getMe('mysite');
+```
+
+### Cross-Domain Setup (Token-Based)
+
+If your client app is on a **different domain** than the API:
+
+```typescript
+// 1. Verify OTP and get token
+const response = await client.siteUsers.verifyOtp(
+  'mysite',
+  { email, code },
+  csrfToken
+);
+
+const { token } = response.data;
+
+// 2. Store token on YOUR domain (httpOnly cookie via your API)
+await fetch('https://yourclient.com/api/set-auth', {
+  method: 'POST',
+  credentials: 'include',
+  body: JSON.stringify({ token })
+});
+
+// 3. Set token in SDK for Authorization header
+client.setAuth(token);
+
+// 4. All subsequent requests include Authorization: Bearer <token>
+await client.siteUsers.getMe('mysite');
+```
+
+## User Data Management
+
+### Updating User Profile
+
+```typescript
+// Update basic user fields
+await client.siteUsers.updateMe(
+  'mysite',
+  {
+    first_name: 'John',
+    last_name: 'Doe',
+    avatar_url: 'https://example.com/avatar.jpg',
+    metadata: {
+      // ... custom metadata
+    }
+  },
+  csrfToken
+);
+```
+
+### Getting Current User
+
+```typescript
+const { data } = await client.siteUsers.getMe('mysite');
+
+console.log(data.user);
+// {
+//   id: 'user_abc123',
+//   email: 'user@example.com',
+//   first_name: 'John',
+//   last_name: 'Doe',
+//   avatar_url: 'https://...',
+//   status: 'active',
+//   email_verified: true,
+//   waitlist: false,
+//   metadata: { ... },
+//   created_at: '2024-01-01T00:00:00Z',
+//   last_login_at: '2024-01-15T12:00:00Z'
+// }
+
+console.log(data.profile);
+// {
+//   phone: { value: '+1-555-0123', updated_at: '...' },
+//   address_shipping: { value: { line1: '...', ... }, updated_at: '...' }
+// }
+```
+
+## Orders and Subscriptions
+
+### Getting Order History
+
+```typescript
+// Get all orders for current user
+const { data } = await client.siteUsers.getOrders('mysite', {
+  limit: 50,
+  offset: 0
+});
+
+console.log(data.orders);
+// [
+//   {
+//     session_id: 'cs_abc123',
+//     order_id: 'ord_xyz789',
+//     customer_email: 'user@example.com',
+//     amount_total: 4999,
+//     currency: 'usd',
+//     status: 'complete',
+//     payment_status: 'paid',
+//     line_items: [...],
+//     created_at: '2024-01-15T12:00:00Z'
+//   }
+// ]
+```
+
+### Getting Single Order
+
+```typescript
+// Get order detail by ID or session ID
+const { data } = await client.siteUsers.getOrder('mysite', 'ord_xyz789');
+
+console.log(data.order);
+```
+
+### Managing Subscriptions
+
+```typescript
+// Get all subscriptions
+const { data } = await client.siteUsers.getSubscriptions('mysite', {
+  limit: 50,
+  offset: 0
+});
+
+console.log(data.subscriptions);
+// [
+//   {
+//     id: 'sub_abc123',
+//     provider: 'stripe',
+//     provider_subscription_id: 'sub_stripe123',
+//     plan_name: 'Pro Plan',
+//     plan_id: 'price_123',
+//     status: 'active',
+//     amount: 2999,
+//     currency: 'usd',
+//     billing_interval: 'month',
+//     current_period_start: '2024-01-01T00:00:00Z',
+//     current_period_end: '2024-02-01T00:00:00Z',
+//     cancel_at_period_end: false,
+//     created_at: '2024-01-01T00:00:00Z'
+//   }
+// ]
+```
+
+### Getting Single Subscription
+
+```typescript
+const { data } = await client.siteUsers.getSubscription('mysite', 'sub_abc123');
+
+console.log(data.subscription);
+```
+
+### Canceling Subscription
+
+```typescript
+// Cancel subscription at period end (default behavior)
+const response = await client.siteUsers.cancelSubscription(
+  'mysite',
+  'sub_abc123',
+  csrfToken
+);
+
+console.log(response.data);
+// { success: true, message: 'Subscription will be canceled at period end' }
+
+// Cancel immediately
+await client.siteUsers.cancelSubscription(
+  'mysite',
+  'sub_abc123',
+  csrfToken,
+  { mode: 'immediate' }
+);
+
+// Cancel at a scheduled timestamp (ISO)
+await client.siteUsers.cancelSubscription(
+  'mysite',
+  'sub_abc123',
+  csrfToken,
+  { mode: 'scheduled', cancel_at: '2026-06-15T14:00:00Z' }
+);
+
+// Cancel after a configured delay
+await client.siteUsers.cancelSubscription(
+  'mysite',
+  'sub_abc123',
+  csrfToken,
+  { mode: 'scheduled', delay_days: 3, delay_hours: 6 }
+);
+```
+
+### Getting Newsletter Subscriptions
+
+```typescript
+// Get linked newsletter subscriptions
+const { data } = await client.siteUsers.getNewsletterSubscriptions('mysite');
+
+console.log(data.newsletters);
+```
+
+## Admin Operations
+
+These endpoints require API key authentication (not site user JWT).
+
+### Listing All Users
+
+```typescript
+// Initialize client with API key
+const adminClient = new PerspectApiClient({
+  baseUrl: 'https://api.yoursite.com',
+  apiKey: 'your-api-key'
+});
+
+// List all users for a site
+const { data } = await adminClient.siteUsers.listUsers(
+  'mysite',
+  {
+    limit: 100,
+    offset: 0,
+    status: 'active'  // Optional: filter by status
+  }
+);
+
+console.log(data.users);
+```
+
+### Getting User Detail (Admin)
+
+```typescript
+// Get full user details including profile
+const { data } = await adminClient.siteUsers.getUser('mysite', 'user_abc123');
+
+console.log(data.user);
+console.log(data.profile);
+```
+
+### Updating User Status (Admin)
+
+```typescript
+// Suspend a user
+await adminClient.siteUsers.updateUserStatus(
+  'mysite',
+  'user_abc123',
+  'suspended',
+  csrfToken
+);
+
+// Reactivate a user
+await adminClient.siteUsers.updateUserStatus(
+  'mysite',
+  'user_abc123',
+  'active',
+  csrfToken
+);
+
+// Available statuses: 'active' | 'suspended' | 'pending_verification'
+```
+
+## Complete Example: User Registration Flow
+
+```typescript
+import { PerspectApiClient } from 'perspectapi-ts-sdk';
+
+const client = new PerspectApiClient({
+  baseUrl: 'https://api.yoursite.com'
+});
+
+// 1. Request OTP with waitlist flag and initial metadata
+async function startSignup(
+  email: string,
+  isWaitlist: boolean,
+  signupContext?: {
+    source?: string;
+    referralCode?: string;
+    utmParams?: Record<string, string>;
+  }
+) {
+  const csrfToken = await getCsrfToken(); // Get from your CSRF endpoint
+
+  const response = await client.siteUsers.requestOtp(
+    'mysite',
+    {
+      email,
+      waitlist: isWaitlist,
+      metadata: {
+        signupSource: signupContext?.source || 'direct',
+        referralCode: signupContext?.referralCode,
+        utmParams: signupContext?.utmParams,
+        signupTimestamp: new Date().toISOString()
+      }
+    },
+    csrfToken
+  );
+
+  return response.data.success;
+}
+
+// 2. Verify OTP and complete signup
+async function completeSignup(email: string, code: string) {
+  const csrfToken = await getCsrfToken();
+
+  const response = await client.siteUsers.verifyOtp(
+    'mysite',
+    { email, code },
+    csrfToken
+  );
+
+  const { token, user } = response.data;
+
+  // Store token securely (e.g., httpOnly cookie via your API)
+  await storeAuthToken(token);
+
+  // Set auth for SDK
+  client.setAuth(token);
+
+  return user;
+}
+
+// 3. Complete user profile
+async function completeProfile(profileData: {
+  first_name: string;
+  last_name: string;
+  phone: string;
+  metadata?: any;
+}) {
+  const csrfToken = await getCsrfToken();
+
+  // Update basic profile
+  await client.siteUsers.updateMe(
+    'mysite',
+    {
+      first_name: profileData.first_name,
+      last_name: profileData.last_name,
+      metadata: {
+        onboardingCompleted: true,
+        signupSource: 'website',
+        ...profileData.metadata
+      }
+    },
+    csrfToken
+  );
+
+  // Set phone in profile key-values
+  await client.siteUsers.setProfileValue(
+    'mysite',
+    'phone',
+    profileData.phone,
+    csrfToken
+  );
+
+  // Get updated user data
+  const { data } = await client.siteUsers.getMe('mysite');
+  return data;
+}
+
+// Usage
+async function registerUser() {
+  // Step 1: Request OTP with signup context
+  await startSignup('user@example.com', false, {
+    source: 'landing-page',
+    referralCode: 'FRIEND123',
+    utmParams: {
+      utm_source: 'google',
+      utm_campaign: 'spring-2024'
+    }
+  });
+  console.log('OTP sent to email');
+
+  // Step 2: User enters code from email
+  const user = await completeSignup('user@example.com', '123456');
+  console.log('Signup successful:', user);
+  console.log('Signup metadata:', user.metadata);
+
+  // Step 3: Complete profile
+  const userData = await completeProfile({
+    first_name: 'John',
+    last_name: 'Doe',
+    phone: '+1-555-0123',
+    metadata: {
+      referralSource: 'friend',
+      interests: ['tech', 'design']
+    }
+  });
+
+  console.log('Profile complete:', userData);
+}
+```
+
+## Best Practices
+
+### Security
+
+1. **Always use CSRF tokens** for browser-based requests
+2. **Store tokens securely**:
+   - Production: httpOnly cookies on your domain
+   - Development: Memory (lost on refresh)
+   - Avoid: localStorage (vulnerable to XSS)
+3. **Validate email addresses** before requesting OTP
+4. **Rate limit OTP requests** on your frontend
+
+### Data Organization
+
+1. **Use metadata for**:
+   - Unstructured custom fields
+   - Site-specific configuration
+   - Temporary flags or states
+   - Analytics data
+
+2. **Use profile key-values for**:
+   - Structured data (addresses, phone numbers)
+   - Data that needs individual timestamps
+   - Data that may be queried separately
+   - User preferences with granular updates
+
+### Performance
+
+1. **Batch profile updates** when possible
+2. **Cache user data** client-side (with TTL)
+3. **Use pagination** for order/subscription lists
+4. **Merge metadata client-side** to avoid fetch-update races
+
+## TypeScript Types
+
+```typescript
+interface SiteUser {
+  id: string;
+  email: string;
+  first_name?: string;
+  last_name?: string;
+  avatar_url?: string;
+  status: 'active' | 'suspended' | 'pending_verification';
+  email_verified: boolean;
+  waitlist: boolean;
+  metadata?: Record<string, any>;
+  created_at: string;
+  last_login_at?: string;
+}
+
+interface SiteUserProfile {
+  [key: string]: {
+    value: any;
+    updated_at: string;
+  };
+}
+
+interface RequestOtpRequest {
+  email: string;
+  waitlist?: boolean;
+  metadata?: Record<string, any>;  // Optional metadata to set on user creation/update
+}
+
+interface VerifyOtpRequest {
+  email: string;
+  code: string;
+}
+
+interface VerifyOtpResponse {
+  success: boolean;
+  token: string;
+  user: {
+    id: string;
+    email: string;
+    first_name?: string;
+    last_name?: string;
+    avatar_url?: string;
+  };
+}
+
+interface UpdateSiteUserRequest {
+  first_name?: string;
+  last_name?: string;
+  avatar_url?: string;
+  metadata?: Record<string, any>;
+}
+```