@inneropen/marvin-astro 1.4.0 → 2.1.0

package/README.md

@@ -132,13 +132,15 @@ entry's image assets, then the list item's `featuredAsset`.
 ## Site and chrome
 
 ```ts
-const site = await marvin.getSite();       // identity, SEO, brand assets — memoized
+const site = await marvin.getSite();       // identity, SEO, logo/favicon URLs — memoized
 const chrome = await marvin.getSiteChrome(); // nav, footer, legal, social, inquiry — memoized
 ```
 
-`getSite()` resolves every `site_metadata_json.brand.<name>` asset slug to a URL in one pass, so
-a site adds a shared brand asset with one config line and reads `site.brand.<name>` — no code
-change per asset. `logo`, `favicon` and `seal` are aliased onto the top level.
+`getSite()` takes `logo`, `favicon` and `seo.image` as the URLs Marvin now returns (no asset
+lookups). `site.brand.<name>` collects the `site_metadata_json.brand.<name>` values that are
+URLs, root-relative paths or data URIs, used as-is; bare asset slugs are left out because the
+publishing API no longer serves assets by slug. `brand.logo`, `brand.favicon` and `brand.seal`
+win over the top-level `logo`/`favicon`/`seal`.
 
 `getSiteChrome()` reads `main-navigation` and `footer-navigation` collections, splits
 `role: 'legal'` entries into `legalLinks`, and groups the rest into footer columns. Social links
@@ -256,6 +258,8 @@ this needs a newer SDK.
 |---|---|
 | `FormRenderer` | a public form from a submittable entry type's `formSchema`; unstyled, progressive-enhancement submit |
 | `Embed`, `LinkCard`, `EmbedLoader` | media embeds (above) |
