@soloworks/smking-next 0.21.0 → 0.21.2

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @soloworks/smking-next
 
+## 0.21.2 — 2026-07-02
+
+**CMS taxonomy page types caught up with the SaaS catalog (types only — no runtime change).**
+
+The CMS page model now includes the `taxonomy` content type used by protected
+category and tag index pages. This keeps the published SDK type surface aligned
+with the SaaS block contract after the taxonomy-page normalization work.
+
+## 0.21.1 — 2026-06-12
+
+**Webhook replay protection (security review M6).**
+
+The webhook receiver now rejects deliveries whose `deliveredAt` falls
+outside a ±5-minute window (401 `stale_delivery`; a missing field counts
+as stale — the SaaS has sent it since v0.11) and dedupes `deliveryId`
+re-sends inside that window (401 `duplicate_delivery`). Dedup is
+best-effort in-memory per serverless instance; the time window is the
+primary defense. The SaaS now stamps every delivery with a unique
+`deliveryId` — payloads from a SaaS predating the field skip dedup and
+keep working. Both fields sit inside the HMAC-signed JSON body, so an
+attacker can't forge or strip them. No customer action needed; `^0.21`
+picks this up automatically.
+
+**Mode B block types caught up with the SaaS catalog (types only — no
+runtime change).**
+
+The `Block` union had drifted to 3 of the SaaS's 10 block components; it
+now covers all of them — added `search`, `nav-recent-posts`,
+`nav-related-posts`, `nav-category-index`, `image`, `slideshow`, and
+`social-share` (plus the missing `NavSnapshotEntry.href` field). The types
+are no longer a hand-maintained mirror: the monorepo's `@smking/shared`
+package is the single source of truth and `src/cms-blocks.ts` is a
+generated vendored copy (`pnpm sync:block-types`, guarded by a vitest
+sync test). All block prop interfaces are also exported from the package
+root now (`Block`, `BlockComponent`, `SearchProps`, …). Mode A
+(`bodyHtml`) rendering is unaffected.
+
 ## 0.21.0 — 2026-06-09
 
 **Per-site CMS theme — `<SmkingRuntime>` now mounts a `theme.css` stylesheet.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "description": "AI-native SEO (AEO) for Next.js — auto-inject JSON-LD, FAQ, AI summary, and SEO metadata so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your pages.",
   "license": "MIT",
   "homepage": "https://github.com/sillyleo/smking/tree/main/packages/smking-next",

package/src/cms-blocks.ts

