@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/bookings/app/wix/bookings/services-core.ts

@@ -0,0 +1,366 @@
+// Service rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./services.ts
+// (the SDK, managed Astro and React) and the REST twin in templates/bookings/rest/services.ts
+// (fetch, a static site or a port to another language). Every rule about price, "Free", duration,
+// media, staff, locations, deposits, the CTA state, and the payment option lives HERE, once. A raw
+// entity may come from the SDK (`_id`, dates as Date, media as a `wix:image://` string) or from REST
+// (`id`, dates as ISO strings, media as an { id, url, width, height } object); the mappers accept
+// both. Imports are type-only so a strip to JS emits no imports.
+import type {
+  BookingCategory,
+  BookingsSettings,
+  CourseSpan,
+  CtaState,
+  Deposit,
+  LocationOption,
+  RateType,
+  ServiceDetail,
+  ServiceLocation,
+  ServiceSummary,
+  ServiceType,
+  StaffSummary,
+} from "./types";
+
+/** A raw Services V2 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** The Wix Bookings app id — the cart's catalogReference.appId and the services filter. */
+export const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+/** Staff-member resource type id (ANY_RESOURCE fallback + staff filtering). */
+export const STAFF_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155";
+/**
+ * Requested on every service read: without STAFF_MEMBER_DETAILS `staffMemberDetails` is absent (staff
+ * = []); without DISCOUNT_INFO_DETAILS `payment.discountInfo` is absent (no discount is ever shown).
+ */
+export const SERVICES_CONDITIONAL_FIELDS = ["STAFF_MEMBER_DETAILS", "DISCOUNT_INFO_DETAILS"] as const;
+/** Listing page size — Wix's own list pages 20 at a time. */
+export const SERVICES_PAGE_SIZE = 20;
+/**
+ * Reserved location-filter id for "held somewhere else" (custom or customer locations) — the same
+ * literal Wix's service list accepts in `?location=`, never a real location GUID.
+ */
+export const OTHER_LOCATIONS_ID = "OTHER_LOCATIONS";
+
+const SERVICE_TYPES: readonly string[] = ["APPOINTMENT", "CLASS", "COURSE"];
+const RATE_TYPES: readonly string[] = ["FIXED", "VARIED", "CUSTOM", "NO_FEE", "SUBSCRIPTION"];
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+export interface ServicesFilterOptions {
+  slug?: string;
+  categoryId?: string | null;
+  /** A business location id, or OTHER_LOCATIONS_ID for the custom/customer bucket. */
+  locationId?: string | null;
+}
+
+/**
+ * The filter every services read shares, in REST query-language form: this app's services, never
+ * hidden ones (filtered by the SERVER — a page is never under-filled by hidden services), optionally
+ * one slug (`mainSlug.name`), one category (`category.id`), one business location
+ * (`locations.business.id`) or the "other locations" bucket (`locations.type` CUSTOM/CUSTOMER).
+ * The SDK transport applies the same rules with its query builder.
+ */
+export function servicesFilter({ slug, categoryId, locationId }: ServicesFilterOptions = {}): Raw {
+  return {
+    appId: BOOKINGS_APP_ID,
+    hidden: false,
+    ...(slug ? { "mainSlug.name": slug } : {}),
+    ...(categoryId ? { "category.id": categoryId } : {}),
+    ...(locationId === OTHER_LOCATIONS_ID
+      ? { "locations.type": { $hasSome: ["CUSTOM", "CUSTOMER"] } }
+      : locationId
+        ? { "locations.business.id": locationId }
+        : {}),
+  };
+}
+
+/** The Query Categories body: only categories that hold at least one bookable service come back. */
+export const CATEGORIES_QUERY: Raw = { filter: { services: {} } };
+/** The Query Locations body: only business locations that host a visible service of this app. */
+export const LOCATIONS_QUERY: Raw = { filter: { services: { appId: BOOKINGS_APP_ID, hidden: false } } };
+
+/**
+ * Whether an offset page has a successor: from the response's total when the server counted, else
+ * from a full page (a short page is the last one).
+ */
+export function hasMorePage(meta: Raw | undefined | null, offset: number, count: number, limit: number): boolean {
+  const total = meta?.total;
+  if (typeof total === "number" && !meta?.tooManyToCount) return offset + count < total;
+  return count >= limit;
+}
+
+/**
+ * A media value the image helpers can resolve. The SDK hands over a `wix:image://v1/<id>/<name>#…`
+ * string (or an https URL); REST hands over the image OBJECT with a bare file id — rebuilt into the
+ * same `wix:image://` form the SDK produces, so imgSrc scales both identically.
+ */
+export function mediaValue(image: unknown): unknown {
+  if (!image || typeof image === "string") return image;
+  const o = image as Raw;
+  const url: string = o.url ?? "";
+  if (/^(https?:|wix:image:)/.test(url)) return url;
+  if (o.id) return `wix:image://v1/${o.id}/${encodeURIComponent(o.filename ?? "")}#originWidth=${o.width ?? 0}&originHeight=${o.height ?? 0}`;
+  return url;
+}
+
+/**
+ * A Money value → display string, the way Wix's own bookings surfaces format it: whole amounts
+ * without decimals ("€75"), fractional ones with two ("€49.99"); "" when the value or the currency
+ * is missing — never a guessed currency (a USD default mislabels every non-USD site).
+ */
+export function formatPrice(value: string | number | undefined | null, currency: string | undefined | null, locale?: string): string {
+  if (value == null || value === "" || !currency) return "";
+  const amount = Number(value);
+  if (!Number.isFinite(amount)) return "";
+  const digits = amount % 1 === 0 ? 0 : 2;
+  try {
+    return new Intl.NumberFormat(locale, { style: "currency", currency, currencyDisplay: "symbol", minimumFractionDigits: digits, maximumFractionDigits: digits }).format(amount);
+  } catch {
+    return `${amount} ${currency}`;
+  }
+}
+
+/** Money as the API sends it ({ value, currency }) → display string ("" when incomplete). */
+export const formatMoney = (money: Raw | undefined | null, locale?: string): string => formatPrice(money?.value, money?.currency, locale);
+
+/** "1 hr 30 min" / "45 min" / "2 hr" through Intl unit formatting ("" when unknown). */
+export function durationLabel(minutes: number | null | undefined, locale?: string): string {
+  if (minutes == null || !Number.isFinite(minutes) || minutes <= 0) return "";
+  try {
+    const unit = (u: "hour" | "minute", n: number) => new Intl.NumberFormat(locale, { style: "unit", unit: u, unitDisplay: "short" }).format(n);
+    if (minutes < 60) return unit("minute", minutes);
+    const hours = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+    return rest === 0 ? unit("hour", hours) : `${unit("hour", hours)} ${unit("minute", rest)}`;
+  } catch {
+    return `${minutes} min`;
+  }
+}
+
+/** A service offers add-ons when any of its groups holds add-on ids. */
+export const hasAddOns = (raw: Raw): boolean => ((raw.addOnGroups ?? []) as Raw[]).some((g) => (g.addOnIds ?? []).length > 0);
+
+export interface ResolvedPrice {
+  rateType: RateType;
+  price: string;
+  priceFrom: boolean;
+  basePrice: string;
+  discountName: string;
+  calculatedAtCheckout: boolean;
+  hasPricingPlans: boolean;
+  free: boolean;
+}
+
+/**
+ * The price a tile shows, by `payment.rateType` — Wix's own rule: FIXED → the price; VARIED → the
+ * minimum with a "From" flag; CUSTOM → the owner's free text; NO_FEE → "Free" (Wix shows nothing;
+ * a headless brief expects the word). A discount (from DISCOUNT_INFO_DETAILS) yields a concrete
+ * discounted price only for a single FIXED price with no add-ons; otherwise it is "calculated at
+ * checkout". A FIXED price of 0 counts as free too — it books without a checkout.
+ */
+export function resolvePrice(raw: Raw): ResolvedPrice {
+  const payment: Raw = raw.payment ?? {};
+  const rateType = (RATE_TYPES.includes(payment.rateType) ? payment.rateType : "NO_FEE") as RateType;
+  const hasPricingPlans = ((payment.pricingPlanIds ?? []) as string[]).length > 0;
+  let price = "";
+  let priceFrom = false;
+  let free = false;
+  switch (rateType) {
+    case "FIXED":
+      price = formatMoney(payment.fixed?.price);
+      free = Number(payment.fixed?.price?.value ?? 0) === 0;
+      if (free) price = "Free";
+      break;
+    case "VARIED":
+      price = formatMoney(payment.varied?.minPrice ?? payment.varied?.defaultPrice);
+      priceFrom = !!price;
+      break;
+    case "CUSTOM":
+      price = payment.custom?.description ?? "";
+      break;
+    case "NO_FEE":
+      price = "Free";
+      free = true;
+      break;
+    default:
+      break;
+  }
+  const discountName: string = payment.discountInfo?.discountName ?? "";
+  const after = discountName && rateType === "FIXED" && !free && !hasAddOns(raw) ? formatMoney(payment.discountInfo?.priceAfterDiscount) : "";
+  return {
+    rateType,
+    price: after || price,
+    priceFrom,
+    basePrice: after ? price : "",
+    discountName,
+    calculatedAtCheckout: !!discountName && !after,
+    hasPricingPlans,
+    free,
+  };
+}
+
+/**
+ * Deposit terms from the service's payment: `options.deposit` says a deposit is taken; the amount is
+ * `fixed|varied.deposit` (a percentage deposit stores no amount — the server resolves it, so the
+ * amount stays ""); `fullUpfrontPaymentAllowed` lets the visitor pay everything now instead.
+ */
+export function depositOf(raw: Raw): Deposit | null {
+  const payment: Raw = raw.payment ?? {};
+  const rate: Raw = payment.fixed ?? payment.varied ?? {};
+  const value = rate.deposit?.value ?? rate.depositDetails?.amount?.value;
+  const takesDeposit = payment.options?.deposit === true || (!!value && Number(value) > 0);
+  if (!takesDeposit) return null;
+  return {
+    amount: formatMoney(rate.deposit ?? rate.depositDetails?.amount),
+    fullUpfrontAllowed: rate.fullUpfrontPaymentAllowed === true,
+  };
+}
+
+/** A service `locations[]` entry → DTO (BUSINESS carries the location's id and name). */
+export function toLocation(raw: Raw): ServiceLocation {
+  const type = (["BUSINESS", "CUSTOM", "CUSTOMER"].includes(raw.type) ? raw.type : "CUSTOM") as ServiceLocation["type"];
+  return {
+    id: type === "BUSINESS" ? rawId(raw.business) || rawId(raw) || null : null,
+    name: raw.business?.name ?? raw.custom?.address?.formattedAddress ?? (type === "CUSTOMER" ? "Your location" : ""),
+    type,
+  };
+}
+
+/** A Query Locations response → the listing's location options (sorted by name) and the "other locations" flag. */
+export function toLocationOptions(res: Raw | null | undefined): { locations: LocationOption[]; hasOtherLocations: boolean } {
+  const locations = ((res?.businessLocations?.locations ?? []) as Raw[])
+    .map((l) => ({ id: rawId(l.business) || rawId(l), name: l.business?.name ?? "" }))
+    .filter((l) => l.id)
+    .sort((a, b) => a.name.localeCompare(b.name));
+  return { locations, hasOtherLocations: res?.customLocations?.exists === true || res?.customerLocations?.exists === true };
+}
+
+/** Staff from `staffMemberDetails` (needs STAFF_MEMBER_DETAILS), photo through the injected imgSrc. */
+export function toStaff(raw: Raw, imgSrc: ImgSrc): StaffSummary[] {
+  return ((raw.staffMemberDetails?.staffMembers ?? []) as Raw[])
+    .map((m) => ({ id: m.staffMemberId ?? "", name: m.name ?? "", imageUrl: imgSrc(mediaValue(m.mainMedia?.image), 160, 160) }))
+    .filter((m) => m.id);
+}
+
+/** An API date (Date on the SDK, ISO string on REST) → ISO string, or null. */
+export function toIso(value: unknown): string | null {
+  if (!value) return null;
+  const d = value instanceof Date ? value : new Date(String(value));
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
+const isMissingOrPast = (iso: string | null, now: number): boolean => !iso || new Date(iso).getTime() <= now;
+
+/**
+ * Whether policy already forbids booking (Wix's rule): the late-booking limit before the first
+ * session has passed, or the first session started and booking after start is off, or a course's
+ * last session ended. Only meaningful for services with a fixed first session (classes, courses).
+ */
+export function isTooLateToBook(raw: Raw, now = Date.now()): boolean {
+  const policy: Raw = raw.bookingPolicy ?? {};
+  const afterStart = policy.bookAfterStartPolicy?.enabled === true;
+  const first = toIso(raw.schedule?.firstSessionStart);
+  const last = toIso(raw.schedule?.lastSessionEnd);
+  let tooLate = false;
+  if (!afterStart && first && policy.limitLateBookingPolicy?.enabled) {
+    const latest = new Date(first).getTime() - (policy.limitLateBookingPolicy.latestBookingInMinutes ?? 0) * 60_000;
+    tooLate = now > latest;
+  }
+  const courseEnded = raw.type === "COURSE" && isMissingOrPast(last, now);
+  const started = !!first && isMissingOrPast(first, now);
+  return courseEnded || (started && !afterStart) || tooLate;
+}
+
+/**
+ * The CTA state: a course that is full or too late to book is only viewable; manual approval turns
+ * "Book" into "Request to book"; otherwise book. `courseFull` comes from the course's sessions
+ * (the booking flow supplies it; the listing passes false).
+ */
+export function ctaStateOf(service: Pick<ServiceSummary, "type" | "requiresManualApproval" | "tooLateToBook">, courseFull = false): CtaState {
+  if (service.type === "COURSE" && (courseFull || service.tooLateToBook)) return "viewCourse";
+  if (service.requiresManualApproval) return "requestToBook";
+  return "book";
+}
+
+/** A COURSE's span from its schedule; null for other types. */
+export function courseSpanOf(raw: Raw, now = Date.now()): CourseSpan | null {
+  if (raw.type !== "COURSE") return null;
+  const endDate = toIso(raw.schedule?.lastSessionEnd);
+  return { startDate: toIso(raw.schedule?.firstSessionStart), endDate, ended: isMissingOrPast(endDate, now) };
+}
+
+/** True for the three known types; an unknown type never becomes a DTO (Wix's own list would not render it either). */
+export const isKnownType = (raw: Raw): boolean => SERVICE_TYPES.includes(raw.type);
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc): ServiceSummary {
+  const priced = resolvePrice(raw);
+  const durationMinutes: number | null = raw.schedule?.availabilityConstraints?.sessionDurations?.[0] ?? null;
+  const type = (isKnownType(raw) ? raw.type : "APPOINTMENT") as ServiceType;
+  const requiresManualApproval = raw.onlineBooking?.requireManualApproval === true;
+  const tooLateToBook = isTooLateToBook(raw);
+  return {
+    id: rawId(raw),
+    slug: raw.mainSlug?.name ?? raw.supportedSlugs?.[0]?.name ?? "",
+    name: raw.name ?? "",
+    tagLine: raw.tagLine ?? "",
+    type,
+    ...priced,
+    durationMinutes,
+    durationLabel: durationLabel(durationMinutes),
+    imageUrl: imgSrc(mediaValue(raw.media?.mainMedia?.image), 800, 800),
+    categoryId: rawId(raw.category) || null,
+    categoryName: raw.category?.name ?? "",
+    scheduleId: rawId(raw.schedule) || null,
+    staff: toStaff(raw, imgSrc),
+    locations: ((raw.locations ?? []) as Raw[]).map(toLocation),
+    conferencing: raw.conferencing?.enabled === true,
+    hasAddOns: hasAddOns(raw),
+    requiresManualApproval,
+    onlineBookingEnabled: raw.onlineBooking?.enabled !== false,
+    tooLateToBook,
+    ctaState: ctaStateOf({ type, requiresManualApproval, tooLateToBook }),
+    defaultCapacity: raw.defaultCapacity ?? null,
+    maxParticipantsPerBooking: raw.bookingPolicy?.participantsPolicy?.maxParticipantsPerBooking ?? null,
+    deposit: depositOf(raw),
+    offeredDays: [],
+  };
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): ServiceDetail {
+  const summary = toSummary(raw, imgSrc);
+  const online = raw.payment?.options?.online === true;
+  const inPerson = raw.payment?.options?.inPerson === true;
+  // Derive — never hardcode "ONLINE": a free/pay-in-person service booked ONLINE gets rejected by the
+  // cart with INSUFFICIENT_INVENTORY. Online-only → ONLINE; in-person-only → OFFLINE; both/neither → ONLINE.
+  const paymentOption: "ONLINE" | "OFFLINE" = !online && inPerson ? "OFFLINE" : "ONLINE";
+  return {
+    ...summary,
+    description: raw.description ?? "",
+    formId: rawId(raw.form) || null,
+    paymentOption,
+    cancellationFeeEnabled: raw.bookingPolicy?.cancellationFeePolicy?.enabled === true,
+    course: courseSpanOf(raw),
+  };
+}
+
+export function toCategory(raw: Raw): BookingCategory {
+  return { id: rawId(raw), name: raw.name ?? "" };
+}
+
+/** Categories in the owner's order (`sortOrder`), ids present. */
+export function toCategories(raws: Raw[]): BookingCategory[] {
+  return [...raws].sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0)).map(toCategory).filter((c) => c.id);
+}
+
+/** Bookings settings (the SDK returns the entity, REST wraps it in `bookingsSettings`); the Wix default is the business zone. */
+export function toBookingsSettings(raw: Raw | null | undefined): BookingsSettings {
+  const settings: Raw = raw?.bookingsSettings ?? raw ?? {};
+  return {
+    displayTimeZone: settings.displayTimeZone?.basedOn === "CUSTOMER_TIME_ZONE" ? "CUSTOMER" : "BUSINESS",
+    customerCanChange: settings.displayTimeZone?.customerCanChange === true,
+  };
+}
+
+/** The settings when they can't be read — Wix's own fallback: business zone, no switching. */
+export const DEFAULT_BOOKINGS_SETTINGS: BookingsSettings = { displayTimeZone: "BUSINESS", customerCanChange: false };

