### Install tin-validator via npm

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Install the package using npm. This is the first step before using the library.

```sh
npm install tin-validator --save
```

--------------------------------

### Run tests with npm test

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Execute the test suite for the tin-validator package using npm.

```sh
npm test
```

--------------------------------

### Standardize TIN with standardize()

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Format TIN values to their official version, useful before masking or database persistence. Options can specify country and entity type.

```javascript
standardize('123A', { country: 'MT' });
// => 0000123A
```

```javascript
standardize('123456789');
// => 123456789
```

--------------------------------

### `mask(value, options?)` — Mask a TIN for display

Source: https://context7.com/uphold/tin-validator/llms.txt

Obfuscates sensitive TIN digits by replacing characters with 'X', leaving only the last four characters visible. Returns a `Promise<string>`. Throws an `Error` if the TIN is invalid (unless `skipValidations: true` is passed).

```APIDOC
## `mask(value, options?)` - Mask a TIN for display

### Description
Obfuscates sensitive TIN digits by replacing characters with 'X', leaving only the last four characters visible. Returns a `Promise<string>`. Throws an `Error` if the TIN is invalid (unless `skipValidations: true` is passed).

### Method
`async`

### Parameters
#### Path Parameters
- **value** (string) - Required - The TIN string to mask.
- **options** (object) - Optional - Configuration options.
  - **country** (string) - Optional - The country code (e.g., 'US', 'BE'). Defaults to 'US'.
  - **entityType** (string) - Optional - The entity type ('natural-person' or 'legal-entity'). Defaults to 'natural-person'.
  - **skipValidations** (boolean) - Optional - If true, skips validation before masking.
  - **skipExternalValidations** (boolean) - Optional - If true, skips external API calls for EU TIN masking.

### Response
#### Success Response (Promise<string>)
- The masked TIN string.

### Request Example
```javascript
const { mask } = require('tin-validator');

// US SSN masking
await mask('900-70-0000'); // => 'XXX-XX-0000'

// EU TIN masking
await mask('12345678901', { country: 'BE', entityType: 'natural-person' }); // => 'XXXXXXX8901'

// Skip validation
await mask('12345678901', { country: 'BE', entityType: 'natural-person', skipValidations: true }); // => 'XXXXXXX8901'

// Non-US, non-EU country
await mask('16-182749', { country: 'BO' }); // => '16-182749'
```
```

--------------------------------

### `isValid(value, options?)` — Validate a TIN

Source: https://context7.com/uphold/tin-validator/llms.txt

Checks whether a given string is a structurally valid TIN for the specified country and entity type. Returns a `Promise<boolean>`. Basic sanity checks are applied before country-specific logic. For EU countries, it consults the European Commission TIN API and falls back to internal regex validation.

```APIDOC
## `isValid(value, options?)` - Validate a TIN

### Description
Checks whether a given string is a structurally valid TIN for the specified country and entity type. Returns a `Promise<boolean>`.

### Method
`async`

### Parameters
#### Path Parameters
- **value** (string) - Required - The TIN string to validate.
- **options** (object) - Optional - Configuration options.
  - **country** (string) - Optional - The country code (e.g., 'US', 'PT', 'DE'). Defaults to 'US'.
  - **entityType** (string) - Optional - The entity type ('natural-person' or 'legal-entity'). Defaults to 'natural-person'.
  - **skipExternalValidations** (boolean) - Optional - If true, skips external API calls for EU TIN validation.

### Response
#### Success Response (Promise<boolean>)
- `true` if the TIN is valid.
- `false` if the TIN is invalid.

### Request Example
```javascript
const { isValid } = require('tin-validator');

// US TIN validation
await isValid('900-70-0000'); // => true
await isValid('123456789'); // => false

// EU TIN validation
await isValid('123456789', { country: 'PT', entityType: 'natural-person' }); // => true

// Skip external API call
await isValid('123456789', { country: 'PT', entityType: 'natural-person', skipExternalValidations: true }); // => true

