@prenta/core 0.118.0

package/dist/billing/stripe-meter.js

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto';
+import { createLogger } from '../diagnostics/logger.js';
+const logger = createLogger('billing');
+function resolveMeterConfig(kind) {
+    const secretKey = process.env.STRIPE_SECRET_KEY?.trim();
+    const customerId = process.env.STRIPE_BILLING_CUSTOMER_ID?.trim();
+    if (!secretKey || !customerId)
+        return null;
+    const eventName = kind === 'ai_tokens'
+        ? process.env.STRIPE_METER_AI_TOKENS?.trim()
+        : process.env.STRIPE_METER_SEO_CALLS?.trim();
+    if (!eventName)
+        return null;
+    return { secretKey, customerId, eventName };
+}
+function buildIdempotencyKey(parts) {
+    const raw = parts.filter((p) => p !== undefined && p !== '').join(':');
+    return createHash('sha256').update(raw).digest('hex').slice(0, 32);
+}
+/** Fire-and-forget Stripe Billing Meter event. No-op when billing env is unset. Never throws. */
+export async function emitUsageMeterEvent(event) {
+    const config = resolveMeterConfig(event.kind);
+    if (!config || event.quantity <= 0)
+        return;
+    const body = new URLSearchParams({
+        event_name: config.eventName,
+        identifier: event.idempotencyKey,
+        'payload[stripe_customer_id]': config.customerId,
+        'payload[value]': String(Math.round(event.quantity)),
+    });
+    if (event.userId)
+        body.set('payload[prenta_user_id]', event.userId);
+    if (event.metadata) {
+        for (const [key, value] of Object.entries(event.metadata)) {
+            if (value)
+                body.set(`payload[${key}]`, value);
+        }
+    }
+    try {
+        const res = await fetch('https://api.stripe.com/v1/billing/meter_events', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${config.secretKey}`,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: body.toString(),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            logger.warn('Stripe meter event rejected', {
+                kind: event.kind,
+                status: res.status,
+                body: text.slice(0, 200),
+            });
+        }
+    }
+    catch (err) {
+        logger.warn('Stripe meter event failed', {
+            kind: event.kind,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+export function emitAiTokenMeterEvent(input) {
+    void emitUsageMeterEvent({
+        kind: 'ai_tokens',
+        quantity: input.totalTokens,
+        userId: input.userId,
+        idempotencyKey: buildIdempotencyKey([
+            'ai_tokens',
+            input.userId,
+            input.featureKey,
+            input.modelId,
+            input.totalTokens,
+            Date.now(),
+        ]),
+        metadata: {
+            feature: input.featureKey,
+            model: input.modelId,
+        },
+    });
+}
+export function emitSeoAiCallMeterEvent(input) {
+    void emitUsageMeterEvent({
+        kind: 'seo_ai_calls',
+        quantity: 1,
+        userId: input.userId,
+        idempotencyKey: buildIdempotencyKey([
+            'seo_ai_calls',
+            input.userId,
+            input.action,
+            input.issueId,
+            Date.now(),
+        ]),
+        metadata: {
+            action: input.action,
+            ...(input.issueId ? { issue_id: input.issueId } : {}),
+        },
+    });
+}
+//# sourceMappingURL=stripe-meter.js.map

package/dist/billing/stripe-meter.js.map

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

package/dist/brand-voice/index.d.ts

@@ -0,0 +1,7 @@
+export { BRAND_VOICE_DOCUMENT_MAX, BRAND_VOICE_EXPORT_FILENAME, applyParsedDocumentToProfile, deriveBrandVoiceFields, ensureBrandVoiceDocument, parseBrandVoiceDocument, serializeBrandVoiceDocument, splitBrandVoiceDocument, syncFieldsFromDocument, type BrandVoiceDocumentFields, type BrandVoiceDocumentMeta, type BrandVoiceDocumentStatus, type ParsedBrandVoiceDocument, type ParseBrandVoiceDocumentError, type ParseBrandVoiceDocumentResult, } from '../ai/brand-voice-document.js';
+export { prepareBrandVoiceForSave } from '../ai/brand-voice-save.js';
+export { alignContentWithBrandVoice, COAUTHOR_BRAND_CHANNEL, hasBrandVoiceForScoring, seoFieldToBrandChannel, } from '../ai/brand-voice-alignment.js';
+export { applyDeterministicBrandFixes, buildBrandVoiceFixPrompt, needsAiBrandFix, runDeterministicBrandFix, type BrandVoiceFixOutcome, type DeterministicFixResult, } from '../ai/brand-voice-fix.js';
+export { BrandVoiceSourceError, fetchBrandVoiceUrlSample, uploadToBrandVoiceSample, MAX_ANALYZE_UPLOADS, MAX_ANALYZE_URLS, MAX_UPLOAD_TEXT_CHARS, } from '../ai/brand-voice-sources.js';
+export { applyStructuredProfileToDocument, defaultStructuredProfile, parseStructuredProfile, scoreBrandAlignment, BRAND_VOICE_CHANNEL_PRESETS, MAX_BANNED_TERMS, MAX_PREFERRED_TERMS, MAX_AVOID_PATTERNS, MAX_WORKED_EXAMPLES, type BrandAlignmentDimension, type BrandAlignmentIssue, type BrandAlignmentScoreResult, type BrandVoiceBannedTerm, type BrandVoiceChannelRule, type BrandVoiceMechanics, type BrandVoiceStructuredProfile, type BrandVoiceToneScales, type BrandVoiceWorkedExample, } from '../ai/brand-voice-structured.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/brand-voice/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/brand-voice/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,4BAA4B,EAC5B,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,GACnC,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,eAAe,EACf,wBAAwB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,gCAAgC,EAChC,wBAAwB,EACxB,sBAAsB,EACtB,mBAAmB,EACnB,2BAA2B,EAC3B,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAA"}

package/dist/brand-voice/index.js

@@ -0,0 +1,7 @@
+export { BRAND_VOICE_DOCUMENT_MAX, BRAND_VOICE_EXPORT_FILENAME, applyParsedDocumentToProfile, deriveBrandVoiceFields, ensureBrandVoiceDocument, parseBrandVoiceDocument, serializeBrandVoiceDocument, splitBrandVoiceDocument, syncFieldsFromDocument, } from '../ai/brand-voice-document.js';
+export { prepareBrandVoiceForSave } from '../ai/brand-voice-save.js';
+export { alignContentWithBrandVoice, COAUTHOR_BRAND_CHANNEL, hasBrandVoiceForScoring, seoFieldToBrandChannel, } from '../ai/brand-voice-alignment.js';
+export { applyDeterministicBrandFixes, buildBrandVoiceFixPrompt, needsAiBrandFix, runDeterministicBrandFix, } from '../ai/brand-voice-fix.js';
+export { BrandVoiceSourceError, fetchBrandVoiceUrlSample, uploadToBrandVoiceSample, MAX_ANALYZE_UPLOADS, MAX_ANALYZE_URLS, MAX_UPLOAD_TEXT_CHARS, } from '../ai/brand-voice-sources.js';
+export { applyStructuredProfileToDocument, defaultStructuredProfile, parseStructuredProfile, scoreBrandAlignment, BRAND_VOICE_CHANNEL_PRESETS, MAX_BANNED_TERMS, MAX_PREFERRED_TERMS, MAX_AVOID_PATTERNS, MAX_WORKED_EXAMPLES, } from '../ai/brand-voice-structured.js';
+//# sourceMappingURL=index.js.map

package/dist/brand-voice/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/brand-voice/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,4BAA4B,EAC5B,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,GAOvB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,eAAe,EACf,wBAAwB,GAGzB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,gCAAgC,EAChC,wBAAwB,EACxB,sBAAsB,EACtB,mBAAmB,EACnB,2BAA2B,EAC3B,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GAUpB,MAAM,iCAAiC,CAAA"}

package/dist/cache/http.d.ts

@@ -0,0 +1,140 @@
+/**
+ * HTTP / CDN cache primitives — the server-side mirror of the
+ * `prentaTags()` helper exposed by `@prenta/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 PrentaTagKind = 'collection' | 'doc' | 'global' | 'path';
+/** The wholesale tag added to every SDK request — panic-button invalidation. */
+export declare const PRENTA_TAG_ROOT = "prenta";
+/**
+ * Build a single canonical tag (e.g. `prenta:collection:posts`). Mirrors
+ * the SDK's `prentaTag()` so the server can construct invalidation keys
+ * that match what the client will actually invalidate.
+ */
+export declare function prentaTag(kind: PrentaTagKind, slug: string): string;
+/**
+ * Tag set to invalidate after a write. Always includes the wholesale
+ * `prenta` 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 + path tags.
+ * - `update` on a global → global tag (+ root, see below).
+ */
+/**
+ * Cache tags fired when a DOCUMENT is written. Emits NARROW tags only — the
+ * collection, the doc, and the public URL path(s) the doc renders at — and
+ * deliberately NOT the wholesale `prenta` root tag. Every write used to fire
+ * the root tag, so a single edit revalidated the ENTIRE site (#544).
+ *
+ * `paths` are the doc's public path(s), e.g. `['/blog/my-post']` — plus the OLD
+ * path on a slug rename so the vacated URL refreshes too, and the deleted doc's
+ * path on delete. They match the `prenta:path:<path>` tags the `/resolve`
+ * endpoint and the ISR site pages apply on read (built from the same
+ * `resolveDocumentUrl` the resolver inverts — see the path-tag-parity test).
+ *
+ * The read side still seeds the root tag on every request, so an operator can
+ * force an immediate full-site purge with `revalidateTag(PRENTA_TAG_ROOT)`.
+ *
+ * Documented tradeoff (#544): content that EMBEDS this doc via `populate` (e.g.
+ * an author's name shown on a posts list) is tagged by ITS OWN path/collection,
+ * not this doc's, so it refreshes on its normal ISR TTL rather than instantly.
+ * Fire the root tag for an immediate cross-content purge when that matters.
+ */
+export declare function invalidationTagsForDocumentWrite(collection: string, documentId: string, paths?: string[]): string[];
+/**
+ * Cache tags for a GLOBAL write. Globals (site settings, navigation, …) are read
+ * on potentially every page and change rarely, so a global write KEEPS the
+ * wholesale root tag: an instant, correct site-wide refresh is worth the
+ * infrequent full purge.
+ */
+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   `PrentaCMSConfig.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 Prenta 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-Prenta-Cache: HIT`; misses get `X-Prenta-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,aAAa,GAAG,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpE,gFAAgF;AAChF,eAAO,MAAM,eAAe,WAAW,CAAA;AAEvC;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAAM,EAAO,GACnB,MAAM,EAAE,CAMV;AAED;;;;;GAKG;AACH,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,213 @@
+/**
+ * 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 PRENTA_TAG_ROOT = 'prenta';
+/**
+ * Build a single canonical tag (e.g. `prenta:collection:posts`). Mirrors
+ * the SDK's `prentaTag()` so the server can construct invalidation keys
+ * that match what the client will actually invalidate.
+ */
+export function prentaTag(kind, slug) {
+    return `${PRENTA_TAG_ROOT}:${kind}:${slug}`;
+}
+/**
+ * Tag set to invalidate after a write. Always includes the wholesale
+ * `prenta` 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 + path tags.
+ * - `update` on a global → global tag (+ root, see below).
+ */
+/**
+ * Cache tags fired when a DOCUMENT is written. Emits NARROW tags only — the
+ * collection, the doc, and the public URL path(s) the doc renders at — and
+ * deliberately NOT the wholesale `prenta` root tag. Every write used to fire
+ * the root tag, so a single edit revalidated the ENTIRE site (#544).
+ *
+ * `paths` are the doc's public path(s), e.g. `['/blog/my-post']` — plus the OLD
+ * path on a slug rename so the vacated URL refreshes too, and the deleted doc's
+ * path on delete. They match the `prenta:path:<path>` tags the `/resolve`
+ * endpoint and the ISR site pages apply on read (built from the same
+ * `resolveDocumentUrl` the resolver inverts — see the path-tag-parity test).
+ *
+ * The read side still seeds the root tag on every request, so an operator can
+ * force an immediate full-site purge with `revalidateTag(PRENTA_TAG_ROOT)`.
+ *
+ * Documented tradeoff (#544): content that EMBEDS this doc via `populate` (e.g.
+ * an author's name shown on a posts list) is tagged by ITS OWN path/collection,
+ * not this doc's, so it refreshes on its normal ISR TTL rather than instantly.
+ * Fire the root tag for an immediate cross-content purge when that matters.
+ */
+export function invalidationTagsForDocumentWrite(collection, documentId, paths = []) {
+    return [
+        prentaTag('collection', collection),
+        prentaTag('doc', documentId),
+        ...paths.map((path) => prentaTag('path', path)),
+    ];
+}
+/**
+ * Cache tags for a GLOBAL write. Globals (site settings, navigation, …) are read
+ * on potentially every page and change rarely, so a global write KEEPS the
+ * wholesale root tag: an instant, correct site-wide refresh is worth the
+ * infrequent full purge.
+ */
+export function invalidationTagsForGlobalWrite(slug) {
+    return [PRENTA_TAG_ROOT, prentaTag('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   `PrentaCMSConfig.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 Prenta 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 `prenta_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*)prenta_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-Prenta-Cache: HIT`; misses get `X-Prenta-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('[prenta][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-Prenta-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('[prenta][cache] runtime cache set failed', err);
+    }
+    const res = opts.wrap(r, request);
+    res.headers.set('X-Prenta-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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"}

package/dist/cache/index.d.ts

@@ -0,0 +1,15 @@
+import type { CacheAdapter } from '../config/types.js';
+export interface CacheEntry<T = unknown> {
+    value: T;
+    tags: string[];
+    expiresAt?: number;
+}
+/** Wrap a computation with tag-based caching. */
+export declare function cached<T>(adapter: CacheAdapter, key: string, tags: string[], ttl: number, fn: () => Promise<T>): Promise<T>;
+/** Invalidate all cache entries associated with a tag. */
+export declare function revalidateTag(adapter: CacheAdapter, tag: string): Promise<void>;
+/** Build a cache key from a collection, operation, and parameters. */
+export declare function buildCacheKey(collection: string, operation: string, params?: Record<string, unknown>): string;
+/** Get the standard cache tags for a document. */
+export declare function getDocumentCacheTags(collection: string, documentId?: string): string[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,KAAK,EAAE,CAAC,CAAA;IACR,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,iDAAiD;AACjD,wBAAsB,MAAM,CAAC,CAAC,EAC5B,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,0DAA0D;AAC1D,wBAAsB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErF;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAUR;AAED,kDAAkD;AAClD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAItF"}

package/dist/cache/index.js

@@ -0,0 +1,32 @@
+/** Wrap a computation with tag-based caching. */
+export async function cached(adapter, key, tags, ttl, fn) {
+    const existing = await adapter.get(key);
+    if (existing)
+        return existing.value;
+    const value = await fn();
+    await adapter.set(key, { value, tags, expiresAt: Date.now() + ttl }, ttl);
+    return value;
+}
+/** Invalidate all cache entries associated with a tag. */
+export async function revalidateTag(adapter, tag) {
+    await adapter.invalidateTag(tag);
+}
+/** Build a cache key from a collection, operation, and parameters. */
+export function buildCacheKey(collection, operation, params) {
+    const base = `prenta:${collection}:${operation}`;
+    if (!params)
+        return base;
+    const sorted = Object.entries(params)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+        .join('&');
+    return `${base}:${sorted}`;
+}
+/** Get the standard cache tags for a document. */
+export function getDocumentCacheTags(collection, documentId) {
+    const tags = [`collection:${collection}`];
+    if (documentId)
+        tags.push(`doc:${documentId}`);
+    return tags;
+}
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAQA,iDAAiD;AACjD,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,OAAqB,EACrB,GAAW,EACX,IAAc,EACd,GAAW,EACX,EAAoB;IAEpB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAgB,GAAG,CAAC,CAAA;IACtD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC,KAAK,CAAA;IAEnC,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAA;IACxB,MAAM,OAAO,CAAC,GAAG,CAAgB,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,GAAG,CAAC,CAAA;IACxF,OAAO,KAAK,CAAA;AACd,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAqB,EAAE,GAAW;IACpE,MAAM,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAA;AAClC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,SAAiB,EACjB,MAAgC;IAEhC,MAAM,IAAI,GAAG,UAAU,UAAU,IAAI,SAAS,EAAE,CAAA;IAChD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAExB,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5C,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,OAAO,GAAG,IAAI,IAAI,MAAM,EAAE,CAAA;AAC5B,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,oBAAoB,CAAC,UAAkB,EAAE,UAAmB;IAC1E,MAAM,IAAI,GAAG,CAAC,cAAc,UAAU,EAAE,CAAC,CAAA;IACzC,IAAI,UAAU;QAAE,IAAI,CAAC,IAAI,CAAC,OAAO,UAAU,EAAE,CAAC,CAAA;IAC9C,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,51 @@
+export { SLUG_PATTERN, RESERVED_SLUGS, normalizeSlug, isValidSlug, isReservedSlug, validateSlug, } from './content/slug.js';
+export { resolveRenderedMetaTitle, type SiteTitleToken } from './seo/title-templates.js';
+/** Client-safe public path authority (no Node/server graph). */
+export { documentPublicPath, resolveDocumentUrl } from './seo/document-path.js';
+export interface FindOptions {
+    page?: number;
+    pageSize?: number;
+    sort?: string;
+    order?: 'asc' | 'desc';
+    where?: Record<string, unknown>;
+    locale?: string;
+}
+export interface FindResult<T = Record<string, unknown>> {
+    docs: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+export interface CollectionClient<T = Record<string, unknown>> {
+    find(options?: FindOptions): Promise<FindResult<T>>;
+    findById(id: string): Promise<T | null>;
+    findBySlug(slug: string): Promise<T | null>;
+}
+export interface GlobalClient<T = Record<string, unknown>> {
+    get(): Promise<T | null>;
+}
+export interface LayoutVariant<T = Record<string, unknown>> {
+    id: string;
+    collection: string;
+    data: T;
+}
+export interface ResolveResult<T = Record<string, unknown>> {
+    data: {
+        id: string;
+        collection: string;
+        data: T;
+        status: string;
+        publishedAt: string | null;
+        structuredData: unknown;
+    };
+    layout?: Record<string, LayoutVariant>;
+}
+export interface CMSClient {
+    collection<T = Record<string, unknown>>(slug: string): CollectionClient<T>;
+    global<T = Record<string, unknown>>(slug: string): GlobalClient<T>;
+    resolve<T = Record<string, unknown>>(path: string): Promise<ResolveResult<T>>;
+}
+/** Create a typed CMS client for frontend data access. */
+export declare function createCMSClient(baseUrl: string, apiKey?: string): CMSClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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