package/skills/wix-headless-templates/bookings/app/wix/bookings/services-store.ts

@@ -0,0 +1,213 @@
+// The services listing as a framework-free store — the logic behind useServices, usable from React
+// (useServices wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. State, actions, subscribe/getState, emit after every
+// change. Category and location filters are applied by Wix (a fresh first page per selection, as its
+// own service list does), pages are 20 long with `hasMore`/`loadMore()`, and the selection lives in
+// the URL (`?category=`, `?location=`) so a filtered list is a link. After every page ONE batched
+// calendar call fills `offeredDays` on the classes and courses of that page.
+// SSR-friendly: seed with `initialServices` (+ `initialHasMore`, `initialCategories`, `initialLocations`)
+// and nothing is fetched for the first paint; without them `start()` loads everything.
+// One store per mounted listing: createServicesStore(), not a singleton.
+import { fetchOfferedDays } from "./booking";
+import { OTHER_LOCATIONS_ID, SERVICES_PAGE_SIZE, fetchBookingCategories, fetchLocations, fetchServices } from "./services";
+import type { BookingCategory, LocationOption, ServiceSummary } from "./types";
+
+export { OTHER_LOCATIONS_ID };
+
+const CATEGORY_PARAM = "category";
+const LOCATION_PARAM = "location";
+
+export interface ServicesStoreOptions {
+  initialServices?: ServiceSummary[];
+  /** Whether a page follows the seeded one (the page's `hasMore`); false when omitted. */
+  initialHasMore?: boolean;
+  initialCategories?: BookingCategory[];
+  initialLocations?: { locations: LocationOption[]; hasOtherLocations: boolean };
+  /** The selection the seeded services were fetched with (the page read it from the URL). */
+  initialCategoryId?: string | null;
+  initialLocationId?: string | null;
+  pageSize?: number;
+  /** Read the selection from `?category=`/`?location=` on start and write it back on change (default true). */
+  syncUrl?: boolean;
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface ServicesState {
+  /** null while the first page (of the current selection) is in flight — render skeletons, not an empty state. */
+  services: ServiceSummary[] | null;
+  categories: BookingCategory[];
+  /** Business locations hosting a bookable service; show a location filter only when there is more than one option. */
+  locations: LocationOption[];
+  /** Some services are held at custom/customer locations — offer OTHER_LOCATIONS_ID as an extra option. */
+  hasOtherLocations: boolean;
+  activeCategoryId: string | null;
+  /** A business location id, OTHER_LOCATIONS_ID, or null for all. */
+  activeLocationId: string | null;
+  /** Another page exists — render a "load more" affordance. */
+  hasMore: boolean;
+  loadingMore: boolean;
+  error: string | null;
+}
+
+export interface ServicesStore {
+  getState(): ServicesState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch whatever wasn't seeded (and the offered days of the seeded page). Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  setActiveCategoryId(id: string | null): void;
+  setActiveLocationId(id: string | null): void;
+  /** Append the next page. No-op while a page is loading or when none is left. */
+  loadMore(): Promise<void>;
+}
+
+const readParam = (name: string): string | null => {
+  if (typeof window === "undefined") return null;
+  try {
+    return new URL(window.location.href).searchParams.get(name) || null;
+  } catch {
+    return null;
+  }
+};
+
+const writeParams = (values: Record<string, string | null>): void => {
+  if (typeof window === "undefined" || typeof history === "undefined") return;
+  try {
+    const url = new URL(window.location.href);
+    for (const [k, v] of Object.entries(values)) v ? url.searchParams.set(k, v) : url.searchParams.delete(k);
+    history.replaceState(history.state, "", url.toString());
+  } catch {
+    /* an unusual URL — the selection still applies, it just isn't shareable */
+  }
+};
+
+export function createServicesStore({
+  initialServices,
+  initialHasMore = false,
+  initialCategories,
+  initialLocations,
+  initialCategoryId = null,
+  initialLocationId = null,
+  pageSize = SERVICES_PAGE_SIZE,
+  syncUrl = true,
+}: ServicesStoreOptions = {}): ServicesStore {
+  let services: ServiceSummary[] | null = initialServices ?? null;
+  let categories: BookingCategory[] = initialCategories ?? [];
+  let locations: LocationOption[] = initialLocations?.locations ?? [];
+  let hasOtherLocations = initialLocations?.hasOtherLocations ?? false;
+  let activeCategoryId: string | null = initialCategoryId;
+  let activeLocationId: string | null = initialLocationId;
+  let hasMore = initialHasMore;
+  let loadingMore = false;
+  let error: string | null = null;
+  let started = false;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+  let snapshot: ServicesState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): ServicesState {
+    if (snapshot) return snapshot;
+    snapshot = { services, categories, locations, hasOtherLocations, activeCategoryId, activeLocationId, hasMore, loadingMore, error };
+    return snapshot;
+  }
+
+  // One batched MASTER-events call per page: the weekdays every class/course on it meets (appointments have none).
+  function fillOfferedDays(items: ServiceSummary[], id: number): void {
+    const scheduleIds = [...new Set(items.filter((s) => s.type !== "APPOINTMENT").map((s) => s.scheduleId).filter((x): x is string => !!x))];
+    if (!scheduleIds.length) return;
+    fetchOfferedDays(scheduleIds).then((days) => {
+      if (!started || generation !== id || !services) return;
+      services = services.map((s) => (s.scheduleId && days[s.scheduleId] ? { ...s, offeredDays: days[s.scheduleId] } : s));
+      emit();
+    });
+  }
+
+  // The selection changed: a fresh first page from Wix (the filter is applied there, never to a page in hand).
+  function loadFirstPage(): void {
+    if (!started) return;
+    const id = ++generation;
+    services = null;
+    hasMore = false;
+    loadingMore = false; // an in-flight loadMore belongs to the old selection
+    error = null;
+    emit();
+    fetchServices({ limit: pageSize, offset: 0, categoryId: activeCategoryId, locationId: activeLocationId })
+      .then((page) => {
+        if (!started || generation !== id) return; // superseded — drop it
+        services = page.items;
+        hasMore = page.hasMore;
+        emit();
+        fillOfferedDays(page.items, id);
+      })
+      .catch((e) => {
+        if (!started || generation !== id) return;
+        services = [];
+        error = e instanceof Error ? e.message : String(e);
+        emit();
+      });
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      // The URL is the source of truth for the selection; a seeded page fetched with a different one is stale.
+      const urlCategory = syncUrl ? readParam(CATEGORY_PARAM) : null;
+      const urlLocation = syncUrl ? readParam(LOCATION_PARAM) : null;
+      const selectionChanged = syncUrl && ((urlCategory ?? null) !== activeCategoryId || (urlLocation ?? null) !== activeLocationId);
+      if (selectionChanged) {
+        activeCategoryId = urlCategory;
+        activeLocationId = urlLocation;
+      }
+      if (!initialServices || selectionChanged) loadFirstPage();
+      else fillOfferedDays(initialServices, generation);
+      if (!initialCategories) fetchBookingCategories().then((c) => { if (started) { categories = c; emit(); } });
+      if (!initialLocations) fetchLocations().then((l) => { if (started) { locations = l.locations; hasOtherLocations = l.hasOtherLocations; emit(); } });
+    },
+    stop() {
+      started = false;
+      generation++;
+    },
+    setActiveCategoryId(id) {
+      if (id === activeCategoryId) return;
+      activeCategoryId = id;
+      if (syncUrl) writeParams({ [CATEGORY_PARAM]: id });
+      loadFirstPage();
+    },
+    setActiveLocationId(id) {
+      if (id === activeLocationId) return;
+      activeLocationId = id;
+      if (syncUrl) writeParams({ [LOCATION_PARAM]: id });
+      loadFirstPage();
+    },
+    async loadMore() {
+      if (!started || loadingMore || !hasMore || !services) return;
+      const id = generation;
+      loadingMore = true;
+      emit();
+      try {
+        const page = await fetchServices({ limit: pageSize, offset: services.length, categoryId: activeCategoryId, locationId: activeLocationId });
+        if (!started || generation !== id) return;
+        services = [...services, ...page.items];
+        hasMore = page.hasMore;
+        fillOfferedDays(page.items, id);
+      } catch (e) {
+        if (!started || generation !== id) return;
+        error = e instanceof Error ? e.message : String(e);
+      } finally {
+        if (generation === id) loadingMore = false;
+        emit();
+      }
+    },
+  };
+}

