@accounter/shaam-uniform-format-generator/README.md

Fully typed application that generates, parses, and validates SHAAM uniform format tax reports (INI.TXT and BKMVDATA.TXT).

# @accounter/shaam-uniform-format-generator

Fully typed application that generates, parses, and validates SHAAM uniform format tax reports
(INI.TXT and BKMVDATA.TXT).

## 🧩 Overview

This package provides a comprehensive solution for working with SHAAM (Israeli tax authority)
uniform format files. It allows you to:

1. **Generate** `INI.TXT` and `BKMVDATA.TXT` files from a high-level JSON object
2. **Parse** those files back into structured, validated JSON with comprehensive validation
3. **Validate** data against SHAAM 1.31 specifications with multiple validation modes
4. **Format** output with spec-compliant field widths, padding, and CRLF line endings
5. **Round-trip** data preservation ensuring high-fidelity parsing and re-generation

## 🚀 Features

- **Type Safety**: Full TypeScript support with strict typing
- **Validation**: Built-in Zod schemas for data validation with multiple modes
- **Format Compliance**: Generates files that meet SHAAM 1.31 specifications
- **Developer Experience**: Excellent autocompletion and helpful error messages
- **File System Agnostic**: Returns content in memory without writing to disk
- **Comprehensive Testing**: Full test coverage with Vitest including integration tests
- **Dual Module Support**: Ships with both CommonJS and ESM builds
- **Round-trip Fidelity**: Preserves original data through parse-generate cycles

## 📁 Supported Record Types

### `INI.TXT`

- `A000` — Header
- `A000Sum` — Count summary records for each record type

### `BKMVDATA.TXT`

- `A100` — Business opening record
- `C100` — Document header
- `D110` — Document line
- `D120` — Payment/receipt
- `B100` — Journal entry line
- `B110` — Account
- `M100` — Inventory item
- `Z900` — Closing record

## 🛠️ Installation

```bash
npm install @accounter/shaam-uniform-format-generator
# or
yarn add @accounter/shaam-uniform-format-generator
```

## 📖 API Documentation

### Main Functions

#### `generateUniformFormatReport(input, options?)`

Generates SHAAM uniform format report files from a high-level JSON input object.

```typescript
import {
  generateUniformFormatReport,
  type ReportInput
} from '@accounter/shaam-uniform-format-generator'

const reportInput: ReportInput = {
  business: {
    businessId: '12345',
    name: 'Example Business Ltd',
    taxId: '123456789',
    reportingPeriod: {
      startDate: '2023-01-01',
      endDate: '2023-12-31'
    }
  },
  documents: [
    {
      id: 'INV001',
      type: '320', // Invoice
      date: '2023-06-15',
      amount: 1000.0,
      description: 'Service invoice'
    }
  ],
  journalEntries: [
    {
      id: 'JE001',
      date: '2023-06-15',
      amount: 1000.0,
      accountId: '1100',
      description: 'Revenue entry'
    }
  ],
  accounts: [
    {
      id: '1100',
      name: 'Revenue Account',
      type: '4', // Revenue
      balance: 1000.0
    }
  ],
  inventory: [
    {
      id: 'ITEM001',
      name: 'Service Item',
      quantity: 1,
      unitPrice: 1000.0
    }
  ]
}

const result = generateUniformFormatReport(reportInput, {
  validationMode: 'fail-fast', // or 'collect-all'
  fileNameBase: 'my-report'
})

console.log(result.iniText) // INI.TXT content
console.log(result.dataText) // BKMVDATA.TXT content
console.log(result.summary) // Generation summary
```

#### `parseUniformFormatFiles(iniContent, dataContent, options?)`

Parses SHAAM uniform format files back into structured JSON with comprehensive validation.

```typescript
import { parseUniformFormatFiles } from '@accounter/shaam-uniform-format-generator'

const parseResult = parseUniformFormatFiles(iniFileContent, dataFileContent, {
  validationMode: 'lenient', // 'strict' | 'lenient' | 'none'
  skipUnknownRecords: true,
  allowPartialData: true
})

console.log(parseResult.data.business) // Parsed business metadata
console.log(parseResult.data.documents) // Parsed documents
console.log(parseResult.summary.totalRecords) // Parse summary
console.log(parseResult.summary.errors) // Validation errors
console.log(parseResult.summary.crossValidationPassed) // Cross-validation result
```

### Types and Interfaces

