domma-cms 0.102.0 → 0.103.0

package/plugins/booking/lib/mail.js

@@ -0,0 +1,113 @@
+/**
+ * Booking's emails: one way out, and never a pretend one.
+ *
+ * Without an SMTP host the CMS falls back to Ethereal and "succeeds" while
+ * delivering nothing, so with no SMTP these are simply not sent (`mailReady()`
+ * says so, and the settings screen shows it). Copied from Waypoint Pro's
+ * lib/mail.js - plugins cannot import each other.
+ *
+ * Tests swap the sender with `setMailer()`.
+ *
+ * @module booking/lib/mail
+ */
+import {createTransport, escapeHtml, isSmtpConfigured, sendEmail} from '../../../server/services/email.js';
+import {getConfig} from '../../../server/config.js';
+
+let override = null;
+let transport = null;
+let transportFor = '';
+
+/** Tests only: `fn(msg)` receives every message instead. Pass null to restore. */
+export function setMailer(fn) { override = fn; }
+
+const site = () => { try { return getConfig('site') || {}; } catch { return {}; } };
+
+/** Can mail really leave this site? */
+export function mailReady() {
+    return Boolean(override) || isSmtpConfigured(site().smtp || {});
+}
+
+/** The site's own address, for mail that has nobody better to go to. */
+export function siteAddress() {
+    const s = site();
+    return s.smtp?.fromAddress || s.contactEmail || '';
+}
+
+export const siteTitle = () => site().title || 'Our site';
+
+/**
+ * Send one message. Returns false (and logs) rather than throwing: a lost
+ * email must never fail the booking that caused it, and callers do not await.
+ *
+ * @param {{to: string, subject: string, html: string, text: string, attachments?: object[], replyTo?: string}} msg
+ */
+export async function send(msg, {log} = {}) {
+    try {
+        if (!msg?.to) return false;
+        if (override) { await override(msg); return true; }
+        const s = site();
+        const smtp = s.smtp || {};
+        if (!isSmtpConfigured(smtp)) return false;
+        const key = JSON.stringify([smtp.host, smtp.port, smtp.user, smtp.secure]);
+        if (!transport || transportFor !== key) { transport = await createTransport(smtp); transportFor = key; }
+        await sendEmail(transport, {from: smtp.fromAddress || 'noreply@example.com', fromName: smtp.fromName || s.title || 'Bookings', ...msg});
+        return true;
+    } catch (err) {
+        const line = `[booking] Email to ${msg?.to} not sent: ${err?.message || err}`;
+        try { if (typeof log?.error === 'function') log.error(line); else console.error(line); } catch { /* never */ }
+        return false;
+    }
+}
+
+/**
+ * A short message: paragraphs, a table of details and an optional button. Everything is escaped.
+ *
+ * @param {{subject: string, lines?: string[], details?: [string, string][], link?: string, linkText?: string, after?: string[]}} m
+ */
+export function compose({subject, lines = [], details = [], link = '', linkText = 'Open', after = []}) {
+    const rows = details.filter(([, v]) => v).map(([k, v]) =>
+        `<tr><td style="padding:4px 12px 4px 0;color:#666;vertical-align:top">${escapeHtml(k)}</td><td style="padding:4px 0">${escapeHtml(v)}</td></tr>`).join('');
+    const html = [
+        ...lines.map(l => `<p>${escapeHtml(l)}</p>`),
+        rows ? `<table style="border-collapse:collapse;margin:8px 0 16px">${rows}</table>` : '',
+        link ? `<p><a href="${escapeHtml(link)}" style="display:inline-block;padding:10px 18px;background:#2563eb;color:#fff;border-radius:6px;text-decoration:none">${escapeHtml(linkText)}</a></p>
+<p style="color:#666;font-size:13px">Or paste this into your browser: ${escapeHtml(link)}</p>` : '',
+        ...after.map(l => `<p style="color:#444">${escapeHtml(l)}</p>`)
+    ].join('\n');
+    const text = [
+        ...lines,
+        details.filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join('\n'),
+        link ? `${linkText}: ${link}` : '',
+        ...after
+    ].filter(Boolean).join('\n\n');
+    return {subject, html, text};
+}
+
+/** RFC 5545 text: escape \ ; , and newlines; fold at 75 octets (approximated by characters). */
+const icsText = (s) => String(s ?? '').replace(/\\/g, '\\\\').replace(/;/g, '\\;').replace(/,/g, '\\,').replace(/\r?\n/g, '\\n');
+const icsTime = (iso) => new Date(iso).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+const fold = (line) => line.length <= 74 ? line : line.match(/.{1,73}/g).join('\r\n ');
+
+/**
+ * An .ics for one booking - METHOD:REQUEST adds it, METHOD:CANCEL takes it off.
+ * The UID is stable per booking, so a move replaces the entry in the customer's calendar.
+ */
+export function icsFor(booking, {host = 'booking', title, location = '', description = '', cancel = false, sequence = 0}) {
+    const lines = [
+        'BEGIN:VCALENDAR', 'VERSION:2.0', 'PRODID:-//Domma CMS//Booking//EN', `METHOD:${cancel ? 'CANCEL' : 'REQUEST'}`,
+        'BEGIN:VEVENT',
+        `UID:booking-${booking.id}@${host}`,
+        `SEQUENCE:${sequence}`,
+        `DTSTAMP:${icsTime(new Date().toISOString())}`,
+        `DTSTART:${icsTime(booking.startAt)}`,
+        `DTEND:${icsTime(booking.endAt)}`,
+        `SUMMARY:${icsText(title)}`,
+        location ? `LOCATION:${icsText(location)}` : '',
+        description ? `DESCRIPTION:${icsText(description)}` : '',
+        `STATUS:${cancel ? 'CANCELLED' : 'CONFIRMED'}`,
+        'END:VEVENT', 'END:VCALENDAR'
+    ].filter(Boolean).map(fold);
+    return lines.join('\r\n') + '\r\n';
+}
+
+export {escapeHtml};

