1// FAQ seed — a BUILD-TIME script, never shipped in the app. Run from the project root (where
2// wix.config.json lives) with a plan file:
3//
4//   node <SKILL_ROOT>/templates/faq/seed/seed-faq.mjs plan.json
5//
6// It mints its own site token via the Wix CLI, installs the Wix FAQ app if needed, reads what the
7// site already holds, creates the missing categories (idempotent by title, with a fresh-install
8// verify-retry), creates the missing questions one at a time (idempotent by category + question text;
9// the API has no bulk create), and verifies by re-querying. Prints a JSON result to stdout.
10//
11// Plan shape (see SEED.md):
12//   { "categories": [{ "title", "questions": [{ "question", "answer", "labels"? }] }] }
13//   answer: a string (plain text) | [blocks] (Ricos richContent) | { nodes: [...] } (a pre-built Ricos document, verbatim)

seed-faq.mjs on GitHub

// 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 { isMain } from "../../shared/seed/main.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/api-reference/business-management/faq-app";

/** 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/api-reference/business-management/faq-app/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/api-reference/business-management/faq-app/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/api-reference/business-management/faq-app/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/api-reference/business-management/faq-app/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 = isMain(import.meta.url);

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);

});

}