perspectapi-ts-sdk 3.7.0 → 5.0.0

package/README.md

@@ -688,79 +688,56 @@ const lists = await client.newsletter.getLists(siteName);
 console.log('Available lists:', lists.data.lists);
 ```
 
-#### Newsletter Admin Functions
+#### Newsletter Management APIs
+
+`client.newsletter` is now public-only (subscribe/confirm/unsubscribe/preferences/public lists/published campaigns).
+For management operations, use `client.newsletterManagement`.
 
 ```typescript
-// Get all subscriptions (admin only)
-const subscriptions = await client.newsletter.getSubscriptions(siteName, {
+// Sync subscriber by email (canonical create/update path)
+const sync = await client.newsletterManagement.syncSubscription(siteName, {
+  email: 'user@example.com',
+  name: 'User Name',
+  list_ids: ['list_default'],
+  resubscribe_override: false
+});
+console.log(sync.data.code); // CREATED, UPDATED, RESUBSCRIBED, ALREADY_UNSUBSCRIBED
+
+// List subscribers
+const subscriptions = await client.newsletterManagement.listSubscriptions(siteName, {
   page: 1,
   limit: 100,
-  status: 'confirmed',
-  list_id: 'list_weekly',
-  search: 'john',
-  startDate: '2024-01-01',
-  endDate: '2024-12-31'
+  status: 'confirmed'
 });
 
-// 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'
+// Import with override controls (row-level override wins)
+await client.newsletterManagement.importSubscriptions(siteName, {
+  resubscribe_override: false,
+  rows: [
+    { email: 'user1@example.com', list_ids: ['list_default'] },
+    { email: 'user2@example.com', resubscribe_override: true }
+  ]
 });
 
-// List management
-const newList = await client.newsletter.createList(siteName, {
+// List + campaign management
+await client.newsletterManagement.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
+  is_public: false
 });
 
-// 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'
+await client.newsletterManagement.createCampaign(siteName, {
+  campaign_name: 'Spring Update',
+  subject: 'Spring Update',
+  markdown_content: '# Hello',
+  status: 'draft'
 });
-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
+// Exports (csv/json only; xlsx returns UNSUPPORTED_FORMAT)
+const exportData = await client.newsletterManagement.createExport(siteName, {
+  format: 'csv'
 });
-console.log('Imported:', importResult.data.imported);
-console.log('Failed:', importResult.data.failed);
+console.log(exportData.data.downloadUrl);
 ```
 
 > 📚 **For complete newsletter documentation**, see [docs/newsletter.md](docs/newsletter.md)
@@ -847,9 +824,33 @@ const orders = await client.siteUsers.getOrders(siteName, {
 // Get subscriptions
 const subscriptions = await client.siteUsers.getSubscriptions(siteName);
 
-// Cancel subscription
+// Cancel at end of billing period (default)
 await client.siteUsers.cancelSubscription(siteName, 'sub_123', csrfToken);
 
+// Cancel immediately
+await client.siteUsers.cancelSubscription(
+  siteName,
+  'sub_123',
+  csrfToken,
+  { mode: 'immediate' }
+);
+
+// Cancel at a scheduled time (absolute)
+await client.siteUsers.cancelSubscription(
+  siteName,
+  'sub_123',
+  csrfToken,
+  { mode: 'scheduled', cancel_at: '2026-05-01T15:30:00Z' }
+);
+
+// Cancel after a configured delay (days/hours/minutes)
+await client.siteUsers.cancelSubscription(
+  siteName,
+  'sub_123',
+  csrfToken,
+  { mode: 'scheduled', delay_days: 7, delay_hours: 2 }
+);
+
 // Logout
 await client.siteUsers.logout(siteName);
 client.setAuth(null);