@inneropen/marvin-astro 1.4.0 → 2.1.0

package/src/privacy.ts

@@ -0,0 +1,210 @@
+/**
+ * Privacy & cookie disclosures: the published `site.privacy` shape, read tolerantly.
+ *
+ * Marvin keeps the structured facts a privacy/cookie policy page needs (who the controller is,
+ * which processors handle visitor data, which cookies and storage entries the site sets). The
+ * components in this package render them and, when any entry is not strictly necessary, run a
+ * consent banner.
+ *
+ * Declared here rather than imported from `@inneropen/marvin-sdk` so the package works with SDKs
+ * that predate `site.privacy`. Both the published camelCase keys and snake_case are accepted, and
+ * a malformed entry is dropped rather than failing the site build.
+ */
+
+import { asRecord, asString } from './normalize.js';
+
+export type CookieCategory = 'necessary' | 'preferences' | 'analytics' | 'marketing';
+
+/** The categories a visitor can switch on; `necessary` is always on and never asked. */
+export type ConsentCategory = Exclude<CookieCategory, 'necessary'>;
+
+export const COOKIE_CATEGORIES: readonly CookieCategory[] = [
+  'necessary',
+  'preferences',
+  'analytics',
+  'marketing',
+];
+
+export const CONSENT_CATEGORIES: readonly ConsentCategory[] = [
+  'preferences',
+  'analytics',
+  'marketing',
+];
+
+/** Who is responsible for the site's data (the GDPR "controller"). */
+export type PrivacyController = {
+  legalName: string;
+  contactEmail?: string;
+  address?: string;
+  euRepresentative?: string;
+  dpoEmail?: string;
+};
+
+/** A third party that handles visitor data on the site's behalf. */
+export type PrivacyProcessor = {
+  name: string;
+  purpose?: string;
+  dataCategories: string[];
+  region?: string;
+  transferBasis?: string;
+  dpaUrl?: string;
+  privacyUrl?: string;
+};
+
+/** A cookie (or similar storage entry) the site sets. */
+export type PrivacyCookie = {
+  name: string;
+  provider: string;
+  purpose: string;
+  duration?: string;
+  category: CookieCategory;
+};
+
+export type PrivacyConsent = {
+  policyEntrySlug?: string;
+  cookiePolicyEntrySlug?: string;
+  /** ISO date (`YYYY-MM-DD`) the disclosures were last checked. */
+  lastReviewed?: string;
+  /** A manual re-prompt bump: changing it asks every visitor again. */
+  version?: string;
+};
+
+export type SitePrivacy = {
+  controller?: PrivacyController;
+  processors: PrivacyProcessor[];
+  cookies: PrivacyCookie[];
+  consent: PrivacyConsent;
+  /** True when any cookie is not `necessary`: those need prior consent. */
+  bannerRequired: boolean;
+};
+
+/** Key a field by its camelCase name, falling back to snake_case. */
+function field(record: Record<string, unknown>, camel: string): unknown {
+  if (record[camel] !== undefined) return record[camel];
+  return record[camel.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)];
+}
+
+function text(record: Record<string, unknown>, camel: string): string | undefined {
+  const value = asString(field(record, camel));
+  return value?.trim();
+}
+
+function records(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is Record<string, unknown> => !!item && typeof item === 'object')
+    : [];
+}
+
+function readController(raw: unknown): PrivacyController | undefined {
+  const value = asRecord(raw);
+  const legalName = text(value, 'legalName');
+  if (!legalName) return undefined;
+  return {
+    legalName,
+    contactEmail: text(value, 'contactEmail'),
+    address: text(value, 'address'),
+    euRepresentative: text(value, 'euRepresentative'),
+    dpoEmail: text(value, 'dpoEmail'),
+  };
+}
+
+function readProcessor(value: Record<string, unknown>): PrivacyProcessor | undefined {
+  const name = text(value, 'name');
+  if (!name) return undefined;
+  const categories = field(value, 'dataCategories');
+  return {
+    name,
+    purpose: text(value, 'purpose'),
+    dataCategories: Array.isArray(categories)
+      ? categories.filter((item): item is string => typeof item === 'string' && item.trim() !== '')
+      : [],
+    region: text(value, 'region'),
+    transferBasis: text(value, 'transferBasis'),
+    dpaUrl: text(value, 'dpaUrl'),
+    privacyUrl: text(value, 'privacyUrl'),
+  };
+}
+
+function readCookie(value: Record<string, unknown>): PrivacyCookie | undefined {
+  const name = text(value, 'name');
+  if (!name) return undefined;
+  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 as CookieCategory)
+      ? (category as CookieCategory)
+      : 'marketing',
+  };
+}
+
+/** True when any listed cookie needs consent. */
+export function cookiesNeedConsent(cookies: readonly Pick<PrivacyCookie, 'category'>[]): boolean {
+  return cookies.some((cookie) => cookie.category !== 'necessary');
+}
+
+/**
+ * Normalize `site.privacy`; `undefined` when the server doesn't send it (or sends a non-object).
+ * `bannerRequired` is taken from the payload when it is a boolean and computed from the cookies
+ * otherwise.
+ */
+export function sitePrivacy(raw: unknown): SitePrivacy | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const value = raw as Record<string, unknown>;
+  const consent = asRecord(field(value, 'consent'));
+
+  const cookies = records(value.cookies)
+    .map(readCookie)
+    .filter((cookie): cookie is PrivacyCookie => cookie !== undefined);
+  const declared = field(value, 'bannerRequired');
+
+  return {
+    controller: readController(value.controller),
+    processors: records(value.processors)
+      .map(readProcessor)
+      .filter((processor): processor is PrivacyProcessor => processor !== undefined),
+    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),
+  };
+}
+
+/** 32-bit FNV-1a of a string, as 8 lowercase hex digits. */
+function fnv1a(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/**
+ * The version a visitor's choice is bound to: FNV-1a over the sorted, non-necessary
+ * `category|name|provider` triples (plus `consent.version`, a manual bump). Adding, removing or
+ * re-categorising a cookie changes it and asks everyone again; rewording a purpose, changing a
+ * duration, or moving `lastReviewed` does not.
+ */
+export function consentVersion(privacy: SitePrivacy | undefined): string {
+  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'));
+}
+
+/** The optional categories that appear in the cookie list, in display order. */
+export function consentCategories(privacy: SitePrivacy | undefined): ConsentCategory[] {
+  const present = new Set((privacy?.cookies ?? []).map((cookie) => cookie.category));
+  return CONSENT_CATEGORIES.filter((category) => present.has(category));
+}

package/src/site.ts

@@ -3,14 +3,15 @@
  *
  * 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.
  */
 
 import type { MarvinSite, SiteConfiguration } from '@inneropen/marvin-sdk';
 import { siteEmbeds } from './embeds.js';
+import { sitePrivacy } from './privacy.js';
 import type { MarvinFetcher } from './fetch.js';
-import { asRecord, asString, assetUrl } from './normalize.js';
+import { asRecord, asString } from './normalize.js';
 import type { ApiSeo, ApiSite } from './types.js';
 
 export type SiteOptions = {
@@ -131,12 +132,20 @@ function transformMarvinSite(marvinSite: MarvinSite, fallback: ApiSite): ApiSite
     embeds: siteEmbeds(
       (config as { embeds?: unknown }).embeds ?? (marvinSite as { embeds?: unknown }).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 as { privacy?: unknown }).privacy ??
+        (marvinSite as { privacy?: unknown }).privacy ??
+        metadata.privacy
+    ),
     metadata,
   };
 }
 
