@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-vibe-headless/platforms/base44.md

@@ -0,0 +1,142 @@
+# Wix Managed Headless — Base44 build instructions
+
+You are building a **Wix Managed** headless site inside Base44. The business to build is
+described in your initial prompt. The Wix connector is already configured for this app — use
+it for all Wix API calls.
+
+Your Wix client id is given in your prompt. It's a public, buyer/visitor-facing credential (it
+only mints anonymous visitor tokens), so it's safe in the frontend — use that value directly for
+the Wix client setup.
+
+Follow the steps below exactly.
+
+## STEP 0 — Install the Wix skills locally
+
+Install three skills — they land under `.agents/skills/` as:
+- **`wix-vibe-headless`** — the client build guide: how to build the frontend against the Wix
+  APIs. This is your main source of truth (STEP 1).
+- **`wix-headless`** — a broad skill for building full Wix apps with the Wix SDK packages, **most
+  of which does not apply to how you build here**. Use it **only** as a seeding/admin recipe
+  reference — its `references/SEED.md` and `references/inline-recipes/`, for STEP 2. **Ignore
+  everything else in it** — in particular do **not** follow its authentication / `@wix/cli` /
+  "managed project" setup (e.g. anything under `references/managed/`, such as `AUTHENTICATION.md`).
+  That is **not** how auth works here — auth is handled per STEP 2 below.
+- **`wix-docs`** — a **fallback**: how to search and read the Wix API reference docs, for anything
+  the seeding recipes above don't cover.
+
+**Option A — skills CLI.** This is the Base44-verified install path — run it first via
+exec_tool, exactly as written:
+
+```js
+const { execSync } = require('child_process');
+const { readdirSync } = require('fs');
+
+const skills = ['wix-headless', 'wix-vibe-headless', 'wix-docs'];
+const results = {};
+
+for (const skill of skills) {
+  try {
+    const out = execSync(`CI=1 npx -y skills add wix/skills/skills/${skill} --yes 2>&1`, {
+      cwd: '/app', timeout: 60000, shell: '/bin/bash', stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const text = out.toString().replace(/\x1b\[[0-9;]*m/g, '');
+    results[skill] = /installed 1 skill|found 1 skill/i.test(text)
+      ? 'success'
+      : text.includes('No valid skills') ? 'not_found' : 'unknown';
+  } catch (e) {
+    results[skill] = 'error: ' + e.message;
+  }
+}
+
+return { results, installed: readdirSync('/app/.agents/skills') };
+```
+
+**Option B — tarball.** Use this **only if Option A actually errored** (check its `results`) —
+do not skip Option A on a guess. Run via exec_tool:
+
+```js
+const { execSync } = require('child_process');
+for (const s of ['headless', 'vibe-headless', 'docs']) {
+  execSync(`mkdir -p /app/.agents/skills/wix-${s} && curl -s "https://www.wix.com/skills/${s}.tgz" | tar xz -C /app/.agents/skills/wix-${s} --strip-components=1`);
+}
+return 'done';
+```
+
+Either way you end up with `.agents/skills/{wix-headless,wix-vibe-headless,wix-docs}`. **Read them
+with the `read_file` tool** — it caps by line (~5000, well above these docs, so each comes through
+whole; page with offset/limit only if ever needed), whereas `cat` through exec_tool caps output at
+~5000 chars and silently truncates, and web-fetch tools truncate/summarise. The path form depends
+on the tool:
+- **`read_file` (preferred):** rooted at `/app`, so use the workspace-relative path
+  `.agents/skills/wix-vibe-headless/SKILL.md` — an absolute `/app/...` double-prefixes and fails.
+- **exec_tool / shell** (only if you must): use the absolute path
+  `/app/.agents/skills/wix-vibe-headless/SKILL.md`.
+
+## STEP 1 — Build the client
+
+Read `.agents/skills/wix-vibe-headless/SKILL.md` and follow it **EXACTLY** — it is the single
+source of truth for how the client app is built. To save time, prefer copying ready-made files
+the `wix-vibe-headless` skill provides (e.g. the Wix client setup) and adapting them over
+re-generating them from scratch.
+
+## STEP 2 — Manage and seed the business
+
+Seed the site with real content by following the **`wix-headless` skill**'s
+`references/SEED.md` (`.agents/skills/wix-headless/references/SEED.md`). Where its seed recipes
+don't cover what you need, **fall back to the `wix-docs` skill** (`.agents/skills/wix-docs`) to
+search and read the relevant Wix API docs.
+
+**Seeding is additive.** You may clean up the app install's **obvious default sample/mock data**
+right after a fresh install, but the site may already hold **real content** (a prior run, or
+owner-added) — if what's there isn't obviously install sample data, or you're unsure, **do not
+delete or overwrite it without the user's explicit ask or approval** (ask first).
+
+**Auth for these admin calls is the already-configured Wix connector — and nothing else.** Get the
+access token from it and send it as a bearer token — do **not** hand-roll a token getter (e.g. a
+custom `getAdminToken()`):
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+// then: fetch(url, { headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" }, ... })
+```
+
+Do **not** install or run the Wix CLI (`@wix/cli`), do a device-login, or follow `wix-headless`'s
+`references/managed/AUTHENTICATION.md` — that managed-project auth flow does not apply to Base44
+and will send you down the wrong path.
+
+When you run seed/management code **inline via exec_tool**, `base44` is already declared — use
+it directly. Do **not** import `@base44/sdk`, re-declare `base44`, or call `createClient()` —
+that pattern is only for standalone `.js` skill files, and inline it throws *"Identifier
+'base44' has already been declared."*
+
+**IMPORTANT:** the Wix connector and the `wix-headless` skill's seeding instructions are for
+management/admin operations only (STEP 2) — they are **NOT** part of the client. The client is
+built solely per the `wix-vibe-headless` skill.
+
+## Parallelism
+
+If possible, run STEP 1 and STEP 2 in parallel — building the client and seeding the business
+are independent, so don't wait for one to start the other. Within each step, also work in
+parallel where possible (e.g. independent API calls, seeding multiple entities) instead of
+one-by-one, to finish faster.
+
+## STEP 3 — Wrap up
+
+Once the site is built and seeded:
+
+1. **Leave a brief "Wix skills" note in `AGENTS.md`** (project root) so a future session has
+   context. If the file already exists, **`read_file` it first and only append your section** —
+   do **not** rewrite, reorder, or remove anything already there; if you can't append cleanly,
+   skip this rather than overwrite. Create the file only if none exists. Keep the note
+   high-level, e.g.: the Wix skills are installed under `.agents/skills/`; the client is built
+   per the `wix-vibe-headless` skill; seeding/management is done per the `wix-headless` +
+   `wix-docs` skills.
+2. **Ask the user to open** this URL to complete the setup in Wix (substitute the metasite id
+   you were given): `https://manage.wix.com/dashboard/{metaSiteId}`
+
+## Later admin requests
+
+For any later admin/management request the user makes, work the same way as STEP 2: check the
+`wix-headless` skill's inline recipes first (`.agents/skills/wix-headless/references/inline-recipes/`)
+and, where the operation isn't documented there, fall back to the `wix-docs` skill to search the
+Wix API docs — all over the Wix connector.

