perspectapi-ts-sdk 1.5.2 → 2.0.0

package/dist/index.mjs

@@ -205,13 +205,273 @@ function createApiError(error) {
   };
 }
 
+// src/cache/in-memory-adapter.ts
+var InMemoryCacheAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (entry.expiresAt && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async set(key, value, options) {
+    const expiresAt = options?.ttlSeconds && options.ttlSeconds > 0 ? Date.now() + options.ttlSeconds * 1e3 : void 0;
+    this.store.set(key, { value, expiresAt });
+  }
+  async delete(key) {
+    this.store.delete(key);
+  }
+  async deleteMany(keys) {
+    keys.forEach((key) => this.store.delete(key));
+  }
+  async clear() {
+    this.store.clear();
+  }
+};
+
+// src/cache/noop-adapter.ts
+var NoopCacheAdapter = class {
+  async get() {
+    return void 0;
+  }
+  async set() {
+  }
+  async delete() {
+  }
+  async deleteMany() {
+  }
+  async clear() {
+  }
+};
+
+// src/cache/cache-manager.ts
+var TAG_PREFIX = "__tag__";
+var CacheManager = class {
+  adapter;
+  defaultTtlSeconds;
+  keyPrefix;
+  enabled;
+  constructor(config) {
+    const defaultOptions = {
+      defaultTtlSeconds: 300,
+      keyPrefix: "perspectapi"
+    };
+    const mergedConfig = {
+      ...defaultOptions,
+      ...config
+    };
+    if (config && config.enabled === false) {
+      this.enabled = false;
+      this.adapter = new NoopCacheAdapter();
+    } else if (config && config.adapter) {
+      this.enabled = true;
+      this.adapter = config.adapter;
+    } else if (config) {
+      this.enabled = true;
+      this.adapter = new InMemoryCacheAdapter();
+    } else {
+      this.enabled = false;
+      this.adapter = new NoopCacheAdapter();
+    }
+    this.defaultTtlSeconds = mergedConfig.defaultTtlSeconds ?? 300;
+    this.keyPrefix = mergedConfig.keyPrefix ?? "perspectapi";
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  getKeyPrefix() {
+    return this.keyPrefix;
+  }
+  buildKey(parts) {
+    const normalized = parts.flatMap((part) => this.normalizeKeyPart(part)).filter((part) => part !== void 0 && part !== null && part !== "");
+    return normalized.join(":");
+  }
+  async getOrSet(key, resolveValue, policy) {
+    if (!this.enabled || policy?.skipCache) {
+      const value2 = await resolveValue();
+      if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
+        await this.set(key, value2, policy);
+      }
+      return value2;
+    }
+    const namespacedKey = this.namespacedKey(key);
+    const cachedRaw = await this.adapter.get(namespacedKey);
+    if (cachedRaw) {
+      const entry = this.deserialize(cachedRaw);
+      if (!entry.expiresAt || entry.expiresAt > Date.now()) {
+        return entry.value;
+      }
+      await this.adapter.delete(namespacedKey);
+      if (entry.tags?.length) {
+        await this.removeKeyFromTags(namespacedKey, entry.tags);
+      }
+    }
+    const value = await resolveValue();
+    await this.set(key, value, policy);
+    return value;
+  }
+  async set(key, value, options) {
+    if (!this.enabled || options?.ttlSeconds === 0) {
+      return;
+    }
+    const namespacedKey = this.namespacedKey(key);
+    const ttlSeconds = options?.ttlSeconds ?? this.defaultTtlSeconds;
+    const entry = {
+      value,
+      expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1e3 : void 0,
+      tags: options?.tags,
+      metadata: options?.metadata
+    };
+    await this.adapter.set(namespacedKey, this.serialize(entry), {
+      ttlSeconds: ttlSeconds > 0 ? ttlSeconds : void 0
+    });
+    if (options?.tags?.length) {
+      await this.registerKeyTags(namespacedKey, options.tags);
+    }
+  }
+  async delete(key) {
+    if (!this.enabled) {
+      return;
+    }
+    const namespacedKey = this.namespacedKey(key);
+    await this.adapter.delete(namespacedKey);
+  }
+  async invalidate(options) {
+    if (!this.enabled) {
+      return;
+    }
+    if (options.keys?.length) {
+      const namespacedKeys = options.keys.map((key) => this.namespacedKey(key));
+      if (this.adapter.deleteMany) {
+        await this.adapter.deleteMany(namespacedKeys);
+      } else {
+        await Promise.all(namespacedKeys.map((key) => this.adapter.delete(key)));
+      }
+    }
+    if (options.tags?.length) {
+      await Promise.all(
+        options.tags.map(async (tag) => {
+          const tagKey = this.tagKey(tag);
+          const payload = await this.adapter.get(tagKey);
+          if (!payload) {
+            return;
+          }
+          const keys = this.deserializeTagSet(payload);
+          if (keys.length) {
+            if (this.adapter.deleteMany) {
+              await this.adapter.deleteMany(keys);
+            } else {
+              await Promise.all(keys.map((key) => this.adapter.delete(key)));
+            }
+          }
+          await this.adapter.delete(tagKey);
+        })
+      );
+    }
+  }
+  namespacedKey(key) {
+    return `${this.keyPrefix}:${key}`;
+  }
+  tagKey(tag) {
+    return this.namespacedKey(`${TAG_PREFIX}:${tag}`);
+  }
+  serialize(entry) {
+    return JSON.stringify(entry);
+  }
+  deserialize(payload) {
+    try {
+      return JSON.parse(payload);
+    } catch {
+      return { value: payload };
+    }
+  }
+  deserializeTagSet(payload) {
+    try {
+      const parsed = JSON.parse(payload);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+  async registerKeyTags(namespacedKey, tags) {
+    await Promise.all(
+      tags.map(async (tag) => {
+        const tagKey = this.tagKey(tag);
+        const existingPayload = await this.adapter.get(tagKey);
+        const keys = existingPayload ? this.deserializeTagSet(existingPayload) : [];
+        if (!keys.includes(namespacedKey)) {
+          keys.push(namespacedKey);
+          await this.adapter.set(tagKey, JSON.stringify(keys));
+        }
+      })
+    );
+  }
+  async removeKeyFromTags(namespacedKey, tags) {
+    await Promise.all(
+      tags.map(async (tag) => {
+        const tagKey = this.tagKey(tag);
+        const existingPayload = await this.adapter.get(tagKey);
+        if (!existingPayload) {
+          return;
+        }
+        const keys = this.deserializeTagSet(existingPayload);
+        const updated = keys.filter((key) => key !== namespacedKey);
+        if (updated.length === 0) {
+          await this.adapter.delete(tagKey);
+        } else if (updated.length !== keys.length) {
+          await this.adapter.set(tagKey, JSON.stringify(updated));
+        }
+      })
+    );
+  }
+  normalizeKeyPart(part) {
+    if (part === void 0 || part === null || part === "") {
+      return [];
+    }
+    if (Array.isArray(part)) {
+      return part.flatMap((item) => this.normalizeKeyPart(item));
+    }
+    if (typeof part === "object") {
+      return [this.normalizeObject(part)];
+    }
+    return [String(part)];
+  }
+  normalizeObject(input) {
+    const sortedKeys = Object.keys(input).sort();
+    const normalized = {};
+    for (const key of sortedKeys) {
+      const value = input[key];
+      if (value === void 0) {
+        continue;
+      }
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        normalized[key] = JSON.parse(this.normalizeObject(value));
+      } else if (Array.isArray(value)) {
+        normalized[key] = value.map(
+          (item) => typeof item === "object" && item !== null ? JSON.parse(this.normalizeObject(item)) : item
+        );
+      } else {
+        normalized[key] = value;
+      }
+    }
+    return JSON.stringify(normalized);
+  }
+};
+
 // src/client/base-client.ts
 var BaseClient = class {
   http;
   basePath;
-  constructor(http, basePath) {
+  cache;
+  constructor(http, basePath, cache) {
     this.http = http;
     this.basePath = basePath;
+    this.cache = cache && cache.isEnabled() ? cache : void 0;
   }
   /**
    * Build a site-scoped endpoint relative to the API base path
@@ -271,12 +531,71 @@ var BaseClient = class {
   async delete(endpoint, csrfToken) {
     return this.http.delete(this.buildPath(endpoint), { csrfToken });
   }
+  /**
+   * Fetch a GET endpoint with optional caching support.
+   */
+  async fetchWithCache(endpoint, params, tags, policy, fetcher) {
+    if (!this.cache) {
+      return fetcher();
+    }
+    const cacheKey = this.buildCacheKey(endpoint, params);
+    const combinedPolicy = policy ? { ...policy, tags: this.mergeTags(tags, policy.tags) } : { tags };
+    return this.cache.getOrSet(cacheKey, fetcher, combinedPolicy);
+  }
+  /**
+   * Invalidate cache entries by keys or tags.
+   */
+  async invalidateCache(options) {
+    if (!this.cache) {
+      return;
+    }
+    await this.cache.invalidate(options);
+  }
+  /**
+   * Build a consistent cache key for an endpoint + params combination.
+   */
+  buildCacheKey(endpoint, params) {
+    const sanitizedEndpoint = endpoint.replace(/^\//, "");
+    const baseSegment = this.basePath.replace(/^\//, "");
+    const parts = [baseSegment, sanitizedEndpoint];
+    if (params && Object.keys(params).length > 0) {
+      parts.push(this.sortObject(params));
+    }
+    if (this.cache) {
+      return this.cache.buildKey(parts);
+    }
+    return parts.map((part) => typeof part === "string" ? part : JSON.stringify(part)).join(":");
+  }
+  mergeTags(defaultTags, overrideTags) {
+    const combined = /* @__PURE__ */ new Set();
+    defaultTags.forEach((tag) => combined.add(tag));
+    overrideTags?.forEach((tag) => combined.add(tag));
+    return Array.from(combined.values());
+  }
+  sortObject(input) {
+    const sortedKeys = Object.keys(input).sort();
+    const result = {};
+    for (const key of sortedKeys) {
+      const value = input[key];
+      if (value === void 0) continue;
+      if (Array.isArray(value)) {
+        result[key] = value.map(
+          (item) => typeof item === "object" && item !== null ? this.sortObject(item) : item
+        );
+      } else if (value && typeof value === "object") {
+        result[key] = this.sortObject(value);
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
 };
 
 // src/client/auth-client.ts
 var AuthClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get CSRF token
@@ -337,28 +656,50 @@ var AuthClient = class extends BaseClient {
 
 // src/client/content-client.ts
 var ContentClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get all content with pagination and filtering for a site
    */
-  async getContent(siteName, params) {
-    return this.http.get(this.buildPath(this.siteScopedEndpoint(siteName)), params);
+  async getContent(siteName, params, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(siteName);
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      params,
+      this.buildContentTags(siteName),
+      cachePolicy,
+      () => this.http.get(path, params)
+    );
   }
   /**
    * Get content by ID
    */
-  async getContentById(id) {
-    return this.getSingle(`/content/${id}`);
+  async getContentById(id, cachePolicy) {
+    const endpoint = `/content/${id}`;
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      void 0,
+      this.buildContentTags(void 0, void 0, id),
+      cachePolicy,
+      () => this.http.get(path)
+    );
   }
   /**
    * Get content by slug for a site
    */
-  async getContentBySlug(siteName, slug) {
-    return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/slug/${encodeURIComponent(slug)}`)
-    ));
+  async getContentBySlug(siteName, slug, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(siteName, `/slug/${encodeURIComponent(slug)}`);
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      void 0,
+      this.buildContentTags(siteName, slug),
+      cachePolicy,
+      () => this.http.get(path)
+    );
   }
   /**
    * Create new content
@@ -420,12 +761,25 @@ var ContentClient = class extends BaseClient {
   async duplicateContent(id) {
     return this.create(`/content/${id}/duplicate`, {});
   }
+  buildContentTags(siteName, slug, id) {
+    const tags = /* @__PURE__ */ new Set(["content"]);
+    if (siteName) {
+      tags.add(`content:site:${siteName}`);
+    }
+    if (slug) {
+      tags.add(`content:slug:${siteName}:${slug}`);
+    }
+    if (typeof id === "number") {
+      tags.add(`content:id:${id}`);
+    }
+    return Array.from(tags.values());
+  }
 };
 
 // src/client/api-keys-client.ts
 var ApiKeysClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get all API keys
@@ -491,8 +845,8 @@ var ApiKeysClient = class extends BaseClient {
 
 // src/client/organizations-client.ts
 var OrganizationsClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get all organizations
@@ -564,8 +918,8 @@ var OrganizationsClient = class extends BaseClient {
 
 // src/client/sites-client.ts
 var SitesClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get all sites
@@ -661,13 +1015,13 @@ var SitesClient = class extends BaseClient {
 
 // src/client/products-client.ts
 var ProductsClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get all products for a site
    */
-  async getProducts(siteName, params) {
+  async getProducts(siteName, params, cachePolicy) {
     const normalizeList = (value) => {
       if (value === void 0 || value === null) {
         return void 0;
@@ -691,30 +1045,61 @@ var ProductsClient = class extends BaseClient {
         delete normalizedParams.category_id;
       }
     }
-    return this.http.get(
-      this.buildPath(this.siteScopedEndpoint(siteName, "/products", { includeSitesSegment: false })),
-      normalizedParams
+    const endpoint = this.siteScopedEndpoint(siteName, "/products", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      normalizedParams,
+      this.buildProductTags(siteName, ["products:list"]),
+      cachePolicy,
+      () => this.http.get(path, normalizedParams)
     );
   }
   /**
    * Get product by ID
    */
-  async getProductById(id) {
-    return this.getSingle(`/products/${id}`);
+  async getProductById(id, cachePolicy) {
+    const endpoint = `/products/${id}`;
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      void 0,
+      this.buildProductTags(void 0, [`products:id:${id}`]),
+      cachePolicy,
+      () => this.http.get(path)
+    );
   }
   /**
    * Get product by SKU
    */
-  async getProductBySku(sku) {
-    return this.getSingle(`/products/sku/${sku}`);
+  async getProductBySku(sku, cachePolicy) {
+    const endpoint = `/products/sku/${encodeURIComponent(sku)}`;
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      void 0,
+      this.buildProductTags(void 0, [`products:sku:${sku.toLowerCase()}`]),
+      cachePolicy,
+      () => this.http.get(path)
+    );
   }
   /**
    * Get product by slug and site name
    */
-  async getProductBySlug(siteName, slug) {
-    return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/products/slug/${encodeURIComponent(slug)}`, { includeSitesSegment: false })
-    ));
+  async getProductBySlug(siteName, slug, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/slug/${encodeURIComponent(slug)}`,
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      void 0,
+      this.buildProductTags(siteName, [`products:slug:${siteName}:${slug}`]),
+      cachePolicy,
+      () => this.http.get(path)
+    );
   }
   /**
    * Create new product
@@ -803,27 +1188,44 @@ var ProductsClient = class extends BaseClient {
   /**
    * Get products by category slug
    */
-  async getProductsByCategorySlug(siteName, categorySlug, params) {
+  async getProductsByCategorySlug(siteName, categorySlug, params, cachePolicy) {
     const queryParams = params ? {
       limit: params.limit,
       offset: params.page ? (params.page - 1) * (params.limit || 20) : void 0,
       published: params.published,
       search: params.search
     } : void 0;
-    return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(
-        siteName,
-        `/products/category/${encodeURIComponent(categorySlug)}`,
-        { includeSitesSegment: false }
-      )
-    ), queryParams);
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/category/${encodeURIComponent(categorySlug)}`,
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      queryParams,
+      this.buildProductTags(siteName, [
+        "products:category",
+        `products:category:${siteName}:${categorySlug}`
+      ]),
+      cachePolicy,
+      () => this.http.get(path, queryParams)
+    );
+  }
+  buildProductTags(siteName, extraTags = []) {
+    const tags = /* @__PURE__ */ new Set(["products"]);
+    if (siteName) {
+      tags.add(`products:site:${siteName}`);
+    }
+    extraTags.filter(Boolean).forEach((tag) => tags.add(tag));
+    return Array.from(tags.values());
   }
 };
 
 // src/client/categories-client.ts
 var CategoriesClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get all categories
@@ -846,14 +1248,20 @@ var CategoriesClient = class extends BaseClient {
   /**
    * Get product category by slug (for products)
    */
-  async getProductCategoryBySlug(siteName, slug) {
-    return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(
-        siteName,
-        `/product_category/slug/${encodeURIComponent(slug)}`,
-        { includeSitesSegment: false }
-      )
-    ));
+  async getProductCategoryBySlug(siteName, slug, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/product_category/slug/${encodeURIComponent(slug)}`,
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      void 0,
+      this.buildCategoryTags(siteName, slug),
+      cachePolicy,
+      () => this.http.get(path)
+    );
   }
   /**
    * Create new category
@@ -922,12 +1330,22 @@ var CategoriesClient = class extends BaseClient {
   async searchCategories(query, params) {
     return this.http.get(`/categories/search`, { q: query, ...params });
   }
+  buildCategoryTags(siteName, slug) {
+    const tags = /* @__PURE__ */ new Set(["categories"]);
+    if (siteName) {
+      tags.add(`categories:site:${siteName}`);
+    }
+    if (slug) {
+      tags.add(`categories:product:${siteName}:${slug}`);
+    }
+    return Array.from(tags.values());
+  }
 };
 
 // src/client/webhooks-client.ts
 var WebhooksClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get all webhooks
@@ -1024,8 +1442,8 @@ var WebhooksClient = class extends BaseClient {
 
 // src/client/checkout-client.ts
 var CheckoutClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Get CSRF token for a specific site
@@ -1136,8 +1554,8 @@ var CheckoutClient = class extends BaseClient {
 
 // src/client/contact-client.ts
 var ContactClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Build a contact endpoint scoped to a site (without /sites prefix)
@@ -1243,8 +1661,8 @@ var ContactClient = class extends BaseClient {
 
 // src/client/newsletter-client.ts
 var NewsletterClient = class extends BaseClient {
-  constructor(http) {
-    super(http, "/api/v1");
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
   }
   /**
    * Build a newsletter endpoint scoped to a site (without /sites prefix)
@@ -1439,6 +1857,7 @@ var NewsletterClient = class extends BaseClient {
 // src/perspect-api-client.ts
 var PerspectApiClient = class {
   http;
+  cache;
   // Service clients
   auth;
   content;
@@ -1456,17 +1875,18 @@ var PerspectApiClient = class {
       throw new Error("baseUrl is required in PerspectApiConfig");
     }
     this.http = new HttpClient(config);
-    this.auth = new AuthClient(this.http);
-    this.content = new ContentClient(this.http);
-    this.apiKeys = new ApiKeysClient(this.http);
-    this.organizations = new OrganizationsClient(this.http);
-    this.sites = new SitesClient(this.http);
-    this.products = new ProductsClient(this.http);
-    this.categories = new CategoriesClient(this.http);
-    this.webhooks = new WebhooksClient(this.http);
-    this.checkout = new CheckoutClient(this.http);
-    this.contact = new ContactClient(this.http);
-    this.newsletter = new NewsletterClient(this.http);
+    this.cache = new CacheManager(config.cache);
+    this.auth = new AuthClient(this.http, this.cache);
+    this.content = new ContentClient(this.http, this.cache);
+    this.apiKeys = new ApiKeysClient(this.http, this.cache);
+    this.organizations = new OrganizationsClient(this.http, this.cache);
+    this.sites = new SitesClient(this.http, this.cache);
+    this.products = new ProductsClient(this.http, this.cache);
+    this.categories = new CategoriesClient(this.http, this.cache);
+    this.webhooks = new WebhooksClient(this.http, this.cache);
+    this.checkout = new CheckoutClient(this.http, this.cache);
+    this.contact = new ContactClient(this.http, this.cache);
+    this.newsletter = new NewsletterClient(this.http, this.cache);
   }
   /**
    * Update authentication token
@@ -2046,13 +2466,16 @@ export {
   ApiKeysClient,
   AuthClient,
   BaseClient,
+  CacheManager,
   CategoriesClient,
   CheckoutClient,
   ContactClient,
   ContentClient,
   DEFAULT_IMAGE_SIZES,
   HttpClient,
+  InMemoryCacheAdapter,
   NewsletterClient,
+  NoopCacheAdapter,
   OrganizationsClient,
   PerspectApiClient,
   ProductsClient,