@evinvest/kitstart 0.17.0 → 0.19.1

package/dist/core/lead.js

@@ -9,9 +9,13 @@
  * `LeadSchema.wire` names the posted fields (a page cached before a rename
  * still delivers) — both deliberate departures from the first design.
  */
+import { MESSAGE_REF_FIELD, messageRefOf } from "./messenger.js";
 import { normalizePhone, phoneProblem } from "./phone.js";
-export const LEAD_CHANNELS = ["form", "callback"];
+export const LEAD_CHANNELS = ["form", "callback", "whatsapp", "telegram"];
 export const CHANNEL_FIELD = "channel";
+export function isMessengerChannel(channel) {
+    return channel === "whatsapp" || channel === "telegram";
+}
 /**
  * The callback's consent: a checkbox whose value is the sentence it shows, in
  * the language it shows it, so the row keeps what was agreed to. Absent → the
@@ -84,8 +88,14 @@ export function rejectionOf(verdict) {
         return { field: "form", why: verdict };
     return FIELD_SLUG.test(verdict.field) ? verdict : { field: "form", why: verdict.why };
 }
-/** The default form rule: a number we can call — the one the form blocks on (`phoneProblem`). */
+/**
+ * The default form rule: a number we can call — the one the form blocks on
+ * (`phoneProblem`). A messenger lead needs none, but one typed must be a
+ * number: the operator may call it.
+ */
 export function validateLead(lead) {
+    if (isMessengerChannel(lead.channel) && lead.mobile.trim() === "")
+        return null;
     const problem = phoneProblem(lead.mobile);
     return problem === null ? null : { field: "phone", why: problem === "required" ? "a phone number" : "a phone number we can call" };
 }
@@ -113,10 +123,10 @@ export function channelOf(lead) {
  * The lead schema's version, shared by every adapter: 1 the Rust server's
  * table (`job`, `zip`, `mobile`, `at`), 2 + the place, 3 + the spam verdict,
  * 4 + the brand's extras, 5 + the channel and the callback's consent, 6 + the
- * script's submission id, unique, 7 + the flow and the price it was taken at.
- * Append only.
+ * script's submission id, unique, 7 + the flow and the price it was taken at,
+ * 8 + the messenger reference (`message_ref`). Append only.
  */
-export const LEAD_SCHEMA_VERSION = 7;
+export const LEAD_SCHEMA_VERSION = 8;
 /** A field is capped, not rejected: a long answer is still a customer. */
 export const MAX_FIELD = 200;
 // C0 and C1 controls, DEL, and the Unicode line and paragraph separators.
@@ -148,18 +158,21 @@ export function readCandidate(schema, form, placeSlug) {
             extras[extra.name] = value;
     }
     const mobile = field(form, schema.wire.mobile, MAX_FIELD) ?? "";
-    const callback = form.get(CHANNEL_FIELD) === "callback";
-    const consent = callback ? field(form, CONSENT_FIELD, MAX_CONSENT) : null;
+    const posted = form.get(CHANNEL_FIELD);
+    const channel = LEAD_CHANNELS.find(c => c === posted) ?? "form";
+    const consent = channel === "callback" ? field(form, CONSENT_FIELD, MAX_CONSENT) : null;
     const submission = field(form, SUBMISSION_FIELD, 64);
+    const messageRef = messageRefOf(form.get(MESSAGE_REF_FIELD));
     return {
         subject: field(form, schema.wire.subject, MAX_FIELD) ?? "",
         locality: field(form, schema.wire.locality, MAX_FIELD) ?? "",
         mobile: schema.mobileFormat === "e164" ? (normalizePhone(mobile) ?? mobile) : mobile,
         extras,
         placeSlug,
-        channel: callback ? "callback" : "form",
+        channel,
         ...(consent ? { consentText: consent } : {}),
         ...(submission && SUBMISSION_ID.test(submission) ? { submissionId: submission } : {}),
+        ...(messageRef ? { messageRef } : {}),
     };
 }
 /** The rule the candidate's channel answers to: the field a refusal is about, or `null`. */

package/dist/core/messenger-message.d.ts

