@evinvest/sites-contract 0.0.0-stage → 0.1.1

package/dist/generated/wire.d.ts

@@ -0,0 +1,502 @@
+export declare const SCHEMA = "sa.funnel.v1";
+/**
+ * booking.attached@1 — an operator joined a provider's booking to the lead (subject.lead_id):
+ * one the panel could not match, or one matched by contact that they confirm or correct.
+ */
+export type BookingAttachedV1 = {
+    provider: string;
+    external_ref: string;
+};
+/**
+ * booking.canceled@1 — a provider says a booking it reported is canceled. As booking.created.
+ */
+export type BookingCanceledV1 = {
+    provider: string;
+    external_ref: string;
+    version: string;
+};
+/**
+ * booking.cleared@1 — an operator took the lead's slot away: no booking any more.
+ */
+export type BookingClearedV1 = Record<string, never>;
+/**
+ * booking.created@1 — a provider says a slot is booked, or moved (the same external_ref with
+ * another start): written by the panel's adapters only (source.kind booking, source.id the
+ * provider). subject.lead_id: the lead it was matched to, absent while unmatched. The
+ * attendee's name, email and phone go in `pii`, never here.
+ */
+export type BookingCreatedV1 = {
+    /**
+     * google_calendar | cal_com: a provider with an adapter.
+     */
+    provider: string;
+    /**
+     * The provider's id of the booking (Google: the calendar event's id). 1–1024 of
+     * [A-Za-z0-9._:-].
+     */
+    external_ref: string;
+    start_at: string;
+    end_at?: string;
+    /**
+     * ref | contact: how subject.lead_id was found; set exactly when it is.
+     */
+    match?: string;
+    /**
+     * The provider's revision of the booking (Google: the event's etag), 1–256 printable
+     * ASCII: the same revision seen twice is one event.
+     */
+    version: string;
+    /**
+     * When the customer booked, as the provider says (Google: the event's `created`).
+     */
+    booked_at?: string;
+};
+/**
+ * booking.requested@1 — from a site (source.kind site), after the lead's lead.created: the
+ * visitor asked for a slot through `provider`, with an optional wish. No free text, no null.
+ * subject.lead_id required, and `lead_ref` is that same id: the site's leadRef,
+ * `lead-<row>-<8 lowercase hex>`, row ≥ 1. Rules normative in
+ * contracts/vectors/booking/README.md. Arriving before its lead.created, the batch is answered
+ * 409 (`deferred`) for the outbox to send again.
+ */
+export type BookingRequestedV1 = {
+    lead_ref: string;
+    provider: string;
+    /**
+     * "YYYY-MM-DD", a real day, 2 days back to 366 ahead of its arrival; `manual` only.
+     */
+    preferred_date?: string;
+    /**
+     * morning | afternoon | evening; `manual` only.
+     */
+    preferred_part?: string;
+};
+/**
+ * booking.set@1 — an operator put the lead's slot in by hand (or moved it): it is booked.
+ * source.kind panel; subject.lead_id required.
+ */
+export type BookingSetV1 = {
+    start_at: string;
+    end_at?: string;
+};
+/**
+ * booking.status_changed@1 — an operator closed a booked slot: done | no_show | canceled.
+ */
+export type BookingStatusChangedV1 = {
+    status: string;
+};
+/**
+ * call.attempted@1 — an outgoing call started from the panel; subject.lead_id required.
+ */
+export type CallAttemptedV1 = Record<string, never>;
+/**
+ * call.logged@1 — how a call ended, as the operator tells it; subject.lead_id required.
+ */
+export type CallLoggedV1 = {
+    /**
+     * answered | no_answer | wrong_number | later
+     */
+    outcome: string;
+    /**
+     * The id of the call.attempted event this closes, when there was one.
+     */
+    attempt_id?: string;
+};
+/**
+ * contact.metrics@1 — intents at a location (`contact_intent_click`) through one channel.
+ * subject.location_id as for site.metrics.
+ */
+export type ContactMetricsV1 = {
+    day: string;
+    /**
+     * phone | whatsapp | form_open | booking
+     */
+    channel: string;
+    intents: number;
+    revision: number;
+};
+/**
+ * One fact about the funnel, as a source reports it.
+ */
+export type Event = {
+    /**
+     * UUIDv7, issued by the source; the idempotency key. Resending an event with the same
+     * id and the same content is answered `duplicate`; with other content, `rejected`.
+     */
+    id: string;
+    /**
+     * Always "sa.funnel.v1".
+     */
+    schema: string;
+    /**
+     * What happened: "lead.created", "call.logged", … A type the panel does not know yet is
+     * stored as unregistered, not dropped, and picked up once it is registered.
+     */
+    type: string;
+    /**
+     * Version of `properties` for this type, 1 to 2147483647.
+     */
+    typeVersion: number;
+    /**
+     * When it happened in the world, not when it was sent.
+     */
+    occurredAt: string;
+    source: Source;
+    subject: Subject;
+    /**
+     * Checked against the message registered for `type@type_version` (the `…V<n>` messages
+     * below). May be omitted when that message has no required fields. At most 16 KiB as
+     * JSON, and no NUL character anywhere — for unregistered types too.
+     */
+    properties: {
+        [key: string]: unknown;
+    };
+    /**
+     * Name, phone, email, … — kept apart, encrypted at rest, never in reporting. Same limits
+     * as `properties`.
+     */
+    pii?: {
+        [key: string]: unknown;
+    };
+};
+export type EventResult = {
+    /**
+     * Position in the request.
+     */
+    index?: number;
+    /**
+     * The event's id as sent; empty when it had none.
+     */
+    id?: string;
+    /**
+     * accepted | duplicate | rejected | deferred (not journaled yet: it names what has not
+     * arrived; the whole batch is answered 409, to be sent again)
+     */
+    status?: string;
+    /**
+     * Why it was rejected; for an accepted event of an unregistered type, that it was stored
+     * without being projected.
+     */
+    reason?: string;
+};
+/**
+ * experiment.configured@1 — an admin's change to one of the brand's experiments, written by the
+ * panel (source.kind panel, source.id the admin's concierge id, or `cli`). subject: the brand
+ * alone. A field absent is left as it was; named in `reset`, it follows the declaration again.
+ */
+export type ExperimentConfiguredV1 = {
+    key: string;
+    enabled?: boolean;
+    /**
+     * 2–32 of them, each ≥ 0, their sum > 0; empty: not set by this change.
+     */
+    weights: number[];
+    /**
+     * [0, 1).
+     */
+    holdout?: number;
+    /**
+     * enabled | weights | holdout.
+     */
+    reset: string[];
+    /**
+     * Who, as the screens show them: the admin's email, or their concierge id when concierge gave
+     * none (as a place's or a price list's history names them). An employee's, not PII. One line,
+     * 1–320 characters.
+     */
+    by: string;
+};
+export type ExperimentDeclaration = {
+    /**
+     * 1–64 of [a-z0-9_].
+     */
+    key: string;
+    /**
+     * 2–32 unique names of 1–32 [a-z0-9_-]; the first is the control.
+     */
+    variants: string[];
+    /**
+     * One per variant, each ≥ 0, their sum > 0.
+     */
+    weights: number[];
+    enabled: boolean;
+    /**
+     * [0, 1).
+     */
+    holdout?: number;
+    /**
+     * The hypothesis, at most 200 characters.
+     */
+    summary?: string;
+};
+/**
+ * experiment.metrics@1 — one variant of one of the brand's experiments, forced (QA) visits
+ * left out. No subject.location_id: the server-side lead event names none.
+ */
+export type ExperimentMetricsV1 = {
+    day: string;
+    /**
+     * Lowercase slugs, as the landing names them ("quote_single_step", "b").
+     */
+    experiment: string;
+    variant: string;
+    /**
+     * Page views shown the variant (`experiment_exposed`).
+     */
+    exposures: number;
+    /**
+     * Leads the landing stored under it (`experiment_lead`).
+     */
+    leads: number;
+    /**
+     * Intents under it, by channel (`experiment_contact{channel}`).
+     */
+    phone: number;
+    whatsapp: number;
+    form_open: number;
+    booking: number;
+    revision: number;
+};
+/**
+ * experiments.declared@1 — what a brand's landing runs, as its code declares it; sent by the
+ * landing (source.kind site) at every start, a new id each time. subject: the brand alone (no
+ * location, lead or job). The panel keeps the latest by occurred_at; an experiment the latest
+ * does not name is retired.
+ */
+export type ExperimentsDeclaredV1 = {
+    /**
+     * At most 64, each key once.
+     */
+    experiments: ExperimentDeclaration[];
+};
+/**
+ * The body of `POST /api/ingest/v1/events`.
+ */
+export type IngestRequest = {
+    /**
+     * 1 to 500 events. Each is judged on its own.
+     */
+    events: Event[];
+};
+/**
+ * The body of the 207 answer: one result per event, in the request's order.
+ */
+export type IngestResponse = {
+    results: EventResult[];
+};
+/**
+ * job.completed@1 — subject.lead_id and subject.job_id required.
+ */
+export type JobCompletedV1 = Record<string, never>;
+/**
+ * job.won@1 — subject.lead_id and subject.job_id required.
+ */
+export type JobWonV1 = Record<string, never>;
+/**
+ * lead.contacted@1 — subject.lead_id required.
+ */
+export type LeadContactedV1 = {
+    /**
+     * phone | whatsapp | email | telegram | other
+     */
+    channel?: string;
+};
+/**
+ * lead.created@1 — subject.lead_id required. Written by a site, the panel, or a bot — a bot
+ * only with channel whatsapp or telegram.
+ */
+export type LeadCreatedV1 = {
+    /**
+     * form | phone_inbound | callback | whatsapp | telegram
+     */
+    channel: string;
+    /**
+     * Who typed it in, for leads entered by hand (a panel user id).
+     */
+    entered_by?: string;
+    /**
+     * rate_limited | too_fast. Set by a landing whose antispam flagged the submission but
+     * kept it, since it may still be a real person: `rate_limited` — the visitor's address
+     * sent more than the landing allows in its window; `too_fast` — the form was sent sooner
+     * after it was shown than a person types. Absent for a lead nothing flagged. A submission
+     * caught by the honeypot is dropped by the landing and never sent.
+     */
+    suspect?: string;
+    /**
+     * The landing's flow for the need (FORM-VARIANTS-SPEC): quote | estimate | fixed. `quote`
+     * asks for a price; `estimate` showed one computed from the visitor's choices; `fixed` showed
+     * a fixed price. Absent: a landing from before the flows, the same as `quote`.
+     */
+    flow?: string;
+    /**
+     * The price shown, in integer cents, EUR TTC (no currency field yet), at least 0, as the
+     * landing's server computed it. With `pricing_valid_from`: both are required when `flow` is
+     * estimate or fixed, and refused with quote or no flow.
+     */
+    quoted_cents?: number;
+    /**
+     * The day the pricing model that gave `quoted_cents` took effect, RFC 3339 full-date
+     * ("2026-10-01").
+     */
+    pricing_valid_from?: string;
+    /**
+     * What the visitor picked for an estimate: input id → value id, the pricing model's slugs
+     * (1–40 of [a-z0-9_-] each), at most 12 pairs, never free text. Only with flow estimate.
+     */
+    estimate_inputs?: {
+        [key: string]: string;
+    };
+    /**
+     * The `distinct_id` of the landing's analytics beacon when the form was sent (a random id it
+     * holds in memory, `crypto.randomUUID()`): 1–128 of [A-Za-z0-9._:-]. Not PII. The panel
+     * sends the lead's later life to PostHog under it, so a visit and its lead are one person
+     * there. Absent: the panel uses `sa-lead:<brand>:<lead>`.
+     */
+    analytics_id?: string;
+    /**
+     * The reference the customer carries into a messenger (MESSENGER-CHANNELS-SPEC §1): the
+     * brand's 2–4 capital letters, a dash, 4–8 of Crockford base32 without I, L, O, U
+     * (`^[A-Z]{2,4}-[0-9A-HJKMNP-TV-Z]{4,8}$`, e.g. "AQ-7K3F"). Made by the landing's form, so
+     * not unique: `lead.messaged` and the lookup by ref name the brand's newest lead carrying
+     * it. Not PII.
+     */
+    message_ref?: string;
+};
+/**
+ * lead.lost@1 — subject.lead_id required.
+ */
+export type LeadLostV1 = {
+    /**
+     * Lowercase slug: no_answer, too_expensive, out_of_area, …
+     */
+    reason: string;
+    note?: string;
+};
+/**
+ * lead.messaged@1 — the customer actually wrote the brand on a messenger. Written by a bot or
+ * the panel. subject.lead_id names the lead; or, absent, `message_ref` does, and the panel
+ * journals the event under the brand's newest lead carrying that ref (the lead id it found is
+ * what the journal keeps, so a rebuild does not look again). A ref no lead of the brand carries
+ * is `deferred` (the batch answered 409 with Retry-After, the event not journaled), the reason
+ * starting with `unknown_ref`: the landing's lead.created may not have arrived yet; send the
+ * same event again. Resolved by ref, the event takes the lead's location when it named none.
+ * A subject.lead_id the panel has no lead for is deferred the same way (`unknown_lead`). The
+ * customer's handle (a Telegram @username, a WhatsApp number or name) is PII: `pii.handle` /
+ * `pii.phone`, never here.
+ */
+export type LeadMessagedV1 = {
+    /**
+     * whatsapp | telegram
+     */
+    channel: string;
+    /**
+     * As in LeadCreatedV1. Required when subject.lead_id is absent.
+     */
+    message_ref?: string;
+};
+/**
+ * lead.quoted@1 — subject.lead_id required.
+ */
+export type LeadQuotedV1 = {
+    /**
+     * In minor units of `currency`; both or neither.
+     */
+    amount?: number;
+    /**
+     * ISO 4217, e.g. "EUR".
+     */
+    currency?: string;
+};
+/**
+ * payment.received@1 — subject.lead_id required.
+ */
+export type PaymentReceivedV1 = {
+    /**
+     * What the customer paid, in minor units of `currency`; at least 0.
+     */
+    billed: number;
+    /**
+     * Our share of it, in the same units; 0 to `billed`.
+     */
+    commission: number;
+    /**
+     * ISO 4217, e.g. "EUR".
+     */
+    currency: string;
+};
+/** Every `type@version` the panel projects, and its properties. */
+export type Registered = {
+    "lead.created@1": LeadCreatedV1;
+    "lead.messaged@1": LeadMessagedV1;
+    "lead.contacted@1": LeadContactedV1;
+    "lead.quoted@1": LeadQuotedV1;
+    "job.won@1": JobWonV1;
+    "lead.lost@1": LeadLostV1;
+    "job.completed@1": JobCompletedV1;
+    "payment.received@1": PaymentReceivedV1;
+    "call.attempted@1": CallAttemptedV1;
+    "call.logged@1": CallLoggedV1;
+    "site.metrics@1": SiteMetricsV1;
+    "contact.metrics@1": ContactMetricsV1;
+    "experiment.metrics@1": ExperimentMetricsV1;
+    "booking.requested@1": BookingRequestedV1;
+    "booking.created@1": BookingCreatedV1;
+    "booking.canceled@1": BookingCanceledV1;
+    "booking.set@1": BookingSetV1;
+    "booking.status_changed@1": BookingStatusChangedV1;
+    "booking.cleared@1": BookingClearedV1;
+    "booking.attached@1": BookingAttachedV1;
+    "experiments.declared@1": ExperimentsDeclaredV1;
+    "experiment.configured@1": ExperimentConfiguredV1;
+};
+/**
+ * site.metrics@1 — page views of a location (`location_page_view`) from one traffic source.
+ * subject.location_id: the location; absent for pages that name none.
+ */
+export type SiteMetricsV1 = {
+    /**
+     * The UTC day, "2026-09-30".
+     */
+    day: string;
+    /**
+     * Lowercase, 1–64 of [a-z0-9._:-]: utm_source, the referrer's host, direct, internal,
+     * unknown, or "other" for whatever does not fit and for the tail past the 20 largest.
+     */
+    source: string;
+    visits: number;
+    /**
+     * 1, 2, …
+     */
+    revision: number;
+};
+export type Source = {
+    /**
+     * site | review_archive | gbp | posthog | panel | sheet | telephony | booking | bot. Must be
+     * the kind the signing key is registered for. `booking` is the panel's own booking adapters
+     * (a provider's webhook or its periodic pull): no key is ever issued for it. `bot` is a
+     * messenger bot or auto-responder (docs/BOT-API.md).
+     */
+    kind: string;
+    /**
+     * Which one. For a signed batch, the key id it is signed with ("aquafix-site"); anything
+     * else is rejected.
+     */
+    id: string;
+};
+/**
+ * What the event is about. Ids are opaque to the panel: 1–128 of [A-Za-z0-9._:-].
+ */
+export type Subject = {
+    /**
+     * Lowercase slug, e.g. "aquafix". Must be one of the brands the signing key may write.
+     */
+    brandId: string;
+    locationId?: string;
+    /**
+     * Unique within the brand.
+     */
+    leadId?: string;
+    jobId?: string;
+};
+export declare const SITE_EVENTS: readonly ["lead.created@1", "booking.requested@1", "experiments.declared@1"];
+export type SiteEventKey = (typeof SITE_EVENTS)[number];