#### `ReportInput`

```typescript
interface ReportInput {
  business: BusinessMetadata
  documents: Document[]
  journalEntries: JournalEntry[]
  accounts: Account[]
  inventory: InventoryItem[]
}
```

#### `BusinessMetadata`

```typescript
interface BusinessMetadata {
  businessId: string
  name: string
  taxId: string
  reportingPeriod: {
    startDate: string // YYYY-MM-DD format
    endDate: string // YYYY-MM-DD format
  }
}
```

#### `Document`

```typescript
interface Document {
  id: string
  type: DocumentType // e.g., "320" for invoice, "330" for credit note
  date: string // YYYY-MM-DD format
  amount: number
  description?: string
}
```

#### `JournalEntry`

```typescript
interface JournalEntry {
  id: string
  date: string // YYYY-MM-DD format
  amount: number
  accountId: string
  description?: string
  transactionNumber?: number
  transactionLineNumber?: number
  batchNumber?: number
  transactionType?: string
  referenceDocument?: string
  referenceDocumentType?: DocumentType
  referenceDocument2?: string
  referenceDocumentType2?: DocumentType
  valueDate?: string
  counterAccountKey?: string
  debitCreditIndicator?: '1' | '2' // 1=Debit, 2=Credit
  currencyCode?: CurrencyCode
  transactionAmount?: number // Preserve original B100 transaction amount
  foreignCurrencyAmount?: number
  quantityField?: number
  matchingField1?: string
  matchingField2?: string
  branchId?: string
  entryDate?: string
  operatorUsername?: string
  reserved?: string
}
```

#### `Account`

```typescript
interface Account {
  id: string
  name?: string // Optional for round-trip compatibility
  sortCode: {
    key: string // Required - Account sort code key
    name?: string // Optional - Sort code description
  }
  address?: {
    street?: string
    houseNumber?: string
    city?: string
    zip?: string
    country?: string
  }
  countryCode?: string // ISO country code
  parentAccountKey?: string // Parent account identifier
  vatId?: string // Supplier/Customer VAT ID
  accountOpeningBalance: number // Required - Opening balance amount
  totalDebits?: number // Total debit transactions
  totalCredits?: number // Total credit transactions
  accountingClassificationCode?: string // Classification code (max 4 digits)
  branchId?: string // Branch identifier
  openingBalanceForeignCurrency?: number // Opening balance in foreign currency
  foreignCurrencyCode?: string // Foreign currency code (e.g., "USD", "EUR")
}
```

#### `InventoryItem`

```typescript
interface InventoryItem {
  id: string
  name: string
  quantity: number
  unitPrice: number
}
```

#### `ValidationError`

```typescript
interface ValidationError {
  recordType: string
  recordIndex: number
  field: string
  message: string
  severity?: 'error' | 'warning' // Only in parse results
}
```

````

#### `ReportOutput`

```typescript
interface ReportOutput {
  iniText: string // INI.TXT file content
  dataText: string // BKMVDATA.TXT file content
  iniFile: File // Virtual File object for INI.TXT
  dataFile: File // Virtual File object for BKMVDATA.TXT
  summary: {
    totalRecords: number
    perType: Record<string, number>
    errors?: ValidationError[] // Only present if validation fails in collect-all mode
  }
}
````

#### `ParseResult`

```typescript
interface ParseResult {
  data: ReportInput // Parsed structured data
  summary: {
    totalRecords: number
    perType: Record<string, number>
    errors: ValidationError[]
    crossValidationPassed: boolean
  }
}
```

### Options

#### `GenerationOptions`

```typescript
interface GenerationOptions {
  validationMode?: 'fail-fast' | 'collect-all' // Default: 'fail-fast'
  fileNameBase?: string // Default: 'report'
}
```

- **`validationMode`**:
  - `'fail-fast'`: Stop validation on first error and throw immediately
  - `'collect-all'`: Collect all validation errors before throwing
- **`fileNameBase`**: Base name for generated files (without extension)

### Enums and Constants

The package exports comprehensive enums for SHAAM code tables:

```typescript
import {
  CountryCodeEnum,
  CurrencyCodeEnum,
  DebitCreditIndicatorEnum,
  DocumentTypeEnum,
  PaymentMethodEnum,
  RecordTypeEnum
  // ... and many more
} from '@accounter/shaam-uniform-format-generator'

