perspectapi-ts-sdk 1.5.1 → 2.0.0

package/src/client/contact-client.ts

@@ -3,6 +3,7 @@
  */
 
 import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
 import type {
   ContactSubmission,
   CreateContactRequest,
@@ -13,8 +14,8 @@ import type {
 } from '../types';
 
 export class ContactClient extends BaseClient {
-  constructor(http: any) {
-    super(http, '/api/v1');
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
   }
 
   /**

package/src/client/content-client.ts

@@ -3,6 +3,8 @@
  */
 
 import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
+import type { CachePolicy } from '../cache/types';
 import type {
   Content,
   CreateContentRequest,
@@ -13,31 +15,64 @@ import type {
 } from '../types';
 
 export class ContentClient extends BaseClient {
-  constructor(http: any) {
-    super(http, '/api/v1');
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
   }
 
   /**
    * Get all content with pagination and filtering for a site
    */
-  async getContent(siteName: string, params?: ContentQueryParams): Promise<PaginatedResponse<Content>> {
-    return this.http.get(this.buildPath(this.siteScopedEndpoint(siteName)), params);
+  async getContent(
+    siteName: string,
+    params?: ContentQueryParams,
+    cachePolicy?: CachePolicy
+  ): Promise<PaginatedResponse<Content>> {
+    const endpoint = this.siteScopedEndpoint(siteName);
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<PaginatedResponse<Content>>(
+      endpoint,
+      params,
+      this.buildContentTags(siteName),
+      cachePolicy,
+      () => this.http.get(path, params) as Promise<PaginatedResponse<Content>>
+    );
   }
 
   /**
    * Get content by ID
    */
-  async getContentById(id: number): Promise<ApiResponse<Content>> {
-    return this.getSingle<Content>(`/content/${id}`);
+  async getContentById(id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<Content>> {
+    const endpoint = `/content/${id}`;
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<Content>>(
+      endpoint,
+      undefined,
+      this.buildContentTags(undefined, undefined, id),
+      cachePolicy,
+      () => this.http.get<Content>(path)
+    );
   }
 
   /**
    * Get content by slug for a site
    */
-  async getContentBySlug(siteName: string, slug: string): Promise<ApiResponse<Content>> {
-    return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/slug/${encodeURIComponent(slug)}`)
-    ));
+  async getContentBySlug(
+    siteName: string,
+    slug: string,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<Content>> {
+    const endpoint = this.siteScopedEndpoint(siteName, `/slug/${encodeURIComponent(slug)}`);
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<Content>>(
+      endpoint,
+      undefined,
+      this.buildContentTags(siteName, slug),
+      cachePolicy,
+      () => this.http.get<Content>(path)
+    );
   }
 
   /**
@@ -109,4 +144,18 @@ export class ContentClient extends BaseClient {
   async duplicateContent(id: number): Promise<ApiResponse<Content>> {
     return this.create<Record<string, never>, Content>(`/content/${id}/duplicate`, {});
   }
+
+  private buildContentTags(siteName?: string, slug?: string, id?: number): string[] {
+    const tags = new Set<string>(['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());
+  }
 }

package/src/client/newsletter-client.ts

@@ -3,6 +3,7 @@
  */
 
 import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
 import type {
   NewsletterSubscription,
   CreateNewsletterSubscriptionRequest,
@@ -18,8 +19,8 @@ import type {
 } from '../types';
 
 export class NewsletterClient extends BaseClient {
-  constructor(http: any) {
-    super(http, '/api/v1');
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
   }
 
   /**
@@ -379,4 +380,4 @@ export class NewsletterClient extends BaseClient {
       data
     );
   }
-}
+}

package/src/client/organizations-client.ts

@@ -3,6 +3,7 @@
  */
 
 import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
 import type {
   Organization,
   CreateOrganizationRequest,
@@ -11,8 +12,8 @@ import type {
 } from '../types';
 
 export class OrganizationsClient extends BaseClient {
-  constructor(http: any) {
-    super(http, '/api/v1');
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
   }
 
   /**

package/src/client/products-client.ts

@@ -3,6 +3,8 @@
  */
 
 import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
+import type { CachePolicy } from '../cache/types';
 import type {
   Product,
   CreateProductRequest,
@@ -12,14 +14,18 @@ import type {
 } from '../types';
 
 export class ProductsClient extends BaseClient {
-  constructor(http: any) {
-    super(http, '/api/v1');
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
   }
 
   /**
    * Get all products for a site
    */
-  async getProducts(siteName: string, params?: ProductQueryParams): Promise<PaginatedResponse<Product>> {
+  async getProducts(
+    siteName: string,
+    params?: ProductQueryParams,
+    cachePolicy?: CachePolicy
+  ): Promise<PaginatedResponse<Product>> {
     const normalizeList = (value: string | number | Array<string | number> | undefined): string | undefined => {
       if (value === undefined || value === null) {
         return undefined;
@@ -50,33 +56,72 @@ export class ProductsClient extends BaseClient {
       }
     }
 
-    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<PaginatedResponse<Product>>(
+      endpoint,
+      normalizedParams,
+      this.buildProductTags(siteName, ['products:list']),
+      cachePolicy,
+      () => this.http.get(path, normalizedParams) as Promise<PaginatedResponse<Product>>
     );
   }
 
   /**
    * Get product by ID
    */
-  async getProductById(id: number): Promise<ApiResponse<Product>> {
-    return this.getSingle<Product>(`/products/${id}`);
+  async getProductById(id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<Product>> {
+    const endpoint = `/products/${id}`;
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<Product>>(
+      endpoint,
+      undefined,
+      this.buildProductTags(undefined, [`products:id:${id}`]),
+      cachePolicy,
+      () => this.http.get<Product>(path)
+    );
   }
 
   /**
    * Get product by SKU
    */
-  async getProductBySku(sku: string): Promise<ApiResponse<Product>> {
-    return this.getSingle<Product>(`/products/sku/${sku}`);
+  async getProductBySku(sku: string, cachePolicy?: CachePolicy): Promise<ApiResponse<Product>> {
+    const endpoint = `/products/sku/${encodeURIComponent(sku)}`;
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<Product>>(
+      endpoint,
+      undefined,
+      this.buildProductTags(undefined, [`products:sku:${sku.toLowerCase()}`]),
+      cachePolicy,
+      () => this.http.get<Product>(path)
+    );
   }
 
   /**
    * Get product by slug and site name
    */
-  async getProductBySlug(siteName: string, slug: string): Promise<ApiResponse<Product & { variants?: any[] }>> {
-    return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/products/slug/${encodeURIComponent(slug)}`, { includeSitesSegment: false })
-    ));
+  async getProductBySlug(
+    siteName: string,
+    slug: string,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<Product & { variants?: any[] }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/slug/${encodeURIComponent(slug)}`,
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<Product & { variants?: any[] }>>(
+      endpoint,
+      undefined,
+      this.buildProductTags(siteName, [`products:slug:${siteName}:${slug}`]),
+      cachePolicy,
+      () => this.http.get<Product & { variants?: any[] }>(path)
+    );
   }
 
   /**
@@ -221,7 +266,8 @@ export class ProductsClient extends BaseClient {
       limit?: number;
       published?: boolean;
       search?: string;
-    }
+    },
+    cachePolicy?: CachePolicy
   ): Promise<ApiResponse<{
     data: Product[];
     category: {
@@ -243,12 +289,59 @@ export class ProductsClient extends BaseClient {
       search: params.search
     } : undefined;
 
-    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<ApiResponse<{
+      data: Product[];
+      category: {
+        id: number;
+        name: string;
+        slug: string;
+        description?: string;
+      };
+      meta: {
+        count: number;
+        limit?: number;
+        offset?: number;
+      };
+    }>>(
+      endpoint,
+      queryParams,
+      this.buildProductTags(siteName, [
+        'products:category',
+        `products:category:${siteName}:${categorySlug}`,
+      ]),
+      cachePolicy,
+      () =>
+        this.http.get<{
+          data: Product[];
+          category: {
+            id: number;
+            name: string;
+            slug: string;
+            description?: string;
+          };
+          meta: {
+            count: number;
+            limit?: number;
+            offset?: number;
+          };
+        }>(path, queryParams)
+    );
+  }
+
+  private buildProductTags(siteName?: string, extraTags: string[] = []): string[] {
+    const tags = new Set<string>(['products']);
+    if (siteName) {
+      tags.add(`products:site:${siteName}`);
+    }
+    extraTags.filter(Boolean).forEach(tag => tags.add(tag));
+    return Array.from(tags.values());
   }
 }

package/src/client/sites-client.ts

@@ -3,6 +3,7 @@
  */
 
 import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
 import type {
   Site,
   CreateSiteRequest,
@@ -11,8 +12,8 @@ import type {
 } from '../types';
 
 export class SitesClient extends BaseClient {
-  constructor(http: any) {
-    super(http, '/api/v1');
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
   }
 
   /**

package/src/client/webhooks-client.ts

@@ -3,6 +3,7 @@
  */
 
 import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
 import type {
   Webhook,
   CreateWebhookRequest,
@@ -11,8 +12,8 @@ import type {
 } from '../types';
 
 export class WebhooksClient extends BaseClient {
-  constructor(http: any) {
-    super(http, '/api/v1');
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
   }
 
   /**

package/src/index.ts

@@ -26,6 +26,11 @@ export { BaseClient } from './client/base-client';
 // Utilities
 export { HttpClient, createApiError } from './utils/http-client';
 
+// Cache utilities
+export { CacheManager } from './cache/cache-manager';
+export { InMemoryCacheAdapter } from './cache/in-memory-adapter';
+export { NoopCacheAdapter } from './cache/noop-adapter';
+
 // Image transformation utilities
 export {
   buildImageUrl,

package/src/perspect-api-client.ts

@@ -4,6 +4,7 @@
  */
 
 import { HttpClient } from './utils/http-client';
+import { CacheManager } from './cache/cache-manager';
 import { AuthClient } from './client/auth-client';
 import { ContentClient } from './client/content-client';
 import { ApiKeysClient } from './client/api-keys-client';
@@ -20,6 +21,7 @@ import type { PerspectApiConfig, ApiResponse } from './types';
 
 export class PerspectApiClient {
   private http: HttpClient;
+  public readonly cache: CacheManager;
   
   // Service clients
   public readonly auth: AuthClient;
@@ -42,19 +44,20 @@ export class PerspectApiClient {
 
     // Initialize HTTP client
     this.http = new HttpClient(config);
+    this.cache = new CacheManager(config.cache);
 
     // Initialize service clients
-    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.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);
   }
 
   /**

package/src/types/index.ts

@@ -2,6 +2,8 @@
  * Core types and interfaces for PerspectAPI SDK
  */
 
+import type { CacheConfig } from '../cache/types';
+
 // Base API Response
 export interface ApiResponse<T = any> {
   data?: T;
@@ -495,6 +497,7 @@ export interface PerspectApiConfig {
   timeout?: number;
   retries?: number;
   headers?: Record<string, string>;
+  cache?: CacheConfig;
 }
 
 // HTTP Methods
@@ -509,3 +512,6 @@ export interface RequestOptions {
   timeout?: number;
   csrfToken?: string;  // Optional CSRF token for protected endpoints
 }
+
+// Cache types re-exported for convenience
+export type { CacheConfig } from '../cache/types';