perspectapi-ts-sdk 1.5.2 → 2.0.0

package/README.md

@@ -82,6 +82,72 @@ const checkout = await createCheckoutSession({
 ```
 
 > 📚 See [docs/loaders.md](docs/loaders.md) for full walkthroughs, including fallback data, custom logging, and Stripe price resolution.
+
+## Configuring Caching
+
+Pass a `cache` block when you create the client to enable caching. The SDK falls back to an in-memory store in development; in production you can supply any adapter that satisfies the `CacheAdapter` interface.
+
+```ts
+import { PerspectApiClient } from 'perspectapi-ts-sdk';
+import { myCacheAdapter } from './cache-adapter';
+
+const perspect = new PerspectApiClient({
+  baseUrl: 'https://api.perspect.co',
+  apiKey: env.PERSPECT_API_KEY,
+  cache: {
+    adapter: myCacheAdapter,
+    defaultTtlSeconds: 300,
+    keyPrefix: 'storefront', // optional namespace
+  },
+});
+```
+
+### Cloudflare Workers KV example
+
+KV namespaces make a great globally distributed cache. Bind a namespace (e.g. `PERSPECT_CACHE`) in your Worker and wrap it with a small adapter:
+
+```ts
+// worker.ts
+import { PerspectApiClient, type CacheAdapter } from 'perspectapi-ts-sdk';
+
+const kvAdapter = (kv: KVNamespace): CacheAdapter => ({
+  async get(key) {
+    const value = await kv.get(key);
+    return value ?? undefined;
+  },
+  async set(key, value, options) {
+    const ttl = options?.ttlSeconds;
+    await kv.put(key, value, ttl ? { expirationTtl: ttl } : undefined);
+  },
+  async delete(key) {
+    await kv.delete(key);
+  },
+  async deleteMany(keys) {
+    await Promise.all(keys.map(key => kv.delete(key)));
+  },
+});
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const perspect = new PerspectApiClient({
+      baseUrl: env.PERSPECT_API_URL,
+      apiKey: env.PERSPECT_API_KEY,
+      cache: {
+        adapter: kvAdapter(env.PERSPECT_CACHE),
+        defaultTtlSeconds: 300,
+        keyPrefix: 'storefront',
+      },
+    });
+
+    const products = await perspect.products.getProducts('museum-indian-art');
+    return new Response(JSON.stringify(products.data), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  },
+};
+```
+
+When PerspectAPI sends a webhook—or when your Worker mutates data directly—call `perspect.cache.invalidate({ tags: [...] })` using the tags emitted by the SDK (`products:site:<site>`, `content:slug:<site>:<slug>`, etc.) so stale entries are purged immediately.
 ```
 
 ## Image Transformations

package/dist/index.d.mts

@@ -1,6 +1,91 @@
+/**
+ * Cache-related types for the PerspectAPI SDK.
+ */
+type CacheKeyPart = string | number | boolean | null | undefined | Record<string, unknown> | Array<Record<string, unknown> | string | number | boolean | null | undefined>;
+interface CacheSetOptions {
+    ttlSeconds?: number;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface CachePolicy extends CacheSetOptions {
+    skipCache?: boolean;
+}
+interface CacheAdapter {
+    /**
+     * Retrieve a raw cache payload for the given key. Implementations should return
+     * undefined (or null) when the key does not exist or has expired.
+     */
+    get(key: string): Promise<string | undefined | null>;
+    /**
+     * Store a raw payload for the given key. Implementations MAY honour ttlSeconds
+     * natively; the cache manager will also persist expiry timestamps in the payload
+     * for adapters that do not have native TTL support.
+     */
+    set(key: string, value: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    /**
+     * Remove a cached entry.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Optional bulk delete implementation.
+     */
+    deleteMany?(keys: string[]): Promise<void>;
+    /**
+     * Optional clear method to wipe all entries for adapters that manage isolated namespaces.
+     */
+    clear?(): Promise<void>;
+}
+interface CacheManagerOptions {
+    defaultTtlSeconds?: number;
+    keyPrefix?: string;
+}
+interface CacheConfig extends CacheManagerOptions {
+    /**
+     * Explicit flag to disable caching. Defaults to false when a cache configuration
+     * is supplied, so caching is considered enabled unless explicitly disabled.
+     */
+    enabled?: boolean;
+    adapter?: CacheAdapter;
+}
+interface CacheInvalidateOptions {
+    keys?: string[];
+    tags?: string[];
+}
+
+/**
+ * CacheManager orchestrates cache get/set/invalidate behaviour using a pluggable adapter.
+ */
+
+declare class CacheManager {
+    private adapter;
+    private readonly defaultTtlSeconds;
+    private readonly keyPrefix;
+    private readonly enabled;
+    constructor(config?: CacheConfig);
+    isEnabled(): boolean;
+    getKeyPrefix(): string;
+    buildKey(parts: CacheKeyPart[]): string;
+    getOrSet<T>(key: string, resolveValue: () => Promise<T>, policy?: CachePolicy): Promise<T>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    invalidate(options: CacheInvalidateOptions): Promise<void>;
+    private namespacedKey;
+    private tagKey;
+    private serialize;
+    private deserialize;
+    private deserializeTagSet;
+    private registerKeyTags;
+    private removeKeyFromTags;
+    private normalizeKeyPart;
+    private normalizeObject;
+}
+
 /**
  * Core types and interfaces for PerspectAPI SDK
  */
+
 interface ApiResponse<T = any> {
     data?: T;
     message?: string;
@@ -420,6 +505,7 @@ interface PerspectApiConfig {
     timeout?: number;
     retries?: number;
     headers?: Record<string, string>;
+    cache?: CacheConfig;
 }
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 interface RequestOptions {
@@ -511,7 +597,8 @@ declare function createApiError(error: unknown): ApiError;
 declare abstract class BaseClient {
     protected http: HttpClient;
     protected basePath: string;
-    constructor(http: HttpClient, basePath: string);
+    protected cache?: CacheManager;
+    constructor(http: HttpClient, basePath: string, cache?: CacheManager);
     /**
      * Build a site-scoped endpoint relative to the API base path
      */
@@ -546,6 +633,20 @@ declare abstract class BaseClient {
      * Handle delete operations
      */
     protected delete<T = any>(endpoint: string, csrfToken?: string): Promise<ApiResponse<T>>;
+    /**
+     * Fetch a GET endpoint with optional caching support.
+     */
+    protected fetchWithCache<T>(endpoint: string, params: Record<string, any> | undefined, tags: string[], policy: CachePolicy | undefined, fetcher: () => Promise<T>): Promise<T>;
+    /**
+     * Invalidate cache entries by keys or tags.
+     */
+    protected invalidateCache(options: CacheInvalidateOptions): Promise<void>;
+    /**
+     * Build a consistent cache key for an endpoint + params combination.
+     */
+    protected buildCacheKey(endpoint: string, params?: Record<string, any>): string;
+    private mergeTags;
+    private sortObject;
 }
 
 /**
@@ -553,7 +654,7 @@ declare abstract class BaseClient {
  */
 
 declare class AuthClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get CSRF token
      */
@@ -606,19 +707,19 @@ declare class AuthClient extends BaseClient {
  */
 
 declare class ContentClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get all content with pagination and filtering for a site
      */
-    getContent(siteName: string, params?: ContentQueryParams): Promise<PaginatedResponse<Content>>;
+    getContent(siteName: string, params?: ContentQueryParams, cachePolicy?: CachePolicy): Promise<PaginatedResponse<Content>>;
     /**
      * Get content by ID
      */
-    getContentById(id: number): Promise<ApiResponse<Content>>;
+    getContentById(id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<Content>>;
     /**
      * Get content by slug for a site
      */
-    getContentBySlug(siteName: string, slug: string): Promise<ApiResponse<Content>>;
+    getContentBySlug(siteName: string, slug: string, cachePolicy?: CachePolicy): Promise<ApiResponse<Content>>;
     /**
      * Create new content
      */
@@ -661,6 +762,7 @@ declare class ContentClient extends BaseClient {
      * Duplicate content
      */
     duplicateContent(id: number): Promise<ApiResponse<Content>>;
+    private buildContentTags;
 }
 
 /**
@@ -668,7 +770,7 @@ declare class ContentClient extends BaseClient {
  */
 
 declare class ApiKeysClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get all API keys
      */
@@ -735,7 +837,7 @@ declare class ApiKeysClient extends BaseClient {
  */
 
 declare class OrganizationsClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get all organizations
      */
@@ -810,7 +912,7 @@ declare class OrganizationsClient extends BaseClient {
  */
 
 declare class SitesClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get all sites
      */
@@ -913,23 +1015,23 @@ declare class SitesClient extends BaseClient {
  */
 
 declare class ProductsClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get all products for a site
      */
-    getProducts(siteName: string, params?: ProductQueryParams): Promise<PaginatedResponse<Product>>;
+    getProducts(siteName: string, params?: ProductQueryParams, cachePolicy?: CachePolicy): Promise<PaginatedResponse<Product>>;
     /**
      * Get product by ID
      */
-    getProductById(id: number): Promise<ApiResponse<Product>>;
+    getProductById(id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<Product>>;
     /**
      * Get product by SKU
      */
-    getProductBySku(sku: string): Promise<ApiResponse<Product>>;
+    getProductBySku(sku: string, cachePolicy?: CachePolicy): Promise<ApiResponse<Product>>;
     /**
      * Get product by slug and site name
      */
-    getProductBySlug(siteName: string, slug: string): Promise<ApiResponse<Product & {
+    getProductBySlug(siteName: string, slug: string, cachePolicy?: CachePolicy): Promise<ApiResponse<Product & {
         variants?: any[];
     }>>;
     /**
@@ -1044,7 +1146,7 @@ declare class ProductsClient extends BaseClient {
         limit?: number;
         published?: boolean;
         search?: string;
-    }): Promise<ApiResponse<{
+    }, cachePolicy?: CachePolicy): Promise<ApiResponse<{
         data: Product[];
         category: {
             id: number;
@@ -1058,6 +1160,7 @@ declare class ProductsClient extends BaseClient {
             offset?: number;
         };
     }>>;
+    private buildProductTags;
 }
 
 /**
@@ -1065,7 +1168,7 @@ declare class ProductsClient extends BaseClient {
  */
 
 declare class CategoriesClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get all categories
      */
@@ -1086,7 +1189,7 @@ declare class CategoriesClient extends BaseClient {
     /**
      * Get product category by slug (for products)
      */
-    getProductCategoryBySlug(siteName: string, slug: string): Promise<ApiResponse<Category>>;
+    getProductCategoryBySlug(siteName: string, slug: string, cachePolicy?: CachePolicy): Promise<ApiResponse<Category>>;
     /**
      * Create new category
      */
@@ -1156,6 +1259,7 @@ declare class CategoriesClient extends BaseClient {
         limit?: number;
         organizationId?: number;
     }): Promise<ApiResponse<Category[]>>;
+    private buildCategoryTags;
 }
 
 /**
@@ -1163,7 +1267,7 @@ declare class CategoriesClient extends BaseClient {
  */
 
 declare class WebhooksClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get all webhooks
      */
@@ -1309,7 +1413,7 @@ declare class WebhooksClient extends BaseClient {
  */
 
 declare class CheckoutClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Get CSRF token for a specific site
      * @param siteName - The site name to get CSRF token for
@@ -1482,7 +1586,7 @@ declare class CheckoutClient extends BaseClient {
  */
 
 declare class ContactClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Build a contact endpoint scoped to a site (without /sites prefix)
      */
@@ -1629,7 +1733,7 @@ declare class ContactClient extends BaseClient {
  */
 
 declare class NewsletterClient extends BaseClient {
-    constructor(http: any);
+    constructor(http: any, cache?: CacheManager);
     /**
      * Build a newsletter endpoint scoped to a site (without /sites prefix)
      */
@@ -1831,6 +1935,7 @@ declare class NewsletterClient extends BaseClient {
 
 declare class PerspectApiClient {
     private http;
+    readonly cache: CacheManager;
     readonly auth: AuthClient;
     readonly content: ContentClient;
     readonly apiKeys: ApiKeysClient;
@@ -1928,6 +2033,33 @@ declare class PerspectApiClient {
  */
 declare function createPerspectApiClient(config: PerspectApiConfig): PerspectApiClient;
 
+/**
+ * Simple in-memory cache adapter primarily suited for development and testing.
+ */
+
+declare class InMemoryCacheAdapter implements CacheAdapter {
+    private store;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMany(keys: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * No-op cache adapter that disables caching while preserving the cache contract.
+ */
+
+declare class NoopCacheAdapter implements CacheAdapter {
+    get(): Promise<undefined>;
+    set(): Promise<void>;
+    delete(): Promise<void>;
+    deleteMany(): Promise<void>;
+    clear(): Promise<void>;
+}
+
 /**
  * Cloudflare Image Resizing Integration
  * Transforms images on-the-fly using Cloudflare's Image Resizing service
@@ -2199,4 +2331,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };