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.

Examples

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

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

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

US states

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

Canada provinces

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

Months

• 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

Controlling Person Roles

• 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

Additional lookup helpers

• 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

Example

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

Examples

isCountryCode('US') // true isValidEmailAddress('[email protected]') // 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<UsStateCode, SmallUsTerritoryCountryCode | NormalUsTerritoryCountryCode>; 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

Example

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) }

Error message helpers

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

Examples

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 } }

Types

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

Notes

• 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 }.

Contributing

• 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

4.0.0

• Removing schemaVersion argument from validation report methods.