@wix/agent-skills 1.17.0 → 1.18.0

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

@@ -0,0 +1,99 @@
+// 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.
+// 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";
+
+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>;
+
+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;
+}
+
+/**
+ * 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.
+ */
+export async function fetchPosts({ limit = 20, cursor, categoryId, tagId }: FetchPostsOptions = {}): Promise<PostPage> {
+  let q = posts.queryPosts().limit(limit);
+  if (cursor) {
+    // A cursor encodes the original filter+sort — re-sending them alongside it is rejected.
+    q = q.skipTo(cursor);
+  } else {
+    q = q.descending("firstPublishedDate");
+    if (categoryId) q = q.hasSome("categoryIds", [categoryId]);
+    if (tagId) q = q.hasSome("tagIds", [tagId]);
+  }
+  const res = await q.find();
+  return {
+    posts: (res.items ?? []).map((p: Raw) => toSummary(p)),
+    nextCursor: res.hasNext() ? (res.cursors?.next ?? null) : null,
+  };
+}
+
+/**
+ * Fetch one post by its URL slug with the full body (RICH_CONTENT + CONTENT_TEXT fieldsets —
+ * without them the body fields come back undefined). Null when not found.
+ */
+export async function fetchPostBySlug(slug: string): Promise<PostDetail | null> {
+  const res = await posts
+    .queryPosts({ fieldsets: ["RICH_CONTENT", "CONTENT_TEXT"] })
+    .eq("slug", slug)
+    .limit(1)
+    .find();
+  const raw = res.items?.[0];
+  return raw ? toDetail(raw as Raw) : null;
+}

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

@@ -0,0 +1,76 @@
+// 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.
+// 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 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);
+  } catch {
+    return [];
+  }
+}
+
+/** 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();
+    return (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) : 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;
+  }
+}

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

@@ -0,0 +1,62 @@
+// Blog DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or across server/client boundaries. Cover images are
+// resolved https URLs; dates are pre-formatted display strings plus an ISO value for <time>.
+
+/** A post as a feed/grid tile needs it. */
+export interface PostSummary {
+  id: string;
+  slug: string;
+  title: string;
+  /** Short summary (≤500 chars) — the card body. May be "". */
+  excerpt: string;
+  /** Display-ready publish date, e.g. "Aug 26, 2026" ("" when missing). */
+  dateLabel: string;
+  /** ISO publish date for <time datetime> ("" when missing). */
+  dateISO: string;
+  /** Estimated reading time in minutes (0 when unknown). */
+  minutesToRead: number;
+  featured: boolean;
+  /** Pinned posts lead the default feed order. */
+  pinned: boolean;
+  /** Resolved https cover URL ("" when the post has no cover). */
+  coverUrl: string;
+  categoryIds: string[];
+  tagIds: string[];
+}
+
+/** A post as the post page needs it. */
+export interface PostDetail extends PostSummary {
+  /**
+   * Ricos rich-content document (plain JSON) — the real post body. Render it ONLY through
+   * the shipped RichContent component (@wix/ricos viewer); it is not HTML and not text.
+   */
+  richContent: Record<string, unknown> | null;
+  /** Plain-text body split into paragraphs — the honest fallback when richContent is null. */
+  paragraphs: string[];
+}
+
+export interface BlogCategory {
+  id: string;
+  slug: string;
+  /** Display name (the API calls it `label`, never `name`). */
+  label: string;
+  description: string;
+  /** Number of posts in the category (hide empty categories with it). */
+  postCount: number;
+  /** Resolved https cover URL ("" when none). */
+  coverUrl: string;
+}
+
+export interface BlogTag {
+  id: string;
+  slug: string;
+  label: string;
+  /** Number of PUBLISHED posts with this tag. */
+  postCount: number;
+}
+
+/** One feed page; pass `nextCursor` back to fetch the next (null → no more). */
+export interface PostPage {
+  posts: PostSummary[];
+  nextCursor: string | null;
+}

package/skills/wix-headless-fast/references/blog/app-astro/layouts/SiteLayout.astro