@@ -0,0 +1,31 @@
+/** The words of the prefilled message, one template per line; `{brand}`, `{need}`, … filled in. */
+export interface MessengerMessageText {
+    messageHello: string;
+    messageNeed: string;
+    messagePostcode: string;
+    messagePrice: string;
+    messageTiming: string;
+    messageRef: string;
+}
+/** What the message says. Nothing typed about the person — no phone, no name. */
+export interface MessengerMessageInput {
+    brand: string;
+    /** The need's label. */
+    need?: string | null | undefined;
+    postcode?: string | null | undefined;
+    /** The estimate the page showed, formatted (`≈ 77 €`). */
+    price?: string | null | undefined;
+    /** When the job is wanted — an urgency or a frequency label. */
+    timing?: string | null | undefined;
+    ref?: string | null | undefined;
+}
+/** WhatsApp shows a long message whole, but the link has to fit a QR code a phone can read off a screen. */
+export declare const MAX_MESSENGER_MESSAGE = 400;
+/**
+ * The prefilled message: a greeting, the need, the postcode, the estimate
+ * and the timing when known, and the reference last — the line the operator
+ * matches the chat by. A line without its value is left out. Past
+ * `MAX_MESSENGER_MESSAGE`, the optional lines go from the bottom up; the
+ * greeting and the reference stay.
+ */
+export declare function messengerMessage(input: MessengerMessageInput, text: MessengerMessageText): string;

package/dist/core/messenger-message.js

@@ -0,0 +1,33 @@
+import { fillText } from "./lead-capture-format.js";
+/** WhatsApp shows a long message whole, but the link has to fit a QR code a phone can read off a screen. */
+export const MAX_MESSENGER_MESSAGE = 400;
+// C0 and C1 controls, DEL, and the Unicode line and paragraph separators: a value is one line.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g;
+/** One line of the message, capped: a value is a label, not a letter. */
+const clean = (value, max = 80) => (value ?? "").replace(CONTROL, " ").trim().slice(0, max);
+/**
+ * The prefilled message: a greeting, the need, the postcode, the estimate
+ * and the timing when known, and the reference last — the line the operator
+ * matches the chat by. A line without its value is left out. Past
+ * `MAX_MESSENGER_MESSAGE`, the optional lines go from the bottom up; the
+ * greeting and the reference stay.
+ */
+export function messengerMessage(input, text) {
+    const line = (template, key, value) => {
+        const v = clean(value);
+        return v === "" ? null : fillText(template, { [key]: v });
+    };
+    const hello = fillText(text.messageHello, { brand: clean(input.brand) });
+    const ref = input.ref ? line(text.messageRef, "ref", input.ref) : null;
+    const optional = [
+        line(text.messageNeed, "need", input.need),
+        line(text.messagePostcode, "postcode", input.postcode),
+        line(text.messagePrice, "price", input.price),
+        line(text.messageTiming, "timing", input.timing),
+    ].filter((l) => l !== null);
+    const compose = (lines) => [hello, ...lines, ...(ref ? [ref] : [])].join("\n");
+    let kept = optional;
+    while (kept.length > 0 && compose(kept).length > MAX_MESSENGER_MESSAGE)
+        kept = kept.slice(0, -1);
+    return compose(kept).slice(0, MAX_MESSENGER_MESSAGE);
+}

package/dist/core/messenger-text.d.ts

