@evinvest/kitstart 0.8.0 → 0.10.0

package/dist/core/phone.js

@@ -1,35 +1,59 @@
 /**
- * A phone number as the funnel keeps it: E.164 when the typed value is one we
- * can read, otherwise exactly as typed. Soft by design — a number we cannot
- * parse is still a way to reach someone, and refusing it loses the customer.
+ * A phone number as the funnel reads it: E.164 when the typed value is a
+ * number someone can be reached on, otherwise `null`.
  *
- * Only the French national plan is read (every brand of the vertical is in
- * France): `06 12 34 56 78`, `+33 (0)6 …`, `0033 6 …` and a mobile typed
- * without its trunk zero (`6 12 34 56 78`) all become `+33612345678`. Any
- * other international number is compacted (`+44 7911 123456` →
- * `+447911123456`); anything else is `null`.
+ * Only the French national plan is read closely (every brand of the vertical
+ * is in France): ten digits from `0[1-9]` — `06 12 34 56 78`, `+33 (0)6 …`,
+ * `0033 6 …`, a mobile typed without its trunk zero (`6 12 34 56 78`) — all
+ * become `+33612345678`. Any other international number is a plausible E.164,
+ * 8 to 15 digits after the `+`, compacted (`+44 7911 123456` →
+ * `+447911123456`). Full-width digits read as digits; a run of one digit
+ * (`00 00 00 00 00`, `06 66 66 66 66`) is a refusal to give a number, not one.
  */
 export function normalizePhone(raw) {
-    let s = raw.replace(/\(0\)/g, "").replace(/[\s.\-()/ ]/g, "");
+    // NFKC: a Japanese or Chinese keyboard types full-width digits and `＋`,
+    // and a pasted number may carry no-break spaces. `\s` takes those too.
+    let s = raw.normalize("NFKC").replace(/\(0\)/g, "").replace(/[\s.\-()/]/g, "");
     if (s.startsWith("00"))
         s = `+${s.slice(2)}`;
+    let e164 = null;
     if (s.startsWith("+33")) {
         const national = /^\+330?([1-9]\d{8})$/.exec(s);
-        return national ? `+33${national[1]}` : null;
+        e164 = national ? `+33${national[1]}` : null;
     }
-    const trunk = /^0([1-9]\d{8})$/.exec(s);
-    if (trunk)
-        return `+33${trunk[1]}`;
-    if (/^[1-9]\d{8}$/.test(s))
-        return `+33${s}`;
-    if (/^\+[1-9]\d{7,14}$/.test(s))
-        return s;
-    return null;
+    else {
+        const trunk = /^0([1-9]\d{8})$/.exec(s);
+        if (trunk)
+            e164 = `+33${trunk[1]}`;
+        else if (/^[1-9]\d{8}$/.test(s))
+            e164 = `+33${s}`;
+        else if (/^\+[1-9]\d{7,14}$/.test(s))
+            e164 = s;
+    }
+    if (e164 === null)
+        return null;
+    // The subscriber's digits: past `+33` for a French number, past `+` otherwise.
+    const subscriber = e164.startsWith("+33") ? e164.slice(3) : e164.slice(1);
+    return /^(\d)\1+$/.test(subscriber) ? null : e164;
 }
-/** Whether a typed number reads as one — the form's soft check, never a block. */
+/**
+ * Whether a typed number is one we can call back — the one rule the form,
+ * the callback and the server share (`phoneProblem`, `validateLead`).
+ */
 export function isPlausiblePhone(raw) {
     return normalizePhone(raw) !== null;
 }