package/skills/wix-vibe-headless/platforms/generic.md

@@ -0,0 +1,87 @@
+# Wix Managed Headless — build instructions
+
+You are building a **Wix Managed** headless site. The business to build, and your Wix client id
+and metasite id, are given in your initial prompt. Follow the steps below.
+
+## STEP 0 — Install the Wix skills locally
+
+Install three skills — they land under `.agents/skills/` as:
+- **`wix-vibe-headless`** — the client build guide: how to build the frontend against the Wix
+  APIs. This is your main source of truth (STEP 1).
+- **`wix-headless`** — a broad skill for building full Wix apps with the Wix SDK packages, **most
+  of which does not apply to how you build here**. Use it **only** as a seeding/admin recipe
+  reference — its `references/SEED.md` and `references/inline-recipes/`, for STEP 2. **Ignore
+  everything else in it** — in particular do **not** follow its authentication / `@wix/cli` /
+  "managed project" setup (e.g. anything under `references/managed/`, such as `AUTHENTICATION.md`).
+  That is **not** how auth works here — auth is handled per STEP 2 below.
+- **`wix-docs`** — a **fallback**: how to search and read the Wix API reference docs, for anything
+  the seeding recipes above don't cover.
+
+Install them so you can read them from files as you go (fetching skill docs over the web
+truncates or summarises large files).
+
+**Run the Skills CLI** — this is the install path to use:
+```bash
+CI=1 npx skills@latest add wix/skills/skills/wix-headless --yes
+CI=1 npx skills@latest add wix/skills/skills/wix-vibe-headless --yes
+CI=1 npx skills@latest add wix/skills/skills/wix-docs --yes
+```
+
+**Only if the CLI above actually errors** (not on a guess), fall back to curl + gzip — download
+each bundle and extract it into `.agents/skills/wix-<name>/`:
+```bash
+for s in headless vibe-headless docs; do
+  mkdir -p ".agents/skills/wix-$s"
+  curl -s "https://www.wix.com/skills/$s.tgz" | tar xz -C ".agents/skills/wix-$s" --strip-components=1
+done
+```
+
+## STEP 1 — Build the client
+
+Read `.agents/skills/wix-vibe-headless/SKILL.md` and follow it **exactly** — it is the single
+source of truth for how the client app is built against the Wix APIs (over the public
+`WIX_CLIENT_ID`, which is a buyer/visitor-facing credential, safe in the frontend). To save time,
+prefer copying the ready-made files the `wix-vibe-headless` skill provides (e.g. the Wix client
+setup) and adapting them over re-generating them from scratch.
+
+## STEP 2 — Seed and manage the business
+
+Seed the site with real content by following the `wix-headless` skill's `references/SEED.md`
+(`.agents/skills/wix-headless/references/SEED.md`). Where its seed recipes don't cover what you
+need, fall back to the `wix-docs` skill to search and read the relevant Wix API docs.
+
+**Seeding is additive.** You may clean up the app install's **obvious default sample/mock data**
+right after a fresh install, but the site may already hold **real content** (a prior run, or
+owner-added) — if what's there isn't obviously install sample data, or you're unsure, **do not
+delete or overwrite it without the user's explicit ask or approval** (ask first).
+
+These management/admin calls need **elevated Wix credentials** — the public client id is not
+enough. If you don't already have a way to authenticate them, either **connect your platform's
+Wix connector** (if it has one) or **ask the user for a Wix API key / token** and store it in your
+platform's built-in **connector / secrets (env) manager** — never hardcode or commit it. **Once
+the connector is connected (or the API key is in place), you can make Wix REST admin calls
+directly** — authenticate each call with that credential (the `wix-docs` skill covers Wix API-key
+auth). Or, if the user prefers, tell them they can add this content themselves in the Wix
+dashboard instead.
+
+Authenticate admin calls with **only** that connector/API key. Do **not** install or run the Wix
+CLI (`@wix/cli`), do a device-login, or follow `wix-headless`'s `references/managed/AUTHENTICATION.md`
+— that managed-project auth flow does not apply here.
+
+Management/admin operations (seeding, `wix-headless`, `wix-docs`) are **separate from the
+client** — the client is built solely per the `wix-vibe-headless` skill.
+
+If possible, run STEP 1 and STEP 2 in parallel — building the client and seeding the business
+are independent. Within each, also parallelize independent work (API calls, seeding multiple
+entities) to finish faster.
+
+## Later admin requests
+
+For any later admin/management request, work the same way as STEP 2: check the `wix-headless`
+skill's inline recipes first (`.agents/skills/wix-headless/references/inline-recipes/`) and fall
+back to the `wix-docs` skill where the operation isn't documented there.
+
+## When done
+
+After the site is built and seeded, ask the user to open this URL to complete the setup in Wix
+(substitute the metasite id you were given): `https://manage.wix.com/dashboard/{metaSiteId}`