// Non-US, non-EU country
await isValid('16-182749', { country: 'BO' }); // => true
```
```

--------------------------------

### standardize(value, options)

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Standardizes TIN values to their official format, removing formatting variations. This is recommended before masking or persisting TINs. Supports country and entity type options.

```APIDOC
## standardize(value, options)

### Description
This method will standardize TIN values. Validators may accept TIN values for specific countries with formatting variations (e.g. omitting prefixes of zeros). Users should invoke this method prior value masking and DB persistence, as it returns the official version of the TIN.

### Arguments
- `value` _(*)_: The value to standardize.
- `options` (object, optional):
  - `country` (string, optional): Country of document to standardize (by default, `US`).
  - `entityType` (string, optional): Regulation entity type (by default, `natural-person`).

### Returns
_(string)_: Returns the standardized value.

### Example
```js
standardize('123A', { country: 'MT' });
// => 0000123A

standardize('123456789');
// => 123456789
```
```

--------------------------------

### Mask TIN with mask()

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Obfuscate digits of a TIN value. Options can specify country, entity type, and whether to skip validations. This method throws an error for invalid inputs.

```javascript
mask({});
// Throws an Error.
```

```javascript
mask('9-0-0700000');
// Throws an Error.
```

```javascript
mask('900-70-0000');
// => XXX-XX-0000
```

```javascript
mask('900700000');
// => XXXXX0000
```

--------------------------------

### Validate TIN using isValid()

Source: https://context7.com/uphold/tin-validator/llms.txt

Checks if a TIN is structurally valid for a specified country and entity type. Basic sanity checks are performed first. For EU countries, it attempts to use the EC API, falling back to internal regex. Use `skipExternalValidations: true` to bypass the EC API.

```javascript
const { isValid } = require('tin-validator');

// US TIN validation (SSN, ITIN, EIN) — defaults to country: 'US'
await isValid('900-70-0000');      // => true  (valid SSN format)
await isValid('9-0-0700000');      // => false (invalid format)
await isValid('123456789');        // => false (sequential — rejected by basic check)
await isValid('111111111');        // => false (repeated digits)
await isValid({});                 // => false (non-string)

// EU TIN validation — country and entityType are required
await isValid('123456789', { country: 'PT', entityType: 'natural-person' });
// => true (valid Portuguese natural-person TIN; tries EC API first, falls back internally)

await isValid('12345678', { country: 'DE', entityType: 'legal-entity' });
// => false (German legal-entity TIN must be 11 digits)

// Skip the external EC API call entirely (useful for testing or offline environments)
await isValid('123456789', { country: 'PT', entityType: 'natural-person', skipExternalValidations: true });
// => true (validated using only internal regex)

// Non-US, non-EU country — always returns true after basic checks
await isValid('16-182749', { country: 'BO' });
// => true
```

--------------------------------

### mask(value, options)

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Masks a TIN value by obfuscating some digits with 'X'. It supports country and entity type options, and can skip validations if needed.

```APIDOC
## mask(value, options)

### Description
This method will help you protect this sensitive piece of information by obfuscating some digits.

### Arguments
- `value` _(*)_: The value to mask.
- `options` (object, optional):
  - `country` (string, optional): Country of document to mask (by default, `US`).
  - `entityType` (string, optional): Regulation entity type (by default, `natural-person`).
  - `skipExternalValidations` (boolean, optional): Only applicable for EU TIN. When set to `true`, it skips external API validation and uses only internal validation. This is useful for performance, offline scenarios, or testing. By default: `false`.
  - `skipValidations` (boolean, optional): Applicable for US and EU TIN. When set to `true`, it skips all kind of validations. This is useful when calling `mask()` after calling `isValid()`. By default: `false`.

### Returns
_(string)_: Returns the masked value by replacing value certain digits by 'X'.

### Example
```js
mask({});
// Throws an Error.

mask('9-0-0700000');
// Throws an Error.

mask('900-70-0000');
// => XXX-XX-0000

mask('900700000');
// => XXXXX0000
```
```

