@actuate-media/cms-core 0.20.0 → 0.22.0

package/dist/cache/__tests__/http.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=http.test.d.ts.map

package/dist/cache/__tests__/http.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.test.d.ts","sourceRoot":"","sources":["../../../src/cache/__tests__/http.test.ts"],"names":[],"mappings":""}

package/dist/cache/__tests__/http.test.js

@@ -0,0 +1,285 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ACTUATE_TAG_ROOT, actuateTag, cacheKeyFor, cachedRead, invalidationTagsForDocumentWrite, invalidationTagsForGlobalWrite, publicReadCacheControl, } from '../http.js';
+import { setActuateConfig } from '../../config/runtime.js';
+// Reset the per-process config global between cases so a publicReads
+// override in one test doesn't leak into the next. The runtime module
+// stores config on globalThis (see runtime.ts header) so vitest's
+// per-file isolation alone isn't enough.
+afterEach(() => {
+    setActuateConfig({});
+});
+describe('actuateTag / tag taxonomy', () => {
+    it('produces canonical tag strings that mirror the SDK output', () => {
+        expect(ACTUATE_TAG_ROOT).toBe('actuate');
+        expect(actuateTag('collection', 'posts')).toBe('actuate:collection:posts');
+        expect(actuateTag('doc', 'abc')).toBe('actuate:doc:abc');
+        expect(actuateTag('global', 'settings')).toBe('actuate:global:settings');
+        expect(actuateTag('path', '/blog/foo')).toBe('actuate:path:/blog/foo');
+    });
+    it('invalidationTagsForDocumentWrite includes root + collection + doc tags', () => {
+        expect(invalidationTagsForDocumentWrite('posts', 'abc')).toEqual([
+            'actuate',
+            'actuate:collection:posts',
+            'actuate:doc:abc',
+        ]);
+    });
+    it('invalidationTagsForGlobalWrite includes root + global tag', () => {
+        expect(invalidationTagsForGlobalWrite('settings')).toEqual([
+            'actuate',
+            'actuate:global:settings',
+        ]);
+    });
+});
+describe('publicReadCacheControl', () => {
+    const apiKeyRequest = () => new Request('https://cms.example.com/api/cms/collections/posts', {
+        headers: { authorization: 'Bearer act_sk_abc123' },
+    });
+    const sessionRequest = () => new Request('https://cms.example.com/api/cms/collections/posts', {
+        // The cookie name is what triggers the session-auth branch — value
+        // and validity don't matter for header-emission rules.
+        headers: { cookie: 'actuate_session=anything; other=x' },
+    });
+    it('returns null when cache config is missing entirely', () => {
+        expect(publicReadCacheControl(apiKeyRequest(), undefined)).toBeNull();
+    });
+    it('returns null when publicReads is not opted in', () => {
+        expect(publicReadCacheControl(apiKeyRequest(), { publicReads: { enabled: false } })).toBeNull();
+    });
+    it('emits public s-maxage when enabled and the request has no session cookie', () => {
+        const value = publicReadCacheControl(apiKeyRequest(), {
+            publicReads: { enabled: true, maxAge: 60, staleWhileRevalidate: 300 },
+        });
+        expect(value).toBe('public, s-maxage=60, stale-while-revalidate=300');
+    });
+    it('applies the documented defaults when maxAge/swr are omitted', () => {
+        const value = publicReadCacheControl(apiKeyRequest(), { publicReads: { enabled: true } });
+        expect(value).toBe('public, s-maxage=60, stale-while-revalidate=300');
+    });
+    it('emits private/no-store for session-cookie requests even when caching is enabled', () => {
+        // This is the security-critical invariant: a shared CDN tier MUST NOT
+        // cache a response that may contain per-user state. Refusing the
+        // public cache here is what makes the rest of the feature safe.
+        const value = publicReadCacheControl(sessionRequest(), {
+            publicReads: { enabled: true, maxAge: 60 },
+        });
+        expect(value).toBe('private, no-store');
+    });
+    it('does not match a cookie whose VALUE happens to contain actuate_session=', () => {
+        const req = new Request('https://cms.example.com/api/cms/collections/posts', {
+            headers: {
+                // Defense-in-depth: an attacker setting another cookie whose value
+                // contains the substring must not flip us into session-cookie mode.
+                cookie: 'analytics=actuate_session=fake; tenant=x',
+            },
+        });
+        expect(publicReadCacheControl(req, { publicReads: { enabled: true } })).toBe('public, s-maxage=60, stale-while-revalidate=300');
+    });
+    it('clamps negative maxAge/swr values to 0 instead of emitting nonsense', () => {
+        const value = publicReadCacheControl(apiKeyRequest(), {
+            publicReads: { enabled: true, maxAge: -10, staleWhileRevalidate: -5 },
+        });
+        expect(value).toBe('public, s-maxage=0, stale-while-revalidate=0');
+    });
+});
+// ─── Runtime cache (layer 3) ─────────────────────────────────────────────
+describe('cacheKeyFor', () => {
+    it('returns the pathname when there is no query string', () => {
+        const req = new Request('https://cms.example.com/api/cms/collections/posts');
+        expect(cacheKeyFor(req)).toBe('/api/cms/collections/posts');
+    });
+    it('appends sorted query params so order does not fragment the cache', () => {
+        const a = new Request('https://cms.example.com/api/cms/collections/posts?page=2&pageSize=20');
+        const b = new Request('https://cms.example.com/api/cms/collections/posts?pageSize=20&page=2');
+        expect(cacheKeyFor(a)).toBe(cacheKeyFor(b));
+        expect(cacheKeyFor(a)).toBe('/api/cms/collections/posts?page=2&pageSize=20');
+    });
+    it('keys populated and non-populated reads independently', () => {
+        const plain = new Request('https://cms.example.com/api/cms/collections/posts/abc');
+        const populated = new Request('https://cms.example.com/api/cms/collections/posts/abc?populate=author');
+        expect(cacheKeyFor(plain)).not.toBe(cacheKeyFor(populated));
+    });
+});
+describe('cachedRead', () => {
+    function makeAdapter(initial) {
+        const store = new Map(Object.entries(initial ?? {}));
+        return {
+            store,
+            calls: { get: [], set: [] },
+            async get(key) {
+                this.calls.get.push(key);
+                return store.get(key);
+            },
+            async set(key, value, options) {
+                this.calls.set.push({ key, ttl: options.ttl, tags: options.tags });
+                store.set(key, value);
+            },
+        };
+    }
+    function jsonWrap(payload) {
+        return new Response(JSON.stringify(payload), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    const anonRequest = () => new Request('https://cms.example.com/api/cms/collections/posts');
+    it('bypasses the cache when no adapter is configured', async () => {
+        const build = vi.fn(async () => ({ data: ['a', 'b'] }));
+        const res = await cachedRead(anonRequest(), {
+            cache: { publicReads: { enabled: true } },
+            tags: ['actuate'],
+            wrap: jsonWrap,
+            build,
+        });
+        expect(res.headers.get('X-Actuate-Cache')).toBeNull();
+        expect(build).toHaveBeenCalledTimes(1);
+        expect(await res.json()).toEqual({ data: ['a', 'b'] });
+    });
+    it('bypasses the cache for session-cookie requests', async () => {
+        const adapter = makeAdapter();
+        const req = new Request('https://cms.example.com/api/cms/collections/posts', {
+            headers: { cookie: 'actuate_session=anything' },
+        });
+        const build = vi.fn(async () => ({ data: 'priv' }));
+        await cachedRead(req, {
+            cache: { runtimeCache: { adapter } },
+            tags: ['actuate', 'actuate:collection:posts'],
+            wrap: jsonWrap,
+            build,
+        });
+        expect(adapter.calls.get).toEqual([]); // never touched the cache
+        expect(adapter.calls.set).toEqual([]);
+        expect(build).toHaveBeenCalledTimes(1);
+    });
+    it('bypasses the cache when the request opts out via Cache-Control: no-cache', async () => {
+        const adapter = makeAdapter({ '/api/cms/collections/posts': { data: ['stale'] } });
+        const req = new Request('https://cms.example.com/api/cms/collections/posts', {
+            headers: { 'cache-control': 'no-cache' },
+        });
+        const build = vi.fn(async () => ({ data: ['fresh'] }));
+        const res = await cachedRead(req, {
+            cache: { runtimeCache: { adapter } },
+            tags: ['actuate'],
+            wrap: jsonWrap,
+            build,
+        });
+        expect(adapter.calls.get).toEqual([]);
+        expect(build).toHaveBeenCalledTimes(1);
+        expect(await res.json()).toEqual({ data: ['fresh'] });
+    });
+    it('returns the cached payload on hit without calling build', async () => {
+        const cached = { data: ['hit'] };
+        const adapter = makeAdapter({ '/api/cms/collections/posts': cached });
+        const build = vi.fn();
+        const res = await cachedRead(anonRequest(), {
+            cache: { runtimeCache: { adapter } },
+            tags: ['actuate', 'actuate:collection:posts'],
+            wrap: jsonWrap,
+            build,
+        });
+        expect(build).not.toHaveBeenCalled();
+        expect(res.headers.get('X-Actuate-Cache')).toBe('HIT');
+        expect(await res.json()).toEqual(cached);
+    });
+    it('runs build on miss and stores the result with tags + ttl', async () => {
+        const adapter = makeAdapter();
+        const payload = { data: ['fresh'] };
+        const build = vi.fn(async () => payload);
+        const res = await cachedRead(anonRequest(), {
+            cache: { runtimeCache: { adapter, ttl: 120 } },
+            tags: ['actuate', 'actuate:collection:posts'],
+            wrap: jsonWrap,
+            build,
+        });
+        expect(build).toHaveBeenCalledTimes(1);
+        expect(adapter.calls.set).toEqual([
+            {
+                key: '/api/cms/collections/posts',
+                ttl: 120,
+                tags: ['actuate', 'actuate:collection:posts'],
+            },
+        ]);
+        expect(res.headers.get('X-Actuate-Cache')).toBe('MISS');
+        expect(await res.json()).toEqual(payload);
+    });
+    it('falls back to defaults when ttl is omitted', async () => {
+        const adapter = makeAdapter();
+        await cachedRead(anonRequest(), {
+            cache: { runtimeCache: { adapter } },
+            tags: ['actuate'],
+            wrap: jsonWrap,
+            build: async () => ({ data: 1 }),
+        });
+        expect(adapter.calls.set[0]?.ttl).toBe(60);
+    });
+    it('never caches a build that returns a Response (e.g. 404)', async () => {
+        const adapter = makeAdapter();
+        const notFound = new Response(JSON.stringify({ error: 'gone' }), { status: 404 });
+        const build = vi.fn(async () => notFound);
+        const res = await cachedRead(anonRequest(), {
+            cache: { runtimeCache: { adapter } },
+            tags: ['actuate'],
+            wrap: jsonWrap,
+            build,
+        });
+        expect(res.status).toBe(404);
+        expect(adapter.calls.set).toEqual([]);
+    });
+    it('degrades to a fresh fetch when adapter.get throws', async () => {
+        const adapter = {
+            async get() {
+                throw new Error('redis down');
+            },
+            async set() {
+                /* unused */
+            },
+        };
+        const errSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const build = vi.fn(async () => ({ data: 'fresh' }));
+        const res = await cachedRead(anonRequest(), {
+            cache: { runtimeCache: { adapter } },
+            tags: ['actuate'],
+            wrap: jsonWrap,
+            build,
+        });
+        expect(build).toHaveBeenCalledTimes(1);
+        expect(await res.json()).toEqual({ data: 'fresh' });
+        expect(errSpy).toHaveBeenCalled();
+        errSpy.mockRestore();
+    });
+    it('swallows adapter.set errors and still returns the fresh result', async () => {
+        const adapter = {
+            async get() {
+                return undefined;
+            },
+            async set() {
+                throw new Error('write fail');
+            },
+        };
+        const errSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const res = await cachedRead(anonRequest(), {
+            cache: { runtimeCache: { adapter } },
+            tags: ['actuate'],
+            wrap: jsonWrap,
+            build: async () => ({ data: 'fresh' }),
+        });
+        expect(await res.json()).toEqual({ data: 'fresh' });
+        expect(res.headers.get('X-Actuate-Cache')).toBe('MISS');
+        expect(errSpy).toHaveBeenCalled();
+        errSpy.mockRestore();
+    });
+    it('skips storing payloads larger than ~1.5 MB to stay under the Vercel ceiling', async () => {
+        const adapter = makeAdapter();
+        // Build a > 1.5 MB payload — ~2 MB worth of repeated string.
+        const huge = { data: { body: 'x'.repeat(2_000_000) } };
+        await cachedRead(anonRequest(), {
+            cache: { runtimeCache: { adapter } },
+            tags: ['actuate'],
+            wrap: jsonWrap,
+            build: async () => huge,
+        });
+        expect(adapter.calls.set).toEqual([]);
+        // ... but the response still returns the fresh data
+        expect(adapter.store.size).toBe(0);
+    });
+});
+//# sourceMappingURL=http.test.js.map

package/dist/cache/__tests__/http.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.test.js","sourceRoot":"","sources":["../../../src/cache/__tests__/http.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC5D,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,UAAU,EACV,gCAAgC,EAChC,8BAA8B,EAC9B,sBAAsB,GACvB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAG1D,qEAAqE;AACrE,sEAAsE;AACtE,kEAAkE;AAClE,yCAAyC;AACzC,SAAS,CAAC,GAAG,EAAE;IACb,gBAAgB,CAAC,EAAW,CAAC,CAAA;AAC/B,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACzC,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QACxC,MAAM,CAAC,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QAC1E,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;QACxD,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAA;QACxE,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAA;IACxE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,CAAC,gCAAgC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;YAC/D,SAAS;YACT,0BAA0B;YAC1B,iBAAiB;SAClB,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,CAAC,8BAA8B,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;YACzD,SAAS;YACT,yBAAyB;SAC1B,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;IACtC,MAAM,aAAa,GAAG,GAAG,EAAE,CACzB,IAAI,OAAO,CAAC,mDAAmD,EAAE;QAC/D,OAAO,EAAE,EAAE,aAAa,EAAE,sBAAsB,EAAE;KACnD,CAAC,CAAA;IAEJ,MAAM,cAAc,GAAG,GAAG,EAAE,CAC1B,IAAI,OAAO,CAAC,mDAAmD,EAAE;QAC/D,mEAAmE;QACnE,uDAAuD;QACvD,OAAO,EAAE,EAAE,MAAM,EAAE,mCAAmC,EAAE;KACzD,CAAC,CAAA;IAEJ,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,CAAC,sBAAsB,CAAC,aAAa,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IACvE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,sBAAsB,CAAC,aAAa,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IACjG,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0EAA0E,EAAE,GAAG,EAAE;QAClF,MAAM,KAAK,GAAG,sBAAsB,CAAC,aAAa,EAAE,EAAE;YACpD,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,oBAAoB,EAAE,GAAG,EAAE;SACtE,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAA;IACvE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACrE,MAAM,KAAK,GAAG,sBAAsB,CAAC,aAAa,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;QACzF,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAA;IACvE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iFAAiF,EAAE,GAAG,EAAE;QACzF,sEAAsE;QACtE,iEAAiE;QACjE,gEAAgE;QAChE,MAAM,KAAK,GAAG,sBAAsB,CAAC,cAAc,EAAE,EAAE;YACrD,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;SAC3C,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;IACzC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;QACjF,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,mDAAmD,EAAE;YAC3E,OAAO,EAAE;gBACP,mEAAmE;gBACnE,oEAAoE;gBACpE,MAAM,EAAE,0CAA0C;aACnD;SACF,CAAC,CAAA;QACF,MAAM,CAAC,sBAAsB,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAC1E,iDAAiD,CAClD,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qEAAqE,EAAE,GAAG,EAAE;QAC7E,MAAM,KAAK,GAAG,sBAAsB,CAAC,aAAa,EAAE,EAAE;YACpD,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,oBAAoB,EAAE,CAAC,CAAC,EAAE;SACtE,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAA;IACpE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,4EAA4E;AAE5E,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,mDAAmD,CAAC,CAAA;QAC5E,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAA;IAC7D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,sEAAsE,CAAC,CAAA;QAC7F,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,sEAAsE,CAAC,CAAA;QAC7F,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;QAC3C,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAA;IAC9E,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,uDAAuD,CAAC,CAAA;QAClF,MAAM,SAAS,GAAG,IAAI,OAAO,CAC3B,uEAAuE,CACxE,CAAA;QACD,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAA;IAC7D,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,SAAS,WAAW,CAAC,OAAiC;QAIpD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAkB,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAA;QACrE,OAAO;YACL,KAAK;YACL,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;YAC3B,KAAK,CAAC,GAAG,CAAC,GAAG;gBACX,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;gBACxB,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACvB,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO;gBAC3B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;gBAClE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACvB,CAAC;SACF,CAAA;IACH,CAAC;IAED,SAAS,QAAQ,CAAC,OAAgB;QAChC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE;YAC3C,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAC,mDAAmD,CAAC,CAAA;IAE1F,EAAE,CAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QAChE,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;QACvD,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE;YAC1C,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAwB;YAC/D,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,IAAI,EAAE,QAAQ;YACd,KAAK;SACN,CAAC,CAAA;QACF,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;QACrD,MAAM,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;QACtC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;IACxD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC9D,MAAM,OAAO,GAAG,WAAW,EAAE,CAAA;QAC7B,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,mDAAmD,EAAE;YAC3E,OAAO,EAAE,EAAE,MAAM,EAAE,0BAA0B,EAAE;SAChD,CAAC,CAAA;QACF,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;QACnD,MAAM,UAAU,CAAC,GAAG,EAAE;YACpB,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;YACpC,IAAI,EAAE,CAAC,SAAS,EAAE,0BAA0B,CAAC;YAC7C,IAAI,EAAE,QAAQ;YACd,KAAK;SACN,CAAC,CAAA;QACF,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA,CAAC,0BAA0B;QAChE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QACrC,MAAM,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;IACxC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0EAA0E,EAAE,KAAK,IAAI,EAAE;QACxF,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,4BAA4B,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAA;QAClF,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,mDAAmD,EAAE;YAC3E,OAAO,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;SACzC,CAAC,CAAA;QACF,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAA;QACtD,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE;YAChC,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;YACpC,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,IAAI,EAAE,QAAQ;YACd,KAAK;SACN,CAAC,CAAA;QACF,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QACrC,MAAM,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;QACtC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,CAAA;QAChC,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,4BAA4B,EAAE,MAAM,EAAE,CAAC,CAAA;QACrE,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;QACrB,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE;YAC1C,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;YACpC,IAAI,EAAE,CAAC,SAAS,EAAE,0BAA0B,CAAC;YAC7C,IAAI,EAAE,QAAQ;YACd,KAAK;SACN,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAA;QACpC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACtD,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0DAA0D,EAAE,KAAK,IAAI,EAAE;QACxE,MAAM,OAAO,GAAG,WAAW,EAAE,CAAA;QAC7B,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,CAAA;QACnC,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,OAAO,CAAC,CAAA;QACxC,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE;YAC1C,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;YAC9C,IAAI,EAAE,CAAC,SAAS,EAAE,0BAA0B,CAAC;YAC7C,IAAI,EAAE,QAAQ;YACd,KAAK;SACN,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;QACtC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;YAChC;gBACE,GAAG,EAAE,4BAA4B;gBACjC,GAAG,EAAE,GAAG;gBACR,IAAI,EAAE,CAAC,SAAS,EAAE,0BAA0B,CAAC;aAC9C;SACF,CAAC,CAAA;QACF,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACvD,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,OAAO,GAAG,WAAW,EAAE,CAAA;QAC7B,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE;YAC9B,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;YACpC,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;SACjC,CAAC,CAAA;QACF,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC5C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,OAAO,GAAG,WAAW,EAAE,CAAA;QAC7B,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;QACjF,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,CAAA;QACzC,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE;YAC1C,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;YACpC,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,IAAI,EAAE,QAAQ;YACd,KAAK;SACN,CAAC,CAAA;QACF,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC5B,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IACvC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;QACjE,MAAM,OAAO,GAAwB;YACnC,KAAK,CAAC,GAAG;gBACP,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAA;YAC/B,CAAC;YACD,KAAK,CAAC,GAAG;gBACP,YAAY;YACd,CAAC;SACF,CAAA;QACD,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACtE,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;QACpD,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE;YAC1C,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;YACpC,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,IAAI,EAAE,QAAQ;YACd,KAAK;SACN,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;QACtC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;QACnD,MAAM,CAAC,MAAM,CAAC,CAAC,gBAAgB,EAAE,CAAA;QACjC,MAAM,CAAC,WAAW,EAAE,CAAA;IACtB,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gEAAgE,EAAE,KAAK,IAAI,EAAE;QAC9E,MAAM,OAAO,GAAwB;YACnC,KAAK,CAAC,GAAG;gBACP,OAAO,SAAS,CAAA;YAClB,CAAC;YACD,KAAK,CAAC,GAAG;gBACP,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAA;YAC/B,CAAC;SACF,CAAA;QACD,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACtE,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE;YAC1C,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;YACpC,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;SACvC,CAAC,CAAA;QACF,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;QACnD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACvD,MAAM,CAAC,MAAM,CAAC,CAAC,gBAAgB,EAAE,CAAA;QACjC,MAAM,CAAC,WAAW,EAAE,CAAA;IACtB,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,6EAA6E,EAAE,KAAK,IAAI,EAAE;QAC3F,MAAM,OAAO,GAAG,WAAW,EAAE,CAAA;QAC7B,6DAA6D;QAC7D,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,EAAE,CAAA;QACtD,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE;YAC9B,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;YACpC,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;SACxB,CAAC,CAAA;QACF,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QACrC,oDAAoD;QACpD,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/cache/http.d.ts

@@ -0,0 +1,119 @@
+/**
+ * HTTP / CDN cache primitives — the server-side mirror of the
+ * `actuateTags()` helper exposed by `@actuate-media/client`.
+ *
+ * These produce the canonical tag strings that:
+ *
+ * 1. The SDK emits on every GET it makes (see
+ *    `packages/client/src/index.ts`), and
+ * 2. The action layer fires through `CacheConfig.onInvalidate` after every
+ *    write so a Next.js host app can call `revalidateTag()` for each one.
+ *
+ * The cms-core in-process cache adapter (`./index.ts`) is a separate
+ * concern and uses its own key/tag taxonomy for in-process bookkeeping —
+ * the two layers never share tag strings.
+ */
+import type { CacheConfig } from '../config/types.js';
+/** A single canonical tag for `revalidateTag()`-style invalidation. */
+export type ActuateTagKind = 'collection' | 'doc' | 'global' | 'path';
+/** The wholesale tag added to every SDK request — panic-button invalidation. */
+export declare const ACTUATE_TAG_ROOT = "actuate";
+/**
+ * Build a single canonical tag (e.g. `actuate:collection:posts`). Mirrors
+ * the SDK's `actuateTag()` so the server can construct invalidation keys
+ * that match what the client will actually invalidate.
+ */
+export declare function actuateTag(kind: ActuateTagKind, slug: string): string;
+/**
+ * Tag set to invalidate after a write. Always includes the wholesale
+ * `actuate` tag plus the narrowest specific tags so consumers who only
+ * tagged broadly (or only tagged narrowly) both pick up the change.
+ *
+ * - `create` / `update` / `delete` on a doc → collection + doc tags.
+ * - `update` on a global → global tag.
+ *
+ * Paths (`actuate:path:<path>`) are intentionally NOT auto-invalidated
+ * here: the server cannot know which paths resolve to which doc without
+ * re-running the resolver, and a stale slug change is a rare-enough
+ * event that the host app should handle it in its own webhook.
+ */
+export declare function invalidationTagsForDocumentWrite(collection: string, documentId: string): string[];
+export declare function invalidationTagsForGlobalWrite(slug: string): string[];
+/**
+ * Build the `Cache-Control` header value for a public read response.
+ *
+ * Rules:
+ *
+ * - Session-cookie authentication ALWAYS returns `private, no-store`.
+ *   Shared CDNs MUST NOT cache per-user responses, full stop.
+ * - When `cache.publicReads.enabled` is false (the default), returns
+ *   null — caller emits no `Cache-Control` header.
+ * - When enabled and the request is unauthenticated or uses an API
+ *   key, returns
+ *   `public, s-maxage=<maxAge>, stale-while-revalidate=<swr>`.
+ *
+ * @param request The inbound request — used to detect session cookies.
+ * @param cache   `ActuateCMSConfig.cache` (may be undefined).
+ * @returns       The `Cache-Control` header value, or null when none should be sent.
+ */
+export declare function publicReadCacheControl(request: Request, cache: CacheConfig | undefined): string | null;
+/**
+ * Returns true when the request carries the Actuate session cookie. We
+ * deliberately check the cookie NAME, not its validity — an expired or
+ * tampered cookie is still associated with a single user agent, so
+ * treating it as "potentially-authenticated" and refusing shared-cache
+ * is the safe default.
+ *
+ * Exported so the runtime-cache layer can reuse the exact same bypass
+ * rule as the CDN-cache layer.
+ */
+export declare function hasSessionCookie(request: Request): boolean;
+/**
+ * Build a stable, content-addressed cache key for a public read.
+ *
+ * - Path-only when the URL has no query (`/api/cms/collections/posts`).
+ * - Path + sorted query when present, so `?page=2&pageSize=20` keys the
+ *   same way regardless of param order.
+ * - Hashing isn't done here — the runtime cache adapter is free to apply
+ *   its own `keyHashFunction` if it cares about key length.
+ *
+ * Exported for tests + custom routes that want to opt into the same
+ * cache layer.
+ */
+export declare function cacheKeyFor(request: Request): string;
+/**
+ * Run a read endpoint through the optional Runtime Cache layer.
+ *
+ * Contract:
+ *   - When `cache.runtimeCache.adapter` is unset, OR the request carries
+ *     a session cookie, OR the caller sent `Cache-Control: no-cache`,
+ *     this helper just invokes `build()` and returns whatever it
+ *     produces (either a `Response` for early-exit cases like 404, or
+ *     plain JSON-able data that gets wrapped via `wrap()`).
+ *   - On cache hit, the cached payload is returned via `wrap(hit, request)`
+ *     so the same CDN-tier `Cache-Control` rules apply. Hits get
+ *     `X-Actuate-Cache: HIT`; misses get `X-Actuate-Cache: MISS`.
+ *   - On cache miss, `build()` runs. If it returns a `Response` (e.g.
+ *     404), that response is passed through untouched — we never cache
+ *     error / not-found shapes. Otherwise the payload is stored under
+ *     the cache key with the supplied tags and TTL.
+ *   - Adapter errors (`get` or `set` throwing) are logged and swallowed.
+ *     The user-visible request never fails because the cache fell over.
+ *   - Payloads larger than ~1.5 MB are not stored — keeps us comfortably
+ *     under the 2 MB Vercel runtime-cache item ceiling.
+ */
+export declare function cachedRead(request: Request, opts: {
+    /** Tag set associated with the cache entry. Must match the SDK + onInvalidate tags. */
+    tags: string[];
+    /**
+     * Produces the payload on cache miss. May short-circuit by returning
+     * a `Response` (e.g. when emitting a 404); that response is never
+     * cached.
+     */
+    build: () => Promise<Response | unknown>;
+    /** Wraps a plain payload into the final `Response`. Typically this calls `jsonWithCache`. */
+    wrap: (payload: unknown, request: Request) => Response;
+    /** Active CMS config. Passed in to keep this helper pure (no `globalThis`). */
+    cache: CacheConfig | undefined;
+}): Promise<Response>;
+//# sourceMappingURL=http.d.ts.map

package/dist/cache/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/cache/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAUrD,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;AAErE,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAEzC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjG;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAErE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,WAAW,GAAG,SAAS,GAC7B,MAAM,GAAG,IAAI,CAef;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAO1D;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAQpD;AAaD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE;IACJ,uFAAuF;IACvF,IAAI,EAAE,MAAM,EAAE,CAAA;IACd;;;;OAIG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,CAAA;IACxC,6FAA6F;IAC7F,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAA;IACtD,+EAA+E;IAC/E,KAAK,EAAE,WAAW,GAAG,SAAS,CAAA;CAC/B,GACA,OAAO,CAAC,QAAQ,CAAC,CAgDnB"}

package/dist/cache/http.js

@@ -0,0 +1,188 @@
+/**
+ * Approximate cap on a single runtime cache entry. Vercel's hard limit
+ * is 2 MB; we stop short so a slightly-larger-than-expected payload
+ * doesn't surface the SDK error path. Anything bigger than this falls
+ * through to a normal DB read on every request — slower, but correct.
+ */
+const MAX_RUNTIME_CACHE_BYTES = 1_500_000;
+/** The wholesale tag added to every SDK request — panic-button invalidation. */
+export const ACTUATE_TAG_ROOT = 'actuate';
+/**
+ * Build a single canonical tag (e.g. `actuate:collection:posts`). Mirrors
+ * the SDK's `actuateTag()` so the server can construct invalidation keys
+ * that match what the client will actually invalidate.
+ */
+export function actuateTag(kind, slug) {
+    return `${ACTUATE_TAG_ROOT}:${kind}:${slug}`;
+}
+/**
+ * Tag set to invalidate after a write. Always includes the wholesale
+ * `actuate` tag plus the narrowest specific tags so consumers who only
+ * tagged broadly (or only tagged narrowly) both pick up the change.
+ *
+ * - `create` / `update` / `delete` on a doc → collection + doc tags.
+ * - `update` on a global → global tag.
+ *
+ * Paths (`actuate:path:<path>`) are intentionally NOT auto-invalidated
+ * here: the server cannot know which paths resolve to which doc without
+ * re-running the resolver, and a stale slug change is a rare-enough
+ * event that the host app should handle it in its own webhook.
+ */
+export function invalidationTagsForDocumentWrite(collection, documentId) {
+    return [ACTUATE_TAG_ROOT, actuateTag('collection', collection), actuateTag('doc', documentId)];
+}
+export function invalidationTagsForGlobalWrite(slug) {
+    return [ACTUATE_TAG_ROOT, actuateTag('global', slug)];
+}
+/**
+ * Build the `Cache-Control` header value for a public read response.
+ *
+ * Rules:
+ *
+ * - Session-cookie authentication ALWAYS returns `private, no-store`.
+ *   Shared CDNs MUST NOT cache per-user responses, full stop.
+ * - When `cache.publicReads.enabled` is false (the default), returns
+ *   null — caller emits no `Cache-Control` header.
+ * - When enabled and the request is unauthenticated or uses an API
+ *   key, returns
+ *   `public, s-maxage=<maxAge>, stale-while-revalidate=<swr>`.
+ *
+ * @param request The inbound request — used to detect session cookies.
+ * @param cache   `ActuateCMSConfig.cache` (may be undefined).
+ * @returns       The `Cache-Control` header value, or null when none should be sent.
+ */
+export function publicReadCacheControl(request, cache) {
+    // Session-cookie auth always opts out of shared caching. This is
+    // non-negotiable: emitting `public` on a session-authed response
+    // could leak admin views to other users on the same CDN tier.
+    if (hasSessionCookie(request)) {
+        return 'private, no-store';
+    }
+    if (!cache?.publicReads?.enabled)
+        return null;
+    const maxAge = cache.publicReads.maxAge ?? 60;
+    const swr = cache.publicReads.staleWhileRevalidate ?? 300;
+    // Clamp negative values to 0 so a misconfigured value doesn't produce
+    // a header the CDN treats as undefined behaviour.
+    const safeMaxAge = Math.max(0, Math.floor(maxAge));
+    const safeSwr = Math.max(0, Math.floor(swr));
+    return `public, s-maxage=${safeMaxAge}, stale-while-revalidate=${safeSwr}`;
+}
+/**
+ * Returns true when the request carries the Actuate session cookie. We
+ * deliberately check the cookie NAME, not its validity — an expired or
+ * tampered cookie is still associated with a single user agent, so
+ * treating it as "potentially-authenticated" and refusing shared-cache
+ * is the safe default.
+ *
+ * Exported so the runtime-cache layer can reuse the exact same bypass
+ * rule as the CDN-cache layer.
+ */
+export function hasSessionCookie(request) {
+    const cookieHeader = request.headers.get('cookie');
+    if (!cookieHeader)
+        return false;
+    // Match `actuate_session=` as a discrete cookie name, not anywhere in
+    // the header text — defense-in-depth against a cookie whose VALUE
+    // happens to contain the substring.
+    return /(?:^|;\s*)actuate_session=/.test(cookieHeader);
+}
+// ─── Runtime cache (layer 3) ────────────────────────────────────────────
+/**
+ * Build a stable, content-addressed cache key for a public read.
+ *
+ * - Path-only when the URL has no query (`/api/cms/collections/posts`).
+ * - Path + sorted query when present, so `?page=2&pageSize=20` keys the
+ *   same way regardless of param order.
+ * - Hashing isn't done here — the runtime cache adapter is free to apply
+ *   its own `keyHashFunction` if it cares about key length.
+ *
+ * Exported for tests + custom routes that want to opt into the same
+ * cache layer.
+ */
+export function cacheKeyFor(request) {
+    const url = new URL(request.url);
+    const params = Array.from(url.searchParams.entries()).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    if (params.length === 0)
+        return url.pathname;
+    const sorted = new URLSearchParams(params).toString();
+    return `${url.pathname}?${sorted}`;
+}
+/**
+ * Returns true when the caller passed `Cache-Control: no-cache` /
+ * `no-store` on the request. Lets debugging tools force a cache miss
+ * without flushing the entire layer.
+ */
+function requestOptedOut(request) {
+    const cc = request.headers.get('cache-control');
+    if (!cc)
+        return false;
+    return /(?:^|,\s*)(no-cache|no-store)\b/i.test(cc);
+}
+/**
+ * Run a read endpoint through the optional Runtime Cache layer.
+ *
+ * Contract:
+ *   - When `cache.runtimeCache.adapter` is unset, OR the request carries
+ *     a session cookie, OR the caller sent `Cache-Control: no-cache`,
+ *     this helper just invokes `build()` and returns whatever it
+ *     produces (either a `Response` for early-exit cases like 404, or
+ *     plain JSON-able data that gets wrapped via `wrap()`).
+ *   - On cache hit, the cached payload is returned via `wrap(hit, request)`
+ *     so the same CDN-tier `Cache-Control` rules apply. Hits get
+ *     `X-Actuate-Cache: HIT`; misses get `X-Actuate-Cache: MISS`.
+ *   - On cache miss, `build()` runs. If it returns a `Response` (e.g.
+ *     404), that response is passed through untouched — we never cache
+ *     error / not-found shapes. Otherwise the payload is stored under
+ *     the cache key with the supplied tags and TTL.
+ *   - Adapter errors (`get` or `set` throwing) are logged and swallowed.
+ *     The user-visible request never fails because the cache fell over.
+ *   - Payloads larger than ~1.5 MB are not stored — keeps us comfortably
+ *     under the 2 MB Vercel runtime-cache item ceiling.
+ */
+export async function cachedRead(request, opts) {
+    const adapter = opts.cache?.runtimeCache?.adapter;
+    const ttl = opts.cache?.runtimeCache?.ttl ?? 60;
+    // Bypass paths — no adapter, per-user request, or explicit opt-out.
+    if (!adapter || hasSessionCookie(request) || requestOptedOut(request)) {
+        const r = await opts.build();
+        return r instanceof Response ? r : opts.wrap(r, request);
+    }
+    const key = cacheKeyFor(request);
+    let hit;
+    try {
+        hit = await adapter.get(key);
+    }
+    catch (err) {
+        // Read failures never break the request — fall through to a fresh fetch.
+        console.error('[actuate][cache] runtime cache get failed', err);
+        const r = await opts.build();
+        return r instanceof Response ? r : opts.wrap(r, request);
+    }
+    if (hit !== undefined && hit !== null) {
+        const res = opts.wrap(hit, request);
+        res.headers.set('X-Actuate-Cache', 'HIT');
+        return res;
+    }
+    const r = await opts.build();
+    if (r instanceof Response)
+        return r; // 404 / error — never cache.
+    try {
+        // Approximate size by serialised length; the runtime cache adapter
+        // will JSON-stringify again on its way out, so the work isn't
+        // duplicated wastefully — and a known-too-big payload skips the
+        // write call entirely.
+        const size = JSON.stringify(r)?.length ?? 0;
+        if (size > 0 && size <= MAX_RUNTIME_CACHE_BYTES) {
+            await adapter.set(key, r, { ttl, tags: opts.tags });
+        }
+    }
+    catch (err) {
+        // Write failures never break the request either — log and move on.
+        console.error('[actuate][cache] runtime cache set failed', err);
+    }
+    const res = opts.wrap(r, request);
+    res.headers.set('X-Actuate-Cache', 'MISS');
+    return res;
+}
+//# sourceMappingURL=http.js.map

package/dist/cache/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/cache/http.ts"],"names":[],"mappings":"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"}