@wix/agent-skills 1.20.0 → 1.21.0

package/skills/wix-headless-fast/references/shared/app/wix/sdk.ts

@@ -15,6 +15,7 @@
 // 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";
 
@@ -66,6 +67,18 @@ export function wixModule<T>(module: T): 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;

package/skills/wix-headless-fast/references/shared/rest/client.ts

@@ -0,0 +1,155 @@
+// The one auth seam for every Wix REST call — the twin of app/wix/sdk.ts, over fetch. No
+// dependencies. deploy.mjs --stack static copies it flat into js/wix/ next to the core files and
+// strips it to JS (comments kept); a port to another language reads it as the specification.
+// Imports carry the .js suffix so the stripped output runs as browser ESM unchanged.
+//
+// WIX_CLIENT_ID is the public OAuth client id (`appId` in wix.config.json). It is NOT a secret — it
+// only mints anonymous VISITOR tokens — so it is fine in page source. deploy.mjs writes ./config.
+//
+// THE TOKEN IS THE CART. A visitor token is the shopper's identity: their cart lives on it. Mint
+// once per shopper, persist it, refresh it — never mint per request (a fresh token is a new visitor
+// with an empty cart). Where it persists depends on where this code runs:
+//   browser — localStorage, keyed by client id so two sites on one origin don't share a token
+//             (what this file does).
+//   server (a Python/PHP/Go port) — the SHOPPER'S SESSION, one token set per shopper. Never one
+//             process-wide token for everyone: that is one shared cart for all visitors.
+//             This is the only part of a port that isn't line-for-line.
+// docs: https://dev.wix.com/docs/go-headless/coding/authentication/visitors.md
+import { WIX_CLIENT_ID } from "./config.js";
+
+export const WIX_API_BASE = "https://www.wixapis.com";
+const TOKEN_URL = `${WIX_API_BASE}/oauth2/token`;
+const STORAGE_KEY = `wix-visitor-${WIX_CLIENT_ID}`;
+
+export interface Tokens {
+  accessToken: string;
+  refreshToken: string;
+  /** Epoch ms. */
+  expiresAt: number;
+  /** Whose tokens: absent or "visitor" for an anonymous visitor, "member" after a login (a vertical's rest/auth.ts). */
+  role?: "visitor" | "member";
+}
+
+/** Swap this for a server-session-backed store in a port; the browser default is localStorage. */
+export interface TokenStore {
+  load(): Tokens | null;
+  save(tokens: Tokens): void;
+}
+
+let memory: Tokens | null = null;
+export const browserTokenStore: TokenStore = {
+  load() {
+    if (memory) return memory;
+    if (typeof localStorage === "undefined") return null;
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY);
+      if (raw) memory = JSON.parse(raw) as Tokens;
+    } catch {
+      /* disabled or corrupt storage — mint a fresh visitor */
+    }
+    return memory;
+  },
+  save(tokens) {
+    memory = tokens;
+    if (typeof localStorage === "undefined") return;
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+    } catch {
+      /* storage full or disabled — the session just won't survive a reload */
+    }
+  },
+};
+let store: TokenStore = browserTokenStore;
+/** A port calls this once with its session-backed store. */
+export function useTokenStore(s: TokenStore): void {
+  store = s;
+}
+
+// POST /oauth2/token — grantType "anonymous" mints a visitor; "refresh_token" renews and KEEPS the
+// identity (a member refresh token yields member tokens); "authorization_code" + codeVerifier turns
+// a login's authorization code into MEMBER tokens (a vertical's rest/auth.ts). `role` records which.
+export async function mintTokens(body: Record<string, string>, role: Tokens["role"] = "visitor"): Promise<Tokens> {
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ clientId: WIX_CLIENT_ID, ...body }),
+  });
+  if (!res.ok) throw new Error(`Wix auth failed (${res.status}).`);
+  const data = await res.json();
+  return { accessToken: data.access_token, refreshToken: data.refresh_token, expiresAt: Date.now() + data.expires_in * 1000, role };
+}
+
+/** The persisted token set as it is (possibly expired), or null before the first mint. */
+export function loadTokens(): Tokens | null {
+  return store.load();
+}
+
+/** Adopt a token set — a member's after login. Every call from here on runs as that identity. */
+export function setTokens(tokens: Tokens): void {
+  store.save(tokens);
+}
+
+/** Drop the current identity (logout): the next call mints a fresh anonymous visitor. */
+export function clearTokens(): void {
+  store.save({ accessToken: "", refreshToken: "", expiresAt: 0 });
+}
+
+/** A valid access token: cached, refreshed when expired, minted on first use. */
+export async function accessToken(): Promise<string> {
+  const t = store.load();
+  if (t && t.expiresAt - 60_000 > Date.now()) return t.accessToken;
+  let fresh: Tokens | undefined;
+  if (t?.refreshToken) {
+    try {
+      fresh = await mintTokens({ grantType: "refresh_token", refreshToken: t.refreshToken }, t.role ?? "visitor");
+    } catch {
+      /* fall through to a new visitor */
+    }
+  }
+  fresh ??= await mintTokens({ grantType: "anonymous" });
+  store.save(fresh);
+  return fresh.accessToken;
+}
+
+export class WixApiError extends Error {
+  /** The response's `details` as Wix sent it (applicationError, validationError) — for callers that map codes. */
+  public details?: Record<string, any>;
+  constructor(message: string, public status: number, public code?: string, details?: Record<string, any>) {
+    super(message);
+    this.details = details;
+  }
+}
+
+/**
+ * Every Wix call goes through here. `path` is relative to WIX_API_BASE; `query` becomes the query
+ * string (an array repeats the key: fields=A&fields=B). Throws WixApiError on a non-2xx, including
+ * 404 — callers that treat 404 as "not found" catch it. The header carries the RAW access token,
+ * no "Bearer " prefix.
+ */
+export async function wixRequest<T = any>(
+  path: string,
+  { method = "POST", body, query }: { method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; body?: unknown; query?: Record<string, string | readonly string[]> } = {},
+): Promise<T> {
+  const url = new URL(path, WIX_API_BASE);
+  for (const [k, v] of Object.entries(query ?? {})) {
+    for (const item of Array.isArray(v) ? v : [v as string]) url.searchParams.append(k, String(item));
+  }
+  const res = await fetch(url, {
+    method,
+    headers: { Authorization: await accessToken(), "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!res.ok) {
+    let message = "", code: string | undefined, details: Record<string, any> | undefined;
+    try {
+      const j = await res.json();
+      message = j?.message ?? "";
+      code = j?.details?.applicationError?.code;
+      details = j?.details;
+    } catch {
+      /* no JSON body */
+    }
+    throw new WixApiError(message || `${method} ${url.pathname} failed (${res.status}).`, res.status, code, details);
+  }
+  return (res.status === 204 ? null : await res.json()) as T;
+}

package/skills/wix-headless-fast/references/shared/rest/config.ts

@@ -0,0 +1,3 @@
+// Written by install/deploy.mjs --stack static from wix.config.json (or --client-id).
+// The public OAuth client id — not a secret: it only mints anonymous visitor tokens.
+export const WIX_CLIENT_ID: string = "";

package/skills/wix-headless-fast/references/shared/rest/media.ts

@@ -0,0 +1,65 @@
+// Wix media → browser-loadable URLs — the twin of app/wix/media.ts, without the SDK.
+//
+// A media value arrives as either an absolute https://static.wixstatic.com/... URL or a raw
+// `wix:image://v1/<file>/<name>#originWidth=W&originHeight=H` identifier a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The raw form is scaled through this ONE URL shape; any other hand-built
+// form 403s:   https://static.wixstatic.com/media/<file>/v1/fill/w_<W>,h_<H>,al_c,q_90/<file>
+const STATIC = "https://static.wixstatic.com/media";
+const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+
+export type MediaLike = string | null | undefined | { image?: string | null; url?: string | null };
+
+function rawOf(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  const o = value as { image?: string | null; url?: string | null };
+  return o.image ?? o.url ?? "";
+}
+
+/** Resolve any Wix media value to a URL sized w×h ("" when absent). */
+export function imgSrc(value: unknown, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) {
+    const file = v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+    return `${STATIC}/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  }
+  // An absolute Wix media URL (bare, or already scaled to some other size): re-issue it through the
+  // scaler at the requested size, so every image path lands on one shape.
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  if (m) return `${STATIC}/${m[1]}/v1/fill/w_${width},h_${height},al_c,q_90/${m[1]}`;
+  return v;
+}
+
+/** srcset candidates at several widths; `ratio` is height/width. "" only when there is no image. */
+export function imgSrcSet(value: unknown, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  if (v.includes("static.wixstatic.com/") && FILL.test(v)) {
+    return widths.map((w) => `${v.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return v;
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcset` without `src`.
+ * Attribute names as HTML spells them — spread into a template or apply with setAttribute:
+ *   `<img ${attrs(imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw"))} alt="…">`
+ * `sizes` is the width the image renders at; `ratio` is height/width. {} when there is no image.
+ */
+export function imgAttrs(value: unknown, sizes: string, ratio = 1): Record<string, string> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcset: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/** The media identity before scaling — de-duplicate galleries on this, never on a resolved URL. */
+export function mediaKey(value: unknown): 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-fast/references/shared/seed/read-site.mjs

@@ -0,0 +1,99 @@
+// The shared runner behind every vertical's `seed/read-site.mjs` — the build-time read of what a
+// site holds, so the agent sizes the content without composing a single Wix request.
+//
+//   node <SKILL_ROOT>/references/<vertical>/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+//
+// The site is `--site`, else the `siteId` in ./wix.config.json. The token is minted by the Wix CLI
+// inside this process and never written anywhere. Output is ONE JSON object on stdout:
+//   { vertical, siteId, installed, ...what the vertical reads..., calls: [{ method, path, status, docs }] }
+// `calls` lists every request made, with the method's documentation URL — open one of those (the
+// URL plus `.md` is the full page) when the brief needs more than the summary shows. A failed call
+// is reported in `calls` with its status and message; the reader continues and marks the field null.
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+
+const API = "https://www.wixapis.com";
+const DOCS_INSTALLED_APPS = "https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/get-installed-apps";
+
+function flag(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith("--") ? process.argv[i + 1] : null;
+}
+
+export function siteIdFromArgsOrConfig() {
+  const fromFlag = flag("site");
+  if (fromFlag) return fromFlag;
+  if (existsSync("wix.config.json")) {
+    const c = JSON.parse(readFileSync("wix.config.json", "utf8"));
+    return c.siteId ?? c.projectId ?? null;
+  }
+  return null;
+}
+
+export function makeApi(siteId) {
+  const token = execFileSync("npx", ["-y", "@wix/cli@latest", "token", "--site", siteId], { encoding: "utf8" }).trim();
+  if (!token) throw new Error("the Wix CLI returned no token — run `npx @wix/cli@latest login` first");
+  const calls = [];
+  async function call({ method = "POST", path, body, docs }) {
+    const entry = { method, path: path.split("?")[0], docs };
+    calls.push(entry);
+    const res = await fetch(API + path, {
+      method,
+      headers: { Authorization: token, "wix-site-id": siteId, "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    entry.status = res.status;
+    if (!res.ok) {
+      entry.error = text.slice(0, 200) || "(empty body)";
+      const e = new Error(`${method} ${entry.path} → ${res.status}: ${entry.error}`);
+      e.status = res.status;
+      throw e;
+    }
+    try { return text ? JSON.parse(text) : {}; } catch { return {}; }
+  }
+  // Same call, but a failure becomes null and stays in `calls` — for reads whose absence is data.
+  async function tryCall(opts) {
+    try { return await call(opts); } catch { return null; }
+  }
+  async function installed(appId) {
+    const r = await tryCall({ method: "GET", path: "/apps-installer-service/v1/app-instances", docs: DOCS_INSTALLED_APPS });
+    if (!r) return null;
+    return (r.appInstances ?? []).some((a) => a.appDefId === appId || a.appId === appId);
+  }
+  return { call, tryCall, installed, calls };
+}
+
+export const limit = () => Number(flag("limit") ?? 12);
+
+// read(api, { limit }) returns the vertical's summary; the runner adds the envelope and prints.
+export async function runReader({ vertical, appId, read }) {
+  const siteId = siteIdFromArgsOrConfig();
+  if (!siteId) {
+    console.log(JSON.stringify({ error: "no site: pass --site <siteId> or run in a folder with wix.config.json" }));
+    process.exit(1);
+  }
+  const api = makeApi(siteId);
+  const out = { vertical, siteId, scope: null };
+  out.installed = appId ? await api.installed(appId) : undefined;
+  let data = {};
+  if (out.installed === false) {
+    out.scope = `${vertical}: the app is not installed on this site — nothing to read; the vertical's seed installs it`;
+  } else {
+    try { data = await read(api, { limit: limit() }); }
+    catch (e) { out.error = String(e.message).slice(0, 300); }
+  }
+  // What this output is and is not: a SIZING. Every list is a sample page; the counts are the site.
+  const partial = Object.entries(data)
+    .filter(([k, v]) => Array.isArray(v) && typeof data[`${k.replace(/s$/, "")}Count`] === "number" && data[`${k.replace(/s$/, "")}Count`] > v.length)
+    .map(([k, v]) => `${k}: ${v.length} of ${data[`${k.replace(/s$/, "")}Count`]} shown`);
+  if (!out.scope) {
+    out.scope = "A sizing, not the content. Lists are one page (--limit, max 100); counts are the whole site. " +
+      (partial.length ? `Partial here: ${partial.join("; ")}. ` : "") +
+      "The pages read everything live through the deployed data layer. To read more or filter, page the same call: its method and documentation URL are in `calls`.";
+  }
+  Object.assign(out, data);
+  out.calls = api.calls;
+  out.docs = [...new Set(api.calls.map((c) => c.docs).filter(Boolean))];
+  console.log(JSON.stringify(out, null, 2));
+}