Taxbit Utilities

A collection of helpers, lookups, validations, and report generators used across Taxbit applications. Everything in this package is exported from the package root, so you can import directly from '@taxbit/utilities'.

Install

- npm: npm i @taxbit/utilities
- yarn: yarn add @taxbit/utilities

Import patterns

- Named imports are preferred.

import {
getCountryOptions,
getCountryLabel,
camelCaseKeys,
} from '@taxbit/utilities'

Contents overview

- Lookups (codes, labels, options, and treaty helpers)
- Validations (simple validators)
- Validation reports (address and tax documentation)
- Error message helpers
- Utilities (camelCaseKeys, snakeCaseKeys)
- Types and schema versions

Lookups

These functions and constants help with countries, states/provinces, months, account types, signatures, and treaty data.

Countries and phone helpers

- countryCodes: CountryCode[] — All ISO 3166-1 alpha-2 country codes supported.
- euCountryCodes: readonly string[] — EU member country codes.
- smallUsTerritoryCountryCodes: readonly ['UM','FM'] — Small US territories represented as country codes.
- normalUsTerritoryCountryCodes: readonly ['AS','GU','MP','PR','VI'] — Larger US territories (outside the 50 states).
- doesNotIssueTinCountryCodes: readonly string[] - Country codes for countries which do not issue TINs.
- doesNotRequireTinDisclosureCountryCodes: readonly ['JP'] - Country codes for countries which do not require TIN disclosures.
- highRiskCountryCodes: readonly string[] - Country codes for countries classified as high risk under OECD guidance.
- isHighRiskCountry(code: string | undefined): boolean - Whether a country is classified as high risk under OECD guidance.
- isTinNotIssuedByCountry(code: string | undefined): boolean - Whether TIN is not issued by the given country.
- isTinDisclosureNotRequiredByCountry(code: string | undefined): boolean - Whether TIN disclosure is not required by the given country.
- isTinExpectedByCountry(code: string | undefined): boolean - Whether TIN is expected by the given country.
- isEuCountryCode(code: string): boolean — Whether a code is in the EU.
- getCountry(code: CountryCode): Country | undefined — Returns the country metadata (internal shape) for a given code.
- getCountryLabel(code: string | undefined, language: string): string — Returns a localized country label. The language should be an IETF/BCP47 tag (e.g., 'en', 'fr').
- getCountryOptions(language: string): Array<{ value: string; label: string }>
- getCountryWithPhoneOptions(language: string): Array<{ value: string; label: string }> — Like getCountryOptions, but label includes phone dialing code.
- getCountryAndPhoneNumber(input: string): { countryCode?: string; phoneNumber?: string } — Extracts a leading + and the remaining number.
- getPhoneNumber(code: string, number: string, formatted?: boolean): string — Build a phone number for a country; optionally formatted.

$3

getCountryOptions('en')
// → [{ value: 'AF', label: 'Afghanistan' }, ...]

getCountryLabel('AL', 'fr')
// → 'Albanie'

getCountryAndPhoneNumber('+1 206-555-1212')
// → { countryCode: 'US', phoneNumber: '2065551212' }

$3

- usStateCodes: string[] — All 50 US state codes.
- getUsStateOptions(): Array<{ value: string; label: string }>
- getUsStateLabel(code?: string): string

$3

- caProvinceCodes: string[] — Canadian provincial/territory codes.
- getCaProvinceOptions(language: string): Array<{ value: string; label: string }>
- getCaProvinceLabel(code?: string, language: string): string

$3

- monthCodes: string[] — ['01', '02', ..., '12']
- getMonthOptions(language: string): Array<{ value: string; label: string }>
- getMonthLabel(month?: string, language: string): string

Account and Entity types

All of the following are readonly string literal arrays plus their corresponding union types (when present):

- accountOwnerTypes
- activeNonFinancialEntityTypes
- entityAccountHolderAccountTypes
- entityRegardedOwnerAccountTypes
- entityTypes and type EntityType
- exemptFatcaCodes
- exemptPayeeCodes
- financialInstitutionTypes
- foreignAccountHolderAccountTypes
- foreignRegardedOwnerAccountTypes
- intermediaryAccountTypes
- limitationOnBenefits and type LimitationOnBenefit
- selfCertificationAccountTypes
- signatureCapacities and type SignatureCapacity
- tinNotRequiredReasons
- usAccountHolderAccountTypes
- usLlcAccountTypes
- usRegardedOwnerAccountTypes

