@wix/agent-skills 1.25.0 → 1.27.0

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" });
+}

package/skills/wix-headless-templates/blog/app/wix/blog/post-likes.ts

@@ -0,0 +1,42 @@
+// Post likes (Wix Blog Like service) over the SDK — the `likes` module of @wix/blog. Every call
+// here runs as the CALLING identity: a member, or the anonymous visitor the token stands for. The
+// like read is personal ("did I like it?") and the writes are the viewer's, so all three are
+// CLIENT-ONLY — the post store runs them only in a browser, never during SSR (where the identity
+// is the app and the read answers PermissionDenied). The rules (FQDN, query, body) live in
+// ./posts-core, shared with the REST twin in templates/blog/rest/post-likes.ts.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/likes/create-like.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/likes/query-likes.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/likes/delete-like-by-fqdn-and-entity-id.md
+import { likes as likesModule } from "@wix/blog";
+import { wixModule } from "../sdk";
+import { fetchPostMetrics } from "./posts";
+import { BLOG_POST_FQDN } from "./posts-core";
+import type { LikeState } from "./types";
+
+const likes = wixModule(likesModule);
+
+/** Like the post as the current viewer. Throws on failure — the store rolls its optimistic flip back. */
+export async function likePost(postId: string): Promise<void> {
+  await likes.createLike({ like: { entityId: postId, fqdn: BLOG_POST_FQDN } });
+}
+
+/** Remove the current viewer's like. */
+export async function unlikePost(postId: string): Promise<void> {
+  await likes.deleteLikeByFqdnAndEntityId({ fqdn: BLOG_POST_FQDN, entityId: postId });
+}
+
+/**
+ * Whether THIS viewer liked the post, plus the post's fresh counters — two independent reads
+ * (allSettled): a failed metrics read still delivers the liked flag and vice versa. The like
+ * read is `limit(1)`: the only question is whether this viewer's row exists.
+ */
+export async function fetchLikeState(postId: string): Promise<LikeState> {
+  const [likeRes, metrics] = await Promise.allSettled([
+    likes.queryLikes().eq("fqdn", BLOG_POST_FQDN).eq("entityId", postId).limit(1).find(),
+    fetchPostMetrics(postId),
+  ]);
+  return {
+    liked: likeRes.status === "fulfilled" && (likeRes.value.items ?? []).length > 0,
+    metrics: metrics.status === "fulfilled" ? metrics.value : null,
+  };
+}

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

