# phone

Build and validate phone numbers

Canonical URL: https://docs.paradoc.dev/sdk/primitives/phone/

Build and validate phone numbers. The Phone primitive captures phone numbers with optional type classification and extension.

## Examples

### Creating phone numbers

```ts
// Object pattern
const phone = p.phone({
  number: '+14155552671'
})

// Builder pattern
const phone = p.phone()
  .number('+14155552671')
  .type('mobile')
  .extension('123')
  .build()

// Copy and modify
const updated = p.phone()
  .from(phone)
  .type('work')
  .build()
```

### Parsing external data

```ts
// Parse unknown input (throws on error)
const phone = p.phone.parse(jsonData)

// Safe parsing (returns result object)
const result = p.phone.safeParse(jsonData)
if (result.success) {
  console.log(`Phone: ${result.data.number}`)
} else {
  console.error(result.error.message)
}
```

### Using with forms

```ts
const form = p.form({
  name: 'contact',
  fields: {
    mobilePhone: { type: 'phone', label: 'Mobile Phone' },
    workPhone: { type: 'phone', label: 'Work Phone' }
  }
})

const filled = form.fill({
  fields: {
    mobilePhone: p.phone()
      .number('+14155552671')
      .type('mobile')
      .build(),
    workPhone: p.phone()
      .number('+14155551234')
      .type('work')
      .extension('567')
      .build()
  }
})
```

## API

### Object Pattern

```ts
p.phone(input: Phone): Phone
```

Pass a Phone object for validation. Returns the validated Phone or throws on error.

```ts
const phone = p.phone({ number: '+442071234567' })
```

### Builder Pattern

Chain methods to build a Phone value incrementally:

Start with `p.phone()`. Each method returns `PhoneBuilder` and can be chained.

| Method | Description |
| --- | --- |
| `number(value: string)` | Set phone number (E.164 format required) |
| `type(value: string \| undefined)` | Set phone type (mobile, home, work, etc.) |
| `extension(value: string \| undefined)` | Set extension number |
| `from(value: Phone)` | Initialize from existing Phone |

Terminal methods return `Phone`.

| Method | Description |
| --- | --- |
| `build()` | Build and validate |

### Static Methods

| Method | Returns | Description |
| --- | --- | --- |
| `parse(input: unknown)` | `Phone` | Parse unknown input (throws on error) |
| `safeParse(input: unknown)` | `Result<Phone>` | Parse unknown input (returns result object) |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `number` | `string` | Phone number. E.164 format required (+[country][number]). |
| `type` | `string?` | Type of phone (mobile, home, work, fax). |
| `extension` | `string?` | Extension number for business lines. |

## E.164 Format

Phone numbers must use E.164:

```
+[country code][subscriber number]
```

| Country    | Format        | Example       |
| ---------- | ------------- | ------------- |
| USA/Canada | +1XXXXXXXXXX  | +14155552671  |
| UK         | +44XXXXXXXXXX | +442071234567 |
| Germany    | +49XXXXXXXXX  | +4930123456   |
| Japan      | +81XXXXXXXXX  | +81312345678  |
| Australia  | +61XXXXXXXXX  | +61212345678  |

## Phone Types

| Type     | Description          |
| -------- | -------------------- |
| `mobile` | Mobile/cell phone    |
| `home`   | Residential landline |
| `work`   | Business/office line |
| `fax`    | Fax machine          |
| `other`  | Other phone type     |

## Validation

The Phone primitive validates:

* `number` must be 8–16 characters, start with `+`, and otherwise contain digits
* `type` and `extension` are optional

```ts
// Valid
p.phone({ number: '+14155552671' })
p.phone({
  number: '+14155552671',
  type: 'mobile'
})
p.phone({
  number: '+14155551234',
  type: 'work',
  extension: '567'
})

// Invalid - throws Error
p.phone({})

p.phone({ number: '' })
```

## Related

* [Primitives Overview](/sdk/primitives) - All available primitives
* [Address](/sdk/primitives/address) - Physical address
* [Phone Field](/sdk/artifacts/form/field#entity) - Phone field type
* [Phone Schema](/schemas/primitives/phone) - JSON Schema definition