perspectapi-ts-sdk 3.7.0 → 5.0.0

package/package.json

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

package/src/client/newsletter-client.ts

@@ -6,7 +6,6 @@ import { BaseClient } from './base-client';
 import type { CacheManager } from '../cache/cache-manager';
 import type { CachePolicy } from '../cache/types';
 import type {
-  NewsletterSubscription,
   CreateNewsletterSubscriptionRequest,
   NewsletterList,
   NewsletterCampaignDetail,
@@ -17,7 +16,6 @@ import type {
   NewsletterConfirmResponse,
   NewsletterUnsubscribeRequest,
   NewsletterUnsubscribeResponse,
-  PaginatedResponse,
   ApiResponse,
 } from '../types';
 import { validateOptionalLimit } from '../utils/validators';
@@ -304,246 +302,6 @@ export class NewsletterClient extends BaseClient {
     );
   }
 
-  // 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
-    );
-  }
-
   // ============================================
   // Tracking methods (for first-party tracking)
   // ============================================

package/src/client/newsletter-management-client.ts

@@ -0,0 +1,426 @@
+/**
+ * Newsletter management client for PerspectAPI SDK
+ * Strict management surface under /newsletter/management/*
+ */
+
+import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
+import type {
+  ApiResponse,
+  NewsletterCampaignTestSendRequest,
+  NewsletterCampaignTestSendResponse,
+  NewsletterExportCreateRequest,
+  NewsletterExportCreateResponse,
+  NewsletterManagementCampaign,
+  NewsletterManagementCampaignListResponse,
+  NewsletterManagementList,
+  NewsletterManagementSeries,
+  NewsletterManagementStatsResponse,
+  NewsletterManagementSubscription,
+  NewsletterManagementSubscriptionsListResponse,
+  NewsletterSubscriptionMembershipUpdateRequest,
+  NewsletterSubscriptionSyncRequest,
+  NewsletterSubscriptionSyncResponse,
+  NewsletterSubscriptionsBulkUpdateRequest,
+  NewsletterSubscriptionsBulkUpdateResponse,
+  NewsletterSubscriptionsImportRequest,
+  NewsletterSubscriptionsImportResponse,
+} from '../types';
+
+export class NewsletterManagementClient extends BaseClient {
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
+  }
+
+  private managementEndpoint(siteName: string, endpoint: string): string {
+    return this.siteScopedEndpoint(
+      siteName,
+      `/newsletter/management${endpoint}`,
+      { includeSitesSegment: false },
+    );
+  }
+
+  async listSubscriptions(
+    siteName: string,
+    params?: {
+      page?: number;
+      limit?: number;
+      status?: 'pending' | 'confirmed' | 'unsubscribed' | 'bounced' | 'complained';
+      list_id?: string;
+      search?: string;
+      startDate?: string;
+      endDate?: string;
+    },
+  ): Promise<ApiResponse<NewsletterManagementSubscriptionsListResponse>> {
+    return this.http.get(
+      this.buildPath(this.managementEndpoint(siteName, '/subscriptions')),
+      params,
+    );
+  }
+
+  async getSubscriptionById(
+    siteName: string,
+    subscriptionId: string,
+  ): Promise<ApiResponse<NewsletterManagementSubscription>> {
+    return this.getSingle(
+      this.managementEndpoint(
+        siteName,
+        `/subscriptions/${encodeURIComponent(subscriptionId)}`,
+      ),
+    );
+  }
+
+  async getSubscriptionByEmail(
+    siteName: string,
+    email: string,
+  ): Promise<ApiResponse<NewsletterManagementSubscription>> {
+    return this.http.get(
+      this.buildPath(this.managementEndpoint(siteName, '/subscriptions/by-email')),
+      { email },
+    );
+  }
+
+  async syncSubscription(
+    siteName: string,
+    data: NewsletterSubscriptionSyncRequest,
+  ): Promise<ApiResponse<NewsletterSubscriptionSyncResponse>> {
+    return this.create(this.managementEndpoint(siteName, '/subscriptions/sync'), data);
+  }
+
+  async updateSubscription(
+    siteName: string,
+    subscriptionId: string,
+    data: Omit<NewsletterSubscriptionSyncRequest, 'email'>,
+  ): Promise<ApiResponse<NewsletterSubscriptionSyncResponse>> {
+    return this.patch(
+      this.managementEndpoint(
+        siteName,
+        `/subscriptions/${encodeURIComponent(subscriptionId)}`,
+      ),
+      data,
+    );
+  }
+
+  async deleteSubscription(
+    siteName: string,
+    subscriptionId: string,
+  ): Promise<ApiResponse<{ deleted: boolean; subscription_id: string }>> {
+    return this.delete(
+      this.managementEndpoint(
+        siteName,
+        `/subscriptions/${encodeURIComponent(subscriptionId)}`,
+      ),
+    );
+  }
+
+  async bulkUpdateSubscriptions(
+    siteName: string,
+    data: NewsletterSubscriptionsBulkUpdateRequest,
+  ): Promise<ApiResponse<NewsletterSubscriptionsBulkUpdateResponse>> {
+    return this.create(this.managementEndpoint(siteName, '/subscriptions/bulk'), data);
+  }
+
+  async updateSubscriptionListMembership(
+    siteName: string,
+    subscriptionId: string,
+    data: NewsletterSubscriptionMembershipUpdateRequest,
+  ): Promise<ApiResponse<{
+    subscription: NewsletterManagementSubscription;
+    mode: 'add' | 'remove' | 'replace';
+    list_ids: string[];
+  }>> {
+    return this.create(
+      this.managementEndpoint(
+        siteName,
+        `/subscriptions/${encodeURIComponent(subscriptionId)}/list-membership`,
+      ),
+      data,
+    );
+  }
+
+  async importSubscriptions(
+    siteName: string,
+    data: NewsletterSubscriptionsImportRequest,
+  ): Promise<ApiResponse<NewsletterSubscriptionsImportResponse>> {
+    return this.create(
+      this.managementEndpoint(siteName, '/subscriptions/import'),
+      data,
+    );
+  }
+
+  async listLists(
+    siteName: string,
+    params?: { status?: 'active' | 'archived' },
+  ): Promise<ApiResponse<{ items: NewsletterManagementList[]; total: number }>> {
+    return this.http.get(
+      this.buildPath(this.managementEndpoint(siteName, '/lists')),
+      params,
+    );
+  }
+
+  async getListById(
+    siteName: string,
+    listId: string,
+  ): Promise<ApiResponse<NewsletterManagementList>> {
+    return this.getSingle(
+      this.managementEndpoint(siteName, `/lists/${encodeURIComponent(listId)}`),
+    );
+  }
+
+  async createList(
+    siteName: string,
+    data: {
+      list_name: string;
+      slug: string;
+      description?: string | null;
+      is_public?: boolean;
+      is_default?: boolean;
+      double_opt_in?: boolean;
+      welcome_email_enabled?: boolean;
+    },
+  ): Promise<ApiResponse<NewsletterManagementList>> {
+    return this.create(this.managementEndpoint(siteName, '/lists'), data);
+  }
+
+  async updateList(
+    siteName: string,
+    listId: string,
+    data: Partial<{
+      list_name: string | null;
+      slug: string | null;
+      description: string | null;
+      is_public: boolean;
+      is_default: boolean;
+      double_opt_in: boolean;
+      welcome_email_enabled: boolean;
+      status: 'active' | 'archived';
+    }>,
+  ): Promise<ApiResponse<NewsletterManagementList>> {
+    return this.update(
+      this.managementEndpoint(siteName, `/lists/${encodeURIComponent(listId)}`),
+      data,
+    );
+  }
+
+  async deleteList(
+    siteName: string,
+    listId: string,
+  ): Promise<ApiResponse<{ deleted: boolean; list_id: string }>> {
+    return this.delete(
+      this.managementEndpoint(siteName, `/lists/${encodeURIComponent(listId)}`),
+    );
+  }
+
+  async listSeries(
+    siteName: string,
+    params?: { status?: 'active' | 'paused' | 'archived' },
+  ): Promise<ApiResponse<{ items: NewsletterManagementSeries[]; total: number }>> {
+    return this.http.get(
+      this.buildPath(this.managementEndpoint(siteName, '/series')),
+      params,
+    );
+  }
+
+  async getSeriesById(
+    siteName: string,
+    seriesId: string,
+  ): Promise<ApiResponse<NewsletterManagementSeries>> {
+    return this.getSingle(
+      this.managementEndpoint(siteName, `/series/${encodeURIComponent(seriesId)}`),
+    );
+  }
+
+  async createSeries(
+    siteName: string,
+    data: {
+      series_name: string;
+      description?: string | null;
+      status?: 'active' | 'paused' | 'archived';
+      cadence?: 'manual' | 'daily' | 'weekly' | 'monthly';
+      timezone?: string | null;
+      send_time?: string | null;
+      day_of_week?: number | null;
+      day_of_month?: number | null;
+      next_send_at?: string | null;
+      list_ids?: string[];
+      from_name?: string | null;
+      from_email?: string | null;
+      reply_to_email?: string | null;
+      subject_prefix?: string | null;
+      tags?: string[];
+      notes?: string | null;
+    },
+  ): Promise<ApiResponse<NewsletterManagementSeries>> {
+    return this.create(this.managementEndpoint(siteName, '/series'), data);
+  }
+
+  async updateSeries(
+    siteName: string,
+    seriesId: string,
+    data: Partial<{
+      series_name: string;
+      description?: string | null;
+      status?: 'active' | 'paused' | 'archived';
+      cadence?: 'manual' | 'daily' | 'weekly' | 'monthly';
+      timezone?: string | null;
+      send_time?: string | null;
+      day_of_week?: number | null;
+      day_of_month?: number | null;
+      next_send_at?: string | null;
+      list_ids?: string[];
+      from_name?: string | null;
+      from_email?: string | null;
+      reply_to_email?: string | null;
+      subject_prefix?: string | null;
+      tags?: string[];
+      notes?: string | null;
+    }>,
+  ): Promise<ApiResponse<NewsletterManagementSeries>> {
+    return this.update(
+      this.managementEndpoint(siteName, `/series/${encodeURIComponent(seriesId)}`),
+      data,
+    );
+  }
+
+  async deleteSeries(
+    siteName: string,
+    seriesId: string,
+  ): Promise<ApiResponse<{ deleted: boolean; series_id: string }>> {
+    return this.delete(
+      this.managementEndpoint(siteName, `/series/${encodeURIComponent(seriesId)}`),
+    );
+  }
+
+  async listCampaigns(
+    siteName: string,
+    params?: {
+      page?: number;
+      limit?: number;
+      status?: 'draft' | 'scheduled' | 'sending' | 'sent' | 'cancelled';
+    },
+  ): Promise<ApiResponse<NewsletterManagementCampaignListResponse>> {
+    return this.http.get(
+      this.buildPath(this.managementEndpoint(siteName, '/campaigns')),
+      params,
+    );
+  }
+
+  async getCampaignById(
+    siteName: string,
+    campaignId: string,
+  ): Promise<ApiResponse<NewsletterManagementCampaign>> {
+    return this.getSingle(
+      this.managementEndpoint(siteName, `/campaigns/${encodeURIComponent(campaignId)}`),
+    );
+  }
+
+  async createCampaign(
+    siteName: string,
+    data: {
+      campaign_name: string;
+      subject: string;
+      markdown_content: string;
+      slug?: string | null;
+      slug_prefix?: string | null;
+      status?: 'draft' | 'scheduled' | 'cancelled';
+      scheduled_at?: string | null;
+      preview_text?: string | null;
+      from_name?: string | null;
+      from_email?: string | null;
+      reply_to_email?: string | null;
+      template_id?: string | null;
+      series_id?: string | null;
+      list_ids?: string[];
+      tags?: string[];
+      notes?: string | null;
+    },
+  ): Promise<ApiResponse<NewsletterManagementCampaign>> {
+    return this.create(this.managementEndpoint(siteName, '/campaigns'), data);
+  }
+
+  async updateCampaign(
+    siteName: string,
+    campaignId: string,
+    data: Partial<{
+      campaign_name: string;
+      subject: string;
+      markdown_content: string;
+      slug?: string | null;
+      slug_prefix?: string | null;
+      status?: 'draft' | 'scheduled' | 'cancelled';
+      scheduled_at?: string | null;
+      preview_text?: string | null;
+      from_name?: string | null;
+      from_email?: string | null;
+      reply_to_email?: string | null;
+      template_id?: string | null;
+      series_id?: string | null;
+      list_ids?: string[];
+      tags?: string[];
+      notes?: string | null;
+    }>,
+  ): Promise<ApiResponse<NewsletterManagementCampaign>> {
+    return this.update(
+      this.managementEndpoint(siteName, `/campaigns/${encodeURIComponent(campaignId)}`),
+      data,
+    );
+  }
+
+  async deleteCampaign(
+    siteName: string,
+    campaignId: string,
+  ): Promise<ApiResponse<{ deleted: boolean; campaign_id: string }>> {
+    return this.delete(
+      this.managementEndpoint(siteName, `/campaigns/${encodeURIComponent(campaignId)}`),
+    );
+  }
+
+  async sendCampaignTest(
+    siteName: string,
+    campaignId: string,
+    data: NewsletterCampaignTestSendRequest,
+  ): Promise<ApiResponse<NewsletterCampaignTestSendResponse>> {
+    return this.create(
+      this.managementEndpoint(
+        siteName,
+        `/campaigns/${encodeURIComponent(campaignId)}/test-send`,
+      ),
+      data,
+    );
+  }
+
+  async getStats(
+    siteName: string,
+    params?: {
+      startDate?: string;
+      endDate?: string;
+      list_id?: string;
+    },
+  ): Promise<ApiResponse<NewsletterManagementStatsResponse>> {
+    return this.http.get(
+      this.buildPath(this.managementEndpoint(siteName, '/stats')),
+      params,
+    );
+  }
+
+  async createExport(
+    siteName: string,
+    data: NewsletterExportCreateRequest,
+  ): Promise<ApiResponse<NewsletterExportCreateResponse>> {
+    return this.create(
+      this.managementEndpoint(siteName, '/exports'),
+      data,
+    );
+  }
+
+  async downloadExport(
+    siteName: string,
+    exportId: string,
+  ): Promise<ApiResponse<string>> {
+    return this.http.get(
+      this.buildPath(
+        this.managementEndpoint(siteName, `/exports/${encodeURIComponent(exportId)}/download`),
+      ),
+    );
+  }
+}