@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/faq/seed/SEED.md

@@ -0,0 +1,104 @@
+# FAQ — seeding
+
+Seed by **running `seed-faq.mjs` with a plan file** — don't hand-write the REST calls. The script
+mints its own site token via the Wix CLI (logged-in session + `wix.config.json` required), installs
+the Wix FAQ app if needed, reads what the site already holds, and creates everything in order:
+categories first (idempotent by title, with a fresh-install verify-retry), then questions (idempotent
+by category + question text, one call each — the API has no bulk create), then a re-query that counts
+what persisted.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/faq/seed/seed-faq.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 2–4 categories with 2–4 questions
+each** (the seed shows the shape; the owner writes the rest in the dashboard). Group by how a visitor
+thinks ("Orders & Shipping", "Returns", "Sizing"), write answers as `blocks` where the brief has
+structure (steps, options), as a plain string otherwise. No images: an FAQ without pictures does not
+look broken.
+
+```json
+{
+  "categories": [
+    {
+      "title": "Orders & Shipping",
+      "questions": [
+        { "question": "How long does delivery take?",
+          "answer": "Orders ship within 2 business days. Delivery takes 3-5 days in the EU and 7-10 days elsewhere." },
+        { "question": "Can I change my order after placing it?",
+          "answer": [
+            { "type": "paragraph", "text": "Yes, within 12 hours of ordering." },
+            { "type": "bulleted", "items": ["Reply to your confirmation email", "Or call the studio during opening hours"] }
+          ],
+          "labels": ["support"] }
+      ]
+    },
+    {
+      "title": "Returns",
+      "questions": [
+        { "question": "What is your return policy?", "answer": "14 days, unused, in the original packaging." }
+      ]
+    }
+  ]
+}
+```
+
+- `categories[].title` — the category as visitors see it (1–500 chars). Plan order is display order:
+  new categories get `sortOrder` after the site's existing ones, in steps of 10.
+- `questions[].question` — the question text (≤1000 chars). Plan order within a category is display
+  order (`sortOrder` in steps of 10, after that category's existing questions).
+- `answer` — a **string** (stored as `plainText`), an **array of blocks** (stored as Ricos
+  `richContent`: `{type:"heading",text,level?}` · `{type:"paragraph",text}` · `{type:"quote",text}` ·
+  `{type:"bulleted"|"ordered",items:[…]}`), or a pre-built Ricos `{ "nodes": [...] }` document used
+  verbatim for node types the blocks don't cover. Exactly one format is sent per question.
+- `labels` — optional strings; not visible to visitors (grouping for chatbots and integrations).
+- Idempotent by text: a category whose title already exists is reused; a question whose text already
+  exists in that category is skipped (`skipped` in the result). Nothing is updated or deleted.
+
+**Seeding is additive — the seed never deletes or overwrites anything on the site, and neither do
+you.** There is no cleanup flag and no cleanup step. A fresh FAQ install comes with Wix's own sample
+categories and questions ("General", "Setting up FAQs", …); the live page shows them above the
+owner's, so they are never silent: the result's `preexisting[]` lists every category the plan did not
+name with its question count, and the closing message names them with the dashboard link so the owner
+removes them there if they want to.
+
+The result lists every category with its id, whether this run created it, and how many questions it
+holds after the run; `created[]` carries each new question's `id` and `slug` (the anchor the page
+uses is `#q-<slug>`); `failed[]` (exit code 1 when non-empty) carries the API message per question.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For an FAQ, each question/answer
+pair the user hands over is one `questions[]` entry: the question verbatim as `question`, the answer
+as a string, or as `blocks` (one block per paragraph or list) when the source has structure. A heading
+above a group of questions becomes that group's category `title`; a source with no headings is one
+category named after the business's subject. A question with no answer is a question for the user.
+
+## Escape hatch — individual functions
+`setupFaq` composes exported steps — `installFaqApp`, `readCategories`, `readQuestions`,
+`ensureCategories`, `createQuestion`, `mkRichContent`, plus `makeCtx()` — import them only for a
+partial re-seed.
+
+## Verification caveats
+
+The FAQ API's reference pages exist (`dev.wix.com/docs/rest/business-management/faq-app/…`) and
+every path, verb, and body here follows them; the following were not checked on a live site:
+
+- Whether the create endpoints answer 409 on a duplicate title/question or create a second copy. The
+  seed compares text before creating, so a duplicate only arises from a race.
+- Whether the fresh-install provisioning window (a create that answers 200 but does not persist) exists
+  for FAQ as it does for Blog; the verify-retry covers it either way.
+- Whether install creates Wix's sample content (the SDK carries a "default content" job type). The seed
+  reads before writing and reports what it found.
+- The reference's sample flow mentions a question `status` of `PUBLISHED`; the entity has no `status`
+  field in the SDK or the reference schema, so the seed sends none. If a question is created but does
+  not show on the page, look for a visibility control in the FAQ dashboard.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; every call the script
+makes carries a `docs:` line with its reference page.
+Endpoints used: `POST /faq/v2/categories` (Create Category), `POST /faq/v2/categories/query`
+(Query Categories), `POST /faq/v2/question-entries` (Create Question Entry),
+`POST /faq/v2/question-entries/query` (Query Question Entries — the read-before and verify steps),
+`POST /apps-installer-service/v1/app-instance/install` (Install App).

