Vérifier un numéro de téléphone et son indicatif

"""
Contrôler un numéro de téléphone contre le plan de numérotation de son pays.

Niveau N0. Chaque pays publie les préfixes qui existent, la longueur d'un
numéro derrière chacun d'eux, et la nature de la ligne qu'il atteint. Google
rassemble ces plans dans libphonenumber et les republie à mesure qu'ils
changent — `phonenumbers` ici, `libphonenumber-js` en JavaScript. Dans les deux cas
c'est une consultation de table : pas de réseau, pas de clé, et la même
réponse deux fois.

La seule chose que ce code refuse de faire, c'est deviner. Un numéro écrit
06 12 34 56 78 n'est français que si quelqu'un le dit ; les mêmes chiffres
sont un numéro mobile valide dans plusieurs autres pays. La région est donc
soit écrite dans le numéro, sous la forme du + initial, soit déclarée par
l'appelant, soit le numéro est refusé — jamais supposée d'après l'endroit où
tourne le serveur.

Ce qui revient, c'est le numéro en E.164, la région à laquelle il appartient,
et la nature de la ligne. C'est la nature qui dit à un formulaire qu'un SMS
n'arrivera jamais : en France, un numéro qui commence par 01 est une ligne
fixe, et il est valide.
"""

from __future__ import annotations

import unicodedata

import phonenumbers
from phonenumbers import PhoneNumberFormat, PhoneNumberType

# The enumeration of libphonenumber, by name, so that both languages of this
# page return the same word for the same line.
TYPE_NAMES = {
    value: name
    for name, value in vars(PhoneNumberType).items()
    if isinstance(value, int) and not name.startswith("_")
}

# E.164 caps a number at fifteen digits. Forty characters leaves room for the
# spaces, dots and brackets people type, and refuses a pasted paragraph.
MAX_CHARACTERS = 40

# Everything a phone number may carry besides digits. Digits are any Unicode
# decimal digit, category Nd, which is what the JavaScript side matches too:
# a number typed in Arabic-Indic digits is a number.
PUNCTUATION = "+ .-()/"

# The space characters a word processor and a French keyboard put inside a
# number. libphonenumber has its own list of punctuation it steps over, and the
# narrow no-break space is not in it: a number grouped with those stops being
# read at the first one. They are levelled to an ordinary space, and nothing
# else is touched.
SPACES = "\t\n\r\u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u202f\u205f\u3000"


def validate_phone_number(raw, *, default_region: str | None = None) -> dict:
    """
    Say whether `raw` is a number that exists in a numbering plan.

    `default_region` is the two-letter country the caller is expecting, and it
    is required unless the number starts with +. There is no fallback: a
    silently assumed region turns a Belgian mobile into a French one, and the
    caller would never see it happen.

    Nothing raises. A number that cannot be read comes back as `valid: False`
    with a `reason`, because a validator that throws in a request path leaves
    the form with nothing to show.
    """
    if not isinstance(raw, str):
        return _report(False, None, None, None, f"a phone number is text, not {type(raw).__name__}")
    if len(raw) > MAX_CHARACTERS:
        return _report(False, None, None, None, f"longer than {MAX_CHARACTERS} characters")

    written = "".join(" " if c in SPACES else c for c in raw).strip(" ")
    # Letters are refused rather than passed on. libphonenumber reads them as
    # the keys of a telephone keypad, so « 06 12 34 56 78 poste 42 » becomes a
    # longer number that is not the one anybody typed.
    if any(c not in PUNCTUATION and unicodedata.category(c) != "Nd" for c in written):
        return _report(False, None, None, None, "contains something that is not a number")
    if not written.startswith("+") and not default_region:
        return _report(False, None, None, None,
                       "no country code in the number and no region declared by the caller")

    try:
        parsed = phonenumbers.parse(written, default_region)
    except phonenumbers.NumberParseException:
        # The two libraries do not word their parse errors the same way, and
        # the caller acts on the refusal, not on its wording.
        return _report(False, None, None, None, "cannot be read as a phone number")

    region = phonenumbers.region_code_for_number(parsed)
    kind = TYPE_NAMES.get(phonenumbers.number_type(parsed))
    kind = None if kind == "UNKNOWN" else kind
    e164 = phonenumbers.format_number(parsed, PhoneNumberFormat.E164)

    if not phonenumbers.is_valid_number(parsed):
        # `is_possible_number` only checks the length, so it separates a number
        # that is too short from one whose prefix is not allocated.
        detail = ("no prefix of that country's plan matches"
                  if phonenumbers.is_possible_number(parsed) else "the wrong length for its country")
        return _report(False, region, kind, e164, f"not in a numbering plan: {detail}")
    return _report(True, region, kind, e164, None)


def _report(valid: bool, region: str | None, kind: str | None,
            e164: str | None, reason: str | None) -> dict:
    return {"valid": valid, "region": region, "type": kind, "e164": e164, "reason": reason}

