@aglyn/plugins-bookings 1.0.0-beta.221 → 1.0.0-beta.222

package/src/lib/transfer/bookings-transfer.js

@@ -0,0 +1,613 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { TRANSFER_ID_FIELD, buildMatchLookup } from "@aglyn/aglyn/data-transfer";
+import { zonedDateTime } from "@aglyn/shared-util-timestamp/zoned-time";
+import { FieldPath } from "firebase-admin/firestore";
+import { bookingTimeZone, storedBookingTimeZone } from "../model/booking-time.js";
+import { BOOKINGS_TRANSFER_MATCH_KEYS, parseBookingsTransferFilter } from "./bookings-transfer-common.js";
+/** The most rows one page answers when the engine does not say. */ const DEFAULT_PAGE_ROWS = 500;
+const MAX_PAGE_ROWS = 1000;
+/** Firestore's bound on an `in` list. */ const IN_LIMIT = 30;
+/*==========================================
+ * THE FIELDS
+ *=========================================*/ export const BOOKINGS_TRANSFER_GROUPS = [
+    {
+        id: 'booking',
+        label: 'Booking'
+    },
+    {
+        id: 'customer',
+        label: 'Customer'
+    },
+    {
+        id: 'payment',
+        label: 'Payment'
+    },
+    {
+        id: 'system',
+        label: 'System'
+    }
+];
+const readOnly = (field)=>_extends({}, field, {
+        readOnly: true
+    });
+/** The booking's own stored fields. */ const STANDARD = [
+    {
+        id: 'serviceId',
+        label: 'Service ID',
+        group: 'booking',
+        type: 'text',
+        description: 'The service that was booked.'
+    },
+    {
+        id: 'serviceName',
+        label: 'Service',
+        group: 'booking',
+        type: 'text',
+        aliases: [
+            'service name'
+        ],
+        description: 'The service’s name when it was booked.'
+    },
+    {
+        id: 'startsAt',
+        label: 'Starts (UTC)',
+        group: 'booking',
+        type: 'datetime',
+        aliases: [
+            'start',
+            'starts at',
+            'start time'
+        ]
+    },
+    {
+        id: 'endsAt',
+        label: 'Ends (UTC)',
+        group: 'booking',
+        type: 'datetime',
+        aliases: [
+            'end',
+            'ends at',
+            'end time'
+        ]
+    },
+    {
+        id: 'timeZone',
+        label: 'Time zone',
+        group: 'booking',
+        type: 'text',
+        aliases: [
+            'timezone'
+        ],
+        description: 'The zone the slot was offered in. Bookings made before it was stored read it from the service, then the site.'
+    },
+    {
+        id: 'status',
+        label: 'Status',
+        group: 'booking',
+        type: 'text',
+        description: 'Awaiting payment, Confirmed or Canceled.'
+    },
+    {
+        id: 'name',
+        label: 'Name',
+        group: 'customer',
+        type: 'text',
+        aliases: [
+            'customer',
+            'customer name'
+        ]
+    },
+    {
+        id: 'email',
+        label: 'Email',
+        group: 'customer',
+        type: 'email',
+        aliases: [
+            'customer email'
+        ]
+    },
+    {
+        id: 'phone',
+        label: 'Phone',
+        group: 'customer',
+        type: 'phone'
+    },
+    {
+        id: 'address',
+        label: 'Address',
+        group: 'customer',
+        type: 'longText',
+        description: 'Where the job is, as the customer typed it, when the service asked.'
+    },
+    {
+        id: 'crmRef',
+        label: 'CRM record',
+        group: 'customer',
+        type: 'text',
+        description: 'The CRM record the booking link carried, as kind:id.'
+    },
+    {
+        id: 'paidAmount',
+        label: 'Amount paid',
+        group: 'payment',
+        type: 'currency',
+        description: 'In US dollars, tax included.'
+    },
+    {
+        id: 'tax',
+        label: 'Tax',
+        group: 'payment',
+        type: 'currency',
+        description: 'In US dollars.'
+    },
+    {
+        id: 'fee',
+        label: 'Platform fee',
+        group: 'payment',
+        type: 'currency',
+        description: 'The platform’s fee on the charge, in US dollars.'
+    },
+    {
+        id: 'refunded',
+        label: 'Refunded',
+        group: 'payment',
+        type: 'currency',
+        description: 'In US dollars.'
+    },
+    {
+        id: 'taxMode',
+        label: 'Tax mode',
+        group: 'payment',
+        type: 'text',
+        description: 'How tax was charged on the booking.'
+    }
+].map(readOnly);
+/** Computed from the booking and its service when read. */ const DERIVED = [
+    {
+        id: 'serviceCurrentName',
+        label: 'Service (current name)',
+        group: 'booking',
+        type: 'text',
+        description: 'The service’s name today; blank when the service no longer exists.'
+    },
+    {
+        id: 'startsLocal',
+        label: 'Starts (local time)',
+        group: 'booking',
+        type: 'text',
+        description: 'The start as a clock in the booking’s time zone read it.'
+    },
+    {
+        id: 'endsLocal',
+        label: 'Ends (local time)',
+        group: 'booking',
+        type: 'text',
+        description: 'The end as a clock in the booking’s time zone read it.'
+    },
+    {
+        id: 'durationMinutes',
+        label: 'Duration (minutes)',
+        group: 'booking',
+        type: 'integer'
+    }
+].map(readOnly);
+/** Written by the platform: Stripe's handles and the booking's history. */ const SYSTEM = [
+    {
+        id: 'paymentIntentId',
+        label: 'Stripe payment ID',
+        group: 'payment',
+        type: 'text'
+    },
+    {
+        id: 'checkoutSessionId',
+        label: 'Stripe checkout session ID',
+        group: 'payment',
+        type: 'text'
+    },
+    {
+        id: 'holdExpiresAt',
+        label: 'Payment hold expires',
+        group: 'payment',
+        type: 'datetime',
+        description: 'When an unpaid booking’s slot is released.'
+    },
+    {
+        id: 'createdAt',
+        label: 'Booked',
+        group: 'system',
+        type: 'datetime'
+    },
+    {
+        id: 'confirmedAt',
+        label: 'Payment confirmed',
+        group: 'system',
+        type: 'datetime'
+    },
+    {
+        id: 'reminderSentAt',
+        label: 'Reminder sent',
+        group: 'system',
+        type: 'datetime'
+    },
+    {
+        id: 'customerErasedAt',
+        label: 'Customer erased',
+        group: 'system',
+        type: 'datetime',
+        description: 'When the customer’s details were erased from the booking.'
+    }
+].map(readOnly);
+/** The catalog, the same for every site. */ export function bookingsTransferCatalog() {
+    return {
+        standard: STANDARD,
+        derived: DERIVED,
+        system: SYSTEM,
+        groups: BOOKINGS_TRANSFER_GROUPS
+    };
+}
+const STATUS_LABELS = {
+    pendingPayment: 'Awaiting payment',
+    confirmed: 'Confirmed',
+    canceled: 'Canceled'
+};
+/*==========================================
+ * READING A BOOKING
+ *=========================================*/ /** Epoch milliseconds from a stored moment: a number, a Timestamp, a Date or a string. */ function millisOf(value) {
+    if (value === null || value === undefined || value === '') return null;
+    if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+    if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.getTime() : null;
+    if (typeof value === 'string') {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    if (typeof value === 'object') {
+        var _stamp_seconds, _ref, _stamp_nanoseconds;
+        const stamp = value;
+        if (typeof stamp.toMillis === 'function') return stamp.toMillis();
+        const seconds = (_stamp_seconds = stamp.seconds) != null ? _stamp_seconds : stamp._seconds;
+        if (typeof seconds === 'number') return seconds * 1000 + Math.floor(((_ref = (_stamp_nanoseconds = stamp.nanoseconds) != null ? _stamp_nanoseconds : stamp._nanoseconds) != null ? _ref : 0) / 1e6);
+    }
+    return null;
+}
+function isoOf(value) {
+    const ms = millisOf(value);
+    return ms === null ? null : new Date(ms).toISOString();
+}
+/** Dollars from stored cents; blank when the booking holds none. */ function dollarsOf(cents) {
+    if (cents === null || cents === undefined || cents === '') return null;
+    const value = Number(cents);
+    return Number.isFinite(value) ? Math.round(value) / 100 : null;
+}
+function textOf(value) {
+    if (value === null || value === undefined) return null;
+    const text = String(value);
+    return text === '' ? null : text;
+}
+const pad = (value)=>String(value).padStart(2, '0');
+/** `2026-04-24 15:00` — the wall clock in `timeZone` at `atMs`. */ function localTextOf(atMs, timeZone) {
+    if (atMs === null) return null;
+    try {
+        const at = zonedDateTime(atMs, timeZone);
+        return `${at.year}-${pad(at.month)}-${pad(at.day)} ${pad(at.hour)}:${pad(at.minute)}`;
+    } catch (unused) {
+        return null;
+    }
+}
+function pageContext(db, ctx, hostId) {
+    let services = null;
+    let site = null;
+    const servicesOfSite = ()=>services != null ? services : services = db.collection('hosts').doc(hostId).collection('services').get().then((snapshot)=>new Map(snapshot.docs.map((doc)=>[
+                    doc.id,
+                    doc.data()
+                ])));
+    const siteZones = ()=>site != null ? site : site = Promise.all([
+            db.collection('hosts').doc(hostId).get(),
+            db.collection('orgs').doc(ctx.orgId).get()
+        ]).then(([host, org])=>{
+            var _host_data, _org_data;
+            return {
+                host: (_host_data = host.data()) != null ? _host_data : null,
+                org: (_org_data = org.data()) != null ? _org_data : null
+            };
+        });
+    return {
+        serviceOf: async (serviceId)=>{
+            var _get;
+            return (_get = (await servicesOfSite()).get(serviceId)) != null ? _get : null;
+        },
+        async zoneOf (booking) {
+            const stored = storedBookingTimeZone(booking);
+            if (stored) return stored;
+            // Written before the zone was stored: the booking route's own chain.
+            const [service, zones] = await Promise.all([
+                servicesOfSite().then((all)=>{
+                    var _all_get, _booking_serviceId;
+                    return (_all_get = all.get(String((_booking_serviceId = booking['serviceId']) != null ? _booking_serviceId : ''))) != null ? _all_get : null;
+                }),
+                siteZones()
+            ]);
+            return bookingTimeZone({
+                service: service,
+                host: zones.host,
+                org: zones.org
+            });
+        }
+    };
+}
+const ZONE_FIELDS = new Set([
+    'timeZone',
+    'startsLocal',
+    'endsLocal'
+]);
+/** One booking as a row holding only `fieldIds`. */ async function bookingRow(id, booking, fieldIds, page) {
+    const startsAtMs = millisOf(booking['startsAtMs']);
+    const endsAtMs = millisOf(booking['endsAtMs']);
+    const zone = fieldIds.some((fieldId)=>ZONE_FIELDS.has(fieldId)) ? await page.zoneOf(booking) : 'UTC';
+    const row = {};
+    for (const fieldId of fieldIds){
+        switch(fieldId){
+            case 'id':
+                row[fieldId] = id;
+                break;
+            case 'serviceId':
+            case 'serviceName':
+            case 'name':
+            case 'phone':
+            case 'address':
+            case 'crmRef':
+            case 'taxMode':
+            case 'paymentIntentId':
+            case 'checkoutSessionId':
+                row[fieldId] = textOf(booking[fieldId]);
+                break;
+            case 'email':
+                // `null` once the customer was erased.
+                row[fieldId] = textOf(booking['email']);
+                break;
+            case 'serviceCurrentName':
+                {
+                    var _booking_serviceId;
+                    const service = await page.serviceOf(String((_booking_serviceId = booking['serviceId']) != null ? _booking_serviceId : ''));
+                    row[fieldId] = service && !service['deletedAt'] ? textOf(service['name']) : null;
+                    break;
+                }
+            case 'startsAt':
+                row[fieldId] = isoOf(startsAtMs);
+                break;
+            case 'endsAt':
+                row[fieldId] = isoOf(endsAtMs);
+                break;
+            case 'timeZone':
+                row[fieldId] = zone;
+                break;
+            case 'startsLocal':
+                row[fieldId] = localTextOf(startsAtMs, zone);
+                break;
+            case 'endsLocal':
+                row[fieldId] = localTextOf(endsAtMs, zone);
+                break;
+            case 'durationMinutes':
+                row[fieldId] = startsAtMs !== null && endsAtMs !== null ? Math.round((endsAtMs - startsAtMs) / 60000) : null;
+                break;
+            case 'status':
+                {
+                    var _STATUS_LABELS_status;
+                    const status = textOf(booking['status']);
+                    row[fieldId] = status ? (_STATUS_LABELS_status = STATUS_LABELS[status]) != null ? _STATUS_LABELS_status : status : null;
+                    break;
+                }
+            case 'paidAmount':
+                row[fieldId] = dollarsOf(booking['paidAmountCents']);
+                break;
+            case 'tax':
+                row[fieldId] = dollarsOf(booking['taxCents']);
+                break;
+            case 'fee':
+                row[fieldId] = dollarsOf(booking['feeCents']);
+                break;
+            case 'refunded':
+                row[fieldId] = dollarsOf(booking['refundedCents']);
+                break;
+            case 'holdExpiresAt':
+                // Only an unpaid booking holds its slot; the stamp is cleared on payment.
+                row[fieldId] = isoOf(booking['expiresAtMs']);
+                break;
+            case 'createdAt':
+            case 'confirmedAt':
+            case 'reminderSentAt':
+                row[fieldId] = isoOf(booking[fieldId]);
+                break;
+            case 'customerErasedAt':
+                row[fieldId] = isoOf(booking['customerErasedAtMs']);
+                break;
+            default:
+                row[fieldId] = null;
+        }
+    }
+    return row;
+}
+function filteredQuery(bookings, filter, nowMs) {
+    if (!filter) return {
+        query: bookings,
+        orderField: 'startsAtMs'
+    };
+    switch(filter.kind){
+        case 'upcoming':
+            var _filter_asOfMs;
+            return {
+                query: bookings.where('endsAtMs', '>=', (_filter_asOfMs = filter.asOfMs) != null ? _filter_asOfMs : nowMs),
+                orderField: 'endsAtMs'
+            };
+        case 'email':
+            return {
+                query: bookings.where('email', '==', filter.email),
+                orderField: 'startsAtMs'
+            };
+        case 'service':
+            return {
+                query: bookings.where('serviceId', '==', filter.serviceId),
+                orderField: 'startsAtMs'
+            };
+    }
+}
+function readQueryCursor(cursor) {
+    if (cursor === null) return null;
+    try {
+        const parsed = JSON.parse(cursor);
+        if (typeof parsed.at === 'number' && typeof parsed.id === 'string' && parsed.id) {
+            return {
+                at: parsed.at,
+                id: parsed.id
+            };
+        }
+    } catch (unused) {
+    // Falls through to the refusal.
+    }
+    throw new Error('bookings export: the page cursor could not be read');
+}
+function hostIdOf(ctx) {
+    var _ctx_hostId;
+    const hostId = String((_ctx_hostId = ctx.hostId) != null ? _ctx_hostId : '').trim();
+    if (!hostId || hostId.includes('/')) throw new Error('bookings export: a site is required');
+    return hostId;
+}
+function pageSizeOf(options) {
+    var _ref;
+    const size = Math.floor(Number((_ref = options == null ? void 0 : options.pageSize) != null ? _ref : DEFAULT_PAGE_ROWS));
+    return Math.max(1, Math.min(MAX_PAGE_ROWS, Number.isFinite(size) ? size : DEFAULT_PAGE_ROWS));
+}
+function chunks(items, size) {
+    const out = [];
+    for(let index = 0; index < items.length; index += size)out.push(items.slice(index, index + size));
+    return out;
+}
+/*==========================================
+ * THE RESOURCE
+ *=========================================*/ /** The `bookings` resource over `deps.firestore()`. Export only: a lookup by id, and no apply or revert. */ export function createBookingsTransferResource(deps) {
+    var _deps_now;
+    const now = (_deps_now = deps.now) != null ? _deps_now : Date.now;
+    const bookingsOf = (hostId)=>deps.firestore().collection('hosts').doc(hostId).collection('bookings');
+    return {
+        fields: ()=>bookingsTransferCatalog(),
+        matchKeys: BOOKINGS_TRANSFER_MATCH_KEYS,
+        async count (ctx, options) {
+            const hostId = hostIdOf(ctx);
+            const bookings = bookingsOf(hostId);
+            if (options.ids) {
+                // Only the ids that name a booking, so the count is the rows the file holds.
+                const ids = [
+                    ...new Set(options.ids)
+                ].filter((id)=>id && !id.includes('/'));
+                let total = 0;
+                for (const part of chunks(ids, IN_LIMIT)){
+                    const snapshot = await bookings.where(FieldPath.documentId(), 'in', part).count().get();
+                    total += snapshot.data().count;
+                }
+                return total;
+            }
+            const { query } = filteredQuery(bookings, parseBookingsTransferFilter(options.filter), now());
+            return (await query.count().get()).data().count;
+        },
+        async readPage (ctx, cursor, fieldIds, options) {
+            var _last_get;
+            const hostId = hostIdOf(ctx);
+            const db = deps.firestore();
+            const bookings = bookingsOf(hostId);
+            const size = pageSizeOf(options);
+            const page = pageContext(db, ctx, hostId);
+            if (options == null ? void 0 : options.ids) {
+                const ids = [
+                    ...new Set(options.ids)
+                ].filter((id)=>id && !id.includes('/'));
+                const offset = cursor === null ? 0 : Number(cursor);
+                if (!Number.isInteger(offset) || offset < 0) {
+                    throw new Error('bookings export: the page cursor could not be read');
+                }
+                const slice = ids.slice(offset, offset + size);
+                const snapshots = slice.length ? await db.getAll(...slice.map((id)=>bookings.doc(id))) : [];
+                const rows = [];
+                for (const snapshot of snapshots){
+                    var _snapshot_data;
+                    if (snapshot.exists) rows.push(await bookingRow(snapshot.id, (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {}, fieldIds, page));
+                }
+                const next = offset + slice.length;
+                return {
+                    rows,
+                    next: next < ids.length ? String(next) : null
+                };
+            }
+            const { query, orderField } = filteredQuery(bookings, parseBookingsTransferFilter(options == null ? void 0 : options.filter), now());
+            let ordered = query.orderBy(orderField, 'asc').orderBy(FieldPath.documentId(), 'asc');
+            const after = readQueryCursor(cursor);
+            if (after) ordered = ordered.startAfter(after.at, after.id);
+            // One more than the page, to know without a second read whether another follows.
+            const snapshot = await ordered.limit(size + 1).get();
+            const docs = snapshot.docs.slice(0, size);
+            const rows = [];
+            for (const doc of docs)rows.push(await bookingRow(doc.id, doc.data(), fieldIds, page));
+            const last = docs[docs.length - 1];
+            const next = snapshot.docs.length > size && last ? JSON.stringify({
+                at: Number((_last_get = last.get(orderField)) != null ? _last_get : 0),
+                id: last.id
+            }) : null;
+            return {
+                rows,
+                next
+            };
+        },
+        /** What a booking holds now, by its Aglyn ID — the one key a resource nothing imports into answers. */ async lookup (ctx, requests) {
+            var _catalog_standard, _catalog_system;
+            const hostId = hostIdOf(ctx);
+            const db = deps.firestore();
+            const bookings = bookingsOf(hostId);
+            const byId = requests.filter((request)=>request.fieldId === TRANSFER_ID_FIELD);
+            const ids = [
+                ...new Set(byId.flatMap((request)=>request.values))
+            ].filter((id)=>id && !id.includes('/'));
+            const catalog = bookingsTransferCatalog();
+            const fieldIds = [
+                TRANSFER_ID_FIELD,
+                ...[
+                    ...(_catalog_standard = catalog.standard) != null ? _catalog_standard : [],
+                    ...(_catalog_system = catalog.system) != null ? _catalog_system : []
+                ].map((field)=>field.id)
+            ];
+            const page = pageContext(db, ctx, hostId);
+            const records = new Map();
+            for (const part of chunks(ids, MAX_PAGE_ROWS)){
+                const snapshots = part.length ? await db.getAll(...part.map((id)=>bookings.doc(id))) : [];
+                for (const snapshot of snapshots){
+                    var _snapshot_data;
+                    if (snapshot.exists) records.set(snapshot.id, await bookingRow(snapshot.id, (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {}, fieldIds, page));
+                }
+            }
+            const lookup = buildMatchLookup([
+                ...records
+            ].map(([id, values])=>({
+                    id,
+                    values
+                })), byId);
+            return {
+                lookup,
+                records
+            };
+        }
+    };
+}
+
+//# sourceMappingURL=bookings-transfer.js.map