--------------------------------

### sanitize(value, options?)

Source: https://context7.com/uphold/tin-validator/llms.txt

Removes non-numeric characters from a TIN string, returning only the raw numeric (or alphanumeric for some EU formats) characters. This is useful for normalizing user input before storage or validation.

```APIDOC
## `sanitize(value, options?)` — Remove non-numeric characters from a TIN

Strips formatting characters (dashes, slashes, spaces, dots) from a TIN string, returning only the raw numeric (or alphanumeric for some EU formats) characters. Synchronous. Useful for normalizing user input before storage or validation.

### Parameters
#### Path Parameters
- **value** (string) - Required - The TIN string to sanitize.
- **options** (object) - Optional - An object containing country and entity type information.
  - **country** (string) - Optional - The ISO country code (e.g., 'FR', 'FI').
  - **entityType** (string) - Optional - The type of entity (e.g., 'natural-person').

### Request Example
```js
const { sanitize } = require('tin-validator');

// US TIN sanitization — removes all non-digit characters
sanitize('9-0 0700000');
// => '900700000'

sanitize('900a7#$0foobar0000');
// => '900700000'

// EU TIN sanitization — removes dashes, slashes, spaces, dots and uppercases
sanitize('66-0000/000.', { country: 'FR', entityType: 'natural-person' });
// => '660000000'

// Finland uses a custom sanitize pattern (removes only ./\ s, preserving +, -, letters)
sanitize('131052-308T', { country: 'FI', entityType: 'natural-person' });
// => '131052-308T'

// Non-US, non-EU — value returned unchanged
sanitize('16-182749', { country: 'BO' });
// => '16-182749'
```
```

--------------------------------

### Mask TIN using mask()

Source: https://context7.com/uphold/tin-validator/llms.txt

Obfuscates TIN digits, leaving only the last four visible. Throws an error for invalid TINs unless `skipValidations: true` is used. For EU TINs, it uppercases the value and masks all but the last four characters. Use `skipExternalValidations: true` to skip the EC API call during validation.

```javascript
const { mask } = require('tin-validator');

// US SSN: XXX-XX-0000
await mask('900-70-0000');
// => 'XXX-XX-0000'

// US SSN without dashes: XXXXX0000
await mask('900700000');
// => 'XXXXX0000'

// Invalid US TIN — throws
try {
  await mask('9-0-0700000');
} catch (err) {
  console.error(err.message); // => 'Invalid Taxpayer Identification Number'
}

// EU TIN — last 4 characters remain visible
await mask('12345678901', { country: 'BE', entityType: 'natural-person' });
// => 'XXXXXXX8901'

// Skip validation before masking (useful when isValid() was already called)
await mask('12345678901', { country: 'BE', entityType: 'natural-person', skipValidations: true });
// => 'XXXXXXX8901'

// Skip external EU API call when masking
await mask('12345678901', { country: 'BE', entityType: 'natural-person', skipExternalValidations: true });
// => 'XXXXXXX8901'

// Non-US, non-EU country — value returned as-is
await mask('16-182749', { country: 'BO' });
// => '16-182749'
```

--------------------------------

### Standardize TIN values

Source: https://context7.com/uphold/tin-validator/llms.txt

Normalizes a TIN to its canonical, officially recognized format. This is useful for EU countries where formatting variations are accepted but need normalization before persistence. For some countries like Malta, this involves zero-padding.

```javascript
const { standardize } = require('tin-validator');

// Malta: short numeric TINs are zero-padded to 7 digits before the letter suffix
standardize('123A', { country: 'MT', entityType: 'natural-person' });
// => '0000123A'

standardize('1234567A', { country: 'MT', entityType: 'natural-person' });
// => '1234567A'  (already the correct length)

// US TIN — standardize is a no-op for US (returns value as-is)
standardize('123456789');
// => '123456789'

// Non-EU country — value returned unchanged
standardize('16-182749', { country: 'BO' });
// => '16-182749'
```