/**
 * Contrôler un numéro de téléphone contre le plan de numérotation de son pays.
 *
 * Niveau N0. Chaque pays publie les préfixes qui existent, la longueur d'un
 * numéro derrière chacun d'eux, et la nature de la ligne qu'il atteint. Google
 * rassemble ces plans dans libphonenumber et les republie à mesure qu'ils
 * changent — `libphonenumber-js` ici, `phonenumbers` en Python. Dans les deux cas
 * c'est une consultation de table : pas de réseau, pas de clé, et la même
 * réponse deux fois.
 *
 * La seule chose que ce code refuse de faire, c'est deviner. Un numéro écrit
 * 06 12 34 56 78 n'est français que si quelqu'un le dit ; les mêmes chiffres
 * sont un numéro mobile valide dans plusieurs autres pays. La région est donc
 * soit écrite dans le numéro, sous la forme du + initial, soit déclarée par
 * l'appelant, soit le numéro est refusé — jamais supposée d'après l'endroit où
 * tourne le serveur.
 *
 * Ce qui revient, c'est le numéro en E.164, la région à laquelle il appartient,
 * et la nature de la ligne. C'est la nature qui dit à un formulaire qu'un SMS
 * n'arrivera jamais : en France, un numéro qui commence par 01 est une ligne
 * fixe, et il est valide.
 */

// The `max` bundle, and not the default one: it is the metadata that carries
// the line types and the full per-country rules, which is what Python's
// `phonenumbers` ships by default.
import { parsePhoneNumberWithError } from 'libphonenumber-js/max';

// E.164 caps a number at fifteen digits. Forty characters leaves room for the
// spaces, dots and brackets people type, and refuses a pasted paragraph.
export const MAX_CHARACTERS = 40;

// Everything a phone number may carry besides digits. Digits are any Unicode
// decimal digit, category Nd, which is what the Python side matches too: a
// number typed in Arabic-Indic digits is a number.
export const PUNCTUATION = '+ .-()/';

// The space characters a word processor and a French keyboard put inside a
// number. libphonenumber has its own list of punctuation it steps over, and
// the narrow no-break space is not in it: a number grouped with those stops
// being read at the first one. They are levelled to an ordinary space, and
// nothing else is touched.
export const SPACES =
  '\t\n\r\u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u202f\u205f\u3000';

/**
 * Say whether `raw` is a number that exists in a numbering plan.
 *
 * `defaultRegion` is the two-letter country the caller is expecting, and it is
 * required unless the number starts with +. There is no fallback: a silently
 * assumed region turns a Belgian mobile into a French one, and the caller
 * would never see it happen.
 *
 * Nothing throws. A number that cannot be read comes back as `valid: false`
 * with a `reason`, because a validator that throws in a request path leaves
 * the form with nothing to show.
 *
 * @param {string} raw
 * @param {{defaultRegion?: string}} [options]
 */
export function validatePhoneNumber(raw, { defaultRegion } = {}) {
  if (typeof raw !== 'string') {
    return report(false, null, null, null, `a phone number is text, not ${kindOf(raw)}`);
  }
  if (raw.length > MAX_CHARACTERS) {
    return report(false, null, null, null, `longer than ${MAX_CHARACTERS} characters`);
  }

  const written = [...raw].map((c) => (SPACES.includes(c) ? ' ' : c)).join('').replace(/^ +| +$/g, '');
  // Letters are refused rather than passed on. libphonenumber reads them as
  // the keys of a telephone keypad, so “06 12 34 56 78 poste 42” becomes a
  // longer number that is not the one anybody typed.
  if ([...written].some((c) => !PUNCTUATION.includes(c) && !/\p{Nd}/u.test(c))) {
    return report(false, null, null, null, 'contains something that is not a number');
  }
  if (!written.startsWith('+') && !defaultRegion) {
    return report(false, null, null, null,
      'no country code in the number and no region declared by the caller');
  }

  let parsed;
  try {
    parsed = parsePhoneNumberWithError(written, defaultRegion);
  } catch {
    // The two libraries do not word their parse errors the same way, and the
    // caller acts on the refusal, not on its wording.
    return report(false, null, null, null, 'cannot be read as a phone number');
  }

  const region = parsed.country ?? null;
  const kind = parsed.getType() ?? null;
  const e164 = parsed.number;

  if (!parsed.isValid()) {
    // `isPossible` only checks the length, so it separates a number that is
    // too short from one whose prefix is not allocated.
    const detail = parsed.isPossible()
      ? "no prefix of that country's plan matches"
      : 'the wrong length for its country';
    return report(false, region, kind, e164, `not in a numbering plan: ${detail}`);
  }
  return report(true, region, kind, e164, null);
}

const kindOf = (value) => (value === null ? 'null' : typeof value);

const report = (valid, region, type, e164, reason) => ({ valid, region, type, e164, reason });