@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/faq/app/wix/faq/faq.ts

@@ -0,0 +1,72 @@
+// FAQ reads (Wix FAQ app: Categories V2 + Question Entries V2) over the SDK — the only file that
+// touches raw FAQ entities on this transport. Everything it returns is a plain DTO from ./types. The
+// rules and mappers live in ./faq-core (shared with the REST twin in templates/faq/rest/); this file
+// is the transport only. Copy as-is; extend by adding functions, not by editing these. The vertical
+// is read-only: authoring stays in the dashboard.
+// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/category-v2/query-categories.md
+// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/question-entry-v2/query-question-entries.md
+import { category as categoryModule, questionEntry as questionModule } from "@wix/faq";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import {
+  CONTENT_FORMAT,
+  FAQ_APP_ID,
+  FIELD_SET,
+  PAGE_LIMIT,
+  assembleFaq,
+  loadAllQuestions,
+  sortCategories,
+  toCategory,
+  toQuestion,
+  type Raw,
+} from "./faq-core";
+import type { FaqCategory, FaqData, FaqQuestion, FaqQuestionPage, FetchQuestionsOptions } from "./types";
+
+export { FAQ_APP_ID };
+
+const categories = wixModule(categoryModule);
+const questions = wixModule(questionModule);
+
+/** All categories in owner order (a site has few; one page of 100 is the whole list). `questionCount` is 0 here — fetchFaq fills it. */
+export async function fetchCategories(): Promise<FaqCategory[]> {
+  const res = await categories.queryCategories().ascending("sortOrder").limit(PAGE_LIMIT).find();
+  return sortCategories((res.items ?? []).map((c: Raw) => toCategory(c)));
+}
+
+/**
+ * One cursor page of questions, optionally one category's, in owner order, with the Ricos answer and
+ * the share link. The builder spells faq-core's questionsQueryBody: filter + sort on the first page,
+ * the cursor alone after (a cursor encodes the original filter+sort).
+ */
+export async function fetchQuestions(o: FetchQuestionsOptions = {}): Promise<FaqQuestionPage> {
+  const { categoryId = null, limit = PAGE_LIMIT, cursor = null } = o;
+  let q = questions.queryQuestionEntries({ contentFormat: CONTENT_FORMAT, fieldSet: [...FIELD_SET] });
+  if (cursor) {
+    q = q.skipTo(cursor);
+  } else {
+    if (categoryId) q = q.eq("categoryId", categoryId);
+    q = q.ascending("sortOrder");
+  }
+  const res = await q.limit(Math.min(Math.max(1, limit), PAGE_LIMIT)).find();
+  return {
+    questions: (res.items ?? []).map((r: Raw) => toQuestion(r, imgSrc)),
+    nextCursor: res.hasNext() ? (res.cursors?.next ?? null) : null,
+  };
+}
+
+/** Everything the FAQ page needs: categories (counted) + every question (paged until done or MAX_QUESTIONS). */
+export async function fetchFaq(): Promise<FaqData> {
+  const [cats, { questions: all, truncated }] = await Promise.all([fetchCategories(), loadAllQuestions(fetchQuestions)]);
+  return assembleFaq(cats, all, truncated);
+}
+
+/** One question by id (a redirect page, a widget) — the same query read as the page, so one permission covers both. Null when missing. */
+export async function fetchQuestionById(id: string): Promise<FaqQuestion | null> {
+  const res = await questions
+    .queryQuestionEntries({ contentFormat: CONTENT_FORMAT, fieldSet: [...FIELD_SET] })
+    .eq("_id", id)
+    .limit(1)
+    .find();
+  const raw = res.items?.[0];
+  return raw ? toQuestion(raw as Raw, imgSrc) : null;
+}

package/skills/wix-headless-templates/faq/app/wix/faq/types.ts

@@ -0,0 +1,63 @@
+// FAQ DTOs — the serializable shapes every hook, component, and page consumes. Plain JSON: safe as
+// Astro island props or across server/client boundaries. Answers arrive as HTML the core produced
+// from the API's rich content (sanitized: text escaped, only http(s) links, no scripts or styles),
+// plus a plain-text twin for search, snippets, and structured data. No dates: the API's
+// _createdDate/_updatedDate are not visitor-facing and are dropped in the data layer.
+
+export interface FaqCategory {
+  id: string;
+  /** Category title as the owner typed it (the API has no description or visibility on a category). */
+  title: string;
+  /** The API's sortOrder — lower first; null sorts after the numbered ones, stable by title. */
+  sortOrder: number | null;
+  /** Filled by the core from the loaded questions — hide empty categories with it. */
+  questionCount: number;
+}
+
+export interface FaqQuestion {
+  id: string;
+  /** The API's readonly slug, generated from the question text ("" when absent). The anchor id is `q-<slug || id>`. */
+  slug: string;
+  question: string;
+  /** Sanitized HTML for the answer body — render with set:html / dangerouslySetInnerHTML on a wrapper you control. */
+  answerHtml: string;
+  /** Plain text of the answer — search, meta descriptions, JSON-LD. */
+  answerText: string;
+  categoryId: string;
+  /** Order within the category — lower first; null sorts last. */
+  sortOrder: number | null;
+  /** Wix's own share link (points at the Wix-hosted FAQ widget, "" when the query did not ask for it). Our deep link is `faqDeepLink()`. */
+  shareLink: string;
+  /** Label titles — not shown to visitors; grouping for chatbots and integrations. */
+  labels: string[];
+}
+
+/** One category with its questions in display order. */
+export interface FaqSection {
+  category: FaqCategory;
+  questions: FaqQuestion[];
+}
+
+/** Everything the FAQ page renders from — the unit the SSR fetch hands the islands. */
+export interface FaqData {
+  categories: FaqCategory[];
+  questions: FaqQuestion[];
+  /** True when the loader hit MAX_QUESTIONS before the site's last page (more questions exist). */
+  truncated: boolean;
+}
+
+/** One cursor page of questions — the paged path for a very large FAQ. */
+export interface FaqQuestionPage {
+  questions: FaqQuestion[];
+  /** Pass back as `cursor` for the next page; null → no more. */
+  nextCursor: string | null;
+}
+
+export interface FetchQuestionsOptions {
+  /** First page only — the cursor carries the filter on later pages. */
+  categoryId?: string | null;
+  /** Page size (default and maximum 100 — the API's CursorPaging.limit cap). */
+  limit?: number;
+  /** `nextCursor` from a previous page. */
+  cursor?: string | null;
+}

package/skills/wix-headless-templates/faq/app-astro/layouts/SiteLayout.astro

@@ -0,0 +1,40 @@
+---
+// The site chrome for every FAQ page — THIS file (header/footer/nav) plus the @theme token block in
+// src/styles/global.css are what you brand. Keep the <slot name="seo-tags" /> in <head> (the FAQ page
+// puts its JSON-LD there) and the global.css import. (If another vertical is also deployed, its
+// SiteLayout won; merge an FAQ nav link there instead.)
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <a href="/faq" class="text-foreground no-underline transition-colors hover:text-muted-foreground">FAQ</a>
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+  </body>
+</html>

package/skills/wix-headless-templates/faq/app-astro/pages/faq.astro

@@ -0,0 +1,39 @@
+---
+// FAQ page — data fetched SERVER-SIDE (SEO: every question and answer is in the HTML, collapsed) and
+// handed to the islands as DTO props. Keep this frontmatter (the fetch, the JSON-LD, the category
+// pre-selection); swap the island imports to YOUR components. The three islands share one module-scope
+// store, so they can stay separate or be merged into one — your call.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import FaqSearch from "../components/faq/FaqSearch";
+import FaqCategoryNav from "../components/faq/FaqCategoryNav";
+import FaqAccordion from "../components/faq/FaqAccordion";
+import { fetchFaq } from "../wix/faq/faq";
+import { faqJsonLd, parseDeepLink } from "../wix/faq/faq-core";
+import type { FaqData } from "../wix/faq/types";
+
+let data: FaqData = { categories: [], questions: [], truncated: false };
+try {
+  data = await fetchFaq();
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the islands render the empty state instead.
+}
+
+// Behind Wix's proxy the request URL is internal — the public page URL arrives on x-wix-forwarded-url.
+const forwarded = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwarded && URL.canParse(forwarded) && /^https?:$/.test(new URL(forwarded).protocol) ? forwarded : Astro.url.href;
+// `?category=` is server-visible (pre-select the nav so SSR and the first paint agree); `#q-…` is not — the store applies it in the browser.
+const { categoryId } = parseDeepLink(Astro.url.search, "");
+const initialCategoryId = categoryId && data.categories.some((c) => c.id === categoryId) ? categoryId : null;
+// The whole FAQ, not the filtered view: every marked-up answer is on the page (collapsed panels are still in the DOM).
+const jsonLd = JSON.stringify(faqJsonLd(data.questions, pageUrl.split("#")[0].split("?")[0])).replace(/</g, "\\u003c");
+const description = data.questions.slice(0, 3).map((q) => q.question).join(" · ");
+---
+
+<SiteLayout title="FAQ" description={description}>
+  <script type="application/ld+json" is:inline slot="seo-tags" set:html={jsonLd} />
+  <h1 class="mb-8 text-3xl font-semibold tracking-tight">Frequently asked questions</h1>
+  <FaqSearch client:load initialData={data} initialCategoryId={initialCategoryId} />
+  <FaqCategoryNav client:load initialData={data} initialCategoryId={initialCategoryId} />
+  <FaqAccordion client:load initialData={data} initialCategoryId={initialCategoryId} />
+</SiteLayout>

package/skills/wix-headless-templates/faq/project/README.md

@@ -0,0 +1,15 @@
+# Wix Astro Blank Template
+
+**[Live demo](https://h6s-1a31f9730cd85b-headlessstack.wix-site-host.com)**
+
+Our Astro templates are still in development and subject to change.
+
+To use a template, follow the [Wix CLI for Headless Quick Start](https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-with-the-wix-cli), and select the desired template during the setup process.
+
+## Need help?
+
+For documentation and support, check out:
+
+- [Wix Headless Documentation](https://dev.wix.com/docs/go-headless)
+- [Wix SDK Documentation](https://dev.wix.com/docs/sdk)
+- [Community on Discord](https://discord.gg/n6TBrSnYTp)

package/skills/wix-headless-templates/faq/project/astro.config.mjs

@@ -0,0 +1,22 @@
+import tailwindcss from "@tailwindcss/vite";
+// @ts-check
+import { defineConfig } from 'astro/config';
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  vite: { plugins: [tailwindcss()] },
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+
+  image: {
+    domains: ["static.wixstatic.com"],
+  },
+
+  output: "server",
+});