perspectapi-ts-sdk 1.2.0 → 1.3.0

package/README.md

@@ -12,6 +12,7 @@ A comprehensive TypeScript SDK for PerspectAPI, designed to work seamlessly with
 - 🔑 **Multiple Auth Methods** - Support for JWT tokens and API keys
 - 📊 **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
 
 ## Installation
 
@@ -376,6 +377,132 @@ const submissions = await client.contact.getContactSubmissions(siteName, {
 await client.contact.updateContactStatus(siteName, submission.data.id, 'read');
 ```
 
+### Newsletter Subscriptions
+
+```typescript
+const siteName = 'your-site-name';
+
+// Subscribe to newsletter (with double opt-in)
+const subscription = await client.newsletter.subscribe(siteName, {
+  email: 'subscriber@example.com',
+  name: 'Jane Doe',
+  list_ids: ['list_default'],  // Optional: subscribe to specific lists
+  frequency: 'weekly',          // instant, daily, weekly, monthly
+  topics: ['news', 'updates'],  // Optional: topic preferences
+  double_opt_in: true,          // Default: true for GDPR compliance
+  turnstile_token: 'token'      // Optional: Turnstile verification
+});
+
+// Confirm subscription via email token
+const confirmed = await client.newsletter.confirmSubscription(
+  siteName,
+  'confirmation-token-from-email'
+);
+
+// Unsubscribe
+const unsubscribed = await client.newsletter.unsubscribe(siteName, {
+  email: 'subscriber@example.com',
+  reason: 'Too many emails'  // Optional feedback
+});
+
+// One-click unsubscribe (from email link)
+await client.newsletter.unsubscribeByToken(siteName, 'unsubscribe-token');
+
+// Update preferences
+await client.newsletter.updatePreferences(siteName, 'subscriber@example.com', {
+  frequency: 'monthly',
+  topics: ['product-updates'],
+  email_format: 'html',  // html, text, or both
+  timezone: 'America/New_York',
+  track_opens: false,
+  track_clicks: false
+});
+
+// Check subscription status
+const status = await client.newsletter.getStatus(siteName, 'subscriber@example.com');
+console.log('Subscribed:', status.data.subscribed);
+console.log('Status:', status.data.status); // pending, confirmed, unsubscribed
+
+// Get available newsletter lists
+const lists = await client.newsletter.getLists(siteName);
+console.log('Available lists:', lists.data.lists);
+```
+
+#### Newsletter Admin Functions
+
+```typescript
+// Get all subscriptions (admin only)
+const subscriptions = await client.newsletter.getSubscriptions(siteName, {
+  page: 1,
+  limit: 100,
+  status: 'confirmed',
+  list_id: 'list_weekly',
+  search: 'john',
+  startDate: '2024-01-01',
+  endDate: '2024-12-31'
+});
+
+// Update subscription status
+await client.newsletter.updateSubscriptionStatus(
+  siteName,
+  'sub_123',
+  'unsubscribed',
+  'Admin action: User requested via support'
+);
+
+// Bulk operations
+await client.newsletter.bulkUpdateSubscriptions(siteName, {
+  ids: ['sub_123', 'sub_456'],
+  action: 'add_to_list',
+  list_id: 'list_special_offers'
+});
+
+// List management
+const newList = await client.newsletter.createList(siteName, {
+  list_name: 'VIP Customers',
+  slug: 'vip-customers',
+  description: 'Exclusive updates for VIP customers',
+  is_public: false,
+  is_default: false,
+  double_opt_in: true,
+  welcome_email_enabled: true
+});
+
+await client.newsletter.updateList(siteName, 'list_123', {
+  description: 'Updated description',
+  is_public: true
+});
+
+// Get statistics
+const stats = await client.newsletter.getStatistics(siteName, {
+  startDate: '2024-01-01',
+  endDate: '2024-12-31',
+  list_id: 'list_weekly'
+});
+console.log('Total subscribers:', stats.data.totalSubscribers);
+console.log('Open rate:', stats.data.engagementMetrics.averageOpenRate);
+
+// Export subscriptions
+const exportData = await client.newsletter.exportSubscriptions(siteName, {
+  format: 'csv',  // csv, json, or xlsx
+  status: 'confirmed',
+  list_id: 'list_weekly'
+});
+console.log('Download URL:', exportData.data.downloadUrl);
+
+// Import subscriptions
+const importResult = await client.newsletter.importSubscriptions(siteName, {
+  subscriptions: [
+    { email: 'user1@example.com', name: 'User One', lists: ['list_weekly'] },
+    { email: 'user2@example.com', name: 'User Two', lists: ['list_daily'] }
+  ],
+  skip_confirmation: false,  // Skip double opt-in for imported users
+  update_existing: true       // Update if email already exists
+});
+console.log('Imported:', importResult.data.imported);
+console.log('Failed:', importResult.data.failed);
+```
+
 ## Configuration Options
 
 ```typescript

package/dist/index.d.mts

@@ -397,6 +397,7 @@ interface RequestOptions {
     body?: any;
     params?: Record<string, string | number | boolean>;
     timeout?: number;
+    csrfToken?: string;
 }
 
 /**
@@ -433,19 +434,19 @@ declare class HttpClient {
     /**
      * POST request
      */
-    post<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>>;
+    post<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>>;
     /**
      * PUT request
      */
-    put<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>>;
+    put<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>>;
     /**
      * DELETE request
      */
-    delete<T = any>(endpoint: string): Promise<ApiResponse<T>>;
+    delete<T = any>(endpoint: string, options?: Partial<RequestOptions>): Promise<ApiResponse<T>>;
     /**
      * PATCH request
      */
-    patch<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>>;
+    patch<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>>;
     /**
      * Build full URL with query parameters
      */
@@ -501,19 +502,19 @@ declare abstract class BaseClient {
     /**
      * Handle create operations
      */
-    protected create<T, R = T>(endpoint: string, data: T): Promise<ApiResponse<R>>;
+    protected create<T, R = T>(endpoint: string, data: T, csrfToken?: string): Promise<ApiResponse<R>>;
     /**
      * Handle update operations
      */
-    protected update<T, R = T>(endpoint: string, data: T): Promise<ApiResponse<R>>;
+    protected update<T, R = T>(endpoint: string, data: T, csrfToken?: string): Promise<ApiResponse<R>>;
     /**
      * Handle partial update operations
      */
-    protected patch<T, R = T>(endpoint: string, data: T): Promise<ApiResponse<R>>;
+    protected patch<T, R = T>(endpoint: string, data: T, csrfToken?: string): Promise<ApiResponse<R>>;
     /**
      * Handle delete operations
      */
-    protected delete<T = any>(endpoint: string): Promise<ApiResponse<T>>;
+    protected delete<T = any>(endpoint: string, csrfToken?: string): Promise<ApiResponse<T>>;
 }
 
 /**
@@ -1457,8 +1458,11 @@ declare class ContactClient extends BaseClient {
     private contactEndpoint;
     /**
      * Submit contact form
+     * @param siteName - The site to submit contact form to
+     * @param data - Contact form data
+     * @param csrfToken - CSRF token (required for browser-based submissions)
      */
-    submitContact(siteName: string, data: CreateContactRequest): Promise<ApiResponse<{
+    submitContact(siteName: string, data: CreateContactRequest, csrfToken?: string): Promise<ApiResponse<{
         id: string;
         message: string;
         status: string;
@@ -1612,16 +1616,22 @@ declare class NewsletterClient extends BaseClient {
     private newsletterEndpoint;
     /**
      * Subscribe to newsletter
+     * @param siteName - The site to subscribe to
+     * @param data - Subscription data
+     * @param csrfToken - CSRF token (required for browser-based submissions)
      */
-    subscribe(siteName: string, data: CreateNewsletterSubscriptionRequest): Promise<ApiResponse<NewsletterSubscribeResponse>>;
+    subscribe(siteName: string, data: CreateNewsletterSubscriptionRequest, csrfToken?: string): Promise<ApiResponse<NewsletterSubscribeResponse>>;
     /**
      * Confirm newsletter subscription via token
      */
     confirmSubscription(siteName: string, token: string): Promise<ApiResponse<NewsletterConfirmResponse>>;
     /**
      * Unsubscribe from newsletter
+     * @param siteName - The site to unsubscribe from
+     * @param data - Unsubscribe data
+     * @param csrfToken - CSRF token (required for browser-based submissions)
      */
-    unsubscribe(siteName: string, data: NewsletterUnsubscribeRequest): Promise<ApiResponse<{
+    unsubscribe(siteName: string, data: NewsletterUnsubscribeRequest, csrfToken?: string): Promise<ApiResponse<{
         message: string;
     }>>;
     /**
@@ -1630,8 +1640,12 @@ declare class NewsletterClient extends BaseClient {
     unsubscribeByToken(siteName: string, token: string): Promise<ApiResponse<string>>;
     /**
      * Update subscription preferences
+     * @param siteName - The site name
+     * @param email - Subscriber email
+     * @param preferences - New preferences
+     * @param csrfToken - CSRF token (required for browser-based submissions)
      */
-    updatePreferences(siteName: string, email: string, preferences: NewsletterPreferences): Promise<ApiResponse<{
+    updatePreferences(siteName: string, email: string, preferences: NewsletterPreferences, csrfToken?: string): Promise<ApiResponse<{
         message: string;
         preferences: NewsletterPreferences;
     }>>;

package/dist/index.d.ts

@@ -397,6 +397,7 @@ interface RequestOptions {
     body?: any;
     params?: Record<string, string | number | boolean>;
     timeout?: number;
+    csrfToken?: string;
 }
 
 /**
@@ -433,19 +434,19 @@ declare class HttpClient {
     /**
      * POST request
      */
-    post<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>>;
+    post<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>>;
     /**
      * PUT request
      */
-    put<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>>;
+    put<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>>;
     /**
      * DELETE request
      */
-    delete<T = any>(endpoint: string): Promise<ApiResponse<T>>;
+    delete<T = any>(endpoint: string, options?: Partial<RequestOptions>): Promise<ApiResponse<T>>;
     /**
      * PATCH request
      */
-    patch<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>>;
+    patch<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>>;
     /**
      * Build full URL with query parameters
      */
@@ -501,19 +502,19 @@ declare abstract class BaseClient {
     /**
      * Handle create operations
      */
-    protected create<T, R = T>(endpoint: string, data: T): Promise<ApiResponse<R>>;
+    protected create<T, R = T>(endpoint: string, data: T, csrfToken?: string): Promise<ApiResponse<R>>;
     /**
      * Handle update operations
      */
-    protected update<T, R = T>(endpoint: string, data: T): Promise<ApiResponse<R>>;
+    protected update<T, R = T>(endpoint: string, data: T, csrfToken?: string): Promise<ApiResponse<R>>;
     /**
      * Handle partial update operations
      */
-    protected patch<T, R = T>(endpoint: string, data: T): Promise<ApiResponse<R>>;
+    protected patch<T, R = T>(endpoint: string, data: T, csrfToken?: string): Promise<ApiResponse<R>>;
     /**
      * Handle delete operations
      */
-    protected delete<T = any>(endpoint: string): Promise<ApiResponse<T>>;
+    protected delete<T = any>(endpoint: string, csrfToken?: string): Promise<ApiResponse<T>>;
 }
 
 /**
@@ -1457,8 +1458,11 @@ declare class ContactClient extends BaseClient {
     private contactEndpoint;
     /**
      * Submit contact form
+     * @param siteName - The site to submit contact form to
+     * @param data - Contact form data
+     * @param csrfToken - CSRF token (required for browser-based submissions)
      */
-    submitContact(siteName: string, data: CreateContactRequest): Promise<ApiResponse<{
+    submitContact(siteName: string, data: CreateContactRequest, csrfToken?: string): Promise<ApiResponse<{
         id: string;
         message: string;
         status: string;
@@ -1612,16 +1616,22 @@ declare class NewsletterClient extends BaseClient {
     private newsletterEndpoint;
     /**
      * Subscribe to newsletter
+     * @param siteName - The site to subscribe to
+     * @param data - Subscription data
+     * @param csrfToken - CSRF token (required for browser-based submissions)
      */
-    subscribe(siteName: string, data: CreateNewsletterSubscriptionRequest): Promise<ApiResponse<NewsletterSubscribeResponse>>;
+    subscribe(siteName: string, data: CreateNewsletterSubscriptionRequest, csrfToken?: string): Promise<ApiResponse<NewsletterSubscribeResponse>>;
     /**
      * Confirm newsletter subscription via token
      */
     confirmSubscription(siteName: string, token: string): Promise<ApiResponse<NewsletterConfirmResponse>>;
     /**
      * Unsubscribe from newsletter
+     * @param siteName - The site to unsubscribe from
+     * @param data - Unsubscribe data
+     * @param csrfToken - CSRF token (required for browser-based submissions)
      */
-    unsubscribe(siteName: string, data: NewsletterUnsubscribeRequest): Promise<ApiResponse<{
+    unsubscribe(siteName: string, data: NewsletterUnsubscribeRequest, csrfToken?: string): Promise<ApiResponse<{
         message: string;
     }>>;
     /**
@@ -1630,8 +1640,12 @@ declare class NewsletterClient extends BaseClient {
     unsubscribeByToken(siteName: string, token: string): Promise<ApiResponse<string>>;
     /**
      * Update subscription preferences
+     * @param siteName - The site name
+     * @param email - Subscriber email
+     * @param preferences - New preferences
+     * @param csrfToken - CSRF token (required for browser-based submissions)
      */
-    updatePreferences(siteName: string, email: string, preferences: NewsletterPreferences): Promise<ApiResponse<{
+    updatePreferences(siteName: string, email: string, preferences: NewsletterPreferences, csrfToken?: string): Promise<ApiResponse<{
         message: string;
         preferences: NewsletterPreferences;
     }>>;

package/dist/index.js

@@ -130,26 +130,26 @@ var HttpClient = class {
   /**
    * POST request
    */
-  async post(endpoint, body) {
-    return this.request(endpoint, { method: "POST", body });
+  async post(endpoint, body, options) {
+    return this.request(endpoint, { method: "POST", body, ...options });
   }
   /**
    * PUT request
    */
-  async put(endpoint, body) {
-    return this.request(endpoint, { method: "PUT", body });
+  async put(endpoint, body, options) {
+    return this.request(endpoint, { method: "PUT", body, ...options });
   }
   /**
    * DELETE request
    */
-  async delete(endpoint) {
-    return this.request(endpoint, { method: "DELETE" });
+  async delete(endpoint, options) {
+    return this.request(endpoint, { method: "DELETE", ...options });
   }
   /**
    * PATCH request
    */
-  async patch(endpoint, body) {
-    return this.request(endpoint, { method: "PATCH", body });
+  async patch(endpoint, body, options) {
+    return this.request(endpoint, { method: "PATCH", body, ...options });
   }
   /**
    * Build full URL with query parameters
@@ -175,6 +175,9 @@ var HttpClient = class {
       ...this.defaultHeaders,
       ...options.headers
     };
+    if (options.csrfToken) {
+      headers["X-CSRF-Token"] = options.csrfToken;
+    }
     const requestOptions = {
       method: options.method || "GET",
       headers
@@ -298,26 +301,26 @@ var BaseClient = class {
   /**
    * Handle create operations
    */
-  async create(endpoint, data) {
-    return this.http.post(this.buildPath(endpoint), data);
+  async create(endpoint, data, csrfToken) {
+    return this.http.post(this.buildPath(endpoint), data, { csrfToken });
   }
   /**
    * Handle update operations
    */
-  async update(endpoint, data) {
-    return this.http.put(this.buildPath(endpoint), data);
+  async update(endpoint, data, csrfToken) {
+    return this.http.put(this.buildPath(endpoint), data, { csrfToken });
   }
   /**
    * Handle partial update operations
    */
-  async patch(endpoint, data) {
-    return this.http.patch(this.buildPath(endpoint), data);
+  async patch(endpoint, data, csrfToken) {
+    return this.http.patch(this.buildPath(endpoint), data, { csrfToken });
   }
   /**
    * Handle delete operations
    */
-  async delete(endpoint) {
-    return this.http.delete(this.buildPath(endpoint));
+  async delete(endpoint, csrfToken) {
+    return this.http.delete(this.buildPath(endpoint), { csrfToken });
   }
 };
 
@@ -1184,9 +1187,15 @@ var ContactClient = class extends BaseClient {
   }
   /**
    * Submit contact form
+   * @param siteName - The site to submit contact form to
+   * @param data - Contact form data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async submitContact(siteName, data) {
-    return this.create(this.contactEndpoint(siteName, "/contact/submit"), data);
+  async submitContact(siteName, data, csrfToken) {
+    if (typeof window !== "undefined" && !csrfToken && !data.turnstileToken) {
+      console.warn("CSRF token recommended for browser-based contact form submissions");
+    }
+    return this.create(this.contactEndpoint(siteName, "/contact/submit"), data, csrfToken);
   }
   /**
    * Get contact submission status
@@ -1281,11 +1290,18 @@ var NewsletterClient = class extends BaseClient {
   }
   /**
    * Subscribe to newsletter
+   * @param siteName - The site to subscribe to
+   * @param data - Subscription data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async subscribe(siteName, data) {
+  async subscribe(siteName, data, csrfToken) {
+    if (typeof window !== "undefined" && !csrfToken && !data.turnstile_token) {
+      console.warn("CSRF token recommended for browser-based newsletter subscriptions");
+    }
     return this.create(
       this.newsletterEndpoint(siteName, "/newsletter/subscribe"),
-      data
+      data,
+      csrfToken
     );
   }
   /**
@@ -1298,11 +1314,15 @@ var NewsletterClient = class extends BaseClient {
   }
   /**
    * Unsubscribe from newsletter
+   * @param siteName - The site to unsubscribe from
+   * @param data - Unsubscribe data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async unsubscribe(siteName, data) {
+  async unsubscribe(siteName, data, csrfToken) {
     return this.create(
       this.newsletterEndpoint(siteName, "/newsletter/unsubscribe"),
-      data
+      data,
+      csrfToken
     );
   }
   /**
@@ -1315,11 +1335,16 @@ var NewsletterClient = class extends BaseClient {
   }
   /**
    * Update subscription preferences
+   * @param siteName - The site name
+   * @param email - Subscriber email
+   * @param preferences - New preferences
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async updatePreferences(siteName, email, preferences) {
+  async updatePreferences(siteName, email, preferences, csrfToken) {
     return this.patch(
       this.newsletterEndpoint(siteName, "/newsletter/preferences"),
-      { email, ...preferences }
+      { email, ...preferences },
+      csrfToken
     );
   }
   /**

package/dist/index.mjs

@@ -79,26 +79,26 @@ var HttpClient = class {
   /**
    * POST request
    */
-  async post(endpoint, body) {
-    return this.request(endpoint, { method: "POST", body });
+  async post(endpoint, body, options) {
+    return this.request(endpoint, { method: "POST", body, ...options });
   }
   /**
    * PUT request
    */
-  async put(endpoint, body) {
-    return this.request(endpoint, { method: "PUT", body });
+  async put(endpoint, body, options) {
+    return this.request(endpoint, { method: "PUT", body, ...options });
   }
   /**
    * DELETE request
    */
-  async delete(endpoint) {
-    return this.request(endpoint, { method: "DELETE" });
+  async delete(endpoint, options) {
+    return this.request(endpoint, { method: "DELETE", ...options });
   }
   /**
    * PATCH request
    */
-  async patch(endpoint, body) {
-    return this.request(endpoint, { method: "PATCH", body });
+  async patch(endpoint, body, options) {
+    return this.request(endpoint, { method: "PATCH", body, ...options });
   }
   /**
    * Build full URL with query parameters
@@ -124,6 +124,9 @@ var HttpClient = class {
       ...this.defaultHeaders,
       ...options.headers
     };
+    if (options.csrfToken) {
+      headers["X-CSRF-Token"] = options.csrfToken;
+    }
     const requestOptions = {
       method: options.method || "GET",
       headers
@@ -247,26 +250,26 @@ var BaseClient = class {
   /**
    * Handle create operations
    */
-  async create(endpoint, data) {
-    return this.http.post(this.buildPath(endpoint), data);
+  async create(endpoint, data, csrfToken) {
+    return this.http.post(this.buildPath(endpoint), data, { csrfToken });
   }
   /**
    * Handle update operations
    */
-  async update(endpoint, data) {
-    return this.http.put(this.buildPath(endpoint), data);
+  async update(endpoint, data, csrfToken) {
+    return this.http.put(this.buildPath(endpoint), data, { csrfToken });
   }
   /**
    * Handle partial update operations
    */
-  async patch(endpoint, data) {
-    return this.http.patch(this.buildPath(endpoint), data);
+  async patch(endpoint, data, csrfToken) {
+    return this.http.patch(this.buildPath(endpoint), data, { csrfToken });
   }
   /**
    * Handle delete operations
    */
-  async delete(endpoint) {
-    return this.http.delete(this.buildPath(endpoint));
+  async delete(endpoint, csrfToken) {
+    return this.http.delete(this.buildPath(endpoint), { csrfToken });
   }
 };
 
@@ -1133,9 +1136,15 @@ var ContactClient = class extends BaseClient {
   }
   /**
    * Submit contact form
+   * @param siteName - The site to submit contact form to
+   * @param data - Contact form data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async submitContact(siteName, data) {
-    return this.create(this.contactEndpoint(siteName, "/contact/submit"), data);
+  async submitContact(siteName, data, csrfToken) {
+    if (typeof window !== "undefined" && !csrfToken && !data.turnstileToken) {
+      console.warn("CSRF token recommended for browser-based contact form submissions");
+    }
+    return this.create(this.contactEndpoint(siteName, "/contact/submit"), data, csrfToken);
   }
   /**
    * Get contact submission status
@@ -1230,11 +1239,18 @@ var NewsletterClient = class extends BaseClient {
   }
   /**
    * Subscribe to newsletter
+   * @param siteName - The site to subscribe to
+   * @param data - Subscription data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async subscribe(siteName, data) {
+  async subscribe(siteName, data, csrfToken) {
+    if (typeof window !== "undefined" && !csrfToken && !data.turnstile_token) {
+      console.warn("CSRF token recommended for browser-based newsletter subscriptions");
+    }
     return this.create(
       this.newsletterEndpoint(siteName, "/newsletter/subscribe"),
-      data
+      data,
+      csrfToken
     );
   }
   /**
@@ -1247,11 +1263,15 @@ var NewsletterClient = class extends BaseClient {
   }
   /**
    * Unsubscribe from newsletter
+   * @param siteName - The site to unsubscribe from
+   * @param data - Unsubscribe data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async unsubscribe(siteName, data) {
+  async unsubscribe(siteName, data, csrfToken) {
     return this.create(
       this.newsletterEndpoint(siteName, "/newsletter/unsubscribe"),
-      data
+      data,
+      csrfToken
     );
   }
   /**
@@ -1264,11 +1284,16 @@ var NewsletterClient = class extends BaseClient {
   }
   /**
    * Update subscription preferences
+   * @param siteName - The site name
+   * @param email - Subscriber email
+   * @param preferences - New preferences
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async updatePreferences(siteName, email, preferences) {
+  async updatePreferences(siteName, email, preferences, csrfToken) {
     return this.patch(
       this.newsletterEndpoint(siteName, "/newsletter/preferences"),
-      { email, ...preferences }
+      { email, ...preferences },
+      csrfToken
     );
   }
   /**

package/package.json

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

package/src/client/base-client.ts

@@ -66,9 +66,10 @@ export abstract class BaseClient {
    */
   protected async create<T, R = T>(
     endpoint: string,
-    data: T
+    data: T,
+    csrfToken?: string
   ): Promise<ApiResponse<R>> {
-    return this.http.post<R>(this.buildPath(endpoint), data);
+    return this.http.post<R>(this.buildPath(endpoint), data, { csrfToken });
   }
 
   /**
@@ -76,9 +77,10 @@ export abstract class BaseClient {
    */
   protected async update<T, R = T>(
     endpoint: string,
-    data: T
+    data: T,
+    csrfToken?: string
   ): Promise<ApiResponse<R>> {
-    return this.http.put<R>(this.buildPath(endpoint), data);
+    return this.http.put<R>(this.buildPath(endpoint), data, { csrfToken });
   }
 
   /**
@@ -86,15 +88,16 @@ export abstract class BaseClient {
    */
   protected async patch<T, R = T>(
     endpoint: string,
-    data: T
+    data: T,
+    csrfToken?: string
   ): Promise<ApiResponse<R>> {
-    return this.http.patch<R>(this.buildPath(endpoint), data);
+    return this.http.patch<R>(this.buildPath(endpoint), data, { csrfToken });
   }
 
   /**
    * Handle delete operations
    */
-  protected async delete<T = any>(endpoint: string): Promise<ApiResponse<T>> {
-    return this.http.delete<T>(this.buildPath(endpoint));
+  protected async delete<T = any>(endpoint: string, csrfToken?: string): Promise<ApiResponse<T>> {
+    return this.http.delete<T>(this.buildPath(endpoint), { csrfToken });
   }
 }

package/src/client/contact-client.ts

@@ -24,17 +24,29 @@ export class ContactClient extends BaseClient {
 
   /**
    * Submit contact form
+   * @param siteName - The site to submit contact form to
+   * @param data - Contact form data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
-  async submitContact(siteName: string, data: CreateContactRequest): Promise<ApiResponse<{
+  async submitContact(
+    siteName: string, 
+    data: CreateContactRequest,
+    csrfToken?: string
+  ): Promise<ApiResponse<{
     id: string;
     message: string;
     status: string;
   }>> {
+    // CSRF token is required for browser submissions
+    if (typeof window !== 'undefined' && !csrfToken && !data.turnstileToken) {
+      console.warn('CSRF token recommended for browser-based contact form submissions');
+    }
+    
     return this.create<CreateContactRequest, {
       id: string;
       message: string;
       status: string;
-    }>(this.contactEndpoint(siteName, '/contact/submit'), data);
+    }>(this.contactEndpoint(siteName, '/contact/submit'), data, csrfToken);
   }
 
   /**

package/src/client/newsletter-client.ts

@@ -30,14 +30,24 @@ export class NewsletterClient extends BaseClient {
 
   /**
    * Subscribe to newsletter
+   * @param siteName - The site to subscribe to
+   * @param data - Subscription data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
   async subscribe(
     siteName: string, 
-    data: CreateNewsletterSubscriptionRequest
+    data: CreateNewsletterSubscriptionRequest,
+    csrfToken?: string
   ): Promise<ApiResponse<NewsletterSubscribeResponse>> {
+    // CSRF token is required for browser submissions
+    if (typeof window !== 'undefined' && !csrfToken && !data.turnstile_token) {
+      console.warn('CSRF token recommended for browser-based newsletter subscriptions');
+    }
+    
     return this.create<CreateNewsletterSubscriptionRequest, NewsletterSubscribeResponse>(
       this.newsletterEndpoint(siteName, '/newsletter/subscribe'),
-      data
+      data,
+      csrfToken
     );
   }
 
@@ -55,14 +65,19 @@ export class NewsletterClient extends BaseClient {
 
   /**
    * Unsubscribe from newsletter
+   * @param siteName - The site to unsubscribe from
+   * @param data - Unsubscribe data
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
   async unsubscribe(
     siteName: string,
-    data: NewsletterUnsubscribeRequest
+    data: NewsletterUnsubscribeRequest,
+    csrfToken?: string
   ): Promise<ApiResponse<{ message: string }>> {
     return this.create<NewsletterUnsubscribeRequest, { message: string }>(
       this.newsletterEndpoint(siteName, '/newsletter/unsubscribe'),
-      data
+      data,
+      csrfToken
     );
   }
 
@@ -81,15 +96,21 @@ export class NewsletterClient extends BaseClient {
 
   /**
    * Update subscription preferences
+   * @param siteName - The site name
+   * @param email - Subscriber email
+   * @param preferences - New preferences
+   * @param csrfToken - CSRF token (required for browser-based submissions)
    */
   async updatePreferences(
     siteName: string,
     email: string,
-    preferences: NewsletterPreferences
+    preferences: NewsletterPreferences,
+    csrfToken?: string
   ): Promise<ApiResponse<{ message: string; preferences: NewsletterPreferences }>> {
     return this.patch(
       this.newsletterEndpoint(siteName, '/newsletter/preferences'),
-      { email, ...preferences }
+      { email, ...preferences },
+      csrfToken
     );
   }
 

package/src/types/index.ts

@@ -473,4 +473,5 @@ export interface RequestOptions {
   body?: any;
   params?: Record<string, string | number | boolean>;
   timeout?: number;
+  csrfToken?: string;  // Optional CSRF token for protected endpoints
 }

package/src/utils/http-client.ts

@@ -115,29 +115,29 @@ export class HttpClient {
   /**
    * POST request
    */
-  async post<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>> {
-    return this.request<T>(endpoint, { method: 'POST', body });
+  async post<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>> {
+    return this.request<T>(endpoint, { method: 'POST', body, ...options });
   }
 
   /**
    * PUT request
    */
-  async put<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>> {
-    return this.request<T>(endpoint, { method: 'PUT', body });
+  async put<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>> {
+    return this.request<T>(endpoint, { method: 'PUT', body, ...options });
   }
 
   /**
    * DELETE request
    */
-  async delete<T = any>(endpoint: string): Promise<ApiResponse<T>> {
-    return this.request<T>(endpoint, { method: 'DELETE' });
+  async delete<T = any>(endpoint: string, options?: Partial<RequestOptions>): Promise<ApiResponse<T>> {
+    return this.request<T>(endpoint, { method: 'DELETE', ...options });
   }
 
   /**
    * PATCH request
    */
-  async patch<T = any>(endpoint: string, body?: any): Promise<ApiResponse<T>> {
-    return this.request<T>(endpoint, { method: 'PATCH', body });
+  async patch<T = any>(endpoint: string, body?: any, options?: Partial<RequestOptions>): Promise<ApiResponse<T>> {
+    return this.request<T>(endpoint, { method: 'PATCH', body, ...options });
   }
 
   /**
@@ -169,6 +169,11 @@ export class HttpClient {
       ...options.headers,
     };
 
+    // Add CSRF token if provided
+    if (options.csrfToken) {
+      headers['X-CSRF-Token'] = options.csrfToken;
+    }
+
     const requestOptions: RequestInit = {
       method: options.method || 'GET',
       headers,