+/**
+ * What is wrong with a typed number, or `null`: `required` when nothing was
+ * typed, `invalid` when it is not a number we can call. The form blocks on it
+ * in the page's words and the server refuses on it — one rule, so a number
+ * the form lets through is never refused behind the visitor's back.
+ */
+export function phoneProblem(raw) {
+    if (raw.trim() === "")
+        return "required";
+    return isPlausiblePhone(raw) ? null : "invalid";
+}
 /**
  * A French mobile (`+33 6…`, `+33 7…`) — the one kind an SMS reaches. A
  * landline answers a text with silence, so the channel is not offered for it.

package/dist/core/pricing/flow.d.ts

@@ -0,0 +1,27 @@
+import type { PricingInputs, PricingModel } from "./model.js";
+/**
+ * How a need is sold. `quote`: the price is uncertain, the lead asks for one.
+ * `estimate`: the price follows from a few enum answers, shown live, then a
+ * slot is booked. `fixed`: one price for a well-defined job, then a slot.
+ * Chosen per need, not per site: one brand can mix them.
+ */
+export type LeadFlow = "quote" | "estimate" | "fixed";
+export declare const LEAD_FLOWS: readonly LeadFlow[];
+/** A brand's flows by subject slug; a need left out is a `quote`. */
+export type LeadFlows = Readonly<Record<string, LeadFlow>>;
+/**
+ * The flow a need actually runs: the brand's, when the model prices the need
+ * that way — an `estimate` the model cannot price (a remote model without
+ * it, no model at all) is a `quote`, never a form with no price. The form and
+ * the server both ask this, so they agree on what was shown.
+ */
+export declare function flowOf(flows: LeadFlows | undefined, model: PricingModel | null, need: string | undefined): LeadFlow;
+/** The form field an estimate's input is posted under: `estimate_<input id>`. */
+export declare const ESTIMATE_FIELD_PREFIX = "estimate_";
+export declare const estimateField: (input: string) => string;
+/**
+ * The answers a form posted for the need's inputs — only those, and only
+ * slugs. Read by the server, which prices them itself: a posted amount, if
+ * any, is never read.
+ */
+export declare function readEstimateInputs(model: PricingModel, need: string, get: (field: string) => string | null): PricingInputs;

package/dist/core/pricing/flow.js

@@ -0,0 +1,37 @@
+import { PRICING_LIMITS } from "./model.js";
+export const LEAD_FLOWS = ["quote", "estimate", "fixed"];
+/**
+ * The flow a need actually runs: the brand's, when the model prices the need
+ * that way — an `estimate` the model cannot price (a remote model without
+ * it, no model at all) is a `quote`, never a form with no price. The form and
+ * the server both ask this, so they agree on what was shown.
+ */
+export function flowOf(flows, model, need) {
+    if (!flows || !model || need === undefined || !Object.hasOwn(flows, need))
+        return "quote";
+    const wanted = flows[need];
+    if (wanted === undefined || wanted === "quote")
+        return "quote";
+    const pricing = Object.hasOwn(model.needs, need) ? model.needs[need] : undefined;
+    return pricing?.kind === wanted ? wanted : "quote";
+}
+/** The form field an estimate's input is posted under: `estimate_<input id>`. */
+export const ESTIMATE_FIELD_PREFIX = "estimate_";
+export const estimateField = (input) => `${ESTIMATE_FIELD_PREFIX}${input}`;
+/**
+ * The answers a form posted for the need's inputs — only those, and only
+ * slugs. Read by the server, which prices them itself: a posted amount, if
+ * any, is never read.
+ */
+export function readEstimateInputs(model, need, get) {
+    const pricing = Object.hasOwn(model.needs, need) ? model.needs[need] : undefined;
+    if (pricing?.kind !== "estimate")
+        return {};
+    const out = {};
+    for (const id of pricing.inputs) {
+        const value = get(estimateField(id))?.trim();
+        if (value && PRICING_LIMITS.slug.test(value))
+            out[id] = value;
+    }
+    return out;
+}

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