package/skills/wix-vibe-headless/references/blog/INSTRUCTIONS.md

@@ -0,0 +1,128 @@
+
+# Wix Blog Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/blog/wix-blog.js`. Copy **both** into your app's `src/rest/` side by side — the helper does `import { wixApiRequest } from "./wix-client.js"`, so they must land in the same folder.
+
+Builds a real, client-only Wix blog reader. The browser talks to Wix directly over a
+public `WIX_CLIENT_ID`. Never mock posts; never hand-build post/category/tag URLs — always
+fetch live data through the official Blog REST endpoints and route by `slug`.
+
+## When to use
+- User wants a Wix blog/news/articles section or asks to "connect my Wix blog".
+- Replacing placeholder/mock articles with live Wix Blog posts.
+- Adding a post feed, post detail pages, category pages, or tag pages over an existing
+  Wix Blog with published posts.
+
+This skill is **read-only and visitor-facing**. It does not create, edit, publish, or
+moderate posts — the author manages all content in the Wix dashboard.
+
+## Prerequisites
+1. A Wix site with **Wix Blog installed and posts already published** (this skill does
+   NOT provision — it's read-only over published content). Draft/unpublished posts are
+   never returned.
+2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the
+   Wix Business Manager surfaces a copyable prompt with the id filled in — see
+   the router `SKILL.md`). Paste it into `src/rest/wix-client.js` in place of the placeholder. It is
+   a visitor-facing credential (it only mints anonymous visitor tokens), **not** a secret,
+   so hardcoding/committing it is fine.
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the blog's UI however the
+project wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and
+only adjust import paths:
+- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to
+  the id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The refresh token is
+  persisted to localStorage so the same anonymous visitor is reused across reloads; do not
+  re-mint anonymously per load.
+- `src/rest/wix-blog.js` — exports:
+  - **Posts:** `queryPosts`, `getPostBySlug`, `queryPostsByCategory`, `queryPostsByTag`, `getTotalPosts`
+  - **Categories:** `queryCategories`, `getCategoryBySlug`
+  - **Tags:** `queryTags`, `getTagBySlug`
+
+The Post, Category, and Tag shapes are documented as JSDoc comments at the top of
+`wix-blog.js`. Read them before building the UI — they describe the key fields and link to
+the full API reference for anything not shown.
+
+## How to wire it (UI is the project's choice)
+- **Post feed** — `queryPosts()` for the listing (published posts only, newest first with
+  pinned posts leading); pass `nextCursor` back as `cursor` to load the next page. Render
+  `title`, `excerpt`, `firstPublishedDate`, `minutesToRead`, and the cover image from
+  **`post.media.wixMedia.image.url`** (see the cover-image note below). Route to the detail page by `slug`.
+- **Post detail** — `getPostBySlug(slug)` keyed off the URL slug; returns `null` on miss —
+  show a not-found state, never invent a post. It returns full content:
+  - `contentText` — the body as plain text. Split on `"\n"` to render simple paragraphs.
+  - `richContent` — the body as a Ricos rich-content document (images, embeds, formatting).
+    Render it with a Ricos renderer for a faithful post. See "Beyond the snippets" if you
+    need rich rendering; `contentText` is the zero-dependency default.
+  - Resolve `categoryIds` / `tagIds` to labels with `queryCategories()` / `queryTags()`
+    (build an id→label map) to show category/tag chips.
+- **Cover image** — use **`post.media.wixMedia.image.url`** (a ready-to-use https URL) for the card
+  thumbnail and post header. `media` is returned by default (including on the list query), so no extra
+  fieldset is needed. When `post.media?.wixMedia?.image` is absent, the cover is the first image inside
+  `richContent` — fall back to the first IMAGE node there, or show a text-only card. Never substitute a
+  stock/placeholder image.
+- **Category page** — `queryCategories()` for a category menu (ordered by `displayPosition`;
+  hide categories with `postCount === 0` if you want); `getCategoryBySlug(slug)` for a
+  category landing page. Pass `category.id` to `queryPostsByCategory(categoryId, { limit?, cursor? })`
+  to list that category's posts; paginate exactly like `queryPosts`.
+- **Tag page** — `queryTags()` for a tag cloud/list (most-used first); `getTagBySlug(slug)`
+  for a tag landing page. Pass `tag.id` to `queryPostsByTag(tagId, { limit?, cursor? })`.
+- **Empty state** — if `getTotalPosts()` is 0, show an empty state telling the user to
+  publish posts in their Wix dashboard. Never invent posts.
+
+## Hard rules (do not violate)
+- ✅ Fetch posts/categories/tags ONLY through the shipped helpers (the official Blog REST
+  endpoints). Route between screens by `slug`.
+- ❌ Never hand-build post, category, or tag URLs to fetch content. Use `getPostBySlug`,
+  `getCategoryBySlug`, `getTagBySlug`. (For an outbound link to the live Wix page, use the
+  `url` field — `url.base + url.path` — returned on the object, not a string you assemble.)
+- ❌ Never mock posts, authors, or content — render live Wix data or the empty state.
+- ❌ Never generate fake comments, likes, view counts, or ratings. This skill is read-only
+  and does not expose engagement actions; leave such UI empty or omit it.
+- ❌ Never use a placeholder/stock cover image. If `post.media?.wixMedia?.image` is missing, fall back
+  to the first richContent image or a text-only card.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
+- ✅ Use `post.media.wixMedia.image.url` for the cover image.
+- The helpers fail soft on single-item lookups: `getPostBySlug` / `getCategoryBySlug` /
+  `getTagBySlug` return `null` on a miss so you can show a proper not-found state — don't
+  swallow that into a fake item.
+
+## Beyond the snippets
+The snippets cover the common blog-reader paths. If you hit a use case they don't cover
+(e.g. rendering `richContent` faithfully, full-text search/filtering, related posts,
+post metrics, members-only/pricing-plan posts, multilingual posts), extend the client
+yourself with `wixApiRequest` — but look up the exact endpoint, HTTP method, and request
+body in the **official Wix API reference** first; never guess:
+- Blog API reference: https://dev.wix.com/docs/api-reference/business-solutions/blog.md
+- Query Posts (filters/sort: `categoryIds`, `tagIds`, `hashtags`, `title`, dates, `featured`):
+  https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md
+- Rendering `richContent` (Ricos document format):
+  https://dev.wix.com/docs/ricos/api-reference/ricos-document
+- **Members-only posts** → the **members** vertical (`references/members/INSTRUCTIONS.md`): once a
+  member is logged in (custom login on your own UI), the existing read helpers return the content
+  gated to members — no extra code. Note this blog helper is **read-only**: member *writes* (posting
+  a comment, liking a post) aren't included — add them as a beyond-the-snippets `wixApiRequest` call,
+  authenticated as the logged-in member.
+- Each helper in `wix-blog.js` links its exact reference page inline.
+
+Keep the snippets as the default for everything they already do; reach for the API
+reference only for the gap.
+
+## Point the user to their dashboard
+In some cases, users need to access the Wix dashboard in order to edit the blog content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For blog data those pages are:
+- **Posts** — `https://manage.wix.com/dashboard/{metaSiteId}/blog/posts` (`Dashboard → Blog → Posts`; write, edit, and publish posts; only published posts appear in the app)
+- **Categories** — `https://manage.wix.com/dashboard/{metaSiteId}/blog/categories` (`Dashboard → Blog → Categories`)
+
+Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Visitor token persists across reload (no re-mint storm; same anonymous visitor)
+- [ ] Post feed lists live published posts, newest first, and paginates via `nextCursor`
+- [ ] Post detail loads by `slug` and renders real `contentText` (or rendered `richContent`)
+- [ ] `getPostBySlug` on a bad slug shows a not-found state (no invented post)
+- [ ] Cover images come from `post.media.wixMedia.image.url` (or richContent fallback) — no stock placeholders
+- [ ] Category and tag pages list the right posts via `queryPostsByCategory` / `queryPostsByTag`
+- [ ] Empty state shown when `getTotalPosts()` is 0
+- [ ] No mock posts, authors, comments, likes, or view counts anywhere
+- [ ] Told the user at least once that they can continue setting up their blog in the dashboard and provided deep links.

