perspectapi-ts-sdk 1.1.1 → 1.3.0

package/src/client/newsletter-client.ts

@@ -0,0 +1,381 @@
+/**
+ * Newsletter subscription client for PerspectAPI SDK
+ */
+
+import { BaseClient } from './base-client';
+import type {
+  NewsletterSubscription,
+  CreateNewsletterSubscriptionRequest,
+  NewsletterList,
+  NewsletterPreferences,
+  NewsletterStatusResponse,
+  NewsletterSubscribeResponse,
+  NewsletterConfirmResponse,
+  NewsletterUnsubscribeRequest,
+  PaginatedResponse,
+  ApiResponse,
+} from '../types';
+
+export class NewsletterClient extends BaseClient {
+  constructor(http: any) {
+    super(http, '/api/v1');
+  }
+
+  /**
+   * Build a newsletter endpoint scoped to a site (without /sites prefix)
+   */
+  private newsletterEndpoint(siteName: string, endpoint: string): string {
+    return this.siteScopedEndpoint(siteName, endpoint, { includeSitesSegment: false });
+  }
+
+  /**
+   * 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,
+    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,
+      csrfToken
+    );
+  }
+
+  /**
+   * Confirm newsletter subscription via token
+   */
+  async confirmSubscription(
+    siteName: string,
+    token: string
+  ): Promise<ApiResponse<NewsletterConfirmResponse>> {
+    return this.getSingle(
+      this.newsletterEndpoint(siteName, `/newsletter/confirm/${encodeURIComponent(token)}`)
+    );
+  }
+
+  /**
+   * 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,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ message: string }>> {
+    return this.create<NewsletterUnsubscribeRequest, { message: string }>(
+      this.newsletterEndpoint(siteName, '/newsletter/unsubscribe'),
+      data,
+      csrfToken
+    );
+  }
+
+  /**
+   * One-click unsubscribe via token (GET request)
+   */
+  async unsubscribeByToken(
+    siteName: string,
+    token: string
+  ): Promise<ApiResponse<string>> {
+    // This returns HTML, so we return the raw response
+    return this.http.get(
+      this.buildPath(this.newsletterEndpoint(siteName, `/newsletter/unsubscribe/${encodeURIComponent(token)}`))
+    );
+  }
+
+  /**
+   * 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,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ message: string; preferences: NewsletterPreferences }>> {
+    return this.patch(
+      this.newsletterEndpoint(siteName, '/newsletter/preferences'),
+      { email, ...preferences },
+      csrfToken
+    );
+  }
+
+  /**
+   * Get available newsletter lists
+   */
+  async getLists(siteName: string): Promise<ApiResponse<{
+    lists: NewsletterList[];
+    total: number;
+  }>> {
+    return this.getSingle(
+      this.newsletterEndpoint(siteName, '/newsletter/lists')
+    );
+  }
+
+  /**
+   * Check subscription status by email
+   */
+  async getStatus(
+    siteName: string,
+    email: string
+  ): Promise<ApiResponse<NewsletterStatusResponse>> {
+    return this.http.get(
+      this.buildPath(this.newsletterEndpoint(siteName, '/newsletter/status')),
+      { email }
+    );
+  }
+
+  // Admin methods (require authentication)
+
+  /**
+   * Get all newsletter subscriptions (admin only)
+   */
+  async getSubscriptions(
+    siteName: string,
+    params?: {
+      page?: number;
+      limit?: number;
+      status?: string;
+      list_id?: string;
+      search?: string;
+      startDate?: string;
+      endDate?: string;
+    }
+  ): Promise<PaginatedResponse<NewsletterSubscription>> {
+    return this.getPaginated<NewsletterSubscription>(
+      this.newsletterEndpoint(siteName, '/newsletter/subscriptions'),
+      params
+    );
+  }
+
+  /**
+   * Get subscription by ID (admin only)
+   */
+  async getSubscriptionById(
+    siteName: string,
+    id: string
+  ): Promise<ApiResponse<NewsletterSubscription>> {
+    return this.getSingle(
+      this.newsletterEndpoint(siteName, `/newsletter/subscriptions/${encodeURIComponent(id)}`)
+    );
+  }
+
+  /**
+   * Update subscription status (admin only)
+   */
+  async updateSubscriptionStatus(
+    siteName: string,
+    id: string,
+    status: 'confirmed' | 'unsubscribed' | 'bounced' | 'complained',
+    notes?: string
+  ): Promise<ApiResponse<{ message: string }>> {
+    return this.patch(
+      this.newsletterEndpoint(siteName, `/newsletter/subscriptions/${encodeURIComponent(id)}`),
+      { status, notes }
+    );
+  }
+
+  /**
+   * Delete subscription (admin only)
+   */
+  async deleteSubscription(
+    siteName: string,
+    id: string
+  ): Promise<ApiResponse<{ message: string }>> {
+    return this.delete<{ message: string }>(
+      this.newsletterEndpoint(siteName, `/newsletter/subscriptions/${encodeURIComponent(id)}`)
+    );
+  }
+
+  /**
+   * Bulk update subscriptions (admin only)
+   */
+  async bulkUpdateSubscriptions(
+    siteName: string,
+    data: {
+      ids: string[];
+      action: 'confirm' | 'unsubscribe' | 'delete' | 'add_to_list' | 'remove_from_list';
+      list_id?: string;
+    }
+  ): Promise<ApiResponse<{
+    success: boolean;
+    updatedCount: number;
+    failedCount: number;
+  }>> {
+    return this.create(
+      this.newsletterEndpoint(siteName, '/newsletter/subscriptions/bulk-update'),
+      data
+    );
+  }
+
+  /**
+   * Create newsletter list (admin only)
+   */
+  async createList(
+    siteName: string,
+    data: {
+      list_name: string;
+      slug: string;
+      description?: string;
+      is_public?: boolean;
+      is_default?: boolean;
+      double_opt_in?: boolean;
+      welcome_email_enabled?: boolean;
+    }
+  ): Promise<ApiResponse<NewsletterList>> {
+    return this.create<any, NewsletterList>(
+      this.newsletterEndpoint(siteName, '/newsletter/lists'),
+      data
+    );
+  }
+
+  /**
+   * Update newsletter list (admin only)
+   */
+  async updateList(
+    siteName: string,
+    listId: string,
+    data: Partial<{
+      list_name: string;
+      description: string;
+      is_public: boolean;
+      is_default: boolean;
+      double_opt_in: boolean;
+      welcome_email_enabled: boolean;
+    }>
+  ): Promise<ApiResponse<{ message: string }>> {
+    return this.update(
+      this.newsletterEndpoint(siteName, `/newsletter/lists/${encodeURIComponent(listId)}`),
+      data
+    );
+  }
+
+  /**
+   * Delete newsletter list (admin only)
+   */
+  async deleteList(
+    siteName: string,
+    listId: string
+  ): Promise<ApiResponse<{ message: string }>> {
+    return this.delete<{ message: string }>(
+      this.newsletterEndpoint(siteName, `/newsletter/lists/${encodeURIComponent(listId)}`)
+    );
+  }
+
+  /**
+   * Get newsletter statistics (admin only)
+   */
+  async getStatistics(
+    siteName: string,
+    params?: {
+      startDate?: string;
+      endDate?: string;
+      list_id?: string;
+    }
+  ): Promise<ApiResponse<{
+    totalSubscribers: number;
+    confirmedSubscribers: number;
+    pendingSubscribers: number;
+    unsubscribedCount: number;
+    bouncedCount: number;
+    subscribersByDay: Array<{
+      date: string;
+      count: number;
+    }>;
+    subscribersByList: Array<{
+      list_id: string;
+      list_name: string;
+      count: number;
+    }>;
+    engagementMetrics: {
+      averageOpenRate: number;
+      averageClickRate: number;
+    };
+  }>> {
+    return this.http.get(
+      this.buildPath(this.newsletterEndpoint(siteName, '/newsletter/statistics')),
+      params
+    );
+  }
+
+  /**
+   * Export newsletter subscriptions (admin only)
+   */
+  async exportSubscriptions(
+    siteName: string,
+    params?: {
+      format?: 'csv' | 'json' | 'xlsx';
+      status?: string;
+      list_id?: string;
+      startDate?: string;
+      endDate?: string;
+    }
+  ): Promise<ApiResponse<{
+    downloadUrl: string;
+    expiresAt: string;
+  }>> {
+    return this.create(
+      this.newsletterEndpoint(siteName, '/newsletter/export'),
+      params || {}
+    );
+  }
+
+  /**
+   * Import newsletter subscriptions (admin only)
+   */
+  async importSubscriptions(
+    siteName: string,
+    data: {
+      subscriptions: Array<{
+        email: string;
+        name?: string;
+        status?: string;
+        lists?: string[];
+      }>;
+      skip_confirmation?: boolean;
+      update_existing?: boolean;
+    }
+  ): Promise<ApiResponse<{
+    imported: number;
+    updated: number;
+    failed: number;
+    errors?: Array<{ email: string; error: string }>;
+  }>> {
+    return this.create(
+      this.newsletterEndpoint(siteName, '/newsletter/import'),
+      data
+    );
+  }
+
+  /**
+   * Send test newsletter (admin only)
+   */
+  async sendTestNewsletter(
+    siteName: string,
+    data: {
+      to: string;
+      subject: string;
+      html_content: string;
+      text_content?: string;
+    }
+  ): Promise<ApiResponse<{ message: string; sent: boolean }>> {
+    return this.create(
+      this.newsletterEndpoint(siteName, '/newsletter/test'),
+      data
+    );
+  }
+}