@@ -0,0 +1,4 @@
+export { PRICING_CURRENCY, PRICING_FORMAT, PRICING_LIMITS, type AddOption, type DiscountOption, type MultiplyOption, type NeedPricing, type Price, type PriceLine, type PricingInput, type PricingInputKind, type PricingInputs, type PricingLabels, type PricingModel, } from "./model.js";
+export { CENTS_BUCKETS, centsBucket, mulBp, priceOf, roundTo } from "./price.js";
+export { labelOf, parsePricingModel, PricingModelError, pricingProblems, pricingProblemsFor } from "./validate.js";
+export { ESTIMATE_FIELD_PREFIX, estimateField, flowOf, LEAD_FLOWS, readEstimateInputs, type LeadFlow, type LeadFlows } from "./flow.js";

package/dist/core/pricing/index.js

@@ -0,0 +1,4 @@
+export { PRICING_CURRENCY, PRICING_FORMAT, PRICING_LIMITS, } from "./model.js";
+export { CENTS_BUCKETS, centsBucket, mulBp, priceOf, roundTo } from "./price.js";
+export { labelOf, parsePricingModel, PricingModelError, pricingProblems, pricingProblemsFor } from "./validate.js";
+export { ESTIMATE_FIELD_PREFIX, estimateField, flowOf, LEAD_FLOWS, readEstimateInputs } from "./flow.js";

package/dist/core/pricing/model.d.ts

@@ -0,0 +1,129 @@
+/**
+ * A brand's price list as data: what an `estimate` need costs for a set of
+ * enum inputs, and what a `fixed` need costs outright. JSON-serialisable on
+ * purpose — the panel edits it, serves it, and prices its own preview with a
+ * port of `priceOf` held to the same fixtures (`test/fixtures/pricing/`).
+ *
+ * Money is integer euro cents, TTC, throughout; a multiplier or a discount is
+ * in basis points (10 000 = ×1, 1 000 = 10 %), so no float ever reaches a
+ * stored or sent number.
+ */
+/** The model's format; a model of another format is refused whole. */
+export declare const PRICING_FORMAT = 1;
+/** The only currency a model may be in today: euros, all taxes included. */
+export declare const PRICING_CURRENCY = "EUR";
+/** A label per locale (`{ fr: "Studio", en: "Studio" }`); the page picks its own. */
+export type PricingLabels = Readonly<Record<string, string>>;
+/** One choice of an input: its slug, its words, and what it does to the price. */
+export interface AddOption {
+    id: string;
+    labels: PricingLabels;
+    /** Added to the base, in cents. */
+    addCents: number;
+}
+export interface MultiplyOption {
+    id: string;
+    labels: PricingLabels;
+    /** The subtotal times this, in basis points: 11 000 is ×1.1. */
+    multiplyBp: number;
+}
+export interface DiscountOption {
+    id: string;
+    labels: PricingLabels;
+    /** Taken off the subtotal, in basis points: 1 000 is 10 % off, 0 none. */
+    discountBp: number;
+}
+/**
+ * An enum the visitor answers — bedrooms, a surface band, a zone, a
+ * frequency. Its `kind` says what its options do, and when (see `priceOf`):
+ * every `add` first, then every `multiply`, then every `discount`.
+ */
+export type PricingInput = {
+    id: string;
+    kind: "add";
+    labels: PricingLabels;
+    options: readonly AddOption[];
+} | {
+    id: string;
+    kind: "multiply";
+    labels: PricingLabels;
+    options: readonly MultiplyOption[];
+} | {
+    id: string;
+    kind: "discount";
+    labels: PricingLabels;
+    options: readonly DiscountOption[];
+};
+export type PricingInputKind = PricingInput["kind"];
+/**
+ * How one need is priced. `estimate`: a base and the inputs the visitor
+ * answers, in the order the form asks them. `fixed`: one price, exactly —
+ * neither rounded nor raised to the minimum, which are the estimate's.
+ */
+export type NeedPricing = {
+    kind: "estimate";
+    baseCents: number;
+    inputs: readonly string[];
+} | {
+    kind: "fixed";
+    cents: number;
+};
+export interface PricingModel {
+    format: typeof PRICING_FORMAT;
+    currency: typeof PRICING_CURRENCY;
+    /** The date the prices hold from, `YYYY-MM-DD` — stored with every lead priced by it. */
+    validFrom: string;
+    /** The estimate's total is rounded half up to a multiple of this (1 = to the cent). */
+    roundToCents: number;
+    /** An estimate never comes out below this, after the rounding. */
+    minimumCents: number;
+    inputs: readonly PricingInput[];
+    /** By the brand's subject slug; a need not here is a `quote`. */
+    needs: Readonly<Record<string, NeedPricing>>;
+}
+/** The answers to an estimate's inputs: input id → option id. */
+export type PricingInputs = Readonly<Record<string, string>>;
+/**
+ * One line of how a price was reached; `cents` is what the line changed, so
+ * the lines add up to the total. `base` is the need's base (or the fixed
+ * price); `rounding` and `minimum` appear only when they changed something.
+ */
+export type PriceLine = {
+    kind: "base";
+    cents: number;
+} | {
+    kind: "add" | "multiply" | "discount";
+    input: string;
+    option: string;
+    cents: number;
+} | {
+    kind: "rounding";
+    cents: number;
+} | {
+    kind: "minimum";
+    cents: number;
+};
+export interface Price {
+    cents: number;
+    breakdown: readonly PriceLine[];
+}
+/**
+ * The model's limits. Ids are slugs (they travel to the panel as
+ * `estimate_inputs`, which takes at most 12 pairs); every amount, and every
+ * step of the dearest combination, stays at or under `MAX_PRICE_CENTS`, so
+ * each product fits a double exactly and a 64-bit integer with room to spare.
+ */
+export declare const PRICING_LIMITS: {
+    readonly slug: RegExp;
+    readonly locale: RegExp;
+    readonly maxLabel: 120;
+    readonly maxInputs: 32;
+    readonly maxOptions: 32;
+    readonly maxNeeds: 64;
+    /** Per need: what `estimate_inputs` may carry. */
+    readonly maxNeedInputs: 12;
+    readonly maxPriceCents: 100000000;
+    /** ×10 at most. */
+    readonly maxMultiplyBp: 100000;
+    readonly maxDiscountBp: 10000;
+};

