@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/blog/app/wix/blog/blog-feed-store.ts

@@ -0,0 +1,156 @@
+// The blog feed as a framework-free store — the logic behind useBlogFeed, usable from React
+// (useBlogFeed wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. State, actions, subscribe/getState, emit after every
+// change — the same shape as storefront's shop-store.
+//
+// Category and tag filters are applied by Wix (fetchPosts), never to a page already in hand; the
+// two are mutually exclusive — setting one clears the other. A changed filter starts a fresh cursor
+// chain; a late response from a superseded query is dropped. Paging appends by cursor. Author
+// bylines and counters ride on the posts themselves (fetchPosts joins them per page).
+//
+// SSR-friendly: seed with `initialPage` (and `initialCategories`/`initialTags`) and the first page
+// renders at once with no client fetch. A category or tag page seeds a FILTERED first page: pass the
+// filter it was fetched with as `initialCategoryId`/`initialTagId`, and the seed is trusted for
+// exactly that filter. A SPA passes nothing and `start()` fetches. One store per mounted feed (a
+// page can hold a feed and a "latest posts" rail): createBlogFeedStore().
+//
+// Error vs empty: a failed read leaves `posts: []` AND sets `error`. Render the empty state only
+// when `error` is null — "No posts yet" over a network failure is a lie.
+import { fetchPosts } from "./posts";
+import { fetchBlogCategories, fetchBlogTags } from "./taxonomy";
+import type { BlogCategory, BlogTag, PostPage, PostSummary } from "./types";
+
+export interface BlogFeedStoreOptions {
+  initialPage?: PostPage;
+  /** The filter `initialPage` was fetched with (a category page); omit for the unfiltered feed. */
+  initialCategoryId?: string | null;
+  initialTagId?: string | null;
+  initialCategories?: BlogCategory[];
+  initialTags?: BlogTag[];
+  pageSize?: number;
+}
+
+/** Everything a feed surface renders from. Read it with getState() or through a subscription. */
+export interface BlogFeedState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  posts: PostSummary[] | null;
+  categories: BlogCategory[];
+  tags: BlogTag[];
+  activeCategoryId: string | null;
+  activeTagId: string | null;
+  /** True when another page exists — render a "load more" control on it. */
+  hasMore: boolean;
+  loadingMore: boolean;
+  /** A failed read. While set, `posts` may be [] — that is not an empty blog. */
+  error: string | null;
+}
+
+export interface BlogFeedStore {
+  getState(): BlogFeedState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the taxonomy (unless seeded) and the first page (unless seeded for the active filter). Call once when mounted. */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  /** Server-side filter; clears the tag filter. */
+  setActiveCategoryId(id: string | null): void;
+  /** Server-side filter; clears the category filter. */
+  setActiveTagId(id: string | null): void;
+  loadMore(): Promise<void>;
+}
+
+export function createBlogFeedStore({
+  initialPage,
+  initialCategoryId = null,
+  initialTagId = null,
+  initialCategories,
+  initialTags,
+  pageSize = 20,
+}: BlogFeedStoreOptions = {}): BlogFeedStore {
+  let posts: PostSummary[] | null = initialPage?.posts ?? null;
+  let cursor: string | null = initialPage?.nextCursor ?? null;
+  let categories: BlogCategory[] = initialCategories ?? [];
+  let tags: BlogTag[] = initialTags ?? [];
+  let activeCategoryId: string | null = initialCategoryId;
+  let activeTagId: string | null = initialTagId;
+  let loadingMore = false;
+  let error: string | null = null;
+  let started = false;
+  let generation = 0; // bumped by every filter change and stop(); a response from an older generation is dropped
+  const listeners = new Set<() => void>();
+  let snapshot: BlogFeedState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function getState(): BlogFeedState {
+    if (snapshot) return snapshot;
+    snapshot = { posts, categories, tags, activeCategoryId, activeTagId, hasMore: cursor !== null, loadingMore, error };
+    return snapshot;
+  }
+
+  // The seeded page answers exactly the filter it was fetched with — nothing else.
+  const seedMatches = () => Boolean(initialPage) && activeCategoryId === initialCategoryId && activeTagId === initialTagId;
+
+  // The first page for the current filter: the seed when it matches, a fetch otherwise.
+  function query(): void {
+    if (!started) return;
+    const id = ++generation;
+    loadingMore = false;
+    if (seedMatches()) {
+      posts = initialPage!.posts; cursor = initialPage!.nextCursor; error = null;
+      emit();
+      return;
+    }
+    posts = null; cursor = null; error = null;
+    emit();
+    fetchPosts({ limit: pageSize, categoryId: activeCategoryId, tagId: activeTagId })
+      .then((page) => {
+        if (generation !== id) return; // superseded — drop it
+        posts = page.posts; cursor = page.nextCursor;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id) return;
+        posts = []; cursor = null;
+        error = e instanceof Error ? e.message : String(e);
+        emit();
+      });
+  }
+
+  return {
+    getState,
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (!initialCategories) fetchBlogCategories().then((c) => { if (started) { categories = c; emit(); } });
+      if (!initialTags) fetchBlogTags().then((t) => { if (started) { tags = t; emit(); } });
+      query();
+    },
+    stop() { started = false; generation++; },
+    setActiveCategoryId(id) {
+      if (id === activeCategoryId && activeTagId === null) return;
+      activeCategoryId = id; activeTagId = null;
+      query();
+    },
+    setActiveTagId(id) {
+      if (id === activeTagId && activeCategoryId === null) return;
+      activeTagId = id; activeCategoryId = null;
+      query();
+    },
+    async loadMore() {
+      if (!cursor || loadingMore) return;
+      const id = generation;
+      loadingMore = true; error = null; emit();
+      try {
+        const page = await fetchPosts({ limit: pageSize, cursor });
+        if (generation !== id) return;
+        posts = [...(posts ?? []), ...page.posts]; cursor = page.nextCursor;
+      } catch (e) {
+        if (generation !== id) return;
+        error = e instanceof Error ? e.message : String(e);
+      } finally {
+        if (generation === id) { loadingMore = false; emit(); }
+      }
+    },
+  };
+}

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

