perspectapi-ts-sdk 1.5.2 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "1.5.2",
+  "version": "2.1.0",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/cache/cache-manager.ts

@@ -0,0 +1,302 @@
+/**
+ * CacheManager orchestrates cache get/set/invalidate behaviour using a pluggable adapter.
+ */
+
+import { InMemoryCacheAdapter } from './in-memory-adapter';
+import { NoopCacheAdapter } from './noop-adapter';
+import type {
+  CacheAdapter,
+  CacheConfig,
+  CacheEntry,
+  CacheInvalidateOptions,
+  CacheKeyPart,
+  CachePolicy,
+  CacheSetOptions,
+  CacheManagerOptions,
+} from './types';
+
+const TAG_PREFIX = '__tag__';
+
+export class CacheManager {
+  private adapter: CacheAdapter;
+  private readonly defaultTtlSeconds: number;
+  private readonly keyPrefix: string;
+  private readonly enabled: boolean;
+
+  constructor(config?: CacheConfig) {
+    const defaultOptions: CacheManagerOptions = {
+      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) {
+      // Cache config supplied but no adapter; fall back to in-memory caching.
+      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(): boolean {
+    return this.enabled;
+  }
+
+  getKeyPrefix(): string {
+    return this.keyPrefix;
+  }
+
+  buildKey(parts: CacheKeyPart[]): string {
+    const normalized = parts
+      .flatMap(part => this.normalizeKeyPart(part))
+      .filter(part => part !== undefined && part !== null && part !== '');
+
+    return normalized.join(':');
+  }
+
+  async getOrSet<T>(
+    key: string,
+    resolveValue: () => Promise<T>,
+    policy?: CachePolicy
+  ): Promise<T> {
+    if (!this.enabled || policy?.skipCache) {
+      console.log('[Cache] Cache disabled or skipped', { key, enabled: this.enabled, skipCache: policy?.skipCache });
+      const value = await resolveValue();
+
+      if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
+        await this.set(key, value, policy);
+      }
+
+      return value;
+    }
+
+    const namespacedKey = this.namespacedKey(key);
+    const cachedRaw = await this.adapter.get(namespacedKey);
+
+    if (cachedRaw) {
+      const entry = this.deserialize<T>(cachedRaw);
+
+      if (!entry.expiresAt || entry.expiresAt > Date.now()) {
+        console.log('[Cache] ✓ HIT', { key, tags: entry.tags });
+        return entry.value;
+      }
+
+      // Expired entry
+      console.log('[Cache] ✗ EXPIRED', { key, expiresAt: new Date(entry.expiresAt) });
+      await this.adapter.delete(namespacedKey);
+      if (entry.tags?.length) {
+        await this.removeKeyFromTags(namespacedKey, entry.tags);
+      }
+    } else {
+      console.log('[Cache] ✗ MISS', { key });
+    }
+
+    const value = await resolveValue();
+    await this.set(key, value, policy);
+
+    return value;
+  }
+
+  async set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void> {
+    if (!this.enabled || options?.ttlSeconds === 0) {
+      return;
+    }
+
+    const namespacedKey = this.namespacedKey(key);
+    const ttlSeconds = options?.ttlSeconds ?? this.defaultTtlSeconds;
+
+    const entry: CacheEntry<T> = {
+      value,
+      expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : undefined,
+      tags: options?.tags,
+      metadata: options?.metadata,
+    };
+
+    console.log('[Cache] SET', { key, ttlSeconds, tags: options?.tags });
+
+    await this.adapter.set(namespacedKey, this.serialize(entry), {
+      ttlSeconds: ttlSeconds > 0 ? ttlSeconds : undefined,
+    });
+
+    if (options?.tags?.length) {
+      await this.registerKeyTags(namespacedKey, options.tags);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+    const namespacedKey = this.namespacedKey(key);
+    await this.adapter.delete(namespacedKey);
+  }
+
+  async invalidate(options: CacheInvalidateOptions): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+
+    let totalInvalidated = 0;
+
+    if (options.keys?.length) {
+      const namespacedKeys = options.keys.map(key => this.namespacedKey(key));
+      console.log('[Cache] INVALIDATE by keys', { count: options.keys.length, keys: options.keys });
+      if (this.adapter.deleteMany) {
+        await this.adapter.deleteMany(namespacedKeys);
+      } else {
+        await Promise.all(namespacedKeys.map(key => this.adapter.delete(key)));
+      }
+      totalInvalidated += options.keys.length;
+    }
+
+    if (options.tags?.length) {
+      console.log('[Cache] INVALIDATE by tags', { tags: options.tags });
+      await Promise.all(
+        options.tags.map(async tag => {
+          const tagKey = this.tagKey(tag);
+          const payload = await this.adapter.get(tagKey);
+          if (!payload) {
+            console.log('[Cache] No entries for tag', { tag });
+            return;
+          }
+
+          const keys = this.deserializeTagSet(payload);
+          if (keys.length) {
+            console.log('[Cache] Invalidating entries for tag', { tag, count: keys.length });
+            if (this.adapter.deleteMany) {
+              await this.adapter.deleteMany(keys);
+            } else {
+              await Promise.all(keys.map(key => this.adapter.delete(key)));
+            }
+            totalInvalidated += keys.length;
+          }
+
+          await this.adapter.delete(tagKey);
+        })
+      );
+    }
+
+    console.log('[Cache] ✓ INVALIDATED', { totalEntries: totalInvalidated, keys: options.keys?.length || 0, tags: options.tags?.length || 0 });
+  }
+
+  private namespacedKey(key: string): string {
+    return `${this.keyPrefix}:${key}`;
+  }
+
+  private tagKey(tag: string): string {
+    return this.namespacedKey(`${TAG_PREFIX}:${tag}`);
+  }
+
+  private serialize(entry: CacheEntry): string {
+    return JSON.stringify(entry);
+  }
+
+  private deserialize<T>(payload: string): CacheEntry<T> {
+    try {
+      return JSON.parse(payload) as CacheEntry<T>;
+    } catch {
+      return { value: payload as unknown as T };
+    }
+  }
+
+  private deserializeTagSet(payload: string): string[] {
+    try {
+      const parsed = JSON.parse(payload);
+      return Array.isArray(parsed) ? (parsed as string[]) : [];
+    } catch {
+      return [];
+    }
+  }
+
+  private async registerKeyTags(namespacedKey: string, tags: string[]): Promise<void> {
+    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));
+        }
+      })
+    );
+  }
+
+  private async removeKeyFromTags(namespacedKey: string, tags: string[]): Promise<void> {
+    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));
+        }
+      })
+    );
+  }
+
+  private normalizeKeyPart(part: CacheKeyPart): string[] {
+    if (part === undefined || part === null || part === '') {
+      return [];
+    }
+
+    if (Array.isArray(part)) {
+      return part.flatMap(item => this.normalizeKeyPart(item as CacheKeyPart));
+    }
+
+    if (typeof part === 'object') {
+      return [this.normalizeObject(part as Record<string, unknown>)];
+    }
+
+    return [String(part)];
+  }
+
+  private normalizeObject(input: Record<string, unknown>): string {
+    const sortedKeys = Object.keys(input).sort();
+    const normalized: Record<string, unknown> = {};
+
+    for (const key of sortedKeys) {
+      const value = (input as Record<string, unknown>)[key];
+      if (value === undefined) {
+        continue;
+      }
+
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        normalized[key] = JSON.parse(this.normalizeObject(value as Record<string, unknown>));
+      } else if (Array.isArray(value)) {
+        normalized[key] = value.map(item =>
+          typeof item === 'object' && item !== null
+            ? JSON.parse(this.normalizeObject(item as Record<string, unknown>))
+            : item
+        );
+      } else {
+        normalized[key] = value;
+      }
+    }
+
+    return JSON.stringify(normalized);
+  }
+}

