Subchapter 16.338

Seed Events

Pricing Plans

Rentalsstatic

Restaurants

815 more in the appendix

Seed Events

export async function setEventMainImage

export async function setupEvents

This file

Number: 16.338
Position: 338 of 828
Type: JavaScript
Size: 15 KB
Lines: 324

Nearby

Source

events/seed/seed-events.mjs

JavaScript324 lines15 KB

1// Events seed — a BUILD-TIME script, never shipped in the app. Run from the project root
2// (where wix.config.json lives) with a plan file:
3//
4//   node <SKILL_ROOT>/templates/events/seed/seed-events.mjs plan.json
5//
6// It mints its own site token via the Wix CLI, installs the Wix Events app if needed,
7// resolves the site currency, then per event: create DRAFT → (TICKETING) add ticket tiers →
8// publish — the order two one-way constraints force (registration.initialType is immutable
9// after create; publishing is one-way). Then it creates + assigns categories and
10// imports+attaches images. Prints a JSON result to stdout.
11//
12// Plan shape (see SEED.md):
13//   { "events": [{ "title", "shortDescription"?, "type": "TICKETING"|"RSVP",
14

seed-events.mjs on GitHub

// "startDate", "endDate" (future ISO-8601 UTC), "timeZoneId",

// "location" ({name,type:"VENUE",address} | {name,type:"ONLINE"} | {locationTbd:true,name}),

// "ticketTiers"?: [{ "name" (≤30 chars), "price" (decimal STRING), "description"?, "initialLimit"?, "feeType"? }],

// "category"? (name), "imageMediaId"? | "imageUrl"? | "imagePrompt"?, "rsvpResponseType"? }] }

//

// Seeding is ADDITIVE — never deletes or overwrites existing content. Unexpected shapes →

// read the live API reference; every call below

// carries a docs: line with its reference page.

import { setSiteCurrency } from "../../shared/seed/site.mjs";

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";

import { isMain } from "../../shared/seed/main.mjs";

const API = "https://www.wixapis.com";

const EVENTS_APP_ID = "140603ad-af8d-84a5-2c80-a0f60cb47351";

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;

}

// {type:"TICKETING"|"RSVP", …} -> the registration block. TICKETING carries a tickets{}

// config; RSVP carries rsvp{responseType} and seeds NO form fields (name+email is built-in).

// initialType is IMMUTABLE after create — set from the plan, never plan to convert.

function buildRegistration(ev) {

if (ev.type === "TICKETING") {

return {

initialType: "TICKETING",

tickets: {

ticketLimitPerOrder: ev.ticketLimitPerOrder ?? 8,

currency: ev.currency ?? "USD", // setupEvents threads the site currency; USD is the last resort

reservationDurationInMinutes: ev.reservationDurationInMinutes ?? 20,

},

};

}

return {

initialType: "RSVP",

rsvp: {

responseType: ev.rsvpResponseType ?? "YES_ONLY", // "YES_ONLY" | "YES_AND_NO"

...(Number.isInteger(ev.rsvpLimit) && ev.rsvpLimit > 0 ? { limit: ev.rsvpLimit } : {}),

...(ev.waitlist === true ? { waitlistEnabled: true } : {}),

// A future start date schedules the opening: the event publishes with status SCHEDULED_RSVP and

// the page says when registration opens; before it, an RSVP is refused. The API requires the

// window's END with its start (run 152: "both start and end dates"); it defaults to the event's

// start, the moment registration stops making sense.

...(ev.registrationOpensAt ? { startDate: ev.registrationOpensAt, endDate: ev.registrationClosesAt ?? ev.startDate } : {}),

},

};

}

// {guests: N} on an RSVP event -> the registration form's guest control, added through the Events

// Forms API AFTER the event exists (Create Event ignores form.controls; probed live 2026-09-28). The

// control lands as a count input (options "0".."N") plus a names list capped at N — the shape the

// site's form reader (events-core toRsvpForm) reads its max from — and takes effect at once.

// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/form/add-control.md

export async function addGuestControl(ctx, eventId, guests) {

const n = Number(guests);

if (!Number.isInteger(n) || n < 1) return false;

await req(ctx, `/events/v1/events/${eventId}/form/control`, { body: {

additionalGuests: { maxGuests: n, namesMandatory: false, labels: { single: "Bringing a guest?", multiple: "How many guests?" } },

} });

return true;

}

// ---- operations ----------------------------------------------------------------------------------

// Idempotent: re-installing an already-installed app 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 installEventsApp(ctx) {

