# Localize.PhoneNumber

Elixir interface to Google's [libphonenumber](https://github.com/google/libphonenumber) C++ library via NIF. Provides phone number parsing, formatting, validation, type detection, and territory resolution with locale-aware defaults powered by [Localize](https://hexdocs.pm/localize).

## Usage

Parse a phone number in international format:

```elixir
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> phone_number.country_code
1
iex> phone_number.national_number
6502530000
```

Parse a national number by supplying a territory or locale:

```elixir
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("020 7946 0958", territory: "GB")
iex> phone_number.country_code
44

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("020 7946 0958", locale: "en-GB")
iex> phone_number.country_code
44
```

When neither `:territory` nor `:locale` is given, the default territory is derived from `Localize.get_locale/0`.

Format a parsed number:

```elixir
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.to_string(phone_number, :e164)
{:ok, "+16502530000"}

iex> Localize.PhoneNumber.to_string(phone_number, :international)
{:ok, "+1 650-253-0000"}

iex> Localize.PhoneNumber.to_string(phone_number, :national)
{:ok, "(650) 253-0000"}

iex> Localize.PhoneNumber.to_string(phone_number, :rfc3966)
{:ok, "tel:+1-650-253-0000"}
```

Validate a number:

```elixir
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.valid?(phone_number)
true

iex> Localize.PhoneNumber.valid_for_territory?(phone_number, "US")
true

iex> Localize.PhoneNumber.possible?(phone_number)
true
```

Detect the number type and territory:

```elixir
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 800-555-0199")
iex> Localize.PhoneNumber.type(phone_number)
:toll_free

iex> Localize.PhoneNumber.territory(phone_number)
"US"
```

See the [Parsing and Formatting Guide](https://hexdocs.pm/localize_phone_number/parsing_and_formatting.html) for detailed usage examples.

## API Summary

| Function | Description |
|----------|-------------|
| `parse/2` | Parse a phone number string into a struct. |
| `to_string/2` | Format a parsed number (`:e164`, `:international`, `:national`, `:rfc3966`). Default is `:international`. |
| `valid?/1` | Check if a parsed number is valid. |
| `valid_for_territory?/2` | Check if a parsed number is valid for a specific territory. |
| `possible?/1` | Quick check if a number has a plausible length. |
| `type/1` | Detect the number type (`:mobile`, `:fixed_line`, `:toll_free`, etc.). |
| `territory/1` | Get the ISO 3166-1 alpha-2 territory code for a number. |

## Territory Resolution

The `parse/2` function needs a default territory to interpret national-format numbers. The territory is resolved in priority order:

1. Explicit `:territory` option — validated via `Localize.validate_territory/1`.
2. Extracted from the `:locale` option — resolved via `Localize.Territory.territory_from_locale/1`. Accepts a string (`"en-GB"`), atom (`:en_GB`), or `Localize.LanguageTag.t()` struct.
3. Derived from the current process locale via `Localize.get_locale/0`.

## Prerequisites

### System Libraries

Google's libphonenumber C++ library must be installed on the build machine. The NIF is compiled automatically by `elixir_make` during `mix compile`.

**macOS (Homebrew):**

```bash
brew install libphonenumber
```

This installs libphonenumber along with its transitive dependencies (protobuf, abseil, boost, and ICU). The Makefile detects the Homebrew prefix automatically on both Apple Silicon (`/opt/homebrew`) and Intel (`/usr/local`) Macs.

**Linux (Debian/Ubuntu):**

```bash
sudo apt-get install libphonenumber-dev libprotobuf-dev protobuf-compiler
```

On distributions that provide a `pkg-config` file for libphonenumber, the Makefile uses it automatically. Otherwise it falls back to standard system library paths.

**Linux (Fedora/RHEL):**

```bash
sudo dnf install libphonenumber-devel protobuf-devel
```

**From source:**

If your distribution does not package libphonenumber, build it from [source](https://github.com/google/libphonenumber/blob/master/cpp/README). Ensure the headers are installed to a standard include path and the shared library is on the linker search path.

### Elixir Dependencies

Add `localize_phone_number` to your `mix.exs`:

```elixir
def deps do
  [
    {:localize_phone_number, "~> 0.1.0"}
  ]
end
```

The library depends on:

* [`localize`](https://hexdocs.pm/localize) — locale and territory resolution.
* [`elixir_make`](https://hex.pm/packages/elixir_make) — compiles the C++ NIF during `mix compile`.

## Architecture

### NIF Design

The library is a thin Elixir wrapper around a C++ NIF that calls libphonenumber's `PhoneNumberUtil` singleton directly. The NIF is compiled automatically by `elixir_make` during `mix compile`.

```
Localize.PhoneNumber              Public API (parse, to_string, valid?, type, territory)
    │
    ├── Localize.PhoneNumber.Territory   Locale-to-territory resolution via Localize
    │
    └── Localize.PhoneNumber.Nif         NIF loader and Elixir stubs
         │
         └── localize_phone_number_nif.cpp
              │
              └── libphonenumber (PhoneNumberUtil)
```

### Parsed Phone Number Struct

`Localize.PhoneNumber.parse/2` returns a `Localize.PhoneNumber.Number` struct:

```elixir
%Localize.PhoneNumber.Number{
  country_code: 1,
  national_number: 6502530000,
  extension: nil,
  raw_input: "+1 650-253-0000"
}
```

The struct also carries an opaque `__native__` field containing the serialized protobuf representation of the phone number. This binary is passed back to the NIF for all subsequent operations (`to_string/2`, `valid?/1`, `type/1`, etc.), ensuring lossless round-trips that preserve metadata such as Italian leading zeros and preferred formatting hints. The `__native__` field is excluded from `Inspect` output.

### Thread Safety

`PhoneNumberUtil::GetInstance()` returns a process-global singleton that is thread-safe for all read operations. No pooling or mutexes are needed — every NIF call can run concurrently on any BEAM scheduler.

### Build System

The `c_src/Makefile` follows the same pattern used by the `localize` project:

* Generates `env.mk` at build time to discover ERTS include paths.
* Detects the platform (macOS ARM/x86, Linux, FreeBSD) and sets appropriate compiler flags.
* Finds libphonenumber, protobuf, and abseil via `pkg-config` with Homebrew fallback paths on macOS.
* Compiles C++17 with `-O3 -fPIC` and produces a shared library at `priv/localize_phone_number_nif.so`.

## License

[Apache-2.0](https://github.com/elixir-localize/localize_phone_number/blob/v0.1.0/LICENSE.md)