perspectapi-ts-sdk 2.0.0 → 2.1.0

package/README.md

@@ -148,6 +148,88 @@ export default {
 ```
 
 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.
+
+### Webhook-driven cache invalidation
+
+Most deployments rely on PerspectAPI webhooks to bust cache entries whenever content changes. Your app needs an HTTP endpoint that:
+
+1. Verifies the webhook signature (or shared secret).
+2. Maps the webhook payload to the cache tags that were used when reading data.
+3. Calls `client.cache.invalidate({ tags })`.
+
+Below is a minimal Cloudflare Worker handler; the same flow works in Express, Fastify, etc.—just swap the request parsing.
+
+```ts
+// worker.ts
+import { PerspectApiClient } from 'perspectapi-ts-sdk';
+
+const kvAdapter = (kv: KVNamespace) => ({
+  get: (key: string) => kv.get(key),
+  set: (key: string, value: string, options?: { ttlSeconds?: number }) =>
+    options?.ttlSeconds
+      ? kv.put(key, value, { expirationTtl: options.ttlSeconds })
+      : kv.put(key, value),
+  delete: (key: string) => kv.delete(key),
+});
+
+const perspect = new PerspectApiClient({
+  baseUrl: env.PERSPECT_API_URL,
+  apiKey: env.PERSPECT_API_KEY,
+  cache: { adapter: kvAdapter(env.PERSPECT_CACHE), defaultTtlSeconds: 300 },
+});
+
+type WebhookEvent =
+  | { type: 'product.updated'; site: string; slug?: string; id?: number }
+  | { type: 'content.published'; site: string; slug: string; id: number }
+  | { type: 'category.updated'; site: string; slug: string };
+
+const tagMap: Record<string, (e: WebhookEvent) => string[]> = {
+  'product.updated': event => [
+    `products`,
+    `products:site:${event.site}`,
+    event.slug ? `products:slug:${event.site}:${event.slug}` : '',
+    event.id ? `products:id:${event.id}` : '',
+  ],
+  'content.published': event => [
+    `content`,
+    `content:site:${event.site}`,
+    `content:slug:${event.site}:${event.slug}`,
+    `content:id:${event.id}`,
+  ],
+  'category.updated': event => [
+    `categories`,
+    `categories:site:${event.site}`,
+    `categories:product:${event.site}:${event.slug}`,
+  ],
+};
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/webhooks/perspect' && request.method === 'POST') {
+      const event = (await request.json()) as WebhookEvent;
+
+      // TODO: validate shared secret / signature before proceeding
+
+      const buildTags = tagMap[event.type];
+      if (buildTags) {
+        const tags = buildTags(event).filter(Boolean);
+        if (tags.length) {
+          await perspect.cache.invalidate({ tags });
+        }
+      }
+
+      return new Response(null, { status: 202 });
+    }
+
+    // ...rest of your app
+    return new Response('ok');
+  },
+};
+```
+
+> 🔁 Adjust the `WebhookEvent` union and `tagMap` to match the actual payloads you receive. PerspectAPI webhooks also carry version IDs and environment metadata that you can use for more granular targeting if needed.
 ```
 
 ## Image Transformations

package/dist/index.js

@@ -354,6 +354,7 @@ var CacheManager = class {
   }
   async getOrSet(key, resolveValue, policy) {
     if (!this.enabled || policy?.skipCache) {
+      console.log("[Cache] Cache disabled or skipped", { key, enabled: this.enabled, skipCache: policy?.skipCache });
       const value2 = await resolveValue();
       if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
         await this.set(key, value2, policy);
@@ -365,12 +366,16 @@ var CacheManager = class {
     if (cachedRaw) {
       const entry = this.deserialize(cachedRaw);
       if (!entry.expiresAt || entry.expiresAt > Date.now()) {
+        console.log("[Cache] \u2713 HIT", { key, tags: entry.tags });
         return entry.value;
       }
+      console.log("[Cache] \u2717 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] \u2717 MISS", { key });
     }
     const value = await resolveValue();
     await this.set(key, value, policy);
@@ -388,6 +393,7 @@ var CacheManager = class {
       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 : void 0
     });
@@ -406,34 +412,42 @@ var CacheManager = class {
     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] \u2713 INVALIDATED", { totalEntries: totalInvalidated, keys: options.keys?.length || 0, tags: options.tags?.length || 0 });
   }
   namespacedKey(key) {
     return `${this.keyPrefix}:${key}`;

package/dist/index.mjs

@@ -293,6 +293,7 @@ var CacheManager = class {
   }
   async getOrSet(key, resolveValue, policy) {
     if (!this.enabled || policy?.skipCache) {
+      console.log("[Cache] Cache disabled or skipped", { key, enabled: this.enabled, skipCache: policy?.skipCache });
       const value2 = await resolveValue();
       if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
         await this.set(key, value2, policy);
@@ -304,12 +305,16 @@ var CacheManager = class {
     if (cachedRaw) {
       const entry = this.deserialize(cachedRaw);
       if (!entry.expiresAt || entry.expiresAt > Date.now()) {
+        console.log("[Cache] \u2713 HIT", { key, tags: entry.tags });
         return entry.value;
       }
+      console.log("[Cache] \u2717 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] \u2717 MISS", { key });
     }
     const value = await resolveValue();
     await this.set(key, value, policy);
@@ -327,6 +332,7 @@ var CacheManager = class {
       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 : void 0
     });
@@ -345,34 +351,42 @@ var CacheManager = class {
     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] \u2713 INVALIDATED", { totalEntries: totalInvalidated, keys: options.keys?.length || 0, tags: options.tags?.length || 0 });
   }
   namespacedKey(key) {
     return `${this.keyPrefix}:${key}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "2.0.0",
+  "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

@@ -75,6 +75,7 @@ export class CacheManager {
     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) {
@@ -91,14 +92,18 @@ export class CacheManager {
       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();
@@ -122,6 +127,8 @@ export class CacheManager {
       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,
     });
@@ -144,37 +151,47 @@ export class CacheManager {
       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 {