@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/blog/project/src/wix/blog/types.ts

@@ -0,0 +1,161 @@
+// 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 field that is "" or undefined means "not known" — render nothing for it, never a placeholder.
+
+/** 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 — render nothing, never "0 min read"). */
+  minutesToRead: number;
+  featured: boolean;
+  /** Pinned posts lead the default feed order. */
+  pinned: boolean;
+  /**
+   * Resolved https cover URL, 16:9 ("" when the post has no cover, or its author hid it). A video
+   * cover resolves to its poster, an external embed (YouTube/Vimeo) to its thumbnail.
+   */
+  coverUrl: string;
+  /** Alt text for the cover: the author's alt text, else the title ("" when there is no cover). */
+  coverAlt: string;
+  categoryIds: string[];
+  tagIds: string[];
+  /** The author's member id ("" when none). */
+  authorId: string;
+  /** The author's display name ("" when unresolved — render no byline then). */
+  authorName: string;
+  /** Resolved https avatar URL ("" when none). */
+  authorAvatarUrl: string;
+  /** Counters (the METRICS fieldset). undefined = unknown → render nothing. */
+  viewCount?: number;
+  likeCount?: number;
+  commentCount?: number;
+}
+
+/** 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[];
+  /** Display-ready last-published date ("" when the post was never republished). */
+  updatedLabel: string;
+  updatedISO: string;
+  /** The owner's SEO title override, else the title — the <title> on stacks without the SEO service. */
+  seoTitle: string;
+  /** The owner's meta-description override, else the excerpt, else the body text cut to 500 chars. */
+  seoDescription: string;
+  /** Writer-curated related posts, in the writer's order (may be empty). */
+  relatedPostIds: string[];
+  /** Comments are open on this post (the dashboard's per-post switch). */
+  commentingEnabled: boolean;
+  /** The comments thread id (the REFERENCE_ID fieldset); "" when the API answered without it. */
+  referenceId: string;
+}
+
+/** A post author — a site member's public profile. */
+export interface BlogAuthor {
+  id: string;
+  /** Display name ("" when the member set none). */
+  name: string;
+  /** Resolved https avatar URL ("" when none). */
+  avatarUrl: string;
+}
+
+/** The post's counters as the API's dedicated metrics read answers them. */
+export interface PostMetrics {
+  views?: number;
+  likes?: number;
+  comments?: number;
+}
+
+/** The viewer's like state for one post, plus the fresh counters read alongside it. */
+export interface LikeState {
+  /** Whether THIS viewer (member or anonymous visitor) has liked the post. */
+  liked: boolean;
+  /** null when the metrics read failed — keep the count you had. */
+  metrics: PostMetrics | null;
+}
+
+export interface BlogCategory {
+  id: string;
+  slug: string;
+  /** Display name (the API calls it `label`, never `name`). */
+  label: string;
+  /** The category's SEO title ("" when the owner set none) — the <title> of a category page. */
+  title: 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;
+}
+
+/** PUBLISHED is the normal state; PENDING awaits the owner's approval; DELETED is a placeholder kept for its replies. */
+export type CommentStatus = "PUBLISHED" | "PENDING" | "DELETED" | "HIDDEN" | "UNKNOWN";
+
+/** One comment — a top-level comment or a reply. Threads are two levels deep (Wix's rule). */
+export interface BlogComment {
+  id: string;
+  /** The top-level comment this reply hangs under; null for a top-level comment. */
+  topLevelId: string | null;
+  /** The comment this one replies to (may itself be a reply — show "replying to"); null for a top-level comment. */
+  parentId: string | null;
+  /** The parent's author name ("" when unknown or a top-level comment). */
+  parentAuthorName: string;
+  /** The author's member id ("" for a guest or a deleted comment). */
+  authorId: string;
+  /** The author's display name ("" when unresolved). */
+  authorName: string;
+  authorAvatarUrl: string;
+  /** True when the current member wrote it — show the delete control only then. */
+  isOwn: boolean;
+  dateLabel: string;
+  dateISO: string;
+  status: CommentStatus;
+  /** Ricos document (plain JSON) — render through RichContent where it deploys; a PENDING comment carries its draft. */
+  content: Record<string, unknown> | null;
+  /** The comment's plain text — the body on stacks without the Ricos viewer ("" for a DELETED placeholder). */
+  text: string;
+  /** Number of replies (any depth) under a top-level comment. */
+  replyCount: number;
+}
+
+/** The replies of one top-level comment; `nextCursor` continues them (null → none or all loaded). */
+export interface CommentThread {
+  comments: BlogComment[];
+  nextCursor: string | null;
+}
+
+/** One page of top-level comments plus the reply seams the API answered for them. */
+export interface CommentPage {
+  comments: BlogComment[];
+  nextCursor: string | null;
+  /** Keyed by top-level comment id — its replies (empty until loaded) and their cursor. */
+  replies: Record<string, CommentThread>;
+}