package/src/cache/in-memory-adapter.ts

@@ -0,0 +1,49 @@
+/**
+ * Simple in-memory cache adapter primarily suited for development and testing.
+ */
+
+import type { CacheAdapter } from './types';
+
+interface StoredValue {
+  value: string;
+  expiresAt?: number;
+}
+
+export class InMemoryCacheAdapter implements CacheAdapter {
+  private store = new Map<string, StoredValue>();
+
+  async get(key: string): Promise<string | undefined> {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return undefined;
+    }
+
+    if (entry.expiresAt && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  async set(key: string, value: string, options?: { ttlSeconds?: number }): Promise<void> {
+    const expiresAt =
+      options?.ttlSeconds && options.ttlSeconds > 0
+        ? Date.now() + options.ttlSeconds * 1000
+        : undefined;
+
+    this.store.set(key, { value, expiresAt });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async deleteMany(keys: string[]): Promise<void> {
+    keys.forEach(key => this.store.delete(key));
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+}

package/src/cache/noop-adapter.ts

@@ -0,0 +1,27 @@
+/**
+ * No-op cache adapter that disables caching while preserving the cache contract.
+ */
+
+import type { CacheAdapter } from './types';
+
+export class NoopCacheAdapter implements CacheAdapter {
+  async get(): Promise<undefined> {
+    return undefined;
+  }
+
+  async set(): Promise<void> {
+    // Intentionally blank
+  }
+
+  async delete(): Promise<void> {
+    // Intentionally blank
+  }
+
+  async deleteMany(): Promise<void> {
+    // Intentionally blank
+  }
+
+  async clear(): Promise<void> {
+    // Intentionally blank
+  }
+}

package/src/cache/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Cache-related types for the PerspectAPI SDK.
+ */
+
+export type CacheKeyPart =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Record<string, unknown>
+  | Array<Record<string, unknown> | string | number | boolean | null | undefined>;
+
+export interface CacheSetOptions {
+  ttlSeconds?: number;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface CachePolicy extends CacheSetOptions {
+  skipCache?: boolean;
+}
+
+export interface CacheEntry<T = unknown> {
+  value: T;
+  expiresAt?: number;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export 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>;
+}
+
+export interface CacheManagerOptions {
+  defaultTtlSeconds?: number;
+  keyPrefix?: string;
+}
+
+export 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;
+}
+
+export interface CacheInvalidateOptions {
+  keys?: string[];
+  tags?: string[];
+}

package/src/client/api-keys-client.ts

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

package/src/client/auth-client.ts

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

package/src/client/base-client.ts

@@ -4,14 +4,18 @@
 
 import { HttpClient } from '../utils/http-client';
 import type { ApiResponse } from '../types';
+import type { CacheManager } from '../cache/cache-manager';
+import type { CachePolicy, CacheInvalidateOptions } from '../cache/types';
 
 export abstract class BaseClient {
   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;
   }
 
   /**
@@ -100,4 +104,87 @@ export abstract class BaseClient {
   protected async delete<T = any>(endpoint: string, csrfToken?: string): Promise<ApiResponse<T>> {
     return this.http.delete<T>(this.buildPath(endpoint), { csrfToken });
   }
+
+  /**
+   * Fetch a GET endpoint with optional caching support.
+   */
+  protected async fetchWithCache<T>(
+    endpoint: string,
+    params: Record<string, any> | undefined,
+    tags: string[],
+    policy: CachePolicy | undefined,
+    fetcher: () => Promise<T>
+  ): Promise<T> {
+    if (!this.cache) {
+      return fetcher();
+    }
+
+    const cacheKey = this.buildCacheKey(endpoint, params);
+    const combinedPolicy: CachePolicy | undefined = policy
+      ? { ...policy, tags: this.mergeTags(tags, policy.tags) }
+      : { tags };
+
+    return this.cache.getOrSet<T>(cacheKey, fetcher, combinedPolicy);
+  }
+
+  /**
+   * Invalidate cache entries by keys or tags.
+   */
+  protected async invalidateCache(options: CacheInvalidateOptions): Promise<void> {
+    if (!this.cache) {
+      return;
+    }
+    await this.cache.invalidate(options);
+  }
+
+  /**
+   * Build a consistent cache key for an endpoint + params combination.
+   */
+  protected buildCacheKey(endpoint: string, params?: Record<string, any>): string {
+    const sanitizedEndpoint = endpoint.replace(/^\//, '');
+    const baseSegment = this.basePath.replace(/^\//, '');
+
+    const parts: Array<string | Record<string, unknown>> = [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(':');
+  }
+
+  private mergeTags(defaultTags: string[], overrideTags?: string[]): string[] {
+    const combined = new Set<string>();
+    defaultTags.forEach(tag => combined.add(tag));
+    overrideTags?.forEach(tag => combined.add(tag));
+    return Array.from(combined.values());
+  }
+
+  private sortObject(input: Record<string, any>): Record<string, any> {
+    const sortedKeys = Object.keys(input).sort();
+    const result: Record<string, any> = {};
+
+    for (const key of sortedKeys) {
+      const value = input[key];
+      if (value === undefined) continue;
+
+      if (Array.isArray(value)) {
+        result[key] = value.map(item =>
+          typeof item === 'object' && item !== null ? this.sortObject(item as Record<string, any>) : item
+        );
+      } else if (value && typeof value === 'object') {
+        result[key] = this.sortObject(value as Record<string, any>);
+      } else {
+        result[key] = value;
+      }
+    }
+
+    return result;
+  }
 }

package/src/client/categories-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 {
   Category,
   CreateCategoryRequest,
@@ -11,8 +13,8 @@ import type {
 } from '../types';
 
 export class CategoriesClient extends BaseClient {
-  constructor(http: any) {
-    super(http, '/api/v1');
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
   }
 
   /**
@@ -44,14 +46,25 @@ export class CategoriesClient extends BaseClient {
   /**
    * Get product category by slug (for products)
    */
-  async getProductCategoryBySlug(siteName: string, slug: string): Promise<ApiResponse<Category>> {
-    return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(
-        siteName,
-        `/product_category/slug/${encodeURIComponent(slug)}`,
-        { includeSitesSegment: false }
-      )
-    ));
+  async getProductCategoryBySlug(
+    siteName: string,
+    slug: string,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<Category>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/product_category/slug/${encodeURIComponent(slug)}`,
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<Category>>(
+      endpoint,
+      undefined,
+      this.buildCategoryTags(siteName, slug),
+      cachePolicy,
+      () => this.http.get<Category>(path)
+    );
   }
 
   /**
@@ -152,4 +165,15 @@ export class CategoriesClient extends BaseClient {
   }): Promise<ApiResponse<Category[]>> {
     return this.http.get(`/categories/search`, { q: query, ...params });
   }
+
+  private buildCategoryTags(siteName: string, slug: string): string[] {
+    const tags = new Set<string>(['categories']);
+    if (siteName) {
+      tags.add(`categories:site:${siteName}`);
+    }
+    if (slug) {
+      tags.add(`categories:product:${siteName}:${slug}`);
+    }
+    return Array.from(tags.values());
+  }
 }

package/src/client/checkout-client.ts

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