perspectapi-ts-sdk 3.5.0 → 3.6.0

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
@@ -2466,6 +2679,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "3.5.0",
+  "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/client/site-users-client.ts

@@ -355,6 +355,24 @@ export class SiteUsersClient extends BaseClient {
     );
   }
 
+  /**
+   * 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: string,
+    returnUrl: string,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ url: string }>> {
+    return this.create<{ return_url: string }, { url: string }>(
+      this.siteUserEndpoint(siteName, '/users/me/billing-portal'),
+      { return_url: returnUrl },
+      csrfToken
+    );
+  }
+
   /**
    * Get linked newsletter subscriptions
    * @param siteName - The site name

package/src/index.ts

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