package/skills/wix-headless-templates/bookings/app/wix/bookings/services.ts

@@ -0,0 +1,100 @@
+// Service reads (Wix Bookings Services V2) over the SDK — the only file that touches raw service
+// entities on this transport. Everything it returns is a plain DTO from ./types. The rules and
+// mappers live in ./services-core (shared with the REST twin in templates/bookings/rest/); this
+// file is the transport only. Copy as-is; extend by adding functions, not by editing these.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-locations.md
+import { services as servicesModule } from "@wix/bookings";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import {
+  BOOKINGS_APP_ID,
+  CATEGORIES_QUERY,
+  LOCATIONS_QUERY,
+  OTHER_LOCATIONS_ID,
+  SERVICES_CONDITIONAL_FIELDS,
+  SERVICES_PAGE_SIZE,
+  STAFF_RESOURCE_TYPE_ID,
+  isKnownType,
+  toCategories,
+  toDetail,
+  toLocationOptions,
+  toSummary,
+  type Raw,
+  type ServicesFilterOptions,
+} from "./services-core";
+import type { BookingCategory, LocationOption, ServiceDetail, ServiceSummary } from "./types";
+
+export { BOOKINGS_APP_ID, OTHER_LOCATIONS_ID, SERVICES_PAGE_SIZE, STAFF_RESOURCE_TYPE_ID };
+
+const services = wixModule(servicesModule);
+
+export interface FetchServicesOptions extends ServicesFilterOptions {
+  limit?: number;
+  offset?: number;
+}
+
+export interface ServicesPage {
+  items: ServiceSummary[];
+  /** Another page follows — pass `offset + items.length`. */
+  hasMore: boolean;
+}
+
+/**
+ * One page of bookable services (this app's, never hidden — filtered by the server), optionally one
+ * category and/or one business location (or OTHER_LOCATIONS_ID for custom/customer locations),
+ * mapped to grid-ready DTOs. Wix pages 20 at a time; `hasMore` says whether to ask for the next.
+ */
+export async function fetchServices({ limit = SERVICES_PAGE_SIZE, offset = 0, categoryId, locationId }: FetchServicesOptions = {}): Promise<ServicesPage> {
+  let query = services
+    .queryServices({ conditionalFields: SERVICES_CONDITIONAL_FIELDS as any })
+    .eq("appId", BOOKINGS_APP_ID)
+    .eq("hidden", false)
+    .limit(limit)
+    .skip(offset);
+  if (categoryId) query = query.eq("category.id", categoryId);
+  if (locationId === OTHER_LOCATIONS_ID) query = query.hasSome("locations.type" as any, ["CUSTOM", "CUSTOMER"] as any);
+  else if (locationId) query = query.eq("locations.business.id" as any, locationId);
+  const res = await query.find();
+  return { items: ((res.items ?? []) as Raw[]).filter(isKnownType).map((s) => toSummary(s, imgSrc)), hasMore: res.hasNext() };
+}
+
+/** Fetch one service by its URL slug (mainSlug.name). Null when not found. */
+export async function fetchServiceBySlug(slug: string): Promise<ServiceDetail | null> {
+  const res = await services
+    .queryServices({ conditionalFields: SERVICES_CONDITIONAL_FIELDS as any })
+    .eq("mainSlug.name", slug)
+    .eq("appId", BOOKINGS_APP_ID)
+    .eq("hidden", false)
+    .limit(1)
+    .find();
+  const raw = res.items?.[0] as Raw | undefined;
+  return raw && isKnownType(raw) ? toDetail(raw, imgSrc) : null;
+}
+
+/**
+ * Service categories for a filter bar — only categories that hold a bookable service, in the owner's
+ * order. Non-fatal (empty array on failure).
+ */
+export async function fetchBookingCategories(): Promise<BookingCategory[]> {
+  try {
+    const res: Raw = await services.queryCategories(CATEGORIES_QUERY as any);
+    return toCategories((res?.categories ?? []) as Raw[]);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Business locations that host a visible service (a listing filter, sorted by name) plus whether any
+ * service is held at a custom/customer location (the OTHER_LOCATIONS_ID bucket). Non-fatal.
+ */
+export async function fetchLocations(): Promise<{ locations: LocationOption[]; hasOtherLocations: boolean }> {
+  try {
+    const res: Raw = await services.queryLocations(LOCATIONS_QUERY as any);
+    return toLocationOptions(res);
+  } catch {
+    return { locations: [], hasOtherLocations: false };
+  }
+}