package/dist/generated/wire.js

@@ -0,0 +1,3 @@
+// AUTO-GENERATED by `nix run .#gen` — do not edit.
+export const SCHEMA = "sa.funnel.v1";
+export const SITE_EVENTS = ["lead.created@1", "booking.requested@1", "experiments.declared@1"];

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./generated/booking.js";
+export * from "./generated/codes.js";
+export * from "./generated/experiments.js";
+export * from "./generated/lead.js";
+export * from "./generated/place.js";
+export * from "./generated/pricing.js";
+export type * from "./generated/types.js";
+export * from "./generated/wire.js";
+export { checkBookingConfig, checkBookingUrl, bookingRequested, isBookingProvider, isLeadRef, isPageProvider, preferredDateInWindow, type BookingProblem, type BookingRequested } from "./booking.js";
+export { declarationProblem, parseLiveExperiments, type DeclarationProblem } from "./experiments.js";
+export { ingestBody, isOpaqueId, siteEvent, uuidV7, type LeadCreated, type SiteEvent, type SiteEventHead, type SiteProperties } from "./ingest.js";
+export { normalizePhone, phoneProblem } from "./phone.js";
+export { checkPlaceLive, isInstant, type PlaceProblem } from "./place.js";
+export { checkPricingModel, mulBp, priceOf, roundTo, type Price, type PriceLine, type PricingInputs, type PricingLabels, type PricingProblem } from "./pricing.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from "./generated/booking.js";
+export * from "./generated/codes.js";
+export * from "./generated/experiments.js";
+export * from "./generated/lead.js";
+export * from "./generated/place.js";
+export * from "./generated/pricing.js";
+export * from "./generated/wire.js";
+export { checkBookingConfig, checkBookingUrl, bookingRequested, isBookingProvider, isLeadRef, isPageProvider, preferredDateInWindow } from "./booking.js";
+export { declarationProblem, parseLiveExperiments } from "./experiments.js";
+export { ingestBody, isOpaqueId, siteEvent, uuidV7 } from "./ingest.js";
+export { normalizePhone, phoneProblem } from "./phone.js";
+export { checkPlaceLive, isInstant } from "./place.js";
+export { checkPricingModel, mulBp, priceOf, roundTo } from "./pricing.js";