package/plugins/booking/lib/store.js

@@ -0,0 +1,384 @@
+/**
+ * Booking's data: the three collections, the live settings, and the moves a
+ * booking makes (made, moved, cancelled, marked done or no-show).
+ *
+ * Every write to a booking goes through `withLock`, one at a time, and
+ * re-checks the slot inside it. Two people choosing the same time in the same
+ * second: the second finds the first's booking and is told the time has gone.
+ *
+ * @module booking/lib/store
+ */
+
+import {randomBytes} from 'crypto';
+import {createCollection, createEntry, deleteEntry, getCollection, getEntry, listEntries, updateEntry} from '../../../server/services/collections.js';
+import {getPluginSettings, getPluginStates, savePluginState} from '../../../server/services/plugins.js';
+import {cleanDaysOff, EMAIL_RE, STATUSES} from '../public/lib/clean.js';
+import {PLAIN, pickBookable, spanOf, whoCanTake} from '../public/lib/slots.js';
+import {atWallClock, cleanZone, isDate, wallClock} from '../public/lib/time.js';
+import defaults from '../config.js';
+import {joinPath} from './call.js';
+
+export const NAME = 'booking';
+export const BOOKABLES = 'booking-bookables';
+export const SERVICES = 'booking-services';
+export const BOOKINGS = 'booking-bookings';
+
+// ---- Setup ---------------------------------------------------------------------
+
+/** Make the collections that are missing. Every boot: a plugin switched on by copy never has onEnable run. */
+export async function ensureCollections(log = console) {
+    const fs = await import('fs/promises');
+    for (const slug of [BOOKABLES, SERVICES, BOOKINGS]) {
+        if (await getCollection(slug)) continue;
+        const schema = JSON.parse(await fs.readFile(new URL(`../collections/${slug}.json`, import.meta.url), 'utf8'));
+        await createCollection(schema);
+        log.info?.(`[booking] Created collection: ${slug}`);
+    }
+}
+
+// ---- Settings ------------------------------------------------------------------
+
+const RESERVED = /^\/(admin|api|plugins|dist|media|assets|login|shop|blog|calendar)(\/|$)/;
+
+/** "/booking" from "booking/", "/Booking//" - one leading slash, no trailing one, never an engine address. */
+export function cleanPath(p) {
+    const t = '/' + String(p || '/booking').toLowerCase().replace(/[^a-z0-9/_-]/g, '').replace(/\/+/g, '/').replace(/^\/|\/$/g, '');
+    return t === '/' || RESERVED.test(t) ? '/booking' : t;
+}
+
+const withDefaults = (s) => ({...defaults, ...s, bookingPath: cleanPath(s.bookingPath), timeZone: cleanZone(s.timeZone)});
+
+/** The settings as they are NOW - read per request, so a change needs no restart. */
+export async function liveSettings() {
+    return withDefaults(await getPluginSettings(NAME) || {});
+}
+
+/** The same, synchronously - for shortcodes, which cannot wait. */
+export function settingsNow() {
+    return withDefaults(getPluginStates()[NAME]?.settings || {});
+}
+
+/** @returns {{settings: object, errors: Object<string, string>}} */
+export function cleanSettings(input, current) {
+    const errors = {};
+    const v = {...current, ...input};
+    const str = (k, max = 300) => String(v[k] ?? '').trim().slice(0, max);
+    const out = {
+        pageTitle: str('pageTitle', 80) || 'Book',
+        bookingPath: cleanPath(v.bookingPath),
+        intro: str('intro', 2000),
+        timeZone: cleanZone(v.timeZone),
+        askPhone: v.askPhone !== false,
+        phoneRequired: v.phoneRequired === true,
+        termsUrl: str('termsUrl'),
+        confirmationNote: str('confirmationNote', 2000),
+        allowCancel: v.allowCancel !== false,
+        allowMove: v.allowMove !== false,
+        changeNoticeHours: Math.max(0, Math.min(24 * 30, Math.round(Number(v.changeNoticeHours) || 0))),
+        sendConfirmation: v.sendConfirmation !== false,
+        reminderHours: Math.max(0, Math.min(24 * 14, Math.round(Number(v.reminderHours) || 0))),
+        notifyAddress: str('notifyAddress', 200),
+        addToContacts: v.addToContacts !== false,
+        contactsOwnerId: str('contactsOwnerId', 64),
+        calendarBusy: v.calendarBusy !== false,
+        closures: cleanDaysOff(v.closures)
+    };
+    if (input.timeZone !== undefined && cleanZone(input.timeZone) !== String(input.timeZone).trim()) errors.timeZone = 'A time zone such as Europe/London.';
+    if (out.termsUrl && !/^(\/(?!\/)|https?:\/\/)/.test(out.termsUrl)) errors.termsUrl = 'A page on this site (/terms) or a full https:// address.';
+    if (out.notifyAddress && !EMAIL_RE.test(out.notifyAddress)) errors.notifyAddress = 'An email address, or leave it empty.';
+    if (input.bookingPath !== undefined && cleanPath(input.bookingPath) !== '/' + String(input.bookingPath).trim().replace(/^\/+|\/+$/g, '').toLowerCase()) {
+        errors.bookingPath = 'Letters, numbers and hyphens, and not an address the CMS uses (admin, api, shop, blog...).';
+    }
+    return {settings: out, errors};
+}
+
+export function saveSettings(next) {
+    const state = getPluginStates()[NAME] || {};
+    savePluginState(NAME, {settings: {...(state.settings || {}), ...next}});
+}
+
+// ---- Reading -------------------------------------------------------------------
+
+const all = async (slug) => (await listEntries(slug, {limit: 100000}).catch(() => ({entries: []}))).entries || [];
+const flat = (e) => (e ? {id: e.id, ...e.data, createdAt: e.meta?.createdAt, updatedAt: e.meta?.updatedAt} : null);
+const byOrder = (a, b) => (a.order || 0) - (b.order || 0) || String(a.name).localeCompare(String(b.name));
+
+export const allBookables = async () => (await all(BOOKABLES)).map(flat).sort(byOrder);
+export const allServices = async () => (await all(SERVICES)).map(flat).sort(byOrder);
+export const allBookings = async () => (await all(BOOKINGS)).map(flat);
+export const getBooking = async (id) => flat(await getEntry(BOOKINGS, id).catch(() => null));
+export const getService = async (id) => flat(await getEntry(SERVICES, id).catch(() => null));
+export const getBookable = async (id) => flat(await getEntry(BOOKABLES, id).catch(() => null));
+
+/** The snapshot shortcodes render from (they are synchronous). */
+let shelf = {services: [], bookables: []};
+export async function refreshShelf() {
+    shelf = {services: await allServices(), bookables: await allBookables()};
+    return shelf;
+}
+export const shelfNow = () => shelf;
+
+// ---- Writing: services and bookables -------------------------------------------
+
+export async function saveThing(slug, id, data) {
+    const saved = id ? await updateEntry(slug, id, data) : await createEntry(slug, data);
+    await refreshShelf();
+    return flat(saved);
+}
+
+export async function removeThing(slug, id) {
+    await deleteEntry(slug, id);
+    await refreshShelf();
+}
+
+/** A service's slug, unique among services. */
+export function uniqueSlug(slug, services, selfId = '') {
+    // 'manage' is the customer's own page (<base>/manage/<id>), never a service.
+    const taken = new Set(['manage', ...services.filter(s => s.id !== selfId).map(s => s.slug)]);
+    if (!taken.has(slug)) return slug;
+    for (let n = 2; ; n++) if (!taken.has(`${slug}-${n}`)) return `${slug}-${n}`;
+}
+
+// ---- The lock ------------------------------------------------------------------
+
+let queue = Promise.resolve();
+/** Run `fn` after every write before it has finished. */
+export function withLock(fn) {
+    const run = queue.then(fn, fn);
+    queue = run.catch(() => {});
+    return run;
+}
+
+// ---- Busy time from the Calendar -----------------------------------------------
+
+/**
+ * A person's commitments in the Calendar, when the Calendar is here: the
+ * active occurrences of events they organise. Read through the collections
+ * service (no import of the Calendar's code - it is a separate, paid Tool).
+ *
+ * An all-day event is stored as UTC midnights of its dates (end exclusive);
+ * it blocks the business's own midnight to midnight, not UTC's.
+ *
+ * @param   {object[]} bookables
+ * @param   {{from: string, to: string}} range - ISO instants
+ * @param   {string} [tz] - the business zone
+ * @returns {Promise<Object<string, {startAt: string, endAt: string}[]>>}
+ */
+export async function calendarBusy(bookables, {from, to}, tz = 'Europe/London') {
+    const out = {};
+    const people = bookables.filter(b => b.kind === 'person' && b.userId && b.calendarBusy !== false);
+    if (!people.length || !getPluginStates().calendar?.enabled) return out;
+    const [events, occurrences] = await Promise.all([all('calendar-events'), all('calendar-occurrences')]);
+    const organiser = new Map(events.map(e => [e.id, e.data?.organiserId]));
+    for (const bk of people) out[bk.id] = [];
+    for (const o of occurrences) {
+        const d = o.data || {};
+        if (d.status && d.status !== 'active') continue;
+        if (!d.startAt) continue;
+        let startAt = new Date(d.startAt).toISOString();
+        let endAt = new Date(d.endAt || d.startAt).toISOString();
+        if (d.allDay) {
+            const first = startAt.slice(0, 10);
+            const end = endAt.slice(0, 10) > first ? endAt.slice(0, 10) : first;
+            startAt = atWallClock(first, 0, tz).toISOString();
+            endAt = atWallClock(end === first ? addDay(first) : end, 0, tz).toISOString();
+        }
+        if (startAt >= to || endAt <= from) continue;
+        const who = organiser.get(d.eventId);
+        for (const bk of people) if (bk.userId === who) out[bk.id].push({startAt, endAt});
+    }
+    return out;
+}
+
+/** Calendar busy time when the site's setting wants it, else none. */
+export async function settingsBusy(bookables, range, tz) {
+    const s = await liveSettings();
+    return s.calendarBusy ? calendarBusy(bookables, range, tz) : {};
+}
+
+const addDay = (date) => new Date(Date.parse(`${date}T00:00:00Z`) + 86400000).toISOString().slice(0, 10);
+
+// ---- Bookings ------------------------------------------------------------------
+
+export const newToken = () => randomBytes(18).toString('base64url');
+
+/** Is this the booking's own link? Constant-time is overkill for 24 random chars; equality of type and value is not. */
+export const tokenOk = (booking, t) => Boolean(booking?.token) && typeof t === 'string' && t === booking.token;
+
+/** Why a booking cannot be made at a time, or '' when it can. */
+export class SlotTaken extends Error {
+    constructor(message = 'That time has just been taken. Please pick another.') { super(message); this.code = 'slot-taken'; }
+}
+
+/**
+ * Make (or move) a booking, inside the lock, after checking the time again.
+ *
+ * @param   {object} p
+ * @param   {object} p.service
+ * @param   {object[]} p.candidates - bookables that may take it (one when chosen)
+ * @param   {string} p.startAt - ISO
+ * @param   {object} p.fields - everything else stored on the booking
+ * @param   {string} [p.moveId] - move this booking instead of making one
+ * @param   {boolean} [p.force] - staff booking over a clash (admin only)
+ * @param   {string} p.tz
+ * @param   {Function} [p.busyFor] - (bookables, range) => busy map
+ * @param   {object} [p.rules] - capacity, companions, maxPerDay (extensions'; plain without)
+ * @returns {Promise<object>} the booking
+ */
+export function placeBooking({service, candidates, startAt, fields, moveId = '', force = false, tz, busyFor = settingsBusy, rules = PLAIN}) {
+    return withLock(async () => {
+        const span = spanOf(service, startAt);
+        const bookings = await allBookings();
+        const range = {from: new Date(span.blockStart).toISOString(), to: new Date(span.blockEnd).toISOString()};
+        const companions = rules.companions || [];
+        const everyone = [...candidates, ...companions.flat()];
+        const busy = force ? {} : await busyFor(everyone, range, tz).catch(() => ({}));
+        const dayOf = (ms) => wallClock(ms, tz).date;
+        let able = whoCanTake({service, candidates, companions, span, bookings, busy, ignoreId: moveId, rules, dayOf});
+        if (!able.length && force) {
+            // Staff booking over a clash: the chosen (or first) provider, and the first of each companion group.
+            able = candidates.slice(0, 1).map(bk => ({bookableId: bk.id, holds: [bk.id, ...companions.map(g => g.find(c => c.id !== bk.id)?.id).filter(Boolean)], left: 1}));
+        }
+        if (!able.length) throw new SlotTaken();
+        const date = dayOf(span.start);
+        const bookableId = pickBookable(able.map(a => a.bookableId), bookings.filter(b => b.id !== moveId), date, tz, {serviceId: service.id, start: span.start});
+        const chosen = able.find(a => a.bookableId === bookableId);
+        const byId = new Map(everyone.map(b => [b.id, b]));
+        const times = {
+            startAt: new Date(span.start).toISOString(),
+            endAt: new Date(span.end).toISOString(),
+            blockStart: new Date(span.blockStart).toISOString(),
+            blockEnd: new Date(span.blockEnd).toISOString(),
+            bookableId,
+            bookableName: byId.get(bookableId)?.name || '',
+            holds: chosen.holds,
+            // What it took along (a court with the trainer), by name, for the diary and the emails.
+            alsoNames: chosen.holds.slice(1).map(id => byId.get(id)?.name || '').filter(Boolean),
+            reminderSentAt: ''
+        };
+        if (moveId) {
+            const current = await getEntry(BOOKINGS, moveId);
+            if (!current) throw new Error('That booking no longer exists.');
+            const history = [...(current.data.history || []), {at: new Date().toISOString(), what: 'moved', from: current.data.startAt, by: fields.by || ''}].slice(-50);
+            return flat(await updateEntry(BOOKINGS, moveId, {...current.data, ...times, history}));
+        }
+        const {by, ...rest} = fields;
+        return flat(await createEntry(BOOKINGS, {
+            serviceId: service.id,
+            serviceName: service.name,
+            duration: service.duration,
+            status: 'confirmed',
+            token: newToken(),
+            ...rest,
+            ...times,
+            history: [{at: new Date().toISOString(), what: 'made', by: by || ''}],
+            ext: rest.ext && typeof rest.ext === 'object' ? rest.ext : {},
+            // Held as a video call (Pro said so when it was made). Kept on the booking, so the call still
+            // happens if Pro lapses; the host key is the person booked's link and never reaches the customer.
+            ...(rules.online ? {online: true, hostKey: newToken(), recordingAllowed: rules.recordingAllowed === true} : {})
+        }));
+    });
+}
+
+/**
+ * Change a booking's status or note (no time change), inside the lock.
+ *
+ * @returns {Promise<{booking: object, from: string}>}
+ */
+export function changeBooking(id, patch, by = '') {
+    return withLock(async () => {
+        const current = await getEntry(BOOKINGS, id);
+        if (!current) return null;
+        const data = {...current.data};
+        const from = data.status;
+        if (patch.status !== undefined) {
+            if (!STATUSES.includes(patch.status)) throw new Error('Not a status a booking can have.');
+            // Its time may be someone else's by now: bringing it back would be a double booking nobody checked.
+            if (from === 'cancelled' && patch.status !== 'cancelled') throw new Error('A cancelled booking cannot be brought back. Make a new booking for that time instead.');
+            data.status = patch.status;
+            if (patch.status !== from) {
+                data.history = [...(data.history || []), {at: new Date().toISOString(), what: patch.status, by, reason: String(patch.reason || '').slice(0, 300)}].slice(-50);
+                if (patch.status === 'cancelled') data.cancelledAt = new Date().toISOString();
+            }
+        }
+        if (patch.staffNote !== undefined) data.staffNote = String(patch.staffNote).slice(0, 4000);
+        if (patch.customer) {
+            for (const k of ['name', 'email', 'phone', 'notes']) if (patch.customer[k] !== undefined) data[k] = patch.customer[k];
+        }
+        if (patch.reminderSentAt !== undefined) data.reminderSentAt = patch.reminderSentAt;
+        if (patch.contactId !== undefined) data.contactId = patch.contactId;
+        if (patch.ext && typeof patch.ext === 'object') data.ext = {...(data.ext || {}), ...patch.ext};
+        return {booking: flat(await updateEntry(BOOKINGS, id, data)), from};
+    });
+}
+
+export async function removeBooking(id) {
+    return withLock(() => deleteEntry(BOOKINGS, id));
+}
+
+/** May the customer still change it themselves? */
+export function customerMayChange(booking, settings, now = Date.now()) {
+    if (booking.status !== 'confirmed') return false;
+    return new Date(booking.startAt).getTime() - now >= (Number(settings.changeNoticeHours) || 0) * 3600000;
+}
+
+/** What the customer's own page may see of a booking. */
+export function publicBooking(b, settings, now = Date.now()) {
+    const wall = wallClock(b.startAt, settings.timeZone);
+    const may = customerMayChange(b, settings, now);
+    return {
+        id: b.id, serviceId: b.serviceId, serviceName: b.serviceName, bookableId: b.bookableId, bookableName: b.bookableName,
+        startAt: b.startAt, endAt: b.endAt, date: wall.date, time: wall.time, status: b.status,
+        name: b.name, email: b.email, phone: b.phone, notes: b.notes,
+        canCancel: may && settings.allowCancel !== false,
+        canMove: may && settings.allowMove !== false,
+        online: b.online === true,
+        callUrl: b.online === true && b.status !== 'cancelled' ? joinPath(settings, b) : ''
+    };
+}
+
+// ---- Contacts ------------------------------------------------------------------
+
+/**
+ * Find or make the customer's contact in the owner's address book. Contacts
+ * are per user; the owner is the person being booked (when they are a user),
+ * else the setting, else whoever made the booking. '' when Contacts is off or
+ * nobody owns it.
+ *
+ * @returns {Promise<string>} contact id
+ */
+export async function linkContact({name, email, phone}, ownerId, contactsOn) {
+    if (!contactsOn || !ownerId || !email) return '';
+    const want = String(email).trim().toLowerCase();
+    const entries = await all('contacts-contacts');
+    const same = entries.find(c => c.data?.userId === ownerId && [c.data?.email, ...(Array.isArray(c.data?.emails) ? c.data.emails.map(x => x?.address) : [])]
+        .some(a => String(a || '').trim().toLowerCase() === want));
+    if (same) return same.id;
+    const made = await createEntry('contacts-contacts', {
+        name: String(name || email).trim(), email: String(email).trim(), phone: String(phone || '').trim(),
+        userId: ownerId, groups: [], favourite: false
+    });
+    return made.id;
+}
+
+/** A contact of this user's, or null. */
+export async function ownContact(id, userId) {
+    const e = await getEntry('contacts-contacts', id).catch(() => null);
+    if (!e || (userId && e.data?.userId !== userId)) return null;
+    return {id: e.id, name: e.data?.name || '', email: e.data?.email || '', phone: e.data?.phone || ''};
+}
+
+/**
+ * The caller's own contact with this email (main address or any of Contacts Pro's), or null - so an email's
+ * "Book Sam…" and a typed address both find the contact they already have instead of making another.
+ */
+export async function contactByEmail(email, userId) {
+    const want = String(email || '').trim().toLowerCase();
+    if (!want || !userId) return null;
+    const e = (await all('contacts-contacts')).find(c => c.data?.userId === userId
+        && [c.data?.email, ...(Array.isArray(c.data?.emails) ? c.data.emails.map(x => x?.address) : [])]
+            .some(a => String(a || '').trim().toLowerCase() === want));
+    return e ? {id: e.id, name: e.data?.name || '', email: e.data?.email || want, phone: e.data?.phone || ''} : null;
+}
+
+export {isDate};