@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/rentals/project/src/wix/rentals/rentals-core.ts

@@ -0,0 +1,435 @@
+// Rentals rules — transport-agnostic, imported by BOTH transports: ./rentals.ts (the SDK) and the
+// REST twin in templates/rentals/rest/rentals.ts. What a rental IS (the five Bookings field values),
+// how its rate and range read, how the two availability flows work (hourly: start then end options;
+// daily: one call then a walk over consecutive days), the price preview, and the exact
+// createBooking → cart → checkout bodies live HERE, once. Type-only imports: a strip to JS emits a
+// plain module.
+//
+// Wix Rentals has no API of its own. A rental is a Bookings V2 APPOINTMENT service with:
+//   appId = RENTALS_APP_ID (immutable), serviceResources + primaryResourceType (a resource type and
+//   its resources; availability comes from them, not from staff), form.id = RENTALS_FORM_ID, and
+//   schedule.availabilityConstraints.durationRange (HOUR with hourOptions, or DAY with dayOptions)
+//   instead of sessionDurations. No category.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/rentals/introduction.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/rentals/wix-rentals-and-the-bookings-apis.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/rentals/about-wix-rentals-availability.md
+import type { EndOption, RentalDetail, RentalFormField, RentalLocation, RentalQuote, RentalResult, RentalSummary, RentalUnit, StartOption } from "./types";
+
+export type Raw = Record<string, any>;
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** The Wix Rentals app: the service's appId, the catalog filter, the cart's catalogReference.appId. */
+export const RENTALS_APP_ID = "ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e";
+/** The Rentals default booking form, provisioned by the install with the same id on every site. */
+export const RENTALS_FORM_ID = "3a2ea2ce-91f4-4617-ab24-629933c0c31a";
+export const RENTALS_PAGE_SIZE = 20;
+/** Slots per page the availability API allows; the transports follow the cursor. */
+export const SLOTS_PAGE_LIMIT = 1000;
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+// ---- money and labels ------------------------------------------------------------------------------
+
+/** "$40" from a Wix money-like `{ value, currency }`; "" when either is missing (never a guessed currency). */
+export function formatMoney(value: string | number | undefined | null, currency: string | undefined | null, locale?: string): string {
+  if (value == null || value === "" || !currency) return "";
+  const n = Number(value);
+  if (!Number.isFinite(n)) return "";
+  try {
+    const opts: Intl.NumberFormatOptions = { style: "currency", currency };
+    if (Number.isInteger(n)) opts.maximumFractionDigits = 0;
+    return new Intl.NumberFormat(locale, opts).format(n);
+  } catch {
+    return "";
+  }
+}
+
+const unitWord = (unit: RentalUnit, n: number): string => (unit === "DAY" ? (n === 1 ? "day" : "days") : n === 1 ? "hour" : "hours");
+
+/** "2 hours", "1.5 hours", "3 days". */
+export function unitsLabel(units: number, unit: RentalUnit): string {
+  const n = Math.round(units * 100) / 100;
+  return `${n} ${unitWord(unit, n)}`;
+}
+
+export function rangeLabel(minUnits: number, maxUnits: number, unit: RentalUnit): string {
+  if (!minUnits || !maxUnits) return "";
+  if (minUnits === maxUnits) return unitsLabel(minUnits, unit);
+  return `${Math.round(minUnits * 100) / 100} to ${unitsLabel(maxUnits, unit)}`;
+}
+
+// ---- dates ---------------------------------------------------------------------------------------------
+
+/** Local wall-clock "YYYY-MM-DDThh:mm:ss" for a Date (no zone, no Z) — the format the availability API speaks. */
+export function toLocalDateString(d: Date): string {
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+export const startOfDay = (d: Date): Date => new Date(d.getFullYear(), d.getMonth(), d.getDate());
+export const defaultTimeZone = (): string => Intl.DateTimeFormat().resolvedOptions().timeZone;
+export const dayKeyOf = (local: string): string => local.slice(0, 10);
+/** Midnight of the day after `dayKey`, as a local wall-clock string. */
+export function midnightAfter(dayKey: string): string {
+  const [y, m, d] = dayKey.split("-").map(Number);
+  return toLocalDateString(new Date(y, m - 1, d + 1));
+}
+export function addDaysKey(dayKey: string, days: number): string {
+  const [y, m, d] = dayKey.split("-").map(Number);
+  return toLocalDateString(new Date(y, m - 1, d + days)).slice(0, 10);
+}
+const minutesBetween = (a: string, b: string): number => Math.round((new Date(b).getTime() - new Date(a).getTime()) / 60000);
+
+export function timeLabel(local: string, locale?: string): string {
+  try {
+    return new Date(local).toLocaleTimeString(locale, { hour: "numeric", minute: "2-digit" });
+  } catch {
+    return local.slice(11, 16);
+  }
+}
+export function dayLabel(dayKey: string, locale?: string): string {
+  try {
+    const [y, m, d] = dayKey.split("-").map(Number);
+    return new Date(y, m - 1, d).toLocaleDateString(locale, { weekday: "short", month: "short", day: "numeric" });
+  } catch {
+    return dayKey;
+  }
+}
+
+// ---- the rental entity -----------------------------------------------------------------------------------
+
+export interface DurationRange {
+  unit: RentalUnit;
+  /** In the unit: hours (fractional allowed) or days. 0 when the range is missing. */
+  minUnits: number;
+  maxUnits: number;
+}
+
+/** The customer-pickable range off a service; HOUR minutes become hours. A service without one is not a rental. */
+export function durationRangeOf(raw: Raw): DurationRange | null {
+  const range: Raw | undefined = raw.schedule?.availabilityConstraints?.durationRange;
+  if (!range?.unitType) return null;
+  if (range.unitType === "DAY") {
+    const o = range.dayOptions ?? {};
+    return { unit: "DAY", minUnits: Number(o.minDurationInDays ?? 0), maxUnits: Number(o.maxDurationInDays ?? 0) };
+  }
+  const o = range.hourOptions ?? {};
+  return { unit: "HOUR", minUnits: Number(o.minDurationInMinutes ?? 0) / 60, maxUnits: Number(o.maxDurationInMinutes ?? 0) / 60 };
+}
+
+/** A service is a rental when it carries the Rentals app id AND a duration range. */
+export const isRental = (raw: Raw): boolean => raw?.appId === RENTALS_APP_ID && durationRangeOf(raw) !== null;
+
+export function toLocation(raw: Raw): RentalLocation {
+  const type = (["BUSINESS", "CUSTOM", "CUSTOMER"].includes(raw?.type) ? raw.type : "BUSINESS") as RentalLocation["type"];
+  return { id: rawId(raw?.business) || null, name: raw?.business?.name ?? raw?.custom?.address?.formattedAddress ?? "", type };
+}
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc): RentalSummary {
+  const range = durationRangeOf(raw) ?? { unit: "HOUR" as RentalUnit, minUnits: 0, maxUnits: 0 };
+  const payment: Raw = raw.payment ?? {};
+  const price: Raw | undefined = payment.fixed?.price;
+  const rateAmount = Number(price?.value ?? 0) || 0;
+  const currency: string = price?.currency ?? "";
+  const free = payment.rateType === "NO_FEE" || (payment.rateType === "FIXED" && rateAmount === 0);
+  const ratePerUnit = free ? "Free" : formatMoney(price?.value, currency);
+  const serviceResources = (raw.serviceResources ?? []) as Raw[];
+  const resourceTypeId: string | null = raw.primaryResourceType ?? rawId(serviceResources[0]?.resourceType) ?? null;
+  const resourceCount = serviceResources.reduce((n, sr) => n + ((sr.resourceIds?.values ?? []) as string[]).length, 0);
+  return {
+    id: rawId(raw),
+    slug: raw.mainSlug?.name ?? "",
+    name: raw.name ?? "",
+    tagLine: raw.tagLine ?? "",
+    unit: range.unit,
+    ratePerUnit,
+    rateLabel: ratePerUnit && !free ? `${ratePerUnit} / ${unitWord(range.unit, 1)}` : ratePerUnit,
+    rateAmount,
+    currency,
+    minUnits: range.minUnits,
+    maxUnits: range.maxUnits,
+    rangeLabel: rangeLabel(range.minUnits, range.maxUnits, range.unit),
+    imageUrl: raw.media?.mainMedia?.image ? imgSrc(raw.media.mainMedia.image, 800, 600) : "",
+    resourceTypeId: resourceTypeId || null,
+    resourceCount,
+    locations: ((raw.locations ?? []) as Raw[]).map(toLocation),
+    onlineBookingEnabled: raw.onlineBooking?.enabled !== false,
+    requiresManualApproval: raw.onlineBooking?.requireManualApproval === true,
+    free,
+  };
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): RentalDetail {
+  const summary = toSummary(raw, imgSrc);
+  const online = raw.payment?.options?.online === true;
+  const inPerson = raw.payment?.options?.inPerson === true;
+  // Derived, never hardcoded: an in-person-only (or free) rental booked ONLINE is refused by the cart.
+  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,
+    scheduleId: rawId(raw.schedule) || null,
+  };
+}
+
+// ---- availability: starts ------------------------------------------------------------------------------
+
+export interface StartWindow {
+  /** First day of the window (defaults to today); the window is `days` long. */
+  from?: Date;
+  days?: number;
+  /** IANA zone the local times are expressed in; the business zone when omitted (daily rentals need the business zone). */
+  timeZone?: string;
+  cursor?: string;
+}
+
+/**
+ * The List Availability Time Slots body for a rental. `includeResourceTypeIds` = the rental's
+ * primary resource type — without it the slots come back with no resource to book. A DAILY rental
+ * asks for one slot per day (the start of each available day).
+ */
+export function startsRequest(rental: Pick<RentalDetail, "id" | "unit" | "resourceTypeId">, { from = new Date(), days = 7, timeZone, cursor }: StartWindow): Raw {
+  const start = startOfDay(from);
+  const end = new Date(start.getFullYear(), start.getMonth(), start.getDate() + days);
+  return {
+    serviceId: rental.id,
+    fromLocalDate: toLocalDateString(start),
+    toLocalDate: toLocalDateString(end), // exclusive: midnight after the last day, never 23:59:59
+    ...(timeZone ? { timeZone } : {}),
+    ...(rental.resourceTypeId ? { includeResourceTypeIds: [rental.resourceTypeId] } : {}),
+    bookable: true,
+    ...(rental.unit === "DAY" ? { timeSlotsPerDay: 1 } : {}),
+    cursorPaging: { limit: SLOTS_PAGE_LIMIT, ...(cursor ? { cursor } : {}) },
+  };
+}
+export const nextSlotsCursor = (res: Raw | null | undefined): string | null => res?.pagingMetadata?.cursors?.next ?? res?.cursorPagingMetadata?.cursors?.next ?? null;
+
+const toSlotLocation = (raw: Raw | undefined): RentalLocation | null => {
+  if (!raw || (!rawId(raw) && !raw.name)) return null;
+  const type = (["BUSINESS", "CUSTOM", "CUSTOMER"].includes(raw.locationType) ? raw.locationType : "BUSINESS") as RentalLocation["type"];
+  return { id: rawId(raw) || null, name: raw.name ?? "", type };
+};
+
+export function toStartOption(raw: Raw, unit: RentalUnit): StartOption {
+  const start: string = raw.localStartDate ?? "";
+  const resource: Raw | undefined = ((raw.availableResources ?? []) as Raw[]).flatMap((ar) => (ar.resources ?? []) as Raw[])[0];
+  return {
+    key: `${start}|${rawId(raw.location)}`,
+    startLocal: start,
+    dayKey: dayKeyOf(start),
+    label: unit === "DAY" ? dayLabel(dayKeyOf(start)) : timeLabel(start),
+    bookable: raw.bookable !== false,
+    location: toSlotLocation(raw.location),
+    resource: resource && rawId(resource) ? { id: rawId(resource), name: resource.name ?? "" } : null,
+    scheduleId: raw.scheduleId ?? null,
+  };
+}
+
+/** Raw slots from one or more pages → deduped (one per start and location), ordered. */
+export function toStartOptions(raws: Raw[], unit: RentalUnit): StartOption[] {
+  const byKey = new Map<string, Raw>();
+  for (const raw of raws) {
+    const key = `${raw.localStartDate ?? ""}|${rawId(raw.location)}`;
+    const seen = byKey.get(key);
+    if (!seen) byKey.set(key, raw);
+    else if (!seen.availableResources?.length && raw.availableResources?.length) byKey.set(key, raw);
+  }
+  return [...byKey.values()].map((r) => toStartOption(r, unit)).sort((a, b) => a.startLocal.localeCompare(b.startLocal));
+}
+
+// ---- availability: lengths ----------------------------------------------------------------------------
+
+/**
+ * HOURLY: the List Availability Time Slot End Options body for a chosen start. `location` is
+ * required and is the start's own; the service's maximum caps the response, so no maxLocalEndDate.
+ * The SDK takes `serviceId` as a positional first argument; REST sends it in the body. `idKey`
+ * spells the location id the way the transport wants it: `_id` on the SDK, `id` on REST.
+ */
+export function endOptionsRequest(start: StartOption, timeZone: string | null | undefined, idKey: "_id" | "id" = "id"): Raw {
+  return {
+    localStartDate: start.startLocal,
+    ...(timeZone ? { timeZone } : {}),
+    location: start.location
+      ? { ...(start.location.id ? { [idKey]: start.location.id } : {}), name: start.location.name, locationType: start.location.type }
+      : { locationType: "BUSINESS" },
+  };
+}
+
+/** HOURLY end options (the response field is `endOptions`, not `timeSlots`) → lengths, shortest first. */
+export function toHourlyEndOptions(res: Raw | null | undefined, start: StartOption): EndOption[] {
+  return ((res?.endOptions ?? []) as Raw[])
+    .map((o) => o.localEndDate as string)
+    .filter(Boolean)
+    .map((endLocal) => {
+      const units = minutesBetween(start.startLocal, endLocal) / 60;
+      return { endLocal, units, label: `${unitsLabel(units, "HOUR")} · until ${timeLabel(endLocal)}` };
+    })
+    .filter((o) => o.units > 0)
+    .sort((a, b) => a.units - b.units);
+}
+
+/**
+ * DAILY: there is no end-options call. From the chosen start day, walk forward through the available
+ * days and stop at the first gap or at the rental's maximum; each reachable length is an option whose
+ * end is midnight on the day AFTER its last day. A 24/7 resource (the seed's default) takes the whole
+ * range as ONE booking.
+ */
+export function dailyEndOptions(start: StartOption, availableDayKeys: string[], range: Pick<RentalDetail, "minUnits" | "maxUnits">): EndOption[] {
+  const available = new Set(availableDayKeys);
+  const out: EndOption[] = [];
+  let lastDay = start.dayKey;
+  for (let days = 1; days <= Math.max(1, Math.floor(range.maxUnits)); days++) {
+    const day = addDaysKey(start.dayKey, days - 1);
+    if (!available.has(day)) break;
+    lastDay = day;
+    if (days >= Math.max(1, Math.floor(range.minUnits))) {
+      out.push({ endLocal: midnightAfter(lastDay), units: days, label: days === 1 ? `1 day · ${dayLabel(lastDay)}` : `${days} days · until ${dayLabel(lastDay)}` });
+    }
+  }
+  return out;
+}
+
+// ---- price -------------------------------------------------------------------------------------------------
+
+/**
+ * Preview Price line items for a rental: one line, ONE participant (a rental takes one resource; the
+ * length drives the price), the resource, and BOTH local dates with the zone — without all three the
+ * server silently returns a duration-blind flat rate.
+ */
+export function previewRequest(rental: Pick<RentalDetail, "id">, start: StartOption, endLocal: string, timeZone: string): Raw[] {
+  return [
+    {
+      serviceId: rental.id,
+      ...(start.resource ? { resourceId: start.resource.id } : {}),
+      numberOfParticipants: 1,
+      localStartDate: start.startLocal,
+      localEndDate: endLocal,
+      timeZone,
+    },
+  ];
+}
+
+/** The server's total (`priceInfo.calculatedPrice`), or the local rate times the length when the preview fails. */
+export function toQuote(res: Raw | null | undefined, rental: Pick<RentalDetail, "rateAmount" | "currency" | "unit">, units: number): RentalQuote {
+  const server = res?.priceInfo?.calculatedPrice;
+  const totalAmount = typeof server === "number" && Number.isFinite(server) ? server : Math.round(rental.rateAmount * units * 100) / 100;
+  return { total: formatMoney(totalAmount, rental.currency), totalAmount, units, unit: rental.unit };
+}
+
+// ---- the booking form ---------------------------------------------------------------------------------
+
+export const FALLBACK_FIELDS: RentalFormField[] = [
+  { target: "first_name", label: "First Name", type: "STRING", required: true },
+  { target: "last_name", label: "Last Name", type: "STRING", required: true },
+  { target: "email", label: "Email", type: "EMAIL", required: true },
+];
+const FIELD_TYPES = ["STRING", "EMAIL", "PHONE", "NUMBER", "URL"];
+
+/** Flat, render-ready fields from a form summary (+ the full schema for `required`); never empty. */
+export function toFormFields(summary: Raw | null | undefined, form?: Raw | null): RentalFormField[] {
+  const requiredByTarget = new Map<string, boolean>(((form?.fields ?? []) as Raw[]).filter((f) => f.target).map((f) => [f.target as string, f.validation?.required === true]));
+  const fields = ((summary?.fields ?? []) as Raw[])
+    .filter((f) => !f.deleted && f.type && FIELD_TYPES.includes(f.type))
+    .map((f) => ({
+      target: f.target ?? "",
+      label: f.label ?? f.target ?? "",
+      type: f.type as RentalFormField["type"],
+      ...(Array.isArray(f.options) && f.options.length ? { options: f.options as string[] } : {}),
+      required: requiredByTarget.get(f.target ?? "") ?? true,
+    }))
+    .filter((f) => f.target);
+  return fields.length ? fields : FALLBACK_FIELDS;
+}
+
+// ---- createBooking → cart → checkout-or-place -------------------------------------------------------------
+
+/** A start's location type → the booking's. */
+export function bookingLocationType(type: RentalLocation["type"] | undefined): "OWNER_BUSINESS" | "CUSTOM" | "OWNER_CUSTOM" {
+  if (type === "CUSTOMER") return "CUSTOM";
+  if (type === "CUSTOM") return "OWNER_CUSTOM";
+  return "OWNER_BUSINESS";
+}
+
+/**
+ * The Create Booking `booking` object for a rental: the start's schedule, the chosen start and END
+ * (the customer's length, never a duration added to the start), the zone, the start's RESOURCE (rentals
+ * are resource-driven: no ANY_RESOURCE staff fallback), and the start's location. `idKey` spells ids
+ * the way the transport wants them: `_id` on the SDK, `id` on REST.
+ */
+export function bookingRequest(rental: Pick<RentalDetail, "id" | "paymentOption">, start: StartOption, endLocal: string, timeZone: string, idKey: "_id" | "id" = "id"): Raw {
+  if (!start.resource) throw new Error("This time has no resource to rent — pick another start.");
+  return {
+    selectedPaymentOption: rental.paymentOption,
+    totalParticipants: 1,
+    bookedEntity: {
+      slot: {
+        serviceId: rental.id,
+        ...(start.scheduleId ? { scheduleId: start.scheduleId } : {}),
+        startDate: start.startLocal,
+        endDate: endLocal,
+        timezone: timeZone,
+        // availableResources carries ids only (no names, verified live) — send the name only when known
+        resource: { [idKey]: start.resource.id, ...(start.resource.name ? { name: start.resource.name } : {}) },
+        location: start.location
+          ? { ...(start.location.id ? { [idKey]: start.location.id } : {}), name: start.location.name, locationType: bookingLocationType(start.location.type) }
+          : { locationType: "OWNER_BUSINESS" },
+      },
+    },
+  };
+}
+
+/** The rest of the Create Booking request: the form values as the formSubmission, and Wix's own notifications. */
+export function bookingOptions(formValues: Record<string, unknown>): Raw {
+  return {
+    participantNotification: { notifyParticipants: true, metadata: { channels: "EMAIL,SMS" } },
+    sendSmsReminder: true,
+    formSubmission: formValues,
+  };
+}
+
+export const bookingIdOf = (res: Raw | null | undefined): string => rawId(res?.booking);
+export const contactOf = (res: Raw | null | undefined): Raw | undefined => res?.booking?.contactDetails ?? undefined;
+
+/** The Create Cart body holding the booking: catalogItemId is the BOOKING id and appId the RENTALS app. */
+export function cartRequest(bookingIds: string[], contact?: Raw | null, locationId?: string | null): Raw {
+  const cart: Raw = { source: { channelType: "WEB" } };
+  if (locationId) cart.businessInfo = { locationId };
+  if (contact) {
+    cart.customerInfo = {
+      ...(contact.firstName ? { firstName: contact.firstName } : {}),
+      ...(contact.lastName ? { lastName: contact.lastName } : {}),
+      ...(contact.phone ? { phone: contact.phone } : {}),
+      ...(contact.email ? { email: contact.email } : {}),
+    };
+  }
+  return { catalogItems: bookingIds.map((id) => ({ quantity: 1, catalogReference: { catalogItemId: id, appId: RENTALS_APP_ID } })), cart };
+}
+
+export const cartIdOf = (res: Raw | null | undefined): string => rawId(res) || rawId(res?.cart);
+export const cartTotal = (calc: Raw | null | undefined): number => Number(calc?.summary?.priceSummary?.total?.amount ?? 0);
+
+/** Hosted checkout whenever a card is involved: a cancellation fee, or a non-zero total not paid fully offline. */
+export function checkoutRequired(rental: Pick<RentalDetail, "cancellationFeeEnabled">, calc: Raw | null | undefined): boolean {
+  if (rental.cancellationFeeEnabled) return true;
+  if (cartTotal(calc) === 0) return false;
+  return calc?.cart?.lineItems?.[0]?.paymentConfig?.paymentOption !== "FULL_PAYMENT_OFFLINE";
+}
+
+export function checkoutRedirectRequest(cartId: string, origin: string): Raw {
+  return { ecomCheckout: { checkoutId: cartId }, callbacks: origin ? { postFlowUrl: `${origin}/` } : {} };
+}
+
+export function confirmedResult(bookingId: string, order: Raw | null | undefined): RentalResult {
+  return { kind: "confirmed", bookingId, orderId: order?.orderId ?? (rawId(order?.order) || null) };
+}
+
+/** Wix's refusal codes a visitor sees, in plain words. */
+export function friendlyError(message: string): string {
+  if (/SLOT_NOT_AVAILABLE/.test(message)) return "That time was just taken. Pick another start.";
+  if (/INVALID_DURATION/.test(message)) return "That length is outside what this rental allows. Pick another length.";
+  if (/PREMIUM_VALIDATION_FAILED|SITE_NOT_ACCEPTING/.test(message)) return "This site cannot take online bookings yet (no payment method or plan). Contact the business directly.";
+  if (/END_OPTIONS_NOT_SUPPORTED/.test(message)) return "This rental is booked by the day.";
+  return message;
+}