package/dist/ingest.d.ts

@@ -0,0 +1,51 @@
+import type { BookingRequested } from "./booking.js";
+import type { LeadFlow, LeadSuspect, SiteChannel } from "./generated/lead.js";
+import { type Event, type ExperimentsDeclaredV1, type IngestRequest, type LeadCreatedV1, type Registered, type SiteEventKey, type Subject } from "./generated/wire.js";
+/** `lead.created@1`'s properties, their vocabularies as the panel checks them. */
+export type LeadCreated = LeadCreatedV1 & {
+    channel: SiteChannel;
+    suspect?: LeadSuspect;
+    flow?: LeadFlow;
+};
+/** The properties a site sends for each event it may write, the vocabularies narrowed. */
+export type SiteProperties = {
+    "lead.created@1": LeadCreated;
+    "booking.requested@1": BookingRequested;
+    "experiments.declared@1": ExperimentsDeclaredV1;
+} & {
+    [K in SiteEventKey]: Registered[K];
+};
+type TypeOf<K extends string> = K extends `${infer T}@${string}` ? T : never;
+type VersionOf<K extends string> = K extends `${string}@${infer V extends number}` ? V : never;
+/** An event a site sends: `Event` with its type, version and properties known. */
+export type SiteEvent<K extends SiteEventKey> = Omit<Event, "type" | "typeVersion" | "properties"> & {
+    type: TypeOf<K>;
+    typeVersion: VersionOf<K>;
+    properties: SiteProperties[K];
+};
+/** What every event a site sends carries besides its properties. */
+export interface SiteEventHead {
+    /** A UUIDv7 (`uuidV7`): the panel refuses another version, and keys the journal by it. */
+    id: string;
+    occurredAt: Date;
+    /** The key id the batch is signed with: the panel refuses any other `source.id`. */
+    sourceId: string;
+    subject: Subject;
+}
+/**
+ * One event as a site sends it (`contracts/vectors/ingest`), and the only way a site builds
+ * one: `pii` is what a person typed, kept apart — the panel seals it — and left out when
+ * empty.
+ */
+export declare function siteEvent<K extends SiteEventKey>(key: K, head: SiteEventHead, properties: SiteProperties[K], pii?: Readonly<Record<string, string>>): SiteEvent<K>;
+/** `POST /api/ingest/v1/events`' body. */
+export declare const ingestBody: (...events: SiteEvent<SiteEventKey>[]) => IngestRequest;
+/** An RFC 9562 UUIDv7 for `atMs`, its other 74 bits random. */
+export declare function uuidV7(atMs: number): string;
+/**
+ * An id the panel takes for a location, a lead or a job: 1–128 of `[A-Za-z0-9._:-]`, starting
+ * alphanumeric — and not made only of digits, dots and dashes with seven digits or more, which
+ * is what a phone number looks like: an id sits in the clear.
+ */
+export declare function isOpaqueId(s: string): boolean;
+export {};

