perspectapi-ts-sdk 3.5.1 → 3.7.0

package/dist/index.js

@@ -1553,7 +1553,36 @@ var ProductsClient = class extends BaseClient {
       `/products/${productId}/skus`,
       { includeSitesSegment: false }
     );
-    return this.create(endpoint, data);
+    const unitAmountCandidate = typeof data.unit_amount === "number" ? data.unit_amount : typeof data.price === "number" ? Math.round(data.price * 100) : void 0;
+    if (typeof unitAmountCandidate !== "number" || !Number.isFinite(unitAmountCandidate)) {
+      throw new Error("createProductSku requires unit_amount or price");
+    }
+    const unitAmount = unitAmountCandidate;
+    const quantityAvailable = data.quantity_available !== void 0 ? data.quantity_available : data.stock_quantity ?? null;
+    const payload = {
+      sku: data.sku ?? null,
+      unit_amount: unitAmount,
+      currency: data.currency || "usd",
+      quantity_available: quantityAvailable,
+      published: data.published,
+      gateway_price_id_test: data.gateway_price_id_test,
+      gateway_price_id_live: data.gateway_price_id_live,
+      value_ids: data.value_ids
+    };
+    if (Object.prototype.hasOwnProperty.call(data, "media_id")) {
+      if (data.media_id === null) {
+        payload.media_id = null;
+      } else if (typeof data.media_id === "string") {
+        const trimmed = data.media_id.trim();
+        if (!trimmed) {
+          throw new Error("createProductSku media_id cannot be empty");
+        }
+        payload.media_id = trimmed;
+      } else if (data.media_id !== void 0) {
+        throw new Error("createProductSku media_id must be a string or null");
+      }
+    }
+    return this.create(endpoint, payload);
   }
 };
 
@@ -2066,11 +2095,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 +2407,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

@@ -1490,7 +1490,36 @@ var ProductsClient = class extends BaseClient {
       `/products/${productId}/skus`,
       { includeSitesSegment: false }
     );
-    return this.create(endpoint, data);
+    const unitAmountCandidate = typeof data.unit_amount === "number" ? data.unit_amount : typeof data.price === "number" ? Math.round(data.price * 100) : void 0;
+    if (typeof unitAmountCandidate !== "number" || !Number.isFinite(unitAmountCandidate)) {
+      throw new Error("createProductSku requires unit_amount or price");
+    }
+    const unitAmount = unitAmountCandidate;
+    const quantityAvailable = data.quantity_available !== void 0 ? data.quantity_available : data.stock_quantity ?? null;
+    const payload = {
+      sku: data.sku ?? null,
+      unit_amount: unitAmount,
+      currency: data.currency || "usd",
+      quantity_available: quantityAvailable,
+      published: data.published,
+      gateway_price_id_test: data.gateway_price_id_test,
+      gateway_price_id_live: data.gateway_price_id_live,
+      value_ids: data.value_ids
+    };
+    if (Object.prototype.hasOwnProperty.call(data, "media_id")) {
+      if (data.media_id === null) {
+        payload.media_id = null;
+      } else if (typeof data.media_id === "string") {
+        const trimmed = data.media_id.trim();
+        if (!trimmed) {
+          throw new Error("createProductSku media_id cannot be empty");
+        }
+        payload.media_id = trimmed;
+      } else if (data.media_id !== void 0) {
+        throw new Error("createProductSku media_id must be a string or null");
+      }
+    }
+    return this.create(endpoint, payload);
   }
 };
 
@@ -2003,11 +2032,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 +2344,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.7.0",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",