@@ -0,0 +1,104 @@
+import type { MessengerMessageText } from "./messenger-message.js";
+/**
+ * What a `messenger` variant of `LeadCapture` prints — and the prefilled
+ * message's lines. Optional in `LeadCaptureText`, as the flows' words are: a
+ * brand's text from before the variants still type-checks, and a key left
+ * out falls back to the kit's in the page's language (`messengerTextOf`).
+ *
+ * Apart from the flows' words on purpose: only a variant's own chunk reads
+ * them, so the control's page never downloads them.
+ */
+export interface LeadCaptureMessengerText extends MessengerMessageText {
+    /** The WhatsApp button. */
+    messengerWhatsappCta: string;
+    /** `saga`: the WhatsApp step's button. */
+    messengerOpenWhatsapp: string;
+    /** The Telegram button. */
+    messengerTelegramCta: string;
+    /** Under the submit when the place has a bot: the way to it. */
+    messengerViaTelegram: string;
+    /** A channel's name in a picker, a tile, a segment — and its line under it. */
+    messengerOptionWhatsapp: string;
+    messengerOptionWhatsappNote: string;
+    messengerOptionCall: string;
+    messengerOptionCallNote: string;
+    messengerOptionTelegram: string;
+    messengerOptionTelegramNote: string;
+    /** The badge on the recommended channel. */
+    messengerRecommended: string;
+    /** Names a channel picker for assistive technology. */
+    messengerChannelLabel: string;
+    /** The way to the phone, beside the messengers. */
+    messengerCallback: string;
+    /** `swap`, `split`: the square back to WhatsApp, for assistive technology. */
+    messengerBackToWhatsapp: string;
+    /** The phone field's placeholder when the phone is optional. */
+    messengerPhoneOptional: string;
+    /** `select`: under the field, by channel. */
+    messengerWhatsappHint: string;
+    messengerTelegramHint: string;
+    /** The message's preview in the slot: its heading, and an optional line after the message. */
+    messengerPreviewTitle: string;
+    /** The estimate in the preview, `{price}` the amount («env. {price}»). */
+    messengerPreviewPrice: string;
+    messengerPreviewNote: string;
+    /** Telegram's card in the slot. */
+    messengerBotTitle: string;
+    messengerBotLede: string;
+    /** `tiles`: over the tiles. */
+    messengerTilesLabel: string;
+    /** `thanks`: the success's ask, and its WhatsApp button. */
+    messengerThanksTitle: string;
+    messengerThanksCta: string;
+    /** `saga`: the channel screen. */
+    messengerSagaTitle: string;
+    messengerSagaLede: string;
+    messengerSagaFoot: string;
+    /** `saga`, `sheet`: back to the channels. */
+    messengerChange: string;
+    /** `saga`, `sheet`: the second screen's heading and lede, by channel. */
+    messengerWhatsappTitle: string;
+    messengerWhatsappLede: string;
+    messengerTelegramTitle: string;
+    messengerTelegramLede: string;
+    messengerCallTitle: string;
+    messengerCallLede: string;
+    /** `urgency`: the question, its two answers, and what each leads to. */
+    messengerUrgencyLabel: string;
+    messengerUrgencyYes: string;
+    messengerUrgencyNo: string;
+    /** The message's timing line for an urgent need, and for one that can wait. */
+    messengerUrgencyToday: string;
+    messengerUrgencyLater: string;
+    messengerUrgentSubmit: string;
+    messengerNotUrgentTitle: string;
+    /** `{ref}` the reference. */
+    messengerNotUrgentLede: string;
+    /** `sheet`: the card's one button and the drawer's heading. */
+    messengerSheetCta: string;
+    messengerSheetTitle: string;
+    /** `chip`: the chip, by channel. */
+    messengerChipWhatsapp: string;
+    messengerChipCall: string;
+    messengerChipTelegram: string;
+    /** `split`: the WhatsApp half of the row. */
+    messengerSplitCta: string;
+    /** In an app's own browser (Instagram, TikTok…): WhatsApp may not open from it. */
+    messengerInappHint: string;
+    messengerCopy: string;
+    messengerCopied: string;
+    /** Back from the messenger: `{channel}` its name, `{ref}` the reference. */
+    messengerReturnTitle: string;
+    messengerReturnBody: string;
+    messengerReopen: string;
+    messengerReturnFailed: string;
+    messengerReturnDone: string;
+    /** On a computer: the QR code that opens WhatsApp on the phone. */
+    messengerQrTitle: string;
+    messengerQrLede: string;
+    messengerQrWeb: string;
+    messengerQrAlt: string;
+}
+export declare const LEAD_CAPTURE_MESSENGER_TEXT: Readonly<Record<"fr" | "en", LeadCaptureMessengerText>>;
+/** The variants' words for a page: the brand's, else the kit's in its language (English for `en*`, French otherwise). */
+export declare function messengerTextOf(text: Partial<LeadCaptureMessengerText>, locale: string): LeadCaptureMessengerText;

package/dist/core/messenger-text.js