@@ -0,0 +1,189 @@
+// Comment rules and DTO mapping — transport-agnostic, imported by both ./comments.ts and the REST
+// twin in templates/blog/rest/comments.ts. Wix Comments is one service for every app; a blog post's
+// thread is addressed by the Blog app id plus the post's REFERENCE ID as both contextId and
+// resourceId (the public-SDK shape Wix's own headless blog uses; the classic Blog widget uses the
+// post id through an internal client instead — verify on a live site that the dashboard's threads
+// come back). Threads are two levels deep: a reply is stored under its TOP-level comment, and its
+// `parentComment` may itself be a reply ("replying to"). Imports are type-only.
+import type { BlogAuthor, BlogComment, CommentPage, CommentStatus, CommentThread } from "./types";
+import type { Raw } from "./posts-core";
+
+// A copy of posts-core's BLOG_APP_ID and dateParts, so this file stands alone when stripped.
+const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
+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() };
+}
+
+/** Top-level comments per page (Wix's default) and replies per "show more replies". */
+export const COMMENTS_PAGE_SIZE = 10;
+export const REPLIES_PAGE_SIZE = 10;
+
+/** The two orders a blog thread offers; replies are always oldest first. */
+export type CommentSort = "NEWEST_FIRST" | "OLDEST_FIRST";
+export const DEFAULT_COMMENT_SORT: CommentSort = "NEWEST_FIRST";
+
+export interface ListCommentsOptions {
+  /** `PostDetail.referenceId` — the thread. */
+  referenceId: string;
+  cursor?: string | null;
+  limit?: number;
+  sort?: CommentSort;
+}
+
+/**
+ * The list-by-resource request as flat query-string params (the endpoint is a GET; nested fields
+ * travel as dotted keys, the SDK flattens them the same way). `repliesLimit: 0` asks for the reply
+ * SEAMS only — each top-level comment's reply cursor comes back without its replies, which load on
+ * demand with `listRepliesParams`.
+ */
+export function listCommentsParams({ referenceId, cursor, limit = COMMENTS_PAGE_SIZE, sort = DEFAULT_COMMENT_SORT }: ListCommentsOptions): Record<string, string> {
+  return {
+    appId: BLOG_APP_ID,
+    contextId: referenceId,
+    resourceId: referenceId,
+    "commentSort.order": sort,
+    "replySort.order": "OLDEST_FIRST",
+    "cursorPaging.limit": String(limit),
+    "cursorPaging.repliesLimit": "0",
+    ...(cursor ? { "cursorPaging.cursor": cursor } : {}),
+  };
+}
+
+/** The same GET, continuing ONE top-level comment's replies from the cursor the list handed back. */
+export function listRepliesParams({ referenceId, cursor, limit = REPLIES_PAGE_SIZE }: { referenceId: string; cursor: string; limit?: number }): Record<string, string> {
+  return {
+    appId: BLOG_APP_ID,
+    contextId: referenceId,
+    resourceId: referenceId,
+    "replySort.order": "OLDEST_FIRST",
+    "cursorPaging.limit": String(limit),
+    "cursorPaging.cursor": cursor,
+  };
+}
+
+export interface CreateCommentOptions {
+  referenceId: string;
+  /** Plain text — wrapped into a one-paragraph Ricos document. */
+  text?: string;
+  /** Or a ready Ricos document (from a rich editor). */
+  richContent?: Record<string, unknown>;
+  /** Reply to this comment (a top-level comment or a reply). */
+  parentId?: string | null;
+}
+
+/** A one-paragraph Ricos document: TEXT is always a leaf inside a PARAGRAPH; the leaf's id is "". */
+export function textToRichContent(text: string): Record<string, unknown> {
+  return {
+    nodes: [
+      { type: "PARAGRAPH", id: "c1", nodes: [{ type: "TEXT", id: "", nodes: [], textData: { text, decorations: [] } }], paragraphData: {} },
+    ],
+  };
+}
+
+/** The create body: `{ comment }`, the reply's parent as `parentComment.id`. */
+export function createCommentBody({ referenceId, text, richContent, parentId }: CreateCommentOptions): Raw {
+  return {
+    comment: {
+      appId: BLOG_APP_ID,
+      contextId: referenceId,
+      resourceId: referenceId,
+      content: { richContent: richContent ?? textToRichContent(text ?? "") },
+      ...(parentId ? { parentComment: { id: parentId } } : {}),
+    },
+  };
+}
+
+/** The plain text of a Ricos document — every TEXT leaf, paragraphs joined by newlines. */
+export function richContentText(rc: Raw | null | undefined): string {
+  const walk = (node: Raw): string =>
+    node.type === "TEXT" ? (node.textData?.text ?? "") : ((node.nodes ?? []) as Raw[]).map(walk).join("");
+  return ((rc?.nodes ?? []) as Raw[]).map(walk).map((s) => s.trim()).filter(Boolean).join("\n");
+}
+
+const STATUSES: readonly CommentStatus[] = ["PUBLISHED", "PENDING", "DELETED", "HIDDEN"];
+
+export interface CommentContext {
+  authors: Record<string, BlogAuthor>;
+  currentMemberId: string | null;
+  /** The top-level comment a reply hangs under; null for top-level comments. */
+  topLevelId: string | null;
+}
+
+export function toComment(raw: Raw, { authors, currentMemberId, topLevelId }: CommentContext): BlogComment {
+  const status: CommentStatus = STATUSES.includes(raw.status) ? raw.status : "UNKNOWN";
+  // A PENDING comment (awaiting the owner's approval) carries its text as draftContent, not content.
+  const content: Raw | null = raw.content?.richContent ?? (status === "PENDING" ? raw.draftContent?.richContent : null) ?? null;
+  const authorId: string = raw.author?.memberId ?? "";
+  const author = authors[authorId];
+  const parentAuthor = authors[raw.parentComment?.author?.memberId ?? ""];
+  return {
+    id: raw._id ?? raw.id ?? "",
+    topLevelId,
+    parentId: raw.parentComment?._id ?? raw.parentComment?.id ?? null,
+    parentAuthorName: parentAuthor?.name ?? "",
+    authorId,
+    authorName: author?.name ?? "",
+    authorAvatarUrl: author?.avatarUrl ?? "",
+    isOwn: Boolean(currentMemberId) && authorId === currentMemberId,
+    ...dateParts(raw.commentDate ?? raw._createdDate ?? raw.createdDate),
+    status,
+    content,
+    text: richContentText(content),
+    replyCount: typeof raw.replyCount === "number" ? raw.replyCount : 0,
+  };
+}
+
+/** Every member id a raw comment list references (authors and reply-to authors), for one batched lookup. */
+export function commentAuthorIds(raws: readonly Raw[]): string[] {
+  return [...new Set(raws.flatMap((c) => [c.author?.memberId, c.parentComment?.author?.memberId]).filter((id): id is string => Boolean(id)))];
+}
+
+/** All raw comments a list response carries — the top-level ones and every seam's replies. */
+export function rawCommentsOf(res: Raw | null | undefined): Raw[] {
+  const replies = Object.values((res?.commentReplies ?? {}) as Record<string, Raw>).flatMap((r) => (r.replies ?? []) as Raw[]);
+  return [...((res?.comments ?? []) as Raw[]), ...replies];
+}
+
+export function toCommentPage(res: Raw | null | undefined, ctx: Omit<CommentContext, "topLevelId">): CommentPage {
+  const replies: Record<string, CommentThread> = {};
+  for (const [topLevelId, r] of Object.entries((res?.commentReplies ?? {}) as Record<string, Raw>)) {
+    replies[topLevelId] = {
+      comments: ((r.replies ?? []) as Raw[]).map((c) => toComment(c, { ...ctx, topLevelId })),
+      nextCursor: r.pagingMetadata?.cursors?.next ?? null,
+    };
+  }
+  return {
+    comments: ((res?.comments ?? []) as Raw[]).map((c) => toComment(c, { ...ctx, topLevelId: null })),
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+    replies,
+  };
+}
+
+/** A replies page: the same response shape, its `comments` being the replies of one top-level comment. */
+export function toCommentThread(res: Raw | null | undefined, ctx: CommentContext): CommentThread {
+  return {
+    comments: ((res?.comments ?? []) as Raw[]).map((c) => toComment(c, ctx)),
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/** Re-mark ownership once the current member is known (the list and the member read run in parallel). */
+export function markOwn<T extends Pick<BlogComment, "authorId" | "isOwn">>(items: T[], currentMemberId: string | null): T[] {
+  return items.map((c) => ({ ...c, isOwn: Boolean(currentMemberId) && c.authorId === currentMemberId }));
+}
+
+/** A deleted comment that still has replies stays as a placeholder: no author, no body. */
+export function toDeletedPlaceholder(c: BlogComment): BlogComment {
+  return { ...c, status: "DELETED", content: null, text: "", authorId: "", authorName: "", authorAvatarUrl: "", isOwn: false };
+}
+
+/** Merge a page into a list by id, keeping the existing order and appending what is new. */
+export function mergeById<T extends { id: string }>(existing: readonly T[], incoming: readonly T[]): T[] {
+  const byId = new Map(existing.map((c) => [c.id, c]));
+  for (const c of incoming) byId.set(c.id, c);
+  const seen = new Set(existing.map((c) => c.id));
+  return [...existing.map((c) => byId.get(c.id)!), ...incoming.filter((c) => !seen.has(c.id))];
+}

package/skills/wix-headless-templates/blog/app/wix/blog/comments-store.ts

@@ -0,0 +1,214 @@
+// A post's comment thread as a framework-free store — the logic behind useComments, usable from
+// React (useComments wraps it), from a static page, from Vue/Svelte, or as the specification for a
+// port. Top-level comments page by cursor; each one's replies load on demand from the seam the list
+// handed back; creating and deleting run as the current identity.
+//
+// Mount it only when `post.commentingEnabled && post.referenceId` — the referenceId IS the thread.
+// Whether guests may comment is the dashboard's "Who can comment" setting, decided by the server: a
+// refused create sets `needsSignIn` (render a sign-in prompt), never a client-side guess. The
+// site-wide comments master switch has no public read — a post whose owner turned comments off
+// site-wide still says commentingEnabled here.
+import { fetchCurrentMemberId } from "./authors";
+import { createComment, deleteComment, fetchComments, fetchReplies } from "./comments";
+import { DEFAULT_COMMENT_SORT, markOwn, mergeById, toDeletedPlaceholder, type CommentSort } from "./comments-core";
+import { isPermissionDenied } from "./posts-core";
+import type { BlogComment, CommentThread } from "./types";
+
+export { type CommentSort };
+
+export interface CommentsStoreOptions {
+  /** `PostDetail.referenceId`. */
+  referenceId: string;
+  pageSize?: number;
+  sort?: CommentSort;
+}
+
+export interface ReplyThreadState extends CommentThread {
+  /** A replies page is in flight. */
+  loading: boolean;
+}
+
+/** Everything a comments surface renders from. */
+export interface CommentsState {
+  /** null while the first load is in flight — render a skeleton, not "no comments yet". */
+  comments: BlogComment[] | null;
+  /** Replies keyed by top-level comment id; a key exists once the list answered a seam for it. */
+  replies: Record<string, ReplyThreadState>;
+  /** True when more top-level comments exist. */
+  hasMore: boolean;
+  loadingMore: boolean;
+  /** A create or delete is in flight — disable the form. */
+  saving: boolean;
+  /** The last create was refused for this identity — render "sign in to comment". */
+  needsSignIn: boolean;
+  /** The current member's id, null for a visitor — own comments carry `isOwn`. */
+  currentMemberId: string | null;
+  sort: CommentSort;
+  /** A failed read or write. While set, an empty `comments` is not an empty thread. */
+  error: string | null;
+}
+
+export interface CommentsStore {
+  getState(): CommentsState;
+  subscribe(listener: () => void): () => void;
+  /** Read the current member and the first page. Call once when mounted. */
+  start(): void;
+  stop(): void;
+  loadMore(): Promise<void>;
+  /** The next page of one top-level comment's replies (its seam's cursor, then each page's). */
+  loadReplies(topLevelId: string): Promise<void>;
+  setSort(sort: CommentSort): void;
+  /**
+   * Post a comment, or a reply to `parentId`. A reply hangs under `topLevelId` (the top-level
+   * comment of the thread); omit it when replying to a top-level comment. Resolves to the created
+   * comment (PENDING when the owner moderates), or null when refused/failed (see needsSignIn/error).
+   */
+  create(text: string, opts?: { parentId?: string | null; topLevelId?: string | null }): Promise<BlogComment | null>;
+  /** Delete one of the member's own comments; a comment with replies becomes a DELETED placeholder. */
+  remove(commentId: string): Promise<void>;
+}
+
+export function createCommentsStore({ referenceId, pageSize, sort: initialSort = DEFAULT_COMMENT_SORT }: CommentsStoreOptions): CommentsStore {
+  let comments: BlogComment[] | null = null;
+  let replies: Record<string, ReplyThreadState> = {};
+  let cursor: string | null = null;
+  let loadingMore = false;
+  let saving = false;
+  let needsSignIn = false;
+  let currentMemberId: string | null = null;
+  let sort: CommentSort = initialSort;
+  let error: string | null = null;
+  let started = false;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+  let snapshot: CommentsState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+  const message = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+  function getState(): CommentsState {
+    if (snapshot) return snapshot;
+    snapshot = { comments, replies, hasMore: cursor !== null, loadingMore, saving, needsSignIn, currentMemberId, sort, error };
+    return snapshot;
+  }
+
+  // The first page for the current sort; a changed sort restarts the list and drops late answers.
+  async function load(): Promise<void> {
+    const id = ++generation;
+    comments = null; replies = {}; cursor = null; error = null; emit();
+    try {
+      const page = await fetchComments({ referenceId, limit: pageSize, sort, currentMemberId });
+      if (generation !== id) return;
+      comments = page.comments; cursor = page.nextCursor;
+      replies = Object.fromEntries(Object.entries(page.replies).map(([k, t]) => [k, { ...t, loading: false }]));
+    } catch (e) {
+      if (generation !== id) return;
+      comments = []; error = message(e);
+    }
+    emit();
+  }
+
+  return {
+    getState,
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      // The member read and the list run in parallel; ownership is re-marked once the id is known.
+      fetchCurrentMemberId().then((mid) => {
+        if (!started) return;
+        currentMemberId = mid;
+        if (comments) comments = markOwn(comments, mid);
+        replies = Object.fromEntries(Object.entries(replies).map(([k, t]) => [k, { ...t, comments: markOwn(t.comments, mid) }]));
+        emit();
+      });
+      void load();
+    },
+    stop() { started = false; generation++; },
+    async loadMore() {
+      if (!cursor || loadingMore) return;
+      const id = generation;
+      loadingMore = true; error = null; emit();
+      try {
+        const page = await fetchComments({ referenceId, limit: pageSize, sort, cursor, currentMemberId });
+        if (generation !== id) return;
+        comments = mergeById(comments ?? [], page.comments); cursor = page.nextCursor;
+        for (const [k, t] of Object.entries(page.replies)) replies[k] ??= { ...t, loading: false };
+        replies = { ...replies };
+      } catch (e) {
+        if (generation !== id) return;
+        error = message(e);
+      } finally {
+        if (generation === id) { loadingMore = false; emit(); }
+      }
+    },
+    async loadReplies(topLevelId) {
+      const thread = replies[topLevelId];
+      if (!thread?.nextCursor || thread.loading) return;
+      const id = generation;
+      replies = { ...replies, [topLevelId]: { ...thread, loading: true } }; emit();
+      try {
+        const page = await fetchReplies({ referenceId, topLevelId, cursor: thread.nextCursor, currentMemberId });
+        if (generation !== id) return;
+        replies = { ...replies, [topLevelId]: { comments: mergeById(thread.comments, page.comments), nextCursor: page.nextCursor, loading: false } };
+      } catch (e) {
+        if (generation !== id) return;
+        replies = { ...replies, [topLevelId]: { ...thread, loading: false } };
+        error = message(e);
+      }
+      emit();
+    },
+    setSort(next) {
+      if (next === sort) return;
+      sort = next;
+      if (started) void load();
+    },
+    async create(text, { parentId = null, topLevelId = null } = {}) {
+      const body = text.trim();
+      if (!body || saving) return null;
+      const threadId = parentId ? (topLevelId ?? parentId) : null;
+      saving = true; needsSignIn = false; error = null; emit();
+      try {
+        const created = await createComment({ referenceId, text: body, parentId, topLevelId: threadId, currentMemberId });
+        if (threadId) {
+          // A reply joins its top-level comment's thread (oldest first → appended) and bumps its count.
+          const thread = replies[threadId] ?? { comments: [], nextCursor: null, loading: false };
+          replies = { ...replies, [threadId]: { ...thread, comments: mergeById(thread.comments, [created]) } };
+          comments = (comments ?? []).map((c) => (c.id === threadId ? { ...c, replyCount: c.replyCount + 1 } : c));
+        } else {
+          comments = sort === "NEWEST_FIRST" ? mergeById([created], comments ?? []) : mergeById(comments ?? [], [created]);
+        }
+        return created;
+      } catch (e) {
+        if (isPermissionDenied(e)) needsSignIn = true; else error = message(e);
+        return null;
+      } finally {
+        saving = false; emit();
+      }
+    },
+    async remove(commentId) {
+      if (saving) return;
+      saving = true; error = null; emit();
+      try {
+        await deleteComment(commentId);
+        const top = (comments ?? []).find((c) => c.id === commentId);
+        if (top) {
+          // A top-level comment with replies stays as a placeholder so its thread keeps its context.
+          const hasReplies = top.replyCount > 0 || (replies[commentId]?.comments.length ?? 0) > 0;
+          comments = hasReplies ? comments!.map((c) => (c.id === commentId ? toDeletedPlaceholder(c) : c)) : comments!.filter((c) => c.id !== commentId);
+        } else {
+          for (const [k, t] of Object.entries(replies)) {
+            if (!t.comments.some((c) => c.id === commentId)) continue;
+            // A reply that other replies point at stays as a placeholder; a leaf is dropped.
+            const referenced = t.comments.some((c) => c.parentId === commentId);
+            replies = { ...replies, [k]: { ...t, comments: referenced ? t.comments.map((c) => (c.id === commentId ? toDeletedPlaceholder(c) : c)) : t.comments.filter((c) => c.id !== commentId) } };
+            if (!referenced) comments = (comments ?? []).map((c) => (c.id === k ? { ...c, replyCount: Math.max(0, c.replyCount - 1) } : c));
+          }
+        }
+      } catch (e) {
+        if (isPermissionDenied(e)) needsSignIn = true; else error = message(e);
+      } finally {
+        saving = false; emit();
+      }
+    },
+  };
+}

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

@@ -0,0 +1,84 @@
+// Post comments (Wix Comments) — the only file that touches raw comment entities on this transport.
+// Goes over `wixFetch` (the SDK's authenticated fetch — the same identity as every module call,
+// member or anonymous visitor) rather than the `@wix/comments` module, which the blog template does
+// not depend on. The rules and mappers live in ./comments-core (shared with the REST twin in
+// templates/blog/rest/comments.ts). Who may comment (members only, or guests too) is the dashboard's
+// "Who can comment" setting, enforced by the server — a denied create surfaces as isPermissionDenied.
+// docs: https://dev.wix.com/docs/api-reference/crm/community/comments/comments/list-comments-by-resource.md
+// docs: https://dev.wix.com/docs/api-reference/crm/community/comments/comments/create-comment.md
+// docs: https://dev.wix.com/docs/api-reference/crm/community/comments/comments/delete-comment.md
+import { wixFetch } from "../sdk";
+import { fetchAuthorsByIds } from "./authors";
+import {
+  commentAuthorIds,
+  createCommentBody,
+  listCommentsParams,
+  listRepliesParams,
+  rawCommentsOf,
+  toComment,
+  toCommentPage,
+  toCommentThread,
+  type CreateCommentOptions,
+  type ListCommentsOptions,
+} from "./comments-core";
+import type { Raw } from "./posts-core";
+import type { BlogComment, CommentPage, CommentThread } from "./types";
+
+export { type CreateCommentOptions, type ListCommentsOptions };
+
+const COMMENTS = "/comments/v1/comments";
+
+// One authenticated JSON call; a non-2xx becomes an Error carrying `status` and the application code,
+// the shape posts-core's isNotFound / isPermissionDenied read.
+async function call(path: string, init?: RequestInit): Promise<Raw> {
+  const res = await wixFetch(path, init);
+  if (res.status === 204) return {};
+  const json = (await res.json().catch(() => ({}))) as Raw;
+  if (!res.ok) {
+    throw Object.assign(new Error(json?.message || `${init?.method ?? "GET"} ${path} failed (${res.status}).`), {
+      status: res.status,
+      code: json?.details?.applicationError?.code,
+      details: json?.details,
+    });
+  }
+  return json;
+}
+const post = (path: string, body: unknown) =>
+  call(path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+
+/**
+ * One page of top-level comments plus each one's reply seam (cursor, no replies yet).
+ * GET /comments/v1/comments/list-by-resource?appId=&contextId=&resourceId=&commentSort.order=&replySort.order=OLDEST_FIRST&cursorPaging.limit=10&cursorPaging.repliesLimit=0[&cursorPaging.cursor=]
+ */
+export async function fetchComments(o: ListCommentsOptions & { currentMemberId?: string | null }): Promise<CommentPage> {
+  const res = await call(`${COMMENTS}/list-by-resource?${new URLSearchParams(listCommentsParams(o))}`);
+  const authors = await fetchAuthorsByIds(commentAuthorIds(rawCommentsOf(res)));
+  return toCommentPage(res, { authors, currentMemberId: o.currentMemberId ?? null });
+}
+
+/**
+ * One page of a top-level comment's replies, from the cursor its seam (or a previous page) handed back.
+ * GET /comments/v1/comments/list-by-resource?appId=&contextId=&resourceId=&replySort.order=OLDEST_FIRST&cursorPaging.limit=10&cursorPaging.cursor=
+ */
+export async function fetchReplies(o: { referenceId: string; topLevelId: string; cursor: string; currentMemberId?: string | null }): Promise<CommentThread> {
+  const res = await call(`${COMMENTS}/list-by-resource?${new URLSearchParams(listRepliesParams(o))}`);
+  const authors = await fetchAuthorsByIds(commentAuthorIds(rawCommentsOf(res)));
+  return toCommentThread(res, { authors, currentMemberId: o.currentMemberId ?? null, topLevelId: o.topLevelId });
+}
+
+/**
+ * Post a comment (or a reply, with `parentId`) as the current identity. Throws — isPermissionDenied(e)
+ * means this viewer may not comment here (sign in). The answer may be PENDING when the owner moderates.
+ * POST /comments/v1/comments  { comment: { appId, contextId, resourceId, content: { richContent }, parentComment?: { id } } }
+ */
+export async function createComment(o: CreateCommentOptions & { topLevelId?: string | null; currentMemberId?: string | null }): Promise<BlogComment> {
+  const res = await post(COMMENTS, createCommentBody(o));
+  const raw: Raw = res?.comment ?? {};
+  const authors = await fetchAuthorsByIds(commentAuthorIds([raw]));
+  return toComment(raw, { authors, currentMemberId: o.currentMemberId ?? null, topLevelId: o.topLevelId ?? o.parentId ?? null });
+}
+
+/** Delete the current member's own comment.  DELETE /comments/v1/comments/{commentId} */
+export async function deleteComment(commentId: string): Promise<void> {
+  await call(`${COMMENTS}/${encodeURIComponent(commentId)}`, { method: "DELETE" });
+}