-function looksLikeAssetSlug(value: string): boolean {
-  return !/^https?:\/\//.test(value) && !value.startsWith('/') && !value.startsWith('data:');
+/** A usable image reference: an absolute URL, a root-relative path or a data URI. */
+function isUrlLike(value: string): boolean {
+  return /^https?:\/\//.test(value) || value.startsWith('/') || value.startsWith('data:');
 }
 
 export type SiteLoader = {
@@ -155,18 +164,6 @@ export function createSiteLoader(fetcher: MarvinFetcher, options: SiteOptions =
   let promise: Promise<ApiSite> | null = null;
   let fromMarvin = false;
 
-  async function resolveAssetSlug(slug: string | undefined): Promise<string | undefined> {
-    if (!slug) return undefined;
-    return assetUrl(await fetcher.asset(slug));
-  }
-
-  // Resolve a value only when it looks like a bare asset slug; a URL/path/data URI (or a slug with
-  // no matching asset) is returned unchanged.
-  async function resolveMaybeSlug(value: string | undefined): Promise<string | undefined> {
-    if (!value || !looksLikeAssetSlug(value)) return value;
-    return (await resolveAssetSlug(value)) ?? value;
-  }
-
   async function load(): Promise<ApiSite> {
     const marvinSite = await fetcher.site();
     fromMarvin = marvinSite !== null;
@@ -174,46 +171,21 @@ export function createSiteLoader(fetcher: MarvinFetcher, options: SiteOptions =
 
     const site = transformMarvinSite(marvinSite, fallback);
 
-    // Brand-asset registry: resolve EVERY `brand.<name>` slug → URL in one pass. A site adds a
-    // shared asset with one config line (`brand.paperFold = "paper-fold"`) plus an upload;
-    // components then read `site.brand.paperFold`. No code change per asset.
-    const brandPairs = Object.entries(asRecord(site.metadata.brand)).filter(
-      (entry): entry is [string, string] =>
-        typeof entry[1] === 'string' && entry[1].trim().length > 0
-    );
-    const resolved = await Promise.all(
-      brandPairs.map(async ([name, slug]) => [name, await resolveAssetSlug(slug)] as const)
-    );
+    // Brand-asset registry: every `brand.<name>` that is a URL (or root-relative path / data URI),
+    // used as-is. Marvin no longer serves assets by slug, so a bare slug can't be resolved here and
+    // is left out; `site.logo`, `site.favicon` and `site.seo.image` arrive already resolved.
     const brand: Record<string, string> = {};
-    const brandBySlug = new Map<string, string>();
-    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();
     }
 
-    // The og:image may be given as a bare asset slug too. It is usually one of the brand slugs
-    // (a monogram, a logo), so check what was just resolved before fetching it again.
-    const rawImage = site.seo.image;
-    const ogImage =
-      rawImage && looksLikeAssetSlug(rawImage)
-        ? (brandBySlug.get(rawImage) ?? (await resolveAssetSlug(rawImage)))
-        : undefined;
-
-    // The top-level `site_logo` / `site_favicon` fields may be bare asset slugs too (like brand.*
-    // and og:image) — resolve them so they can reference an uploaded asset by slug. The brand-map
-    // aliases still win when present.
-    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,
+      logo: brand.logo ?? site.logo,
+      favicon: brand.favicon ?? site.favicon,
       seal: brand.seal ?? site.seal,
-      seo: { ...site.seo, image: ogImage ?? site.seo.image },
     };
   }
 

package/src/types.ts

@@ -7,6 +7,7 @@
  */
 
 import type { MarvinSiteEmbeds } from './embeds.js';
+import type { SitePrivacy } from './privacy.js';
 import type {
   CollectionEntry,
   Entry,
@@ -93,11 +94,11 @@ export type ApiSite = {
   canonicalUrl?: string;
   logo?: string;
   favicon?: string;
-  /** Round maker's stamp / seal — resolved from `site_metadata_json.brand.seal` (asset slug). */
+  /** Round maker's stamp / seal — `site_metadata_json.brand.seal`, when it is a URL. */
   seal?: string;
   /**
-   * Brand-asset registry: every `site_metadata_json.brand.<name>` slug resolved to its URL.
-   * Add a shared asset with one config line; components read `site.brand.<name>`.
+   * Brand-asset registry: every `site_metadata_json.brand.<name>` that is a URL, path or data URI,
+   * used as-is. Bare asset slugs are left out (Marvin no longer serves assets by slug).
    */
   brand?: Record<string, string>;
   locale: string;
@@ -111,6 +112,11 @@ export type ApiSite = {
    * Absent when the server predates media embeds.
    */
   embeds?: MarvinSiteEmbeds;
+  /**
+   * Privacy & cookie disclosures (`site.privacy`), normalized by `sitePrivacy`. Absent when the
+   * server predates them or none are configured.
+   */
+  privacy?: SitePrivacy;
   metadata: Record<string, unknown>;
 };
 
@@ -186,3 +192,12 @@ export type {
   MarvinEmbedStatus,
   MarvinSiteEmbeds,
 } from './embeds.js';
+export type {
+  ConsentCategory,
+  CookieCategory,
+  PrivacyConsent,
+  PrivacyController,
+  PrivacyCookie,
+  PrivacyProcessor,
+  SitePrivacy,
+} from './privacy.js';