+| `PrivacyPolicy`, `CookieTable`, `ProcessorTable` | privacy & cookie policy rendering ([below](#privacy--cookies)) |
+| `ConsentBanner`, `CookieSettingsLink` | cookie-consent banner and settings link ([below](#consent-banner)) |
 | `EntryRenderer` | picks the renderer for an entry from its entry type's `rendering` |
 | `PageRenderer`, `ArticleRenderer`, `FaqRenderer`, `NavigationRenderer` | unstyled, semantic core renderers with `data-renderer`/`data-role` hooks |
 
@@ -286,6 +290,116 @@ Options: `registry` (required), `apiUrl`, `siteToken` (default to the `MARVIN_*`
 Marvin's system entry types name their renderer package `@inneropen/marvin-renderers-core`; the
 core renderers still answer to that name (and to `@inneropen/marvin-astro`).
 
+## Privacy & cookies
+
+Marvin keeps the facts a privacy/cookie policy needs (`site.privacy`: the controller, processors and
+the cookies/storage the site sets). `site.privacy` is read tolerantly (typed field or
+`metadata.privacy`, camelCase or snake_case), so it needs no SDK bump; it is `undefined` until a
+workspace configures it. Not legal advice: you decide the text and the classification.
+
+```astro
+---
+import { PrivacyPolicy } from '@inneropen/marvin-astro/components';
+const site = await marvin.getSite();
+const entry = await policies.bySlug('privacy'); // your policy entry (prose)
+---
+<PrivacyPolicy privacy={site.privacy} headingLevel={2}>
+  <Fragment set:html={entry.bodyHtml} />
+</PrivacyPolicy>
+```
+
+| Component | Renders |
+|---|---|
+| `PrivacyPolicy` | the entry prose (default slot), controller block, processors, cookies, "Last reviewed" |
+| `CookieTable` | `cookies`, one table per category (`category` narrows it); adds the `marvin-consent` storage row as necessary when a banner is required (`includeConsentEntry={false}` to skip) |
+| `ProcessorTable` | `processors`: region, transfer basis, DPA/privacy links (http(s) only) |
+
+All server-rendered with zero JavaScript. Styling is `privacy.css`: zero-specificity `:where()` rules
+you override freely, themed with `--marvin-privacy-gap | -border | -head-bg | -muted | -pad`; tables
+stack below 600px. Every string has a neutral English default; pass `labels={{ ... }}` to change it.
+
+`sitePrivacy(raw)` and `consentVersion(privacy)` are exported from the package root. The version is
+a hash of the sorted non-necessary `category|name|provider` triples, so rewording a purpose or
+moving `lastReviewed` never re-asks, while adding, removing or re-categorising a cookie does.
+
+### Consent banner
+
+`<ConsentBanner>` asks only when it has to. It renders **nothing, and ships no script or CSS**, unless
+`site.privacy.bannerRequired` (at least one listed cookie/storage entry is not `necessary`), so a site
+with no optional cookies carries zero banner bytes.
+
+```astro
+---
+// src/layouts/BaseLayout.astro
+import { ConsentBanner, CookieSettingsLink } from '@inneropen/marvin-astro/components';
+const site = await marvin.getSite();
+---
+<html>
+  <body>
+    <ConsentBanner privacy={site.privacy} policyHref="/privacy" />
+    <main>...</main>
+    <footer>
+      <CookieSettingsLink href="/privacy" privacy={site.privacy} />
+    </footer>
+  </body>
+</html>
+```
+
+- **Fail closed.** The markup is `hidden` and the runtime reveals it only when the visitor has no valid
+  choice; without JavaScript there is no dead banner and nothing optional loads. The link in
+  `<CookieSettingsLink>` is a real link to your policy page; with JavaScript it opens the dialog.
+- **Equal choices.** Accept all and Reject all share one class and size; Customise opens a native
+  `<dialog>` with one unticked checkbox per category listed in `site.privacy.cookies`. A non-modal bottom
+  bar, no focus stealing; after a choice focus moves to `<main>`, and the dialog returns it to its opener.
+- **Remembered for 6 months**, refusals too (`maxAgeDays`, default 180), in
+  `localStorage['marvin-consent']`. The choice is bound to `consentVersion(privacy)`: adding, removing or
+  re-categorising an optional cookie asks everyone again; rewording does not. `consent.version` in
+  Marvin's privacy block is a manual re-ask bump. Safari caps script-written storage at 7 days without
+  interaction, so some visitors are asked sooner.
+- **Disclosure.** `marvin-consent` is listed automatically by `<CookieTable>` / `<PrivacyPolicy>`.
+
+Gate optional scripts and markup so they ship inert and run only after consent:
+
+```html
+<script type="text/plain" data-consent="analytics" data-src="https://stats.example/script.js" defer></script>
+<script type="text/plain" data-consent="analytics">window.track?.();</script>
+<template data-consent="marketing"><iframe src="https://ads.example/widget"></iframe></template>
+```
+
+`data-consent` takes one or more categories (`preferences`, `analytics`, `marketing`; all must be
+allowed). Other attributes on the script are copied over, `data-type="module"` restores a module type.
+An unknown category never runs. A site whose `bannerRequired` is false never activates anything, so a
+gated script with no matching entry in Marvin stays inert; a dev build logs a console warning for that.
+Prefer `data-src` over inline code if you use a CSP (inline gated code needs a hash or `unsafe-inline`).
+
+```ts
+window.marvinConsent.get();            // { v, version, choices, at } | null while undecided
+window.marvinConsent.has('analytics'); // 'necessary' is always true
+window.marvinConsent.set({ analytics: true });
+window.marvinConsent.open();           // the Customise dialog
+document.addEventListener('marvin:consent', (e) => e.detail); // { choices, version, initial }
+```
+
+`marvin:consent` fires on load when a valid choice exists (`initial: true`, after the page's module
+scripts have run, so late listeners see it) and on every change. Withdrawing a category deletes the
+site's listed first-party cookies for it (a trailing `*` is a prefix: `_ga*`; the host and its parent
+domains) and reloads the page so nothing keeps running.
+
+**Embeds** stay click-to-load: the click on a facade is the visitor's consent, and they do not make
+`bannerRequired` true. Opt in to auto-loading them after a category is allowed with
+`<ConsentBanner embeds="marketing" ... />` (off by default; needs `<EmbedLoader />`).
+
+Text defaults to neutral English: override per site with `labels={{ title, body, acceptAll, rejectAll,
+customise, save, settingsLink, policyLink, dialogTitle, dialogBody, categories, categoryDescriptions }}`.
+Theme with `--marvin-consent-bg | -fg | -accent | -radius | -font | -shadow | -z` (zero-specificity
+`consent.css`; dark mode follows `prefers-color-scheme`). No consent log is kept anywhere.
+
+`consent.css` is inlined as a `<style>` next to the banner markup, and the runtime `<script>` is only
+emitted with it, so a page without a banner carries neither (Astro 5 ships a component's `<script>` only
+where it renders but ships imported stylesheets wherever the component is merely imported, hence the
+inline style). Under a CSP without `style-src 'unsafe-inline'`, pass `inlineStyles={false}` and import
+`@inneropen/marvin-astro/components/consent.css` yourself. Check your build output on other Astro versions.
+
 ## Migrating from @inneropen/marvin-renderers-core
 
 The components and logic moved here with their names unchanged. Swap the import paths, then
@@ -352,7 +466,7 @@ verification tags. No styling, no site coupling.
 | `@inneropen/marvin-astro` | `createMarvinContent` and every helper below it |
 | `@inneropen/marvin-astro/types` | resolved types only (`ApiSite`, `ApiSeo`, `ApiSiteChrome`, …) |
 | `@inneropen/marvin-astro/astro` | `SeoHead` |
-| `@inneropen/marvin-astro/components` | `FormRenderer`, `Embed`, `LinkCard`, `EmbedLoader`, `EntryRenderer`, the core renderers, registry, `marvinIntegration` |
+| `@inneropen/marvin-astro/components` | `FormRenderer`, `Embed`, `LinkCard`, `EmbedLoader`, `PrivacyPolicy`, `CookieTable`, `ProcessorTable`, `ConsentBanner`, `CookieSettingsLink`, `EntryRenderer`, the core renderers, registry, `marvinIntegration` |
 | `@inneropen/marvin-astro/components/registry` | `getRenderer`, `astroRegistry`, `coreRendererPackage` |
 | `@inneropen/marvin-astro/components/integration` | `marvinIntegration` (for `astro.config.mjs`) |
 | `@inneropen/marvin-astro/components/*` | individual components, `renderers/*.astro`, `embeds.css` |
@@ -360,7 +474,7 @@ verification tags. No styling, no site coupling.
 
 Beyond `createMarvinContent`, the pieces are usable on their own: `createBackend`,
 `createFetcher`, `createRepository`, `createSiteLoader`, `createChromeLoader`,
-`createFieldAccessor`, `createMarkdownRenderer`, `entryEmbeds`, `findEmbed`, `siteEmbeds`,
+`createFieldAccessor`, `createMarkdownRenderer`, `entryEmbeds`, `findEmbed`, `siteEmbeds`, `sitePrivacy`, `consentVersion`,
 `formatDisplayDate`, `selectValuesForPage`, and the whole `normalize` surface.
 
 ## Development

package/dist/index.d.ts

@@ -2,9 +2,9 @@ import { MarkedOptions } from 'marked';
 import { M as MarvinEmbeds, a as MarvinEmbed } from './embeds-BTNryQA6.js';
 export { b as MarvinEmbedIframe, c as MarvinEmbedKind, d as MarvinEmbedLink, e as MarvinEmbedMode, f as MarvinEmbedStatus, g as MarvinSiteEmbeds, h as entryEmbeds, i as findEmbed, s as siteEmbeds } from './embeds-BTNryQA6.js';
 import * as _inneropen_marvin_sdk from '@inneropen/marvin-sdk';
-import { MarvinClient, MarvinEntry, Entry, PublishedCollectionSummary, Collection, CollectionEntry, MarvinSite, Workspace, MarvinAsset, MarvinResource } from '@inneropen/marvin-sdk';
-import { MarvinContentEntry, ApiSite, ApiSeo, ApiSiteChrome, ApiNavigationLink, ApiSocialLink, AssetSelectOptions, ApiImage, ApiResourceLink, SectionLanding } from './types.js';
-export { ApiActionVariant, ApiHero, ApiHeroAction, ApiPageAction } from './types.js';
+import { MarvinClient, MarvinEntry, Entry, PublishedCollectionSummary, Collection, CollectionEntry, MarvinSite, Workspace } from '@inneropen/marvin-sdk';
+import { M as MarvinContentEntry, A as ApiSite, a as ApiSeo, b as ApiSiteChrome, c as ApiNavigationLink, d as ApiSocialLink, e as AssetSelectOptions, f as ApiImage, g as ApiResourceLink, S as SectionLanding } from './types-4VdGN9e_.js';
+export { h as ApiActionVariant, i as ApiHero, j as ApiHeroAction, k as ApiPageAction, C as CONSENT_CATEGORIES, l as COOKIE_CATEGORIES, m as ConsentCategory, n as CookieCategory, P as PrivacyConsent, o as PrivacyController, p as PrivacyCookie, q as PrivacyProcessor, r as SitePrivacy, s as consentCategories, t as consentVersion, u as cookiesNeedConsent, v as sitePrivacy } from './types-4VdGN9e_.js';
 
 type MarkdownOptions = MarkedOptions;
 /** Per-call options for a {@link MarkdownRenderer}. */
@@ -179,9 +179,6 @@ declare function createFetcher(backend: MarvinBackend): {
     entry: (slug: string) => Promise<Entry | null>;
     site(): Promise<MarvinSite | null>;
     workspace(): Promise<Workspace | null>;
-    assets(type?: string): Promise<MarvinAsset[]>;
-    asset(slugOrId: string): Promise<MarvinAsset | null>;
-    resources(resourceType?: string): Promise<MarvinResource[]>;
 };
 
 /**
@@ -189,8 +186,8 @@ declare function createFetcher(backend: MarvinBackend): {
  *
  * Marvin's site configuration is optional almost everywhere; a template that had to guard every
  * field would be unreadable. This resolves it once into an `ApiSite` where title, description,
- * siteName, locale and timezone are always present, and where brand asset slugs have already
- * become URLs.
+ * siteName, locale and timezone are always present. Logo, favicon and SEO image are the URLs
+ * Marvin returns, used as-is.
  */
 
 type SiteOptions = {
@@ -620,14 +617,11 @@ declare function createMarvinContent(options?: MarvinContentOptions): {
         entry: (slug: string) => Promise<_inneropen_marvin_sdk.Entry | null>;
         site(): Promise<_inneropen_marvin_sdk.MarvinSite | null>;
         workspace(): Promise<_inneropen_marvin_sdk.Workspace | null>;
-        assets(type?: string): Promise<_inneropen_marvin_sdk.MarvinAsset[]>;
-        asset(slugOrId: string): Promise<_inneropen_marvin_sdk.MarvinAsset | null>;
-        resources(resourceType?: string): Promise<_inneropen_marvin_sdk.MarvinResource[]>;
     };
     renderMarkdown: MarkdownRenderer;
     /** True when Marvin is configured and not currently latched out as unreachable. */
     hasBackend: () => boolean;
-    /** Resolved site identity, SEO and brand assets. Memoized per process. */
+    /** Site identity, SEO and logo/favicon URLs. Memoized per process. */
     getSite(): Promise<ApiSite>;
     /** Navigation, footer, legal, social and inquiry links. Memoized per process. */
     getSiteChrome(): Promise<ApiSiteChrome>;

package/dist/index.js

@@ -546,15 +546,6 @@ function createFetcher(backend) {
     },
     workspace() {
       return guarded("Workspace", null, () => backend.client().getWorkspace());
-    },
-    assets(type) {
-      return guarded("Assets", [], () => backend.client().assets.list({ type }));
-    },
-    asset(slugOrId) {
-      return guarded(`Asset "${slugOrId}"`, null, () => backend.client().assets.get(slugOrId));
-    },
-    resources(resourceType) {
-      return guarded("Resources", [], () => backend.client().resources.list({ resourceType }));
     }
   };
 }
@@ -611,9 +602,9 @@ var EMBEDS = /* @__PURE__ */ Symbol("marvin.embeds");
 var BARE_URL = /^https?:\/\/\S+$/i;
 function paragraphEmbedHtml(token, embeds) {
   if (!embeds) return void 0;
-  const text = token.text.trim();
-  if (!BARE_URL.test(text)) return void 0;
-  const html = findEmbed(embeds, text)?.html;
+  const text2 = token.text.trim();
+  if (!BARE_URL.test(text2)) return void 0;
+  const html = findEmbed(embeds, text2)?.html;
   return typeof html === "string" && html.trim() ? html : void 0;
 }
 function createMarkdownRenderer(options = {}) {
@@ -993,6 +984,109 @@ async function loadSectionLanding(fetcher, slug, renderMarkdown = createMarkdown
   };
 }
 
+// src/privacy.ts
+var COOKIE_CATEGORIES = [
+  "necessary",
+  "preferences",
+  "analytics",
+  "marketing"
+];
+var CONSENT_CATEGORIES = [
+  "preferences",
+  "analytics",
+  "marketing"
+];
+function field2(record, camel) {
+  if (record[camel] !== void 0) return record[camel];
+  return record[camel.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)];
+}
+function text(record, camel) {
+  const value = asString(field2(record, camel));
+  return value?.trim();
+}
+function records(value) {
+  return Array.isArray(value) ? value.filter((item) => !!item && typeof item === "object") : [];
+}
+function readController(raw) {
+  const value = asRecord(raw);
+  const legalName = text(value, "legalName");
+  if (!legalName) return void 0;
+  return {
+    legalName,
+    contactEmail: text(value, "contactEmail"),
+    address: text(value, "address"),
+    euRepresentative: text(value, "euRepresentative"),
+    dpoEmail: text(value, "dpoEmail")
+  };
+}
+function readProcessor(value) {
+  const name = text(value, "name");
+  if (!name) return void 0;
+  const categories = field2(value, "dataCategories");
+  return {
+    name,
+    purpose: text(value, "purpose"),
+    dataCategories: Array.isArray(categories) ? categories.filter((item) => typeof item === "string" && item.trim() !== "") : [],
+    region: text(value, "region"),
+    transferBasis: text(value, "transferBasis"),
+    dpaUrl: text(value, "dpaUrl"),
+    privacyUrl: text(value, "privacyUrl")
+  };
+}
+function readCookie(value) {
+  const name = text(value, "name");
+  if (!name) return void 0;
+  const category = text(value, "category");
+  return {
+    name,
+    provider: text(value, "provider") ?? "",
+    purpose: text(value, "purpose") ?? "",
+    duration: text(value, "duration"),
+    // A category a newer server invented is treated as the strictest optional one, never as
+    // `necessary`: it must be asked about before anything it covers loads.
+    category: COOKIE_CATEGORIES.includes(category) ? category : "marketing"
+  };
+}
+function cookiesNeedConsent(cookies) {
+  return cookies.some((cookie) => cookie.category !== "necessary");
+}
+function sitePrivacy(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const value = raw;
+  const consent = asRecord(field2(value, "consent"));
+  const cookies = records(value.cookies).map(readCookie).filter((cookie) => cookie !== void 0);
+  const declared = field2(value, "bannerRequired");
+  return {
+    controller: readController(value.controller),
+    processors: records(value.processors).map(readProcessor).filter((processor) => processor !== void 0),
+    cookies,
+    consent: {
+      policyEntrySlug: text(consent, "policyEntrySlug"),
+      cookiePolicyEntrySlug: text(consent, "cookiePolicyEntrySlug"),
+      lastReviewed: text(consent, "lastReviewed"),
+      version: text(consent, "version")
+    },
+    bannerRequired: typeof declared === "boolean" ? declared : cookiesNeedConsent(cookies)
+  };
+}
+function fnv1a(input) {
+  let hash = 2166136261;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function consentVersion(privacy) {
+  const triples = (privacy?.cookies ?? []).filter((cookie) => cookie.category !== "necessary").map((cookie) => `${cookie.category}|${cookie.name}|${cookie.provider}`).sort();
+  const bump = privacy?.consent.version;
+  return fnv1a(bump ? [...triples, `v:${bump}`].join("\n") : triples.join("\n"));
+}
+function consentCategories(privacy) {
+  const present = new Set((privacy?.cookies ?? []).map((cookie) => cookie.category));
+  return CONSENT_CATEGORIES.filter((category) => present.has(category));
+}
+
 // src/site.ts
 function buildSeo(raw, identity) {
   const seo = raw ?? {};
@@ -1080,54 +1174,37 @@ function transformMarvinSite(marvinSite, fallback) {
     embeds: siteEmbeds(
       config.embeds ?? marvinSite.embeds
     ),
+    // Typed `config.privacy` when the SDK declares it (SDK 7.2+), else the raw blob under
+    // `metadata.privacy`; this package's SDK peer range predates the typed field, so read both.
+    privacy: sitePrivacy(
+      config.privacy ?? marvinSite.privacy ?? metadata.privacy
+    ),
     metadata
   };
 }
-function looksLikeAssetSlug(value) {
-  return !/^https?:\/\//.test(value) && !value.startsWith("/") && !value.startsWith("data:");
+function isUrlLike(value) {
+  return /^https?:\/\//.test(value) || value.startsWith("/") || value.startsWith("data:");
 }
 function createSiteLoader(fetcher, options = {}) {
   const fallback = buildFallbackSite(options);
   let promise = null;
   let fromMarvin = false;
-  async function resolveAssetSlug(slug) {
-    if (!slug) return void 0;
-    return assetUrl(await fetcher.asset(slug));
-  }
-  async function resolveMaybeSlug(value) {
-    if (!value || !looksLikeAssetSlug(value)) return value;
-    return await resolveAssetSlug(value) ?? value;
-  }
   async function load() {
     const marvinSite = await fetcher.site();
     fromMarvin = marvinSite !== null;
     if (!marvinSite) return fallback;
     const site = transformMarvinSite(marvinSite, fallback);
-    const brandPairs = Object.entries(asRecord(site.metadata.brand)).filter(
-      (entry) => typeof entry[1] === "string" && entry[1].trim().length > 0
-    );
-    const resolved = await Promise.all(
-      brandPairs.map(async ([name, slug]) => [name, await resolveAssetSlug(slug)])
-    );
     const brand = {};
-    const brandBySlug = /* @__PURE__ */ new Map();
-    for (const [index, [name, url]] of resolved.entries()) {
-      if (!url) continue;
-      brand[name] = url;
-      brandBySlug.set(brandPairs[index][1], url);
+    for (const [name, value] of Object.entries(asRecord(site.metadata.brand))) {
+      if (typeof value === "string" && isUrlLike(value.trim())) brand[name] = value.trim();
     }
-    const rawImage = site.seo.image;
-    const ogImage = rawImage && looksLikeAssetSlug(rawImage) ? brandBySlug.get(rawImage) ?? await resolveAssetSlug(rawImage) : void 0;
-    const logo = brand.logo ?? await resolveMaybeSlug(site.logo);
-    const favicon = brand.favicon ?? await resolveMaybeSlug(site.favicon);
     return {
       ...site,
       brand,
       // Convenience aliases for common callers; all of these also live in `site.brand`.
-      logo,
-      favicon,
-      seal: brand.seal ?? site.seal,
-      seo: { ...site.seo, image: ogImage ?? site.seo.image }
+      logo: brand.logo ?? site.logo,
+      favicon: brand.favicon ?? site.favicon,
+      seal: brand.seal ?? site.seal
     };
   }
   return {
@@ -1164,7 +1241,7 @@ function createMarvinContent(options = {}) {
     renderMarkdown,
     /** True when Marvin is configured and not currently latched out as unreachable. */
     hasBackend: () => backend.hasBackend(),
-    /** Resolved site identity, SEO and brand assets. Memoized per process. */
+    /** Site identity, SEO and logo/favicon URLs. Memoized per process. */
     getSite() {
       return siteLoader.get();
     },
@@ -1192,6 +1269,8 @@ function createMarvinContent(options = {}) {
   };
 }
 export {
+  CONSENT_CATEGORIES,
+  COOKIE_CATEGORIES,
   DEFAULT_DEV_RETRY_MS,
   DEFAULT_HYDRATE_CONCURRENCY,
   ENV_KEYS,
@@ -1206,6 +1285,9 @@ export {
   buildSeo,
   collectionRole,
   collectionSlugs,
+  consentCategories,
+  consentVersion,
+  cookiesNeedConsent,
   createBackend,
   createChromeLoader,
   createFetcher,
@@ -1244,6 +1326,7 @@ export {
   selectImageAsset,
   selectValuesForPage,
   siteEmbeds,
+  sitePrivacy,
   socialLinkFromKey,
   toNavigationLink
 };