package/src/index.ts

@@ -18,6 +18,7 @@ export { CategoriesClient } from './client/categories-client';
 export { WebhooksClient } from './client/webhooks-client';
 export { CheckoutClient } from './client/checkout-client';
 export { ContactClient } from './client/contact-client';
+export { NewsletterClient } from './client/newsletter-client';
 
 // Base classes
 export { BaseClient } from './client/base-client';
@@ -71,4 +72,12 @@ export type {
   ContactSubmission,
   CheckoutSession,
   PaymentGateway,
+  NewsletterSubscription,
+  CreateNewsletterSubscriptionRequest,
+  NewsletterList,
+  NewsletterPreferences,
+  NewsletterStatusResponse,
+  NewsletterSubscribeResponse,
+  NewsletterConfirmResponse,
+  NewsletterUnsubscribeRequest,
 } from './types';

package/src/perspect-api-client.ts

@@ -14,6 +14,7 @@ import { CategoriesClient } from './client/categories-client';
 import { WebhooksClient } from './client/webhooks-client';
 import { CheckoutClient } from './client/checkout-client';
 import { ContactClient } from './client/contact-client';
+import { NewsletterClient } from './client/newsletter-client';
 
 import type { PerspectApiConfig, ApiResponse } from './types';
 
@@ -31,6 +32,7 @@ export class PerspectApiClient {
   public readonly webhooks: WebhooksClient;
   public readonly checkout: CheckoutClient;
   public readonly contact: ContactClient;
+  public readonly newsletter: NewsletterClient;
 
   constructor(config: PerspectApiConfig) {
     // Validate required configuration
@@ -52,6 +54,7 @@ export class PerspectApiClient {
     this.webhooks = new WebhooksClient(this.http);
     this.checkout = new CheckoutClient(this.http);
     this.contact = new ContactClient(this.http);
+    this.newsletter = new NewsletterClient(this.http);
   }
 
   /**

package/src/types/index.ts

@@ -119,6 +119,83 @@ export interface CreateSiteRequest {
   organizationId: number;
 }
 
+// Newsletter Subscriptions
+export interface NewsletterSubscription {
+  id: string;
+  email: string;
+  name?: string;
+  status: 'pending' | 'confirmed' | 'unsubscribed' | 'bounced' | 'complained';
+  frequency: 'instant' | 'daily' | 'weekly' | 'monthly';
+  topics?: string[];
+  language: string;
+  confirmedAt?: string;
+  unsubscribedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateNewsletterSubscriptionRequest {
+  email: string;
+  name?: string;
+  list_ids?: string[];
+  frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
+  topics?: string[];
+  language?: string;
+  source?: string;
+  source_url?: string;
+  double_opt_in?: boolean;
+  turnstile_token?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface NewsletterList {
+  id: string;
+  list_name: string;
+  slug: string;
+  description?: string;
+  is_default: boolean;
+  subscriber_count?: number;
+}
+
+export interface NewsletterPreferences {
+  frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
+  topics?: string[];
+  language?: string;
+  email_format?: 'html' | 'text' | 'both';
+  timezone?: string;
+  track_opens?: boolean;
+  track_clicks?: boolean;
+}
+
+export interface NewsletterStatusResponse {
+  subscribed: boolean;
+  status: string;
+  frequency?: string;
+  created_at?: string;
+  confirmed_at?: string;
+}
+
+export interface NewsletterSubscribeResponse {
+  message: string;
+  status: string;
+  subscription_id?: string;
+}
+
+export interface NewsletterConfirmResponse {
+  message: string;
+  subscription?: {
+    email: string;
+    name?: string;
+    frequency: string;
+  };
+}
+
+export interface NewsletterUnsubscribeRequest {
+  token?: string;
+  email?: string;
+  reason?: string;
+}
+
 // Content Management
 export type ContentStatus = 'draft' | 'publish' | 'private' | 'trash';
 export type ContentType = 'post' | 'page';
@@ -396,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,