perspectapi-ts-sdk 2.8.1 → 2.8.3

package/README.md

@@ -13,6 +13,7 @@ A comprehensive TypeScript SDK for PerspectAPI, designed to work seamlessly with
 - 📊 **Comprehensive Coverage** - All PerspectAPI endpoints supported
 - 🧩 **High-Level Loaders** - Drop-in helpers for products, content, and checkout flows with fallbacks
 - 📧 **Newsletter Management** - Complete newsletter subscription system with double opt-in, preferences, and lists
+- 👥 **Site Users** - OTP-based customer accounts with metadata, profiles, orders, and subscriptions
 
 ## Installation
 
@@ -734,6 +735,100 @@ console.log('Imported:', importResult.data.imported);
 console.log('Failed:', importResult.data.failed);
 ```
 
+> 📚 **For complete newsletter documentation**, see [docs/newsletter.md](docs/newsletter.md)
+
+### Site Users (Customer Accounts)
+
+Site users are per-site customer accounts with OTP-based authentication, separate from admin users.
+
+```typescript
+const siteName = 'your-site-name';
+
+// Request OTP for login/signup (with optional metadata)
+await client.siteUsers.requestOtp(
+  siteName,
+  {
+    email: 'user@example.com',
+    waitlist: true,  // Optional: mark as waitlist signup
+    metadata: {      // Optional: set metadata at signup time
+      signupSource: 'landing-page',
+      referralCode: 'FRIEND123',
+      interests: ['product-updates']
+    }
+  },
+  csrfToken
+);
+
+// Verify OTP and get JWT token
+const response = await client.siteUsers.verifyOtp(
+  siteName,
+  { email: 'user@example.com', code: '123456' },
+  csrfToken
+);
+
+const { token, user } = response.data;
+client.setAuth(token);  // Set auth for subsequent requests
+
+// Get current user profile
+const { data } = await client.siteUsers.getMe(siteName);
+console.log(data.user);      // Basic user fields + metadata
+console.log(data.profile);   // Key-value profile data
+
+// Update user profile and metadata
+await client.siteUsers.updateMe(
+  siteName,
+  {
+    first_name: 'John',
+    last_name: 'Doe',
+    metadata: {
+      preferences: { theme: 'dark' },
+      tags: ['premium'],
+      customField: 'value'
+    }
+  },
+  csrfToken
+);
+
+// Set profile key-values (phone, addresses, etc.)
+await client.siteUsers.setProfileValue(
+  siteName,
+  'phone',
+  '+1-555-0123',
+  csrfToken
+);
+
+await client.siteUsers.setProfileValue(
+  siteName,
+  'address_shipping',
+  JSON.stringify({
+    line1: '123 Main St',
+    city: 'San Francisco',
+    state: 'CA',
+    postal_code: '94102',
+    country: 'US'
+  }),
+  csrfToken
+);
+
+// Get order history
+const orders = await client.siteUsers.getOrders(siteName, {
+  limit: 50,
+  offset: 0
+});
+
+// Get subscriptions
+const subscriptions = await client.siteUsers.getSubscriptions(siteName);
+
+// Cancel subscription
+await client.siteUsers.cancelSubscription(siteName, 'sub_123', csrfToken);
+
+// Logout
+await client.siteUsers.logout(siteName);
+client.setAuth(null);
+```
+
+> 📚 **For complete site users documentation** including waitlist management, metadata patterns, cross-domain authentication, and complete examples, see [docs/site-users.md](docs/site-users.md)
+
 ## Configuration Options
 
 ```typescript

package/dist/index.d.mts

@@ -582,6 +582,7 @@ interface SiteUser {
     status: 'active' | 'suspended' | 'pending_verification';
     email_verified: boolean;
     waitlist: boolean;
+    metadata?: Record<string, any>;
     created_at: string;
     last_login_at?: string;
 }
@@ -626,6 +627,7 @@ interface SiteUserOrder {
 interface RequestOtpRequest {
     email: string;
     waitlist?: boolean;
+    metadata?: Record<string, any>;
 }
 interface VerifyOtpRequest {
     email: string;
@@ -646,6 +648,7 @@ interface UpdateSiteUserRequest {
     first_name?: string;
     last_name?: string;
     avatar_url?: string;
+    metadata?: Record<string, any>;
 }
 interface SetProfileValueRequest {
     value: string;

package/dist/index.d.ts

@@ -582,6 +582,7 @@ interface SiteUser {
     status: 'active' | 'suspended' | 'pending_verification';
     email_verified: boolean;
     waitlist: boolean;
+    metadata?: Record<string, any>;
     created_at: string;
     last_login_at?: string;
 }
@@ -626,6 +627,7 @@ interface SiteUserOrder {
 interface RequestOtpRequest {
     email: string;
     waitlist?: boolean;
+    metadata?: Record<string, any>;
 }
 interface VerifyOtpRequest {
     email: string;
@@ -646,6 +648,7 @@ interface UpdateSiteUserRequest {
     first_name?: string;
     last_name?: string;
     avatar_url?: string;
+    metadata?: Record<string, any>;
 }
 interface SetProfileValueRequest {
     value: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "2.8.1",
+  "version": "2.8.3",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/types/index.ts

@@ -589,6 +589,7 @@ export interface SiteUser {
   status: 'active' | 'suspended' | 'pending_verification';
   email_verified: boolean;
   waitlist: boolean;
+  metadata?: Record<string, any>;
   created_at: string;
   last_login_at?: string;
 }
@@ -637,6 +638,7 @@ export interface SiteUserOrder {
 export interface RequestOtpRequest {
   email: string;
   waitlist?: boolean;  // Mark user as waitlist signup
+  metadata?: Record<string, any>;  // Optional metadata to set on user creation/update
 }
 
 export interface VerifyOtpRequest {
@@ -660,6 +662,7 @@ export interface UpdateSiteUserRequest {
   first_name?: string;
   last_name?: string;
   avatar_url?: string;
+  metadata?: Record<string, any>;
 }
 
 export interface SetProfileValueRequest {