perspectapi-ts-sdk 3.6.0 → 4.1.0

package/src/client/products-client.ts

@@ -8,6 +8,8 @@ import type { CachePolicy } from '../cache/types';
 import type {
   Product,
   CreateProductRequest,
+  CreateProductSkuRequest,
+  ProductSku,
   PaginatedResponse,
   ApiResponse,
   ProductQueryParams,
@@ -457,17 +459,7 @@ export class ProductsClient extends BaseClient {
   async getProductSkus(
     siteName: string,
     productId: number
-  ): Promise<ApiResponse<Array<{
-    sku_id: number;
-    sku: string;
-    price?: number;
-    sale_price?: number;
-    stock_quantity?: number;
-    combination_key: string;
-    value_ids: number[];
-    created_at: string;
-    updated_at: string;
-  }>>> {
+  ): Promise<ApiResponse<ProductSku[]>> {
     const endpoint = this.siteScopedEndpoint(
       siteName,
       `/products/${productId}/skus`,
@@ -482,26 +474,66 @@ export class ProductsClient extends BaseClient {
   async createProductSku(
     siteName: string,
     productId: number,
-    data: {
-      sku: string;
-      price?: number | null;
-      sale_price?: number | null;
-      stock_quantity?: number | null;
-      value_ids: number[];
-    }
-  ): Promise<ApiResponse<{
-    sku_id: number;
-    sku: string;
-    price?: number;
-    sale_price?: number;
-    stock_quantity?: number;
-    combination_key: string;
-  }>> {
+    data: CreateProductSkuRequest
+  ): Promise<ApiResponse<ProductSku>> {
     const endpoint = this.siteScopedEndpoint(
       siteName,
       `/products/${productId}/skus`,
       { includeSitesSegment: false }
     );
-    return this.create(endpoint, data);
+
+    const unitAmountCandidate =
+      typeof data.unit_amount === 'number'
+        ? data.unit_amount
+        : typeof data.price === 'number'
+          ? Math.round(data.price * 100)
+          : undefined;
+
+    if (typeof unitAmountCandidate !== 'number' || !Number.isFinite(unitAmountCandidate)) {
+      throw new Error('createProductSku requires unit_amount or price');
+    }
+    const unitAmount = unitAmountCandidate;
+
+    const quantityAvailable =
+      data.quantity_available !== undefined
+        ? data.quantity_available
+        : (data.stock_quantity ?? null);
+
+    const payload: {
+      sku: string | null;
+      media_id?: string | null;
+      unit_amount: number;
+      currency: string;
+      quantity_available: number | null;
+      published?: boolean;
+      gateway_price_id_test?: string | null;
+      gateway_price_id_live?: string | null;
+      value_ids: number[];
+    } = {
+      sku: data.sku ?? null,
+      unit_amount: unitAmount,
+      currency: data.currency || 'usd',
+      quantity_available: quantityAvailable,
+      published: data.published,
+      gateway_price_id_test: data.gateway_price_id_test,
+      gateway_price_id_live: data.gateway_price_id_live,
+      value_ids: data.value_ids,
+    };
+
+    if (Object.prototype.hasOwnProperty.call(data, 'media_id')) {
+      if (data.media_id === null) {
+        payload.media_id = null;
+      } else if (typeof data.media_id === 'string') {
+        const trimmed = data.media_id.trim();
+        if (!trimmed) {
+          throw new Error('createProductSku media_id cannot be empty');
+        }
+        payload.media_id = trimmed;
+      } else if (data.media_id !== undefined) {
+        throw new Error('createProductSku media_id must be a string or null');
+      }
+    }
+
+    return this.create(endpoint, payload);
   }
 }

package/src/index.ts

@@ -19,6 +19,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 +110,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';
@@ -320,6 +583,49 @@ export interface MediaItem {
   site_name: string;
 }
 
+export interface ProductSkuMediaItem {
+  id?: string;
+  media_id: string;
+  file_name?: string;
+  fileName?: string;
+  link?: string;
+  url?: string;
+  content_type?: string;
+  contentType?: string;
+  width?: number;
+  height?: number;
+  filesize?: number;
+  r2_key?: string;
+  site_name?: string;
+}
+
+export interface ProductSkuOption {
+  name: string;
+  key: string;
+  value: string;
+  label: string;
+  value_id: number;
+}
+
+export interface ProductSku {
+  sku_id: number;
+  sku?: string | null;
+  combination_key: string;
+  media_id?: string | null;
+  media?: ProductSkuMediaItem | null;
+  options?: ProductSkuOption[];
+  unit_amount?: number;
+  currency?: string;
+  quantity_available?: number | null;
+  price?: number;
+  sale_price?: number;
+  stock_quantity?: number;
+  value_ids: number[];
+  created_at?: string;
+  updated_at?: string;
+  [key: string]: any;
+}
+
 export interface Product {
   id: number | string;
   name?: string;
@@ -333,6 +639,7 @@ export interface Product {
   slug_prefix?: string;
   image?: string;
   media?: MediaItem[] | MediaItem[][];
+  skus?: ProductSku[];
   isActive?: boolean;
   organizationId?: number;
   createdAt?: string;
@@ -362,6 +669,21 @@ export interface CreateProductRequest {
   isActive?: boolean;
 }
 
+export interface CreateProductSkuRequest {
+  sku?: string | null;
+  media_id?: string | null;
+  unit_amount?: number;
+  currency?: string;
+  quantity_available?: number | null;
+  price?: number | null;
+  stock_quantity?: number | null;
+  sale_price?: number | null;
+  published?: boolean;
+  gateway_price_id_test?: string | null;
+  gateway_price_id_live?: string | null;
+  value_ids: number[];
+}
+
 export interface ProductQueryParams extends PaginationParams {
   organizationId?: number;
   isActive?: boolean;