Skip to content

CLAUDE.md

Latest commit

 

History

History
105 lines (80 loc) · 3.98 KB

CLAUDE.md

File metadata and controls

105 lines (80 loc) · 3.98 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

  • Build: npm run build - Uses tsup to build CommonJS and ESM distributions with TypeScript declarations
  • Test: npm run test - Runs tests using vitest
  • Lint: npm run lint - Runs biome linter
  • Format: npm run format - Formats code using biome
  • Fix: npm run fix - Auto-fixes linting and formatting issues

Architecture

This is a TypeScript library providing type definitions, validation, and conversion utilities for IVMS101 (interVASP Messaging Standard). The library defaults to IVMS101.2023 with legacy 2020 support available via submodule import.

Core Structure

  • src/core.ts - Shared base types, enums, and interfaces used by both versions
  • src/countries.ts - ISO country code definitions
  • src/ivms101_2023.ts - Complete type definitions for IVMS101.2023 (depends only on core)
  • src/ivms101_2020.ts - Complete type definitions for IVMS101 2020 (depends only on core)
  • src/validator.ts - Zod-based validation schemas with all IVMS101 constraints (C1-C12)
  • src/converter.ts - Bidirectional conversion functions between versions
  • src/arbitraries.ts - Fast-check arbitraries for property-based testing
  • src/index.ts - Main entry point (exports 2023 types by default)
  • src/legacy.ts - Legacy entry point (exports 2020 types and converters)

Dependency Architecture

countries.ts (no dependencies)
    ↓
core.ts (depends on: countries.ts)
    ↓
    ├── ivms101_2023.ts (depends only on core.ts)
    └── ivms101_2020.ts (depends only on core.ts)
        ↓
    converter.ts (depends on both version files)
    validator.ts (depends on both version files)
    arbitraries.ts (depends on both version files)
        ↓
    ├── index.ts (main export - 2023 only)
    └── legacy.ts (legacy export - 2020 support)

Key principle: The 2020 and 2023 type definitions are completely independent of each other. Both depend only on shared core types.

Public API

Default (2023-first):

import { validate, type IVMS101, type NaturalPerson } from 'ivms101'
// All exports are IVMS101.2023 by default

Legacy (2020 support):

import { IVMS101_2020 } from 'ivms101/legacy'
import { validate } from 'ivms101'
// Access 2020 types and conversion utilities

Key Concepts

Version Detection: ivms101_version() automatically detects which version based on payloadMetadata.payloadVersion field

Validation: validate(data, { version?: '2020' | '2023' }) validates data against the spec (defaults to 2023)

Conversion: ensureVersion(version, data) converts data to desired version (defaults to 2023)

Version Differences (2020 → 2023)

Field name changes:

  • originatorPersons → originatorPerson (singular)
  • beneficiaryPersons → beneficiaryPerson (singular)
  • customerNumber → customerIdentification (both person types)
  • nameIdentifierType → naturalPersonNameIdentifierType (natural persons only)

New fields in 2023:

  • payloadMetadata.payloadVersion (required)

Validation Constraints

The library implements all 12 IVMS101 specification constraints:

  • C1: OriginatorInformationNaturalPerson
  • C2: DateInPast
  • C4: OriginatorInformationLegalPerson
  • C5: LegalNamePresentLegalPerson
  • C6: LegalNamePresentNaturalPerson
  • C8: ValidAddress
  • C9: CompleteNationalIdentifierLegalPerson
  • C10: RegistrationAuthority format
  • C11: ValidLEI format
  • C12: sequentialIntegrity (transfer paths)

Testing

Tests use vitest with property-based testing via fast-check:

  • test/converter.test.ts - Conversion accuracy and roundtrip tests
  • test/validator.test.ts - Validation constraint tests
  • test/arbitraries.test.ts - Arbitrary generator tests
  • test/arbitrary-validation.test.ts - Comprehensive validation tests

All generated data is 100% IVMS101-compliant.