@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/faq/project/src/wix/faq/faq-store.ts

@@ -0,0 +1,212 @@
+// FAQ page state — a module-scope store, deliberately NOT a React context and not a per-surface
+// factory: the category nav, the search box, and the accordion are separate Astro islands on one
+// page and must share one state (a context can't span islands; each island is its own React root).
+// Framework-free — consume it through useFaq() (hooks/), or subscribe directly from a static page,
+// Vue, or Svelte. Same shape as the storefront cart store: getState/subscribe + actions, emit after
+// every change.
+//
+// Seeding: every island receives the SSR data and calls seedFaq(); on the server every seed replaces
+// the state (a request renders its own props), in the browser the first seed wins and the rest are
+// no-ops, so the SSR HTML and the first client paint agree. A page with no SSR data (a SPA) fetches on
+// the first subscription.
+//
+// URL state (syncUrl, default on): `?category=<id>` and `#q-<slug>` are read once when the first
+// island subscribes and written with history.replaceState on every change — a visitor can copy the
+// address bar at any point and get back to the same view.
+import { fetchFaq } from "./faq";
+import { anchorId, findByAnchor, parseDeepLink, visibleQuestions } from "./faq-core";
+import type { FaqData, FaqQuestion } from "./types";
+
+export interface FaqState {
+  /** null while the first load is in flight and nothing was seeded — render skeletons, not an empty state. */
+  data: FaqData | null;
+  /** null = all categories (sections); an id = that category only. */
+  activeCategoryId: string | null;
+  query: string;
+  /** Expanded question ids; at most one when expandOnlyOne. */
+  expandedIds: string[];
+  /** Derived on every change: category filter, then search, in owner order — what the accordion renders. */
+  visible: FaqQuestion[];
+  /** visible.length while a query is typed, 0 otherwise — for the results announcement. */
+  resultsCount: number;
+  loading: boolean;
+  /** The last failed load's message — render it with a retry; a new load clears it. */
+  error: string | null;
+}
+
+export interface FaqStoreOptions {
+  /** SSR data — no client fetch happens when present. */
+  initialData?: FaqData;
+  /** The `?category=` the server saw (validated by the page); null/undefined = all. */
+  initialCategoryId?: string | null;
+  /** One open answer at a time (default true — the accordion behaviour). */
+  expandOnlyOne?: boolean;
+  /** Open the first visible answer on load (default false). */
+  openFirst?: boolean;
+  /** Read `?category` and `#q-…` on start and write them on change (default true). */
+  syncUrl?: boolean;
+}
+
+const EMPTY_DATA: FaqData = { categories: [], questions: [], truncated: false };
+
+let state: FaqState = {
+  data: null,
+  activeCategoryId: null,
+  query: "",
+  expandedIds: [],
+  visible: [],
+  resultsCount: 0,
+  loading: false,
+  error: null,
+};
+let expandOnlyOne = true;
+let openFirst = false;
+let syncUrl = true;
+let seeded = false;
+let started = false;
+let generation = 0; // bumped by every load; a response from an older generation is dropped
+const listeners = new Set<() => void>();
+
+const isBrowser = (): boolean => typeof window !== "undefined";
+
+function setState(patch: Partial<FaqState>): void {
+  const next = { ...state, ...patch };
+  next.visible = visibleQuestions(next.data, next.activeCategoryId, next.query);
+  next.resultsCount = next.query.trim() ? next.visible.length : 0;
+  state = next;
+  for (const l of listeners) l();
+}
+
+function writeUrl(): void {
+  if (!syncUrl || !isBrowser() || typeof history === "undefined") return;
+  const url = new URL(location.href);
+  if (state.activeCategoryId) url.searchParams.set("category", state.activeCategoryId);
+  else url.searchParams.delete("category");
+  const open = state.expandedIds.length === 1 ? state.visible.find((q) => q.id === state.expandedIds[0]) : undefined;
+  url.hash = open ? anchorId(open) : "";
+  try {
+    history.replaceState(history.state, "", url.pathname + url.search + url.hash);
+  } catch {
+    /* a sandboxed frame may refuse — the view is right, only the address bar lags */
+  }
+}
+
+/** `?category` and `#q-…` from the address bar → state: the anchor's question expands and its category is shown. */
+function applyDeepLink(): void {
+  if (!syncUrl || !isBrowser() || !state.data) return;
+  const { categoryId, anchor } = parseDeepLink(location.search, location.hash);
+  const patch: Partial<FaqState> = {};
+  if (categoryId && state.data.categories.some((c) => c.id === categoryId)) patch.activeCategoryId = categoryId;
+  const target = anchor ? findByAnchor(state.data.questions, anchor) : undefined;
+  if (target) {
+    patch.expandedIds = expandOnlyOne ? [target.id] : [...new Set([...state.expandedIds, target.id])];
+    // The deep link decides the category: a question hidden by the active filter switches the filter to its own.
+    const active = patch.activeCategoryId ?? state.activeCategoryId;
+    if (active && active !== target.categoryId) patch.activeCategoryId = target.categoryId;
+  }
+  if (Object.keys(patch).length) setState(patch);
+  if (target && typeof document !== "undefined") {
+    requestAnimationFrame(() => document.getElementById(anchorId(target))?.scrollIntoView({ block: "start" }));
+  }
+}
+
+function load(): void {
+  const id = ++generation;
+  setState({ loading: true, error: null });
+  fetchFaq()
+    .then((data) => {
+      if (generation !== id) return; // superseded — drop it
+      setState({ data, loading: false, expandedIds: openFirst ? firstId(data) : state.expandedIds });
+      applyDeepLink();
+    })
+    .catch((e) => {
+      if (generation !== id) return;
+      // An empty data set with an error: the accordion shows the error line and a retry, not skeletons forever.
+      setState({ data: state.data ?? EMPTY_DATA, loading: false, error: e instanceof Error ? e.message : String(e) });
+    });
+}
+
+function firstId(data: FaqData): string[] {
+  const first = visibleQuestions(data, state.activeCategoryId, state.query)[0];
+  return first ? [first.id] : [];
+}
+
+function start(): void {
+  if (started) return;
+  started = true;
+  if (state.data) applyDeepLink();
+  else load();
+}
+
+/**
+ * Hand the store its SSR data and options. Call from every island (useFaq does) — on the server each
+ * call replaces the state (one request, one data set); in the browser the first call seeds and later
+ * calls are no-ops, so hydration matches the server HTML.
+ */
+export function seedFaq(o: FaqStoreOptions = {}): void {
+  if (o.expandOnlyOne !== undefined) expandOnlyOne = o.expandOnlyOne;
+  if (o.openFirst !== undefined) openFirst = o.openFirst;
+  if (o.syncUrl !== undefined) syncUrl = o.syncUrl;
+  if (!o.initialData || (seeded && isBrowser())) return;
+  seeded = true;
+  const activeCategoryId =
+    o.initialCategoryId && o.initialData.categories.some((c) => c.id === o.initialCategoryId) ? o.initialCategoryId : null;
+  const data = o.initialData;
+  state = { ...state, data, activeCategoryId, loading: false, error: null };
+  state.visible = visibleQuestions(data, activeCategoryId, state.query);
+  state.resultsCount = 0;
+  state.expandedIds = openFirst ? firstId(data) : [];
+  // No emit: seeding happens during render, before any subscriber exists.
+}
+
+export function getFaqState(): FaqState {
+  return state;
+}
+
+/** The first browser subscriber starts the store: the deep link is applied, and unseeded data is fetched. */
+export function subscribeFaq(listener: () => void): () => void {
+  listeners.add(listener);
+  if (isBrowser()) start();
+  return () => listeners.delete(listener);
+}
+
+/** Show one category (null = all). Keeps the search query — the two compose. */
+export function selectCategory(id: string | null): void {
+  if (id === state.activeCategoryId) return;
+  setState({ activeCategoryId: id });
+  writeUrl();
+}
+
+/** Set the search query (debounce lives in the component). */
+export function setQuery(q: string): void {
+  if (q === state.query) return;
+  setState({ query: q });
+}
+
+export function toggleQuestion(id: string): void {
+  if (state.expandedIds.includes(id)) collapseQuestion(id);
+  else expandQuestion(id);
+}
+
+export function expandQuestion(id: string): void {
+  if (state.expandedIds.includes(id)) return;
+  setState({ expandedIds: expandOnlyOne ? [id] : [...state.expandedIds, id] });
+  writeUrl();
+}
+
+export function collapseQuestion(id: string): void {
+  if (!state.expandedIds.includes(id)) return;
+  setState({ expandedIds: state.expandedIds.filter((x) => x !== id) });
+  writeUrl();
+}
+
+export function collapseAll(): void {
+  if (!state.expandedIds.length) return;
+  setState({ expandedIds: [] });
+  writeUrl();
+}
+
+/** Re-run the load after an error. */
+export function retry(): void {
+  load();
+}

package/skills/wix-headless-templates/faq/project/src/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/project/src/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/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/faq/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/faq/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/faq/project/tsconfig.json

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

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

@@ -0,0 +1,71 @@
+// FAQ reads over REST — the twin of app/wix/faq/faq.ts. Same exports, same DTOs; the rules and mappers
+// come from faq-core (the SAME file the SDK transport uses, deployed flat next to this one by
+// deploy.mjs --stack static), so this file is only the transport: one fetch with a literal body per
+// function. Both endpoints are the FAQ app's READ scope; whether an anonymous VISITOR token may call
+// them is not documented — the reference shows an elevated example — so a 403 here means the site's
+// read needs a server-side path, not that the body is wrong (INSTRUCTIONS.md, verification caveats).
+// Porting: keep the paths, keep the bodies, port the core once.
+// 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 { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import {
+  FAQ_APP_ID,
+  assembleFaq,
+  categoriesQueryBody,
+  loadAllQuestions,
+  nextCursor,
+  questionByIdBody,
+  questionsQueryBody,
+  sortCategories,
+  toCategory,
+  toQuestion,
+  type Raw,
+} from "./faq-core.js";
+import type { FaqCategory, FaqData, FaqQuestion, FaqQuestionPage, FetchQuestionsOptions } from "./types.js";
+
+export { FAQ_APP_ID };
+
+const CATEGORIES_QUERY = "/faq/v2/categories/query";
+const QUESTIONS_QUERY = "/faq/v2/question-entries/query";
+
+/**
+ * All categories in owner order, one page (a site has few). `questionCount` is 0 here — fetchFaq fills it.
+ * POST /faq/v2/categories/query  { query: { sort: [{ fieldName: "sortOrder", order: "ASC" }], cursorPaging: { limit: 100 } } }
+ *   → { categories: [{ id, title, sortOrder, revision, createdDate, updatedDate }], pagingMetadata }
+ */
+export async function fetchCategories(): Promise<FaqCategory[]> {
+  const res = await wixRequest<Raw>(CATEGORIES_QUERY, { body: categoriesQueryBody() });
+  return sortCategories(((res?.categories ?? []) as Raw[]).map((c) => toCategory(c)));
+}
+
+/**
+ * One cursor page of questions, optionally one category's; `nextCursor` continues the same query —
+ * send it alone, the filter and sort ride inside it.
+ * POST /faq/v2/question-entries/query  { query: { filter?: { categoryId: { $eq } }, sort, cursorPaging: { limit } }, contentFormat: "RICH_CONTENT", fieldSet: ["SHARE_LINKS"] }  — first page
+ * POST /faq/v2/question-entries/query  { query: { cursorPaging: { limit, cursor } }, contentFormat, fieldSet }                                                        — later pages
+ *   → { questionEntries: [{ id, question, richContent | plainText | draftjs, categoryId, sortOrder, slug, shareLink, labels }], pagingMetadata: { count, cursors: { next, prev }, hasNext } }
+ */
+export async function fetchQuestions(o: FetchQuestionsOptions = {}): Promise<FaqQuestionPage> {
+  const res = await wixRequest<Raw>(QUESTIONS_QUERY, { body: questionsQueryBody(o) });
+  return {
+    questions: ((res?.questionEntries ?? []) as Raw[]).map((r) => toQuestion(r, imgSrc)),
+    nextCursor: nextCursor(res?.pagingMetadata),
+  };
+}
+
+/** Everything the FAQ page needs: categories (counted) + every question (paged until done or MAX_QUESTIONS). */
+export async function fetchFaq(): Promise<FaqData> {
+  const [cats, { questions, truncated }] = await Promise.all([fetchCategories(), loadAllQuestions(fetchQuestions)]);
+  return assembleFaq(cats, questions, truncated);
+}
+
+/**
+ * One question by id — the same query read as the page, so one permission covers both. Null when missing.
+ * POST /faq/v2/question-entries/query  { query: { filter: { _id: { $eq } }, cursorPaging: { limit: 1 } }, contentFormat, fieldSet }
+ */
+export async function fetchQuestionById(id: string): Promise<FaqQuestion | null> {
+  const res = await wixRequest<Raw>(QUESTIONS_QUERY, { body: questionByIdBody(id) });
+  const raw: Raw | undefined = res?.questionEntries?.[0];
+  return raw ? toQuestion(raw, imgSrc) : null;
+}