package/skills/wix-headless-templates/blog/project/src/wix/config.ts

@@ -0,0 +1,16 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. deploy.mjs copies it from `.env.local`
+//                         (`WIX_CLIENT_ID`, what `wix env pull` writes): the CONTENT site's app — on a
+//                         migration preview the site being migrated, while wix.config.json names
+//                         only the deploy target.
+export const WIX_CLIENT_ID: string | null = null;
+
+// Kept for projects deployed before the Members vertical moved onto the shared seam; the shipped
+// members code no longer reads it (ambient Astro uses the built-in /api/auth routes, manual mode
+// uses the shared client above). deploy.mjs still fills it so older code keeps compiling.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

package/skills/wix-headless-templates/blog/project/src/wix/media.ts

@@ -0,0 +1,106 @@
+// Wix media resolution — define once, use on EVERY image render path. Copy as-is.
+//
+// SDK media fields come back either as an already-absolute https URL, or as a
+// `wix:image://v1/<hash>/<file>#originWidth=…` identifier that a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The wix:image:// form must go through the SDK media module;
+// never hand-build a static.wixstatic.com URL (wrong format → 403).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import { media } from "@wix/sdk";
+
+type MediaLike =
+  | string
+  | null
+  | undefined
+  | { image?: unknown; url?: string | null; id?: string | null };
+
+/** A bare Wix media file id (`e6a89e_06cf…~mv2.png`): what REST-shaped media objects carry as `url` and `id`. */
+const BARE_FILE_ID = /^[\w-]+~mv2\.[a-z0-9]+$/i;
+
+function rawOf(value: MediaLike): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (value.image != null && typeof value.image === "object") return rawOf(value.image as MediaLike); // { image: { id, url } }
+  return (typeof value.image === "string" ? value.image : null) ?? value.url ?? value.id ?? "";
+}
+
+/** Resolve any Wix media value to a browser-loadable URL ("" when absent). */
+export function imgSrc(value: MediaLike, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) {
+    return media.getScaledToFillImageUrl(v, width, height, {});
+  }
+  // A bare file id (what REST-shaped media objects carry) or an absolute Wix media URL (bare, or
+  // already carrying a /v1/fill/ segment at some other size): re-issue it through the scaler at the
+  // requested size, so every image path lands on one shape.
+  const file = BARE_FILE_ID.test(v) ? v : v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/)?.[1];
+  if (file) return `https://static.wixstatic.com/media/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  return v;
+}
+
+/**
+ * Responsive candidates for `srcset`: the same image at several widths through Wix's scaler, so a
+ * card never downloads a hero-sized file. Pair with `sizes`:
+ *   <img src={imgSrc(m, 640, 640)} srcSet={imgSrcSet(m)} sizes="(min-width: 1024px) 25vw, 50vw"
+ *        width={640} height={640} loading="lazy" alt={…} />
+ * Accepts every form an image reaches you in: a raw `wix:image://` id, an ALREADY-RESOLVED Wix URL
+ * (what the DTOs carry — `imageUrl`, `gallery[]`; its `/v1/fill/w_…,h_…` segment is rewritten per
+ * width), or any other https URL (returned as the single candidate). `ratio` is height/width
+ * (1 = square). "" only when there is no image at all — still set `src` as well.
+ */
+export function imgSrcSet(value: MediaLike, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const raw = rawOf(value);
+  if (!raw) return "";
+  if (raw.startsWith("wix:image://") || BARE_FILE_ID.test(raw)) {
+    return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  }
+  // A resolved Wix URL: …/v1/fill/w_800,h_800,al_c,… — swap the size for each width.
+  const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+  if (/static\.wixstatic\.com\//.test(raw) && FILL.test(raw)) {
+    return widths.map((w) => `${raw.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return raw; // one candidate, never an empty srcset for a real image
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcSet` without `src`:
+ *   <img {...imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw")} alt={p.name} />
+ * `sizes` is the width the image renders at (a CSS length or media-query list); `ratio` is
+ * height/width. Returns an empty object when there is no image — render your placeholder then.
+ */
+export function imgAttrs(value: MediaLike, sizes: string, ratio = 1): { src: string; srcSet: string; sizes: string; loading: "lazy"; decoding: "async" } | Record<string, never> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcSet: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/**
+ * Height/width of a Wix image when the value carries its size: a raw
+ * `wix:image://…#originWidth=W&originHeight=H` id (the natural size) or a resolved `/v1/fill/w_W,h_H/`
+ * URL (the size it was scaled to). null when neither is present. Pass it as `ratio` to keep a
+ * srcset at the image's own aspect instead of the square default:
+ *   <img {...imgAttrs(item.photo, "33vw", imgRatio(item.photo) ?? 1)} alt={…} />
+ */
+export function imgRatio(value: MediaLike): number | null {
+  const v = rawOf(value);
+  if (typeof v !== "string" || !v) return null;
+  const size = v.startsWith("wix:image://")
+    ? [v.match(/[#&]originWidth=(\d+)/)?.[1], v.match(/[#&]originHeight=(\d+)/)?.[1]]
+    : (v.match(/\/v1\/fill\/w_(\d+),h_(\d+)/)?.slice(1) ?? []);
+  const w = Number(size[0]);
+  const h = Number(size[1]);
+  return w > 0 && h > 0 ? h / w : null;
+}
+
+/**
+ * The identity of a media value BEFORE scaling — de-duplicate galleries on this, never on a
+ * resolved URL (two scaled URLs of one photo differ in their size parameters).
+ */
+export function mediaKey(value: MediaLike): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  // The file id, whichever form the value takes — a raw id and a resolved URL of one photo share it.
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : v;
+}

package/skills/wix-headless-templates/blog/project/src/wix/money.ts

@@ -0,0 +1,24 @@
+// Money formatting for API amounts that carry no formatted string. Copy as-is.
+//
+// Catalog prices come with a ready `formattedAmount` — use that directly. But eCom Cart V2
+// amounts are ConvertedMoney `{ amount, convertedAmount }` with NO formatted string, and the
+// currency lives on the cart, not on the money object. Never hardcode "$" or assume USD.
+export interface ConvertedMoneyLike {
+  amount?: string | null;
+  convertedAmount?: string | null;
+}
+
+/** Format a ConvertedMoney in the given currency, using the visitor's locale. */
+export function formatMoney(
+  money: ConvertedMoneyLike | null | undefined,
+  currencyCode: string | null | undefined,
+): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}

package/skills/wix-headless-templates/blog/project/src/wix/sdk.ts

@@ -0,0 +1,89 @@
+// The one auth seam for every Wix SDK call in this app. Copy as-is; do not rewrite.
+//
+// Two modes, switched by WIX_CLIENT_ID in ./config:
+//   null (ambient)  — a Wix-managed Astro project: `@wix/astro` authenticates raw SDK module
+//                     calls automatically, server-side AND in client islands. `wixModule()`
+//                     returns the module untouched.
+//   string (manual) — any other React setup (Vite SPA, non-Astro): one shared client is built
+//                     with OAuthStrategy, and `wixModule()` returns the module bound to it.
+//                     The strategy self-manages visitor tokens on every call (mints on first
+//                     use, renews on expiry) and persists them through the storage below.
+//
+// The visitor token IS the identity of the current cart / member session, so in manual mode
+// tokens persist to localStorage — never re-minted per load (a fresh anonymous mint is a NEW
+// visitor and silently empties the cart).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
+// docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
+import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import { fetchWithAuth as ambientFetch } from "@wix/sdk/context";
+import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
+import { WIX_CLIENT_ID } from "./config";
+
+const STORAGE_KEY = `wix-session-${WIX_CLIENT_ID ?? "ambient"}`;
+
+function browserTokenStorage(): TokenStorage {
+  return {
+    getTokens(): Tokens {
+      if (typeof window !== "undefined") {
+        try {
+          const raw = window.localStorage.getItem(STORAGE_KEY);
+          if (raw) return JSON.parse(raw) as Tokens;
+        } catch {
+          /* disabled/corrupt storage — fall through to empty */
+        }
+      }
+      return EMPTY_TOKENS;
+    },
+    setTokens(tokens: Tokens): void {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+      } catch {
+        /* storage full/disabled — the session just won't survive a reload */
+      }
+    },
+  };
+}
+
+const client = WIX_CLIENT_ID
+  ? createClient({
+      auth: OAuthStrategy({
+        clientId: WIX_CLIENT_ID,
+        tokenStorage: browserTokenStorage(),
+      }),
+    })
+  : null;
+
+/**
+ * Bind an SDK module to this app's auth. Usage (identical in both modes):
+ *   import { productsV3 } from "@wix/stores";
+ *   const products = wixModule(productsV3);
+ *   await products.queryProducts(...)
+ */
+export function wixModule<T>(module: T): T {
+  // The cast bridges the SDK's internal Descriptors constraint; the in/out type is identical.
+  return client
+    ? (client.use(module as unknown as Record<string, unknown>) as unknown as T)
+    : module;
+}
+
+/**
+ * An authenticated fetch of a Wix REST endpoint under the SAME auth as the SDK modules (ambient
+ * on managed Astro, the shared client elsewhere) — for the few APIs whose generated SDK module is
+ * too heavy to bundle (the Forms schema module alone is 15 MB: server-side it pushes a Wix
+ * deploy past its size limit, client-side every visitor downloads it). Same visitor identity,
+ * same token, no second mint. `path` is the wixapis.com path; returns the raw Response.
+ */
+export function wixFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = path.startsWith("http") ? path : `https://www.wixapis.com${path}`;
+  return client ? client.fetchWithAuth(url, init) : ambientFetch(url, init);
+}
+
+/**
+ * The shared data client's manual-mode auth strategy, or null under ambient auth. The
+ * Members vertical deliberately owns a separate explicit client for its custom in-app login;
+ * app code reads that session through the members hooks instead.
+ */
+export function wixAuth(): IOAuthStrategy | null {
+  return client ? client.auth : null;
+}

package/skills/wix-headless-templates/blog/project/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/skills/wix-headless-templates/blog/rest/authors.ts

@@ -0,0 +1,39 @@
+// Author reads over REST — the twin of app/wix/blog/authors.ts. Same exports, same DTOs; the
+// mappers come from authors-core (the SAME file the SDK transport uses, deployed flat next to this
+// one). Both reads are non-fatal: authors are decoration on a card. Porting: keep the paths, keep
+// the bodies, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/query-members.md
+// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/get-my-member.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { authorsQuery, indexAuthors, toAuthor, uniqueIds } from "./authors-core.js";
+import type { Raw } from "./posts-core.js";
+import type { BlogAuthor } from "./types.js";
+
+/**
+ * Every distinct author of one page in ONE request, keyed by member id. {} on failure.
+ * POST /members/v1/members/query  { fieldsets: ["PUBLIC"], query: { filter: { id: { $in } }, paging: { limit } } }
+ */
+export async function fetchAuthorsByIds(ids: readonly (string | null | undefined)[]): Promise<Record<string, BlogAuthor>> {
+  const unique = uniqueIds(ids);
+  if (!unique.length) return {};
+  try {
+    const res = await wixRequest<Raw>("/members/v1/members/query", { body: authorsQuery(unique) });
+    return indexAuthors(((res?.members ?? []) as Raw[]).map((m) => toAuthor(m, imgSrc)));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The current member's id, or null for an anonymous visitor (401/403 → null).
+ * GET /members/v1/members/my
+ */
+export async function fetchCurrentMemberId(): Promise<string | null> {
+  try {
+    const res = await wixRequest<Raw>("/members/v1/members/my", { method: "GET" });
+    return res?.member?.id ?? null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,64 @@
+// Post comments over REST — the twin of app/wix/blog/comments.ts. Same exports, same DTOs; the
+// rules and mappers come from comments-core (the SAME file the SDK transport uses, deployed flat
+// next to this one). Every call runs as the calling identity — in a port, the viewer's session
+// token, never a process-wide one (a create would be attributed to whoever that token is).
+// 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 { wixRequest } from "./client.js";
+import { fetchAuthorsByIds } from "./authors.js";
+import {
+  commentAuthorIds,
+  createCommentBody,
+  listCommentsParams,
+  listRepliesParams,
+  rawCommentsOf,
+  toComment,
+  toCommentPage,
+  toCommentThread,
+  type CreateCommentOptions,
+  type ListCommentsOptions,
+} from "./comments-core.js";
+import type { Raw } from "./posts-core.js";
+import type { BlogComment, CommentPage, CommentThread } from "./types.js";
+
+export { type CreateCommentOptions, type ListCommentsOptions };
+
+const COMMENTS = "/comments/v1/comments";
+
+/**
+ * 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 wixRequest<Raw>(`${COMMENTS}/list-by-resource`, { method: "GET", query: 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 wixRequest<Raw>(`${COMMENTS}/list-by-resource`, { method: "GET", query: 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 a WixApiError —
+ * isPermissionDenied(e) means this viewer may not comment here (sign in).
+ * 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 wixRequest<Raw>(COMMENTS, { body: 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 wixRequest(`${COMMENTS}/${encodeURIComponent(commentId)}`, { method: "DELETE" });
+}

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

@@ -0,0 +1,37 @@
+// Post likes over REST — the twin of app/wix/blog/post-likes.ts. Same exports, same DTOs; the FQDN,
+// query, and body come from posts-core. Every call runs as the calling identity (member or the
+// anonymous visitor the token stands for), so all three are CLIENT-ONLY — in a port, never from a
+// process-wide token. Porting: keep the paths, keep the bodies.
+// 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 { wixRequest } from "./client.js";
+import { fetchPostMetrics } from "./posts.js";
+import { BLOG_POST_FQDN, likeBody, likeStateQuery, type Raw } from "./posts-core.js";
+import type { LikeState } from "./types.js";
+
+/** Like the post as the current viewer.  POST /blog/v1/likes  { like: { entityId, fqdn: "wix.blog.v3.post" } } */
+export async function likePost(postId: string): Promise<void> {
+  await wixRequest("/blog/v1/likes", { body: likeBody(postId) });
+}
+
+/** Remove the current viewer's like.  DELETE /blog/v1/likes/fqdn/{fqdn}/entity-id/{entityId} */
+export async function unlikePost(postId: string): Promise<void> {
+  await wixRequest(`/blog/v1/likes/fqdn/${encodeURIComponent(BLOG_POST_FQDN)}/entity-id/${encodeURIComponent(postId)}`, { method: "DELETE" });
+}
+
+/**
+ * Whether THIS viewer liked the post (one row = yes; the service scopes the query to the caller),
+ * plus the fresh counters — two independent reads (allSettled).
+ * POST /blog/v1/likes/query  { query: { filter: { fqdn: { $eq }, entityId: { $eq } }, cursorPaging: { limit: 1 } } }
+ */
+export async function fetchLikeState(postId: string): Promise<LikeState> {
+  const [likeRes, metrics] = await Promise.allSettled([
+    wixRequest<Raw>("/blog/v1/likes/query", { body: { query: likeStateQuery(postId) } }),
+    fetchPostMetrics(postId),
+  ]);
+  return {
+    liked: likeRes.status === "fulfilled" && ((likeRes.value?.likes ?? []) as Raw[]).length > 0,
+    metrics: metrics.status === "fulfilled" ? metrics.value : null,
+  };
+}