@@ -0,0 +1,150 @@
+const FR = {
+    messageHello: "Bonjour {brand} 👋",
+    messageNeed: "Je souhaite un devis : {need}",
+    messagePostcode: "Code postal : {postcode}",
+    messagePrice: "Estimation vue sur le site : {price}",
+    messageTiming: "Délai souhaité : {timing}",
+    messageRef: "Réf. {ref}",
+    messengerWhatsappCta: "Recevoir mon devis sur WhatsApp",
+    messengerOpenWhatsapp: "Ouvrir WhatsApp",
+    messengerTelegramCta: "Ouvrir Telegram",
+    messengerViaTelegram: "ou via Telegram",
+    messengerOptionWhatsapp: "WhatsApp",
+    messengerOptionWhatsappNote: "Recommandé · demande déjà rédigée",
+    messengerOptionCall: "Appel",
+    messengerOptionCallNote: "On vous rappelle rapidement",
+    messengerOptionTelegram: "Telegram",
+    messengerOptionTelegramNote: "Via notre bot Telegram",
+    messengerRecommended: "Recommandé",
+    messengerChannelLabel: "Canal de réponse",
+    messengerCallback: "Être rappelé",
+    messengerBackToWhatsapp: "Revenir à WhatsApp",
+    messengerPhoneOptional: "Téléphone (facultatif)",
+    messengerWhatsappHint: "WhatsApp s’ouvre, demande déjà rédigée. Numéro facultatif.",
+    messengerTelegramHint: "Telegram s’ouvre : notre bot vous répond.",
+    messengerPreviewTitle: "Votre message est prêt",
+    messengerPreviewPrice: "{price}",
+    messengerPreviewNote: "",
+    messengerBotTitle: "Notre bot vous envoie le devis",
+    messengerBotLede: "Telegram s’ouvre : appuyez sur « Démarrer », le devis arrive dans le chat.",
+    messengerTilesLabel: "Recevoir mon devis par",
+    messengerThanksTitle: "Plus rapide : envoyez une photo",
+    messengerThanksCta: "Envoyer la photo sur WhatsApp",
+    messengerSagaTitle: "Comment voulez-vous nous joindre ?",
+    messengerSagaLede: "Réponse rapide, sans engagement.",
+    messengerSagaFoot: "Réponse rapide · sans engagement",
+    messengerChange: "Changer de canal",
+    messengerWhatsappTitle: "Sur WhatsApp",
+    messengerWhatsappLede: "Puis WhatsApp s’ouvre, message prêt.",
+    messengerTelegramTitle: "Sur Telegram",
+    messengerTelegramLede: "Puis Telegram s’ouvre : notre bot vous répond.",
+    messengerCallTitle: "On vous rappelle",
+    messengerCallLede: "Laissez votre numéro.",
+    messengerUrgencyLabel: "C’est urgent ?",
+    messengerUrgencyYes: "Oui, aujourd’hui",
+    messengerUrgencyNo: "Non, je compare",
+    messengerUrgencyToday: "aujourd’hui",
+    messengerUrgencyLater: "pas pressé",
+    messengerUrgentSubmit: "Rappelez-moi tout de suite",
+    messengerNotUrgentTitle: "Pas pressé ? Message prêt",
+    messengerNotUrgentLede: "Un message sur WhatsApp suffit. Réf. {ref}.",
+    messengerSheetCta: "Recevoir mon devis",
+    messengerSheetTitle: "Où recevoir votre devis ?",
+    messengerChipWhatsapp: "Réponse sur WhatsApp",
+    messengerChipCall: "Réponse par appel",
+    messengerChipTelegram: "Réponse sur Telegram",
+    messengerSplitCta: "Devis sur WhatsApp",
+    messengerInappHint: "WhatsApp ne s’ouvre pas ? Menu ⋯ → « Ouvrir dans le navigateur ».",
+    messengerCopy: "Copier le message",
+    messengerCopied: "Message copié",
+    messengerReturnTitle: "Message envoyé ?",
+    messengerReturnBody: "Si oui, on vous répond sur {channel} rapidement, référence {ref}.",
+    messengerReopen: "Rouvrir {channel}",
+    messengerReturnFailed: "Je n’ai pas pu envoyer → être rappelé",
+    messengerReturnDone: "C’est envoyé",
+    messengerQrTitle: "Scannez avec votre téléphone",
+    messengerQrLede: "WhatsApp s’ouvre avec votre demande déjà rédigée.",
+    messengerQrWeb: "ou ouvrir WhatsApp Web →",
+    messengerQrAlt: "QR code qui ouvre WhatsApp avec votre demande",
+};
+const EN = {
+    messageHello: "Hello {brand} 👋",
+    messageNeed: "I would like a quote: {need}",
+    messagePostcode: "Postcode: {postcode}",
+    messagePrice: "Estimate seen on the site: {price}",
+    messageTiming: "When: {timing}",
+    messageRef: "Ref. {ref}",
+    messengerWhatsappCta: "Get my quote on WhatsApp",
+    messengerOpenWhatsapp: "Open WhatsApp",
+    messengerTelegramCta: "Open Telegram",
+    messengerViaTelegram: "or via Telegram",
+    messengerOptionWhatsapp: "WhatsApp",
+    messengerOptionWhatsappNote: "Recommended · request already written",
+    messengerOptionCall: "Call",
+    messengerOptionCallNote: "We call you back shortly",
+    messengerOptionTelegram: "Telegram",
+    messengerOptionTelegramNote: "Through our Telegram bot",
+    messengerRecommended: "Recommended",
+    messengerChannelLabel: "Where to answer you",
+    messengerCallback: "Call me back",
+    messengerBackToWhatsapp: "Back to WhatsApp",
+    messengerPhoneOptional: "Phone (optional)",
+    messengerWhatsappHint: "WhatsApp opens with your request written. Phone optional.",
+    messengerTelegramHint: "Telegram opens: our bot answers you.",
+    messengerPreviewTitle: "Your message is ready",
+    messengerPreviewPrice: "{price}",
+    messengerPreviewNote: "",
+    messengerBotTitle: "Our bot sends you the quote",
+    messengerBotLede: "Telegram opens: tap “Start” and the quote arrives in the chat.",
+    messengerTilesLabel: "Get my quote by",
+    messengerThanksTitle: "Faster: send a photo",
+    messengerThanksCta: "Send the photo on WhatsApp",
+    messengerSagaTitle: "How would you like to reach us?",
+    messengerSagaLede: "A quick answer, no commitment.",
+    messengerSagaFoot: "Quick answer · no commitment",
+    messengerChange: "Change channel",
+    messengerWhatsappTitle: "On WhatsApp",
+    messengerWhatsappLede: "Then WhatsApp opens with the message ready.",
+    messengerTelegramTitle: "On Telegram",
+    messengerTelegramLede: "Then Telegram opens: our bot answers you.",
+    messengerCallTitle: "We call you back",
+    messengerCallLede: "Leave your number.",
+    messengerUrgencyLabel: "Is it urgent?",
+    messengerUrgencyYes: "Yes, today",
+    messengerUrgencyNo: "No, comparing",
+    messengerUrgencyToday: "today",
+    messengerUrgencyLater: "no rush",
+    messengerUrgentSubmit: "Call me right away",
+    messengerNotUrgentTitle: "No rush? Message ready",
+    messengerNotUrgentLede: "A WhatsApp message is enough. Ref. {ref}.",
+    messengerSheetCta: "Get my quote",
+    messengerSheetTitle: "Where should we send your quote?",
+    messengerChipWhatsapp: "Answer on WhatsApp",
+    messengerChipCall: "Answer by phone",
+    messengerChipTelegram: "Answer on Telegram",
+    messengerSplitCta: "Quote on WhatsApp",
+    messengerInappHint: "WhatsApp does not open? Menu ⋯ → “Open in browser”.",
+    messengerCopy: "Copy the message",
+    messengerCopied: "Message copied",
+    messengerReturnTitle: "Message sent?",
+    messengerReturnBody: "If so, we answer you on {channel} shortly, reference {ref}.",
+    messengerReopen: "Open {channel} again",
+    messengerReturnFailed: "I could not send it → call me back",
+    messengerReturnDone: "It is sent",
+    messengerQrTitle: "Scan with your phone",
+    messengerQrLede: "WhatsApp opens with your request already written.",
+    messengerQrWeb: "or open WhatsApp Web →",
+    messengerQrAlt: "QR code that opens WhatsApp with your request",
+};
+export const LEAD_CAPTURE_MESSENGER_TEXT = { fr: FR, en: EN };
+/** The variants' words for a page: the brand's, else the kit's in its language (English for `en*`, French otherwise). */
+export function messengerTextOf(text, locale) {
+    const kit = locale.startsWith("en") ? EN : FR;
+    const out = { ...kit };
+    for (const key of Object.keys(kit)) {
+        const own = text[key];
+        if (own !== undefined)
+            out[key] = own;
+    }
+    return out;
+}