```javascript
// Typical flow: sanitize first, then standardize before persisting
const { sanitize, standardize: std } = require('tin-validator');

const raw = '123/A';
const sanitized = sanitize(raw, { country: 'MT', entityType: 'natural-person' });
const canonical = std(sanitized, { country: 'MT', entityType: 'natural-person' });
// canonical => '0000123A'
```

--------------------------------

### Sanitize TIN with sanitize()

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Remove all non-numeric characters from a TIN value. Options can specify country and entity type.

```javascript
sanitize('9-0 0700000');
// => 900700000
```

```javascript
sanitize('900a7#$0foobar0000');
// => 900700000
```

--------------------------------

### sanitize(value, options)

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Removes all non-numeric characters from a TIN value, returning only the numeric digits. Supports country and entity type options.

```APIDOC
## sanitize(value, options)

### Description
This method will remove all non numeric characters from the value.

### Arguments
- `value` _(*)_: The value to sanitize.
- `options` (object, optional):
  - `country` (string, optional): Country of document to sanitize (by default, `US`).
  - `entityType` (string, optional): Regulation entity type (by default, `natural-person`).

### Returns
_(string)_: Returns the sanitized value containing only numeric characters.

### Example
```js
sanitize('9-0 0700000');
// => 900700000

sanitize('900a7#$0foobar0000');
// => 900700000
```
```

--------------------------------

### Validate TIN with isValid()

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Check if a given value is a valid Taxpayer Identification Number. Options can specify country and entity type. For EU TINs, external API validation can be skipped.

```javascript
isValid({});
// => false
```

```javascript
isValid('9-0-0700000');
// => false
```

```javascript
isValid('900-70-0000');
// => true
```

```javascript
isValid('900700000');
// => true
```

```javascript
isValid('123456789', { country: 'PT', entityType: 'natural-person' });
// => true
```

--------------------------------

### isValid(value, options)

Source: https://github.com/uphold/tin-validator/blob/master/README.md

Validates if the given value is a valid Taxpayer Identification Number (TIN). It supports country-specific and entity-type-specific validations, with options to skip external validations for EU TINs.

```APIDOC
## isValid(value, options)

### Description
This method validates if the given value is a valid `Taxpayer Identification Number`.

### Arguments
- `value` _(*)_: The string value to validate.
- `options` (object, optional):
  - `country` (string, optional): Country of document to validate (by default, `US`).
  - `entityType` (string, optional): Possible values: `natural-person` and `legal-entity`. By default: `natural-person`.
  - `skipExternalValidations` (boolean, optional): Only applicable for EU TIN. When set to `true`, it skips external API validation and uses only internal validation. This is useful for performance, offline scenarios, or testing. By default: `false`.

### Returns
_(boolean)_: Returns whether the input value is a valid TIN or not.

### Example
```js
isValid({});
// => false

isValid('9-0-0700000');
// => false

isValid('900-70-0000');
// => true

isValid('900700000');
// => true

isValid('123456789', { country: 'PT', entityType: 'natural-person' });
// => true
```
```

--------------------------------

### Sanitize TIN values

Source: https://context7.com/uphold/tin-validator/llms.txt

Removes non-numeric characters from a TIN string. Useful for normalizing user input before storage or validation. Different country codes may apply custom sanitization rules.

```javascript
const { sanitize } = require('tin-validator');

// US TIN sanitization — removes all non-digit characters
sanitize('9-0 0700000');
// => '900700000'

sanitize('900a7#$0foobar0000');
// => '900700000'

// EU TIN sanitization — removes dashes, slashes, spaces, dots and uppercases
sanitize('66-0000/000.', { country: 'FR', entityType: 'natural-person' });
// => '660000000'

// Finland uses a custom sanitize pattern (removes only ./\ s, preserving +, -, letters)
sanitize('131052-308T', { country: 'FI', entityType: 'natural-person' });
// => '131052-308T'

// Non-US, non-EU — value returned unchanged
sanitize('16-182749', { country: 'BO' });
// => '16-182749'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.