perspectapi-ts-sdk 5.0.3 → 5.2.0

package/dist/index.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   CacheManager: () => CacheManager,
   CategoriesClient: () => CategoriesClient,
   CheckoutClient: () => CheckoutClient,
+  CloudflareKVCacheAdapter: () => CloudflareKVCacheAdapter,
   ContactClient: () => ContactClient,
   ContentClient: () => ContentClient,
   DEFAULT_IMAGE_SIZES: () => DEFAULT_IMAGE_SIZES,
@@ -3342,9 +3343,11 @@ var PerspectV2Error = class extends Error {
 var BaseV2Client = 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;
   }
   buildPath(endpoint) {
     const clean = endpoint.replace(/^\//, "");
@@ -3386,15 +3389,21 @@ var BaseV2Client = class {
     }
     return payload;
   }
-  /** GET a single resource. */
-  async getOne(path, params) {
-    const response = await this.http.get(path, this.toParams(params));
-    return this.extractData(response);
+  /** GET a single resource, with optional caching. */
+  async getOne(path, params, cachePolicy) {
+    const fetcher = async () => {
+      const response = await this.http.get(path, this.toParams(params));
+      return this.extractData(response);
+    };
+    return this.fetchWithCache(path, params, cachePolicy, fetcher);
   }
-  /** GET a list of resources with cursor pagination. */
-  async getList(path, params) {
-    const response = await this.http.get(path, this.toParams(params));
-    return this.extractData(response);
+  /** GET a list of resources with cursor pagination, with optional caching. */
+  async getList(path, params, cachePolicy) {
+    const fetcher = async () => {
+      const response = await this.http.get(path, this.toParams(params));
+      return this.extractData(response);
+    };
+    return this.fetchWithCache(path, params, cachePolicy, fetcher);
   }
   /** POST to create a resource. */
   async post(path, body) {
@@ -3411,6 +3420,33 @@ var BaseV2Client = class {
     const response = await this.http.delete(path);
     return this.extractData(response);
   }
+  /** Fetch with optional cache. Bypasses cache for writes or when no cache is configured. */
+  async fetchWithCache(path, params, policy, fetcher) {
+    if (!this.cache || policy?.skipCache) {
+      return fetcher();
+    }
+    const key = this.buildCacheKey(path, params);
+    return this.cache.getOrSet(key, fetcher, policy);
+  }
+  /** Invalidate cache entries by keys or tags. */
+  async invalidateCache(options) {
+    if (!this.cache) return;
+    await this.cache.invalidate(options);
+  }
+  buildCacheKey(path, params) {
+    const parts = [path];
+    if (params && Object.keys(params).length > 0) {
+      const sorted = {};
+      for (const key of Object.keys(params).sort()) {
+        sorted[key] = params[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.
@@ -3451,14 +3487,14 @@ var BaseV2Client = class {
 
 // src/v2/client/content-client.ts
 var ContentV2Client = class extends BaseV2Client {
-  async list(siteName, params) {
-    return this.getList(this.sitePath(siteName, "content"), params);
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "content"), params, cachePolicy);
   }
   async *listAutoPaginated(siteName, params) {
     yield* this.listAutoPaginate(this.sitePath(siteName, "content"), params);
   }
-  async get(siteName, idOrSlug) {
-    return this.getOne(this.sitePath(siteName, "content", idOrSlug));
+  async get(siteName, idOrSlug, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "content", idOrSlug), void 0, cachePolicy);
   }
   async create(siteName, data) {
     return this.post(this.sitePath(siteName, "content"), data);
@@ -3479,14 +3515,14 @@ var ContentV2Client = class extends BaseV2Client {
 
 // src/v2/client/products-client.ts
 var ProductsV2Client = class extends BaseV2Client {
-  async list(siteName, params) {
-    return this.getList(this.sitePath(siteName, "products"), params);
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "products"), params, cachePolicy);
   }
   async *listAutoPaginated(siteName, params) {
     yield* this.listAutoPaginate(this.sitePath(siteName, "products"), params);
   }
-  async get(siteName, idOrSlug) {
-    return this.getOne(this.sitePath(siteName, "products", idOrSlug));
+  async get(siteName, idOrSlug, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "products", idOrSlug), void 0, cachePolicy);
   }
   async create(siteName, data) {
     return this.post(this.sitePath(siteName, "products"), data);
@@ -3501,11 +3537,11 @@ var ProductsV2Client = class extends BaseV2Client {
 
 // src/v2/client/categories-client.ts
 var CategoriesV2Client = class extends BaseV2Client {
-  async list(siteName, params) {
-    return this.getList(this.sitePath(siteName, "categories"), params);
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "categories"), params, cachePolicy);
   }
-  async get(siteName, id) {
-    return this.getOne(this.sitePath(siteName, "categories", id));
+  async get(siteName, id, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "categories", id), void 0, cachePolicy);
   }
   async create(siteName, data) {
     return this.post(this.sitePath(siteName, "categories"), data);
@@ -3562,14 +3598,14 @@ var CollectionsV2Client = class extends BaseV2Client {
 
 // src/v2/client/orders-client.ts
 var OrdersV2Client = class extends BaseV2Client {
-  async list(siteName, params) {
-    return this.getList(this.sitePath(siteName, "orders"), params);
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "orders"), params, cachePolicy);
   }
   async *listAutoPaginated(siteName, params) {
     yield* this.listAutoPaginate(this.sitePath(siteName, "orders"), params);
   }
-  async get(siteName, id) {
-    return this.getOne(this.sitePath(siteName, "orders", id));
+  async get(siteName, id, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "orders", id), void 0, cachePolicy);
   }
 };
 
@@ -3629,33 +3665,41 @@ var NewsletterV2Client = class extends BaseV2Client {
     );
   }
   // --- Subscriptions (admin) ---
-  async listSubscriptions(siteName, params) {
+  async listSubscriptions(siteName, params, cachePolicy) {
     return this.getList(
       this.sitePath(siteName, "newsletter", "subscriptions"),
-      params
+      params,
+      cachePolicy
     );
   }
-  async getSubscription(siteName, id) {
+  async getSubscription(siteName, id, cachePolicy) {
     return this.getOne(
-      this.sitePath(siteName, "newsletter", `subscriptions/${id}`)
+      this.sitePath(siteName, "newsletter", `subscriptions/${id}`),
+      void 0,
+      cachePolicy
     );
   }
   // --- Lists ---
-  async listLists(siteName) {
+  async listLists(siteName, cachePolicy) {
     return this.getList(
-      this.sitePath(siteName, "newsletter", "lists")
+      this.sitePath(siteName, "newsletter", "lists"),
+      void 0,
+      cachePolicy
     );
   }
   // --- Campaigns ---
-  async listCampaigns(siteName, params) {
+  async listCampaigns(siteName, params, cachePolicy) {
     return this.getList(
       this.sitePath(siteName, "newsletter", "campaigns"),
-      params
+      params,
+      cachePolicy
     );
   }
-  async getCampaign(siteName, idOrSlug) {
+  async getCampaign(siteName, idOrSlug, cachePolicy) {
     return this.getOne(
-      this.sitePath(siteName, "newsletter", `campaigns/${idOrSlug}`)
+      this.sitePath(siteName, "newsletter", `campaigns/${idOrSlug}`),
+      void 0,
+      cachePolicy
     );
   }
 };
@@ -3728,6 +3772,7 @@ var WebhooksV2Client = class extends BaseV2Client {
 // src/v2/index.ts
 var PerspectApiV2Client = class {
   http;
+  cache;
   content;
   products;
   categories;
@@ -3744,19 +3789,21 @@ var PerspectApiV2Client = class {
     const baseUrl = config.baseUrl.replace(/\/+$/, "");
     const v2BaseUrl = baseUrl.endsWith("/api/v2") ? baseUrl : `${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. */
   setAuth(jwt) {
@@ -3775,6 +3822,35 @@ function createPerspectApiV2Client(config) {
   return new PerspectApiV2Client(config);
 }
 
+// src/cache/cloudflare-kv-adapter.ts
+var CloudflareKVCacheAdapter = class {
+  kv;
+  constructor(kv) {
+    this.kv = kv;
+  }
+  async get(key) {
+    return this.kv.get(key);
+  }
+  async set(key, value, options) {
+    await this.kv.put(key, value, options?.ttlSeconds ? { expirationTtl: options.ttlSeconds } : void 0);
+  }
+  async delete(key) {
+    await this.kv.delete(key);
+  }
+  async deleteMany(keys) {
+    if (this.kv.deleteMultiple) {
+      await this.kv.deleteMultiple(keys);
+    } else {
+      await Promise.all(keys.map((k) => this.kv.delete(k)));
+    }
+  }
+  async clear() {
+    if (this.kv.clear) {
+      await this.kv.clear();
+    }
+  }
+};
+
 // src/utils/image-transform.ts
 var DEFAULT_IMAGE_SIZES = {
   thumbnail: {
@@ -4390,6 +4466,7 @@ async function createCheckoutSession(options) {
   CacheManager,
   CategoriesClient,
   CheckoutClient,
+  CloudflareKVCacheAdapter,
   ContactClient,
   ContentClient,
   DEFAULT_IMAGE_SIZES,

package/dist/index.mjs

@@ -3275,9 +3275,11 @@ var PerspectV2Error = class extends Error {
 var BaseV2Client = 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;
   }
   buildPath(endpoint) {
     const clean = endpoint.replace(/^\//, "");
@@ -3319,15 +3321,21 @@ var BaseV2Client = class {
     }
     return payload;
   }
-  /** GET a single resource. */
-  async getOne(path, params) {
-    const response = await this.http.get(path, this.toParams(params));
-    return this.extractData(response);
+  /** GET a single resource, with optional caching. */
+  async getOne(path, params, cachePolicy) {
+    const fetcher = async () => {
+      const response = await this.http.get(path, this.toParams(params));
+      return this.extractData(response);
+    };
+    return this.fetchWithCache(path, params, cachePolicy, fetcher);
   }
-  /** GET a list of resources with cursor pagination. */
-  async getList(path, params) {
-    const response = await this.http.get(path, this.toParams(params));
-    return this.extractData(response);
+  /** GET a list of resources with cursor pagination, with optional caching. */
+  async getList(path, params, cachePolicy) {
+    const fetcher = async () => {
+      const response = await this.http.get(path, this.toParams(params));
+      return this.extractData(response);
+    };
+    return this.fetchWithCache(path, params, cachePolicy, fetcher);
   }
   /** POST to create a resource. */
   async post(path, body) {
@@ -3344,6 +3352,33 @@ var BaseV2Client = class {
     const response = await this.http.delete(path);
     return this.extractData(response);
   }
+  /** Fetch with optional cache. Bypasses cache for writes or when no cache is configured. */
+  async fetchWithCache(path, params, policy, fetcher) {
+    if (!this.cache || policy?.skipCache) {
+      return fetcher();
+    }
+    const key = this.buildCacheKey(path, params);
+    return this.cache.getOrSet(key, fetcher, policy);
+  }
+  /** Invalidate cache entries by keys or tags. */
+  async invalidateCache(options) {
+    if (!this.cache) return;
+    await this.cache.invalidate(options);
+  }
+  buildCacheKey(path, params) {
+    const parts = [path];
+    if (params && Object.keys(params).length > 0) {
+      const sorted = {};
+      for (const key of Object.keys(params).sort()) {
+        sorted[key] = params[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.
@@ -3384,14 +3419,14 @@ var BaseV2Client = class {
 
 // src/v2/client/content-client.ts
 var ContentV2Client = class extends BaseV2Client {
-  async list(siteName, params) {
-    return this.getList(this.sitePath(siteName, "content"), params);
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "content"), params, cachePolicy);
   }
   async *listAutoPaginated(siteName, params) {
     yield* this.listAutoPaginate(this.sitePath(siteName, "content"), params);
   }
-  async get(siteName, idOrSlug) {
-    return this.getOne(this.sitePath(siteName, "content", idOrSlug));
+  async get(siteName, idOrSlug, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "content", idOrSlug), void 0, cachePolicy);
   }
   async create(siteName, data) {
     return this.post(this.sitePath(siteName, "content"), data);
@@ -3412,14 +3447,14 @@ var ContentV2Client = class extends BaseV2Client {
 
 // src/v2/client/products-client.ts
 var ProductsV2Client = class extends BaseV2Client {
-  async list(siteName, params) {
-    return this.getList(this.sitePath(siteName, "products"), params);
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "products"), params, cachePolicy);
   }
   async *listAutoPaginated(siteName, params) {
     yield* this.listAutoPaginate(this.sitePath(siteName, "products"), params);
   }
-  async get(siteName, idOrSlug) {
-    return this.getOne(this.sitePath(siteName, "products", idOrSlug));
+  async get(siteName, idOrSlug, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "products", idOrSlug), void 0, cachePolicy);
   }
   async create(siteName, data) {
     return this.post(this.sitePath(siteName, "products"), data);
@@ -3434,11 +3469,11 @@ var ProductsV2Client = class extends BaseV2Client {
 
 // src/v2/client/categories-client.ts
 var CategoriesV2Client = class extends BaseV2Client {
-  async list(siteName, params) {
-    return this.getList(this.sitePath(siteName, "categories"), params);
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "categories"), params, cachePolicy);
   }
-  async get(siteName, id) {
-    return this.getOne(this.sitePath(siteName, "categories", id));
+  async get(siteName, id, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "categories", id), void 0, cachePolicy);
   }
   async create(siteName, data) {
     return this.post(this.sitePath(siteName, "categories"), data);
@@ -3495,14 +3530,14 @@ var CollectionsV2Client = class extends BaseV2Client {
 
 // src/v2/client/orders-client.ts
 var OrdersV2Client = class extends BaseV2Client {
-  async list(siteName, params) {
-    return this.getList(this.sitePath(siteName, "orders"), params);
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "orders"), params, cachePolicy);
   }
   async *listAutoPaginated(siteName, params) {
     yield* this.listAutoPaginate(this.sitePath(siteName, "orders"), params);
   }
-  async get(siteName, id) {
-    return this.getOne(this.sitePath(siteName, "orders", id));
+  async get(siteName, id, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "orders", id), void 0, cachePolicy);
   }
 };
 
@@ -3562,33 +3597,41 @@ var NewsletterV2Client = class extends BaseV2Client {
     );
   }
   // --- Subscriptions (admin) ---
-  async listSubscriptions(siteName, params) {
+  async listSubscriptions(siteName, params, cachePolicy) {
     return this.getList(
       this.sitePath(siteName, "newsletter", "subscriptions"),
-      params
+      params,
+      cachePolicy
     );
   }
-  async getSubscription(siteName, id) {
+  async getSubscription(siteName, id, cachePolicy) {
     return this.getOne(
-      this.sitePath(siteName, "newsletter", `subscriptions/${id}`)
+      this.sitePath(siteName, "newsletter", `subscriptions/${id}`),
+      void 0,
+      cachePolicy
     );
   }
   // --- Lists ---
-  async listLists(siteName) {
+  async listLists(siteName, cachePolicy) {
     return this.getList(
-      this.sitePath(siteName, "newsletter", "lists")
+      this.sitePath(siteName, "newsletter", "lists"),
+      void 0,
+      cachePolicy
     );
   }
   // --- Campaigns ---
-  async listCampaigns(siteName, params) {
+  async listCampaigns(siteName, params, cachePolicy) {
     return this.getList(
       this.sitePath(siteName, "newsletter", "campaigns"),
-      params
+      params,
+      cachePolicy
     );
   }
-  async getCampaign(siteName, idOrSlug) {
+  async getCampaign(siteName, idOrSlug, cachePolicy) {
     return this.getOne(
-      this.sitePath(siteName, "newsletter", `campaigns/${idOrSlug}`)
+      this.sitePath(siteName, "newsletter", `campaigns/${idOrSlug}`),
+      void 0,
+      cachePolicy
     );
   }
 };
@@ -3661,6 +3704,7 @@ var WebhooksV2Client = class extends BaseV2Client {
 // src/v2/index.ts
 var PerspectApiV2Client = class {
   http;
+  cache;
   content;
   products;
   categories;
@@ -3677,19 +3721,21 @@ var PerspectApiV2Client = class {
     const baseUrl = config.baseUrl.replace(/\/+$/, "");
     const v2BaseUrl = baseUrl.endsWith("/api/v2") ? baseUrl : `${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. */
   setAuth(jwt) {
@@ -3708,6 +3754,35 @@ function createPerspectApiV2Client(config) {
   return new PerspectApiV2Client(config);
 }
 
+// src/cache/cloudflare-kv-adapter.ts
+var CloudflareKVCacheAdapter = class {
+  kv;
+  constructor(kv) {
+    this.kv = kv;
+  }
+  async get(key) {
+    return this.kv.get(key);
+  }
+  async set(key, value, options) {
+    await this.kv.put(key, value, options?.ttlSeconds ? { expirationTtl: options.ttlSeconds } : void 0);
+  }
+  async delete(key) {
+    await this.kv.delete(key);
+  }
+  async deleteMany(keys) {
+    if (this.kv.deleteMultiple) {
+      await this.kv.deleteMultiple(keys);
+    } else {
+      await Promise.all(keys.map((k) => this.kv.delete(k)));
+    }
+  }
+  async clear() {
+    if (this.kv.clear) {
+      await this.kv.clear();
+    }
+  }
+};
+
 // src/utils/image-transform.ts
 var DEFAULT_IMAGE_SIZES = {
   thumbnail: {
@@ -4322,6 +4397,7 @@ export {
   CacheManager,
   CategoriesClient,
   CheckoutClient,
+  CloudflareKVCacheAdapter,
   ContactClient,
   ContentClient,
   DEFAULT_IMAGE_SIZES,

package/package.json

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

package/src/cache/cloudflare-kv-adapter.ts

@@ -0,0 +1,58 @@
+/**
+ * Adapter that bridges a CacheStorage-compatible KV implementation
+ * (e.g. CloudflareKvAdapter from @perspect/shared) to the SDK's CacheAdapter interface.
+ *
+ * Usage:
+ *   import { CloudflareKvAdapter } from '@perspect/shared';
+ *   import { CloudflareKVCacheAdapter } from 'perspectapi-ts-sdk';
+ *
+ *   const kvAdapter = new CloudflareKvAdapter(env.CACHE_KV);
+ *   const cacheAdapter = new CloudflareKVCacheAdapter(kvAdapter);
+ *
+ * Or pass any object with get/put/delete methods matching Cloudflare KV semantics.
+ */
+
+import type { CacheAdapter } from './types';
+
+/** Minimal interface matching CloudflareKvAdapter / CacheStorage from @perspect/shared. */
+export interface KVLike {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+  deleteMultiple?(keys: string[]): Promise<void>;
+  clear?(): Promise<void>;
+}
+
+export class CloudflareKVCacheAdapter implements CacheAdapter {
+  private kv: KVLike;
+
+  constructor(kv: KVLike) {
+    this.kv = kv;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.kv.get(key);
+  }
+
+  async set(key: string, value: string, options?: { ttlSeconds?: number }): Promise<void> {
+    await this.kv.put(key, value, options?.ttlSeconds ? { expirationTtl: options.ttlSeconds } : undefined);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.kv.delete(key);
+  }
+
+  async deleteMany(keys: string[]): Promise<void> {
+    if (this.kv.deleteMultiple) {
+      await this.kv.deleteMultiple(keys);
+    } else {
+      await Promise.all(keys.map((k) => this.kv.delete(k)));
+    }
+  }
+
+  async clear(): Promise<void> {
+    if (this.kv.clear) {
+      await this.kv.clear();
+    }
+  }
+}

package/src/index.ts

@@ -35,6 +35,7 @@ export { HttpClient, createApiError } from './utils/http-client';
 
 // Cache utilities
 export { CacheManager } from './cache/cache-manager';
+export { CloudflareKVCacheAdapter } from './cache/cloudflare-kv-adapter';
 export { InMemoryCacheAdapter } from './cache/in-memory-adapter';
 export { NoopCacheAdapter } from './cache/noop-adapter';