perspectapi-ts-sdk 6.5.9 → 7.0.0

package/docs/v1-deprecated/legacy-docs/caching.md

@@ -0,0 +1,667 @@
+# Caching and Invalidation in PerspectAPI SDK
+
+> Deprecated v1 material. Do not copy these examples into new code. v1 sunsets
+> on 2026-06-01; use `createPerspectApiV2Client` from
+> `perspectapi-ts-sdk/v2` and `/api/v2`.
+
+This document covers how to configure, use, and invalidate the cache in the PerspectAPI TypeScript SDK.
+
+## Configuration
+
+Enable caching when creating the client:
+
+```typescript
+import { PerspectApiClient } from 'perspectapi-ts-sdk';
+
+const client = new PerspectApiClient({
+  baseUrl: 'https://api.perspect.commm',
+  apiKey: 'your-api-key',
+  cache: {
+    enabled: true,
+    defaultTtlSeconds: 300,  // 5 minutes
+    keyPrefix: 'perspectapi'
+  }
+});
+```
+
+### Infinite (Non-Expiring) Caching
+
+To cache indefinitely (until you explicitly invalidate), set `defaultTtlSeconds` to `0`:
+
+```typescript
+import { PerspectApiClient } from 'perspectapi-ts-sdk';
+
+const client = new PerspectApiClient({
+  baseUrl: 'https://api.perspect.commm',
+  apiKey: 'your-api-key',
+  cache: {
+    enabled: true,
+    defaultTtlSeconds: 0,
+    keyPrefix: 'perspectapi'
+  }
+});
+```
+
+With `defaultTtlSeconds: 0`, cached entries do not expire based on time. They will remain cached until:
+
+- **You invalidate them** via tags/keys.
+- **Your underlying cache adapter evicts them** (for example due to memory limits).
+
+### Cache Adapters
+
+The SDK supports pluggable cache adapters:
+
+- **Memory adapter** (default): In-memory cache, suitable for development
+- **Custom adapters**: Implement the `CacheAdapter` interface for Redis, Cloudflare KV, etc.
+
+## How Caching Works
+
+### Automatic Caching on Reads
+
+All GET requests through the content, products, and newsletter clients are automatically cached with appropriate tags:
+
+```typescript
+// This response is cached automatically
+const content = await client.content.getContent('my-site', {
+  page_status: 'publish',
+  limit: 20
+});
+
+// Subsequent calls with the same parameters return cached data
+const cachedContent = await client.content.getContent('my-site', {
+  page_status: 'publish',
+  limit: 20
+});
+
+// Newsletter list + campaign endpoints are cached too
+const campaigns = await client.newsletter.getPublishedCampaigns('my-site', {
+  page: 1,
+  limit: 20
+});
+const sameCampaigns = await client.newsletter.getPublishedCampaigns('my-site', {
+  page: 1,
+  limit: 20
+});
+const campaign = await client.newsletter.getPublishedCampaignBySlug(
+  'my-site',
+  'spring-launch',
+  { slugPrefix: 'updates' }
+);
+```
+
+### Cache Keys
+
+Cache keys are built from:
+1. The API base path
+2. The endpoint
+3. Query parameters (sorted for consistency)
+
+Example key: `perspectapi:api/v1:sites/my-site:{"limit":20,"page_status":"publish"}`
+
+### Cache Tags
+
+Every cached entry is tagged for targeted invalidation. Tags follow a hierarchical pattern:
+
+| Tag Pattern | Description |
+|-------------|-------------|
+| `content` | All content entries |
+| `content:site:{siteName}` | All content for a specific site |
+| `content:slug:{siteName}:{slug}` | A specific content item by slug |
+| `content:id:{id}` | A specific content item by ID |
+| `content:prefix:{prefix}` | All content with a specific slug prefix |
+| `products` | All product entries |
+| `products:site:{siteName}` | All products for a specific site |
+| `products:slug:{siteName}:{slug}` | A specific product by slug |
+| `products:id:{id}` | A specific product by ID |
+| `products:prefix:{prefix}` | All products with a specific slug prefix |
+| `products:list` | Product list queries |
+| `products:category` | Category-filtered product queries |
+| `products:category:{siteName}:{slug}` | Products in a specific category |
+| `newsletter` | All newsletter entries |
+| `newsletter:site:{siteName}` | All newsletter entries for a specific site |
+| `newsletter:lists` | Newsletter list queries |
+| `newsletter:lists:site:{siteName}` | Newsletter lists for a specific site |
+| `newsletter:campaigns` | Published newsletter campaign queries |
+| `newsletter:campaigns:list:{siteName}` | Published campaign list queries for a site |
+| `newsletter:campaigns:detail:{siteName}` | Published campaign detail queries for a site |
+| `newsletter:campaigns:slug:{siteName}:{slug}` | A specific published campaign by slug |
+| `newsletter:campaigns:id:{siteName}:{campaignId}` | A specific published campaign by campaign ID |
+| `newsletter:prefix:{prefix}` | Newsletter entries with a specific slug prefix |
+
+## Cache Policies
+
+Override default caching behavior per-request:
+
+```typescript
+// Skip cache entirely
+const fresh = await client.content.getContent('my-site', params, {
+  skipCache: true
+});
+
+// Custom TTL
+const shortLived = await client.content.getContent('my-site', params, {
+  ttlSeconds: 60
+});
+
+// Cache indefinitely for this request (until invalidation)
+const cachedForever = await client.content.getContent('my-site', params, {
+  ttlSeconds: 0
+});
+
+// Add extra tags
+const tagged = await client.content.getContent('my-site', params, {
+  tags: ['homepage', 'featured']
+});
+```
+
+## Invalidation
+
+### By Tags
+
+Invalidate all cache entries matching specific tags:
+
+```typescript
+// Invalidate all content for a site
+await cacheManager.invalidate({
+  tags: ['content:site:my-site']
+});
+
+// Invalidate a specific content item
+await cacheManager.invalidate({
+  tags: ['content:slug:my-site:blog/my-post']
+});
+
+// Invalidate multiple tags at once
+await cacheManager.invalidate({
+  tags: ['content:site:my-site', 'products:site:my-site']
+});
+```
+
+### By Keys
+
+Invalidate specific cache keys directly:
+
+```typescript
+await cacheManager.invalidate({
+  keys: ['perspectapi:api/v1:sites/my-site:{"limit":20}']
+});
+```
+
+### Webhook-Driven Invalidation for Newsletters
+
+The newsletter client includes a helper that converts webhook payloads to the correct cache tags and invalidates them for you.
+
+```typescript
+const result = await client.newsletter.invalidatePublishedCampaignCacheFromWebhook(
+  webhookPayload,
+  'my-site' // optional fallback when payload omits site name
+);
+
+if (result.invalidated) {
+  console.log('Invalidated tags:', result.tags);
+}
+```
+
+`invalidatePublishedCampaignCacheFromWebhook` intentionally invalidates only publish events (for example `newsletter.published`, `newsletter_campaign.published`, or `content.published` with `origin_type = newsletter_campaign`). Create/draft updates are ignored.
+
+---
+
+## Slug Prefix Caching
+
+### What is a Slug Prefix?
+
+A slug prefix is the first path segment of a hierarchical slug. For example:
+
+| Full Slug | Prefix |
+|-----------|--------|
+| `blog/my-first-post` | `blog` |
+| `blog/2024/annual-review` | `blog` |
+| `shop/electronics/laptop` | `shop` |
+| `about` | *(none)* |
+
+Slug prefixes are commonly used to organize content by section (blog, shop, docs) or by language (en, es, fr).
+
+### Why Cache by Slug Prefix?
+
+Consider a site with this content structure:
+
+```
+/blog/post-1
+/blog/post-2
+/blog/post-3
+/shop/product-a
+/shop/product-b
+/about
+/contact
+```
+
+When a blog post is updated, you need to invalidate:
+1. The individual post cache (`content:slug:my-site:blog/post-1`)
+2. Any list queries that included that post
+
+Without prefix tagging, you'd have to either:
+- Invalidate ALL content caches (too broad, poor cache hit rate)
+- Track every list query that might include the post (complex and error-prone)
+
+With prefix tagging, you can surgically invalidate just the blog section:
+
+```typescript
+await cacheManager.invalidate({
+  tags: ['content:prefix:blog']
+});
+```
+
+This invalidates:
+- All blog post individual page caches
+- All list queries filtered by `slug_prefix: 'blog'`
+
+But preserves:
+- Shop product caches
+- Other page caches (`/about`, `/contact`)
+- List queries for other prefixes
+
+### How Prefix Tags Are Applied
+
+#### List Queries
+
+When fetching lists with a `slug_prefix` parameter, the cache is tagged with that prefix:
+
+```typescript
+// Tagged with: content, content:site:my-site, content:prefix:blog
+const blogPosts = await client.content.getContent('my-site', {
+  slug_prefix: 'blog',
+  page_status: 'publish'
+});
+
+// Tagged with: products, products:site:my-site, products:prefix:shop, products:list
+const shopProducts = await client.products.getProducts('my-site', {
+  slug_prefix: 'shop'
+});
+```
+
+#### Individual Item Fetches
+
+When fetching by slug, the prefix is automatically extracted:
+
+```typescript
+// Tagged with: content, content:site:my-site, content:slug:my-site:blog/my-post, content:prefix:blog
+const post = await client.content.getContentBySlug('my-site', 'blog/my-post');
+
+// Tagged with: products, products:site:my-site, products:slug:my-site:shop/widget, products:prefix:shop
+const product = await client.products.getProductBySlug('my-site', 'shop/widget');
+```
+
+### Invalidation Patterns
+
+#### When a single item changes
+
+```typescript
+// Invalidate the specific item AND all prefix-filtered lists
+await cacheManager.invalidate({
+  tags: [
+    'content:slug:my-site:blog/my-post',  // The specific post
+    'content:prefix:blog'                  // All blog lists and posts
+  ]
+});
+```
+
+#### When rebuilding a section
+
+```typescript
+// Invalidate everything under the 'docs' prefix
+await cacheManager.invalidate({
+  tags: ['content:prefix:docs']
+});
+```
+
+#### When a new item is added
+
+Adding a new item to a prefix section should invalidate list queries:
+
+```typescript
+// New blog post added - invalidate blog lists so they include the new post
+await cacheManager.invalidate({
+  tags: ['content:prefix:blog']
+});
+```
+
+#### Site-wide content update
+
+```typescript
+// Nuclear option: invalidate all content for a site
+await cacheManager.invalidate({
+  tags: ['content:site:my-site']
+});
+```
+
+### Multi-Language Sites
+
+Slug prefixes work well for language-segmented sites:
+
+```typescript
+// Fetch English content
+const enContent = await client.content.getContent('my-site', {
+  slug_prefix: 'en'
+});
+
+// Fetch Spanish content
+const esContent = await client.content.getContent('my-site', {
+  slug_prefix: 'es'
+});
+
+// Invalidate only Spanish content after translation update
+await cacheManager.invalidate({
+  tags: ['content:prefix:es']
+});
+```
+
+### Best Practices
+
+1. **Use consistent prefix conventions**: Establish a clear URL structure (`/blog/*`, `/shop/*`, `/docs/*`) and stick to it.
+
+2. **Invalidate by prefix when content changes**: When a CMS webhook fires for a content update, extract the prefix from the slug and invalidate that prefix tag.
+
+3. **Don't over-invalidate**: Use the most specific tag that covers the affected content. Prefer `content:prefix:blog` over `content:site:my-site` when only blog content changed.
+
+4. **Combine with item-specific tags**: For single-item updates, invalidate both the specific item and the prefix to ensure both individual fetches and list queries are refreshed.
+
+```typescript
+// Recommended pattern for content updates
+async function onContentUpdated(siteName: string, slug: string) {
+  const prefix = slug.includes('/') ? slug.split('/')[0] : null;
+
+  const tags = [`content:slug:${siteName}:${slug}`];
+  if (prefix) {
+    tags.push(`content:prefix:${prefix}`);
+  }
+
+  await cacheManager.invalidate({ tags });
+}
+```
+
+5. **Consider prefix hierarchies**: If you have nested prefixes like `docs/api/v1/*`, the SDK tags with the first segment (`docs`). For more granular control, use custom tags via cache policies.
+
+---
+
+## Granular Caching and Invalidation
+
+**Always prefer the most specific invalidation possible.** Over-invalidating defeats the purpose of caching and can cause unnecessary load on your API. Under-invalidating leads to stale data.
+
+### The Granularity Hierarchy
+
+From most specific (preferred) to least specific (avoid when possible):
+
+| Level | Tag Pattern | Use When |
+|-------|-------------|----------|
+| 1. Item | `content:slug:my-site:blog/post-1` | A single item changed |
+| 2. Prefix | `content:prefix:blog` | Multiple items in a section changed |
+| 3. Site | `content:site:my-site` | Site-wide changes (settings, theme) |
+| 4. Global | `content` | Schema changes, migrations |
+
+### ❌ Anti-Pattern: Over-Invalidation
+
+```typescript
+// BAD: Invalidates ALL content when only one post changed
+async function onBlogPostUpdated(siteName: string, slug: string) {
+  await cacheManager.invalidate({
+    tags: ['content:site:my-site']  // Nukes everything!
+  });
+}
+```
+
+This invalidates:
+- All blog posts (intended)
+- All shop pages (unnecessary)
+- All static pages (unnecessary)
+- All list queries (unnecessary)
+
+**Result**: Poor cache hit rate, increased API load, slower page loads.
+
+### ✅ Correct Pattern: Targeted Invalidation
+
+```typescript
+// GOOD: Invalidates only what's affected
+async function onBlogPostUpdated(siteName: string, slug: string) {
+  const prefix = slug.includes('/') ? slug.split('/')[0] : null;
+  
+  const tags = [`content:slug:${siteName}:${slug}`];
+  if (prefix) {
+    tags.push(`content:prefix:${prefix}`);
+  }
+  
+  await cacheManager.invalidate({ tags });
+}
+```
+
+This invalidates:
+- The specific post (`content:slug:my-site:blog/post-1`)
+- Blog list queries (`content:prefix:blog`)
+
+**Result**: Shop pages, static pages, and other sections remain cached.
+
+### Real-World Invalidation Scenarios
+
+#### Scenario 1: Single Blog Post Edit
+
+A user edits the title of `blog/my-post`.
+
+```typescript
+// Invalidate the post and any lists that might show it
+await cacheManager.invalidate({
+  tags: [
+    'content:slug:my-site:blog/my-post',
+    'content:prefix:blog'
+  ]
+});
+```
+
+#### Scenario 2: New Product Added to Category
+
+A new product is added to the "electronics" category.
+
+```typescript
+// Invalidate category listings, not individual product pages
+await cacheManager.invalidate({
+  tags: [
+    'products:category:my-site:electronics',
+    'products:prefix:shop'  // If products use shop/* slugs
+  ]
+});
+```
+
+#### Scenario 3: Product Price Update
+
+Only the price of a specific product changed.
+
+```typescript
+// Invalidate just that product - lists showing price need refresh too
+await cacheManager.invalidate({
+  tags: [
+    'products:slug:my-site:shop/widget-pro',
+    'products:id:prod_12345'
+  ]
+});
+```
+
+#### Scenario 4: Bulk Import of Blog Posts
+
+50 new blog posts were imported.
+
+```typescript
+// Prefix invalidation is appropriate here
+await cacheManager.invalidate({
+  tags: ['content:prefix:blog']
+});
+```
+
+#### Scenario 5: Site Settings Changed (Logo, Footer)
+
+Global site settings affect all pages.
+
+```typescript
+// Site-wide invalidation is justified
+await cacheManager.invalidate({
+  tags: ['content:site:my-site', 'products:site:my-site']
+});
+```
+
+### List Invalidation by Slug Prefix
+
+When content is fetched with a `slug_prefix` parameter, the SDK automatically tags that cached response with `content:prefix:{prefix}`. This is the key mechanism for invalidating lists when new items are created.
+
+**How it works:**
+
+```typescript
+// This list query gets tagged with: content:prefix:blog
+const blogPosts = await client.content.getContent('my-site', {
+  slug_prefix: 'blog',
+  page_status: 'publish',
+  limit: 10
+});
+```
+
+When a new post `blog/new-article` is created, invalidating `content:prefix:blog` will:
+- Clear the cached list above (so the next fetch includes the new post)
+- Clear any other cached lists filtered by `slug_prefix: 'blog'`
+- Clear individual post caches under the `blog/` prefix
+
+**Example: New content created with a slug prefix**
+
+```typescript
+// A new blog post is created: blog/exciting-news
+async function onContentCreated(siteName: string, slug: string) {
+  const prefix = slug.includes('/') ? slug.split('/')[0] : null;
+  
+  if (prefix) {
+    // Invalidate ALL cached lists that used this prefix
+    // This ensures the new post appears in list queries
+    await cacheManager.invalidate({
+      tags: [`content:prefix:${prefix}`]
+    });
+  } else {
+    // Root-level content (no prefix) - must invalidate site-wide lists
+    await cacheManager.invalidate({
+      tags: [`content:site:${siteName}`]
+    });
+  }
+}
+
+// When blog/exciting-news is created:
+// - Invalidates: content:prefix:blog
+// - Clears: all cached getContent() calls with slug_prefix: 'blog'
+// - Preserves: shop/* caches, docs/* caches, individual non-blog pages
+```
+
+**Why this matters:**
+
+Without prefix-based list invalidation, you'd face a dilemma:
+1. **Over-invalidate**: Clear all site content caches (wasteful)
+2. **Under-invalidate**: Only clear the new item's cache (lists show stale data, missing the new post)
+
+The prefix tag gives you the middle ground: invalidate only the lists that could contain the new item.
+
+### Using Custom Tags for Fine-Grained Control
+
+When built-in tags aren't granular enough, add custom tags:
+
+```typescript
+// Tag featured content separately
+const featured = await client.content.getContent('my-site', 
+  { page_status: 'publish', limit: 5 },
+  { tags: ['homepage:featured'] }
+);
+
+// Tag sidebar content
+const sidebar = await client.content.getContent('my-site',
+  { slug_prefix: 'widgets' },
+  { tags: ['layout:sidebar'] }
+);
+
+// Invalidate only homepage featured section
+await cacheManager.invalidate({
+  tags: ['homepage:featured']
+});
+```
+
+### Webhook Integration Example
+
+Here's a complete example for handling CMS webhooks with granular invalidation:
+
+```typescript
+import { CacheManager } from 'perspectapi-ts-sdk';
+
+interface WebhookPayload {
+  event: 'content.created' | 'content.updated' | 'content.deleted' | 'content.bulk_update';
+  site: string;
+  slug?: string;
+  id?: string;
+  prefix?: string;  // For bulk operations
+}
+
+async function handleWebhook(payload: WebhookPayload, cacheManager: CacheManager) {
+  const { event, site, slug, id, prefix } = payload;
+  
+  switch (event) {
+    case 'content.created':
+    case 'content.deleted':
+      // New/deleted items affect list queries
+      if (slug) {
+        const slugPrefix = slug.includes('/') ? slug.split('/')[0] : null;
+        await cacheManager.invalidate({
+          tags: slugPrefix 
+            ? [`content:prefix:${slugPrefix}`]
+            : [`content:site:${site}`]  // Fallback for root-level content
+        });
+      }
+      break;
+      
+    case 'content.updated':
+      // Updated items: invalidate specific item + relevant lists
+      const tags: string[] = [];
+      if (slug) {
+        tags.push(`content:slug:${site}:${slug}`);
+        const slugPrefix = slug.includes('/') ? slug.split('/')[0] : null;
+        if (slugPrefix) {
+          tags.push(`content:prefix:${slugPrefix}`);
+        }
+      }
+      if (id) {
+        tags.push(`content:id:${id}`);
+      }
+      if (tags.length > 0) {
+        await cacheManager.invalidate({ tags });
+      }
+      break;
+      
+    case 'content.bulk_update':
+      // Bulk operations: use prefix if provided, otherwise site-wide
+      await cacheManager.invalidate({
+        tags: prefix 
+          ? [`content:prefix:${prefix}`]
+          : [`content:site:${site}`]
+      });
+      break;
+  }
+}
+```
+
+### Monitoring Cache Effectiveness
+
+Track these metrics to ensure your invalidation strategy is working:
+
+1. **Cache hit rate**: Should be >80% for read-heavy sites
+2. **Invalidation frequency**: Spikes may indicate over-invalidation
+3. **Stale content reports**: May indicate under-invalidation
+
+```typescript
+// Example: Log invalidation events for monitoring
+async function invalidateWithLogging(
+  cacheManager: CacheManager, 
+  tags: string[]
+) {
+  console.log(`[Cache] Invalidating tags: ${tags.join(', ')}`);
+  const start = Date.now();
+  await cacheManager.invalidate({ tags });
+  console.log(`[Cache] Invalidation completed in ${Date.now() - start}ms`);
+}
+```