create-shapio 0.2.0

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

@@ -0,0 +1,96 @@
+/**
+ * Content as the Shapio delivery API returns it for the starter'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/next/src/lib/webhookEvent.test.ts

@@ -0,0 +1,61 @@
+import { createHmac } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import { readWebhookEvent } from './webhookEvent';
+
+const SECRET = 'test-secret';
+const NOW = new Date('2026-10-03T12:00:00Z');
+const BODY = JSON.stringify({
+  id: 'evt-1',
+  type: 'entry.published',
+  createdAt: NOW.toISOString(),
+  site: null,
+  data: {},
+});
+
+const signed = (body: string, { secret = SECRET, at = NOW } = {}) => {
+  const timestamp = String(Math.floor(at.getTime() / 1000));
+  const signature = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
+  return new Request('http://localhost/api/revalidate', {
+    method: 'POST',
+    headers: { 'x-shapio-timestamp': timestamp, 'x-shapio-signature': `v1=${signature}` },
+    body,
+  });
+};
+
+describe('readWebhookEvent', () => {
+  it('accepts a correctly signed event', async () => {
+    const read = await readWebhookEvent(signed(BODY), SECRET, NOW);
+    expect(read).toMatchObject({ ok: true, event: { id: 'evt-1', type: 'entry.published' } });
+  });
+
+  it('refuses another secret, a stale timestamp and a missing signature', async () => {
+    expect(await readWebhookEvent(signed(BODY, { secret: 'other' }), SECRET, NOW)).toMatchObject({
+      ok: false,
+      status: 401,
+      reason: 'signature mismatch',
+    });
+    const stale = new Date(NOW.getTime() - 10 * 60 * 1000);
+    expect(await readWebhookEvent(signed(BODY, { at: stale }), SECRET, NOW)).toMatchObject({
+      ok: false,
+      status: 401,
+    });
+    const unsigned = new Request('http://localhost/api/revalidate', { method: 'POST', body: BODY });
+    expect(await readWebhookEvent(unsigned, SECRET, NOW)).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('refuses a body changed after signing', async () => {
+    const request = signed(BODY);
+    const tampered = new Request(request.url, {
+      method: 'POST',
+      headers: request.headers,
+      body: BODY.replace('evt-1', 'evt-2'),
+    });
+    expect(await readWebhookEvent(tampered, SECRET, NOW)).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('answers 503 without a configured secret and 400 for a signed non-event', async () => {
+    expect(await readWebhookEvent(signed(BODY), undefined, NOW)).toMatchObject({ ok: false, status: 503 });
+    expect(await readWebhookEvent(signed('[]'), SECRET, NOW)).toMatchObject({ ok: false, status: 400 });
+    expect(await readWebhookEvent(signed('not json'), SECRET, NOW)).toMatchObject({ ok: false, status: 400 });
+  });
+});

package/templates/next/src/lib/webhookEvent.ts

@@ -0,0 +1,47 @@
+import {
+  verifyWebhookSignature,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER,
+  type WebhookEventBody,
+} from '@shapio/client';
+
+export type WebhookEventRead =
+  { ok: true; event: WebhookEventBody } | { ok: false; status: 400 | 401 | 503; reason: string };
+
+const isEventBody = (value: unknown): value is WebhookEventBody =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as { id?: unknown }).id === 'string' &&
+  typeof (value as { type?: unknown }).type === 'string';
+
+/**
+ * Reads a Shapio webhook delivery: checks `X-Shapio-Signature` over the raw body with the webhook's secret
+ * (and the timestamp's freshness), then parses the event. Nothing in the body is trusted before that.
+ */
+export const readWebhookEvent = async (
+  request: Request,
+  secret: string | undefined,
+  now = new Date(),
+): Promise<WebhookEventRead> => {
+  if (!secret) {
+    return { ok: false, status: 503, reason: 'SHAPIO_WEBHOOK_SECRET is not set' };
+  }
+  const body = await request.text();
+  const check = await verifyWebhookSignature({
+    secret,
+    signature: request.headers.get(WEBHOOK_SIGNATURE_HEADER),
+    timestamp: request.headers.get(WEBHOOK_TIMESTAMP_HEADER),
+    body,
+    now,
+  });
+  if (!check.ok) {
+    return { ok: false, status: 401, reason: check.reason };
+  }
+  let event: unknown;
+  try {
+    event = JSON.parse(body);
+  } catch {
+    return { ok: false, status: 400, reason: 'the body is not JSON' };
+  }
+  return isEventBody(event) ? { ok: true, event } : { ok: false, status: 400, reason: 'not a Shapio event' };
+};

