perspectapi-ts-sdk 5.0.2 → 5.1.0

package/src/v2/client/base-v2-client.ts

@@ -1,8 +1,10 @@
 /**
- * v2 Base Client — cursor pagination, expand support, typed errors.
+ * v2 Base Client — cursor pagination, expand support, caching, typed errors.
  */
 
 import { HttpClient } from '../../utils/http-client';
+import type { CacheManager } from '../../cache/cache-manager';
+import type { CachePolicy, CacheInvalidateOptions } from '../../cache/types';
 import type { V2List, V2Error, V2Deleted } from '../types';
 
 export class PerspectV2Error extends Error {
@@ -24,10 +26,12 @@ export class PerspectV2Error extends Error {
 export abstract class BaseV2Client {
   protected http: HttpClient;
   protected basePath: string;
+  protected cache?: CacheManager;
 
-  constructor(http: HttpClient, basePath: string) {
+  constructor(http: HttpClient, basePath: string, cache?: CacheManager) {
     this.http = http;
     this.basePath = basePath;
+    this.cache = cache && cache.isEnabled() ? cache : undefined;
   }
 
   protected buildPath(endpoint: string): string {
@@ -77,19 +81,26 @@ export abstract class BaseV2Client {
     return payload as T;
   }
 
-  /** GET a single resource. */
-  protected async getOne<T>(path: string, params?: object): Promise<T> {
-    const response = await this.http.get<T>(path, this.toParams(params));
-    return this.extractData<T>(response);
+  /** GET a single resource, with optional caching. */
+  protected async getOne<T>(path: string, params?: object, cachePolicy?: CachePolicy): Promise<T> {
+    const fetcher = async () => {
+      const response = await this.http.get<T>(path, this.toParams(params));
+      return this.extractData<T>(response);
+    };
+    return this.fetchWithCache(path, params, cachePolicy, fetcher);
   }
 
-  /** GET a list of resources with cursor pagination. */
+  /** GET a list of resources with cursor pagination, with optional caching. */
   protected async getList<T>(
     path: string,
     params?: object,
+    cachePolicy?: CachePolicy,
   ): Promise<V2List<T>> {
-    const response = await this.http.get<V2List<T>>(path, this.toParams(params));
-    return this.extractData<V2List<T>>(response);
+    const fetcher = async () => {
+      const response = await this.http.get<V2List<T>>(path, this.toParams(params));
+      return this.extractData<V2List<T>>(response);
+    };
+    return this.fetchWithCache(path, params, cachePolicy, fetcher);
   }
 
   /** POST to create a resource. */
@@ -110,6 +121,41 @@ export abstract class BaseV2Client {
     return this.extractData<V2Deleted>(response);
   }
 
+  /** Fetch with optional cache. Bypasses cache for writes or when no cache is configured. */
+  private async fetchWithCache<T>(
+    path: string,
+    params: object | undefined,
+    policy: CachePolicy | undefined,
+    fetcher: () => Promise<T>,
+  ): Promise<T> {
+    if (!this.cache || policy?.skipCache) {
+      return fetcher();
+    }
+    const key = this.buildCacheKey(path, params);
+    return this.cache.getOrSet<T>(key, fetcher, policy);
+  }
+
+  /** Invalidate cache entries by keys or tags. */
+  protected async invalidateCache(options: CacheInvalidateOptions): Promise<void> {
+    if (!this.cache) return;
+    await this.cache.invalidate(options);
+  }
+
+  private buildCacheKey(path: string, params?: object): string {
+    const parts: Array<string | Record<string, unknown>> = [path];
+    if (params && Object.keys(params).length > 0) {
+      const sorted: Record<string, unknown> = {};
+      for (const key of Object.keys(params).sort()) {
+        sorted[key] = (params as Record<string, unknown>)[key];
+      }
+      parts.push(sorted);
+    }
+    if (this.cache) {
+      return this.cache.buildKey(parts);
+    }
+    return parts.map(p => typeof p === 'string' ? p : JSON.stringify(p)).join(':');
+  }
+
   /**
    * Auto-paginating async generator.
    * Yields every item across all pages.

package/src/v2/client/categories-client.ts

@@ -3,6 +3,7 @@
  */
 
 import { BaseV2Client } from './base-v2-client';
+import type { CachePolicy } from '../../cache/types';
 import type {
   V2Category, V2CategoryCreateParams, V2CategoryUpdateParams,
   V2PaginationParams, V2List, V2Deleted,
@@ -10,12 +11,12 @@ import type {
 
 export class CategoriesV2Client extends BaseV2Client {
 
-  async list(siteName: string, params?: V2PaginationParams & { type?: string }): Promise<V2List<V2Category>> {
-    return this.getList<V2Category>(this.sitePath(siteName, 'categories'), params);
+  async list(siteName: string, params?: V2PaginationParams & { type?: string }, cachePolicy?: CachePolicy): Promise<V2List<V2Category>> {
+    return this.getList<V2Category>(this.sitePath(siteName, 'categories'), params, cachePolicy);
   }
 
-  async get(siteName: string, id: string): Promise<V2Category> {
-    return this.getOne<V2Category>(this.sitePath(siteName, 'categories', id));
+  async get(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2Category> {
+    return this.getOne<V2Category>(this.sitePath(siteName, 'categories', id), undefined, cachePolicy);
   }
 
   async create(siteName: string, data: V2CategoryCreateParams): Promise<V2Category> {

package/src/v2/client/content-client.ts

@@ -3,6 +3,7 @@
  */
 
 import { BaseV2Client } from './base-v2-client';
+import type { CachePolicy } from '../../cache/types';
 import type {
   V2Content, V2ContentCreateParams, V2ContentUpdateParams,
   V2ContentListParams, V2List, V2Deleted,
@@ -10,16 +11,16 @@ import type {
 
 export class ContentV2Client extends BaseV2Client {
 
-  async list(siteName: string, params?: V2ContentListParams): Promise<V2List<V2Content>> {
-    return this.getList<V2Content>(this.sitePath(siteName, 'content'), params);
+  async list(siteName: string, params?: V2ContentListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Content>> {
+    return this.getList<V2Content>(this.sitePath(siteName, 'content'), params, cachePolicy);
   }
 
   async *listAutoPaginated(siteName: string, params?: Omit<V2ContentListParams, 'starting_after' | 'ending_before'>) {
     yield* this.listAutoPaginate<V2Content>(this.sitePath(siteName, 'content'), params);
   }
 
-  async get(siteName: string, idOrSlug: string): Promise<V2Content> {
-    return this.getOne<V2Content>(this.sitePath(siteName, 'content', idOrSlug));
+  async get(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2Content> {
+    return this.getOne<V2Content>(this.sitePath(siteName, 'content', idOrSlug), undefined, cachePolicy);
   }
 
   async create(siteName: string, data: V2ContentCreateParams): Promise<V2Content> {

package/src/v2/client/newsletter-client.ts

@@ -3,9 +3,10 @@
  */
 
 import { BaseV2Client } from './base-v2-client';
+import type { CachePolicy } from '../../cache/types';
 import type {
   V2NewsletterSubscription, V2NewsletterList, V2NewsletterCampaign,
-  V2PaginationParams, V2List,
+  V2PaginationParams, V2List, V2NewsletterTrackingResponse,
 } from '../types';
 
 export class NewsletterV2Client extends BaseV2Client {
@@ -48,29 +49,55 @@ export class NewsletterV2Client extends BaseV2Client {
     );
   }
 
+  async trackOpen(
+    siteName: string,
+    token: string,
+  ): Promise<V2NewsletterTrackingResponse> {
+    return this.post<V2NewsletterTrackingResponse>(
+      this.sitePath(siteName, 'newsletter', `track/open/${encodeURIComponent(token)}`),
+    );
+  }
+
+  async trackClick(
+    siteName: string,
+    token: string,
+    url: string,
+  ): Promise<V2NewsletterTrackingResponse> {
+    return this.post<V2NewsletterTrackingResponse>(
+      this.sitePath(siteName, 'newsletter', `track/click/${encodeURIComponent(token)}`),
+      { url },
+    );
+  }
+
   // --- Subscriptions (admin) ---
 
   async listSubscriptions(
     siteName: string,
     params?: V2PaginationParams & { status?: string },
+    cachePolicy?: CachePolicy,
   ): Promise<V2List<V2NewsletterSubscription>> {
     return this.getList<V2NewsletterSubscription>(
       this.sitePath(siteName, 'newsletter', 'subscriptions'),
       params,
+      cachePolicy,
     );
   }
 
-  async getSubscription(siteName: string, id: string): Promise<V2NewsletterSubscription> {
+  async getSubscription(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2NewsletterSubscription> {
     return this.getOne<V2NewsletterSubscription>(
       this.sitePath(siteName, 'newsletter', `subscriptions/${id}`),
+      undefined,
+      cachePolicy,
     );
   }
 
   // --- Lists ---
 
-  async listLists(siteName: string): Promise<V2List<V2NewsletterList>> {
+  async listLists(siteName: string, cachePolicy?: CachePolicy): Promise<V2List<V2NewsletterList>> {
     return this.getList<V2NewsletterList>(
       this.sitePath(siteName, 'newsletter', 'lists'),
+      undefined,
+      cachePolicy,
     );
   }
 
@@ -79,16 +106,20 @@ export class NewsletterV2Client extends BaseV2Client {
   async listCampaigns(
     siteName: string,
     params?: V2PaginationParams & { status?: string },
+    cachePolicy?: CachePolicy,
   ): Promise<V2List<V2NewsletterCampaign>> {
     return this.getList<V2NewsletterCampaign>(
       this.sitePath(siteName, 'newsletter', 'campaigns'),
       params,
+      cachePolicy,
     );
   }
 
-  async getCampaign(siteName: string, idOrSlug: string): Promise<V2NewsletterCampaign> {
+  async getCampaign(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2NewsletterCampaign> {
     return this.getOne<V2NewsletterCampaign>(
       this.sitePath(siteName, 'newsletter', `campaigns/${idOrSlug}`),
+      undefined,
+      cachePolicy,
     );
   }
 }

package/src/v2/client/orders-client.ts

@@ -3,19 +3,20 @@
  */
 
 import { BaseV2Client } from './base-v2-client';
+import type { CachePolicy } from '../../cache/types';
 import type { V2Order, V2OrderListParams, V2List } from '../types';
 
 export class OrdersV2Client extends BaseV2Client {
 
-  async list(siteName: string, params?: V2OrderListParams): Promise<V2List<V2Order>> {
-    return this.getList<V2Order>(this.sitePath(siteName, 'orders'), params);
+  async list(siteName: string, params?: V2OrderListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Order>> {
+    return this.getList<V2Order>(this.sitePath(siteName, 'orders'), params, cachePolicy);
   }
 
   async *listAutoPaginated(siteName: string, params?: Omit<V2OrderListParams, 'starting_after' | 'ending_before'>) {
     yield* this.listAutoPaginate<V2Order>(this.sitePath(siteName, 'orders'), params);
   }
 
-  async get(siteName: string, id: string): Promise<V2Order> {
-    return this.getOne<V2Order>(this.sitePath(siteName, 'orders', id));
+  async get(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2Order> {
+    return this.getOne<V2Order>(this.sitePath(siteName, 'orders', id), undefined, cachePolicy);
   }
 }

package/src/v2/client/products-client.ts

@@ -3,6 +3,7 @@
  */
 
 import { BaseV2Client } from './base-v2-client';
+import type { CachePolicy } from '../../cache/types';
 import type {
   V2Product, V2ProductCreateParams, V2ProductUpdateParams,
   V2ProductListParams, V2List, V2Deleted,
@@ -10,16 +11,16 @@ import type {
 
 export class ProductsV2Client extends BaseV2Client {
 
-  async list(siteName: string, params?: V2ProductListParams): Promise<V2List<V2Product>> {
-    return this.getList<V2Product>(this.sitePath(siteName, 'products'), params);
+  async list(siteName: string, params?: V2ProductListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Product>> {
+    return this.getList<V2Product>(this.sitePath(siteName, 'products'), params, cachePolicy);
   }
 
   async *listAutoPaginated(siteName: string, params?: Omit<V2ProductListParams, 'starting_after' | 'ending_before'>) {
     yield* this.listAutoPaginate<V2Product>(this.sitePath(siteName, 'products'), params);
   }
 
-  async get(siteName: string, idOrSlug: string): Promise<V2Product> {
-    return this.getOne<V2Product>(this.sitePath(siteName, 'products', idOrSlug));
+  async get(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2Product> {
+    return this.getOne<V2Product>(this.sitePath(siteName, 'products', idOrSlug), undefined, cachePolicy);
   }
 
   async create(siteName: string, data: V2ProductCreateParams): Promise<V2Product> {

package/src/v2/index.ts

@@ -11,7 +11,9 @@
  */
 
 import { HttpClient } from '../utils/http-client';
+import { CacheManager } from '../cache/cache-manager';
 import type { PerspectApiConfig } from '../types';
+import type { CacheConfig } from '../cache/types';
 
 import { ContentV2Client } from './client/content-client';
 import { ProductsV2Client } from './client/products-client';
@@ -26,8 +28,13 @@ import { SitesV2Client } from './client/sites-client';
 import { ApiKeysV2Client } from './client/api-keys-client';
 import { WebhooksV2Client } from './client/webhooks-client';
 
+export interface PerspectApiV2Config extends PerspectApiConfig {
+  cache?: CacheConfig;
+}
+
 export class PerspectApiV2Client {
   private http: HttpClient;
+  readonly cache: CacheManager;
 
   readonly content: ContentV2Client;
   readonly products: ProductsV2Client;
@@ -42,7 +49,7 @@ export class PerspectApiV2Client {
   readonly apiKeys: ApiKeysV2Client;
   readonly webhooks: WebhooksV2Client;
 
-  constructor(config: PerspectApiConfig) {
+  constructor(config: PerspectApiV2Config) {
     // Ensure base URL points to /api/v2
     const baseUrl = config.baseUrl.replace(/\/+$/, '');
     const v2BaseUrl = baseUrl.endsWith('/api/v2')
@@ -50,20 +57,22 @@ export class PerspectApiV2Client {
       : `${baseUrl}/api/v2`;
 
     this.http = new HttpClient({ ...config, baseUrl: v2BaseUrl });
+    this.cache = new CacheManager(config.cache);
 
     const basePath = '';
-    this.content = new ContentV2Client(this.http, basePath);
-    this.products = new ProductsV2Client(this.http, basePath);
-    this.categories = new CategoriesV2Client(this.http, basePath);
-    this.collections = new CollectionsV2Client(this.http, basePath);
-    this.orders = new OrdersV2Client(this.http, basePath);
-    this.siteUsers = new SiteUsersV2Client(this.http, basePath);
-    this.newsletter = new NewsletterV2Client(this.http, basePath);
-    this.contacts = new ContactsV2Client(this.http, basePath);
-    this.organizations = new OrganizationsV2Client(this.http, basePath);
-    this.sites = new SitesV2Client(this.http, basePath);
-    this.apiKeys = new ApiKeysV2Client(this.http, basePath);
-    this.webhooks = new WebhooksV2Client(this.http, basePath);
+    const cache = this.cache;
+    this.content = new ContentV2Client(this.http, basePath, cache);
+    this.products = new ProductsV2Client(this.http, basePath, cache);
+    this.categories = new CategoriesV2Client(this.http, basePath, cache);
+    this.collections = new CollectionsV2Client(this.http, basePath, cache);
+    this.orders = new OrdersV2Client(this.http, basePath, cache);
+    this.siteUsers = new SiteUsersV2Client(this.http, basePath, cache);
+    this.newsletter = new NewsletterV2Client(this.http, basePath, cache);
+    this.contacts = new ContactsV2Client(this.http, basePath, cache);
+    this.organizations = new OrganizationsV2Client(this.http, basePath, cache);
+    this.sites = new SitesV2Client(this.http, basePath, cache);
+    this.apiKeys = new ApiKeysV2Client(this.http, basePath, cache);
+    this.webhooks = new WebhooksV2Client(this.http, basePath, cache);
   }
 
   /** Update the JWT token for authenticated requests. */

package/src/v2/types.ts

@@ -311,6 +311,10 @@ export interface V2NewsletterCampaign extends V2Object {
   updated_at: string | null;
 }
 
+export interface V2NewsletterTrackingResponse {
+  success: boolean;
+}
+
 // --- Contact ---
 
 export interface V2ContactSubmission extends V2Object {