phone

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 5 Imported by: 0

Documentation

Overview

Package phone reads phone numbers for the text channels (design expansion phase 8): E.164, the country the number belongs to, what kind of line it looks like, and the recipient's time zone when the contact has none.

The country always comes from the number, never from the contact's address. Parsing and the area-code time zones come from libphonenumber's metadata (nyaruka/phonenumbers).

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalid = errors.New("phone: not a phone number")
	// ErrNoCountry is a national number without a country to read it in.
	ErrNoCountry = errors.New("phone: the number needs its country code")
)

Errors.

Functions

func CallingCode

func CallingCode(country string) int

CallingCode is a country's calling code ("GB" → 44); 0 when unknown.

func Countries

func Countries() []string

Countries are the countries numbers can be from, as ISO codes.

func Display

func Display(e164 string) string

Display formats an E.164 number for people: +1 312 555 0123. Anything that doesn't parse is returned as it is.

func Mask

func Mask(e164 string) string

Mask hides the middle of a number: +1 773 ••• 0148. Numbers are shown this way in lists (suppressions, event logs, reports).

Types

type LineType

type LineType string

LineType is what a number is known to be. Carriers and providers know better than the number plan, so a provider's error ("landline or unreachable carrier") overrides it.

const (
	Mobile   LineType = "mobile"
	Landline LineType = "landline"
	TollFree LineType = "toll_free"
	VoIP     LineType = "voip"
	Unknown  LineType = "unknown"
)

Line types.

type Number

type Number struct {
	// E164 is the number as providers take it: +13125550123.
	E164 string `json:"e164"`
	// Country is its ISO 3166-1 alpha-2 code ("US").
	Country string `json:"country"`
	// CallingCode is the country calling code (1, 44).
	CallingCode int `json:"callingCode"`
	// Display is the international form with spaces: +1 312 555 0123.
	Display string `json:"display"`
	// Type is what the number plan says about the line.
	Type LineType `json:"type" enum:"mobile,landline,toll_free,voip,unknown"`
}

Number is a parsed phone number.

func MustParse

func MustParse(e164 string) Number

MustParse parses an E.164 number known to be valid (tests, the demo).

func Parse

func Parse(raw, defaultCountry string) (Number, error)

Parse reads a number as a person typed it ("+1 (312) 555-0123", "07700 900456" with country "GB"). defaultCountry is used for national numbers; it may be empty when the number starts with + or 00.

type ZoneSource

type ZoneSource string

ZoneSource says where a recipient's time zone came from.

const (
	ZoneContact  ZoneSource = "contact"   // the contact's time zone field
	ZoneAreaCode ZoneSource = "area_code" // the number's area code maps to one zone
	ZoneCountry  ZoneSource = "country"   // the country's main zone
	ZoneUnknown  ZoneSource = "unknown"
)

Zone sources. Both phone sources are "assumed": the pre-send check counts them.

func RecipientZone

func RecipientZone(contactZone, e164 string) (string, ZoneSource)

RecipientZone is the zone quiet hours use for a recipient: the contact's own time zone field when it has a valid one, otherwise the number's.

func TimeZone

func TimeZone(e164 string) (string, ZoneSource)

TimeZone is the zone the number points to: its area code's when that maps to one zone, else the country's main zone. It returns "" with ZoneUnknown when neither is known.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL