perspectapi-ts-sdk 3.5.0 → 3.6.0

package/README.md

@@ -93,7 +93,7 @@ import { PerspectApiClient } from 'perspectapi-ts-sdk';
 import { myCacheAdapter } from './cache-adapter';
 
 const perspect = new PerspectApiClient({
-  baseUrl: 'https://api.perspect.co',
+  baseUrl: 'https://api.perspect.comm',
   apiKey: env.PERSPECT_API_KEY,
   cache: {
     adapter: myCacheAdapter,
@@ -148,7 +148,7 @@ export default {
 };
 ```
 
-When PerspectAPI sends a webhook—or when your Worker mutates data directly—call `perspect.cache.invalidate({ tags: [...] })` using the tags emitted by the SDK (`products:site:<site>`, `content:slug:<site>:<slug>`, `content:category:<site>:<category_slug>`, etc.) so stale entries are purged immediately.
+When PerspectAPI sends a webhook—or when your Worker mutates data directly—call `perspect.cache.invalidate({ tags: [...] })` using the tags emitted by the SDK (`products:site:<site>`, `content:slug:<site>:<slug>`, `newsletter:campaigns:slug:<site>:<slug>`, etc.) so stale entries are purged immediately.
 
 ### Webhook-driven cache invalidation
 
@@ -233,6 +233,34 @@ export default {
 ```
 
 > 🔁 Adjust the `WebhookEvent` union and `tagMap` to match the actual payloads you receive. PerspectAPI webhooks also carry version IDs and environment metadata that you can use for more granular targeting if needed.
+
+### Newsletter Publish Invalidation
+
+Newsletter list and campaign reads are cache-aware:
+
+```ts
+const campaigns = await perspect.newsletter.getPublishedCampaigns('museum-indian-art', {
+  page: 1,
+  limit: 20,
+});
+const campaign = await perspect.newsletter.getPublishedCampaignBySlug(
+  'museum-indian-art',
+  'spring-launch',
+  { slugPrefix: 'updates' }
+);
+```
+
+For webhook handling, use the newsletter helper so invalidation happens only when campaigns are published (not when drafts are created):
+
+```ts
+const result = await perspect.newsletter.invalidatePublishedCampaignCacheFromWebhook(
+  webhookPayload,
+  'museum-indian-art'
+);
+
+if (result.invalidated) {
+  console.log(result.tags);
+}
 ```
 
 ## Image Transformations
@@ -248,7 +276,7 @@ const media = product.data.media?.[0];
 
 if (media) {
   // Generate all responsive sizes automatically
-  const urls = transformMediaItem('https://api.perspect.co', media);
+  const urls = transformMediaItem('https://api.perspect.comm', media);
   
   console.log(urls.thumbnail);  // 150x150 cover crop
   console.log(urls.small);      // 400px wide
@@ -259,7 +287,7 @@ if (media) {
 
 // Or build custom transformations
 const customUrl = buildImageUrl(
-  'https://api.perspect.co',
+  'https://api.perspect.comm',
   'media/mysite/photo.jpg',
   {
     width: 400,

package/dist/index.d.mts

@@ -202,6 +202,34 @@ interface NewsletterList {
     is_default: boolean;
     subscriber_count?: number;
 }
+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;
+}
+interface NewsletterCampaignDetail extends NewsletterCampaignSummary {
+    markdown_content?: string | null;
+    html_content?: string | null;
+    text_content?: string | null;
+    excerpt?: string | null;
+}
+interface NewsletterCampaignListResponse {
+    items: NewsletterCampaignSummary[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        pages: number;
+    };
+}
 interface NewsletterPreferences {
     frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
     topics?: string[];
@@ -2043,10 +2071,33 @@ declare class NewsletterClient extends BaseClient {
     /**
      * Get available newsletter lists
      */
-    getLists(siteName: string): Promise<ApiResponse<{
+    getLists(siteName: string, cachePolicy?: CachePolicy): Promise<ApiResponse<{
         lists: NewsletterList[];
         total: number;
     }>>;
+    /**
+     * List publicly available (sent) newsletter campaigns
+     */
+    getPublishedCampaigns(siteName: string, params?: {
+        page?: number;
+        limit?: number;
+        search?: string;
+    }, cachePolicy?: CachePolicy): Promise<ApiResponse<NewsletterCampaignListResponse>>;
+    /**
+     * Fetch a publicly available (sent) newsletter campaign by slug
+     */
+    getPublishedCampaignBySlug(siteName: string, slug: string, optionsOrPolicy?: {
+        slugPrefix?: string;
+    } | CachePolicy, cachePolicy?: CachePolicy): Promise<ApiResponse<NewsletterCampaignDetail>>;
+    /**
+     * Invalidate cached published newsletter campaign data from a webhook payload.
+     * Only publish events (and legacy sent aliases) trigger invalidation.
+     */
+    invalidatePublishedCampaignCacheFromWebhook(payload: Record<string, unknown>, fallbackSiteName?: string): Promise<{
+        invalidated: boolean;
+        tags: string[];
+        reason?: string;
+    }>;
     /**
      * Check subscription status by email
      */
@@ -2221,6 +2272,12 @@ declare class NewsletterClient extends BaseClient {
      * Client sites can use this to serve the tracking pixel response.
      */
     static getTrackingPixel(): Uint8Array;
+    private buildNewsletterTags;
+    private extractSlugPrefix;
+    private normalizeNewsletterWebhookPayload;
+    private isPublishEvent;
+    private pickString;
+    private isCachePolicy;
 }
 
 /**
@@ -2416,6 +2473,15 @@ declare class SiteUsersClient extends BaseClient {
     changeSubscriptionPlan(siteName: string, subscriptionId: string, productId: number, csrfToken?: string): Promise<ApiResponse<{
         success: boolean;
     }>>;
+    /**
+     * Create a Stripe Billing Portal session for updating payment methods
+     * @param siteName - The site name
+     * @param returnUrl - URL to redirect back to after portal session
+     * @param csrfToken - CSRF token (required)
+     */
+    createBillingPortalSession(siteName: string, returnUrl: string, csrfToken?: string): Promise<ApiResponse<{
+        url: string;
+    }>>;
     /**
      * Get linked newsletter subscriptions
      * @param siteName - The site name
@@ -2769,7 +2835,7 @@ declare const DEFAULT_IMAGE_SIZES: ResponsiveImageSizes;
 /**
  * Build Cloudflare Image Resizing URL
  *
- * @param baseUrl - The base URL of your API (e.g., "https://api.perspect.co")
+ * @param baseUrl - The base URL of your API (e.g., "https://api.perspect.comm")
  * @param mediaPath - The path to the media file (e.g., "media/site/image.jpg")
  * @param options - Transform options
  * @returns Cloudflare Image Resizing URL
@@ -2777,11 +2843,11 @@ declare const DEFAULT_IMAGE_SIZES: ResponsiveImageSizes;
  * @example
  * ```typescript
  * const url = buildImageUrl(
- *   'https://api.perspect.co',
+ *   'https://api.perspect.comm',
  *   'media/mysite/photo.jpg',
  *   { width: 400, format: 'webp', quality: 85 }
  * );
- * // Returns: '/cdn-cgi/image/width=400,format=webp,quality=85/https://api.perspect.co/media/mysite/photo.jpg'
+ * // Returns: '/cdn-cgi/image/width=400,format=webp,quality=85/https://api.perspect.comm/media/mysite/photo.jpg'
  * ```
  */
 declare function buildImageUrl(baseUrl: string, mediaPath: string, options?: ImageTransformOptions): string;
@@ -2791,7 +2857,7 @@ declare function buildImageUrl(baseUrl: string, mediaPath: string, options?: Ima
  * @example
  * ```typescript
  * const urls = generateResponsiveUrls(
- *   'https://api.perspect.co',
+ *   'https://api.perspect.comm',
  *   'media/mysite/photo.jpg'
  * );
  * // Returns: { thumbnail: '...', small: '...', medium: '...', large: '...', original: '...' }
@@ -2804,7 +2870,7 @@ declare function generateResponsiveUrls(baseUrl: string, mediaPath: string, size
  * @example
  * ```typescript
  * const srcset = generateSrcSet(
- *   'https://api.perspect.co',
+ *   'https://api.perspect.comm',
  *   'media/mysite/photo.jpg',
  *   [400, 800, 1200]
  * );
@@ -2831,7 +2897,7 @@ declare function generateSizesAttribute(breakpoints?: Array<{
  * @example
  * ```typescript
  * const html = generateResponsiveImageHtml(
- *   'https://api.perspect.co',
+ *   'https://api.perspect.comm',
  *   'media/mysite/photo.jpg',
  *   'My photo',
  *   { className: 'rounded-lg', loading: 'lazy' }
@@ -2857,7 +2923,7 @@ declare function generateResponsiveImageHtml(baseUrl: string, mediaPath: string,
  * const media = product.data.media?.[0];
  *
  * if (media) {
- *   const urls = transformMediaItem('https://api.perspect.co', media);
+ *   const urls = transformMediaItem('https://api.perspect.comm', media);
  *   console.log(urls.thumbnail); // Cloudflare-transformed thumbnail URL
  * }
  * ```
@@ -3021,4 +3087,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type AddCollectionItemRequest, type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, BaseClient, type BlogPost, type BundleCollection, type BundleCollectionItem, type BundleCollectionItemWithProduct, BundlesClient, type CacheConfig, CacheManager, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateBundleCollectionRequest, type CreateBundleGroupRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, type CreditBalance, type CreditBalanceWithTransactions, type CreditTransaction, DEFAULT_IMAGE_SIZES, type GrantCreditRequest, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductBundleGroup, type ProductQueryParams, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type AddCollectionItemRequest, type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, BaseClient, type BlogPost, type BundleCollection, type BundleCollectionItem, type BundleCollectionItemWithProduct, BundlesClient, type CacheConfig, CacheManager, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateBundleCollectionRequest, type CreateBundleGroupRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, type CreditBalance, type CreditBalanceWithTransactions, type CreditTransaction, DEFAULT_IMAGE_SIZES, type GrantCreditRequest, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, type NewsletterCampaignDetail, type NewsletterCampaignListResponse, type NewsletterCampaignSummary, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductBundleGroup, type ProductQueryParams, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };

package/dist/index.d.ts

@@ -202,6 +202,34 @@ interface NewsletterList {
     is_default: boolean;
     subscriber_count?: number;
 }
+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;
+}
+interface NewsletterCampaignDetail extends NewsletterCampaignSummary {
+    markdown_content?: string | null;
+    html_content?: string | null;
+    text_content?: string | null;
+    excerpt?: string | null;
+}
+interface NewsletterCampaignListResponse {
+    items: NewsletterCampaignSummary[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        pages: number;
+    };
+}
 interface NewsletterPreferences {
     frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
     topics?: string[];
@@ -2043,10 +2071,33 @@ declare class NewsletterClient extends BaseClient {
     /**
      * Get available newsletter lists
      */
-    getLists(siteName: string): Promise<ApiResponse<{
+    getLists(siteName: string, cachePolicy?: CachePolicy): Promise<ApiResponse<{
         lists: NewsletterList[];
         total: number;
     }>>;
+    /**
+     * List publicly available (sent) newsletter campaigns
+     */
+    getPublishedCampaigns(siteName: string, params?: {
+        page?: number;
+        limit?: number;
+        search?: string;
+    }, cachePolicy?: CachePolicy): Promise<ApiResponse<NewsletterCampaignListResponse>>;
+    /**
+     * Fetch a publicly available (sent) newsletter campaign by slug
+     */
+    getPublishedCampaignBySlug(siteName: string, slug: string, optionsOrPolicy?: {
+        slugPrefix?: string;
+    } | CachePolicy, cachePolicy?: CachePolicy): Promise<ApiResponse<NewsletterCampaignDetail>>;
+    /**
+     * Invalidate cached published newsletter campaign data from a webhook payload.
+     * Only publish events (and legacy sent aliases) trigger invalidation.
+     */
+    invalidatePublishedCampaignCacheFromWebhook(payload: Record<string, unknown>, fallbackSiteName?: string): Promise<{
+        invalidated: boolean;
+        tags: string[];
+        reason?: string;
+    }>;
     /**
      * Check subscription status by email
      */
@@ -2221,6 +2272,12 @@ declare class NewsletterClient extends BaseClient {
      * Client sites can use this to serve the tracking pixel response.
      */
     static getTrackingPixel(): Uint8Array;
+    private buildNewsletterTags;
+    private extractSlugPrefix;
+    private normalizeNewsletterWebhookPayload;
+    private isPublishEvent;
+    private pickString;
+    private isCachePolicy;
 }
 
 /**
@@ -2416,6 +2473,15 @@ declare class SiteUsersClient extends BaseClient {
     changeSubscriptionPlan(siteName: string, subscriptionId: string, productId: number, csrfToken?: string): Promise<ApiResponse<{
         success: boolean;
     }>>;
+    /**
+     * Create a Stripe Billing Portal session for updating payment methods
+     * @param siteName - The site name
+     * @param returnUrl - URL to redirect back to after portal session
+     * @param csrfToken - CSRF token (required)
+     */
+    createBillingPortalSession(siteName: string, returnUrl: string, csrfToken?: string): Promise<ApiResponse<{
+        url: string;
+    }>>;
     /**
      * Get linked newsletter subscriptions
      * @param siteName - The site name
@@ -2769,7 +2835,7 @@ declare const DEFAULT_IMAGE_SIZES: ResponsiveImageSizes;
 /**
  * Build Cloudflare Image Resizing URL
  *
- * @param baseUrl - The base URL of your API (e.g., "https://api.perspect.co")
+ * @param baseUrl - The base URL of your API (e.g., "https://api.perspect.comm")
  * @param mediaPath - The path to the media file (e.g., "media/site/image.jpg")
  * @param options - Transform options
  * @returns Cloudflare Image Resizing URL
@@ -2777,11 +2843,11 @@ declare const DEFAULT_IMAGE_SIZES: ResponsiveImageSizes;
  * @example
  * ```typescript
  * const url = buildImageUrl(
- *   'https://api.perspect.co',
+ *   'https://api.perspect.comm',
  *   'media/mysite/photo.jpg',
  *   { width: 400, format: 'webp', quality: 85 }
  * );
- * // Returns: '/cdn-cgi/image/width=400,format=webp,quality=85/https://api.perspect.co/media/mysite/photo.jpg'
+ * // Returns: '/cdn-cgi/image/width=400,format=webp,quality=85/https://api.perspect.comm/media/mysite/photo.jpg'
  * ```
  */
 declare function buildImageUrl(baseUrl: string, mediaPath: string, options?: ImageTransformOptions): string;
@@ -2791,7 +2857,7 @@ declare function buildImageUrl(baseUrl: string, mediaPath: string, options?: Ima
  * @example
  * ```typescript
  * const urls = generateResponsiveUrls(
- *   'https://api.perspect.co',
+ *   'https://api.perspect.comm',
  *   'media/mysite/photo.jpg'
  * );
  * // Returns: { thumbnail: '...', small: '...', medium: '...', large: '...', original: '...' }
@@ -2804,7 +2870,7 @@ declare function generateResponsiveUrls(baseUrl: string, mediaPath: string, size
  * @example
  * ```typescript
  * const srcset = generateSrcSet(
- *   'https://api.perspect.co',
+ *   'https://api.perspect.comm',
  *   'media/mysite/photo.jpg',
  *   [400, 800, 1200]
  * );
@@ -2831,7 +2897,7 @@ declare function generateSizesAttribute(breakpoints?: Array<{
  * @example
  * ```typescript
  * const html = generateResponsiveImageHtml(
- *   'https://api.perspect.co',
+ *   'https://api.perspect.comm',
  *   'media/mysite/photo.jpg',
  *   'My photo',
  *   { className: 'rounded-lg', loading: 'lazy' }
@@ -2857,7 +2923,7 @@ declare function generateResponsiveImageHtml(baseUrl: string, mediaPath: string,
  * const media = product.data.media?.[0];
  *
  * if (media) {
- *   const urls = transformMediaItem('https://api.perspect.co', media);
+ *   const urls = transformMediaItem('https://api.perspect.comm', media);
  *   console.log(urls.thumbnail); // Cloudflare-transformed thumbnail URL
  * }
  * ```
@@ -3021,4 +3087,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type AddCollectionItemRequest, type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, BaseClient, type BlogPost, type BundleCollection, type BundleCollectionItem, type BundleCollectionItemWithProduct, BundlesClient, type CacheConfig, CacheManager, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateBundleCollectionRequest, type CreateBundleGroupRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, type CreditBalance, type CreditBalanceWithTransactions, type CreditTransaction, DEFAULT_IMAGE_SIZES, type GrantCreditRequest, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductBundleGroup, type ProductQueryParams, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type AddCollectionItemRequest, type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, BaseClient, type BlogPost, type BundleCollection, type BundleCollectionItem, type BundleCollectionItemWithProduct, BundlesClient, type CacheConfig, CacheManager, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateBundleCollectionRequest, type CreateBundleGroupRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, type CreditBalance, type CreditBalanceWithTransactions, type CreditTransaction, DEFAULT_IMAGE_SIZES, type GrantCreditRequest, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, type NewsletterCampaignDetail, type NewsletterCampaignListResponse, type NewsletterCampaignSummary, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductBundleGroup, type ProductQueryParams, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };

package/dist/index.js

@@ -2066,11 +2066,123 @@ var NewsletterClient = class extends BaseClient {
   /**
    * Get available newsletter lists
    */
-  async getLists(siteName) {
-    return this.getSingle(
-      this.newsletterEndpoint(siteName, "/newsletter/lists")
+  async getLists(siteName, cachePolicy) {
+    const endpoint = this.newsletterEndpoint(siteName, "/newsletter/lists");
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      void 0,
+      this.buildNewsletterTags(siteName, [
+        "newsletter:lists",
+        `newsletter:lists:site:${siteName}`
+      ]),
+      cachePolicy,
+      () => this.http.get(path)
     );
   }
+  /**
+   * List publicly available (sent) newsletter campaigns
+   */
+  async getPublishedCampaigns(siteName, params, cachePolicy) {
+    const endpoint = this.newsletterEndpoint(siteName, "/newsletter/campaigns");
+    const path = this.buildPath(endpoint);
+    const normalizedParams = params ? { ...params } : void 0;
+    if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        "newsletter campaigns query"
+      );
+      if (validatedLimit !== void 0) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+      if (typeof normalizedParams.search === "string" && normalizedParams.search.trim().length === 0) {
+        delete normalizedParams.search;
+      }
+    }
+    return this.fetchWithCache(
+      endpoint,
+      normalizedParams,
+      this.buildNewsletterTags(siteName, [
+        "newsletter:campaigns",
+        `newsletter:campaigns:list:${siteName}`
+      ]),
+      cachePolicy,
+      () => this.http.get(path, normalizedParams)
+    );
+  }
+  /**
+   * Fetch a publicly available (sent) newsletter campaign by slug
+   */
+  async getPublishedCampaignBySlug(siteName, slug, optionsOrPolicy, cachePolicy) {
+    let normalizedSlug = slug.trim();
+    if (!normalizedSlug) {
+      throw new Error("slug is required");
+    }
+    const isCachePolicyArg = this.isCachePolicy(optionsOrPolicy);
+    const providedSlugPrefix = !isCachePolicyArg && optionsOrPolicy ? this.pickString(optionsOrPolicy, ["slugPrefix", "slug_prefix"]) : void 0;
+    const resolvedCachePolicy = isCachePolicyArg ? optionsOrPolicy : 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 } : void 0;
+    return this.fetchWithCache(
+      endpoint,
+      queryParams,
+      this.buildNewsletterTags(
+        siteName,
+        [
+          "newsletter:campaigns",
+          `newsletter:campaigns:slug:${siteName}:${normalizedSlug}`,
+          `newsletter:campaigns:detail:${siteName}`
+        ],
+        slugPrefix
+      ),
+      resolvedCachePolicy,
+      () => this.http.get(path, queryParams)
+    );
+  }
+  /**
+   * Invalidate cached published newsletter campaign data from a webhook payload.
+   * Only publish events (and legacy sent aliases) trigger invalidation.
+   */
+  async invalidatePublishedCampaignCacheFromWebhook(payload, fallbackSiteName) {
+    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
    */
@@ -2266,6 +2378,107 @@ var NewsletterClient = class extends BaseClient {
       59
     ]);
   }
+  buildNewsletterTags(siteName, extraTags = [], slugPrefix) {
+    const tags = /* @__PURE__ */ new Set(["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());
+  }
+  extractSlugPrefix(slug) {
+    const normalized = slug.trim();
+    if (!normalized.includes("/")) {
+      return void 0;
+    }
+    const [prefix] = normalized.split("/").filter(Boolean);
+    return prefix || void 0;
+  }
+  normalizeNewsletterWebhookPayload(payload, fallbackSiteName) {
+    const eventType = (this.pickString(payload, ["event_type", "type"]) || "").toLowerCase();
+    const dataRaw = payload.data;
+    const data = dataRaw && typeof dataRaw === "object" && !Array.isArray(dataRaw) ? dataRaw : 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"]) || void 0;
+    let slugPrefix = this.pickString(data, ["slug_prefix", "slugPrefix"]) || this.pickString(payload, ["slug_prefix", "slugPrefix"]) || (slug ? this.extractSlugPrefix(slug) : void 0);
+    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"]) || void 0;
+    return {
+      shouldInvalidate: true,
+      siteName,
+      slug,
+      slugPrefix,
+      campaignId
+    };
+  }
+  isPublishEvent(eventType, status, originType) {
+    const knownPublishEvents = /* @__PURE__ */ 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;
+    }
+    if (eventType === "content.published" && originType === "newsletter_campaign") {
+      return true;
+    }
+    if ((eventType.includes("newsletter") || eventType.includes("campaign")) && eventType.endsWith(".updated") && (status === "published" || status === "sent")) {
+      return true;
+    }
+    return false;
+  }
+  pickString(source, keys) {
+    if (!source) {
+      return void 0;
+    }
+    for (const key of keys) {
+      const value = source[key];
+      if (typeof value === "string" && value.trim().length > 0) {
+        return value.trim();
+      }
+    }
+    return void 0;
+  }
+  isCachePolicy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const record = value;
+    return "ttlSeconds" in record || "tags" in record || "metadata" in record || "skipCache" in record;
+  }
 };
 
 // src/client/site-users-client.ts
@@ -2529,6 +2742,19 @@ var SiteUsersClient = class extends BaseClient {
       csrfToken
     );
   }
+  /**
+   * Create a Stripe Billing Portal session for updating payment methods
+   * @param siteName - The site name
+   * @param returnUrl - URL to redirect back to after portal session
+   * @param csrfToken - CSRF token (required)
+   */
+  async createBillingPortalSession(siteName, returnUrl, csrfToken) {
+    return this.create(
+      this.siteUserEndpoint(siteName, "/users/me/billing-portal"),
+      { return_url: returnUrl },
+      csrfToken
+    );
+  }
   /**
    * Get linked newsletter subscriptions
    * @param siteName - The site name