// Document types
const invoiceType = DocumentTypeEnum.enum['320'] // Invoice
const creditNoteType = DocumentTypeEnum.enum['330'] // Credit Tax Invoice

// Currency codes
const ils = CurrencyCodeEnum.enum.ILS // Israeli Shekel
const usd = CurrencyCodeEnum.enum.USD // US Dollar

// Payment methods
const cash = PaymentMethodEnum.enum['1'] // Cash
const check = PaymentMethodEnum.enum['2'] // Check

// Debit/Credit indicators
const debit = DebitCreditIndicatorEnum.enum['1'] // Debit
const credit = DebitCreditIndicatorEnum.enum['2'] // Credit

// Record types
const b110 = RecordTypeEnum.enum.B110 // Account record
const c100 = RecordTypeEnum.enum.C100 // Document header record
```

## 🎯 Complete Example

```typescript
import {
  generateUniformFormatReport,
  parseUniformFormatFiles,
  type ReportInput
} from '@accounter/shaam-uniform-format-generator'

// 1. Prepare your data
const reportData: ReportInput = {
  business: {
    businessId: 'COMP001',
    name: 'Acme Corp Ltd',
    taxId: '123456789',
    reportingPeriod: {
      startDate: '2023-01-01',
      endDate: '2023-12-31'
    }
  },
  documents: [
    {
      id: 'INV-2023-001',
      type: '320', // Invoice
      date: '2023-03-15',
      amount: 2340.0,
      description: 'Consulting services'
    },
    {
      id: 'CN-2023-001',
      type: '330', // Credit note
      date: '2023-04-10',
      amount: -340.0,
      description: 'Service adjustment'
    }
  ],
  journalEntries: [
    {
      id: 'JE-2023-001',
      date: '2023-03-15',
      amount: 2340.0,
      accountId: '4000',
      description: 'Consulting revenue',
      batchNumber: 'BATCH-Q1-2023',
      transactionType: 'SALE',
      referenceDocument: 'INV-2023-001'
    },
    {
      id: 'JE-2023-002',
      date: '2023-04-10',
      amount: -340.0,
      accountId: '4000',
      description: 'Revenue adjustment',
      currencyCode: 'USD',
      foreignCurrencyAmount: -290.0
    }
  ],
  accounts: [
    {
      id: '4000',
      name: 'Consulting Revenue',
      sortCode: {
        key: 'Revenue',
        name: 'Revenue Accounts'
      },
      accountOpeningBalance: 0.0,
      totalDebits: 500.0,
      totalCredits: 2500.0,
      accountingClassificationCode: '0001'
    },
    {
      id: '1200',
      name: 'Accounts Receivable',
      sortCode: {
        key: 'Asset',
        name: 'Asset Accounts'
      },
      accountOpeningBalance: 1500.0,
      countryCode: 'IL',
      branchId: 'MAIN',
      foreignCurrencyCode: 'USD',
      openingBalanceForeignCurrency: 1250.0
    }
  ],
  inventory: [
    {
      id: 'SERV-001',
      name: 'Consulting Hour',
      quantity: 20,
      unitPrice: 117.0
    }
  ]
}

// 2. Generate the files
try {
  const result = generateUniformFormatReport(reportData, {
    validationMode: 'fail-fast',
    fileNameBase: 'quarterly-report-2023-q1'
  })

  // 3. Access the generated content
  console.log('Generated INI.TXT:')
  console.log(result.iniText)

  console.log('\nGenerated BKMVDATA.TXT:')
  console.log(result.dataText)

  console.log('\nSummary:')
  console.log(`Total records: ${result.summary.totalRecords}`)
  console.log('Records per type:', result.summary.perType)

  // 4. Save files (example using Node.js fs)
  // import { writeFileSync } from 'fs'
  // writeFileSync('report.INI.TXT', result.iniText, 'utf8')
  // writeFileSync('report.BKMVDATA.TXT', result.dataText, 'utf8')

  // 5. Parse files back (round-trip test)
  const parsedData = parseUniformFormatFiles(result.iniText, result.dataText)
  console.log('\nParsed business data:', parsedData.business)
} catch (error) {
  console.error('Generation failed:', error.message)
  if (error.errors) {
    console.error('Validation errors:', error.errors)
  }
}
```

## 🔧 Advanced Usage

### Custom Validation

```typescript
import { ReportInputSchema } from '@accounter/shaam-uniform-format-generator'