package/dist/ingest.js

@@ -0,0 +1,45 @@
+import { SCHEMA } from "./generated/wire.js";
+/**
+ * One event as a site sends it (`contracts/vectors/ingest`), and the only way a site builds
+ * one: `pii` is what a person typed, kept apart — the panel seals it — and left out when
+ * empty.
+ */
+export function siteEvent(key, head, properties, pii = {}) {
+    const [type, version] = key.split("@");
+    return {
+        id: head.id,
+        schema: SCHEMA,
+        type,
+        typeVersion: Number(version),
+        occurredAt: head.occurredAt.toISOString(),
+        source: { kind: "site", id: head.sourceId },
+        subject: head.subject,
+        properties,
+        ...(Object.keys(pii).length > 0 ? { pii } : {}),
+    };
+}
+/** `POST /api/ingest/v1/events`' body. */
+export const ingestBody = (...events) => ({ events });
+/** An RFC 9562 UUIDv7 for `atMs`, its other 74 bits random. */
+export function uuidV7(atMs) {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    let ms = atMs;
+    for (let i = 5; i >= 0; i--) {
+        bytes[i] = ms % 256;
+        ms = Math.floor(ms / 256);
+    }
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x70;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * An id the panel takes for a location, a lead or a job: 1–128 of `[A-Za-z0-9._:-]`, starting
+ * alphanumeric — and not made only of digits, dots and dashes with seven digits or more, which
+ * is what a phone number looks like: an id sits in the clear.
+ */
+export function isOpaqueId(s) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(s))
+        return false;
+    return !(/^[0-9.-]+$/.test(s) && (s.match(/[0-9]/g)?.length ?? 0) >= 7);
+}

package/dist/phone.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 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`) — and, for the plans a visitor here most often dials
+ * from (`NATIONAL_LENGTH`), as long as that plan's numbers are, so `+12345678`
+ * is not a number. 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 declare function normalizePhone(raw: string): string | 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 declare function phoneProblem(raw: string): "required" | "invalid" | null;