package/skills/wix-vibe-headless/references/blog/wix-blog.js

@@ -0,0 +1,217 @@
+import { wixApiRequest } from "./wix-client.js";
+
+/**
+ * Wix Blog Post — key fields.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/post-object.md
+ *
+ *   id {string}, title {string}, slug {string},
+ *   excerpt {string} — short summary ≤500 chars (use for cards),
+ *   firstPublishedDate {string} — ISO date, default sort key DESC,
+ *   pinned {boolean}, featured {boolean}, minutesToRead {number},
+ *   categoryIds {string[]}, tagIds {string[]}, hashtags {string[]},
+ *   media {object} — cover image at media.wixMedia.image { id, url, height, width, filename, altText? };
+ *     media.wixMedia.image.url is a ready-to-use https URL (returned by default, incl. the list query).
+ *     media.displayed / media.custom are booleans,
+ *   contentText {string} — plain text body (CONTENT_TEXT fieldset; getPostBySlug requests it),
+ *   richContent {object} — Ricos document (RICH_CONTENT fieldset; getPostBySlug requests it),
+ *   url {object} — { base, path } live post URL (URL fieldset; build full link as base+path)
+ * Available fieldsets: "URL" | "CONTENT_TEXT" | "RICH_CONTENT" | "METRICS" | "SEO"
+ *
+ * Category: { id, label, slug, description, postCount, displayPosition,
+ *   coverImage: { id, url, height, width, altText }, url: { base, path } }
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/category-object.md
+ *
+ * Tag: { id, label, slug, publishedPostCount, url: { base, path } }
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/tag-object.md
+ */
+
+const POST_LIST_FIELDSETS = ["URL"];
+const POST_FULL_FIELDSETS = ["URL", "CONTENT_TEXT", "RICH_CONTENT"];
+
+/**
+ * Query published posts (one page), newest first (pinned posts lead).
+ * Pass `nextCursor` from a previous call back as `cursor` to load the next page.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ posts: object[], nextCursor: string|null }>}
+ */
+export async function queryPosts({ limit = 100, cursor } = {}) {
+  const res = await wixApiRequest("/v3/posts/query", {
+    method: "POST",
+    body: {
+      fieldsets: POST_LIST_FIELDSETS,
+      query: {
+        cursorPaging: cursor ? { limit, cursor } : { limit },
+        sort: [{ fieldName: "firstPublishedDate", order: "DESC" }],
+      },
+    },
+  });
+  return {
+    posts: res?.posts ?? [],
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Fetch one post by its URL slug, with full content (contentText + richContent + url).
+ * Returns null if no post matches the slug — show a not-found state, never invent a post.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/get-post-by-slug.md
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getPostBySlug(slug) {
+  try {
+    const res = await wixApiRequest(`/v3/posts/slugs/${encodeURIComponent(slug)}`, {
+      method: "GET",
+      query: { fieldsets: POST_FULL_FIELDSETS },
+    });
+    return res?.post ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query published posts in a given category (one page), newest first.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md
+ * @param {string} categoryId  Category GUID (`category.id` from queryCategories / getCategoryBySlug).
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ posts: object[], nextCursor: string|null }>}
+ */
+export async function queryPostsByCategory(categoryId, { limit = 100, cursor } = {}) {
+  const res = await wixApiRequest("/v3/posts/query", {
+    method: "POST",
+    body: {
+      fieldsets: POST_LIST_FIELDSETS,
+      query: {
+        ...(cursor ? {} : { filter: { categoryIds: { $hasSome: [categoryId] } } }),
+        cursorPaging: cursor ? { limit, cursor } : { limit },
+        sort: [{ fieldName: "firstPublishedDate", order: "DESC" }],
+      },
+    },
+  });
+  return {
+    posts: res?.posts ?? [],
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Query published posts with a given tag (one page), newest first.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md
+ * @param {string} tagId  Tag GUID (`tag.id` from queryTags / getTagBySlug).
+ * @param {{ limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ posts: object[], nextCursor: string|null }>}
+ */
+export async function queryPostsByTag(tagId, { limit = 100, cursor } = {}) {
+  const res = await wixApiRequest("/v3/posts/query", {
+    method: "POST",
+    body: {
+      fieldsets: POST_LIST_FIELDSETS,
+      query: {
+        ...(cursor ? {} : { filter: { tagIds: { $hasSome: [tagId] } } }),
+        cursorPaging: cursor ? { limit, cursor } : { limit },
+        sort: [{ fieldName: "firstPublishedDate", order: "DESC" }],
+      },
+    },
+  });
+  return {
+    posts: res?.posts ?? [],
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Total number of published posts. Used for empty-state logic (0 → prompt the user to add
+ * posts in their Wix dashboard). Never invent posts.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/get-total-posts.md
+ * @returns {Promise<number>}
+ */
+export async function getTotalPosts() {
+  const res = await wixApiRequest("/blog/v2/stats/posts/total", { method: "GET" });
+  return res?.total ?? 0;
+}
+
+/**
+ * Query blog categories (one page), ordered by menu display position.
+ * Categories use offset paging (max 100 per page); most blogs have well under 100.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/query-categories.md
+ * @param {{ limit?: number, offset?: number }} [options]
+ * @returns {Promise<{ categories: object[], total: number }>}
+ */
+export async function queryCategories({ limit = 100, offset = 0 } = {}) {
+  const res = await wixApiRequest("/blog/v3/categories/query", {
+    method: "POST",
+    body: {
+      fieldsets: ["URL"],
+      query: {
+        paging: { limit, offset },
+        sort: [{ fieldName: "displayPosition", order: "ASC" }],
+      },
+    },
+  });
+  return {
+    categories: res?.categories ?? [],
+    total: res?.pagingMetadata?.total ?? (res?.categories?.length ?? 0),
+  };
+}
+
+/**
+ * Get one category by its URL slug. Returns null if not found.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/get-category-by-slug.md
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getCategoryBySlug(slug) {
+  try {
+    const res = await wixApiRequest(`/blog/v3/categories/slugs/${encodeURIComponent(slug)}`, {
+      method: "GET",
+      query: { fieldsets: ["URL"] },
+    });
+    return res?.category ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query blog tags (one page), most-used first.
+ * Tags use offset paging (max 100 per page).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/query-tags.md
+ * @param {{ limit?: number, offset?: number }} [options]
+ * @returns {Promise<{ tags: object[], total: number }>}
+ */
+export async function queryTags({ limit = 100, offset = 0 } = {}) {
+  const res = await wixApiRequest("/v3/tags/query", {
+    method: "POST",
+    body: {
+      fieldsets: ["URL"],
+      query: {
+        paging: { limit, offset },
+        sort: [{ fieldName: "publishedPostCount", order: "DESC" }],
+      },
+    },
+  });
+  return {
+    tags: res?.tags ?? [],
+    total: res?.pagingMetadata?.total ?? (res?.tags?.length ?? 0),
+  };
+}
+
+/**
+ * Get one tag by its URL slug. Returns null if not found.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/get-tag-by-slug.md
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getTagBySlug(slug) {
+  try {
+    const res = await wixApiRequest(`/v3/tags/slugs/${encodeURIComponent(slug)}`, {
+      method: "GET",
+      query: { fieldsets: ["URL"] },
+    });
+    return res?.tag ?? null;
+  } catch {
+    return null;
+  }
+}