create-shapio 0.2.0

package/templates/astro/shapio/models/siteSettings.json

@@ -0,0 +1,87 @@
+{
+  "apiKey": "siteSettings",
+  "display": {
+    "titleFieldId": "e54b64bb-62c9-4a9c-8842-f8af5151feac"
+  },
+  "draftAndPublish": true,
+  "fields": [
+    {
+      "apiKey": "siteName",
+      "deprecated": false,
+      "editor": {
+        "id": "textInput",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "e54b64bb-62c9-4a9c-8842-f8af5151feac",
+      "label": "Site name",
+      "localized": true,
+      "public": true,
+      "required": true,
+      "settings": {},
+      "sortable": false,
+      "type": "string",
+      "unique": false
+    },
+    {
+      "apiKey": "tagline",
+      "deprecated": false,
+      "editor": {
+        "id": "textarea",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "51448036-f103-46fa-8e2c-25e56e1c25fd",
+      "label": "Tagline",
+      "localized": true,
+      "public": true,
+      "required": false,
+      "settings": {},
+      "sortable": false,
+      "type": "text",
+      "unique": false
+    },
+    {
+      "apiKey": "footer",
+      "deprecated": false,
+      "editor": {
+        "id": "textInput",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "49c371ca-eb2f-4bed-b831-6dbc74ea6628",
+      "label": "Footer text",
+      "localized": true,
+      "public": true,
+      "required": false,
+      "settings": {},
+      "sortable": false,
+      "type": "string",
+      "unique": false
+    },
+    {
+      "apiKey": "colophon",
+      "deprecated": false,
+      "editor": {
+        "id": "richText",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "797ba365-a0fe-4572-a90f-9b524d12dc06",
+      "label": "Colophon",
+      "localized": true,
+      "public": true,
+      "required": false,
+      "settings": {
+        "formatVersion": 1
+      },
+      "sortable": false,
+      "type": "richtext",
+      "unique": false
+    }
+  ],
+  "id": "a1471f8b-5ee4-4a27-a7e0-934bb872b479",
+  "kind": "singleton",
+  "label": "Site settings",
+  "localized": true
+}

package/templates/astro/src/layouts/Base.astro

@@ -0,0 +1,52 @@
+---
+import '../styles/site.css';
+import { getSiteSettings } from '../lib/shapio.js';
+import { articlesPath, colophonPath, HOME_SLUG, otherLocale, pagePath, stringsFor, type Locale } from '../lib/site.js';
+
+type Props = {
+  title: string;
+  description?: string | null;
+  locale: Locale;
+  /** This page in the other locale. */
+  alternatePath?: string;
+  noindex?: boolean;
+};
+
+const { title, description, locale, alternatePath, noindex = false } = Astro.props;
+const strings = stringsFor(locale);
+const other = otherLocale(locale);
+// The name, tagline and footer come from the siteSettings singleton (the built-in strings until it is published).
+const settings = await getSiteSettings(locale);
+const siteName = settings?.siteName ?? strings.siteName;
+---
+
+<!doctype html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title} · {siteName}</title>
+    {description ? <meta name="description" content={description} /> : null}
+    {noindex ? <meta name="robots" content="noindex" /> : null}
+    {alternatePath ? <link rel="alternate" hreflang={other} href={alternatePath} /> : null}
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+  </head>
+  <body>
+    <a class="skip" href="#content">{strings.skipToContent}</a>
+    <header class="site-header">
+      <a class="brand" href={pagePath(locale, HOME_SLUG)}>{siteName}</a>
+      {settings?.tagline ? <p class="tagline">{settings.tagline}</p> : null}
+      <nav aria-label="Main">
+        <a href={articlesPath(locale)}>{strings.articles}</a>
+        <a href={colophonPath(locale)}>{strings.colophon}</a>
+        <a href={alternatePath ?? pagePath(other, HOME_SLUG)} hreflang={other} lang={other}>{strings.switchTo}</a>
+      </nav>
+    </header>
+    <main id="content">
+      <slot />
+    </main>
+    <footer class="site-footer">
+      <p>{siteName} · {settings?.footer ?? 'Built with Shapio'} · Astro</p>
+    </footer>
+  </body>
+</html>

package/templates/astro/src/lib/config.ts

@@ -0,0 +1,42 @@
+/**
+ * Build-time settings, from the environment (or `.env` in this folder, which `npm run seed` writes):
+ * - SHAPIO_URL: the Shapio origin (with BASE_PATH), e.g. https://cms.example.com.
+ * - SHAPIO_DELIVERY_TOKEN: a read-only delivery token (Settings → API tokens, delivery role).
+ * - SHAPIO_SNAPSHOT: optional; the publication snapshot to build. A generic-webhook trigger carries it;
+ *   without it the build pins the latest snapshot when it starts.
+ * - SHAPIO_SITE: optional; the site key on a multi-site Shapio (default: the token's site, else the primary).
+ * - PUBLIC_SHAPIO_URL: the origin the browser calls for previews (defaults to SHAPIO_URL).
+ */
+const read = (name: string): string | undefined => {
+  const fromVite = (import.meta as { env?: Record<string, string | undefined> }).env?.[name];
+  const value = fromVite ?? process.env[name];
+  return value === undefined || value === '' ? undefined : value;
+};
+
+export const shapioUrl = () => read('SHAPIO_URL') ?? 'http://localhost:4300';
+
+export const deliveryToken = () => {
+  const token = read('SHAPIO_DELIVERY_TOKEN');
+  if (!token) {
+    throw new Error(
+      'Set SHAPIO_DELIVERY_TOKEN (a Shapio delivery token) to build the site; `npm run seed` writes one to .env',
+    );
+  }
+  return token;
+};
+
+export const configuredSnapshot = (): number | undefined => {
+  const value = read('SHAPIO_SNAPSHOT');
+  if (value === undefined) {
+    return undefined;
+  }
+  const snapshot = Number(value);
+  if (!Number.isInteger(snapshot) || snapshot < 0) {
+    throw new Error(`SHAPIO_SNAPSHOT must be a publication snapshot number, got "${value}"`);
+  }
+  return snapshot;
+};
+
+export const publicShapioUrl = () => read('PUBLIC_SHAPIO_URL') ?? shapioUrl();
+
+export const siteKey = () => read('SHAPIO_SITE');

package/templates/astro/src/lib/preview.ts

@@ -0,0 +1,57 @@
+import { createClient } from '@shapio/client';
+import { renderArticle, renderPage } from './render.js';
+import { DEFAULT_LOCALE, stringsFor } from './site.js';
+import type { Article, DeliveryItem, Page } from './types.js';
+
+/**
+ * Preview: Shapio opens `/preview/?model={modelKey}&id={entryId}&locale={locale}#token={token}` (the
+ * connection's preview URL template). `{modelKey}` is the model's route key, as in the delivery and preview
+ * APIs: the plural API ID of a collection (`pages`, `articles`). The token sits in the fragment, so it never reaches a server log or a
+ * Referer header; it is a scoped, expiring preview token, never an admin credential. The draft is read from
+ * `/api/preview/content/...` and rendered with the same functions as the published pages.
+ */
+export const PREVIEW_MODELS = ['pages', 'articles'] as const;
+
+export type PreviewRequest = {
+  token: string;
+  modelKey: (typeof PREVIEW_MODELS)[number];
+  entryId: string;
+  locale: string;
+};
+
+/** Reads the request from a preview URL; undefined when something is missing or unknown. */
+export const parsePreviewUrl = (url: URL): PreviewRequest | undefined => {
+  const fragment = new URLSearchParams(url.hash.slice(1));
+  const token = fragment.get('token') ?? url.searchParams.get('token');
+  const modelKey = url.searchParams.get('model');
+  const entryId = url.searchParams.get('id');
+  if (!token || !entryId || !(PREVIEW_MODELS as readonly string[]).includes(modelKey ?? '')) {
+    return undefined;
+  }
+  return {
+    token,
+    modelKey: modelKey as PreviewRequest['modelKey'],
+    entryId,
+    locale: url.searchParams.get('locale') ?? DEFAULT_LOCALE,
+  };
+};
+
+/** Fetches the draft through the preview API and renders it. */
+export const loadPreview = async (
+  shapioUrl: string,
+  request: PreviewRequest,
+): Promise<{ html: string; title: string }> => {
+  const client = createClient({ baseUrl: shapioUrl, token: request.token });
+  const params = new URLSearchParams({
+    locale: request.locale,
+    ...(request.modelKey === 'articles' ? { populate: 'author' } : {}),
+  });
+  const { data } = await client.request<DeliveryItem<Page | Article>>(
+    `/api/preview/content/${encodeURIComponent(request.modelKey)}/${encodeURIComponent(request.entryId)}?${params.toString()}`,
+  );
+  const context = { locale: request.locale, strings: stringsFor(request.locale) };
+  return {
+    title: data.title,
+    html: request.modelKey === 'pages' ? renderPage(data as Page) : renderArticle(data as Article, context),
+  };
+};

package/templates/astro/src/lib/render.ts

@@ -0,0 +1,146 @@
+import { shapioAttr, type EntryRef } from '@shapio/visual';
+import { articlePath, formatDate, type Strings } from './site.js';
+import type { Article, Author, Media, Section } from './types.js';
+
+/**
+ * HTML for the site's content, as plain functions: the static pages render with them at build time and the
+ * preview page renders drafts with the same functions in the browser, so a preview looks exactly like the
+ * published page. Every string from the CMS is escaped; rich text arrives as Shapio's sanitised `html`.
+ */
+export type RenderContext = { locale: string; strings: Strings };
+
+const ESCAPES: Readonly<Record<string, string>> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+
+export const escapeHtml = (value: string): string =>
+  value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+
+/** Links from content: web, mail, phone and site-relative only (a `javascript:` URL renders as `#`). */
+export const safeHref = (value: string | null | undefined): string => {
+  const href = (value ?? '').trim();
+  return /^(https?:\/\/|mailto:|tel:|\/(?!\/)|#)/i.test(href) ? escapeHtml(href) : '#';
+};
+
+/**
+ * `shapioAttr` as an HTML attribute string: the field an element shows, so Shapio's preview can take a click on
+ * it back to that field (@shapio/visual). Harmless on published pages (entry IDs and API IDs only).
+ */
+export const visualAttributes = (entry: EntryRef, path: string): string =>
+  Object.entries(shapioAttr(entry, path))
+    .map(([name, value]) => ` ${name}="${escapeHtml(value)}"`)
+    .join('');
+
+const paragraph = (text: string | null | undefined, className = '') =>
+  text ? `<p${className ? ` class="${className}"` : ''}>${escapeHtml(text)}</p>` : '';
+
+type ImageOptions = { sizes: string; eager?: boolean; className?: string; attributes?: string };
+
+/** A responsive `<img>`: WebP variants in `srcset`, intrinsic size set (no layout shift), lazy unless eager. */
+export const responsiveImage = (
+  media: Media,
+  { sizes, eager = false, className, attributes: extra = '' }: ImageOptions,
+): string => {
+  const widths = media.variants
+    .filter((variant) => variant.name.startsWith('w') && variant.width !== null)
+    .sort((a, b) => (a.width ?? 0) - (b.width ?? 0));
+  const largest = widths.at(-1);
+  const srcset = widths.map((variant) => `${variant.url} ${variant.width}w`);
+  const attributes = [
+    `src="${escapeHtml(largest?.url ?? media.url)}"`,
+    srcset.length > 0 ? `srcset="${escapeHtml(srcset.join(', '))}" sizes="${escapeHtml(sizes)}"` : '',
+    media.width && media.height ? `width="${media.width}" height="${media.height}"` : '',
+    `alt="${escapeHtml(media.alt)}"`,
+    eager ? 'loading="eager" fetchpriority="high"' : 'loading="lazy"',
+    'decoding="async"',
+    className ? `class="${className}"` : '',
+  ];
+  return `<img ${attributes.filter(Boolean).join(' ')}${extra}>`;
+};
+
+const renderSection = (section: Section, index: number, entry: EntryRef): string => {
+  switch (section.__component) {
+    case 'hero': {
+      const heading = index === 0 ? 'h1' : 'h2';
+      return `<section class="hero">
+  <div class="hero-text">
+    <${heading}${visualAttributes(entry, `sections/${index}/heading`)}>${escapeHtml(section.heading)}</${heading}>
+    ${paragraph(section.subheading, 'lead')}
+    ${section.ctaLabel && section.ctaUrl ? `<a class="button" href="${safeHref(section.ctaUrl)}">${escapeHtml(section.ctaLabel)}</a>` : ''}
+  </div>
+  ${section.image ? responsiveImage(section.image, { sizes: '(min-width: 64rem) 50vw, 100vw', eager: index === 0, className: 'hero-image' }) : ''}
+</section>`;
+    }
+    case 'featureGrid':
+      return `<section class="features">
+  ${section.heading ? `<h2>${escapeHtml(section.heading)}</h2>` : ''}
+  <ul class="feature-grid">${section.features
+    .map((feature) => `<li><h3>${escapeHtml(feature.title)}</h3>${paragraph(feature.description)}</li>`)
+    .join('')}</ul>
+</section>`;
+    case 'gallery':
+      return `<section class="gallery">
+  ${section.heading ? `<h2>${escapeHtml(section.heading)}</h2>` : ''}
+  <ul class="gallery-grid">${section.images
+    .map(
+      (image) =>
+        `<li><figure>${responsiveImage(image, { sizes: '(min-width: 48rem) 33vw, 100vw' })}${image.caption ? `<figcaption>${escapeHtml(image.caption)}</figcaption>` : ''}</figure></li>`,
+    )
+    .join('')}</ul>
+</section>`;
+    case 'callToAction':
+      return `<section class="cta">
+  <h2>${escapeHtml(section.heading)}</h2>
+  ${paragraph(section.text)}
+  <a class="button" href="${safeHref(section.buttonUrl)}">${escapeHtml(section.buttonLabel)}</a>
+</section>`;
+    default:
+      // A section type this site does not know yet (added in Shapio after the last site deploy): skipped.
+      return '';
+  }
+};
+
+/** A page's dynamic zone. The page title is the heading when the page does not open with a hero. */
+export const renderPage = (page: {
+  id: string;
+  locale: string;
+  title: string;
+  sections: Section[];
+}): string => {
+  const opensWithHero = page.sections[0]?.__component === 'hero';
+  return `${opensWithHero ? '' : `<h1 class="page-title"${visualAttributes(page, 'title')}>${escapeHtml(page.title)}</h1>`}${page.sections
+    .map((section, index) => renderSection(section, index, page))
+    .join('\n')}`;
+};
+
+const authorOf = (article: Article): Author | null =>
+  typeof article.author === 'object' && article.author !== null ? article.author : null;
+
+const byline = (article: Article, context: RenderContext) => {
+  const author = authorOf(article);
+  return `<p class="byline">${author ? `${context.strings.by} ${escapeHtml(author.name)} · ` : ''}<time datetime="${escapeHtml(article.publishedOn)}">${formatDate(article.publishedOn, context.locale)}</time></p>`;
+};
+
+export const renderArticle = (article: Article, context: RenderContext): string => {
+  const author = authorOf(article);
+  return `<article class="article" lang="${escapeHtml(article.locale)}">
+  <header>
+    <h1${visualAttributes(article, 'title')}>${escapeHtml(article.title)}</h1>
+    ${byline(article, context)}
+  </header>
+  ${article.cover ? responsiveImage(article.cover, { sizes: '(min-width: 48rem) 48rem, 100vw', eager: true, className: 'cover', attributes: visualAttributes(article, 'cover') }) : ''}
+  <div class="prose"${visualAttributes(article, 'body')}>${article.body?.html ?? ''}</div>
+  ${author ? `<aside class="author">${author.avatar ? responsiveImage(author.avatar, { sizes: '4rem', className: 'avatar' }) : ''}<div><p class="author-name">${escapeHtml(author.name)}</p>${paragraph(author.bio)}</div></aside>` : ''}
+</article>`;
+};
+
+export const renderArticleCard = (article: Article, context: RenderContext): string => `<li class="card">
+  ${article.cover ? responsiveImage(article.cover, { sizes: '(min-width: 48rem) 33vw, 100vw' }) : ''}
+  <h2${visualAttributes(article, 'title')}><a href="${escapeHtml(articlePath(context.locale, article.slug))}">${escapeHtml(article.title)}</a></h2>
+  ${byline(article, context)}
+  ${paragraph(article.excerpt)}
+</li>`;

package/templates/astro/src/lib/shapio.ts

@@ -0,0 +1,104 @@
+import { createClient, ShapioApiError } from '@shapio/client';
+import { configuredSnapshot, deliveryToken, shapioUrl, siteKey } from './config.js';
+import type { Locale } from './site.js';
+import type { Article, DeliveryList, Page, SiteSettings } from './types.js';
+
+/**
+ * The site's read side: Shapio's delivery API through `@shapio/client`, pinned to one publication snapshot
+ * for the whole build. The snapshot is read once, when the build starts (or taken from SHAPIO_SNAPSHOT), and
+ * sent with every request, so a page built a minute later still shows the same moment: a publish during the
+ * build never yields a site that mixes old and new content.
+ */
+const PAGE_SIZE = 100;
+
+/** Delivery addresses a collection by its plural API ID (`/api/content/pages`), not its API ID (`page`). */
+const PAGES = 'pages';
+const ARTICLES = 'articles';
+
+/**
+ * The fields each listing renders, sent as `fields=`: the response carries only these, and Shapio's field
+ * usage shows exactly what the site reads (a whole-model read would count every field as used).
+ */
+const PAGE_FIELDS = 'title,slug,description,sections';
+const ARTICLE_FIELDS = 'title,slug,excerpt,body,cover,author,publishedOn';
+
+/** The `siteSettings` singleton is read by its API ID (singletons have no plural). */
+const SITE_SETTINGS = 'siteSettings';
+const SITE_SETTINGS_FIELDS = ['siteName', 'tagline', 'footer', 'colophon'];
+
+let client: ReturnType<typeof createClient> | undefined;
+const shapio = () =>
+  (client ??= createClient({ baseUrl: shapioUrl(), token: deliveryToken(), site: siteKey() }));
+
+let pinned: Promise<number> | undefined;
+
+/** The snapshot every request of this build reads. */
+export const pinnedSnapshot = (): Promise<number> =>
+  (pinned ??= (async () => {
+    const configured = configuredSnapshot();
+    if (configured !== undefined) {
+      return configured;
+    }
+    const { snapshot } = await shapio().snapshots.current();
+    // Shared with any other copy of this module in the build (one value per build).
+    process.env.SHAPIO_SNAPSHOT = String(snapshot);
+    return snapshot;
+  })());
+
+const query = (params: Record<string, string | number>) =>
+  new URLSearchParams(Object.entries(params).map(([key, value]) => [key, String(value)])).toString();
+
+/** Every published entry of a collection (by plural API ID) in one locale, page by page, at the pinned snapshot. */
+const listAll = async <T>(
+  routeKey: string,
+  locale: Locale,
+  extra: Record<string, string> = {},
+): Promise<T[]> => {
+  const snapshot = await pinnedSnapshot();
+  const entries: T[] = [];
+  for (let page = 1; ; page += 1) {
+    const result = await shapio().request<DeliveryList<T>>(
+      `/api/content/${routeKey}?${query({ locale, snapshot, page, pageSize: PAGE_SIZE, ...extra })}`,
+    );
+    entries.push(...result.data);
+    if (page >= result.meta.pagination.pageCount) {
+      return entries;
+    }
+  }
+};
+
+export const listPages = (locale: Locale) => listAll<Page>(PAGES, locale, { fields: PAGE_FIELDS });
+
+export const listArticles = (locale: Locale) =>
+  listAll<Article>(ARTICLES, locale, {
+    fields: ARTICLE_FIELDS,
+    populate: 'author',
+    sort: 'publishedOn:desc',
+  });
+
+const settingsByLocale = new Map<Locale, Promise<SiteSettings | null>>();
+
+/** The site settings singleton in one locale at the pinned snapshot; null until it is published. */
+export const getSiteSettings = (locale: Locale): Promise<SiteSettings | null> => {
+  let settings = settingsByLocale.get(locale);
+  if (!settings) {
+    settings = (async () => {
+      try {
+        const snapshot = await pinnedSnapshot();
+        const { data } = await shapio().delivery.singleton<SiteSettings>(SITE_SETTINGS, {
+          locale,
+          snapshot,
+          fields: SITE_SETTINGS_FIELDS,
+        });
+        return data;
+      } catch (error) {
+        if (error instanceof ShapioApiError && error.status === 404) {
+          return null;
+        }
+        throw error;
+      }
+    })();
+    settingsByLocale.set(locale, settings);
+  }
+  return settings;
+};

package/templates/astro/src/lib/site.ts

@@ -0,0 +1,55 @@
+/** The site's locales (they must exist in Shapio: the seed creates `fr`; `en` is Shapio's default). */
+export const LOCALES = ['en', 'fr'] as const;
+export type Locale = (typeof LOCALES)[number];
+export const DEFAULT_LOCALE: Locale = 'en';
+
+/** The page whose slug is `home` is each locale's front page. */
+export const HOME_SLUG = 'home';
+
+export const isLocale = (value: string): value is Locale => (LOCALES as readonly string[]).includes(value);
+
+const STRINGS = {
+  en: {
+    siteName: 'Northwind Studio',
+    articles: 'Journal',
+    readMore: 'Read the article',
+    by: 'By',
+    publishedOn: 'Published',
+    switchTo: 'Français',
+    allArticles: 'All articles',
+    colophon: 'Colophon',
+    previewBanner: 'Preview: this is a draft, not the published page.',
+    previewLoading: 'Loading the draft…',
+    previewFailed: 'The preview could not be loaded',
+    skipToContent: 'Skip to content',
+  },
+  fr: {
+    siteName: 'Studio Northwind',
+    articles: 'Journal',
+    readMore: "Lire l'article",
+    by: 'Par',
+    publishedOn: 'Publié le',
+    switchTo: 'English',
+    allArticles: 'Tous les articles',
+    colophon: 'Colophon',
+    previewBanner: 'Aperçu : ceci est un brouillon, pas la page publiée.',
+    previewLoading: 'Chargement du brouillon…',
+    previewFailed: "L'aperçu n'a pas pu être chargé",
+    skipToContent: 'Aller au contenu',
+  },
+} as const satisfies Record<Locale, Record<string, string>>;
+
+export type Strings = (typeof STRINGS)[Locale];
+
+export const stringsFor = (locale: string): Strings => STRINGS[isLocale(locale) ? locale : DEFAULT_LOCALE];
+
+export const otherLocale = (locale: Locale): Locale => (locale === 'en' ? 'fr' : 'en');
+
+export const formatDate = (iso: string, locale: string) =>
+  new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(new Date(iso));
+
+export const pagePath = (locale: string, slug: string) =>
+  slug === HOME_SLUG ? `/${locale}/` : `/${locale}/${slug}/`;
+export const articlesPath = (locale: string) => `/${locale}/articles/`;
+export const articlePath = (locale: string, slug: string) => `/${locale}/articles/${slug}/`;
+export const colophonPath = (locale: string) => `/${locale}/colophon/`;

package/templates/astro/src/lib/types.ts

@@ -0,0 +1,96 @@
+/**
+ * Content as the Shapio delivery API returns it for this site's models (shapio/). Delivery
+ * entries are flat: system attributes next to the fields, keyed by API key. Media fields are asset views,
+ * rich text carries the JSON document plus a sanitised `html` rendering, populated relations are entries.
+ */
+export type MediaVariant = {
+  name: string;
+  width: number | null;
+  height: number | null;
+  format: string;
+  mimeType: string;
+  url: string;
+};
+
+export type Media = {
+  id: string;
+  filename: string;
+  mimeType: string;
+  width: number | null;
+  height: number | null;
+  alt: string;
+  caption: string;
+  url: string;
+  variants: MediaVariant[];
+};
+
+export type RichText = { format: 'shapio-richtext'; version: number; html: string };
+
+type EntryBase = {
+  id: string;
+  /** The locale that served the entry (differs from the requested one on fallback). */
+  locale: string;
+  createdAt: string;
+  updatedAt: string;
+  publishedAt?: string;
+};
+
+export type Feature = { title: string; description: string | null };
+
+export type HeroSection = {
+  __component: 'hero';
+  heading: string;
+  subheading: string | null;
+  image: Media | null;
+  ctaLabel: string | null;
+  ctaUrl: string | null;
+};
+export type FeatureGridSection = { __component: 'featureGrid'; heading: string | null; features: Feature[] };
+export type GallerySection = { __component: 'gallery'; heading: string | null; images: Media[] };
+export type CallToActionSection = {
+  __component: 'callToAction';
+  heading: string;
+  text: string | null;
+  buttonLabel: string;
+  buttonUrl: string;
+};
+export type Section = HeroSection | FeatureGridSection | GallerySection | CallToActionSection;
+
+export type Page = EntryBase & {
+  title: string;
+  slug: string;
+  description: string | null;
+  sections: Section[];
+};
+
+export type Author = EntryBase & { name: string; bio: string | null; avatar: Media | null };
+
+export type Article = EntryBase & {
+  title: string;
+  slug: string;
+  excerpt: string | null;
+  body: RichText | null;
+  cover: Media | null;
+  /** Populated (`populate=author`) or just the ID; null when the author is not published. */
+  author: Author | string | null;
+  publishedOn: string;
+};
+
+/** The `siteSettings` singleton: one entry per site, read by its API ID. */
+export type SiteSettings = EntryBase & {
+  siteName: string;
+  tagline: string | null;
+  footer: string | null;
+  colophon: RichText | null;
+};
+
+export type DeliveryList<T> = {
+  data: T[];
+  meta: {
+    locale: string;
+    snapshot: number;
+    pagination: { page: number; pageSize: number; total: number; pageCount: number };
+  };
+};
+
+export type DeliveryItem<T> = { data: T; meta: { locale: string; snapshot: number } };

package/templates/astro/src/pages/404.astro

@@ -0,0 +1,8 @@
+---
+import Base from '../layouts/Base.astro';
+---
+
+<Base title="Not found" locale="en" noindex>
+  <h1 class="page-title">Page not found</h1>
+  <p><a href="/en/">Back to the home page</a></p>
+</Base>