Phone number validation in Java and Kotlin with libphonenumber

<dependency>
  <groupId>com.googlecode.libphonenumber</groupId>
  <artifactId>libphonenumber</artifactId>
  <version>9.0.40</version>
</dependency>

// Phones.java
package com.example.phone;

import com.google.i18n.phonenumbers.NumberParseException;
import com.google.i18n.phonenumbers.PhoneNumberUtil;
import com.google.i18n.phonenumbers.PhoneNumberUtil.PhoneNumberFormat;
import com.google.i18n.phonenumbers.PhoneNumberUtil.ValidationResult;
import com.google.i18n.phonenumbers.Phonenumber.PhoneNumber;
import java.util.regex.Pattern;

public final class Phones {
  private static final PhoneNumberUtil UTIL = PhoneNumberUtil.getInstance(); // thread-safe, load once
  // Our reserved test range (+44 7700 9xxxxx). libphonenumber marks it invalid on purpose.
  private static final Pattern TEST_RANGE = Pattern.compile("^\\+4477009\\d{5}$");

  public record Result(boolean ok, String e164, String region, String type, String reason) {
    static Result fail(String reason) { return new Result(false, null, null, null, reason); }
  }

  private Phones() {}

  /** defaultRegion like "GB"; null requires a leading +. */
  public static Result normalize(String raw, String defaultRegion, boolean allowTestRange) {
    String in = raw == null ? "" : raw.strip();
    if (in.isEmpty() || in.length() > 32) return Result.fail("unparseable");
    PhoneNumber number;
    try {
      number = UTIL.parse(in, defaultRegion);
    } catch (NumberParseException e) {
      return Result.fail("unparseable");
    }
    String e164 = UTIL.format(number, PhoneNumberFormat.E164);
    if (allowTestRange && TEST_RANGE.matcher(e164).matches()) return new Result(true, e164, "GB", "TEST", null);
    if (!UTIL.isValidNumber(number)) {
      ValidationResult why = UTIL.isPossibleNumberWithReason(number);
      return Result.fail(switch (why) {
        case TOO_SHORT -> "too_short";
        case TOO_LONG -> "too_long";
        default -> "invalid";
      });
    }
    return new Result(true, e164, UTIL.getRegionCodeForNumber(number), UTIL.getNumberType(number).name(), null);
  }
}

// ValidPhone.java
package com.example.phone;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.RECORD_COMPONENT})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = ValidPhoneValidator.class)
public @interface ValidPhone {
  String message() default "is not a valid phone number";
  String defaultRegion() default "";
  Class<?>[] groups() default {};
  Class<? extends Payload>[] payload() default {};
}

// ValidPhoneValidator.java
package com.example.phone;

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

public class ValidPhoneValidator implements ConstraintValidator<ValidPhone, String> {
  private String region;

  @Override
  public void initialize(ValidPhone annotation) {
    region = annotation.defaultRegion().isEmpty() ? null : annotation.defaultRegion();
  }

  @Override
  public boolean isValid(String value, ConstraintValidatorContext context) {
    if (value == null) return true; // combine with @NotBlank when the field is required
    return Phones.normalize(value, region, false).ok();
  }
}

import com.google.i18n.phonenumbers.NumberParseException
import com.google.i18n.phonenumbers.PhoneNumberUtil
import com.google.i18n.phonenumbers.PhoneNumberUtil.PhoneNumberFormat

private val util: PhoneNumberUtil = PhoneNumberUtil.getInstance()

/** Returns the E.164 form, or null when the input is not a valid number. */
fun toE164(raw: String, defaultRegion: String? = null): String? {
    val number = try {
        util.parse(raw.trim(), defaultRegion)
    } catch (e: NumberParseException) {
        return null
    }
    return if (util.isValidNumber(number)) util.format(number, PhoneNumberFormat.E164) else null
}

fun main() {
    println(toE164("07911 123456", "GB"))   // +447911123456
    println(toE164("+1 123 456 7890"))       // null
}

// MobileValidateClient.java
package com.example.phone;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.List;
import java.util.Map;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.json.JsonMapper;

public final class MobileValidateClient {
  private static final JsonMapper JSON = JsonMapper.builder().build();
  private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
  private final String baseUrl;
  private final String apiKey;

  public MobileValidateClient(String apiKey, String baseUrl) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl == null ? "https://api.mobilevalidate.com" : baseUrl;
  }

  public static final class ApiException extends RuntimeException {
    public final String code;
    public final int status;
    ApiException(String code, int status, String message) {
      super(code + " (" + status + "): " + message);
      this.code = code;
      this.status = status;
    }
  }

  /** Checks up to 100 E.164 numbers. Numbers go in the POST body, never in the URL. */
  public JsonNode lookup(List<String> numbers, List<String> checks) throws IOException, InterruptedException {
    String body = JSON.writeValueAsString(Map.of("numbers", numbers, "checks", checks, "wait", 10));
    JsonNode res = send(HttpRequest.newBuilder(URI.create(baseUrl + "/v1/lookup"))
        .POST(HttpRequest.BodyPublishers.ofString(body)).header("Content-Type", "application/json"));
    while ("pending".equals(res.path("status").asString())) {
      Thread.sleep(res.path("next").path("poll_after_ms").asLong(2000));
      res = send(HttpRequest.newBuilder(URI.create(baseUrl + "/v1/lookups/" + res.path("id").asString() + "?wait=10")).GET());
    }
    return res.path("results");
  }

  private JsonNode send(HttpRequest.Builder builder) throws IOException, InterruptedException {
    HttpRequest request = builder.header("Authorization", "Bearer " + apiKey)
        .timeout(Duration.ofSeconds(45)) // the server may long-poll for up to `wait` seconds
        .build();
    for (int attempt = 0; ; attempt++) {
      HttpResponse<String> res = http.send(request, HttpResponse.BodyHandlers.ofString());
      JsonNode json = JSON.readTree(res.body());
      if (res.statusCode() < 300) return json;
      JsonNode err = json.path("error");
      if (!err.path("retryable").asBoolean(false) || attempt == 3) {
        throw new ApiException(err.path("code").asString("http_error"), res.statusCode(), err.path("message").asString(""));
      }
      long retryAfter = res.headers().firstValueAsLong("Retry-After").orElse(1L << attempt);
      Thread.sleep(Duration.ofSeconds(retryAfter));
    }
  }
}

+447700900001 completed mobile
+447700900003 unknown unknown UPSTREAM_TIMEOUT
+447700900004 completed mobile