package/dist/core/messenger.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The messenger channels: WhatsApp, where the customer sends our prefilled
+ * message, and Telegram, the brand's bot opened with a deep link. Either way
+ * the lead is posted first, carrying a short reference the customer's message
+ * carries too (`message_ref`) — the one thing that joins the chat to the lead.
+ */
+/** The form field the reference is posted under. */
+export declare const MESSAGE_REF_FIELD = "message_ref";
+/**
+ * `<PREFIX>-<4..8 chars>` in Crockford base32 without I, L, O, U — read aloud
+ * and typed back without a mix-up. The panel's own rule, the same regex.
+ */
+export declare const MESSAGE_REF: RegExp;
+/** A brand's reference prefix (`AQ`, `VF`). */
+export declare const MESSAGE_REF_PREFIX: RegExp;
+/** The random bytes a reference is drawn from; a test passes its own. */
+export type RandomBytes = (length: number) => Uint8Array;
+/**
+ * A fresh reference, `AQ-7K3F`. Not a secret and not unique — 32⁴ per prefix
+ * collide sooner or later, and the panel resolves a reference to the brand's
+ * newest lead — just short enough to survive a chat.
+ */
+export declare function newMessageRef(prefix: string, random?: RandomBytes): string;
+/** A posted reference, when it is one; anything else is dropped, never refused. */
+export declare function messageRefOf(value: unknown): string | null;
+/**
+ * A Telegram bot's username, without `@`: Telegram's own rule for a bot — 5
+ * to 32 characters, a letter first, ending in `bot` — and the panel's.
+ */
+export declare const TELEGRAM_BOT: RegExp;
+/**
+ * The bot's deep link, `https://t.me/<bot>?start=<ref>`. The `start`
+ * parameter allows `A-Za-z0-9_-` only — a reference always is — so anything
+ * else is left off rather than encoded into a link the bot would not read.
+ */
+export declare function telegramHref(bot: string, start?: string): string;
+/**
+ * What a card may offer for the messengers (`messengerFacts`): the place's
+ * own WhatsApp number — never the brand's phone as a fallback, the chat is
+ * answered by hand — and its bot. `null` → not offered.
+ */
+export interface MessengerFacts {
+    whatsapp: string | null;
+    telegram: string | null;
+}
+/** Which messengers a card offered, as every event of a `LeadCapture` says it (`channels_available`). */
+export type ChannelsAvailable = "wa,tg" | "wa" | "tg" | "none";
+export declare function channelsAvailable(facts: MessengerFacts | null | undefined): ChannelsAvailable;
+/**
+ * How a `LeadCapture` offers the messengers — an arm of the site's
+ * `lead_channel` experiment; `undefined` is the control. Every kind falls
+ * back to the control when the place has no WhatsApp (`urgency` keeps its
+ * question; `thanks` keeps its Telegram button), and loses its Telegram
+ * pieces when the place has no bot.
+ *
+ * - `select`: a channel select inside the phone field, before or after it;
+ * - `segment`: «WhatsApp | Appel» over a fixed slot — the message or the phone;
+ * - `tiles`: WhatsApp / Telegram / Appel tiles over the slot;
+ * - `thanks`: the control's form; its success offers WhatsApp (a photo) and Telegram;
+ * - `swap`: no phone until «Être rappelé» swaps the WhatsApp button for it;
+ * - `saga`: the channel first, on a screen of its own, then the job;
+ * - `urgency`: «C’est urgent ?» — posted as the brand's extra `field` — picks a call or WhatsApp;
+ * - `sheet`: one button, the channels in a drawer;
+ * - `chip`: the lede becomes a channel chip with a menu;
+ * - `split`: a WhatsApp button with Telegram and call squares beside it.
+ */
+export type MessengerVariant = {
+    kind: "select";
+    side: "prefix" | "suffix";
+} | {
+    kind: "segment";
+} | {
+    kind: "tiles";
+} | {
+    kind: "thanks";
+} | {
+    kind: "swap";
+} | {
+    kind: "saga";
+} | {
+    kind: "urgency";
+    field: string;
+} | {
+    kind: "sheet";
+} | {
+    kind: "chip";
+} | {
+    kind: "split";
+};
+export type MessengerKind = MessengerVariant["kind"];
+/** A channel the visitor picked in a variant: a messenger, or the phone. */
+export type MessengerMode = "whatsapp" | "telegram" | "call";

