@wix/agent-skills 1.21.0 → 1.22.0

package/skills/wix-headless-fast/references/portfolio/rest/portfolio.ts

@@ -1,75 +0,0 @@
-// Portfolio reads over REST — the twin of app/wix/portfolio/portfolio.ts. Same exports, same DTOs;
-// the rules and mappers come from portfolio-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 URL and body per function. Every call here is a public read, safe from a
-// browser with a visitor token. Porting: keep the paths, keep the bodies, port the core once.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/list-collections.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/query-collections.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/list-projects.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/query-projects.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/list-project-items.md
-import { wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
-import {
-  galleryItems,
-  visibleCollection,
-  visibleCollections,
-  visibleProject,
-  visibleProjects,
-  type Raw,
-  type VideoSrc,
-} from "./portfolio-core.js";
-import type { CollectionSummary, GalleryItem, ProjectDetail, ProjectSummary } from "./types.js";
-
-// REST never returns the bare wix:video:// string — videoInfo arrives as { resolutions, posters },
-// which the core reads directly. A string here has no resolver on this transport → dropped.
-const videoSrc: VideoSrc = () => null;
-
-/** Visible collections in dashboard order.  GET /portfolio/v1/collections?paging.limit=N → { collections } */
-export async function fetchCollections({ limit = 100 } = {}): Promise<CollectionSummary[]> {
-  const res = await wixRequest<Raw>("/portfolio/v1/collections", { method: "GET", query: { "paging.limit": String(limit) } });
-  return visibleCollections((res?.collections ?? []) as Raw[], imgSrc);
-}
-
-/**
- * One visible collection by URL slug; null when missing or hidden → a real 404.
- * POST /portfolio/v1/collections/query  { query: { filter: { slug }, cursorPaging: { limit: 1 } } } → { collections }
- */
-export async function fetchCollectionBySlug(slug: string): Promise<CollectionSummary | null> {
-  const res = await wixRequest<Raw>("/portfolio/v1/collections/query", {
-    body: { query: { filter: { slug }, cursorPaging: { limit: 1 } } },
-  });
-  return visibleCollection(res?.collections?.[0] as Raw | undefined, imgSrc);
-}
-
-/** Visible projects in list order, optionally one collection's.  GET /portfolio/v1/projects?paging.limit=N → { projects } */
-export async function fetchProjects({
-  collectionId,
-  limit = 100,
-}: { collectionId?: string; limit?: number } = {}): Promise<ProjectSummary[]> {
-  const res = await wixRequest<Raw>("/portfolio/v1/projects", { method: "GET", query: { "paging.limit": String(limit) } });
-  return visibleProjects((res?.projects ?? []) as Raw[], collectionId, imgSrc, videoSrc);
-}
-
-/**
- * One visible project with its details rows by URL slug; null when missing or hidden.
- * POST /portfolio/v1/projects/query  { query: { filter: { slug }, cursorPaging: { limit: 1 } } } → { projects }
- */
-export async function fetchProjectBySlug(slug: string): Promise<ProjectDetail | null> {
-  const res = await wixRequest<Raw>("/portfolio/v1/projects/query", {
-    body: { query: { filter: { slug }, cursorPaging: { limit: 1 } } },
-  });
-  return visibleProject(res?.projects?.[0] as Raw | undefined, imgSrc, videoSrc);
-}
-
-/**
- * A project's gallery in dashboard order; IMAGE and VIDEO items only.
- * GET /portfolio/v1/projectItems/{projectId}/items?paging.limit=100 → { items }
- */
-export async function fetchProjectGallery(projectId: string): Promise<GalleryItem[]> {
-  const res = await wixRequest<Raw>(`/portfolio/v1/projectItems/${encodeURIComponent(projectId)}/items`, {
-    method: "GET",
-    query: { "paging.limit": "100" },
-  });
-  return galleryItems((res?.items ?? []) as Raw[], imgSrc, videoSrc);
-}

package/skills/wix-headless-fast/references/portfolio/seed/SEED.md

@@ -1,86 +0,0 @@
-# Portfolio — seeding
-
-Seed by **running `seed-portfolio.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 Portfolio app if needed, and creates everything in the right order:
-collections first (a project's `collectionIds` are NOT validated — a wrong id silently
-orphans the project), then projects, gallery items, and covers.
-
-```bash
-# from the project root (where wix.config.json lives):
-node <SKILL_ROOT>/references/portfolio/seed/seed-portfolio.mjs plan.json
-```
-
-`plan.json` is plain data — write it from the brief. **Default to 2 collections × 2 projects
-each** (the seed shows the shape; the owner adds the rest in the dashboard) and make them
-exercise the UI: every collection and project gets a cover, every project gets 2–3 gallery
-`items` (a portfolio without images looks broken), and a couple of projects get `details`
-rows (Role, Year, Client…).
-
-```json
-{
-  "collections": [
-    { "title": "Brand Identity", "description": "Logo systems and visual identities.",
-      "coverImageUrl": "https://…" },
-    { "title": "Editorial", "description": "Print and digital editorial design.",
-      "coverImageUrl": "https://…" }
-  ],
-  "projects": [
-    { "title": "Northwind Rebrand", "description": "Full identity refresh for a logistics firm.",
-      "collection": "Brand Identity",
-      "details": [ { "label": "Role", "text": "Brand & Art Direction" }, { "label": "Year", "text": "2025" } ],
-      "coverImageUrl": "https://…",
-      "items": [
-        { "sortOrder": 1, "title": "Logo system", "imageUrl": "https://…" },
-        { "sortOrder": 2, "title": "Stationery", "imageUrl": "https://…" }
-      ] },
-    { "title": "Harbor Coffee", "description": "Packaging and label suite.",
-      "collection": "Brand Identity", "coverImageUrl": "https://…",
-      "items": [ { "sortOrder": 1, "title": "Label set", "imageUrl": "https://…" } ] },
-    { "title": "Field Notes Quarterly", "description": "Magazine layout and typography.",
-      "collection": "Editorial", "coverImageUrl": "https://…",
-      "items": [ { "sortOrder": 1, "title": "Spread", "imageUrl": "https://…" } ] },
-    { "title": "City Guides", "description": "Travel series covers.",
-      "collection": "Editorial", "coverImageUrl": "https://…",
-      "items": [ { "sortOrder": 1, "title": "Covers", "imageUrl": "https://…" } ] }
-  ]
-}
-```
-
-- `collection` — a collection **title from this plan**; resolved to its created id. A project
-  without one belongs to no collection (reachable only from an all-projects list).
-- `details` — optional `[{ label, text }]` rows; render on the project page. Omit for none.
-- Every image field's default is a prompt (`coverImagePrompt` / `items[].imagePrompt` —
-  AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
-  aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied
-  use a path (`coverImagePath` / `items[].imagePath` — a file on this machine, uploaded to
-  Wix Media) or a url (`coverImageUrl` / `items[].imageUrl` — their own hosted URL; verify it
-  with `curl -sI` → 200) — never a stock-photo or guessed URL. All images —
-  covers and gallery items alike — resolve in one parallel wave and never block the seed; a
-  failed image skips just that item/cover. The **cover** is the
-  listing thumbnail; **items** are the detail-page gallery — separate entities, both wanted.
-  If a project has only a cover, reuse its url as item 1 so the gallery isn't empty.
-- `sortOrder` (1, 2, 3…) sets the gallery render order.
-- `hidden` defaults to shown — omit it; send `hidden: true` only to hide an entity.
-- Gallery items seed as images only; the owner adds videos in the dashboard.
-- A fresh Portfolio install ships sample content ("My Portfolio" + sample projects). **Seeding
-  is additive — never delete or overwrite existing content**; if removing the samples seems
-  wanted, ask the owner first.
-
-## Supplied content
-
-The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For a portfolio, each project the
-user lists is one entry. Its title becomes `title`; its category or series becomes `collection`
-(and joins the `collections` list); client, role, year and similar facts become `details`; their
-cover image becomes `coverImageUrl`; their project images become `items` in the order given. A
-photo with no caption gets its file name as `title`.
-
-## Escape hatch — individual functions
-`setupPortfolio` composes exported steps — `installPortfolioApp`, `createCollections`,
-`createProjects`, `importImage`, `attachProjectCovers`, `attachCollectionCovers`,
-`createProjectItems`, `listCollections`, `listProjects`, plus `makeCtx()` — import them only
-for a partial re-seed.
-
-## Reference
-Unexpected shape or an uncovered operation → read the live Wix API reference; the
-authoritative source recipe is `wix-headless/references/inline-recipes/setup-portfolio.md`.

package/skills/wix-headless-fast/references/portfolio/seed/read-site.mjs

@@ -1,20 +0,0 @@
-// What the portfolio holds: collections and projects.
-//   node <SKILL_ROOT>/references/portfolio/seed/read-site.mjs [--site <siteId>] [--limit <n>]
-import { runReader } from "../../shared/seed/read-site.mjs";
-
-const PORTFOLIO_APP_ID = "d90652a2-f5a1-4c7c-84c4-d4cdcc41f130";
-const D = "https://dev.wix.com/docs/api-reference/business-solutions/portfolio";
-
-await runReader({
-  vertical: "portfolio",
-  appId: PORTFOLIO_APP_ID,
-  async read(api, { limit }) {
-    const cols = await api.call({ method: "GET", path: "/portfolio/v1/collections", docs: `${D}/collections/list-collections` });
-    const projs = await api.tryCall({ method: "GET", path: "/portfolio/v1/projects", docs: `${D}/projects/list-projects` });
-    return {
-      collections: (cols.collections ?? []).map((c) => ({ id: c.id, title: c.title, slug: c.slug, hidden: c.hidden ?? false, cover: !!c.coverImage })),
-      projectCount: (projs?.projects ?? []).length,
-      projects: (projs?.projects ?? []).slice(0, limit).map((p) => ({ title: p.title, slug: p.slug, hidden: p.hidden ?? false, collections: (p.collectionIds ?? []).length, cover: !!p.coverImage })),
-    };
-  },
-});

package/skills/wix-headless-fast/references/portfolio/seed/seed-portfolio.mjs

@@ -1,256 +0,0 @@
-// Portfolio 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>/references/portfolio/seed/seed-portfolio.mjs plan.json
-//
-// It mints its own site token via the Wix CLI, installs the Wix Portfolio app if needed,
-// creates collections then projects (collections FIRST — a project's collectionIds are NOT
-// validated, so a wrong id is silently accepted and orphans the project), creates each
-// project's gallery items, and imports+attaches cover images. Prints a JSON result to stdout.
-//
-// Plan shape (see SEED.md):
-//   { "collections": [{ "title", "description"?, "hidden"?, "coverImageUrl"? | "coverImagePrompt"? }],
-//     "projects":    [{ "title", "description"?, "hidden"?,
-//                       "collection"? (title),        // resolved to that collection's id
-//                       "details"?: [{ "label", "text" }],
-//                       "coverImageUrl"? | "coverImagePrompt"?,
-//                       "items"?: [{ "sortOrder", "title"?, "imageUrl" | "imagePrompt" }] }] }
-//
-// Seeding is ADDITIVE — never deletes or overwrites existing content. A fresh Portfolio
-// install ships its own sample content ("My Portfolio" + sample projects); removing it is the
-// owner's call, not this script's. Unexpected shapes → read the live API reference;
-// authoritative source recipe: wix-headless/references/inline-recipes/setup-portfolio.md.
-import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { resolveItemImages } from "../../shared/seed/images.mjs";
-
-const API = "https://www.wixapis.com";
-const PORTFOLIO_APP_ID = "d90652a2-f5a1-4c7c-84c4-d4cdcc41f130";
-
-export function makeCtx({ cwd = process.cwd() } = {}) {
-  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
-  const siteId = config.siteId ?? config.projectId;
-  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
-  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
-    encoding: "utf8",
-    cwd,
-  }).trim();
-  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
-  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;
-}
-
-// ---- operations ----------------------------------------------------------------------------------
-
-// Idempotent — re-installing returns 200.
-// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
-export async function installPortfolioApp(ctx) {
-  try {
-    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
-      tenant: { tenantType: "SITE", id: ctx.siteId },
-      appInstance: { appDefId: PORTFOLIO_APP_ID, enabled: true },
-    } });
-  } catch {
-    /* already installed is fine */
-  }
-}
-
-// Read-only listing helpers (partial re-seeds, verification).
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/list-collections.md
-export async function listCollections(ctx) {
-  const r = await req(ctx, "/portfolio/v1/collections", { method: "GET" });
-  return (r.collections ?? []).map((c) => ({ id: c.id, title: c.title, slug: c.slug }));
-}
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/list-projects.md
-export async function listProjects(ctx) {
-  const r = await req(ctx, "/portfolio/v1/projects", { method: "GET" });
-  return (r.projects ?? []).map((p) => ({ id: p.id, title: p.title, slug: p.slug }));
-}
-
-// STEP 1 — collections. The display name is `title`, not `name`; `slug` auto-generates from
-// the title; `hidden` defaults to false = shown (omit it — send true only to hide). No
-// bulk-create: one call per collection.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/create-collection.md
-export async function createCollections(ctx, collections) {
-  const out = [];
-  for (const c of collections) {
-    const body = { collection: { title: c.title, description: c.description } };
-    if (c.hidden) body.collection.hidden = true;
-    const r = await req(ctx, "/portfolio/v1/collections", { body });
-    out.push({ id: r.collection?.id, slug: r.collection?.slug, revision: r.collection?.revision });
-  }
-  return out;
-}
-
-// STEP 2 — projects, AFTER collections: collectionIds must hold real ids from createCollections
-// (they are NOT validated — a wrong/missing id silently orphans the project). `details` is an
-// optional [{ label, text }] array. No bulk-create: one call per project.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/create-project.md
-export async function createProjects(ctx, projects) {
-  const out = [];
-  for (const p of projects) {
-    const project = {
-      title: p.title,
-      description: p.description,
-      collectionIds: p.collectionIds ?? [],
-    };
-    if (p.details) project.details = p.details;
-    if (p.hidden) project.hidden = true;
-    const r = await req(ctx, "/portfolio/v1/projects", { body: { project } });
-    out.push({ id: r.project?.id, slug: r.project?.slug, revision: r.project?.revision });
-  }
-  return out;
-}
-
-// Portfolio binds covers + gallery items by Wix Media file ID — an external url must be
-// imported first (a raw url renders nothing); a plan `imagePrompt`/`coverImagePrompt` is
-// generated (Wix AI, 1 credit) then imported. Both live in the shared util (parallel,
-// resilient, never blocks the seed).
-export { importImage } from "../../shared/seed/images.mjs";
-
-// Cover = the listing-card thumbnail. PATCH per entity, echoing the current revision (missing/
-// stale revision fails); height + width are required alongside the imported file id.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/update-project.md
-// One PATCH per entity; a failure on one must not cost the rest theirs. Returns
-// { attached: [id], failures: [{ id, error }] } — the caller counts what persisted, not what was sent.
-async function attachEach(ctx, items, urlOf, bodyOf) {
-  const attached = [];
-  const failures = [];
-  for (const it of items) {
-    try { await req(ctx, urlOf(it), { method: "PATCH", body: bodyOf(it) }); attached.push(it.id); }
-    catch (e) { failures.push({ id: it.id, error: e?.message ?? String(e) }); }
-  }
-  return { attached, failures };
-}
-export async function attachProjectCovers(ctx, items) {
-  return attachEach(ctx, items, (it) => `/portfolio/v1/projects/${it.id}`,
-    (it) => ({ project: { id: it.id, revision: it.revision, coverImage: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } }));
-}
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/update-collection.md
-export async function attachCollectionCovers(ctx, items) {
-  return attachEach(ctx, items, (it) => `/portfolio/v1/collections/${it.id}`,
-    (it) => ({ collection: { id: it.id, revision: it.revision, coverImage: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } }));
-}
-
-// The detail-page gallery is a SEPARATE `item` entity — one POST per image; sortOrder (1,2,3…)
-// sets render order. Lowercase `items` — `/Items` 404s. There is NO public list endpoint.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/create-project-item.md
-export async function createProjectItems(ctx, items) {
-  const out = [];
-  for (const it of items) {
-    const r = await req(ctx, "/portfolio/v1/items", {
-      body: { item: { projectId: it.projectId, sortOrder: it.sortOrder, title: it.title, image: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } },
-    });
-    out.push({ id: r.item?.id });
-  }
-  return out;
-}
-
-/**
- * ONE-CALL seed: install → collections → projects (into collections) → gallery items →
- * covers, ids threaded in memory. The default path.
- */
-export async function setupPortfolio(ctx, { collections = [], projects = [] } = {}) {
-  await installPortfolioApp(ctx);
-
-  const cols = await createCollections(ctx, collections);
-  const idByTitle = new Map(collections.map((c, i) => [c.title, cols[i].id]));
-
-  const projs = await createProjects(
-    ctx,
-    projects.map((p) => ({
-      title: p.title,
-      description: p.description,
-      details: p.details,
-      hidden: p.hidden,
-      collectionIds: p.collection ? [idByTitle.get(p.collection)].filter(Boolean) : [],
-    })),
-  );
-
-  // Pass 2 — images: gallery items + project covers + collection covers, flattened into ONE
-  // parallel wave (import by url / generate by prompt), then mapped back to each attach.
-  // A failed image skips just that item/cover; the seed's exit never depends on images.
-  const specs = [];
-  const galleryRefs = [];
-  projects.forEach((p, pi) => {
-    for (const it of p.items ?? []) {
-      galleryRefs.push({ pi, it, spec: specs.length });
-      specs.push({ path: it.imagePath, url: it.imageUrl, prompt: it.imagePrompt, displayName: `${it.title || "item"}.png` });
-    }
-  });
-  const projCoverAt = specs.length;
-  projects.forEach((p) => specs.push({ path: p.coverImagePath, url: p.coverImageUrl, prompt: p.coverImagePrompt, displayName: `${p.title || "project"}-cover.png` }));
-  const colCoverAt = specs.length;
-  collections.forEach((c) => specs.push({ path: c.coverImagePath, url: c.coverImageUrl, prompt: c.coverImagePrompt, displayName: `${c.title || "collection"}-cover.png` }));
-  const files = await resolveItemImages(ctx, specs);
-  const dims = { height: 1024, width: 1024 };
-
-  const itemsFlat = galleryRefs
-    .map(({ pi, it, spec }) => (files[spec] && projs[pi]?.id
-      ? { projectId: projs[pi].id, sortOrder: it.sortOrder, title: it.title, imageId: files[spec].id, ...dims }
-      : null))
-    .filter(Boolean);
-  let items = [];
-  try {
-    if (itemsFlat.length) items = await createProjectItems(ctx, itemsFlat);
-  } catch {
-    /* the remaining gallery items stay unseeded */
-  }
-
-  const projCovers = projs
-    .map((p, i) => (files[projCoverAt + i] && p.id
-      ? { id: p.id, revision: p.revision, imageId: files[projCoverAt + i].id, ...dims }
-      : null))
-    .filter(Boolean);
-  const colCovers = cols
-    .map((c, i) => (files[colCoverAt + i] && c.id
-      ? { id: c.id, revision: c.revision, imageId: files[colCoverAt + i].id, ...dims }
-      : null))
-    .filter(Boolean);
-  // coversAttached counts the PATCHes that succeeded; coverFailures names the rest. Neither blocks the seed.
-  let coversAttached = 0;
-  const coverFailures = [];
-  if (projCovers.length) { const r = await attachProjectCovers(ctx, projCovers); coversAttached += r.attached.length; coverFailures.push(...r.failures.map((f) => ({ project: f.id, error: f.error }))); }
-  if (colCovers.length) { const r = await attachCollectionCovers(ctx, colCovers); coversAttached += r.attached.length; coverFailures.push(...r.failures.map((f) => ({ collection: f.id, error: f.error }))); }
-
-  return {
-    collections: cols,
-    projects: projs,
-    itemsCreated: items.length,
-    coversAttached,
-    coverFailures,
-  };
-}
-
-// ---- 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-portfolio.mjs <plan.json>   (run from the project root)");
-    process.exit(1);
-  }
-  const plan = JSON.parse(readFileSync(planPath, "utf8"));
-  const ctx = makeCtx();
-  setupPortfolio(ctx, plan)
-    .then((result) => console.log(JSON.stringify(result, null, 2)))
-    .catch((e) => {
-      console.error(e.message);
-      process.exit(1);
-    });
-}