@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-headless-templates/blog/app/wix/blog/posts-core.ts

@@ -0,0 +1,347 @@
+// Post rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./posts.ts (the
+// SDK, managed Astro and React) and the REST twin in templates/blog/rest/posts.ts (fetch, a static
+// site or a port to another language). Every rule about dates, covers, the feed's sort and filters,
+// the body fieldsets, SEO overrides, related posts, likes, and URLs lives HERE, once. A raw post may
+// come from the SDK (`_id`, media as a `wix:image://` string, dates as Date) or from REST (`id`,
+// media as an { id, url } object, dates as ISO strings); the mappers accept both and produce the
+// same DTO. Imports are type-only so a strip to JS emits no imports.
+import type { BlogAuthor, PostDetail, PostMetrics, PostSummary } from "./types";
+
+/** A raw Blog V3 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** The Wix Blog app id (Astro item-page routing; comments use it as appId). */
+export const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
+
+/** Where the blog lives in the site's URL space; every path helper below builds on it. */
+export const BLOG_BASE = "/blog";
+
+/**
+ * The post page's fieldsets — without them richContent, contentText, seoData, and referenceId come
+ * back undefined. SEO carries the owner's title/description overrides. The comments thread id is
+ * `referenceId`: verified live, the REFERENCE_ID fieldset returns the post WITHOUT it (silently),
+ * while INTERNAL_ID returns both `internalId` and `referenceId` — so both are requested, and the
+ * mapper falls back to the post id (which is what referenceId equalled on every post read live, and
+ * what Wix's own Blog widget addresses the thread by). (Fieldset enum: URL, CONTENT_TEXT, METRICS,
+ * SEO, CONTACT_ID, RICH_CONTENT, REFERENCE_ID; INTERNAL_ID is accepted on the wire.)
+ */
+export const DETAIL_FIELDSETS = ["RICH_CONTENT", "CONTENT_TEXT", "SEO", "REFERENCE_ID", "INTERNAL_ID"] as const;
+
+/**
+ * The card fieldsets: METRICS puts view/like/comment counts on every post of a page in one read. The
+ * field is deprecated on the SDK's Post type ("data can be inconsistent") but live on the wire; the
+ * post page refreshes it with the dedicated metrics read (fetchPostMetrics / fetchLikeState).
+ */
+export const CARD_FIELDSETS = ["METRICS"] as const;
+
+/**
+ * The feed's order: pinned posts first, then newest first. Only listPosts' FEED default pins on its
+ * own; queryPosts with an explicit sort is pure date order, so the pinned key is spelled out here.
+ */
+export const FEED_SORT = [
+  { fieldName: "pinned", order: "DESC" },
+  { fieldName: "firstPublishedDate", order: "DESC" },
+] as const;
+
+/** Related posts: newest first among posts sharing a category (no pinned key — Wix's related strip has none). */
+export const RECENT_SORT = [{ fieldName: "firstPublishedDate", order: "DESC" }] as const;
+
+/** How many related posts a post page shows (Wix's default; curated lists are capped the same way). */
+export const RELATED_LIMIT = 3;
+
+/** The Like service scopes likes by entity FQDN; blog posts use the V3 post FQDN. */
+export const BLOG_POST_FQDN = "wix.blog.v3.post";
+
+/** Meta descriptions are cut here — the Blog API caps its own `excerpt` at the same length. */
+export const SEO_DESCRIPTION_MAX = 500;
+
+/** Cover size every card and post header gets — 16:9, one scaled URL per post. */
+export const COVER_WIDTH = 1200;
+export const COVER_HEIGHT = 675;
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+// ---- URLs ----------------------------------------------------------------------------------
+
+/** A slug may contain "/" — encode per segment so the path keeps its shape and a `[...slug]` route re-joins it. */
+export const encodeSlugPath = (slug: string): string => slug.split("/").map(encodeURIComponent).join("/");
+/** The post page: /blog/<slug>. Never build it from an id, never use `post.url` (the legacy blog page). */
+export const postPath = (slug: string): string => `${BLOG_BASE}/${encodeSlugPath(slug)}`;
+/** The category page: /blog/category/<slug>. */
+export const categoryPath = (slug: string): string => `${BLOG_BASE}/category/${encodeSlugPath(slug)}`;
+/** The tag page: /blog/tag/<slug>. */
+export const tagPath = (slug: string): string => `${BLOG_BASE}/tag/${encodeSlugPath(slug)}`;
+
+// ---- media ---------------------------------------------------------------------------------
+
+/**
+ * A media value in the form imgSrc scales. The SDK hands over the `wix:image://v1/<file>/<name>#…`
+ * string; REST hands over the Image object { id, url, width, height, filename }. Rebuilding the
+ * wix:image form from the object makes both transports scale to the SAME URL — passing the object's
+ * `url` through would skip scaling and the two paths would disagree on coverUrl.
+ */
+export function mediaValue(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  const o = value as Raw;
+  const id = o._id ?? o.id;
+  if (id && !String(id).startsWith("http")) {
+    const size = o.width && o.height ? `#originWidth=${o.width}&originHeight=${o.height}` : "";
+    return `wix:image://v1/${id}/${o.filename ?? ""}${size}`;
+  }
+  return o.url ?? o.image ?? "";
+}
+
+/**
+ * A video cover's poster as a wix:image value. The SDK's videoV2 is the string
+ * `wix:video://v1/<id>/<file>#posterUri=<file>&posterWidth=<w>&posterHeight=<h>`; REST's is the
+ * object { id, filename, posters: [{ id, url, width, height }] } (the SDK builds its string from
+ * the LAST poster). "" when the video carries no poster.
+ */
+export function videoPoster(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") {
+    const hash = value.split("#")[1] ?? "";
+    const params = new URLSearchParams(hash);
+    const uri = params.get("posterUri");
+    if (!uri) return "";
+    const w = params.get("posterWidth"), h = params.get("posterHeight");
+    return `wix:image://v1/${uri}/${uri}${w && h ? `#originWidth=${w}&originHeight=${h}` : ""}`;
+  }
+  const posters: Raw[] = (value as Raw).posters ?? [];
+  const poster = posters[posters.length - 1];
+  if (!poster) return "";
+  const id = poster.id || (poster.url ? String(poster.url).slice(String(poster.url).lastIndexOf("/") + 1) : "");
+  return id ? mediaValue({ id, filename: id, width: poster.width, height: poster.height }) : "";
+}
+
+/**
+ * The cover as a card renders it. `media.displayed === false` is the author hiding the cover —
+ * no cover at all. Otherwise the image wins, then a Wix video's poster, then an external embed's
+ * thumbnail (YouTube/Vimeo). Alt text is the author's, else the title.
+ */
+export function coverOf(raw: Raw, imgSrc: ImgSrc): { coverUrl: string; coverAlt: string } {
+  const media: Raw | undefined = raw.media;
+  if (!media || media.displayed === false) return { coverUrl: "", coverAlt: "" };
+  const coverUrl =
+    imgSrc(mediaValue(media.wixMedia?.image), COVER_WIDTH, COVER_HEIGHT) ||
+    imgSrc(videoPoster(media.wixMedia?.videoV2), COVER_WIDTH, COVER_HEIGHT) ||
+    (media.embedMedia?.thumbnail?.url ?? "");
+  return { coverUrl, coverAlt: coverUrl ? (media.altText ?? raw.title ?? "") : "" };
+}
+
+// ---- dates and numbers -----------------------------------------------------------------------
+
+/** Display date + ISO date from either a Date (SDK) or an ISO string (REST); both "" when missing or invalid. */
+export function dateParts(value: unknown): { dateLabel: string; dateISO: string } {
+  if (!value) return { dateLabel: "", dateISO: "" };
+  const d = value instanceof Date ? value : new Date(String(value));
+  if (Number.isNaN(d.getTime())) return { dateLabel: "", dateISO: "" };
+  return {
+    dateLabel: d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" }),
+    dateISO: d.toISOString(),
+  };
+}
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Wix's default date style: relative under a week ("3 days ago"), "Aug 5" in the current year,
+ * "Aug 5, 2024" otherwise. Pass the SAME `now` on the server and the client (e.g. a `fetchedAt`
+ * you put in the island's props) or the two renders disagree and hydration warns. "" when unknown.
+ */
+export function relativeDateLabel(dateISO: string, now: number = Date.now(), locale?: string): string {
+  if (!dateISO) return "";
+  const d = new Date(dateISO);
+  if (Number.isNaN(d.getTime())) return "";
+  const diff = now - d.getTime();
+  if (diff >= 0 && diff < 7 * DAY_MS) {
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+    if (diff < 60_000) return rtf.format(-Math.round(diff / 1000), "second");
+    if (diff < 3_600_000) return rtf.format(-Math.round(diff / 60_000), "minute");
+    if (diff < DAY_MS) return rtf.format(-Math.round(diff / 3_600_000), "hour");
+    return rtf.format(-Math.round(diff / DAY_MS), "day");
+  }
+  const sameYear = d.getFullYear() === new Date(now).getFullYear();
+  return new Intl.DateTimeFormat(locale, { ...(sameYear ? {} : { year: "numeric" }), month: "short", day: "numeric" }).format(d);
+}
+
+/** "1.2K" (compact, the default) or "1,234" (full) — counters. "" for an unknown count. */
+export function formatCount(n: number | undefined, style: "compact" | "full" = "compact", locale?: string): string {
+  if (typeof n !== "number" || !Number.isFinite(n)) return "";
+  return new Intl.NumberFormat(locale, style === "compact" ? { notation: "compact", maximumFractionDigits: 1 } : {}).format(n);
+}
+
+/** "Aug 27, 2026 · 4 min read" — the card's and header's meta line; either half alone, "" when neither is known. */
+export function postMetaLine(post: Pick<PostSummary, "dateLabel" | "minutesToRead">): string {
+  return [post.dateLabel, post.minutesToRead > 0 ? `${post.minutesToRead} min read` : ""].filter(Boolean).join(" · ");
+}
+
+// ---- SEO overrides (the dashboard's Advanced SEO panel, on posts and categories) --------------
+
+const liveSeoTags = (seoData: Raw | undefined | null): Raw[] => ((seoData?.tags ?? []) as Raw[]).filter((t) => !t.disabled);
+
+/** The owner's title override, "" when none. A title tag carries its value in `children`. */
+export function seoTitleFrom(seoData: Raw | undefined | null): string {
+  return liveSeoTags(seoData).find((t) => t.type === "title")?.children || "";
+}
+
+/** The owner's meta-description override, "" when none: a `meta` tag with props.name "description". */
+export function seoDescriptionFrom(seoData: Raw | undefined | null): string {
+  const c = liveSeoTags(seoData).find((t) => t.type === "meta" && t.props?.name === "description")?.props?.content;
+  return typeof c === "string" ? c : "";
+}
+
+// ---- mappers -------------------------------------------------------------------------------
+
+const count = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
+
+/** The counters from a metrics object (a post's `metrics` field or the metrics read's `metrics`). */
+export function toMetrics(raw: Raw | undefined | null): PostMetrics {
+  return { views: count(raw?.views), likes: count(raw?.likes), comments: count(raw?.comments) };
+}
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc): PostSummary {
+  const metrics = toMetrics(raw.metrics);
+  return {
+    id: rawId(raw),
+    slug: raw.slug ?? "",
+    title: raw.title ?? "",
+    excerpt: raw.excerpt ?? "",
+    ...dateParts(raw.firstPublishedDate),
+    minutesToRead: raw.minutesToRead ?? 0,
+    featured: raw.featured === true,
+    pinned: raw.pinned === true,
+    ...coverOf(raw, imgSrc),
+    categoryIds: raw.categoryIds ?? [],
+    tagIds: raw.tagIds ?? [],
+    authorId: raw.memberId ?? "",
+    authorName: "",
+    authorAvatarUrl: "",
+    viewCount: metrics.views,
+    likeCount: metrics.likes,
+    commentCount: metrics.comments,
+  };
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): PostDetail {
+  const summary = toSummary(raw, imgSrc);
+  const contentText = String(raw.contentText ?? "");
+  const updated = dateParts(raw.lastPublishedDate);
+  return {
+    ...summary,
+    richContent: raw.richContent ?? null,
+    // contentText is plain text — split on newlines for the fallback body.
+    paragraphs: contentText
+      .split("\n")
+      .map((s: string) => s.trim())
+      .filter(Boolean),
+    updatedLabel: updated.dateLabel,
+    updatedISO: updated.dateISO,
+    seoTitle: seoTitleFrom(raw.seoData) || summary.title,
+    seoDescription: (seoDescriptionFrom(raw.seoData) || summary.excerpt || contentText).slice(0, SEO_DESCRIPTION_MAX),
+    relatedPostIds: raw.relatedPostIds ?? [],
+    commentingEnabled: raw.commentingEnabled === true,
+    referenceId: raw.referenceId ?? raw.internalId ?? raw.id ?? "",
+  };
+}
+
+/** Join resolved authors onto posts; a post whose author did not resolve keeps "" (no byline). */
+export function withAuthors<T extends PostSummary>(posts: T[], authors: Record<string, BlogAuthor>): T[] {
+  return posts.map((p) => {
+    const a = authors[p.authorId];
+    return a ? { ...p, authorName: a.name, authorAvatarUrl: a.avatarUrl } : p;
+  });
+}
+
+// ---- queries -------------------------------------------------------------------------------
+
+export interface FetchPostsOptions {
+  limit?: number;
+  /** `nextCursor` from a previous page. */
+  cursor?: string | null;
+  /** Server-side filters (first page only — the cursor carries them on later pages). */
+  categoryId?: string | null;
+  tagId?: string | null;
+}
+
+/**
+ * The feed query as one object — the REST body's `query`, and the rule the SDK builder in ./posts.ts
+ * spells with .descending()/.hasSome()/.skipTo(). A cursor encodes the original filter+sort, so a
+ * cursor request carries ONLY cursorPaging; the first page carries the sort and the filters.
+ */
+export function feedQuery({ limit = 20, cursor, categoryId, tagId }: FetchPostsOptions = {}): Raw {
+  if (cursor) return { cursorPaging: { limit, cursor } };
+  const filter: Raw = {};
+  if (categoryId) filter.categoryIds = { $hasSome: [categoryId] };
+  if (tagId) filter.tagIds = { $hasSome: [tagId] };
+  return { ...(Object.keys(filter).length ? { filter } : {}), sort: FEED_SORT, cursorPaging: { limit } };
+}
+
+/** The by-slug query (REST body's `query`): exact slug, one row. A documented fallback — the by-slug getter is the primary read. */
+export function slugQuery(slug: string): Raw {
+  return { filter: { slug: { $eq: slug } }, cursorPaging: { limit: 1 } };
+}
+
+/** Posts by id (REST body's `query`; the SDK spells it .in("_id", ids)) — the curated related posts. */
+export function byIdsQuery(ids: string[], limit: number = ids.length): Raw {
+  return { filter: { id: { $in: ids } }, cursorPaging: { limit } };
+}
+
+/**
+ * The algorithmic related posts: newest first among posts sharing a category with the current one,
+ * the current one excluded. A post with no categories gets plain site-wide recents — a
+ * `$hasSome: []` matches nothing, so the category filter is added only when there is one.
+ */
+export function recentRelatedQuery(post: Pick<PostSummary, "id" | "categoryIds">, limit = RELATED_LIMIT): Raw {
+  const filter: Raw = { id: { $ne: post.id } };
+  if (post.categoryIds.length) filter.categoryIds = { $hasSome: post.categoryIds };
+  return { filter, sort: RECENT_SORT, cursorPaging: { limit } };
+}
+
+/**
+ * The curated list in the WRITER's order (the query answers in its own), the current post dropped,
+ * ids that no longer resolve to a visible post dropped, capped at `limit`. Strictly either/or with
+ * the algorithmic list: when at least one curated pick survives, exactly those are shown, never
+ * topped up.
+ */
+export function pickCurated<T extends { id: string }>(ids: string[], items: T[], currentId: string, limit = RELATED_LIMIT): T[] {
+  const byId = new Map(items.map((p) => [p.id, p]));
+  return ids
+    .filter((id) => id !== currentId)
+    .map((id) => byId.get(id))
+    .filter((p): p is T => p !== undefined)
+    .slice(0, limit);
+}
+
+/**
+ * "Did THIS viewer like the post?" — the Like service scopes queryLikes to the calling identity
+ * (member or anonymous visitor), so one row means yes. REST body's `query`; the SDK spells it
+ * .eq("fqdn").eq("entityId").limit(1). Personal → client-only, never during SSR.
+ */
+export function likeStateQuery(postId: string): Raw {
+  return { filter: { fqdn: { $eq: BLOG_POST_FQDN }, entityId: { $eq: postId } }, cursorPaging: { limit: 1 } };
+}
+
+/** The like write's body — the same object for createLike and for the REST POST. */
+export function likeBody(postId: string): Raw {
+  return { like: { entityId: postId, fqdn: BLOG_POST_FQDN } };
+}
+
+/**
+ * An expected miss, not a failure: a 404, or an application error whose code names NOT_FOUND.
+ * Guarded with String() — the SDK's transformed error carries a NUMERIC code for HTTP failures.
+ */
+export function isNotFound(e: unknown): boolean {
+  const err = (e ?? {}) as { status?: unknown; code?: unknown; details?: { applicationError?: { code?: unknown } } };
+  return err.status === 404 || String(err.details?.applicationError?.code ?? err.code ?? "").includes("NOT_FOUND");
+}
+
+/** A write the caller's identity may not perform — an anonymous visitor commenting where members only may. */
+export function isPermissionDenied(e: unknown): boolean {
+  const err = (e ?? {}) as { status?: unknown; code?: unknown; details?: { applicationError?: { code?: unknown } } };
+  const code = String(err.details?.applicationError?.code ?? err.code ?? "");
+  return err.status === 401 || err.status === 403 || /PERMISSION_DENIED|UNAUTHENTICATED|FORBIDDEN/.test(code);
+}

package/skills/wix-headless-templates/blog/app/wix/blog/posts.ts

@@ -0,0 +1,132 @@
+// Post reads (Wix Blog V3) over the SDK — the only file that touches raw post entities on this
+// transport. Everything it returns is a plain DTO from ./types. The rules and mappers live in
+// ./posts-core (shared with the REST twin in templates/blog/rest/); this file is the transport
+// only. Copy as-is; extend by adding functions, not by editing these. Blog posts are NOT CMS
+// collections — always @wix/blog, never @wix/data.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/get-post-by-slug.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/get-post-metrics.md
+import { posts as postsModule } from "@wix/blog";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import { fetchAuthorsByIds } from "./authors";
+import {
+  BLOG_APP_ID,
+  CARD_FIELDSETS,
+  DETAIL_FIELDSETS,
+  RELATED_LIMIT,
+  categoryPath,
+  formatCount,
+  isNotFound,
+  pickCurated,
+  postMetaLine,
+  postPath,
+  relativeDateLabel,
+  tagPath,
+  toDetail,
+  toMetrics,
+  toSummary,
+  withAuthors,
+  type FetchPostsOptions,
+  type Raw,
+} from "./posts-core";
+import type { PostDetail, PostMetrics, PostPage, PostSummary } from "./types";
+
+export { BLOG_APP_ID, categoryPath, formatCount, postMetaLine, postPath, relativeDateLabel, tagPath, type FetchPostsOptions };
+
+const posts = wixModule(postsModule);
+
+// Cards carry METRICS (view/like/comment counts); the fieldsets option rides outside the query.
+const cardQuery = () => posts.queryPosts({ fieldsets: [...CARD_FIELDSETS] as any });
+
+// The authors of one page in one batched read, joined onto the DTOs; a failed read leaves "" (no byline).
+async function withPageAuthors<T extends PostSummary>(items: T[]): Promise<T[]> {
+  return withAuthors(items, await fetchAuthorsByIds(items.map((p) => p.authorId)));
+}
+
+/**
+ * One page of published posts: pinned first, then newest first. Only published posts come back
+ * to a visitor token — a "missing" post usually wasn't published, not a query bug. The builder
+ * below spells posts-core's feedQuery: sort + filters on the first page, the cursor alone after.
+ */
+export async function fetchPosts({ limit = 20, cursor, categoryId, tagId }: FetchPostsOptions = {}): Promise<PostPage> {
+  let q = cardQuery().limit(limit);
+  if (cursor) {
+    // A cursor encodes the original filter+sort — re-sending them alongside it is rejected.
+    q = q.skipTo(cursor);
+  } else {
+    // queryPosts with an explicit sort does not pin on its own — the pinned key comes first.
+    q = q.descending("pinned").descending("firstPublishedDate");
+    if (categoryId) q = q.hasSome("categoryIds", [categoryId]);
+    if (tagId) q = q.hasSome("tagIds", [tagId]);
+  }
+  const res = await q.find();
+  return {
+    posts: await withPageAuthors((res.items ?? []).map((p: Raw) => toSummary(p, imgSrc))),
+    nextCursor: res.hasNext() ? (res.cursors?.next ?? null) : null,
+  };
+}
+
+/**
+ * One post by its URL slug with the full body and SEO/comments fields (RICH_CONTENT, CONTENT_TEXT,
+ * SEO, REFERENCE_ID, INTERNAL_ID — without them those fields come back undefined; INTERNAL_ID is the
+ * one that actually carries referenceId). Null when the slug resolves
+ * to nothing (404 / NOT_FOUND is an expected miss); any other failure throws. The dedicated
+ * by-slug read, not a slug query: slugs are per translation, so a slug-only query is ambiguous on
+ * a multilingual site.
+ */
+export async function fetchPostBySlug(slug: string): Promise<PostDetail | null> {
+  let raw: Raw | undefined;
+  try {
+    raw = (await posts.getPostBySlug(slug, { fieldsets: [...DETAIL_FIELDSETS] as any })).post as Raw | undefined;
+  } catch (e) {
+    if (isNotFound(e)) return null;
+    throw e;
+  }
+  if (!raw) return null;
+  const [detail] = await withPageAuthors([toDetail(raw, imgSrc)]);
+  return detail;
+}
+
+/** Posts by id, as cards (order is the API's — callers restore their own). Non-fatal: [] on failure. */
+export async function fetchPostsByIds(ids: string[]): Promise<PostSummary[]> {
+  if (!ids.length) return [];
+  try {
+    const res = await cardQuery().in("_id", ids).limit(ids.length).find();
+    return withPageAuthors((res.items ?? []).map((p: Raw) => toSummary(p, imgSrc)));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The post page's related strip: the writer's curated `relatedPostIds` (their order, the current
+ * post dropped) when at least one still resolves; else the newest posts sharing a category with this
+ * one (site-wide recents when it has none). Strictly either/or — never topped up. Non-fatal: [].
+ */
+export async function fetchRelatedPosts(post: Pick<PostDetail, "id" | "categoryIds" | "relatedPostIds">, limit = RELATED_LIMIT): Promise<PostSummary[]> {
+  try {
+    if (post.relatedPostIds.length) {
+      const curated = pickCurated(post.relatedPostIds, await fetchPostsByIds(post.relatedPostIds), post.id, limit);
+      if (curated.length) return curated;
+    }
+    let q = cardQuery().ne("_id", post.id).descending("firstPublishedDate").limit(limit);
+    if (post.categoryIds.length) q = q.hasSome("categoryIds", post.categoryIds);
+    const res = await q.find();
+    return withPageAuthors((res.items ?? []).map((p: Raw) => toSummary(p, imgSrc)));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The post's fresh counters — the API's designated source (the `metrics` field on a post is
+ * deprecated as potentially inconsistent). Null on failure: keep the count you had.
+ */
+export async function fetchPostMetrics(postId: string): Promise<PostMetrics | null> {
+  try {
+    return toMetrics((await posts.getPostMetrics(postId)).metrics as Raw | undefined);
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-templates/blog/app/wix/blog/taxonomy-core.ts

@@ -0,0 +1,80 @@
+// Category + tag rules and DTO mapping — transport-agnostic, imported by both ./taxonomy.ts (SDK)
+// and the REST twin in templates/blog/rest/taxonomy.ts (fetch). Raw entities may carry `_id`
+// (SDK) or `id` (REST). Has its own rawId/mediaValue (copies of posts-core's) so it stands alone
+// when stripped; imports are type-only.
+import type { BlogCategory, BlogTag } from "./types";
+import type { ImgSrc, Raw } from "./posts-core";
+
+/** Menu order — displayPosition ascending; -1 (unplaced) sorts first, which is also what the SDK path shows. */
+export const CATEGORY_SORT = [{ fieldName: "displayPosition", order: "ASC" }] as const;
+/** Most-published-posts first. */
+export const TAG_SORT = [{ fieldName: "publishedPostCount", order: "DESC" }] as const;
+/** Blog taxonomies are small — one read of up to 100 is the whole list. */
+export const TAXONOMY_LIMIT = 100;
+/** A post carries at most 30 tag ids (the API's own cap), so one by-id read answers a post in full. */
+export const TAG_BY_IDS_LIMIT = 30;
+/** Server-side "only categories that have posts" — the filter row's rule, applied at the source. */
+export const WITH_POSTS_FILTER = { postCount: { $gt: 0 } } as const;
+
+const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+// A copy of posts-core's mediaValue: the REST Image object → the wix:image form imgSrc scales.
+function mediaValue(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  const o = value as Raw;
+  if (o.id && !String(o.id).startsWith("http")) {
+    const size = o.width && o.height ? `#originWidth=${o.width}&originHeight=${o.height}` : "";
+    return `wix:image://v1/${o.id}/${o.filename ?? ""}${size}`;
+  }
+  return o.url ?? o.image ?? "";
+}
+
+export interface FetchCategoriesOptions {
+  /** Only categories with at least one post (the filter row's rule) — applied by Wix. */
+  withPosts?: boolean;
+}
+
+/** The categories query (REST body's `query`); the SDK spells it .ascending("displayPosition").gt("postCount", 0).limit(100). */
+export function categoriesQuery({ withPosts = false }: FetchCategoriesOptions = {}): Raw {
+  return { ...(withPosts ? { filter: WITH_POSTS_FILTER } : {}), sort: CATEGORY_SORT, paging: { limit: TAXONOMY_LIMIT } };
+}
+
+/**
+ * Tags BY ID (REST body's `query`; the SDK spells it .in("_id", ids).limit(30)) — a post's chips are
+ * read this way, not joined off a top-100 catalog: a blog's tags run to hundreds, and a tag past the
+ * first page would silently lose its chip. Categories run to tens, so their catalog is joined in memory.
+ */
+export function tagsByIdsQuery(ids: string[]): Raw {
+  return { filter: { id: { $in: ids } }, paging: { limit: TAG_BY_IDS_LIMIT } };
+}
+
+/**
+ * Items in the order the POST lists them (its `categoryIds`/`tagIds`), ids that resolved to nothing
+ * dropped — the catalog's displayPosition and the query's own order are not the post's order.
+ */
+export function inIdOrder<T extends { id: string }>(ids: readonly string[], items: readonly T[]): T[] {
+  const byId = new Map(items.map((x) => [x.id, x]));
+  return ids.map((id) => byId.get(id)).filter((x): x is T => x !== undefined);
+}
+
+export function toCategory(raw: Raw, imgSrc: ImgSrc): BlogCategory {
+  return {
+    id: rawId(raw),
+    slug: raw.slug ?? "",
+    label: raw.label ?? "", // the API's display name is `label`, never `name`
+    title: raw.title ?? "", // the category's SEO title (the dashboard's "title tag"); "" until the owner sets one
+    description: raw.description ?? "",
+    postCount: raw.postCount ?? 0,
+    coverUrl: imgSrc(mediaValue(raw.coverImage), 1200, 675),
+  };
+}
+
+export function toTag(raw: Raw): BlogTag {
+  return {
+    id: rawId(raw),
+    slug: raw.slug ?? "",
+    label: raw.label ?? "",
+    postCount: raw.publishedPostCount ?? 0, // PUBLISHED posts — postCount also counts drafts
+  };
+}

package/skills/wix-headless-templates/blog/app/wix/blog/taxonomy.ts

@@ -0,0 +1,78 @@
+// Category + tag reads (Wix Blog V3) over the SDK — the only file that touches raw taxonomy
+// entities on this transport. Everything it returns is a plain DTO from ./types. The mappers live
+// in ./taxonomy-core (shared with the REST twin in templates/blog/rest/); this file is the
+// transport only. Copy as-is; extend by adding functions.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/get-category-by-slug.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/query-tags.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/get-tag-by-slug.md
+import { categories as categoriesModule, tags as tagsModule } from "@wix/blog";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import { TAG_BY_IDS_LIMIT, TAXONOMY_LIMIT, inIdOrder, toCategory, toTag, type FetchCategoriesOptions } from "./taxonomy-core";
+import type { Raw } from "./posts-core";
+import type { BlogCategory, BlogTag } from "./types";
+
+export { inIdOrder, type FetchCategoriesOptions };
+
+const categories = wixModule(categoriesModule);
+const tags = wixModule(tagsModule);
+
+/** Categories in menu order (displayPosition); `withPosts` drops empty ones at the source — non-fatal (empty array on failure). */
+export async function fetchBlogCategories({ withPosts = false }: FetchCategoriesOptions = {}): Promise<BlogCategory[]> {
+  try {
+    let q = categories.queryCategories().ascending("displayPosition").limit(TAXONOMY_LIMIT);
+    if (withPosts) q = q.gt("postCount", 0);
+    const res = await q.find();
+    return (res.items ?? []).map((c: Raw) => toCategory(c, imgSrc)).filter((c) => c.id);
+  } catch {
+    return [];
+  }
+}
+
+/** Tags, most-published-posts first — a tag cloud; non-fatal (empty array on failure). */
+export async function fetchBlogTags(): Promise<BlogTag[]> {
+  try {
+    const res = await tags.queryTags().descending("publishedPostCount").limit(TAXONOMY_LIMIT).find();
+    return (res.items ?? []).map((t: Raw) => toTag(t)).filter((t) => t.id);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * A post's tags by id, in the post's own order (a blog's tags run to hundreds — a catalog page would
+ * silently drop chips). Non-fatal: [] on failure.
+ */
+export async function fetchTagsByIds(ids: readonly string[]): Promise<BlogTag[]> {
+  if (!ids.length) return [];
+  try {
+    const res = await tags.queryTags().in("_id", [...ids]).limit(TAG_BY_IDS_LIMIT).find();
+    return inIdOrder(ids, (res.items ?? []).map((t: Raw) => toTag(t)).filter((t) => t.id));
+  } catch {
+    return [];
+  }
+}
+
+// The two by-slug getters return DIFFERENT envelopes upstream ({ category } vs { tag } here;
+// getTag(id) even returns the tag bare) — the mapping below absorbs that asymmetry once.
+
+/** One category by its URL slug. Null when not found. */
+export async function fetchCategoryBySlug(slug: string): Promise<BlogCategory | null> {
+  try {
+    const res = await categories.getCategoryBySlug(slug);
+    return res.category ? toCategory(res.category as Raw, imgSrc) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One tag by its URL slug. Null when not found. */
+export async function fetchTagBySlug(slug: string): Promise<BlogTag | null> {
+  try {
+    const res = await tags.getTagBySlug(slug);
+    return res.tag ? toTag(res.tag as Raw) : null;
+  } catch {
+    return null;
+  }
+}