package/dist/core/pricing/model.js

@@ -0,0 +1,34 @@
+/**
+ * A brand's price list as data: what an `estimate` need costs for a set of
+ * enum inputs, and what a `fixed` need costs outright. JSON-serialisable on
+ * purpose — the panel edits it, serves it, and prices its own preview with a
+ * port of `priceOf` held to the same fixtures (`test/fixtures/pricing/`).
+ *
+ * Money is integer euro cents, TTC, throughout; a multiplier or a discount is
+ * in basis points (10 000 = ×1, 1 000 = 10 %), so no float ever reaches a
+ * stored or sent number.
+ */
+/** The model's format; a model of another format is refused whole. */
+export const PRICING_FORMAT = 1;
+/** The only currency a model may be in today: euros, all taxes included. */
+export const PRICING_CURRENCY = "EUR";
+/**
+ * The model's limits. Ids are slugs (they travel to the panel as
+ * `estimate_inputs`, which takes at most 12 pairs); every amount, and every
+ * step of the dearest combination, stays at or under `MAX_PRICE_CENTS`, so
+ * each product fits a double exactly and a 64-bit integer with room to spare.
+ */
+export const PRICING_LIMITS = {
+    slug: /^[a-z0-9_-]{1,40}$/,
+    locale: /^[a-z]{2}(-[A-Z]{2})?$/,
+    maxLabel: 120,
+    maxInputs: 32,
+    maxOptions: 32,
+    maxNeeds: 64,
+    /** Per need: what `estimate_inputs` may carry. */
+    maxNeedInputs: 12,
+    maxPriceCents: 100_000_000,
+    /** ×10 at most. */
+    maxMultiplyBp: 100_000,
+    maxDiscountBp: 10_000,
+};