@@ -0,0 +1,158 @@
+// One post as a framework-free store — the logic behind usePost, usable from React (usePost wraps
+// it), from a static page's post view, from Vue/Svelte, or as the specification for a port. Loads
+// the post by slug (unless seeded), resolves its category chips from the catalog and its tag chips
+// BY ID (both in the post's own order), loads the related strip, and — in a browser only — the
+// viewer's like state with fresh counters, with an optimistic like toggle.
+//
+// SSR-friendly: pass the server-fetched PostDetail as `initialPost` (plus `initialCategories`,
+// `initialTags`, `initialRelated`) and no client read happens except the personal like state; a SPA
+// passes only the slug. One store per post surface: createPostStore().
+import { fetchPostBySlug, fetchRelatedPosts } from "./posts";
+import { fetchLikeState, likePost, unlikePost } from "./post-likes";
+import { fetchBlogCategories, fetchTagsByIds, inIdOrder } from "./taxonomy";
+import type { BlogCategory, BlogTag, PostDetail, PostSummary } from "./types";
+
+export interface PostStoreOptions {
+  slug: string;
+  initialPost?: PostDetail;
+  /** The category catalog (or just this post's categories) — chips resolve from it in the post's order. */
+  initialCategories?: BlogCategory[];
+  /** This post's tags, already resolved — skips the by-id read. */
+  initialTags?: BlogTag[];
+  /** The related strip, server-fetched — skips the client read. */
+  initialRelated?: PostSummary[];
+  /** Read the viewer's like state and fresh counters, client-side (default true; never runs on a server). */
+  engagement?: boolean;
+}
+
+export interface PostState {
+  /** null while loading (render a skeleton) AND when not found — disambiguate via notFound. */
+  post: PostDetail | null;
+  /** True once the slug definitively resolved to nothing — render a not-found state. */
+  notFound: boolean;
+  /** This post's categories/tags, in the post's order, resolved to full objects (display .label, route by .slug). */
+  categories: BlogCategory[];
+  tags: BlogTag[];
+  /** Related posts (curated, else same-category recents); null while loading, [] when there are none. */
+  related: PostSummary[] | null;
+  /** Whether THIS viewer liked the post (false until the client read lands). */
+  isLiked: boolean;
+  /** The like count to show: the fresh read (else the post's own) plus this viewer's optimistic change; undefined = unknown. */
+  likeCount: number | undefined;
+  /** True once the fresh counters landed — render a skeleton for the like count until then. */
+  likeCountLoaded: boolean;
+  viewCount: number | undefined;
+  commentCount: number | undefined;
+  /** A like write is in flight — disable the control. */
+  liking: boolean;
+  error: string | null;
+}
+
+export interface PostStore {
+  getState(): PostState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch what was not seeded, then (browser only) the like state. Call once when mounted. */
+  start(): void;
+  stop(): void;
+  /** Like / unlike as the current viewer: optimistic, rolled back on failure, one write at a time. */
+  toggleLike(): Promise<void>;
+}
+
+export function createPostStore({ slug, initialPost, initialCategories, initialTags, initialRelated, engagement = true }: PostStoreOptions): PostStore {
+  let post: PostDetail | null = initialPost && initialPost.slug === slug ? initialPost : null;
+  let notFound = false;
+  let catalog: BlogCategory[] | null = initialCategories ?? null;
+  let tags: BlogTag[] = initialTags && post ? inIdOrder(post.tagIds, initialTags) : [];
+  let related: PostSummary[] | null = initialRelated ?? null;
+  let liked = false;
+  let baselineLiked = false; // what the server said — the optimistic delta is measured against it
+  let freshLikes: number | undefined;
+  let likeCountLoaded = false;
+  let viewCount: number | undefined = post?.viewCount;
+  let commentCount: number | undefined = post?.commentCount;
+  let liking = false;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: PostState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function likeCount(): number | undefined {
+    const base = freshLikes ?? post?.likeCount;
+    return base === undefined ? undefined : Math.max(0, base + Number(liked) - Number(baselineLiked));
+  }
+
+  function getState(): PostState {
+    if (snapshot) return snapshot;
+    snapshot = {
+      post,
+      notFound,
+      categories: post && catalog ? inIdOrder(post.categoryIds, catalog) : [],
+      tags,
+      related,
+      isLiked: liked,
+      likeCount: likeCount(),
+      likeCountLoaded,
+      viewCount,
+      commentCount,
+      liking,
+      error,
+    };
+    return snapshot;
+  }
+
+  // Everything that needs the post: tag chips by id, the related strip, the viewer's like state.
+  function afterPost(p: PostDetail): void {
+    if (!initialTags) fetchTagsByIds(p.tagIds).then((t) => { if (started) { tags = t; emit(); } });
+    if (!initialRelated) fetchRelatedPosts(p).then((r) => { if (started) { related = r; emit(); } });
+    // Personal and visitor-scoped: never during SSR (the identity there is the app, not the viewer).
+    if (engagement && typeof window !== "undefined") {
+      fetchLikeState(p.id).then(({ liked: l, metrics }) => {
+        if (!started) return;
+        liked = baselineLiked = l;
+        if (metrics) {
+          freshLikes = metrics.likes;
+          viewCount = metrics.views ?? viewCount;
+          commentCount = metrics.comments ?? commentCount;
+        }
+        likeCountLoaded = true;
+        emit();
+      });
+    }
+  }
+
+  return {
+    getState,
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (!catalog) fetchBlogCategories().then((c) => { if (started) { catalog = c; emit(); } });
+      if (post) {
+        afterPost(post);
+      } else {
+        notFound = false; emit();
+        fetchPostBySlug(slug)
+          .then((p) => {
+            if (!started) return;
+            if (p) { post = p; viewCount = p.viewCount; commentCount = p.commentCount; afterPost(p); } else notFound = true;
+            emit();
+          })
+          .catch((e) => { if (started) { error = e instanceof Error ? e.message : String(e); emit(); } });
+      }
+    },
+    stop() { started = false; },
+    async toggleLike() {
+      if (!post || liking) return;
+      const next = !liked;
+      liked = next; liking = true; emit(); // optimistic flip
+      try {
+        await (next ? likePost(post.id) : unlikePost(post.id));
+      } catch {
+        liked = !next; // roll back — the control reverting is the whole error surface
+      } finally {
+        liking = false; emit();
+      }
+    },
+  };
+}