package/templates/next/src/styles.d.ts

@@ -0,0 +1,3 @@
+// Global stylesheets are imported for their side effect (Next's own declarations arrive in next-env.d.ts,
+// which `next build` writes; this keeps `npm run typecheck` working before the first build).
+declare module '*.css';

package/templates/next/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["dom", "dom.iterable", "es2024"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "types": ["node"],
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/sveltekit/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env, or let `npm run seed` write SHAPIO_URL and SHAPIO_DELIVERY_TOKEN for you.
+SHAPIO_URL=http://localhost:4300
+# A read-only delivery token (Shapio admin: Settings → API tokens, a delivery role).
+SHAPIO_DELIVERY_TOKEN=
+# Optional: build this publication snapshot instead of the latest one.
+# SHAPIO_SNAPSHOT=42
+# Optional: the site key on a multi-site Shapio (default: the token's site, else the primary site).
+# SHAPIO_SITE=marketing
+# Optional: the Shapio URL the browser calls for draft previews, when it differs from SHAPIO_URL.
+# PUBLIC_SHAPIO_URL=https://cms.example.com

package/templates/sveltekit/README.md

@@ -0,0 +1,38 @@
+# Shapio starter: SvelteKit
+
+A [SvelteKit 3](https://svelte.dev) site built from [Shapio](https://github.com/mybrokengnome/shapio) content:
+pages made of sections, a journal of articles with an author, and the `siteSettings` singleton, in English and
+French. Every page is prerendered to static HTML (adapter-static) from one pinned publication snapshot.
+
+You need a running Shapio (>= 0.1) with an owner account.
+
+```sh
+npm install
+SHAPIO_URL=http://localhost:4300 SHAPIO_ADMIN_EMAIL=you@example.com SHAPIO_ADMIN_PASSWORD='…' npm run seed
+npm run build       # → build/
+npm run preview     # http://localhost:4173/ (redirects to /en/)
+npm run smoke       # in another shell: checks the served pages over HTTP
+```
+
+`npm run seed` applies the models in `shapio/` to Shapio live, creates the content and writes `SHAPIO_URL` and
+`SHAPIO_DELIVERY_TOKEN` to `.env`. `SHAPIO_SNAPSHOT` pins a build to an exact snapshot (by default the latest
+one, read once when prerendering starts); `SHAPIO_SITE` picks the site on a multi-site instance.
+
+| File                         | Role                                                                |
+| ---------------------------- | ------------------------------------------------------------------- |
+| `src/env.ts`                 | the settings the build reads (`SHAPIO_*`, from the environment)     |
+| `src/lib/server/shapio.ts`   | reads the delivery API with `@shapio/client` at the pinned snapshot |
+| `src/routes/[locale]/…`      | the layout (site settings), pages, articles and the colophon        |
+| `src/lib/components/…`       | sections, articles and responsive images                            |
+| `src/routes/preview/`        | draft preview with visual editing (`@shapio/visual`)                |
+| `vite.config.ts`             | `frame-ancestors` for the servers and `build/_headers`              |
+| `shapio/`, `scripts/seed.ts` | the models and the seed                                             |
+
+Preview: the seed creates a deployment connection named **Preview** that opens drafts at
+`http://localhost:5173/preview/` (`npm run dev`; set `SITE_URL` when seeding for another address). Add that
+origin to Shapio's `CORS_ORIGINS`. In Shapio's preview pane, clicking the title, body or cover focuses that
+field and saves re-render the draft ([visual editing](https://github.com/mybrokengnome/shapio/blob/main/documentation/visual-editing.md)). `PUBLIC_SHAPIO_URL` sets the Shapio URL the
+browser calls, when it differs from `SHAPIO_URL`.
+
+Guide: [site starters](https://github.com/mybrokengnome/shapio/blob/main/documentation/starters.md). Inside the
+Shapio repository, run the scripts with `pnpm --filter example-sveltekit <script>` after `pnpm build`.

package/templates/sveltekit/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.svelte-kit/
+build/
+.env

package/templates/sveltekit/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "example-sveltekit",
+  "version": "0.1.0",
+  "private": true,
+  "description": "SvelteKit starter: pages and articles from Shapio, prerendered to static HTML at one pinned snapshot, EN + FR.",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "imports": {
+    "#lib": "./src/lib",
+    "#lib/*": "./src/lib/*"
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo ''",
+    "seed": "node --env-file-if-exists=.env --import tsx scripts/seed.ts --site-url http://localhost:5173",
+    "smoke": "node --import tsx scripts/smokeHttp.ts --url http://localhost:4173",
+    "typecheck": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings"
+  },
+  "dependencies": {
+    "@shapio/client": "^0.2.0",
+    "@shapio/visual": "^0.2.0"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "4.0.0",
+    "@sveltejs/kit": "3.0.0",
+    "@sveltejs/vite-plugin-svelte": "7.3.1",
+    "@types/node": "24.19.1",
+    "svelte": "5.57.1",
+    "svelte-check": "4.7.6",
+    "tsx": "4.23.15",
+    "typescript": "6.0.3",
+    "vite": "8.3.2"
+  }
+}

package/templates/sveltekit/scripts/lib/admin.ts

@@ -0,0 +1,76 @@
+import { createClient, type ShapioClient } from '@shapio/client';
+
+/**
+ * How the seed talks to Shapio's admin API: with SHAPIO_TOKEN (an admin API token), or with
+ * SHAPIO_ADMIN_EMAIL + SHAPIO_ADMIN_PASSWORD, in which case it signs in, creates a one-hour admin API token
+ * for itself (the schema CLI needs a bearer token) and revokes it when done.
+ */
+export type AdminConnection = {
+  url: string;
+  token: string;
+  client: ShapioClient;
+  /** A signed-in admin session (email and password only): preview tokens are issued to people, not API tokens. */
+  session: ShapioClient | undefined;
+  close: () => Promise<void>;
+};
+
+const SESSION_COOKIE = 'shapio_session';
+const SEED_TOKEN_TTL_MS = 60 * 60 * 1000;
+
+const signIn = async (url: string, email: string, password: string) => {
+  const response = await fetch(`${url.replace(/\/+$/, '')}/api/admin/auth/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  });
+  if (!response.ok) {
+    throw new Error(`Signing in as ${email} failed: HTTP ${response.status} ${await response.text()}`);
+  }
+  const cookie = response.headers.getSetCookie().find((value) => value.startsWith(`${SESSION_COOKIE}=`));
+  const { csrfToken } = (await response.json()) as { csrfToken: string };
+  if (!cookie) {
+    throw new Error('Signing in returned no session cookie');
+  }
+  return createClient({
+    baseUrl: url,
+    headers: () => ({ cookie: cookie.split(';')[0] ?? '', 'x-csrf-token': csrfToken }),
+  });
+};
+
+export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnection> => {
+  const url = env.SHAPIO_URL ?? 'http://localhost:4300';
+  if (env.SHAPIO_TOKEN) {
+    return {
+      url,
+      token: env.SHAPIO_TOKEN,
+      client: createClient({ baseUrl: url, token: env.SHAPIO_TOKEN }),
+      session: undefined,
+      close: async () => undefined,
+    };
+  }
+  const email = env.SHAPIO_ADMIN_EMAIL;
+  const password = env.SHAPIO_ADMIN_PASSWORD;
+  if (!email || !password) {
+    throw new Error('Set SHAPIO_TOKEN (an admin API token), or SHAPIO_ADMIN_EMAIL and SHAPIO_ADMIN_PASSWORD');
+  }
+  const session = await signIn(url, email, password);
+  const roles = await session.admin.roles.list();
+  const admin = roles.find((role) => role.key === 'admin');
+  if (!admin) {
+    throw new Error('The built-in admin role is missing');
+  }
+  const created = await session.admin.tokens.create({
+    name: 'starter seed (temporary)',
+    roleId: admin.id,
+    // A network token: the seed applies models and adds locales, which are network actions.
+    network: true,
+    expiresAt: new Date(Date.now() + SEED_TOKEN_TTL_MS).toISOString(),
+  });
+  return {
+    url,
+    token: created.token,
+    client: createClient({ baseUrl: url, token: created.token }),
+    session,
+    close: () => session.admin.tokens.revoke(created.apiToken.id),
+  };
+};