perspectapi-ts-sdk 3.7.0 → 5.0.0

package/src/client/site-users-client.ts

@@ -18,6 +18,8 @@ import type {
   VerifyOtpResponse,
   UpdateSiteUserRequest,
   SetProfileValueRequest,
+  CancelSubscriptionRequest,
+  CancelSubscriptionResponse,
   ApiResponse,
 } from '../types';
 
@@ -276,19 +278,21 @@ export class SiteUsersClient extends BaseClient {
   }
 
   /**
-   * Cancel a subscription (marks for cancellation at period end)
+   * Cancel a subscription.
    * @param siteName - The site name
    * @param id - Subscription ID
    * @param csrfToken - CSRF token (required)
+   * @param options - Cancellation mode/details
    */
   async cancelSubscription(
     siteName: string,
     id: string,
-    csrfToken?: string
-  ): Promise<ApiResponse<{ success: boolean; message: string }>> {
-    return this.create<Record<string, never>, { success: boolean; message: string }>(
+    csrfToken?: string,
+    options?: CancelSubscriptionRequest
+  ): Promise<ApiResponse<CancelSubscriptionResponse>> {
+    return this.create<CancelSubscriptionRequest, CancelSubscriptionResponse>(
       this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(id)}/cancel`),
-      {},
+      options ?? {},
       csrfToken
     );
   }
@@ -596,15 +600,17 @@ export class SiteUsersClient extends BaseClient {
    * @param siteName - The site name
    * @param userId - User ID
    * @param subscriptionId - Subscription ID
+   * @param options - Cancellation mode/details
    */
   async cancelUserSubscription(
     siteName: string,
     userId: string,
-    subscriptionId: string
-  ): Promise<ApiResponse<{ success: boolean; message: string }>> {
-    return this.create<Record<string, never>, { success: boolean; message: string }>(
+    subscriptionId: string,
+    options?: CancelSubscriptionRequest
+  ): Promise<ApiResponse<CancelSubscriptionResponse>> {
+    return this.create<CancelSubscriptionRequest, CancelSubscriptionResponse>(
       this.siteUserEndpoint(siteName, `/users/${encodeURIComponent(userId)}/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`),
-      {}
+      options ?? {}
     );
   }
 

package/src/index.ts

@@ -3,10 +3,14 @@
  * Cloudflare Workers compatible SDK for PerspectAPI
  */
 
-// Main client
+// Main client (v1)
 export { PerspectApiClient, createPerspectApiClient } from './perspect-api-client';
 export { default } from './perspect-api-client';
 
+// v2 client
+export { PerspectApiV2Client, createPerspectApiV2Client } from './v2';
+export { PerspectV2Error } from './v2/client/base-v2-client';
+
 // Individual clients (for advanced usage)
 export { AuthClient } from './client/auth-client';
 export { ContentClient } from './client/content-client';
@@ -19,6 +23,7 @@ export { WebhooksClient } from './client/webhooks-client';
 export { CheckoutClient } from './client/checkout-client';
 export { ContactClient } from './client/contact-client';
 export { NewsletterClient } from './client/newsletter-client';
+export { NewsletterManagementClient } from './client/newsletter-management-client';
 export { SiteUsersClient } from './client/site-users-client';
 export { BundlesClient } from './client/bundles-client';
 
@@ -109,6 +114,30 @@ export type {
   NewsletterConfirmResponse,
   NewsletterUnsubscribeRequest,
   NewsletterUnsubscribeResponse,
+  NewsletterManagementListMembership,
+  NewsletterManagementSubscription,
+  NewsletterSubscriptionSyncRequest,
+  NewsletterSubscriptionSyncResponse,
+  NewsletterSubscriptionsBulkAction,
+  NewsletterSubscriptionsBulkUpdateRequest,
+  NewsletterSubscriptionsBulkOutcome,
+  NewsletterSubscriptionsBulkUpdateResponse,
+  NewsletterSubscriptionMembershipUpdateRequest,
+  NewsletterSubscriptionImportRowRequest,
+  NewsletterSubscriptionsImportRequest,
+  NewsletterSubscriptionsImportRowResult,
+  NewsletterSubscriptionsImportResponse,
+  NewsletterManagementPagination,
+  NewsletterManagementSubscriptionsListResponse,
+  NewsletterManagementList,
+  NewsletterManagementSeries,
+  NewsletterManagementCampaign,
+  NewsletterManagementCampaignListResponse,
+  NewsletterCampaignTestSendRequest,
+  NewsletterCampaignTestSendResponse,
+  NewsletterManagementStatsResponse,
+  NewsletterExportCreateRequest,
+  NewsletterExportCreateResponse,
   ContactSubmitResponse,
   ContactStatusResponse,
   SiteUser,

package/src/perspect-api-client.ts

@@ -16,6 +16,7 @@ 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 { NewsletterManagementClient } from './client/newsletter-management-client';
 import { SiteUsersClient } from './client/site-users-client';
 import { BundlesClient } from './client/bundles-client';
 
@@ -37,6 +38,7 @@ export class PerspectApiClient {
   public readonly checkout: CheckoutClient;
   public readonly contact: ContactClient;
   public readonly newsletter: NewsletterClient;
+  public readonly newsletterManagement: NewsletterManagementClient;
   public readonly siteUsers: SiteUsersClient;
   public readonly bundles: BundlesClient;
 
@@ -62,6 +64,7 @@ export class PerspectApiClient {
     this.checkout = new CheckoutClient(this.http, this.cache);
     this.contact = new ContactClient(this.http, this.cache);
     this.newsletter = new NewsletterClient(this.http, this.cache);
+    this.newsletterManagement = new NewsletterManagementClient(this.http, this.cache);
     this.siteUsers = new SiteUsersClient(this.http, this.cache);
     this.bundles = new BundlesClient(this.http, this.cache);
   }

package/src/types/index.ts

@@ -225,6 +225,269 @@ export interface NewsletterUnsubscribeResponse {
   status?: string;
 }
 
+// Newsletter Management
+export interface NewsletterManagementListMembership {
+  id: string;
+  list_name: string;
+  slug: string;
+}
+
+export interface NewsletterManagementSubscription {
+  id: string;
+  site_id: string;
+  site_name: string;
+  email: string;
+  name?: string | null;
+  status: 'pending' | 'confirmed' | 'unsubscribed' | 'bounced' | 'complained';
+  confirmation_token?: string | null;
+  unsubscribe_token: string;
+  double_opt_in: boolean;
+  confirmed_at?: string | null;
+  source?: string | null;
+  source_url?: string | null;
+  frequency: 'instant' | 'daily' | 'weekly' | 'monthly';
+  topics?: string[] | string | null;
+  language: string;
+  tags?: string[] | string | null;
+  custom_fields?: Record<string, any> | string | null;
+  notes?: string | null;
+  unsubscribed_at?: string | null;
+  unsubscribe_reason?: string | null;
+  created_at: string;
+  updated_at: string;
+  lists: NewsletterManagementListMembership[];
+}
+
+export interface NewsletterSubscriptionSyncRequest {
+  email: string;
+  name?: string | null;
+  status?: 'pending' | 'confirmed' | 'unsubscribed' | 'bounced' | 'complained';
+  list_ids?: string[];
+  frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
+  topics?: string[];
+  language?: string | null;
+  source?: string | null;
+  source_url?: string | null;
+  notes?: string | null;
+  tags?: string[];
+  metadata?: Record<string, any>;
+  resubscribe_override?: boolean;
+}
+
+export interface NewsletterSubscriptionSyncResponse {
+  applied: boolean;
+  code: 'CREATED' | 'UPDATED' | 'RESUBSCRIBED' | 'ALREADY_UNSUBSCRIBED';
+  skipped_unsubscribed: boolean;
+  resubscribed: boolean;
+  created: boolean;
+  updated: boolean;
+  subscription_id: string;
+  subscription: NewsletterManagementSubscription;
+}
+
+export type NewsletterSubscriptionsBulkAction =
+  | 'confirm'
+  | 'unsubscribe'
+  | 'delete'
+  | 'add_to_list'
+  | 'remove_from_list';
+
+export interface NewsletterSubscriptionsBulkUpdateRequest {
+  ids: string[];
+  action: NewsletterSubscriptionsBulkAction;
+  list_id?: string;
+  resubscribe_override?: boolean;
+}
+
+export interface NewsletterSubscriptionsBulkOutcome {
+  id: string;
+  applied: boolean;
+  code: string;
+  error?: string;
+  skipped_unsubscribed?: boolean;
+}
+
+export interface NewsletterSubscriptionsBulkUpdateResponse {
+  succeeded: number;
+  failed: number;
+  skipped_unsubscribed: number;
+  outcomes: NewsletterSubscriptionsBulkOutcome[];
+}
+
+export interface NewsletterSubscriptionMembershipUpdateRequest {
+  mode: 'add' | 'remove' | 'replace';
+  list_ids: string[];
+}
+
+export interface NewsletterSubscriptionImportRowRequest {
+  email: string;
+  name?: string | null;
+  status?: 'pending' | 'confirmed' | 'unsubscribed' | 'bounced' | 'complained';
+  list_ids?: string[];
+  frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
+  topics?: string[];
+  language?: string | null;
+  source?: string | null;
+  source_url?: string | null;
+  notes?: string | null;
+  tags?: string[];
+  metadata?: Record<string, any>;
+  resubscribe_override?: boolean;
+}
+
+export interface NewsletterSubscriptionsImportRequest {
+  rows: NewsletterSubscriptionImportRowRequest[];
+  resubscribe_override?: boolean;
+}
+
+export interface NewsletterSubscriptionsImportRowResult {
+  index: number;
+  email: string;
+  applied: boolean;
+  code: string;
+  skipped_unsubscribed: boolean;
+  resubscribed: boolean;
+  subscription_id: string;
+}
+
+export interface NewsletterSubscriptionsImportResponse {
+  total: number;
+  processed: number;
+  applied: number;
+  created: number;
+  updated: number;
+  resubscribed: number;
+  skipped_unsubscribed: number;
+  rows: NewsletterSubscriptionsImportRowResult[];
+}
+
+export interface NewsletterManagementPagination {
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+}
+
+export interface NewsletterManagementSubscriptionsListResponse {
+  items: NewsletterManagementSubscription[];
+  pagination: NewsletterManagementPagination;
+}
+
+export interface NewsletterManagementList extends NewsletterList {
+  site_id: string;
+  site_name: string;
+  description?: string;
+  is_public: boolean;
+  is_default: boolean;
+  double_opt_in: boolean;
+  welcome_email_enabled: boolean;
+  subscriber_count: number;
+  status: 'active' | 'archived';
+  created_at: string;
+  updated_at: string;
+}
+
+export interface NewsletterManagementSeries {
+  id: string;
+  site_id: string;
+  site_name: string;
+  series_name: string;
+  description?: string | null;
+  list_ids?: string | null;
+  from_name?: string | null;
+  from_email?: string | null;
+  reply_to_email?: string | null;
+  subject_prefix?: string | null;
+  cadence: 'manual' | 'daily' | 'weekly' | 'monthly';
+  timezone?: string | null;
+  send_time?: string | null;
+  day_of_week?: number | null;
+  day_of_month?: number | null;
+  status: 'active' | 'paused' | 'archived';
+  last_sent_at?: string | null;
+  next_send_at?: string | null;
+  tags?: string | null;
+  notes?: string | null;
+  created_at: string;
+  updated_at: string;
+  created_by?: string | null;
+}
+
+export interface NewsletterManagementCampaign {
+  id: string;
+  site_id: string;
+  site_name: string;
+  series_id?: string | null;
+  series_name?: string | null;
+  campaign_name: string;
+  slug?: string | null;
+  slug_prefix?: string | null;
+  subject: string;
+  markdown_content?: string | null;
+  template_id?: string | null;
+  list_ids?: string | null;
+  tags?: string | null;
+  notes?: string | null;
+  preview_text?: string | null;
+  from_name?: string | null;
+  from_email?: string | null;
+  reply_to_email?: string | null;
+  status: 'draft' | 'scheduled' | 'sending' | 'sent' | 'cancelled';
+  scheduled_at?: string | null;
+  sent_at?: string | null;
+  completed_at?: string | null;
+  total_recipients?: number | null;
+  sent_count?: number | null;
+  delivered_count?: number | null;
+  opened_count?: number | null;
+  clicked_count?: number | null;
+  unsubscribed_count?: number | null;
+  bounced_count?: number | null;
+  complained_count?: number | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface NewsletterManagementCampaignListResponse {
+  items: NewsletterManagementCampaign[];
+  pagination: NewsletterManagementPagination;
+}
+
+export interface NewsletterCampaignTestSendRequest {
+  to: string | string[];
+  subject?: string | null;
+}
+
+export interface NewsletterCampaignTestSendResponse {
+  sent: number;
+  recipients: string[];
+  campaign_id: string;
+}
+
+export interface NewsletterManagementStatsResponse {
+  total: number;
+  byStatus: Record<string, number>;
+  recentActivity: Array<{
+    date: string;
+    count: number;
+  }>;
+}
+
+export interface NewsletterExportCreateRequest {
+  format?: 'csv' | 'json' | 'xlsx';
+  status?: 'pending' | 'confirmed' | 'unsubscribed' | 'bounced' | 'complained';
+  list_id?: string;
+  search?: string | null;
+}
+
+export interface NewsletterExportCreateResponse {
+  exportId: string;
+  downloadUrl: string;
+  expiresAt: string;
+  format: 'csv' | 'json';
+  rowCount: number;
+}
+
 // Content Management
 export type ContentStatus = 'draft' | 'publish' | 'private' | 'trash';
 export type ContentType = 'post' | 'page' | 'block';
@@ -695,7 +958,7 @@ export interface SiteUserSubscription {
   provider_subscription_id?: string;
   plan_name?: string;
   plan_id?: string;
-  status: 'active' | 'past_due' | 'canceled' | 'paused' | 'trialing' | 'expired';
+  status: 'active' | 'past_due' | 'canceled' | 'paused' | 'trialing' | 'expired' | 'incomplete';
   amount?: number;
   currency?: string;
   billing_interval?: string;
@@ -718,11 +981,34 @@ export interface SiteUserOrder {
   currency: string;
   status: string;
   payment_status?: string;
+  fulfillment_status?: string;
   line_items: any[];
   created_at: string;
   completed_at?: string;
 }
 
+export type SubscriptionCancellationMode = 'immediate' | 'period_end' | 'scheduled';
+
+export interface CancelSubscriptionRequest {
+  mode?: SubscriptionCancellationMode;
+  cancel_at?: string;      // ISO timestamp
+  delay_days?: number;
+  delay_hours?: number;
+  delay_minutes?: number;
+}
+
+export interface CancelSubscriptionResponse {
+  success: boolean;
+  message: string;
+  cancellation?: {
+    mode: SubscriptionCancellationMode;
+    status: string;
+    cancel_at_period_end: boolean;
+    effective_at: string | null;
+    scheduled_cancel_at: string | null;
+  };
+}
+
 // Credits
 export interface CreditTransaction {
   id: number;

package/src/v2/client/api-keys-client.ts

@@ -0,0 +1,21 @@
+/**
+ * v2 API Keys Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type { V2ApiKey, V2PaginationParams, V2List, V2Deleted } from '../types';
+
+export class ApiKeysV2Client extends BaseV2Client {
+
+  async list(params?: V2PaginationParams): Promise<V2List<V2ApiKey>> {
+    return this.getList<V2ApiKey>('/api-keys', params);
+  }
+
+  async get(id: string): Promise<V2ApiKey> {
+    return this.getOne<V2ApiKey>(`/api-keys/${id}`);
+  }
+
+  async del(id: string): Promise<V2Deleted> {
+    return this.deleteOne(`/api-keys/${id}`);
+  }
+}

package/src/v2/client/base-v2-client.ts

@@ -0,0 +1,146 @@
+/**
+ * v2 Base Client — cursor pagination, expand support, typed errors.
+ */
+
+import { HttpClient } from '../../utils/http-client';
+import type { V2List, V2Error, V2Deleted } from '../types';
+
+export class PerspectV2Error extends Error {
+  readonly type: string;
+  readonly code: string;
+  readonly param?: string;
+  readonly status: number;
+
+  constructor(error: V2Error['error'], status: number) {
+    super(error.message);
+    this.name = 'PerspectV2Error';
+    this.type = error.type;
+    this.code = error.code;
+    this.param = error.param;
+    this.status = status;
+  }
+}
+
+export abstract class BaseV2Client {
+  protected http: HttpClient;
+  protected basePath: string;
+
+  constructor(http: HttpClient, basePath: string) {
+    this.http = http;
+    this.basePath = basePath;
+  }
+
+  protected buildPath(endpoint: string): string {
+    const clean = endpoint.replace(/^\//, '');
+    return clean ? `${this.basePath}/${clean}` : this.basePath;
+  }
+
+  protected sitePath(siteName: string, resource: string, suffix = ''): string {
+    const encoded = encodeURIComponent(siteName.trim());
+    const cleanSuffix = suffix.replace(/^\//, '');
+    const end = cleanSuffix ? `/${cleanSuffix}` : '';
+    return `/sites/${encoded}/${resource}${end}`;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private toParams(params?: any): Record<string, string> | undefined {
+    if (!params) return undefined;
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null) out[k] = String(v);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  }
+
+  /** GET a single resource. */
+  protected async getOne<T>(path: string, params?: object): Promise<T> {
+    const response = await this.http.get<T>(path, this.toParams(params));
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /** GET a list of resources with cursor pagination. */
+  protected async getList<T>(
+    path: string,
+    params?: object,
+  ): Promise<V2List<T>> {
+    const response = await this.http.get<V2List<T>>(path, this.toParams(params));
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /** POST to create a resource. */
+  protected async post<T>(path: string, body?: unknown): Promise<T> {
+    const response = await this.http.post<T>(path, body);
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /** PATCH to update a resource. */
+  protected async patchOne<T>(path: string, body?: unknown): Promise<T> {
+    const response = await this.http.patch<T>(path, body);
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /** DELETE a resource. */
+  protected async deleteOne(path: string): Promise<V2Deleted> {
+    const response = await this.http.delete<V2Deleted>(path);
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /**
+   * Auto-paginating async generator.
+   * Yields every item across all pages.
+   *
+   * Usage:
+   *   for await (const item of client.listAutoPaginate(path, params)) { ... }
+   */
+  protected async *listAutoPaginate<T extends { id: string }>(
+    path: string,
+    params?: object,
+  ): AsyncGenerator<T, void, unknown> {
+    let startingAfter: string | undefined;
+    let hasMore = true;
+
+    while (hasMore) {
+      const queryParams: Record<string, unknown> = { ...(params as Record<string, unknown>) };
+      if (startingAfter) queryParams.starting_after = startingAfter;
+
+      const page = await this.getList<T>(path, queryParams);
+      for (const item of page.data) {
+        yield item;
+      }
+
+      hasMore = page.has_more;
+      if (page.data.length > 0) {
+        startingAfter = page.data[page.data.length - 1].id;
+      } else {
+        hasMore = false;
+      }
+    }
+  }
+
+  private toError(response: { data?: unknown; error?: unknown; message?: string }): PerspectV2Error {
+    const data = response.data as Record<string, unknown> | undefined;
+    const errorObj = (data?.error ?? response.error) as V2Error['error'] | undefined;
+    if (errorObj && typeof errorObj === 'object' && 'type' in errorObj) {
+      return new PerspectV2Error(errorObj, 400);
+    }
+    return new PerspectV2Error(
+      { type: 'api_error', code: 'unknown', message: response.message ?? 'Unknown error' },
+      500,
+    );
+  }
+}

package/src/v2/client/categories-client.ts

@@ -0,0 +1,32 @@
+/**
+ * v2 Categories Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type {
+  V2Category, V2CategoryCreateParams, V2CategoryUpdateParams,
+  V2PaginationParams, V2List, V2Deleted,
+} from '../types';
+
+export class CategoriesV2Client extends BaseV2Client {
+
+  async list(siteName: string, params?: V2PaginationParams & { type?: string }): Promise<V2List<V2Category>> {
+    return this.getList<V2Category>(this.sitePath(siteName, 'categories'), params);
+  }
+
+  async get(siteName: string, id: string): Promise<V2Category> {
+    return this.getOne<V2Category>(this.sitePath(siteName, 'categories', id));
+  }
+
+  async create(siteName: string, data: V2CategoryCreateParams): Promise<V2Category> {
+    return this.post<V2Category>(this.sitePath(siteName, 'categories'), data);
+  }
+
+  async update(siteName: string, id: string, data: V2CategoryUpdateParams): Promise<V2Category> {
+    return this.patchOne<V2Category>(this.sitePath(siteName, 'categories', id), data);
+  }
+
+  async del(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(this.sitePath(siteName, 'categories', id));
+  }
+}