perspectapi-ts-sdk 1.1.1 → 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

@@ -98,6 +98,74 @@ interface CreateSiteRequest {
     description?: string;
     organizationId: number;
 }
+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;
+}
+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>;
+}
+interface NewsletterList {
+    id: string;
+    list_name: string;
+    slug: string;
+    description?: string;
+    is_default: boolean;
+    subscriber_count?: number;
+}
+interface NewsletterPreferences {
+    frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
+    topics?: string[];
+    language?: string;
+    email_format?: 'html' | 'text' | 'both';
+    timezone?: string;
+    track_opens?: boolean;
+    track_clicks?: boolean;
+}
+interface NewsletterStatusResponse {
+    subscribed: boolean;
+    status: string;
+    frequency?: string;
+    created_at?: string;
+    confirmed_at?: string;
+}
+interface NewsletterSubscribeResponse {
+    message: string;
+    status: string;
+    subscription_id?: string;
+}
+interface NewsletterConfirmResponse {
+    message: string;
+    subscription?: {
+        email: string;
+        name?: string;
+        frequency: string;
+    };
+}
+interface NewsletterUnsubscribeRequest {
+    token?: string;
+    email?: string;
+    reason?: string;
+}
 type ContentStatus = 'draft' | 'publish' | 'private' | 'trash';
 type ContentType = 'post' | 'page';
 interface Content {
@@ -329,6 +397,7 @@ interface RequestOptions {
     body?: any;
     params?: Record<string, string | number | boolean>;
     timeout?: number;
+    csrfToken?: string;
 }
 
 /**
@@ -365,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
      */
@@ -433,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>>;
 }
 
 /**
@@ -1389,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;
@@ -1532,6 +1604,208 @@ declare class ContactClient extends BaseClient {
     }>>;
 }
 
+/**
+ * Newsletter subscription client for PerspectAPI SDK
+ */
+
+declare class NewsletterClient extends BaseClient {
+    constructor(http: any);
+    /**
+     * Build a newsletter endpoint scoped to a site (without /sites prefix)
+     */
+    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, 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, csrfToken?: string): Promise<ApiResponse<{
+        message: string;
+    }>>;
+    /**
+     * One-click unsubscribe via token (GET request)
+     */
+    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, csrfToken?: string): Promise<ApiResponse<{
+        message: string;
+        preferences: NewsletterPreferences;
+    }>>;
+    /**
+     * Get available newsletter lists
+     */
+    getLists(siteName: string): Promise<ApiResponse<{
+        lists: NewsletterList[];
+        total: number;
+    }>>;
+    /**
+     * Check subscription status by email
+     */
+    getStatus(siteName: string, email: string): Promise<ApiResponse<NewsletterStatusResponse>>;
+    /**
+     * Get all newsletter subscriptions (admin only)
+     */
+    getSubscriptions(siteName: string, params?: {
+        page?: number;
+        limit?: number;
+        status?: string;
+        list_id?: string;
+        search?: string;
+        startDate?: string;
+        endDate?: string;
+    }): Promise<PaginatedResponse<NewsletterSubscription>>;
+    /**
+     * Get subscription by ID (admin only)
+     */
+    getSubscriptionById(siteName: string, id: string): Promise<ApiResponse<NewsletterSubscription>>;
+    /**
+     * Update subscription status (admin only)
+     */
+    updateSubscriptionStatus(siteName: string, id: string, status: 'confirmed' | 'unsubscribed' | 'bounced' | 'complained', notes?: string): Promise<ApiResponse<{
+        message: string;
+    }>>;
+    /**
+     * Delete subscription (admin only)
+     */
+    deleteSubscription(siteName: string, id: string): Promise<ApiResponse<{
+        message: string;
+    }>>;
+    /**
+     * Bulk update subscriptions (admin only)
+     */
+    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;
+    }>>;
+    /**
+     * Create newsletter list (admin only)
+     */
+    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>>;
+    /**
+     * Update newsletter list (admin only)
+     */
+    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;
+    }>>;
+    /**
+     * Delete newsletter list (admin only)
+     */
+    deleteList(siteName: string, listId: string): Promise<ApiResponse<{
+        message: string;
+    }>>;
+    /**
+     * Get newsletter statistics (admin only)
+     */
+    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;
+        };
+    }>>;
+    /**
+     * Export newsletter subscriptions (admin only)
+     */
+    exportSubscriptions(siteName: string, params?: {
+        format?: 'csv' | 'json' | 'xlsx';
+        status?: string;
+        list_id?: string;
+        startDate?: string;
+        endDate?: string;
+    }): Promise<ApiResponse<{
+        downloadUrl: string;
+        expiresAt: string;
+    }>>;
+    /**
+     * Import newsletter subscriptions (admin only)
+     */
+    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;
+        }>;
+    }>>;
+    /**
+     * Send test newsletter (admin only)
+     */
+    sendTestNewsletter(siteName: string, data: {
+        to: string;
+        subject: string;
+        html_content: string;
+        text_content?: string;
+    }): Promise<ApiResponse<{
+        message: string;
+        sent: boolean;
+    }>>;
+}
+
 /**
  * Main PerspectAPI SDK Client
  * Cloudflare Workers compatible TypeScript SDK
@@ -1549,6 +1823,7 @@ declare class PerspectApiClient {
     readonly webhooks: WebhooksClient;
     readonly checkout: CheckoutClient;
     readonly contact: ContactClient;
+    readonly newsletter: NewsletterClient;
     constructor(config: PerspectApiConfig);
     /**
      * Update authentication token
@@ -1767,4 +2042,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactSubmission, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, HttpClient, type HttpMethod, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactSubmission, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, HttpClient, type HttpMethod, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformProduct };