@wix/agent-skills 1.20.0 → 1.21.0

package/skills/wix-headless-fast/references/blog/app/wix/blog/posts.ts

@@ -1,71 +1,24 @@
-// Post reads (Wix Blog V3) — the only file that touches raw post entities. Everything it
-// returns is a plain DTO from ./types. Copy as-is; extend by adding functions, not by editing
-// these. Blog posts are NOT CMS collections — always @wix/blog, never @wix/data.
+// 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 references/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
 import { posts as postsModule } from "@wix/blog";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
-import type { PostDetail, PostPage, PostSummary } from "./types";
+import { BLOG_APP_ID, DETAIL_FIELDSETS, postMetaLine, toDetail, toSummary, type FetchPostsOptions, type Raw } from "./posts-core";
+import type { PostDetail, PostPage } from "./types";
 
-const posts = wixModule(postsModule);
-
-/** The Wix Blog app id (Astro item-page routing; comments use it as appId). */
-export const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
-
-type Raw = Record<string, any>;
+export { BLOG_APP_ID, postMetaLine, type FetchPostsOptions };
 
-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(),
-  };
-}
-
-function toSummary(raw: Raw): PostSummary {
-  return {
-    id: raw._id ?? "",
-    slug: raw.slug ?? "",
-    title: raw.title ?? "",
-    excerpt: raw.excerpt ?? "",
-    ...dateParts(raw.firstPublishedDate),
-    minutesToRead: raw.minutesToRead ?? 0,
-    featured: raw.featured === true,
-    pinned: raw.pinned === true,
-    // The cover is a media STRING (wix:image:// or https) at media.wixMedia.image.
-    coverUrl: imgSrc(raw.media?.wixMedia?.image, 1200, 675),
-    categoryIds: raw.categoryIds ?? [],
-    tagIds: raw.tagIds ?? [],
-  };
-}
-
-function toDetail(raw: Raw): PostDetail {
-  return {
-    ...toSummary(raw),
-    richContent: raw.richContent ?? null,
-    // contentText is plain text — split on newlines for the fallback body.
-    paragraphs: String(raw.contentText ?? "")
-      .split("\n")
-      .map((s: string) => s.trim())
-      .filter(Boolean),
-  };
-}
-
-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;
-}
+const posts = wixModule(postsModule);
 
 /**
  * One page of published posts, newest first (pinned posts lead). 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 = posts.queryPosts().limit(limit);
@@ -79,7 +32,7 @@ export async function fetchPosts({ limit = 20, cursor, categoryId, tagId }: Fetc
   }
   const res = await q.find();
   return {
-    posts: (res.items ?? []).map((p: Raw) => toSummary(p)),
+    posts: (res.items ?? []).map((p: Raw) => toSummary(p, imgSrc)),
     nextCursor: res.hasNext() ? (res.cursors?.next ?? null) : null,
   };
 }
@@ -90,10 +43,10 @@ export async function fetchPosts({ limit = 20, cursor, categoryId, tagId }: Fetc
  */
 export async function fetchPostBySlug(slug: string): Promise<PostDetail | null> {
   const res = await posts
-    .queryPosts({ fieldsets: ["RICH_CONTENT", "CONTENT_TEXT"] })
+    .queryPosts({ fieldsets: [...DETAIL_FIELDSETS] as any })
     .eq("slug", slug)
     .limit(1)
     .find();
   const raw = res.items?.[0];
-  return raw ? toDetail(raw as Raw) : null;
+  return raw ? toDetail(raw as Raw, imgSrc) : null;
 }

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