package/dist/core/pricing/price.d.ts

@@ -0,0 +1,34 @@
+import type { Price, PricingInputs, PricingModel } from "./model.js";
+/**
+ * `cents × bp / 10 000`, rounded half up to the cent. Integers throughout:
+ * the product is exact (the model's limits keep it under 2^53), and the
+ * division is done on the remainder, never on a float.
+ */
+export declare function mulBp(cents: number, bp: number): number;
+/** Half up to a multiple of `step` (≥ 1). */
+export declare function roundTo(cents: number, step: number): number;
+/**
+ * What a need costs for these answers — the one function the form shows and
+ * the server stores, and the one the panel's preview ports. Normative order:
+ *
+ * 1. the need's base, plus every `add` input, in the need's input order;
+ * 2. times every `multiply` input, in order, each product rounded half up to
+ *    the cent at once;
+ * 3. less every `discount` input, in order, each as a multiplication by
+ *    `10 000 − discountBp` rounded the same way;
+ * 4. the total rounded half up to a multiple of `roundToCents`;
+ * 5. raised to `minimumCents`.
+ *
+ * A `fixed` need is its price, as is. `null`: the need is not priced, or an
+ * input is unanswered or answered with an option it does not have — never a
+ * guess. Answers to inputs the need does not ask are ignored.
+ */
+export declare function priceOf(model: PricingModel, need: string, inputs: PricingInputs): Price | null;
+/**
+ * The band a price falls in, for analytics: `"5000-7500"` (cents, lower
+ * bound included), never the price itself — a funnel needs the shape of
+ * what was shown, not a number that, with a time and a place, singles a
+ * visitor out.
+ */
+export declare const CENTS_BUCKETS: readonly number[];
+export declare function centsBucket(cents: number): string;

package/dist/core/pricing/price.js

