perspectapi-ts-sdk 3.5.1 → 3.6.0

package/README.md

@@ -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

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;
 }
 
 /**
@@ -3030,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;
 }
 
 /**
@@ -3030,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

package/dist/index.mjs

@@ -2003,11 +2003,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
    */
@@ -2203,6 +2315,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

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/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[];