package/skills/wix-headless-templates/rentals/project/src/wix/rentals/rentals-store.ts

@@ -0,0 +1,112 @@
+// The rentals listing as a framework-free store — the logic behind useRentals, usable from React
+// (useRentals wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. Pages are 20 long with `hasMore`/`loadMore()`.
+// SSR-friendly: seed with `initialRentals` (+ `initialHasMore`) and nothing is fetched for the first
+// paint; without them `start()` loads the first page. One store per mounted listing.
+import { RENTALS_PAGE_SIZE, fetchRentals } from "./rentals";
+import type { RentalSummary } from "./types";
+
+export interface RentalsStoreOptions {
+  initialRentals?: RentalSummary[];
+  /** Whether a page follows the seeded one (the page's `hasMore`); false when omitted. */
+  initialHasMore?: boolean;
+  pageSize?: number;
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface RentalsState {
+  /** null while the first page is in flight — render skeletons, not an empty state. */
+  rentals: RentalSummary[] | null;
+  /** Another page exists — render a "load more" affordance. */
+  hasMore: boolean;
+  loadingMore: boolean;
+  error: string | null;
+}
+
+export interface RentalsStore {
+  getState(): RentalsState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the first page unless it was seeded. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  /** Append the next page. No-op while a page is loading or when none is left. */
+  loadMore(): Promise<void>;
+}
+
+export function createRentalsStore({ initialRentals, initialHasMore = false, pageSize = RENTALS_PAGE_SIZE }: RentalsStoreOptions = {}): RentalsStore {
+  let rentals: RentalSummary[] | null = initialRentals ?? null;
+  let hasMore = initialHasMore;
+  let loadingMore = false;
+  let error: string | null = null;
+  let started = false;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+  let snapshot: RentalsState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): RentalsState {
+    if (snapshot) return snapshot;
+    snapshot = { rentals, hasMore, loadingMore, error };
+    return snapshot;
+  }
+
+  function loadFirstPage(): void {
+    const id = ++generation;
+    rentals = null;
+    hasMore = false;
+    error = null;
+    emit();
+    fetchRentals({ limit: pageSize, offset: 0 })
+      .then((page) => {
+        if (!started || generation !== id) return; // superseded — drop it
+        rentals = page.items;
+        hasMore = page.hasMore;
+        emit();
+      })
+      .catch((e) => {
+        if (!started || generation !== id) return;
+        rentals = [];
+        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;
+      if (!initialRentals) loadFirstPage();
+    },
+    stop() {
+      started = false;
+      generation++;
+    },
+    async loadMore() {
+      if (!started || loadingMore || !hasMore || !rentals) return;
+      const id = generation;
+      loadingMore = true;
+      emit();
+      try {
+        const page = await fetchRentals({ limit: pageSize, offset: rentals.length });
+        if (!started || generation !== id) return;
+        rentals = [...rentals, ...page.items];
+        hasMore = page.hasMore;
+      } catch (e) {
+        if (!started || generation !== id) return;
+        error = e instanceof Error ? e.message : String(e);
+      } finally {
+        if (generation === id) loadingMore = false;
+        emit();
+      }
+    },
+  };
+}