@@ -0,0 +1,105 @@
+const BP = 10_000;
+/**
+ * `cents × bp / 10 000`, rounded half up to the cent. Integers throughout:
+ * the product is exact (the model's limits keep it under 2^53), and the
+ * division is done on the remainder, never on a float.
+ */
+export function mulBp(cents, bp) {
+    const n = cents * bp + BP / 2;
+    return (n - (n % BP)) / BP;
+}
+/** Half up to a multiple of `step` (≥ 1). */
+export function roundTo(cents, step) {
+    const rest = cents % step;
+    return rest * 2 >= step ? cents - rest + step : cents - rest;
+}
+/** The option answered for each of the need's inputs, or `null` when one is missing or unknown. */
+function chosen(model, ids, inputs) {
+    const out = [];
+    for (const id of ids) {
+        const input = model.inputs.find(i => i.id === id);
+        const answer = Object.hasOwn(inputs, id) ? inputs[id] : undefined;
+        if (!input || answer === undefined)
+            return null;
+        const effect = effectOf(input, answer);
+        if (effect === null)
+            return null;
+        out.push({ input, option: answer, effect });
+    }
+    return out;
+}
+function effectOf(input, option) {
+    switch (input.kind) {
+        case "add":
+            return input.options.find(o => o.id === option)?.addCents ?? null;
+        case "multiply":
+            return input.options.find(o => o.id === option)?.multiplyBp ?? null;
+        case "discount":
+            return input.options.find(o => o.id === option)?.discountBp ?? null;
+    }
+}
+/**
+ * What a need costs for these answers — the one function the form shows and
+ * the server stores, and the one the panel's preview ports. Normative order:
+ *
+ * 1. the need's base, plus every `add` input, in the need's input order;
+ * 2. times every `multiply` input, in order, each product rounded half up to
+ *    the cent at once;
+ * 3. less every `discount` input, in order, each as a multiplication by
+ *    `10 000 − discountBp` rounded the same way;
+ * 4. the total rounded half up to a multiple of `roundToCents`;
+ * 5. raised to `minimumCents`.
+ *
+ * A `fixed` need is its price, as is. `null`: the need is not priced, or an
+ * input is unanswered or answered with an option it does not have — never a
+ * guess. Answers to inputs the need does not ask are ignored.
+ */
+export function priceOf(model, need, inputs) {
+    const pricing = Object.hasOwn(model.needs, need) ? model.needs[need] : undefined;
+    if (!pricing)
+        return null;
+    if (pricing.kind === "fixed")
+        return { cents: pricing.cents, breakdown: [{ kind: "base", cents: pricing.cents }] };
+    const answers = chosen(model, pricing.inputs, inputs);
+    if (!answers)
+        return null;
+    const lines = [{ kind: "base", cents: pricing.baseCents }];
+    let total = pricing.baseCents;
+    const step = (kind, apply) => {
+        for (const a of answers) {
+            if (a.input.kind !== kind)
+                continue;
+            const next = apply(total, a.effect);
+            lines.push({ kind, input: a.input.id, option: a.option, cents: next - total });
+            total = next;
+        }
+    };
+    step("add", (t, cents) => t + cents);
+    step("multiply", (t, bp) => mulBp(t, bp));
+    step("discount", (t, bp) => mulBp(t, BP - bp));
+    const rounded = roundTo(total, model.roundToCents);
+    if (rounded !== total)
+        lines.push({ kind: "rounding", cents: rounded - total });
+    total = rounded;
+    if (total < model.minimumCents) {
+        lines.push({ kind: "minimum", cents: model.minimumCents - total });
+        total = model.minimumCents;
+    }
+    return { cents: total, breakdown: lines };
+}
+/**
+ * The band a price falls in, for analytics: `"5000-7500"` (cents, lower
+ * bound included), never the price itself — a funnel needs the shape of
+ * what was shown, not a number that, with a time and a place, singles a
+ * visitor out.
+ */
+export const CENTS_BUCKETS = [0, 2_500, 5_000, 7_500, 10_000, 15_000, 20_000, 30_000, 50_000, 100_000];
+export function centsBucket(cents) {
+    let at = 0;
+    for (let i = 0; i < CENTS_BUCKETS.length; i++)
+        if (cents >= (CENTS_BUCKETS[i] ?? 0))
+            at = i;
+    const low = CENTS_BUCKETS[at] ?? 0;
+    const high = CENTS_BUCKETS[at + 1];
+    return high === undefined ? `${low}+` : `${low}-${high}`;
+}

package/dist/core/pricing/validate.d.ts

@@ -0,0 +1,27 @@
+import { type PricingLabels, type PricingModel } from "./model.js";
+/**
+ * A model that does not validate, with every reason found. A model is taken
+ * whole or not at all: one bad field refuses it, so a page never prices from
+ * half a model.
+ */
+export declare class PricingModelError extends Error {
+    readonly problems: readonly string[];
+    readonly name = "PricingModelError";
+    constructor(problems: readonly string[]);
+}
+/**
+ * Every reason `value` is not a pricing model, or none. The panel's editor
+ * holds a model to the same rules (`test/fixtures/pricing/`): unknown fields
+ * are refused, not ignored, so the two never disagree on what a model says.
+ */
+export declare function pricingProblems(value: unknown): string[];
+/** The model `value` is, rebuilt from what was checked; throws `PricingModelError` with every problem. */
+export declare function parsePricingModel(value: unknown): PricingModel;
+/**
+ * A model a site can show: valid, and labelled in every one of its locales —
+ * the panel may serve a model before a language is filled in, and a page
+ * must not show an option with no words.
+ */
+export declare function pricingProblemsFor(value: unknown, locales: readonly string[]): string[];
+/** The label for `locale`, or the first one the model has. */
+export declare function labelOf(labels: PricingLabels, locale: string): string;