package/dist/core/messenger.js

@@ -0,0 +1,55 @@
+/**
+ * The messenger channels: WhatsApp, where the customer sends our prefilled
+ * message, and Telegram, the brand's bot opened with a deep link. Either way
+ * the lead is posted first, carrying a short reference the customer's message
+ * carries too (`message_ref`) — the one thing that joins the chat to the lead.
+ */
+/** The form field the reference is posted under. */
+export const MESSAGE_REF_FIELD = "message_ref";
+/**
+ * `<PREFIX>-<4..8 chars>` in Crockford base32 without I, L, O, U — read aloud
+ * and typed back without a mix-up. The panel's own rule, the same regex.
+ */
+export const MESSAGE_REF = /^[A-Z]{2,4}-[0-9A-HJKMNP-TV-Z]{4,8}$/;
+/** A brand's reference prefix (`AQ`, `VF`). */
+export const MESSAGE_REF_PREFIX = /^[A-Z]{2,4}$/;
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const cryptoBytes = length => crypto.getRandomValues(new Uint8Array(length));
+/**
+ * A fresh reference, `AQ-7K3F`. Not a secret and not unique — 32⁴ per prefix
+ * collide sooner or later, and the panel resolves a reference to the brand's
+ * newest lead — just short enough to survive a chat.
+ */
+export function newMessageRef(prefix, random = cryptoBytes) {
+    if (!MESSAGE_REF_PREFIX.test(prefix))
+        throw new Error(`message ref: the prefix must be 2–4 capital letters, got ${JSON.stringify(prefix)}`);
+    // 32 divides 256: a byte masked to five bits draws each symbol evenly.
+    const body = [...random(4)].map(b => CROCKFORD[b & 31] ?? "0").join("");
+    return `${prefix}-${body}`;
+}
+/** A posted reference, when it is one; anything else is dropped, never refused. */
+export function messageRefOf(value) {
+    if (typeof value !== "string")
+        return null;
+    const ref = value.trim().toUpperCase();
+    return MESSAGE_REF.test(ref) ? ref : null;
+}
+/**
+ * A Telegram bot's username, without `@`: Telegram's own rule for a bot — 5
+ * to 32 characters, a letter first, ending in `bot` — and the panel's.
+ */
+export const TELEGRAM_BOT = /^[A-Za-z][A-Za-z0-9_]{1,28}[Bb][Oo][Tt]$/;
+/**
+ * The bot's deep link, `https://t.me/<bot>?start=<ref>`. The `start`
+ * parameter allows `A-Za-z0-9_-` only — a reference always is — so anything
+ * else is left off rather than encoded into a link the bot would not read.
+ */
+export function telegramHref(bot, start) {
+    const name = bot.replace(/^@/, "");
+    return start && /^[A-Za-z0-9_-]{1,64}$/.test(start) ? `https://t.me/${name}?start=${start}` : `https://t.me/${name}`;
+}
+export function channelsAvailable(facts) {
+    const wa = Boolean(facts?.whatsapp);
+    const tg = Boolean(facts?.telegram);
+    return wa && tg ? "wa,tg" : wa ? "wa" : tg ? "tg" : "none";
+}

