@curless/hotel-storefront 0.28.0 → 0.29.0

package/dist/huazhu/backend.js

@@ -86,6 +86,21 @@ const WINDOW = {
     '3': 'No window',
     '4': 'Window onto an inner courtyard',
 };
+/** The same, as Huazhu's own dictionary says it - for a connector that speaks Chinese. */
+const WINDOW_ZH = {
+    '1': '有窗',
+    '2': '部分有窗',
+    '3': '无窗',
+    '4': '内窗(朝天井)',
+};
+/** A rate's meal in Chinese, by its code; room only is 不含早. */
+const MEAL_ZH = {
+    BB: '含早',
+    BF: '含自助早',
+    HB: '含半餐',
+    FB: '含全餐',
+    AI: '全包',
+};
 const pool = async (items, n, fn) => {
     const out = new Array(items.length);
     let next = 0;
@@ -268,12 +283,43 @@ export const englishFits = (hotels, ref) => {
  * "Sun 11 Oct, 00:00" for a stay arriving on Saturday the 10th - read as a
  * day more than there is (2026-10-05 audit, P3). Said as the 10th, 24:00.
  */
-export const deadlineAt = (instant, tz) => {
+export const deadlineAt = (instant, tz, language = 'en') => {
+    if (language === 'zh')
+        return deadlineZh(instant, tz);
     const shown = atHotelTime(instant, tz);
     if (!/, 00:00\b/.test(shown))
         return shown;
     return atHotelTime(instant - 60_000, tz).replace(/, 23:59\b/, ', 24:00');
 };
+/**
+ * The same deadline in Chinese - "10月25日 周日 18:00", midnight still the
+ * day before's 24:00. A connector that speaks Chinese had its card say
+ * "Sun 25 Oct, 18:00" beside Chinese words (香格里拉, 2026-10-12).
+ */
+const deadlineZh = (instant, tz) => {
+    const parts = (at) => {
+        const p = Object.fromEntries(new Intl.DateTimeFormat('en-GB', {
+            timeZone: tz,
+            month: 'numeric',
+            day: 'numeric',
+            weekday: 'short',
+            hour: '2-digit',
+            minute: '2-digit',
+            hourCycle: 'h23',
+        })
+            .formatToParts(at)
+            .map((x) => [x.type, x.value]));
+        const week = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(String(p.weekday));
+        return {
+            day: `${Number(p.month)}月${Number(p.day)}日 周${'日一二三四五六'[week] ?? ''}`,
+            time: `${p.hour}:${p.minute}`,
+        };
+    };
+    const now = parts(instant);
+    if (now.time !== '00:00')
+        return `${now.day} ${now.time}`;
+    return `${parts(instant - 60_000).day} 24:00`;
+};
 /**
  * How a fresh price differs from what the guest was shown - or nothing, when
  * it does not. See `ShownQuote`.
@@ -302,6 +348,15 @@ export const movedSince = (shown, q) => {
 };
 export const createHuazhuHotels = (opts) => {
     const { client, catalog, store, reconciler } = opts;
+    // ⚠️ NO MONEY TAKEN FOR A REAL HUAZHU YET: who takes it, the licence, a
+    // partial refund, mixed trips, invoices and VCC are robin's to decide
+    // (总线程, 2026-10-12). Prepaid runs against the simulated Huazhu only.
+    if (opts.prepaid && !opts.sandbox)
+        throw new Error('prepaid rates are sold against the simulated Huazhu only, until robin decides who takes the money (docs/huazhu-products-plan.md)');
+    const checkout = opts.prepaid?.checkout;
+    /** Unpaid this long, the page is closed and the booking lapses - inside the card page's own ~31 minutes. */
+    const payWithin = opts.prepaid?.payWithinMs ?? 30 * 60_000;
+    const prepaidType = checkout ? 'OPN' : undefined;
     const now = opts.now ?? (() => Date.now());
     const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const ariTtl = opts.ariTtlMs ?? 60_000;
@@ -314,6 +369,14 @@ export const createHuazhuHotels = (opts) => {
     /** A room as offered - type and rate - in the connector's language. */
     const offerOf = (p) => (en ? offerNameEn(p.roomTypeName, p.rateCodeName) : undefined) ??
         [p.roomTypeName, p.rateCodeName].filter(Boolean).join(' · ');
+    /** A rate's meal as the trip line says it, in the connector's language. */
+    const mealWords = (r) => en
+        ? r.meal
+            ? `${r.meal}${r.mealCount > 1 ? ` × ${r.mealCount}` : ''}`
+            : 'Room only'
+        : r.meal
+            ? `${MEAL_ZH[r.mealType] ?? '含餐'}${r.mealCount > 1 ? ` × ${r.mealCount}` : ''}`
+            : '不含早';
     /** A rate's own name in the connector's language, or Huazhu's words as they are. */
     const rateNameOf = (p) => (en ? rateNameEn(p.rateCodeName) : undefined) ?? p.rateCodeName ?? p.rateCode;
     const today = () => todayAt(now(), opts.tz);
@@ -529,6 +592,7 @@ export const createHuazhuHotels = (opts) => {
             today: today(),
             clock: clockAt(now(), opts.tz),
             paymentType: opts.paymentType,
+            ...(prepaidType ? { prepaidType } : {}),
             allowTags,
         };
         return products
@@ -605,6 +669,7 @@ export const createHuazhuHotels = (opts) => {
             today: date,
             clock,
             paymentType: opts.paymentType,
+            ...(prepaidType ? { prepaidType } : {}),
             allowTags,
         };
         return live
@@ -645,7 +710,9 @@ export const createHuazhuHotels = (opts) => {
             sleeps: s.sleeps,
             ...(rt?.hotelArea ? { sizeSqm: rt.hotelArea } : {}),
             ...(beds.length ? { beds: beds.join(' / ') } : {}),
-            ...(rt?.isHasWindow && WINDOW[rt.isHasWindow] ? { view: WINDOW[rt.isHasWindow] } : {}),
+            ...(rt?.isHasWindow && (en ? WINDOW : WINDOW_ZH)[rt.isHasWindow]
+                ? { view: (en ? WINDOW : WINDOW_ZH)[rt.isHasWindow] }
+                : {}),
             breakfast: !!s.meal,
             ...(roomPhoto(h, p.product.roomTypeCode)
                 ? { imageUrl: roomPhoto(h, p.product.roomTypeCode) }
@@ -666,21 +733,41 @@ export const createHuazhuHotels = (opts) => {
                     // ⚠️ ON THE HOTEL'S CLOCK. Without it the guest read "10:00 (UTC)"
                     // for what a Shanghai desk calls 18:00 - found by the Huazhu evals
                     // (2026-10-05).
-                    freeCancellationLocal: deadlineAt(freeUntil, opts.tz),
+                    freeCancellationLocal: deadlineAt(freeUntil, opts.tz, en ? 'en' : 'zh'),
                 }
                 : {}),
             roomsLeft: s.roomsLeft,
             roomType: { id: p.product.roomTypeCode, name: roomTypeOf(p.product) },
             rate: { id: p.product.rateCode, name: rateNameOf(p.product) },
             labels: rateLabels(p.product, { type: s.mealType, count: s.mealCount }),
-            // ⚠️ AT THE HOTEL, ALWAYS, HERE: prepaid rates are left out before
-            // this (`sell`, kind 'prepaid') until robin decides how that money is
-            // taken - a live deployment never offers one (总线程, 2026-10-12).
-            payment: 'at-hotel',
+            // ⚠️ PREPAID ONLY WHERE THIS DEPLOYMENT TAKES PAYMENT - a sandbox's test
+            // mode (`opts.prepaid`); everywhere else `sell` leaves prepaid rates out
+            // and every room is paid at the hotel (总线程, 2026-10-12).
+            payment: s.prepaid ? 'prepaid' : 'at-hotel',
             ...(hourly ? { hourly } : {}),
             ...(maxChildren > 0 && maxChildren < 99 ? { maxChildren } : {}),
         };
     };
+    /** The most a room here sleeps, from rates refused for the party ("sleeps 2"). */
+    const largestOf = (fails) => Math.max(...fails.map((f) => Number(/\d+/.exec(f.why)?.[0] ?? 0)));
+    /**
+     * Why no room by the hour can be sold here today.
+     *
+     * ⚠️ A PARTY TOO BIG IS SAID AS partyNeeds SAYS IT, as for nights: the card
+     * reads "the largest sleeps N" from that sentence to offer more rooms with
+     * fewer in each (香格里拉, 2026-10-12). Three guests at a hotel whose hourly
+     * rooms sleep two were told none was left.
+     */
+    const hourlyNoRoomsWhy = (priced, guests) => {
+        if (priced.length === 0)
+            return 'This hotel sells no rooms by the hour today.';
+        const fails = priced.map((p) => p.res).filter((r) => !r.ok);
+        if (fails.length > 0 && fails.every((f) => f.kind === 'party'))
+            return partyNeeds(guests, largestOf(fails));
+        if (fails.some((f) => f.kind === 'prepaid'))
+            return "This hotel's rooms by the hour are paid in advance, and this connector books rates paid at the hotel.";
+        return 'No room by the hour is left here today.';
+    };
     /** Why nothing here can be sold for these nights - the most useful reason first. */
     const noRoomsWhy = (priced, stay, rooms) => {
         if (priced.length === 0)
@@ -688,10 +775,8 @@ export const createHuazhuHotels = (opts) => {
         const fails = priced.map((p) => p.res).filter((r) => !r.ok);
         const kinds = new Set(fails.map((f) => f.kind));
         const only = (k) => kinds.size === 1 && kinds.has(k);
-        if (only('party')) {
-            const largest = Math.max(...fails.map((f) => Number(/\d+/.exec(f.why)?.[0] ?? 0)));
-            return partyNeeds(stay.guests, largest);
-        }
+        if (only('party'))
+            return partyNeeds(stay.guests, largestOf(fails));
         if (only('prepaid'))
             return 'Every rate here for those nights is paid in advance, and this connector books rates paid at the hotel.';
         if (only('sold-out'))
@@ -819,9 +904,7 @@ export const createHuazhuHotels = (opts) => {
                 detail: [
                     room.beds,
                     room.view,
-                    p.res.meal
-                        ? `${p.res.meal}${p.res.mealCount > 1 ? ` × ${p.res.mealCount}` : ''}`
-                        : 'Room only',
+                    mealWords(p.res),
                     hourly ? `${hourly.start}–${endOf(hourly.start, hourly.hours)}` : undefined,
                 ]
                     .filter(Boolean)
@@ -829,11 +912,15 @@ export const createHuazhuHotels = (opts) => {
                 stay: line.stay,
                 nights: room.nights,
                 ...(hourly ? { hourly } : {}),
+                ...(room.payment === 'prepaid' ? { payment: 'prepaid' } : {}),
                 quantity: wanted,
                 unit: room.nightly,
                 total: money(preTax, room.stayTotal.currency),
                 refundable: room.refundable,
                 freeCancellationUntil: room.freeCancellationUntil,
+                ...(room.freeCancellationLocal
+                    ? { freeCancellationLocal: room.freeCancellationLocal }
+                    : {}),
                 day: line.stay.checkIn,
             });
         }
@@ -869,6 +956,33 @@ export const createHuazhuHotels = (opts) => {
         return q;
     };
     // ------------------------------------------------------------ bookings ----
+    /** The money's side of a booking paid in advance, as the guest is shown it. */
+    const paymentOf = (b) => {
+        const p = b.prepaid;
+        const refund = p.refund;
+        const status = refund
+            ? refund.status === 'refunded'
+                ? 'refunded'
+                : 'refunding'
+            : p.lapsedAt
+                ? 'lapsed'
+                : p.paidAt
+                    ? 'paid'
+                    : 'awaiting';
+        return {
+            method: p.method,
+            amount: b.quote.total,
+            status,
+            ...(status === 'awaiting' && p.url ? { url: p.url } : {}),
+            ...(status === 'awaiting'
+                ? {
+                    payBy: new Date(p.payBy).toISOString(),
+                    payByLocal: deadlineAt(p.payBy, b.tz, en ? 'en' : 'zh'),
+                }
+                : {}),
+            ...(refund ? { refundReason: refund.reason } : {}),
+        };
+    };
     const publicBooking = (b) => ({
         id: b.id,
         confirmationCode: b.confirmationCode,
@@ -883,6 +997,7 @@ export const createHuazhuHotels = (opts) => {
         ...(b.cancelledAt ? { cancelledAt: b.cancelledAt } : {}),
         ...(b.cancellationFee ? { cancellationFee: b.cancellationFee } : {}),
         ...(b.requests ? { requests: b.requests } : {}),
+        ...(b.prepaid ? { payment: paymentOf(b) } : {}),
     });
     /**
      * The codes a guest may have been given for a booking: ours, and the
@@ -919,7 +1034,15 @@ export const createHuazhuHotels = (opts) => {
         return there;
     };
     /** Huazhu's own word on a booking, at most once a minute each. */
-    const refresh = async (b) => {
+    const refresh = async (found) => {
+        // A page open for payment, or money going back, is looked at as it is
+        // asked about - the guest who just paid sees it booked without waiting
+        // for the next pass.
+        let b = found;
+        if (b.prepaid && moneyPending(b)) {
+            await settlePrepaid(b);
+            b = store.get(b.id) ?? b;
+        }
         if (!b.resId || b.pendingSince !== undefined)
             return b;
         if (b.refreshedAt && now() - b.refreshedAt < 60_000)
@@ -1003,7 +1126,11 @@ export const createHuazhuHotels = (opts) => {
     const conversationOf = (who) => who.tripOwner ?? who.sessionId;
     /** A name for a booking in what the guest is told. */
     const named = (b) => `${b.hotelName} (${b.confirmationCode})`;
-    const isLive = (b) => (b.status === 'confirmed' || b.status === 'requested' || b.status === 'unconfirmed') &&
+    const isLive = (b) => (b.status === 'confirmed' ||
+        b.status === 'requested' ||
+        b.status === 'unconfirmed' ||
+        // A page open for payment holds its place in the limits until it closes.
+        b.status === 'awaiting-payment') &&
         !b.rollback &&
         b.stay.checkOut >= today();
     /** The booking itself, one request at a time per conversation and email - see `single`. */
@@ -1097,6 +1224,197 @@ export const createHuazhuHotels = (opts) => {
             },
         }
         : { checkin: line.stay.checkIn, checkout: line.stay.checkOut };
+    /**
+     * Books a stay the guest has paid for - the request made from what was
+     * prebooked and written down, at the price Huazhu's prebook vouched for.
+     * Huazhu's "no" refunds the money in full; no answer leaves it to the
+     * reconciler, whose write-off or "nobody could confirm it" refunds it too
+     * (`settlePrepaid`).
+     */
+    const bookPaid = async (id) => {
+        const row = store.get(id);
+        const p = row?.prepaid;
+        if (!row || !p?.paidAt || row.status !== 'awaiting-payment')
+            return;
+        const contact = contactOf(row.guest);
+        if (typeof contact === 'string') {
+            store.update(id, { status: 'failed' });
+            await refundOf(id, "the guest's name could not be sent to Huazhu as written");
+            return;
+        }
+        const comment = commentOf(row.requests, row.guest.notes);
+        const request = {
+            hotelId: row.hotelId,
+            checkinType: row.hourly ? 'HOUR' : 'DAY',
+            contactPerson: contact,
+            distributorResId: row.distributorResId,
+            paymentType: row.paymentType,
+            reservations: [
+                {
+                    roomTypeCode: row.roomTypeCode,
+                    rateCode: row.rateCode,
+                    ...stayDatesOf(row),
+                    amountAfterTax: p.after,
+                    ...(p.before ? { amountBeforeTax: p.before } : {}),
+                    ...(p.rack ? { rackRate: p.rack } : {}),
+                    currencyCode: p.currency,
+                    roomCount: row.rooms,
+                    adultCount: row.stay.guests,
+                    guaranteePolicyCode: row.guaranteeCode,
+                    ...(row.requests?.arrivingAt ? { estimatedArrivalTime: row.requests.arrivingAt } : {}),
+                    resGuest: [contact],
+                },
+            ],
+            ...(comment ? { guestComment: comment } : {}),
+            ...(p.preBookToken ? { preBookToken: p.preBookToken } : {}),
+        };
+        // ⚠️ SET BEFORE THE CALL, as every booking is: a process that dies in it
+        // leaves a row the reconciler follows up.
+        store.update(id, { status: 'requested', pendingSince: now() });
+        let refusal;
+        let answer;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                const got = await client.book(request);
+                if (got && typeof got.resId === 'string' && got.resId)
+                    answer = got;
+            }
+            catch (err) {
+                if (err instanceof HuazhuRefusal && err.code === CODES.systemError && attempt === 0) {
+                    await sleep(1_000);
+                    continue;
+                }
+                if (err instanceof HuazhuRefusal &&
+                    BOOK_REFUSALS.has(err.code) &&
+                    !BOOK_EXISTS.has(err.code))
+                    refusal = err;
+            }
+            break;
+        }
+        if (answer) {
+            store.update(id, {
+                resId: answer.resId,
+                ...(answer.resCode ? { resCode: answer.resCode } : {}),
+                status: 'confirmed',
+                hotelStatus: 'HOTEL_RESERVATION',
+                pendingSince: undefined,
+            });
+            return;
+        }
+        if (refusal) {
+            store.update(id, { status: 'failed', pendingSince: undefined });
+            // A price that moved since the prebook is one of these (5209): the
+            // guest paid for a price Huazhu no longer gives, and gets it all back.
+            await refundOf(id, `Huazhu did not take the booking: ${refusal.huazhuMessage} (${refusal.code})`);
+        }
+        // No answer: the reconciler's eight minutes decide it.
+    };
+    /**
+     * Gives a guest's money back, in full - the only refund the gateway makes.
+     * Written down with the gateway's checkout session (its payment intent)
+     * and, once open, its refund request: the two ids the money is found by.
+     */
+    const refundOf = async (id, reason) => {
+        const row = store.get(id);
+        const p = row?.prepaid;
+        if (!row || !p?.sessionId || !p.paidAt || !checkout || p.refund?.requestId)
+            return;
+        const tries = (p.refund?.tries ?? 0) + 1;
+        const at = p.refund?.at ?? now();
+        try {
+            const r = await checkout.refund(p.sessionId, reason);
+            store.update(id, {
+                prepaid: { ...p, refund: { reason, at, requestId: r.requestId, status: r.status, tries } },
+            });
+            console.error(`[huazhu prepaid ${id}] refund ${r.requestId} (${r.status}) of session ${p.sessionId}: ${reason}`);
+        }
+        catch (err) {
+            store.update(id, { prepaid: { ...p, refund: { reason, at, tries } } });
+            if (tries >= 8 && !row.attention) {
+                const why = `the guest paid (gateway session ${p.sessionId}) and the refund could not be opened: ${err.message}`;
+                store.update(id, { attention: why, attentionAt: new Date(now()).toISOString() });
+                console.error(`[huazhu prepaid ${id}] ⚠️ NEEDS A PERSON: ${why}`);
+            }
+        }
+    };
+    /** Whether a booking paid in advance still has money work to do. */
+    const moneyPending = (b) => {
+        const p = b.prepaid;
+        if (!p)
+            return false;
+        if (b.status === 'awaiting-payment')
+            return true;
+        if (!p.paidAt)
+            return false;
+        if (!p.refund?.requestId)
+            return !!p.refund || b.status === 'failed' || b.status === 'unconfirmed';
+        return !['refunded', 'failed', 'rejected'].includes(p.refund.status ?? '');
+    };
+    /**
+     * One step for a booking paid in advance: a page paid → booked; a page
+     * unpaid past its time → closed (so it cannot be paid later) and lapsed; a
+     * paid booking Huazhu did not take, or nobody could confirm → refunded in
+     * full; a refund under way → followed to its end.
+     */
+    const settlePrepaid = async (found) => {
+        const row = store.get(found.id) ?? found;
+        const p = row.prepaid;
+        if (!p || !checkout)
+            return;
+        if (row.status === 'awaiting-payment') {
+            if (!p.sessionId) {
+                if (now() >= p.payBy)
+                    store.update(row.id, { status: 'expired', prepaid: { ...p, lapsedAt: now() } });
+                return;
+            }
+            let state;
+            try {
+                state = await checkout.state(p.sessionId);
+                if (state === 'open' && now() >= p.payBy)
+                    state = await checkout.close(p.sessionId);
+            }
+            catch {
+                return; // asked again on the next pass
+            }
+            if (state === 'paid') {
+                store.update(row.id, { prepaid: { ...p, paidAt: now(), url: undefined } });
+                await bookPaid(row.id);
+            }
+            else if (state === 'closed') {
+                store.update(row.id, {
+                    status: 'expired',
+                    prepaid: { ...p, lapsedAt: now(), url: undefined },
+                });
+            }
+            return;
+        }
+        if (!p.paidAt)
+            return;
+        if (!p.refund?.requestId &&
+            (p.refund || row.status === 'failed' || row.status === 'unconfirmed')) {
+            await refundOf(row.id, p.refund?.reason ??
+                (row.status === 'failed'
+                    ? 'Huazhu did not take the booking'
+                    : 'nobody could confirm the booking with Huazhu - if it turns up there, a person cancels it'));
+            return;
+        }
+        const refund = p.refund;
+        if (refund?.requestId && !['refunded', 'failed', 'rejected'].includes(refund.status ?? '')) {
+            try {
+                const status = await checkout.refundState(refund.requestId);
+                if (status !== refund.status)
+                    store.update(row.id, { prepaid: { ...p, refund: { ...refund, status } } });
+                if ((status === 'failed' || status === 'rejected') && !row.attention) {
+                    const why = `refund ${refund.requestId} of gateway session ${p.sessionId} came back ${status}: the guest's money is not back`;
+                    store.update(row.id, { attention: why, attentionAt: new Date(now()).toISOString() });
+                    console.error(`[huazhu prepaid ${row.id}] ⚠️ NEEDS A PERSON: ${why}`);
+                }
+            }
+            catch {
+                // asked again on the next pass
+            }
+        }
+    };
     const bookHeld = async (lines, shown, tripKey, email, guest, contact, who, requests, slot) => {
         // Priced afresh, not from the cache: this is the price that will be sent.
         const priced = await quoteLines({ lines }, true);
@@ -1118,6 +1436,11 @@ export const createHuazhuHotels = (opts) => {
                 throw new Error('Nothing was booked: the trip changed while it was being priced.');
             plans.push({ i, line, sold, qline });
         }
+        // ⚠️ A STAY PAID IN ADVANCE IS BOOKED ON ITS OWN (v1): its money is taken
+        // before Huazhu is asked, and a trip half paid and half not - or two paid
+        // stays, one refused - has no whole refund to give (总线程, 2026-10-12).
+        if (plans.length > 1 && plans.some((p) => p.sold.res.prepaid))
+            throw new Error('Nothing was booked: a stay paid in advance is booked on its own here. Take the other stays out of the trip, book this one, then book the rest.');
         for (const plan of plans) {
             const s = plan.sold.res;
             const title = `${plan.qline.hotelName} - ${plan.qline.title}`;
@@ -1125,7 +1448,7 @@ export const createHuazhuHotels = (opts) => {
                 const out = await client.prebook({
                     hotelId: plan.line.hotelId,
                     checkinType: plan.line.hourly ? 'HOUR' : 'DAY',
-                    paymentType: opts.paymentType,
+                    paymentType: plan.sold.res.paymentType,
                     reservations: [
                         {
                             roomTypeCode: plan.sold.product.roomTypeCode,
@@ -1150,6 +1473,92 @@ export const createHuazhuHotels = (opts) => {
         requestsByEmail.add(email);
         requestsByConversation.add(conversationOf(who));
         const tripRef = randomUUID();
+        // ⚠️ PAID FIRST, BOOKED AFTER. A stay paid in advance is not asked of
+        // Huazhu until the guest has paid on the gateway's card page - then
+        // `settlePrepaid` books it, and gives the money back whole if it cannot.
+        const prepaidPlan = plans.find((p) => p.sold.res.prepaid);
+        if (prepaidPlan) {
+            const plan = prepaidPlan;
+            const s = plan.sold.res;
+            if (!checkout)
+                throw new Error('Nothing was booked: this deployment takes no payment.');
+            const rooms = plan.qline.quantity ?? 1;
+            const qTotal = plan.qline.total.minor;
+            const nightlyMinor = s.after.map((x) => toMinor(x, s.currency));
+            const allIn = nightlyMinor.reduce((a, b) => a + b, 0) * rooms;
+            const cur = s.currency;
+            const id = `hz_${randomUUID()}`;
+            const dres = distributorResId();
+            const record = {
+                method: checkout.method,
+                payBy: now() + payWithin,
+                ...(plan.token ? { preBookToken: plan.token } : {}),
+                after: s.after,
+                ...(s.before ? { before: s.before } : {}),
+                ...(s.rack ? { rack: s.rack } : {}),
+                currency: cur,
+            };
+            const row = {
+                id,
+                confirmationCode: newPublicCode((c) => store.all().some((b) => b.confirmationCode === c)),
+                status: 'awaiting-payment',
+                createdAt: new Date(now()).toISOString(),
+                hotelId: plan.line.hotelId,
+                hotelName: plan.qline.hotelName,
+                stay: plan.line.stay,
+                ...(plan.line.hourly ? { hourly: plan.line.hourly } : {}),
+                guest,
+                quote: {
+                    lines: [plan.qline],
+                    subtotal: money(qTotal, cur),
+                    taxesAndFees: money(allIn - qTotal, cur),
+                    ...(s.before ? {} : { taxesIncluded: true }),
+                    total: money(allIn, cur),
+                    stay: plan.line.stay,
+                },
+                ...(clean ? { requests: clean } : {}),
+                owners: [...new Set([who.sessionId, conversationOf(who)])],
+                distributorResId: dres,
+                tripRef,
+                tripKey,
+                paymentType: s.paymentType,
+                guaranteeCode: s.guaranteeCode,
+                cancelCode: s.cancelCode,
+                nightlyMinor,
+                rooms,
+                tz: opts.tz,
+                roomTypeCode: plan.sold.product.roomTypeCode,
+                rateCode: plan.sold.product.rateCode,
+                prepaid: record,
+            };
+            try {
+                store.put(row);
+            }
+            catch (err) {
+                if (err instanceof StoreWriteError)
+                    throw new Error('Nothing was booked or charged: the booking could not be written down here, so no payment was asked for. A person has been told.');
+                throw err;
+            }
+            slot.n -= 1;
+            let opened;
+            try {
+                opened = await checkout.open({
+                    ref: dres,
+                    title: `${plan.qline.hotelName} · ${plan.qline.title}`.slice(0, 200),
+                    amountMinor: allIn,
+                    currency: cur,
+                });
+            }
+            catch (err) {
+                store.update(id, { status: 'failed' });
+                throw new Error(`Nothing was booked or charged: the payment page could not be opened (${err.message}). Asking again is safe.`);
+            }
+            return [
+                publicBooking(store.update(id, {
+                    prepaid: { ...record, sessionId: opened.sessionId, url: opened.url },
+                }) ?? row),
+            ];
+        }
         const made = [];
         /**
          * Undo what this trip booked, when a later stay of it failed - and say
@@ -1254,7 +1663,7 @@ export const createHuazhuHotels = (opts) => {
                     distributorResId: dres,
                     tripRef,
                     tripKey,
-                    paymentType: opts.paymentType,
+                    paymentType: s.paymentType,
                     guaranteeCode: s.guaranteeCode,
                     cancelCode: s.cancelCode,
                     nightlyMinor,
@@ -1299,7 +1708,7 @@ export const createHuazhuHotels = (opts) => {
                     checkinType: plan.line.hourly ? 'HOUR' : 'DAY',
                     contactPerson: contact,
                     distributorResId: dres,
-                    paymentType: opts.paymentType,
+                    paymentType: s.paymentType,
                     reservations: [reservation],
                     ...(comment ? { guestComment: comment } : {}),
                     ...(plan.token ? { preBookToken: plan.token } : {}),
@@ -1374,7 +1783,21 @@ export const createHuazhuHotels = (opts) => {
     };
     return {
         brand: opts.brand,
-        capabilities: { ...HUAZHU_CAPABILITIES, ...(opts.hourly ? { hourly: true } : {}) },
+        capabilities: {
+            ...HUAZHU_CAPABILITIES,
+            ...(opts.hourly ? { hourly: true } : {}),
+            ...(checkout ? { prepaid: true } : {}),
+        },
+        /**
+         * One pass over the bookings paid in advance - every 10 seconds while the
+         * deployment takes payment (make.ts): pages paid or past their time, and
+         * money going back.
+         */
+        async prepaidTick() {
+            for (const row of store.all())
+                if (moneyPending(row))
+                    await settlePrepaid(row);
+        },
         imageDomains() {
             const hosts = new Set();
             for (const h of catalog.all()) {
@@ -1524,7 +1947,7 @@ export const createHuazhuHotels = (opts) => {
                         const priced = await priceHourly(raw, stay.guests, wantRooms);
                         pricedRooms.set(raw.hotelId, priced);
                         if (!priced.some((p) => p.res.ok))
-                            why.set(raw.hotelId, 'No room by the hour here today.');
+                            why.set(raw.hotelId, hourlyNoRoomsWhy(priced, stay.guests));
                     }
                     catch {
                         pricedRooms.set(raw.hotelId, []);
@@ -1574,8 +1997,16 @@ export const createHuazhuHotels = (opts) => {
             if (priceEverything)
                 await pool(matches.map((m) => m.raw), PRICE_CONCURRENCY, priceHotel);
             const canRoomFilter = priceEverything;
+            // ⚠️ A HOTEL WHOSE ROOMS BY THE HOUR ARE ONLY TOO SMALL STILL SELLS
+            // THEM: it stays, with partyNeeds as its reason, so the card can offer
+            // more rooms with fewer in each (香格里拉, 2026-10-12) - three guests
+            // were shown no hotel at all, as if none sold rooms by the hour.
+            const tooSmallOnly = (raw) => {
+                const priced = pricedRooms.get(raw.hotelId) ?? [];
+                return priced.length > 0 && priced.every((p) => !p.res.ok && p.res.kind === 'party');
+            };
             if (canRoomFilter && (roomTerms || hourlyOnly))
-                matches = matches.filter(({ raw }) => bestFor(raw, f) !== null);
+                matches = matches.filter(({ raw }) => bestFor(raw, f) !== null || (hourlyOnly && !roomTerms && tooSmallOnly(raw)));
             const currencies = [...new Set(matches.map((m) => m.hotel.currency))].sort();
             const onePrice = currencies.length === 1;
             const ceiling = priceEverything && onePrice && Number(q.maxNightly) > 0 ? Number(q.maxNightly) : undefined;
@@ -1774,13 +2205,12 @@ export const createHuazhuHotels = (opts) => {
                 .filter((p) => p.res.ok)
                 .map((p) => toRoom(raw, p, stay))
                 .sort((a, b) => a.stayTotal.minor - b.stayTotal.minor);
-            const why = priced.length === 0
-                ? 'This hotel sells no rooms by the hour today.'
-                : priced.some((p) => !p.res.ok && p.res.kind === 'prepaid') &&
-                    priced.every((p) => !p.res.ok)
-                    ? "This hotel's rooms by the hour are paid in advance, and this connector books rates paid at the hotel."
-                    : 'No room by the hour is left here today.';
-            return { hotel, stay, rooms, ...(rooms.length === 0 ? { noRooms: why } : {}) };
+            return {
+                hotel,
+                stay,
+                rooms,
+                ...(rooms.length === 0 ? { noRooms: hourlyNoRoomsWhy(priced, guests) } : {}),
+            };
         },
         async datesAround(id, stay, o) {
             const raw = findHotel(id);
@@ -1820,6 +2250,7 @@ export const createHuazhuHotels = (opts) => {
                     today: from,
                     clock: clockAt(now(), opts.tz),
                     paymentType: opts.paymentType,
+                    ...(prepaidType ? { prepaidType } : {}),
                     allowTags,
                 };
                 let cheapest;
@@ -1899,7 +2330,13 @@ export const createHuazhuHotels = (opts) => {
             const mine = store
                 .all()
                 .filter((b) => b.owners.includes(who.sessionId) &&
-                !(b.status === 'failed' && !b.resId && b.pendingSince === undefined && !b.attention))
+                // A refused booking is nothing to show - unless the guest paid for
+                // it: their money going back is.
+                !(b.status === 'failed' &&
+                    !b.resId &&
+                    b.pendingSince === undefined &&
+                    !b.attention &&
+                    !b.prepaid?.paidAt))
                 .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
                 .slice(0, most);
             const fresh = await pool(mine, 3, (b) => refresh(b));
@@ -1939,6 +2376,16 @@ export const createHuazhuHotels = (opts) => {
             const cur = b.quote.total.currency;
             const zero = money(0, cur);
             const past = now() >= nightAuditOf(b.stay.checkIn, b.tz);
+            if (b.status === 'awaiting-payment') {
+                return {
+                    bookingId: b.id,
+                    confirmationCode: b.confirmationCode,
+                    fee: zero,
+                    refund: zero,
+                    rule: 'Not paid yet, and nothing is booked with Huazhu: cancelling closes the payment page, and nothing is charged.',
+                    cancellable: true,
+                };
+            }
             if (b.pendingSince !== undefined || b.status === 'unconfirmed') {
                 return {
                     bookingId: b.id,
@@ -1962,6 +2409,24 @@ export const createHuazhuHotels = (opts) => {
                 };
             }
             const { fee, forbidden, rule, freeUntil } = feeNow(b);
+            if (b.prepaid?.paidAt) {
+                // Paid here in advance: free means all of it back, anything else -
+                // the whole stay, on these rates - means none.
+                const back = !forbidden && fee === 0;
+                return {
+                    bookingId: b.id,
+                    confirmationCode: b.confirmationCode,
+                    fee: money(forbidden ? 0 : fee, cur),
+                    refund: back ? b.quote.total : zero,
+                    rule: forbidden
+                        ? `This rate cannot be cancelled now. ${rule} The ${formatMoney(b.quote.total)} paid stays paid.`
+                        : back
+                            ? `${rule} Cancelling now gives back all ${formatMoney(b.quote.total)} paid, to the card it was paid with.${opts.sandbox ? ' This is a test booking in the simulated Huazhu, paid in the gateway’s test mode: no real money moves.' : ''}`
+                            : `${rule} Cancelling now gives nothing back: the fee is the whole stay.`,
+                    ...(freeUntil ? { freeUntil: new Date(freeUntil).toISOString() } : {}),
+                    cancellable: !forbidden,
+                };
+            }
             return {
                 bookingId: b.id,
                 confirmationCode: b.confirmationCode,
@@ -1982,6 +2447,19 @@ export const createHuazhuHotels = (opts) => {
             if (!found)
                 return null;
             const b = await refresh(found);
+            // Not paid yet: the page is closed, so it cannot be paid after this.
+            if (b.status === 'awaiting-payment' && b.prepaid?.sessionId && checkout) {
+                const state = await checkout.close(b.prepaid.sessionId).catch(() => undefined);
+                if (state === 'closed') {
+                    return publicBooking(store.update(b.id, {
+                        status: 'expired',
+                        prepaid: { ...b.prepaid, lapsedAt: now(), url: undefined },
+                    }) ?? b);
+                }
+                // Paid in the last second: it is booked now, and cancelled as one.
+                await settlePrepaid(b);
+                throw new Error('The guest has just paid, so the stay is being booked with Huazhu now. Ask again in a moment to cancel it - a cancellation in the free period gives all the money back.');
+            }
             if (b.pendingSince !== undefined || b.status === 'unconfirmed') {
                 throw new Error(waitingWords(b));
             }
@@ -1995,12 +2473,18 @@ export const createHuazhuHotels = (opts) => {
                 const fee = typeof out.penaltyAmount === 'number'
                     ? money(toMinor(out.penaltyAmount, out.penaltyCurrencyCode || cur), out.penaltyCurrencyCode || cur)
                     : money(feeNow(b).fee, cur);
-                return publicBooking(store.update(b.id, {
+                const cancelled = store.update(b.id, {
                     status: 'cancelled',
                     hotelStatus: 'HOTEL_CANCEL',
                     cancelledAt: new Date(now()).toISOString(),
                     cancellationFee: fee,
-                }) ?? b);
+                }) ?? b;
+                // Paid in advance and cancelled free: all of it back. A fee here is
+                // the whole stay (only whole-or-nothing rates are sold this way), so
+                // nothing comes back.
+                if (cancelled.prepaid?.paidAt && fee.minor === 0)
+                    await refundOf(b.id, 'cancelled within the free cancellation period');
+                return publicBooking(store.get(b.id) ?? cancelled);
             }
             catch (err) {
                 if (err instanceof HuazhuRefusal && err.code === 5402) {