try {

await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {

tenant: { tenantType: "SITE", id: ctx.siteId },

appInstance: { appDefId: EVENTS_APP_ID, enabled: true },

} });

} catch {

/* already installed is fine */

}

// The ticket-definitions API REQUIRES currency and uses whatever you pass verbatim (it does

// NOT fall back to the site currency) — resolve it once, or a non-USD site gets mis-priced.

// docs: https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties.md

export async function getSiteCurrency(ctx) {

try {

const r = await req(ctx, "/site-properties/v4/properties", { method: "GET" });

return r?.properties?.paymentCurrency || "USD";

} catch {

return "USD";

}

/**

* STEP 1 — create ONE event as a draft (no bulk endpoint; loop for multiple). Dates MUST be

* in the future — a past event isn't registerable and won't show in the live listing.

* Returns { id, slug } — id feeds the tier/publish steps; slug is the URL identifier.

* docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/create-event.md

*/

export async function createEvent(ctx, ev) {

const body = {

draft: true,

event: {

title: ev.title,

shortDescription: ev.shortDescription,

location: ev.location,

dateAndTimeSettings: {

startDate: ev.startDate,

endDate: ev.endDate,

timeZoneId: ev.timeZoneId,

showTimeZone: ev.showTimeZone ?? true,

},

registration: buildRegistration(ev),

},

fields: ["DETAILS", "TEXTS", "REGISTRATION", "URLS"],

};

const r = await req(ctx, "/events/v3/events", { body });

return { id: r.event?.id, slug: r.event?.slug };

}

/**

* STEP 2 — ticket tiers for a TICKETING event (skip for RSVP). Must run BEFORE publish —

* publishing a ticketed event with no tiers ships an event with nothing to buy, and there is

* no un-publish. price is a decimal STRING ("65.00", never a number); name ≤ 30 chars; omit

* initialLimit for unlimited. `feeType` is FEE_INCLUDED (the Wix fee comes out of the price),

* FEE_ADDED_AT_CHECKOUT (the buyer pays it on top) or NO_FEE (free tickets and sites that don't

* require a fee). Tiers are independent — fired as one parallel batch.

* docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3/create-ticket-definition.md

*/

export async function createTicketTiers(ctx, eventId, tiers) {

return Promise.all(tiers.map(async (t) => {

const body = (feeType) => ({

ticketDefinition: {

eventId,

name: t.name,

description: t.description,

...(t.initialLimit != null ? { initialLimit: t.initialLimit } : {}),

pricingMethod: { fixedPrice: { value: String(t.price), currency: t.currency ?? "USD" } },

feeType,

},

fields: ["SALES_DETAILS"],

});

// INVALID_FEE_TYPE ("feeType=FEE_INCLUDED feeRequired=false") means this site doesn't take a

// fee on this tier — right after the Events app is installed the fee settings can also lag a

// few seconds (seen on a fresh site, 2026-09-27). So the retries change the fee type instead

// of re-sending the same one: the plan's (default FEE_INCLUDED), then NO_FEE, then

// FEE_ADDED_AT_CHECKOUT after a five-second pause for the install race. Anything else, or a

// third failure, throws as before.

const feeTypes = [t.feeType ?? "FEE_INCLUDED", "NO_FEE", "FEE_ADDED_AT_CHECKOUT"];

for (let attempt = 0; ; attempt++) {

try {

const r = await req(ctx, "/events/v3/ticket-definitions", { body: body(feeTypes[attempt]) });

return { id: r.ticketDefinition?.id, feeType: feeTypes[attempt] };

} catch (e) {

if (!/INVALID_FEE_TYPE/.test(e.message) || attempt >= 2) throw e;

if (attempt === 1) await new Promise((res) => setTimeout(res, 5000));

}

}));

}

// STEP 3 — publish (one-way; for TICKETING only after its tiers exist).

// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/publish-draft-event.md

export async function publishEvent(ctx, eventId) {

return req(ctx, `/events/v3/events/${eventId}/publish`, { body: {} });

}

// STEP 4 (optional) — group events by a format/track. Categories are the v1 API (NOT v3).

// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories/create-category.md

export async function createEventCategories(ctx, names) {

const out = [];

for (const name of names) {

const r = await req(ctx, "/events/v1/categories", { body: { category: { name } } });

out.push({ id: r.category?.id, name });

}

return out;

}

// Assign events to a category. Path is /{categoryId}/events (NOT /assign); body key is

// `eventId` — an ARRAY despite the singular name.

// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories/assign-events.md

export async function assignEventsToCategory(ctx, categoryId, eventIds) {

return req(ctx, `/events/v1/categories/${categoryId}/events`, { body: { eventId: eventIds } });

}

// Events binds mainImage by Wix Media file ID — an external url must be imported first

// (a raw url as the id stores 200 but renders nothing); a plan `imagePrompt` 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";

// mainImage is an Image OBJECT; height/width are REQUIRED or it won't render. Events V3 uses

// NO revision — partial PATCH keyed by event.id. Works before OR after publish.

// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/update-event.md

export async function setEventMainImage(ctx, it) {

return req(ctx, `/events/v3/events/${it.eventId}`, {

method: "PATCH",

body: {

event: {

id: it.eventId,

mainImage: { id: it.id, url: it.url, height: it.height ?? 1024, width: it.width ?? 1024, altText: it.altText },

},

fields: ["DETAILS"], // mainImage reads back only under DETAILS

},

});

}

/**

* ONE-CALL seed: install → site currency → per event create DRAFT → tiers → publish →

* categories → images, ids threaded in memory. The default path.

*/

export async function setupEvents(ctx, { events = [], currency } = {}) {

// Before any event exists: a ticket tier's currency is fixed at creation.

if (currency) await setSiteCurrency(ctx, currency);

await installEventsApp(ctx);

const siteCurrency = currency ?? await getSiteCurrency(ctx);

const created = [];

for (const ev of events) {

const e = await createEvent(ctx, { ...ev, currency: ev.currency ?? siteCurrency });

if (!e.id) throw new Error(`Event "${ev.title}" was not created — no id returned.`);

const tiers = ev.type === "TICKETING" && ev.ticketTiers?.length

? await createTicketTiers(ctx, e.id, ev.ticketTiers.map((t) => ({ ...t, currency: t.currency ?? siteCurrency })))

: [];

// The guest control goes on the draft's form before publish; a refusal leaves the event without it

// (the owner adds it in the dashboard) and the result says so.

let guestControl = false;

if (ev.type !== "TICKETING" && ev.guests) {

try { guestControl = await addGuestControl(ctx, e.id, ev.guests); }

catch (err) { console.error(`guest control skipped for "${ev.title}": ${err.message}`); }

}

await publishEvent(ctx, e.id);

created.push({ ...e, category: ev.category, imageMediaId: ev.imageMediaId, imageUrl: ev.imageUrl, imagePrompt: ev.imagePrompt, ticketCount: tiers.length, feeTypes: tiers.map((t) => t.feeType), ...(ev.guests ? { guestControl } : {}) });

}

const names = [...new Set(created.map((e) => e.category).filter(Boolean))];

const categories = names.length ? await createEventCategories(ctx, names) : [];

for (const c of categories) {

const eventIds = created.filter((e) => e.category === c.name).map((e) => e.id);

if (eventIds.length) await assignEventsToCategory(ctx, c.id, eventIds);

}

// Pass 2 — images: resolve (import by url / generate by prompt) in one parallel wave, then

// attach. Failures leave the event text-only; the seed's exit never depends on images.

const files = await resolveItemImages(ctx, created.map((e) => ({

mediaId: e.imageMediaId,

url: e.imageUrl,

path: e.imagePath,

prompt: e.imagePrompt,

displayName: `${e.slug || "event"}.png`,

})));

let imagesAttached = 0;

for (let i = 0; i < created.length; i++) {

const e = created[i];

if (!files[i]) continue;

try {

await setEventMainImage(ctx, { eventId: e.id, id: files[i].id, url: files[i].url, height: 1024, width: 1024, altText: e.slug });

imagesAttached++;

} catch {

/* never block on image failure — the event stays text-only */

}

return {

events: created.map((e) => ({ id: e.id, slug: e.slug, ticketCount: e.ticketCount, feeTypes: e.feeTypes, category: e.category ?? null })),

categories,

imagesAttached,

// Completing a PAID purchase needs a premium plan + a configured payment method in the

// dashboard — not a seeding failure; surface it to the owner. Free/RSVP need neither.

notes: created.some((e) => e.ticketCount > 0)

? ["Paid tickets require a premium plan + a configured payment method in the dashboard to complete a purchase."]

: [],

};

}

// ---- CLI entry ----------------------------------------------------------------------------------

const invokedDirectly = isMain(import.meta.url);

if (invokedDirectly) {

const planPath = process.argv[2];

if (!planPath) {

console.error("usage: node seed-events.mjs <plan.json> (run from the project root)");

process.exit(1);

}

const plan = JSON.parse(readFileSync(planPath, "utf8"));

const ctx = makeCtx();

setupEvents(ctx, plan)

.then((result) => console.log(JSON.stringify(result, null, 2)))

.catch((e) => {

console.error(e.message);

process.exit(1);

});

}