package/dist/core/place/index.d.ts

@@ -1,4 +1,4 @@
-export { servedLocalities, storefrontOf, type DayOfWeek, type Geo, type OpeningHours, type Place, type PostalAddress, type Presence, type Rating, type ServiceArea, } from "./types.js";
+export { servedLocalities, storefrontOf, type DayOfWeek, type Geo, type MessengerSwitches, type OpeningHours, type Place, type PostalAddress, type Presence, type Rating, type ServiceArea, } from "./types.js";
 export { isPublished, publicationGaps, SERVICE_AREA_GATE, STOREFRONT_GATE, type PublicationField, type PublicationPolicy, } from "./publication.js";
 export { DEFAULT_TIME_ZONE, isOpenAt, nextOpening, type Opening } from "./hours.js";
 export { freshRating, parseInstant, RATING_MAX_AGE_DAYS } from "./rating.js";

package/dist/core/place/live.d.ts

@@ -1,5 +1,5 @@
 import type { BookingConfig, BookingRules } from "../booking/model.js";
-import type { Geo, OpeningHours, Place, PostalAddress, Rating, ServiceArea } from "./types.js";
+import type { Geo, MessengerSwitches, OpeningHours, Place, PostalAddress, Rating, ServiceArea } from "./types.js";
 /**
  * The live half of a place, as `GET <source>/locations/<slug>` answers it.
  * Every field is optional: whatever the source leaves out, the baked config
@@ -19,6 +19,10 @@ export interface PlaceLive<L extends string> {
     rating?: Rating;
     /** Validated with the site's Cal.com hosts; one that does not validate is dropped, the baked one kept. */
     booking?: BookingConfig;
