perspectapi-ts-sdk 3.5.1 → 3.7.0

package/src/client/newsletter-client.ts

@@ -4,10 +4,13 @@
 
 import { BaseClient } from './base-client';
 import type { CacheManager } from '../cache/cache-manager';
+import type { CachePolicy } from '../cache/types';
 import type {
   NewsletterSubscription,
   CreateNewsletterSubscriptionRequest,
   NewsletterList,
+  NewsletterCampaignDetail,
+  NewsletterCampaignListResponse,
   NewsletterPreferences,
   NewsletterStatusResponse,
   NewsletterSubscribeResponse,
@@ -17,6 +20,7 @@ import type {
   PaginatedResponse,
   ApiResponse,
 } from '../types';
+import { validateOptionalLimit } from '../utils/validators';
 
 export class NewsletterClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
@@ -119,15 +123,174 @@ export class NewsletterClient extends BaseClient {
   /**
    * Get available newsletter lists
    */
-  async getLists(siteName: string): Promise<ApiResponse<{
+  async getLists(
+    siteName: string,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<{
     lists: NewsletterList[];
     total: number;
   }>> {
-    return this.getSingle(
-      this.newsletterEndpoint(siteName, '/newsletter/lists')
+    const endpoint = this.newsletterEndpoint(siteName, '/newsletter/lists');
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<{
+      lists: NewsletterList[];
+      total: number;
+    }>>(
+      endpoint,
+      undefined,
+      this.buildNewsletterTags(siteName, [
+        'newsletter:lists',
+        `newsletter:lists:site:${siteName}`,
+      ]),
+      cachePolicy,
+      () => this.http.get(path)
+    );
+  }
+
+  /**
+   * List publicly available (sent) newsletter campaigns
+   */
+  async getPublishedCampaigns(
+    siteName: string,
+    params?: {
+      page?: number;
+      limit?: number;
+      search?: string;
+    },
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<NewsletterCampaignListResponse>> {
+    const endpoint = this.newsletterEndpoint(siteName, '/newsletter/campaigns');
+    const path = this.buildPath(endpoint);
+    const normalizedParams = params ? { ...params } : undefined;
+
+    if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        'newsletter campaigns query',
+      );
+      if (validatedLimit !== undefined) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+
+      if (
+        typeof normalizedParams.search === 'string' &&
+        normalizedParams.search.trim().length === 0
+      ) {
+        delete normalizedParams.search;
+      }
+    }
+
+    return this.fetchWithCache<ApiResponse<NewsletterCampaignListResponse>>(
+      endpoint,
+      normalizedParams,
+      this.buildNewsletterTags(siteName, [
+        'newsletter:campaigns',
+        `newsletter:campaigns:list:${siteName}`,
+      ]),
+      cachePolicy,
+      () => this.http.get<NewsletterCampaignListResponse>(path, normalizedParams)
+    );
+  }
+
+  /**
+   * Fetch a publicly available (sent) newsletter campaign by slug
+   */
+  async getPublishedCampaignBySlug(
+    siteName: string,
+    slug: string,
+    optionsOrPolicy?: { slugPrefix?: string } | CachePolicy,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<NewsletterCampaignDetail>> {
+    let normalizedSlug = slug.trim();
+    if (!normalizedSlug) {
+      throw new Error('slug is required');
+    }
+
+    const isCachePolicyArg = this.isCachePolicy(optionsOrPolicy);
+    const providedSlugPrefix =
+      !isCachePolicyArg && optionsOrPolicy
+        ? this.pickString(optionsOrPolicy as Record<string, unknown>, ['slugPrefix', 'slug_prefix'])
+        : undefined;
+    const resolvedCachePolicy = isCachePolicyArg
+      ? (optionsOrPolicy as CachePolicy)
+      : cachePolicy;
+
+    let slugPrefix = providedSlugPrefix;
+    if (!slugPrefix) {
+      const parts = normalizedSlug.split('/').filter(Boolean);
+      if (parts.length > 1) {
+        slugPrefix = parts.slice(0, -1).join('/');
+        normalizedSlug = parts[parts.length - 1];
+      }
+    }
+    normalizedSlug = normalizedSlug.trim();
+    if (!normalizedSlug) {
+      throw new Error('slug is required');
+    }
+
+    const endpoint = this.newsletterEndpoint(
+      siteName,
+      `/newsletter/campaigns/${encodeURIComponent(normalizedSlug)}`
+    );
+    const path = this.buildPath(endpoint);
+    const queryParams = slugPrefix ? { slug_prefix: slugPrefix } : undefined;
+
+    return this.fetchWithCache<ApiResponse<NewsletterCampaignDetail>>(
+      endpoint,
+      queryParams,
+      this.buildNewsletterTags(
+        siteName,
+        [
+          'newsletter:campaigns',
+          `newsletter:campaigns:slug:${siteName}:${normalizedSlug}`,
+          `newsletter:campaigns:detail:${siteName}`,
+        ],
+        slugPrefix
+      ),
+      resolvedCachePolicy,
+      () => this.http.get<NewsletterCampaignDetail>(path, queryParams)
     );
   }
 
+  /**
+   * Invalidate cached published newsletter campaign data from a webhook payload.
+   * Only publish events (and legacy sent aliases) trigger invalidation.
+   */
+  async invalidatePublishedCampaignCacheFromWebhook(
+    payload: Record<string, unknown>,
+    fallbackSiteName?: string,
+  ): Promise<{ invalidated: boolean; tags: string[]; reason?: string }> {
+    const normalized = this.normalizeNewsletterWebhookPayload(payload, fallbackSiteName);
+    if (!normalized.shouldInvalidate) {
+      return {
+        invalidated: false,
+        tags: [],
+        reason: normalized.reason || 'event_not_publish_related',
+      };
+    }
+
+    const tags = this.buildNewsletterTags(
+      normalized.siteName,
+      [
+        'newsletter:campaigns',
+        `newsletter:campaigns:list:${normalized.siteName}`,
+        normalized.slug
+          ? `newsletter:campaigns:slug:${normalized.siteName}:${normalized.slug}`
+          : '',
+        normalized.campaignId
+          ? `newsletter:campaigns:id:${normalized.siteName}:${normalized.campaignId}`
+          : '',
+      ],
+      normalized.slugPrefix,
+    );
+
+    await this.invalidateCache({ tags });
+    return { invalidated: true, tags };
+  }
+
   /**
    * Check subscription status by email
    */
@@ -432,4 +595,181 @@ export class NewsletterClient extends BaseClient {
       0x44, 0x01, 0x00, 0x3b,
     ]);
   }
+
+  private buildNewsletterTags(
+    siteName?: string,
+    extraTags: string[] = [],
+    slugPrefix?: string
+  ): string[] {
+    const tags = new Set<string>(['newsletter']);
+    if (siteName) {
+      tags.add(`newsletter:site:${siteName}`);
+    }
+    if (slugPrefix) {
+      tags.add(`newsletter:prefix:${slugPrefix}`);
+    }
+    extraTags.filter(Boolean).forEach(tag => tags.add(tag));
+    return Array.from(tags.values());
+  }
+
+  private extractSlugPrefix(slug: string): string | undefined {
+    const normalized = slug.trim();
+    if (!normalized.includes('/')) {
+      return undefined;
+    }
+    const [prefix] = normalized.split('/').filter(Boolean);
+    return prefix || undefined;
+  }
+
+  private normalizeNewsletterWebhookPayload(
+    payload: Record<string, unknown>,
+    fallbackSiteName?: string
+  ): {
+    shouldInvalidate: boolean;
+    reason?: string;
+    siteName: string;
+    slug?: string;
+    slugPrefix?: string;
+    campaignId?: string;
+  } {
+    const eventType = (
+      this.pickString(payload, ['event_type', 'type']) || ''
+    ).toLowerCase();
+
+    const dataRaw = payload.data;
+    const data = (dataRaw && typeof dataRaw === 'object' && !Array.isArray(dataRaw))
+      ? (dataRaw as Record<string, unknown>)
+      : payload;
+
+    const originType = (
+      this.pickString(data, ['origin_type', 'originType']) || ''
+    ).toLowerCase();
+    const status = (
+      this.pickString(data, ['status', 'campaign_status', 'campaignStatus']) || ''
+    ).toLowerCase();
+
+    if (!this.isPublishEvent(eventType, status, originType)) {
+      return {
+        shouldInvalidate: false,
+        reason: 'not_publish_or_sent_event',
+        siteName: fallbackSiteName || '',
+      };
+    }
+
+    const siteName =
+      this.pickString(payload, ['site', 'site_name', 'siteName']) ||
+      this.pickString(data, ['site', 'site_name', 'siteName']) ||
+      fallbackSiteName ||
+      '';
+
+    if (!siteName) {
+      return {
+        shouldInvalidate: false,
+        reason: 'missing_site_name',
+        siteName: '',
+      };
+    }
+
+    let slug =
+      this.pickString(data, ['slug', 'canonical_slug', 'canonicalSlug']) ||
+      this.pickString(payload, ['slug', 'canonical_slug', 'canonicalSlug']) ||
+      undefined;
+
+    let slugPrefix =
+      this.pickString(data, ['slug_prefix', 'slugPrefix']) ||
+      this.pickString(payload, ['slug_prefix', 'slugPrefix']) ||
+      (slug ? this.extractSlugPrefix(slug) : undefined);
+
+    if (slug) {
+      const slugParts = slug.split('/').filter(Boolean);
+      if (slugParts.length > 1) {
+        if (!slugPrefix) {
+          slugPrefix = slugParts.slice(0, -1).join('/');
+        }
+        slug = slugParts[slugParts.length - 1];
+      }
+    }
+
+    const campaignId =
+      this.pickString(data, ['campaign_id', 'campaignId']) ||
+      this.pickString(payload, ['campaign_id', 'campaignId']) ||
+      undefined;
+
+    return {
+      shouldInvalidate: true,
+      siteName,
+      slug,
+      slugPrefix,
+      campaignId,
+    };
+  }
+
+  private isPublishEvent(
+    eventType: string,
+    status: string,
+    originType: string
+  ): boolean {
+    const knownPublishEvents = new Set([
+      'newsletter.published',
+      'newsletter.sent',
+      'newsletter_campaign.published',
+      'newsletter_campaign.sent',
+      'newsletter.campaign.published',
+      'newsletter.campaign.sent',
+      'campaign.published',
+      'campaign.sent',
+    ]);
+
+    if (knownPublishEvents.has(eventType)) {
+      return true;
+    }
+
+    // Content webhook event for unified newsletter campaign content.
+    if (eventType === 'content.published' && originType === 'newsletter_campaign') {
+      return true;
+    }
+
+    // Some systems emit update events with final status.
+    if (
+      (eventType.includes('newsletter') || eventType.includes('campaign')) &&
+      eventType.endsWith('.updated') &&
+      (status === 'published' || status === 'sent')
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  private pickString(
+    source: Record<string, unknown> | undefined,
+    keys: string[]
+  ): string | undefined {
+    if (!source) {
+      return undefined;
+    }
+
+    for (const key of keys) {
+      const value = source[key];
+      if (typeof value === 'string' && value.trim().length > 0) {
+        return value.trim();
+      }
+    }
+
+    return undefined;
+  }
+
+  private isCachePolicy(value: unknown): value is CachePolicy {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return false;
+    }
+
+    const record = value as Record<string, unknown>;
+    return (
+      'ttlSeconds' in record ||
+      'tags' in record ||
+      'metadata' in record ||
+      'skipCache' in record
+    );
+  }
 }

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

@@ -100,6 +100,9 @@ export type {
   NewsletterSubscription,
   CreateNewsletterSubscriptionRequest,
   NewsletterList,
+  NewsletterCampaignSummary,
+  NewsletterCampaignDetail,
+  NewsletterCampaignListResponse,
   NewsletterPreferences,
   NewsletterStatusResponse,
   NewsletterSubscribeResponse,

package/src/types/index.ts

@@ -141,6 +141,37 @@ export interface NewsletterList {
   subscriber_count?: number;
 }
 
+export interface NewsletterCampaignSummary {
+  id: string;
+  campaign_name: string;
+  slug: string;
+  slug_prefix?: string | null;
+  subject: string;
+  preview_text?: string | null;
+  status: string;
+  sent_at?: string | null;
+  completed_at?: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface NewsletterCampaignDetail extends NewsletterCampaignSummary {
+  markdown_content?: string | null;
+  html_content?: string | null;
+  text_content?: string | null;
+  excerpt?: string | null;
+}
+
+export interface NewsletterCampaignListResponse {
+  items: NewsletterCampaignSummary[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    pages: number;
+  };
+}
+
 export interface NewsletterPreferences {
   frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
   topics?: string[];
@@ -289,6 +320,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;
@@ -302,6 +376,7 @@ export interface Product {
   slug_prefix?: string;
   image?: string;
   media?: MediaItem[] | MediaItem[][];
+  skus?: ProductSku[];
   isActive?: boolean;
   organizationId?: number;
   createdAt?: string;
@@ -331,6 +406,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;