@@ -0,0 +1,470 @@
+// GENERATED FILE — do not edit by hand.
+// Vendored copy of packages/shared/src/types/cms-blocks.ts (the SDK ships
+// raw src/ to npm, so it can't import the private workspace package).
+// Regenerate with: pnpm sync:block-types
+
+/**
+ * CMS block primitives — substrate-pivot v2.
+ *
+ * Single source of truth for the Mode B (blocks JSON) contract shared by
+ * the SaaS dashboard (`apps/web/src/features/cms`) and the customer SDKs.
+ * The dashboard editor serializes Plate documents into this shape, the
+ * publish pipeline materializes nav snapshots into it, and
+ * `/api/v1/public/page` returns it verbatim.
+ *
+ * ⚠️ `@soloworks/smking-next` publishes raw `src/` to npm and cannot import
+ * this private workspace package — it ships a vendored copy at
+ * `packages/smking-next/src/cms-blocks.ts` instead. After editing this file
+ * run `pnpm sync:block-types` to regenerate it (drift fails the SDK's
+ * vitest guard).
+ *
+ * `article` is the serialize-time HTML container for runs of Plate built-in
+ * blocks — paragraphs / headings / lists are collapsed into one HTML body
+ * block via Plate's `serializeHtml`. New block primitives land here + in
+ * apps/web `block-schemas.ts`.
+ *
+ * `nav-taxonomy-list` uses a `source` discriminator — category mode is
+ * slug-prefix derived, tag mode targets `taxonomies.slug`.
+ */
+
+export interface HeroProps {
+  title: string;
+  /** Generic visible meta lines. Legacy drafts may still also carry subtitle. */
+  line1?: string;
+  line2?: string;
+  /** When true, render the backend page publish date. */
+  showPublishedAt?: boolean;
+  /** ISO or display date injected from page metadata at publish time. */
+  publishedAt?: string;
+  /** Legacy single-line fallback for SDK Mode B consumers. */
+  subtitle?: string;
+  image?: { url: string; alt: string };
+  cta?: { label: string; href: string };
+  /** Header layout — omitted = the original centred hero; "start" = the
+   * Apple-newsroom-style left-aligned header; "cover" = title-only banner over
+   * a full-bleed background image with a dark scrim (Apple services index);
+   * "cover-plain" = the same banner WITHOUT the scrim (image shown untouched).
+   * Visuals ship via bodyHtml; this mirrors the node attr for SDK Mode B
+   * (per-block) consumers. */
+  align?: "center" | "start" | "cover" | "cover-plain";
+  /** Crop ratio for cover heroes and the optional hero image.
+   * Omitted = auto, preserving the original image ratio. */
+  aspectRatio?: "auto" | "16:9" | "4:3";
+}
+
+export interface ArticleProps {
+  /** Plate `serializeHtml` output — a contiguous run of built-in blocks
+   * (paragraphs / headings / lists) collapsed into one HTML body block. */
+  html: string;
+}
+
+export interface ModuleHeader {
+  heading?: string;
+  viewAll?: { label: string; href: string };
+}
+
+export type NavLayout = "grid" | "list" | "carousel" | "archive";
+
+/**
+ * Materialized snapshot entry written into nav-* block props at publish
+ * time (see apps/web `materialize-blocks.ts` for the resolver). The
+ * customer SDK echoes `snapshot` verbatim — it never round-trips back to
+ * smking for nav rendering, so if smking is down customer pages still
+ * render whatever was last published.
+ */
+export interface NavSnapshotEntry {
+  slug: string;
+  /**
+   * Absolute href = the customer's CMS mount prefix + slug (baked at publish
+   * from `sites.config.cmsBasePath`). Optional — falls back to `/${slug}`.
+   */
+  href?: string;
+  title: string | null;
+  excerpt: string | null;
+  featuredImageUrl: string | null;
+  /** ISO string. */
+  publishedAt: string | null;
+  /** ISO string. Present when the article is manually pinned in CMS feeds. */
+  pinnedAt?: string | null;
+  contentType: "article" | "landing" | "listing" | "taxonomy" | null;
+}
+
+export type SearchQuickLinkSource = "category-by-path" | "tag" | "url";
+
+/**
+ * Optional links shown beside the search trigger on desktop and inside the
+ * search panel on small screens. Category/tag links keep their semantic source
+ * + path so publish-time materialization can bake the customer's CMS mount
+ * prefix into `href`; URL links carry the author's literal `href`.
+ */
+export interface SearchQuickLink {
+  label: string;
+  source: SearchQuickLinkSource;
+  /** Category slug path or flat tag slug. Not used for arbitrary URLs. */
+  path?: string;
+  /** Materialized href for category/tag links, or the author-entered URL. */
+  href?: string;
+}
+
+/**
+ * `search` block — a command-palette over the WHOLE site's published CMS
+ * pages. Unlike `nav-taxonomy-list` (which scopes to a category / tag),
+ * search bakes EVERY published `cms_page` into `snapshot` at publish time
+ * and the `<smking-search>` web component filters the rendered cards
+ * client-side. Reuses `NavSnapshotEntry` (the static render only reads
+ * `href` / `title` / `excerpt` — no thumbnail, command-palette text feel).
+ */
+export interface SearchProps {
+  /** Input placeholder. Defaults to "Search…" at render time. */
+  placeholder?: string;
+  /** Optional heading above the search input. */
+  heading?: string;
+  /** Content column vs wide breakout (default wide). Mirrors the media
+   * blocks (image/embed). */
+  widthMode?: "content" | "wide";
+  /** Optional quick links adjacent to search. */
+  links?: SearchQuickLink[];
+  /** Publish-time materialized snapshot — every published page on the site. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+export interface RecentPostsProps extends ModuleHeader {
+  /** Author-set number of latest posts to show (1..50). */
+  limit: number;
+  /** Content column vs wide breakout (default content). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
+  /** Publish-time materialized snapshot — whole-site newest-first. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+/** One author-picked source for nav-related-posts. Same shape as
+ * `CategoryIndexItem` (a category path OR a tag), reused so the source picker
+ * UI stays identical across blocks. */
+export interface RelatedPostsSource {
+  /** Slug prefix (category-by-path) or taxonomy slug (tag), per `source`. */
+  path: string;
+  /** Display name (only used by the editor chip; resolver ignores it). */
+  label: string;
+  /** Omitted = `category-by-path` (back-compat, mirrors CategoryIndexItem). */
+  source?: "category-by-path" | "tag";
+}
+
+export interface RelatedPostsProps extends ModuleHeader {
+  /** Authoring mode before materialization. Published blocks carry resolved
+   * `heading`; SDK consumers can ignore this field. */
+  headingMode?: "global" | "custom";
+  /** Author-set number of related posts to show (1..50). */
+  limit: number;
+  /** Content column vs wide breakout (default content). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
+  /** Author-picked sources. Empty/omitted → auto-fill from the CURRENT page's
+   * category, derived from its slug at publish time. When set, related posts
+   * are the latest across ALL picked sources (OR), newest-first, excluding the
+   * current page. */
+  sources?: RelatedPostsSource[];
+  /** Publish-time materialized snapshot. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+/** One tag attached to the current article, materialized at publish time. */
+export interface ArticleTagSnapshot {
+  slug: string;
+  name: string;
+  /** Virtual tag archive href, e.g. `/blog/tag/tofu-life`. */
+  href: string;
+}
+
+/**
+ * `article-tags` block — renders the current article's CMS tags as chips.
+ * The tags are page metadata, not authored inside the block, so `snapshot`
+ * is filled at publish time from `content_taxonomies`.
+ */
+export interface ArticleTagsProps {
+  /** Optional section heading. Omitted / empty means no heading. */
+  heading?: string;
+  /** Publish-time materialized current-article tags. */
+  snapshot?: ArticleTagSnapshot[];
+}
+
+/** One author-selected category OR tag in a nav-category-index block. */
+export interface CategoryIndexItem {
+  /** Slug prefix (category-by-path) or taxonomy slug (tag), per `source`.
+   * e.g. category `blog/seo`, tag `announcements`. */
+  path: string;
+  /** Display name on the card (slug leaf / tag name by default; author-editable). */
+  label: string;
+  /** Source discriminator (mirrors nav-taxonomy-list). Omitted =
+   * `category-by-path` — back-compat: pre-tag nodes carry no source. A `tag`
+   * card shows that tag's latest post + links to its archive. */
+  source?: "category-by-path" | "tag";
+}
+
+/**
+ * Materialized card for nav-category-index: the category's name, its archive
+ * link, and its latest post (null when the category has no published posts).
+ */
+export interface CategoryCardSnapshot {
+  label: string;
+  /** Archive href = mount prefix + category path (baked at publish). */
+  href: string;
+  latest: NavSnapshotEntry | null;
+}
+
+export interface CategoryIndexProps extends ModuleHeader {
+  /** `auto` = listing categories directly under `autoBasePath` at publish
+   * time; `manual` = exactly the picked items below. Omitted = back-compat:
+   * items present means manual, otherwise auto. */
+  mode?: "auto" | "manual";
+  /** Auto mode source. Omitted = category hierarchy, for back-compat. */
+  autoSource?: "category-by-path" | "tag";
+  /** Auto mode source hierarchy. Empty string means root-level listing
+   * categories; any other value is a listing slug whose direct child listing
+   * pages should be shown. Omitted falls back to root for new materialization. */
+  autoBasePath?: string;
+  items: CategoryIndexItem[];
+  /** Card layout — omitted/"cards" = category cards (archive links);
+   * "featured" = Apple-newsroom services-index tiles where each card IS the
+   * category's latest article. Visuals ship via bodyHtml; this mirrors the
+   * node attr for SDK Mode B (per-block) consumers. */
+  layout?: "cards" | "featured";
+  /** Content column vs wide breakout. Omitted = layout-derived default
+   * (cards → content, featured → wide); set explicitly to override. */
+  widthMode?: "content" | "wide";
+  snapshot?: CategoryCardSnapshot[];
+}
+
+export type MediaAspectRatio = "auto" | "16:9" | "4:3" | "square";
+
+/**
+ * `image` block — a single figure (image + optional caption). `widthMode`
+ * controls the breakout (content = text column, wide = up to 1024px centred
+ * on the container). All fields optional so an unconfigured block is valid;
+ * the static render emits nothing until an image is uploaded.
+ */
+export interface ImageProps {
+  url?: string;
+  alt?: string;
+  caption?: string;
+  widthMode?: "content" | "wide";
+  /** Plain image vs soft neutral tonal surface. */
+  styleVariant?: "plain" | "tonal";
+  /** Omitted / auto preserves the original image ratio. Fixed values crop. */
+  aspectRatio?: MediaAspectRatio;
+}
+
+/** One slide in a `slideshow` block. */
+export interface SlideshowSlideProps {
+  url: string;
+  alt?: string;
+  caption?: string;
+}
+
+/**
+ * `slideshow` block — an image carousel. `widthMode` controls the breakout
+ * (content / wide). `slides` optional so an unconfigured block is valid; the
+ * static render emits nothing (and the customer SDK upgrades it into a
+ * paginated carousel via the `<smking-slideshow>` web component).
+ */
+export interface SlideshowProps {
+  slides?: SlideshowSlideProps[];
+  widthMode?: "content" | "wide";
+  /** Fixed crop ratio for every slide (render default 16:9). */
+  aspectRatio?: "16:9" | "4:3";
+}
+
+/** One image in a `collage` block. Width/height are optional natural
+ * dimensions saved at authoring time so the auto layout can keep row
+ * proportions stable without loading images first. */
+export interface CollageImageProps {
+  url: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * `collage` block — a 1–6 image composition. `auto` uses natural image
+ * ratios and the wide breakout; `row-grid` keeps each row at one height while
+ * allowing different rows to have different proportions. Content width forces
+ * `row-grid` at render time.
+ */
+export interface CollageProps {
+  images?: CollageImageProps[];
+  widthMode?: "content" | "wide";
+  mode?: "auto" | "row-grid";
+}
+
+export type SocialSharePlatform =
+  | "threads"
+  | "instagram"
+  | "facebook"
+  | "line"
+  | "copy";
+
+/**
+ * `social-share` block — Threads / Instagram / Facebook / LINE share links +
+ * copy-link.
+ * Platform visibility is site-wide; `shareUrl` is the optional no-JS fallback
+ * target (the `<smking-share>` web component overrides every link from
+ * window.location at runtime, so the live share always points at the real
+ * current page).
+ */
+export interface SocialShareProps {
+  shareUrl?: string;
+  /** Global mode reads the site-wide share title. Custom mode reads `label`.
+   * Omitted = global; empty resolved title = bare icon row. */
+  headingMode?: "global" | "custom";
+  label?: string;
+  /** Site-wide platform visibility snapshot baked into published output. */
+  platforms?: SocialSharePlatform[];
+}
+
+export interface NavTaxonomyListProps extends ModuleHeader {
+  /**
+   * Discriminator:
+   *  - `category-by-path` → `path` is a slug prefix (e.g. `/blog/seo`); SDK
+   *    queries pages whose slug starts with this prefix.
+   *  - `tag` → `path` is the taxonomy slug (flat tag namespace).
+   */
+  source: "category-by-path" | "tag";
+  path: string;
+  limit: number;
+  /** List EVERY published article under the category/tag instead of the
+   * latest `limit` (Apple archive page). The resolver still applies a 200
+   * safety cap. Omitted (not false) when off — back-compat shape. */
+  showAll?: boolean;
+  layout: NavLayout;
+  /** Content column vs wide breakout (default content). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
+  /** Publish-time materialized snapshot. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+/** One button in a `button-group` block. */
+export interface ButtonItemProps {
+  label: string;
+  href: string;
+  /** Apple-style looks: `filled` = primary capsule, `tinted` = soft primary
+   * wash, `outline` = bordered. Omitted = filled. */
+  variant?: "filled" | "tinted" | "outline";
+}
+
+/**
+ * `button-group` block — a row of Apple-style capsule CTAs. Buttons wrap on
+ * narrow screens; `align` positions the row. Empty `buttons` is valid (an
+ * unconfigured block renders nothing on the customer side).
+ */
+export interface ButtonGroupProps {
+  buttons?: ButtonItemProps[];
+  align?: "start" | "center";
+}
+
+/**
+ * `embed` block — a privacy-friendly YouTube embed (youtube-nocookie
+ * iframe). `url` accepts any YouTube form (watch / youtu.be / shorts /
+ * embed); the video id is resolved at render time. No url / unrecognised
+ * url = renders nothing on the customer side. `widthMode` matches the other
+ * media blocks (content column vs wide breakout).
+ */
+export interface EmbedProps {
+  url?: string;
+  caption?: string;
+  widthMode?: "content" | "wide";
+}
+
+/**
+ * `media-text` block — Apple-style feature row: image on one side, RICH
+ * EDITABLE text on the other. Unlike the attr-panel blocks, the text is
+ * real Plate content (the node's children — headings/paragraphs edited
+ * inline); `html` carries its serialized form for Mode B consumers, while
+ * Mode A ships the full markup inside bodyHtml as usual.
+ */
+export interface MediaTextProps {
+  imageUrl?: string;
+  imageAlt?: string;
+  /** Which side the IMAGE sits on (md+ screens; stacks on mobile). */
+  side?: "left" | "right";
+  /** Content column vs wide breakout (default wide). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
+  /** Plain row vs soft neutral tonal surface. */
+  styleVariant?: "plain" | "tonal";
+  /** Omitted / auto preserves the original image ratio. Fixed values crop. */
+  aspectRatio?: MediaAspectRatio;
+  /** Serialized text-column HTML (class-stripped, same treatment as
+   * `article`). */
+  html: string;
+}
+
+/**
+ * One slot in a `latest-news` block — sourced independently from EITHER a
+ * specific article (by slug) or a category (shows that category's latest
+ * post). The discriminator mirrors `nav-taxonomy-list`'s source pattern.
+ */
+export type LatestNewsSlot =
+  | { kind: "article"; slug: string }
+  | {
+      kind: "category";
+      path: string;
+      label: string;
+      /** Source discriminator (mirrors nav-taxonomy-list). Omitted =
+       * `category-by-path` — back-compat. A `tag` slot shows the latest post
+       * carrying that tag. */
+      source?: "category-by-path" | "tag";
+    };
+
+/**
+ * One materialized `latest-news` card: the resolved article entry (the
+ * article itself for an `article` slot, or the category's latest post for a
+ * `category` slot) plus an optional eyebrow (the category label for category
+ * slots; null for article slots). A null `entry` = the slot's source
+ * resolved to nothing and is skipped at render.
+ */
+export interface LatestNewsCardSnapshot {
+  eyebrow: string | null;
+  entry: NavSnapshotEntry | null;
+}
+
+/**
+ * `latest-news` block — the Apple-newsroom "Latest News" magazine grid.
+ * 3–6 author-curated slots; the first is the large feature card, the rest
+ * scale down to medium / small tiles (6 = 1 feature + 2 medium + 3 small,
+ * down to 3 = 1 feature + 2 medium). Materialized at publish like the nav-*
+ * feeds; reuses `NavSnapshotEntry` for each resolved card.
+ */
+export interface LatestNewsProps extends ModuleHeader {
+  /** Author-curated slots, 3–6, in display order (first = feature card). */
+  slots: LatestNewsSlot[];
+  /** Content column vs wide breakout (default wide). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
+  /** Publish-time materialized snapshot — one card per slot, same order. */
+  snapshot?: LatestNewsCardSnapshot[];
+}
+
+export type Block =
+  | { component: "hero"; id: string; props: HeroProps }
+  | { component: "article"; id: string; props: ArticleProps }
+  | {
+      component: "nav-taxonomy-list";
+      id: string;
+      props: NavTaxonomyListProps;
+    }
+  | { component: "search"; id: string; props: SearchProps }
+  | { component: "nav-recent-posts"; id: string; props: RecentPostsProps }
+  | { component: "nav-related-posts"; id: string; props: RelatedPostsProps }
+  | { component: "article-tags"; id: string; props: ArticleTagsProps }
+  | { component: "nav-category-index"; id: string; props: CategoryIndexProps }
+  | { component: "image"; id: string; props: ImageProps }
+  | { component: "slideshow"; id: string; props: SlideshowProps }
+  | { component: "collage"; id: string; props: CollageProps }
+  | { component: "social-share"; id: string; props: SocialShareProps }
+  | { component: "button-group"; id: string; props: ButtonGroupProps }
+  | { component: "embed"; id: string; props: EmbedProps }
+  | { component: "media-text"; id: string; props: MediaTextProps }
+  | { component: "latest-news"; id: string; props: LatestNewsProps };
+
+export type BlockComponent = Block["component"];

package/src/index.ts

@@ -6,6 +6,12 @@ export { getCmsPage } from "./lib/cms-client";
 export type {
   AeoResponse,
   AeoStatus,
+  ArticleProps,
+  Block,
+  BlockComponent,
+  CategoryCardSnapshot,
+  CategoryIndexItem,
+  CategoryIndexProps,
   ChatLinks,
   CmsPage,
   CmsParams,
@@ -13,5 +19,20 @@ export type {
   CmsStatus,
   DiscoverParams,
   FaqItem,
+  HeroProps,
+  ImageProps,
+  ModuleHeader,
+  NavLayout,
+  NavSnapshotEntry,
+  NavTaxonomyListProps,
+  RecentPostsProps,
+  RelatedPostsProps,
+  SearchQuickLink,
+  SearchQuickLinkSource,
+  SearchProps,
   SeoMeta,
+  SlideshowProps,
+  SlideshowSlideProps,
+  SocialSharePlatform,
+  SocialShareProps,
 } from "./types";

package/src/lib/webhook-route.ts

@@ -7,6 +7,35 @@ interface WebhookPayload {
   paths?: string[];
   slugs?: string[];
   deliveredAt?: string;
+  deliveryId?: string;
+}
+
+// Replay protection (v0.21.1+). The deliveredAt window is the primary
+// defense — ±5min absorbs clock skew between SaaS and customer while
+// capping how long an intercepted delivery stays replayable. deliveryId
+// dedup is best-effort on top: serverless instances each hold their own
+// Map, so a replay landing on a different instance only has the window
+// to beat. SaaS payloads predating deliveryId pass dedup untouched.
+const REPLAY_WINDOW_MS = 5 * 60 * 1000;
+const SEEN_DELIVERIES_MAX = 1000;
+const seenDeliveries = new Map<string, number>(); // deliveryId → expiry (ms)
+
+function isDuplicateDelivery(
+  deliveryId: string | undefined,
+  now: number,
+): boolean {
+  for (const [id, expiry] of seenDeliveries) {
+    if (expiry <= now) seenDeliveries.delete(id);
+  }
+  if (typeof deliveryId !== "string" || deliveryId.length === 0) return false;
+  if (seenDeliveries.has(deliveryId)) return true;
+  if (seenDeliveries.size >= SEEN_DELIVERIES_MAX) {
+    // Map iterates in insertion order — evict the oldest entry.
+    const oldest = seenDeliveries.keys().next().value;
+    if (oldest !== undefined) seenDeliveries.delete(oldest);
+  }
+  seenDeliveries.set(deliveryId, now + REPLAY_WINDOW_MS);
+  return false;
 }
 
 /**
@@ -41,6 +70,13 @@ interface WebhookPayload {
  * Auth: HMAC-SHA256 only. Bearer dropped — single auth model means one
  * env var, one shim, fewer customer mis-config paths (the disambiguation
  * problem the v0.10 dual-handler shipped with).
+ *
+ * Replay protection (v0.21.1+): a signed delivery is only accepted while
+ * `deliveredAt` sits inside a ±5min window (401 `stale_delivery`
+ * otherwise — missing field counts as stale), and a `deliveryId` seen
+ * before within that window is rejected (401 `duplicate_delivery`).
+ * Payloads from a SaaS predating `deliveryId` skip dedup — the window
+ * remains the primary defense.
  */
 export async function POST(request: Request): Promise<Response> {
   const secret = process.env.SMKING_WEBHOOK_SECRET;
@@ -66,6 +102,23 @@ export async function POST(request: Request): Promise<Response> {
     return Response.json({ error: "invalid_payload" }, { status: 400 });
   }
 
+  // Replay protection — deliveredAt must sit inside a ±5min window
+  // (missing/unparseable counts as stale; SaaS has sent it since v0.11),
+  // then deliveryId dedup rejects re-sends of a delivery we already saw.
+  const now = Date.now();
+  const deliveredAtMs = payload.deliveredAt
+    ? Date.parse(payload.deliveredAt)
+    : Number.NaN;
+  if (
+    Number.isNaN(deliveredAtMs) ||
+    Math.abs(now - deliveredAtMs) > REPLAY_WINDOW_MS
+  ) {
+    return Response.json({ error: "stale_delivery" }, { status: 401 });
+  }
+  if (isDuplicateDelivery(payload.deliveryId, now)) {
+    return Response.json({ error: "duplicate_delivery" }, { status: 401 });
+  }
+
   const kind = payload.kind;
   if (typeof kind !== "string" || kind.length === 0) {
     // Forward-compat: SaaS may emit kinds we haven't taught the SDK

package/src/types.ts

@@ -56,7 +56,7 @@ export interface AeoResponse {
 
 export type CmsStatus = "ready" | "preview" | "pending" | "not_found";
 
-export type CmsContentType = "article" | "landing" | "listing";
+export type CmsContentType = "article" | "landing" | "listing" | "taxonomy";
 
 // `CmsThemeMode` removed in v0.15.0 — Mode B (`tailwind-prose`) dropped
 // in favour of the canonical Plate-serialized HTML render (Mode A only).
@@ -64,58 +64,37 @@ export type CmsContentType = "article" | "landing" | "listing";
 // `<article class="prose">` around `<SmkingCms>` themselves.
 
 /**
- * v2 substrate block primitives. Mirrors `apps/web/src/features/cms/types.ts`
- * on the SaaS side (kept in sync manually — when the v1 block catalog
- * grows past 5 primitives, a shared workspace package replaces this
- * duplication per `docs/superpowers/specs/2026-05-15-cms-dashboard-editor-design.md`
- * section §11 + ai-cms-v2 §"擴充性").
+ * v2 substrate block primitives. Single source of truth lives in the
+ * monorepo's `packages/shared/src/types/cms-blocks.ts`; this package ships
+ * a vendored copy (`./cms-blocks`, regenerated via `pnpm sync:block-types`)
+ * because raw `src/` is published to npm and can't depend on the private
+ * workspace package. A vitest guard fails when the copy drifts.
  */
-export interface HeroProps {
-  title: string;
-  subtitle?: string;
-  image?: { url: string; alt: string };
-  cta?: { label: string; href: string };
-}
-export interface ArticleProps {
-  html: string;
-}
-export interface ModuleHeader {
-  heading?: string;
-  viewAll?: { label: string; href: string };
-}
-export type NavLayout = "grid" | "list" | "carousel";
-
-/**
- * Materialized snapshot entry — published pages on the smking SaaS
- * pre-resolve their nav-* block data at publish time and bake it into
- * `block.props.snapshot`. Customer SDK echoes this verbatim, never
- * round-trips back to smking for nav rendering. If smking is down,
- * customer pages still render whatever was last published.
- */
-export interface NavSnapshotEntry {
-  slug: string;
-  title: string | null;
-  excerpt: string | null;
-  featuredImageUrl: string | null;
-  /** ISO string. */
-  publishedAt: string | null;
-  contentType: "article" | "landing" | "listing" | null;
-}
-
-export interface NavTaxonomyListProps extends ModuleHeader {
-  /** category-by-path: slug prefix; tag: taxonomies.slug */
-  source: "category-by-path" | "tag";
-  path: string;
-  limit: number;
-  layout: NavLayout;
-  /** Publish-time materialized — never fetched live. */
-  snapshot?: NavSnapshotEntry[];
-}
-
-export type Block =
-  | { component: "hero"; id: string; props: HeroProps }
-  | { component: "article"; id: string; props: ArticleProps }
-  | { component: "nav-taxonomy-list"; id: string; props: NavTaxonomyListProps };
+import type { Block } from "./cms-blocks";
+
+export type {
+  ArticleProps,
+  Block,
+  BlockComponent,
+  CategoryCardSnapshot,
+  CategoryIndexItem,
+  CategoryIndexProps,
+  HeroProps,
+  ImageProps,
+  ModuleHeader,
+  NavLayout,
+  NavSnapshotEntry,
+  NavTaxonomyListProps,
+  RecentPostsProps,
+  RelatedPostsProps,
+  SearchQuickLink,
+  SearchQuickLinkSource,
+  SearchProps,
+  SlideshowProps,
+  SlideshowSlideProps,
+  SocialSharePlatform,
+  SocialShareProps,
+} from "./cms-blocks";
 
 /**
  * A single published CMS page returned by the smking public API