+    /** The place's Telegram bot, its username without `@` (`TELEGRAM_BOT`). */
+    telegram?: string;
+    /** The panel's kill switches for the messengers; a key left out is on. */
+    messengers?: MessengerSwitches;
 }
 /**
  * Drops what does not validate instead of failing the page on one bad field.

package/dist/core/place/live.js

@@ -1,4 +1,5 @@
 import { BookingConfigError, parseBookingConfig } from "../booking/validate.js";
+import { TELEGRAM_BOT } from "../messenger.js";
 import { parseInstant } from "./rating.js";
 const DAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
 const TIME = /^([01]\d|2[0-3]):[0-5]\d$/;
@@ -61,6 +62,17 @@ function landmark(v, locales) {
 function isComplete(record, locales) {
     return locales.every(locale => typeof record[locale] === "string");
 }
+/** Each switch only when it is a boolean: a switch that does not read is left on. */
+function messengers(v) {
+    if (!isObject(v))
+        return undefined;
+    const out = {};
+    if (typeof v.whatsapp === "boolean")
+        out.whatsapp = v.whatsapp;
+    if (typeof v.telegram === "boolean")
+        out.telegram = v.telegram;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function booking(v, rules) {
     if (v === undefined || v === null)
         return undefined;
@@ -121,6 +133,12 @@ export function parsePlaceLive(body, locales, rules = {}) {
     const b = booking(body.booking, rules);
     if (b)
         live.booking = b;
+    const bot = str(body.telegram)?.replace(/^@/, "");
+    if (bot && TELEGRAM_BOT.test(bot))
+        live.telegram = bot;
+    const m = messengers(body.messengers);
+    if (m)
+        live.messengers = m;
     return live;
 }
 /**
@@ -131,6 +149,8 @@ export function parsePlaceLive(body, locales, rules = {}) {
 export function mergeLive(baked, live) {
     const front = baked.presence;
     const booking = live.booking ?? baked.booking;
+    const telegram = live.telegram ?? baked.channels.telegram;
+    const switches = live.messengers ?? baked.messengers;
     return {
         ...baked,
         presence: front.kind === "storefront"
@@ -142,10 +162,11 @@ export function mergeLive(baked, live) {
                 landmark: live.landmark ?? front.landmark,
             }
             : front,
-        channels: { phone: live.phone ?? baked.channels.phone, whatsapp: live.whatsapp ?? baked.channels.whatsapp },
+        channels: { phone: live.phone ?? baked.channels.phone, whatsapp: live.whatsapp ?? baked.channels.whatsapp, ...(telegram !== undefined ? { telegram } : {}) },
         serviceArea: live.serviceArea ?? baked.serviceArea,
         hours: live.hours ?? baked.hours,
         rating: live.rating ?? baked.rating,
         ...(booking ? { booking } : {}),
+        ...(switches ? { messengers: switches } : {}),
     };
 }

package/dist/core/place/types.d.ts

@@ -72,11 +72,22 @@ export interface Place<L extends string> {
     name: Readonly<Record<L, string>>;
     presence: Presence<L>;
     serviceArea: readonly ServiceArea[] | null;
-    /** International numbers as printed; `null` → the brand's own. */
+    /**
+     * International numbers as printed; `null` → the brand's own. `telegram`:
+     * the place's bot, its username without `@` (`PlaceLive.telegram`) —
+     * absent or `null`, no bot; never the brand's.
+     */
     channels: {
         phone: string | null;
         whatsapp: string | null;
+        telegram?: string | null;
     };
+    /**
+     * The panel's switches for the messengers (`PlaceLive.messengers`): `false`
+     * takes one off the lead form's messenger variants (`messengerFacts`) only —
+     * `contactOf`, the header's and the call bar's numbers, keeps it; absent is on.
+     */
+    messengers?: MessengerSwitches;
     hours: readonly OpeningHours[] | null;
     /** Live only. */
     rating: Rating | null;
@@ -86,6 +97,11 @@ export interface Place<L extends string> {
      */
     booking?: BookingConfig;
 }
+/** Which messengers the panel lets a place offer; a key left out is on. */
+export interface MessengerSwitches {
+    whatsapp?: boolean;
+    telegram?: boolean;
+}
 /** The storefront half of a place, or `null` for a service-area business. */
 export declare function storefrontOf<L extends string>(place: Place<L>): Extract<Presence<L>, {
     kind: "storefront";