@wix/agent-skills 1.26.0 → 1.28.0

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

@@ -0,0 +1,20 @@
+// What the portfolio holds: collections and projects.
+//   node <SKILL_ROOT>/templates/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-templates/portfolio/seed/seed-portfolio.mjs

@@ -0,0 +1,253 @@
+// 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>/templates/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; every call
+// below carries a docs: line with its reference page.
+import { readFileSync } from "node:fs";
+import { resolveItemImages } from "../../shared/seed/images.mjs";
+import { seedSiteId } from "../../shared/seed/site-context.mjs";
+import { wixToken } from "../../shared/seed/wix-cli.mjs";
+
+const API = "https://www.wixapis.com";
+const PORTFOLIO_APP_ID = "d90652a2-f5a1-4c7c-84c4-d4cdcc41f130";
+
+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;
+}
+
+// ---- 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);
+    });
+}