@@ -0,0 +1,47 @@
+// Category + tag rules and DTO mapping — transport-agnostic, imported by both ./taxonomy.ts (SDK)
+// and the REST twin in references/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;
+
+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 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`
+    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-fast/references/blog/app/wix/blog/taxonomy.ts

@@ -1,42 +1,24 @@
-// Category + tag reads (Wix Blog V3) — the only file that touches raw taxonomy entities.
-// Everything it returns is a plain DTO from ./types. Copy as-is; extend by adding functions.
+// 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 references/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/tags/query-tags.md
 import { categories as categoriesModule, tags as tagsModule } from "@wix/blog";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
+import { TAXONOMY_LIMIT, toCategory, toTag } from "./taxonomy-core";
+import type { Raw } from "./posts-core";
 import type { BlogCategory, BlogTag } from "./types";
 
 const categories = wixModule(categoriesModule);
 const tags = wixModule(tagsModule);
 
-type Raw = Record<string, any>;
-
-function toCategory(raw: Raw): BlogCategory {
-  return {
-    id: raw._id ?? "",
-    slug: raw.slug ?? "",
-    label: raw.label ?? "",
-    description: raw.description ?? "",
-    postCount: raw.postCount ?? 0,
-    coverUrl: imgSrc(raw.coverImage, 1200, 675),
-  };
-}
-
-function toTag(raw: Raw): BlogTag {
-  return {
-    id: raw._id ?? "",
-    slug: raw.slug ?? "",
-    label: raw.label ?? "",
-    postCount: raw.publishedPostCount ?? 0,
-  };
-}
-
 /** Categories in menu order (displayPosition) — non-fatal (empty array on failure). */
 export async function fetchBlogCategories(): Promise<BlogCategory[]> {
   try {
-    const res = await categories.queryCategories().ascending("displayPosition").limit(100).find();
-    return (res.items ?? []).map((c: Raw) => toCategory(c)).filter((c) => c.id);
+    const res = await categories.queryCategories().ascending("displayPosition").limit(TAXONOMY_LIMIT).find();
+    return (res.items ?? []).map((c: Raw) => toCategory(c, imgSrc)).filter((c) => c.id);
   } catch {
     return [];
   }
@@ -45,7 +27,7 @@ export async function fetchBlogCategories(): Promise<BlogCategory[]> {
 /** Tags, most-published-posts first — non-fatal (empty array on failure). */
 export async function fetchBlogTags(): Promise<BlogTag[]> {
   try {
-    const res = await tags.queryTags().descending("publishedPostCount").limit(100).find();
+    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 [];
@@ -59,7 +41,7 @@ export async function fetchBlogTags(): Promise<BlogTag[]> {
 export async function fetchCategoryBySlug(slug: string): Promise<BlogCategory | null> {
   try {
     const res = await categories.getCategoryBySlug(slug);
-    return res.category ? toCategory(res.category as Raw) : null;
+    return res.category ? toCategory(res.category as Raw, imgSrc) : null;
   } catch {
     return null;
   }

package/skills/wix-headless-fast/references/blog/app-astro/pages/blog/[...slug].astro

@@ -7,7 +7,7 @@
 // template below freely. The body island is client:only — the ricos viewer breaks under SSR.
 import SiteLayout from "../../layouts/SiteLayout.astro";
 import RichContent from "../../components/blog/RichContent";
-import { fetchPostBySlug } from "../../wix/blog/posts";
+import { fetchPostBySlug, postMetaLine } from "../../wix/blog/posts";
 import { fetchBlogCategories, fetchBlogTags } from "../../wix/blog/taxonomy";
 import type { BlogCategory, BlogTag } from "../../wix/blog/types";
 import { WIX_APPS } from "@wix/essentials";
@@ -70,9 +70,7 @@ const postTags = allTags.filter((t) => post!.tagIds.includes(t.id));
     {postCategories.length > 0 && <p class="eyebrow">{postCategories.map((c) => c.label).join(" · ")}</p>}
     <h1 class="mt-2 text-3xl font-semibold tracking-tight">{post.title}</h1>
     <p class="mt-3 text-sm text-muted-foreground">
-      {post.dateLabel && <time datetime={post.dateISO}>{post.dateLabel}</time>}
-      {post.dateLabel && post.minutesToRead > 0 ? " · " : ""}
-      {post.minutesToRead > 0 ? `${post.minutesToRead} min read` : ""}
+      <time datetime={post.dateISO}>{postMetaLine(post)}</time>
     </p>
     {
       post.coverUrl && (

package/skills/wix-headless-fast/references/blog/rest/posts.ts

@@ -0,0 +1,42 @@
+// Post reads over REST — the twin of app/wix/blog/posts.ts. Same exports, same DTOs; the rules and
+// mappers come from posts-core (the SAME file the SDK transport uses, deployed flat next to this one
+// by deploy.mjs --stack static), so this file is only the transport: one fetch with a literal body
+// per function. Every call here is safe from a browser with a visitor token — only PUBLISHED posts
+// come back to it. Porting: keep the paths, keep the bodies, port the core once.
+// 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
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { BLOG_APP_ID, DETAIL_FIELDSETS, feedQuery, postMetaLine, slugQuery, toDetail, toSummary, type FetchPostsOptions, type Raw } from "./posts-core.js";
+import type { PostDetail, PostPage } from "./types.js";
+
+export { BLOG_APP_ID, postMetaLine, type FetchPostsOptions };
+
+const POSTS_QUERY = "/blog/v3/posts/query";
+
+/**
+ * One page of published posts, newest first (pinned posts lead); `nextCursor` continues the same
+ * query — send it alone, the filters ride inside it.
+ * POST /blog/v3/posts/query  { query: { filter?, sort, cursorPaging: { limit } } }   — first page
+ * POST /blog/v3/posts/query  { query: { cursorPaging: { limit, cursor } } }            — later pages
+ */
+export async function fetchPosts(o: FetchPostsOptions = {}): Promise<PostPage> {
+  const res = await wixRequest<Raw>(POSTS_QUERY, { body: { query: feedQuery(o) } });
+  const paging: Raw = res?.pagingMetadata ?? {};
+  return {
+    posts: ((res?.posts ?? []) as Raw[]).map((p) => toSummary(p, imgSrc)),
+    nextCursor: paging.hasNext ? (paging.cursors?.next ?? null) : null,
+  };
+}
+
+/**
+ * One post by URL slug with the full body (the RICH_CONTENT + CONTENT_TEXT fieldsets — without
+ * them richContent and contentText are absent). Null when the slug resolves to nothing — a real
+ * 404 for the page, never a fallback to another post.
+ * POST /blog/v3/posts/query  { fieldsets: ["RICH_CONTENT", "CONTENT_TEXT"], query: { filter: { slug: { $eq } }, cursorPaging: { limit: 1 } } }
+ */
+export async function fetchPostBySlug(slug: string): Promise<PostDetail | null> {
+  const res = await wixRequest<Raw>(POSTS_QUERY, { body: { fieldsets: DETAIL_FIELDSETS, query: slugQuery(slug) } });
+  const raw: Raw | undefined = res?.posts?.[0];
+  return raw ? toDetail(raw, imgSrc) : null;
+}

package/skills/wix-headless-fast/references/blog/rest/taxonomy.ts

@@ -0,0 +1,62 @@
+// Category + tag reads over REST — the twin of app/wix/blog/taxonomy.ts. Same exports, same DTOs;
+// the mappers come from taxonomy-core (the SAME file the SDK transport uses, deployed flat next to
+// this one). Taxonomy queries page by OFFSET (`paging`), unlike posts (`cursorPaging`); a blog's
+// taxonomy fits in one read of 100. All four calls are visitor-safe.
+// 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 { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { CATEGORY_SORT, TAG_SORT, TAXONOMY_LIMIT, toCategory, toTag } from "./taxonomy-core.js";
+import type { Raw } from "./posts-core.js";
+import type { BlogCategory, BlogTag } from "./types.js";
+
+/**
+ * Categories in menu order. Non-fatal: [] on failure (the feed renders without its filter row).
+ * POST /blog/v3/categories/query  { query: { sort: [{ fieldName: "displayPosition", order: "ASC" }], paging: { limit: 100 } } }
+ */
+export async function fetchBlogCategories(): Promise<BlogCategory[]> {
+  try {
+    const res = await wixRequest<Raw>("/blog/v3/categories/query", { body: { query: { sort: CATEGORY_SORT, paging: { limit: TAXONOMY_LIMIT } } } });
+    return ((res?.categories ?? []) as Raw[]).map((c) => toCategory(c, imgSrc)).filter((c) => c.id);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Tags, most-published-posts first. Non-fatal: [] on failure.
+ * POST /blog/v3/tags/query  { query: { sort: [{ fieldName: "publishedPostCount", order: "DESC" }], paging: { limit: 100 } } }
+ */
+export async function fetchBlogTags(): Promise<BlogTag[]> {
+  try {
+    const res = await wixRequest<Raw>("/blog/v3/tags/query", { body: { query: { sort: TAG_SORT, paging: { limit: TAXONOMY_LIMIT } } } });
+    return ((res?.tags ?? []) as Raw[]).map(toTag).filter((t) => t.id);
+  } catch {
+    return [];
+  }
+}
+
+// The two by-slug getters answer in DIFFERENT envelopes ({ category } and { tag }); a missing slug
+// is a 404 — mapped to null here, as the SDK transport does.
+
+/** One category by its URL slug. Null when not found.  GET /blog/v3/categories/slugs/{slug} */
+export async function fetchCategoryBySlug(slug: string): Promise<BlogCategory | null> {
+  try {
+    const res = await wixRequest<Raw>(`/blog/v3/categories/slugs/${encodeURIComponent(slug)}`, { method: "GET" });
+    return res?.category ? toCategory(res.category, imgSrc) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One tag by its URL slug. Null when not found.  GET /blog/v3/tags/slugs/{slug} */
+export async function fetchTagBySlug(slug: string): Promise<BlogTag | null> {
+  try {
+    const res = await wixRequest<Raw>(`/blog/v3/tags/slugs/${encodeURIComponent(slug)}`, { method: "GET" });
+    return res?.tag ? toTag(res.tag) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-fast/references/blog/seed/SEED.md

@@ -62,6 +62,15 @@ feed without covers looks broken.
 **Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
 seems needed.
 
+## Supplied content
+
+The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For a blog, each post the user
+hands over is one entry. Its title becomes `title`; its body becomes `content` blocks, one block per
+paragraph, heading or list, whether the body arrived as text, HTML or Markdown; a category becomes
+`category` (and joins the `categories` list); tags become `tags`; their cover image becomes
+`coverImageUrl`. A post with no body is a question for the user. Authors and publish dates are
+not seeded — say so.
+
 ## Escape hatch — individual functions
 `setupBlog` composes exported steps — `installBlogApp`, `getAuthorMemberId`, `createPosts`,
 `createCategories`, `createTags`, `importImage`, `attachPostCovers`, plus `makeCtx()` —

package/skills/wix-headless-fast/references/blog/seed/read-site.mjs

@@ -0,0 +1,22 @@
+// What the blog holds: posts, categories, tags.
+//   node <SKILL_ROOT>/references/blog/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/blog";
+
+await runReader({
+  vertical: "blog",
+  appId: BLOG_APP_ID,
+  async read(api, { limit }) {
+    const posts = await api.call({ path: "/v3/posts/query", body: { fieldsets: ["URL"], query: { paging: { limit } } }, docs: `${D}/posts-stats/query-posts` });
+    const cats = await api.tryCall({ path: "/blog/v3/categories/query", body: { query: { paging: { limit: 100 } } }, docs: `${D}/category/query-categories` });
+    const tags = await api.tryCall({ path: "/v3/tags/query", body: { query: { paging: { limit: 100 } } }, docs: `${D}/tags/query-tags` });
+    return {
+      postCount: posts.metaData?.total ?? posts.pagingMetadata?.total ?? (posts.posts ?? []).length,
+      posts: (posts.posts ?? []).map((p) => ({ title: p.title, slug: p.slug, published: p.firstPublishedDate ?? null, cover: !!p.coverMedia?.image, categories: (p.categoryIds ?? []).length, tags: (p.tagIds ?? []).length, minutesToRead: p.minutesToRead ?? null })),
+      categories: (cats?.categories ?? []).map((c) => ({ id: c.id, label: c.label, slug: c.slug, postCount: c.postCount ?? null })),
+      tags: (tags?.tags ?? []).map((t) => ({ id: t.id, label: t.label, postCount: t.postCount ?? null })),
+    };
+  },
+});