$3

- trustRoles: readonly string[] — Roles for trust entities
- similarToTrustRoles: readonly string[] — Roles for entities similar to trusts
- otherEntityRoles: readonly string[] — Roles for other entity types
- getControllingPersonRoles(entityType: EntityType): readonly string[] — Returns appropriate roles for entity type

$3

- getLimitationOnBenefit(limitationOnBenefit: string): LimitationOnBenefit — Maps camelCase keys to limitation constants

Treaty helpers

- treatyCountryCodes: string[] — Codes of countries with treaty data.
- typesOfIncomeIndividual: Array
- typesOfIncomeEntity: Array
- getTreatyCountry(countryCode?: string): TreatyCountry — Returns structured treaty data or an empty object with defaults.
- getTreatyCountryWithholding(countryCode?: string, typeOfIncome?: string): { rate: string; articleParagraph: string; additionalConditionsRequired: boolean } | undefined
- getTreatyCountryWithholdingLabel(countryCode?: string, typeOfIncome?: string): string — Friendly label like "15% - Article 12(2)"; defaults to '30%'.
- getTreatyCountryLimitationsOnBenefit(country?: string): Array
- hasLimitationOnBenefits(country?: string): boolean
- getTreatyCountryLimitationOnBenefitOtherArticleParagraphs(country?: string): string[]
- isAdditionalConditionsRequired(country?: string, typeOfIncome?: string): boolean

$3

getTreatyCountryWithholdingLabel('GB', 'ROYALTIES_OTHER')
// → '0% - Article 12(1)'

Validations

Simple predicates for common fields.

- isCountryCode(value: unknown): value is CountryCode
- isSmallUsTerritoryCountryCode(value: unknown): value is SmallUsTerritoryCountryCode
- isNormalUsTerritoryCountryCode(value: unknown): value is NormalUsTerritoryCountryCode
- isValidEmailAddress(value: unknown): boolean
- isValidPhoneNumber(value: unknown): boolean
- isCorrectGiinFormat(value: unknown): boolean

$3

isCountryCode('US') // true
isValidEmailAddress('name@example.com') // true
isValidPhoneNumber('+14155552671') // true

Validation reports

Tools to build structured validation results used by forms and APIs.
SchemaVersion for validation is currently '3.0'

Address validation reports

- getAddressValidationReport(address: unknown): ValidationReport
- getCaAddressValidationReport(address: CaAddress): ValidationReport
- getUsStateAddressValidationReport(address: UsStateAddress): ValidationReport

Types

- CaAddress: { city: string; country: 'CA'; stateOrProvince: CaProvinceCode; firstLine: string; secondLine?: string; postalCode: string }
- UsStateAddress: { city: string; country: 'US'; stateOrProvince: Exclude; firstLine: string; secondLine?: string; postalCode: string }

Tax documentation validation reports

- assertVerifiedClientTaxDocumentation(data: unknown): asserts data is SignedClientTaxDocumentation
- assertVerifiedComprehensiveTaxDocumentation(data: unknown): asserts data is SignedDatedComprehensiveTaxDocumentation
- getClientTaxDocumentationValidationReport(data: unknown): ValidationReport
- getComprehensiveTaxDocumentationValidationReport(data: unknown): ValidationReport
- getSelfCertificationApiTaxDocumentationValidationReport(data: unknown): ValidationReport
- getWFormForeignIntermediaryApiValidationReport(data: unknown): ValidationReport
- getWFormTreatyClaimApiValidationReport(data: unknown): ValidationReport

$3

import { getAddressValidationReport } from '@taxbit/utilities'

const report = getAddressValidationReport({
country: 'US',
stateOrProvince: 'CA',
city: 'Salt Lake City',
firstLine: '123 Example St',
postalCode: '84111',
})

if (report.hasIssues()) {
console.log(report.issues)
}

$3