package/skills/wix-headless-templates/faq/seed/read-site.mjs

@@ -0,0 +1,23 @@
+// What the FAQ holds: categories and questions.
+//   node <SKILL_ROOT>/templates/faq/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const FAQ_APP_ID = "14c92d28-031e-7910-c9a8-a670011e062d";
+const D = "https://dev.wix.com/docs/rest/business-management/faq-app/faq";
+
+await runReader({
+  vertical: "faq",
+  appId: FAQ_APP_ID,
+  async read(api, { limit }) {
+    const cats = await api.call({ path: "/faq/v2/categories/query", body: { query: { sort: [{ fieldName: "sortOrder", order: "ASC" }], cursorPaging: { limit: 100 } } }, docs: `${D}/category-v2/query-categories` });
+    const qs = await api.call({ path: "/faq/v2/question-entries/query", body: { query: { sort: [{ fieldName: "sortOrder", order: "ASC" }], cursorPaging: { limit } }, contentFormat: "PLAIN_TEXT" }, docs: `${D}/question-entry-v2/query-question-entries` });
+    const questions = qs.questionEntries ?? [];
+    return {
+      categoryCount: (cats.categories ?? []).length,
+      categories: (cats.categories ?? []).map((c) => ({ id: c.id, title: c.title, sortOrder: c.sortOrder ?? null })),
+      // The query has no total: the count is exact only when this page is the last one.
+      questionCount: qs.pagingMetadata?.hasNext ? null : questions.length,
+      questions: questions.map((q) => ({ question: q.question, categoryId: q.categoryId, sortOrder: q.sortOrder ?? null, slug: q.slug ?? null, hasAnswer: !!(q.plainText || q.richContent || q.draftjs) })),
+    };
+  },
+});

package/skills/wix-headless-templates/faq/seed/seed-faq.mjs