@@ -0,0 +1,40 @@
+---
+// The site chrome for every blog page — THIS file (header/footer/nav) plus the @theme
+// token block in src/styles/global.css are what you brand. Keep the <slot name="seo-tags" />
+// in <head> and the global.css import. (If another vertical is also deployed, its SiteLayout
+// won; merge a Blog nav link there instead.)
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <a href="/blog" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Blog</a>
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+  </body>
+</html>

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

@@ -0,0 +1,99 @@
+---
+// Post page.
+//
+// This is a Wix ITEM PAGE: the wixMetadata export + <SEO.Tags> below let the site owner edit
+// this page's title/description/OG in the dashboard and register the route in the sitemap.
+// Keep all three SEO pieces, the [...slug] rest param, and this frontmatter; restyle the
+// 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 { fetchBlogCategories, fetchBlogTags } from "../../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag } from "../../wix/blog/types";
+import { WIX_APPS } from "@wix/essentials";
+import { SEO } from "@wix/seo/components";
+import { loadSEOTagsServiceConfig } from "@wix/seo/services";
+import { seoTags } from "@wix/seo";
+
+export const wixMetadata = {
+  appDefId: WIX_APPS.blogs.id,
+  pageIdentifier: WIX_APPS.blogs.postPageMetadata.pageIdentifier,
+  identifiers: {
+    slug: WIX_APPS.blogs.postPageMetadata.identifiers.slug,
+  },
+};
+
+const slug = Astro.params.slug;
+if (!slug) {
+  return new Response(null, { status: 404 });
+}
+
+// Behind Wix's proxy the request URL is internal — the real public page URL arrives on
+// x-wix-forwarded-url; the SEO service needs the public one.
+const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
+    ? forwardedUrl
+    : Astro.url.href;
+
+let post = null;
+let allCategories: BlogCategory[] = [];
+let allTags: BlogTag[] = [];
+let seoTagsServiceConfig = null;
+try {
+  [post, allCategories, allTags, seoTagsServiceConfig] = await Promise.all([
+    fetchPostBySlug(slug),
+    fetchBlogCategories(),
+    fetchBlogTags(),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.BLOG_POST,
+      itemData: { slug },
+    }).catch(() => null),
+  ]);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!post) {
+  return new Response(null, { status: 404 });
+}
+
+const postCategories = allCategories.filter((c) => post!.categoryIds.includes(c.id));
+const postTags = allTags.filter((t) => post!.tagIds.includes(t.id));
+---
+
+<SiteLayout title={post.title} description={post.excerpt}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+
+  <article class="mx-auto max-w-3xl">
+    {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` : ""}
+    </p>
+    {
+      post.coverUrl && (
+        <div class="mt-6 aspect-[16/9] overflow-hidden rounded-xl bg-secondary">
+          <img src={post.coverUrl} alt={post.title} class="h-full w-full object-cover" />
+        </div>
+      )
+    }
+    <div class="mt-8">
+      <RichContent client:only="react" content={post.richContent} fallbackParagraphs={post.paragraphs} />
+    </div>
+    {
+      postTags.length > 0 && (
+        <div class="mt-10 flex flex-wrap gap-2">
+          {postTags.map((t) => (
+            <span class="rounded-full border border-border px-3 py-1 text-xs font-medium text-muted-foreground">
+              {t.label}
+            </span>
+          ))}
+        </div>
+      )
+    }
+  </article>
+</SiteLayout>

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

@@ -0,0 +1,24 @@
+---
+// Blog index — data fetched SERVER-SIDE (SEO) and handed to the island as DTO props.
+// Keep this frontmatter; swap the island import to YOUR feed component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import BlogFeedView from "../components/blog/BlogFeedView";
+import { fetchPosts } from "../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags } from "../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostPage } from "../wix/blog/types";
+
+let page: PostPage = { posts: [], nextCursor: null };
+let categories: BlogCategory[] = [];
+let tags: BlogTag[] = [];
+try {
+  [page, categories, tags] = await Promise.all([fetchPosts(), fetchBlogCategories(), fetchBlogTags()]);
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // empty state instead.
+}
+---
+
+<SiteLayout title="Blog">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Blog</h1>
+  <BlogFeedView client:load initialPage={page} initialCategories={categories} initialTags={tags} />
+</SiteLayout>