Each function takes a value (and sometimes additional context) and returns an array of message keys or undefined if the value is valid.

- getBusinessRegistrationNumberErrorMessages(value: unknown)
- getCaPostalCodeErrorMessages(value: unknown)
- getCaStateOrProvinceErrorMessages(value: unknown)
- getCountryErrorMessages(value: unknown)
- getDateOfBirthErrorMessages(value: unknown)
- getEmailAddressErrorMessages(value: unknown)
- getGbTinNinoErrorMessages(value: unknown)
- getPhoneNumberErrorMessages(value: unknown)
- getSignatureErrorMessages(value: unknown)
- getSpecialNumberErrorMessages(value: unknown)
- getSpecialStringErrorMessages(value: unknown)
- getTaxResidencesErrorMessages(value: unknown)
- getTaxResidenceTinErrorMessages(value: unknown)
- getUsPostalCodeErrorMessages(value: unknown)
- getUsStateOrProvinceErrorMessages(value: unknown)
- getUsTinErrorMessages(value: unknown)
- getVatIdentificationNumberErrorMessages(value: unknown)
- getWFormDateOfBirthErrorMessages(value: unknown)
- getGinnErrorMessages(value: unknown)

Utilities

- camelCaseKeys(obj: T): CamelCaseKeys
- snakeCaseKeys(obj: T): SnakeCaseKeys

$3

camelCaseKeys({ first_name: 'A', LAST_NAME: 'B' })
// → { firstName: 'A', lastName: 'b' }

snakeCaseKeys({ firstName: 'A', lastName: 'B', nestedValue1: { myValue2: 2 } })
// → { first_name: 'A', last_name: 'B', nested_value_1: { my_value_2: 2 } }

$3

Exported types (see source for full definitions):

- From types/ClientTaxDocumentation
- ClientAddress
- ClientTaxResidence
- ControllingPerson
- ClientAccountHolderTaxDocumentation
- ClientRegardedOwnerTaxDocumentation
- ClientTaxDocumentation
- SignedClientTaxDocumentation
- From types/ComprehensiveTaxDocumentation
- SignedComprehensiveTaxDocumentation
- SignedDatedComprehensiveTaxDocumentation
- From types/ErrorMessage
- ErrorMessage
- From types/Questionnaire
- Questionnaire
- From types/TypeOfIncome
- TypeOfIncome
- From types/ValidationError
- ValidationError
- From types/CamelCaseKeys
- CamelCase
- CamelCaseKeys
- SnakeCaseKeys
- From types/Utilities
- Requiredish
- Extends
- IsExact
- RequireKeys

$3

- Language parameters are expected to be IETF language tags (e.g., 'en', 'fr').
- Option/list helpers typically return arrays shaped as { value: string; label: string }.

$3

- Keep this README in sync with new exports from src/index.ts.
- When adding lookups, prefer readonly const arrays and export matching union types for better type safety.

Validation Report Notes

The getComprehensiveTaxDocumentationValidationReport function is used to validate the Submission posts.

| Package Version | Current Schema Version | Validation Report Improvements | Validated Schema Version |
| :-------------: | :--------------------: | -------------------------------------------------------- | :----------------------: |
| 4.0.0 | 3.1 | Schema Version removed from Validation Report functions | 3.0 |
| 3.6.0 | 3.1 | OECD high risk country helper function. | 3.0 |
| 3.5.0 | 3.1 | Country code helper functions. | 3.0 |
| 3.4.0 | 3.1 | CARF/CRS validations. | 3.0 |
| 3.3.x | 3.1 | Tax Residence Validation Refinements | 3.0 |
| 3.2.x | 3.1 | W8IMY validation report. | 3.0 |
| 3.1.0 | 3.1 | Self-Cert and SERR validation reports. | 2.0 |
| 3.0.0 | 3.0 | Account Owner key for foreign accounts. | 2.0 |
| 2.0.0 | 2.0 | Treaty Claim validation report. | 2.0 |
| 0.3.3 | 1.1 | Updated validations for US territories. | 1.1 |
| 0.3.1 | 1.0 | Initial release with lookups, validations, and utilities | 1.0 |

Version History

$3

- Removing schemaVersion argument from validation report methods.