@@ -0,0 +1,302 @@
+// FAQ seed — a BUILD-TIME script, never shipped in the app. Run from the project root (where
+// wix.config.json lives) with a plan file:
+//
+//   node <SKILL_ROOT>/templates/faq/seed/seed-faq.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix FAQ app if needed, reads what the
+// site already holds, creates the missing categories (idempotent by title, with a fresh-install
+// verify-retry), creates the missing questions one at a time (idempotent by category + question text;
+// the API has no bulk create), and verifies by re-querying. Prints a JSON result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "categories": [{ "title", "questions": [{ "question", "answer", "labels"? }] }] }
+//   answer: a string (plain text) | [blocks] (Ricos richContent) | { nodes: [...] } (a pre-built Ricos document, verbatim)
+//   blocks: { type:"heading", text, level? } | { type:"paragraph", text }
+//     | { type:"quote", text } | { type:"bulleted"|"ordered", items:[text,…] }
+//
+// Seeding is ADDITIVE — never deletes or overwrites existing content. A fresh FAQ install may carry
+// Wix's own sample categories/questions; removing them is the owner's call, not this script's.
+// Unexpected shapes → read the live API reference; every call below carries a docs: line with its
+// reference page.
+import { seedSiteId } from "../../shared/seed/site-context.mjs";
+import { wixToken } from "../../shared/seed/wix-cli.mjs";
+import { readFileSync } from "node:fs";
+
+const API = "https://www.wixapis.com";
+const FAQ_APP_ID = "14c92d28-031e-7910-c9a8-a670011e062d";
+const D = "https://dev.wix.com/docs/rest/business-management/faq-app/faq";
+/** The API's page cap (CursorPaging.limit max 100). */
+const PAGE_LIMIT = 100;
+/** sortOrder step — increments of 10 leave room to insert between items later (the reference's own tip). */
+const SORT_STEP = 10;
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  // The content site: the config's site, or the parent on a migration preview (site-context.mjs stops
+  // a seed there unless --allow-parent is passed after the user confirmed).
+  const siteId = seedSiteId({ cwd, argv: process.argv });
+  const token = wixToken(siteId, cwd);
+  return { token, siteId };
+}
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  const res = await fetch(API + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  return json;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// A fresh site's FAQ backend can transiently fail its FIRST calls while provisioning (403, 404 before
+// the app instance exists, 5xx). Retry the same body ONCE after ~3s, then fail loud (never loop).
+async function reqRetryOnce(ctx, path, opts) {
+  try {
+    return await req(ctx, path, opts);
+  } catch (e) {
+    if (/-> (403|404|5\d\d):/.test(String(e.message))) {
+      await sleep(3000);
+      return req(ctx, path, opts);
+    }
+    throw e;
+  }
+}
+
+// ---- Ricos richContent builder (the blog seed's, copied) ------------------------------------------
+// Rules baked in: TEXT is always a leaf inside a container; BLOCKQUOTE / LIST_ITEM wrap a PARAGRAPH;
+// BULLETED_LIST / ORDERED_LIST wrap LIST_ITEM -> PARAGRAPH -> TEXT; every container node gets a unique
+// id, TEXT leaves use id "". For node types not covered here pass a pre-built `answer: { nodes }`.
+const mkText = (text) => ({ type: "TEXT", id: "", nodes: [], textData: { text: text || "", decorations: [] } });
+const mkParagraph = (id, text) => ({ type: "PARAGRAPH", id, nodes: [mkText(text)], paragraphData: {} });
+
+export function mkRichContent(blocks = [], idx = 0) {
+  let n = 0;
+  const id = () => `q${idx}-n${n++}`;
+  const nodes = [];
+  for (const b of blocks) {
+    switch (b.type) {
+      case "heading":
+        nodes.push({ type: "HEADING", id: id(), nodes: [mkText(b.text)], headingData: { level: b.level ?? 2 } });
+        break;
+      case "quote":
+        nodes.push({ type: "BLOCKQUOTE", id: id(), nodes: [mkParagraph(id(), b.text)], blockquoteData: { indentation: 1 } });
+        break;
+      case "bulleted":
+      case "ordered": {
+        const listType = b.type === "bulleted" ? "BULLETED_LIST" : "ORDERED_LIST";
+        nodes.push({
+          type: listType, id: id(),
+          nodes: (b.items ?? []).map((item) => ({ type: "LIST_ITEM", id: id(), nodes: [mkParagraph(id(), item)] })),
+        });
+        break;
+      }
+      case "paragraph":
+      default:
+        nodes.push(mkParagraph(id(), b.text));
+    }
+  }
+  return { nodes };
+}
+
+// A plan answer → the entity's answer field. The answer is a oneof: exactly one of plainText |
+// richContent | draftjs is sent.
+function answerField(answer, idx) {
+  if (typeof answer === "string") return { plainText: answer };
+  if (Array.isArray(answer)) return { richContent: mkRichContent(answer, idx) };
+  if (answer && typeof answer === "object" && Array.isArray(answer.nodes)) return { richContent: answer };
+  throw new Error(`question ${idx}: "answer" must be a string, an array of blocks, or a Ricos { nodes } object`);
+}
+
+const rawId = (x) => x?.id ?? x?._id ?? null;
+const norm = (s) => String(s ?? "").trim().toLowerCase().replace(/\s+/g, " ");
+
+// ---- operations ----------------------------------------------------------------------------------
+
+// Idempotent — re-installing an installed app is fine.
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installFaqApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: FAQ_APP_ID, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+// Existing categories, straight from the query (the source of truth for what persisted).
+// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/category-v2/query-categories.md
+export async function readCategories(ctx) {
+  const r = await reqRetryOnce(ctx, "/faq/v2/categories/query", { body: { query: { cursorPaging: { limit: PAGE_LIMIT } } } });
+  return (r.categories ?? []).map((c) => ({ id: rawId(c), title: c.title ?? "", sortOrder: typeof c.sortOrder === "number" ? c.sortOrder : null }));
+}
+
+// Every existing question (paged by cursor; PLAIN_TEXT keeps the read light — only the text is compared).
+// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/question-entry-v2/query-question-entries.md
+export async function readQuestions(ctx) {
+  const out = [];
+  let cursor = null;
+  do {
+    const query = cursor ? { cursorPaging: { limit: PAGE_LIMIT, cursor } } : { cursorPaging: { limit: PAGE_LIMIT } };
+    // No contentFormat: the default read. Asking for PLAIN_TEXT made entries stored as rich content
+    // drop out of the page while the platform converted them, so a re-run did not see them and created
+    // them again (run 153). Only `question`, `categoryId` and `sortOrder` are read here.
+    const r = await reqRetryOnce(ctx, "/faq/v2/question-entries/query", { body: { query } });
+    for (const q of r.questionEntries ?? []) out.push({ id: rawId(q), question: q.question ?? "", categoryId: q.categoryId ?? "", sortOrder: q.sortOrder ?? null });
+    cursor = r.pagingMetadata?.hasNext ? (r.pagingMetadata?.cursors?.next ?? null) : null;
+  } while (cursor);
+  return out;
+}
+
+// Create the missing categories resiliently. TWO hazards this absorbs:
+//  1. Fresh-install provisioning window — a create can answer 200 with an id that does not persist.
+//     So the create response is never trusted — re-query, treat the query as truth, re-create what's
+//     still missing until it sticks (8 attempts, 1.5 s apart).
+//  2. Idempotency — an already-present title (a partial-failure re-run, Wix's sample content) is kept.
+// New categories append after the existing ones: sortOrder = max(existing) + 10, +20, …
+// Body is NESTED: { category: { title, sortOrder } } → { category: { id, … } }.
+// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/category-v2/create-category.md
+export async function ensureCategories(ctx, titles) {
+  let existing = await readCategories(ctx);
+  const byTitle = () => new Map(existing.map((c) => [norm(c.title), c]));
+  const created = new Set();
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const map = byTitle();
+    const missing = titles.filter((t) => !map.has(norm(t)));
+    if (!missing.length) break;
+    if (attempt) await sleep(1500); // backoff only between retries — the happy path pays nothing
+    // Never 0: a zero sortOrder is dropped on the wire (the proto default) and the category then sorts as unnumbered.
+    const base = Math.max(0, ...existing.map((c) => c.sortOrder ?? 0));
+    for (const [i, title] of missing.entries()) {
+      try {
+        await req(ctx, "/faq/v2/categories", { body: { category: { title, sortOrder: base + SORT_STEP * (i + 1) } } });
+        created.add(norm(title));
+      } catch (e) {
+        if (!String(e.message).includes("-> 409")) throw e; // 409 = raced, already there
+      }
+    }
+    existing = await readCategories(ctx);
+  }
+  const map = byTitle();
+  return titles.map((title) => {
+    const c = map.get(norm(title));
+    if (!c?.id) throw new Error(`category "${title}" did not persist after 8 attempts — retry the seed`);
+    return { id: c.id, title, created: created.has(norm(title)) };
+  });
+}
+
+// One question, one call (the SDK exports no bulk create). Body is NESTED: { questionEntry: { … } } →
+// { questionEntry: { id, slug, … } }. `question` and `categoryId` are required; the answer is a oneof.
+// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/question-entry-v2/create-question-entry.md
+export async function createQuestion(ctx, { question, categoryId, sortOrder, labels, answer }, idx) {
+  const body = {
+    questionEntry: {
+      question,
+      categoryId,
+      sortOrder,
+      ...(labels?.length ? { labels: labels.map((title, i) => ({ title, sortOrder: i })) } : {}),
+      ...answerField(answer, idx),
+    },
+  };
+  const r = await req(ctx, "/faq/v2/question-entries", { body });
+  return { id: rawId(r.questionEntry), slug: r.questionEntry?.slug ?? null };
+}
+
+/**
+ * ONE-CALL seed: install → read existing → categories (idempotent by title) → questions (idempotent
+ * by category + question text, one at a time, in plan order) → verify by re-query. The default path.
+ */
+export async function setupFaq(ctx, { categories = [] } = {}) {
+  if (!categories.length) throw new Error("plan.categories is empty — nothing to seed");
+  await installFaqApp(ctx);
+  await sleep(3000); // let a fresh FAQ install settle so the first writes stick (ensureCategories verifies anyway)
+
+  // What the site held BEFORE this seed and the plan does not name: on a fresh install that is Wix's
+  // sample content ("General", "Setting up FAQs", …), which the live page shows above the owner's
+  // questions. Reported, never touched: this seed deletes nothing on a site, ever. The owner removes
+  // what they do not want in the dashboard; the closing message tells them it is there and where.
+  const planTitles = new Set(categories.map((c) => norm(c.title)));
+  const preexisting = (await readCategories(ctx)).filter((c) => !planTitles.has(norm(c.title)));
+  const preexistingQuestions = preexisting.length ? (await readQuestions(ctx)).filter((q) => preexisting.some((c) => c.id === q.categoryId)) : [];
+
+  const cats = await ensureCategories(ctx, categories.map((c) => c.title));
+  const catId = new Map(cats.map((c) => [norm(c.title), c.id]));
+
+  const existing = await readQuestions(ctx);
+  const seen = new Set(existing.map((q) => `${q.categoryId}\n${norm(q.question)}`));
+  const maxSort = new Map();
+  for (const q of existing) if (typeof q.sortOrder === "number") maxSort.set(q.categoryId, Math.max(maxSort.get(q.categoryId) ?? 0, q.sortOrder));
+
+  const created = [];
+  const skipped = [];
+  const failed = [];
+  let idx = 0;
+  for (const c of categories) {
+    const categoryId = catId.get(norm(c.title));
+    let next = Math.max(0, maxSort.get(categoryId) ?? 0) + SORT_STEP; // never 0 (dropped on the wire)
+    for (const q of c.questions ?? []) {
+      idx++;
+      const key = `${categoryId}\n${norm(q.question)}`;
+      if (seen.has(key)) { skipped.push({ category: c.title, question: q.question }); continue; }
+      try {
+        const r = await createQuestion(ctx, { question: q.question, categoryId, sortOrder: next, labels: q.labels, answer: q.answer }, idx);
+        created.push({ category: c.title, question: q.question, id: r.id, slug: r.slug });
+        seen.add(key);
+        next += SORT_STEP;
+      } catch (e) {
+        if (String(e.message).includes("-> 409")) { skipped.push({ category: c.title, question: q.question }); continue; }
+        failed.push({ category: c.title, question: q.question, error: String(e.message).slice(0, 300) });
+      }
+    }
+  }
+
+  // A 200 on create does NOT prove persistence — re-query and count per category.
+  const after = await readQuestions(ctx);
+  const counts = new Map();
+  for (const q of after) counts.set(q.categoryId, (counts.get(q.categoryId) ?? 0) + 1);
+  return {
+    categories: cats.map((c) => ({ id: c.id, title: c.title, created: c.created, questions: counts.get(c.id) ?? 0 })),
+    questionsCreated: created.length,
+    questionsSkipped: skipped.length,
+    questionsFailed: failed.length,
+    created,
+    skipped,
+    failed,
+    questionsOnSite: after.length,
+    // Content the plan did not name (Wix's install samples on a fresh site, or the owner's own on an
+    // existing one): the closing message names what is on the page and where the owner removes it.
+    preexisting: preexisting.map((c) => ({ id: c.id, title: c.title, questions: preexistingQuestions.filter((q) => q.categoryId === c.id).length })),
+    dashboardUrl: `https://manage.wix.com/dashboard/${ctx.siteId}/app/${FAQ_APP_ID}`,
+    docs: [`${D}/category-v2/create-category`, `${D}/question-entry-v2/create-question-entry`, `${D}/question-entry-v2/query-question-entries`],
+  };
+}
+
+// ---- CLI entry ----------------------------------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const planPath = process.argv[2];
+  if (!planPath) {
+    console.error("usage: node seed-faq.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupFaq(ctx, plan)
+    .then((result) => {
+      console.log(JSON.stringify(result, null, 2));
+      if (result.questionsFailed) process.exit(1);
+    })
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}