// Validate data before generation
const validationResult = ReportInputSchema.safeParse(yourData)
if (!validationResult.success) {
  console.error('Validation errors:', validationResult.error.issues)
}
```

### Parse with Different Validation Modes

```typescript
import { parseUniformFormatFiles } from '@accounter/shaam-uniform-format-generator'

// Strict validation - throws on any error
try {
  const strictResult = parseUniformFormatFiles(iniContent, dataContent, {
    validationMode: 'strict',
    allowPartialData: false
  })
  console.log('Strict parsing succeeded:', strictResult.data)
} catch (error) {
  console.error('Strict parsing failed:', error.message)
}

// Lenient validation - reports issues but continues
const lenientResult = parseUniformFormatFiles(iniContent, dataContent, {
  validationMode: 'lenient'
})
console.log('Parsed data:', lenientResult.data)
console.log('Validation issues:', lenientResult.summary.errors)

// No validation - fastest parsing
const fastResult = parseUniformFormatFiles(iniContent, dataContent, {
  validationMode: 'none'
})
console.log('Fast parsing result:', fastResult.data)
```

### Working with Individual Records

```typescript
import { encodeC100, parseC100, type C100 } from '@accounter/shaam-uniform-format-generator'

// Encode a single document record
const documentRecord: C100 = {
  code: 'C100',
  recordNumber: 1,
  vatId: '123456789',
  documentType: '320',
  documentId: 'INV001',
  documentIssueDate: '20230315',
  documentIssueTime: '',
  customerName: '',
  customerStreet: '',
  customerHouseNumber: '',
  customerCity: '',
  customerPostCode: '',
  customerCountry: '',
  customerCountryCode: '',
  customerPhone: '',
  customerVatId: '',
  documentValueDate: '',
  foreignCurrencyAmount: '',
  currencyCode: '',
  amountBeforeDiscount: '',
  documentDiscount: '',
  amountAfterDiscountExcludingVat: '',
  vatAmount: '',
  amountIncludingVat: '1000.00',
  withholdingTaxAmount: '',
  customerKey: '',
  matchingField: '',
  cancelledAttribute1: '',
  cancelledDocument: '',
  cancelledAttribute2: '',
  documentDate: '',
  branchKey: '',
  cancelledAttribute3: '',
  actionExecutor: '',
  lineConnectingField: '',
  reserved: ''
}

const encodedLine = encodeC100(documentRecord)
console.log(encodedLine) // Fixed-width formatted line

// Parse it back
const parsedRecord = parseC100(encodedLine)
console.log(parsedRecord) // Structured object
```

## 🏗️ Development

This project uses:

- **TypeScript** in strict mode for type safety
- **Zod** for runtime validation and schema definitions
- **Vitest** for testing with comprehensive integration tests
- **Bob the Bundler** for building dual CJS/ESM packages
- **ESLint** for code linting and formatting

### Commands

```bash
# Development
yarn dev

# Testing
yarn test
yarn test:watch

# Building
yarn build

# Linting
yarn lint
```

## 📋 Requirements

- Node.js ^20.0.0 || >= 22
- TypeScript support

## 🚨 Error Handling

The library provides detailed error information:

```typescript
import { ShaamFormatError } from '@accounter/shaam-uniform-format-generator'

try {
  const result = generateUniformFormatReport(invalidData)
} catch (error) {
  if (error instanceof ShaamFormatError) {
    console.error('SHAAM format error:', error.message)
    console.error('Validation errors:', error.errors)
  }
}

// Parse errors include context and severity
try {
  const parseResult = parseUniformFormatFiles(iniContent, dataContent, {
    validationMode: 'strict'
  })
} catch (error) {
  console.error('Parse failed:', error.message)
}

// Access detailed validation information
const parseResult = parseUniformFormatFiles(iniContent, dataContent, {
  validationMode: 'lenient'
})

for (const error of parseResult.summary.errors) {
  console.log(`${error.severity}: ${error.message}`)
  console.log(`Record: ${error.recordType}[${error.recordIndex}], Field: ${error.field}`)
}
```

## �📄 License

MIT

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our
repository.

## 📚 Documentation

For detailed documentation about SHAAM format specifications, see the `documentation/` folder.

## 🔗 Related

- [SHAAM Specification 1.31](documentation/) - Official specification documents
- [Israeli Tax Authority](https://www.gov.il/he/departments/taxes) - Official tax authority website