@accounter/shaam-uniform-format-generator 0.1.0 → 0.1.1

package/README.md

@@ -27,18 +27,18 @@ uniform format files. It allows you to:
 ### `INI.TXT`
 
 - `A000` — Header
-- `B100`, `B110`, `C100`, `D110`, `D120`, `M100` — Count summary records
+- `A000Sum` — Count summary records for each record type
 
 ### `BKMVDATA.TXT`
 
-- `A100` — Opening
+- `A100` — Business opening record
 - `C100` — Document header
 - `D110` — Document line
 - `D120` — Payment/receipt
 - `B100` — Journal entry line
 - `B110` — Account
 - `M100` — Inventory item
-- `Z900` — Closing
+- `Z900` — Closing record
 
 ## 🛠️ Installation
 
@@ -48,36 +48,367 @@ npm install @accounter/shaam-uniform-format-generator
 yarn add @accounter/shaam-uniform-format-generator
 ```
 
-## 📖 Usage
+## 📖 API Documentation
+
+### Main Functions
+
+#### `generateUniformFormatReport(input, options?)`
+
+Generates SHAAM uniform format report files from a high-level JSON input object.
 
 ```typescript
-import { generateUniformFormatReport } from '@accounter/shaam-uniform-format-generator'
+import {
+  generateUniformFormatReport,
+  type ReportInput
+} from '@accounter/shaam-uniform-format-generator'
 
-const reportInput = {
+const reportInput: ReportInput = {
   business: {
-    // Business metadata
+    businessId: '12345',
+    name: 'Example Business Ltd',
+    taxId: '123456789',
+    reportingPeriod: {
+      startDate: '2023-01-01',
+      endDate: '2023-12-31'
+    }
   },
   documents: [
-    // Document records
+    {
+      id: 'INV001',
+      type: '320', // Invoice
+      date: '2023-06-15',
+      amount: 1000.0,
+      description: 'Service invoice'
+    }
   ],
   journalEntries: [
-    // Journal entry records
+    {
+      id: 'JE001',
+      date: '2023-06-15',
+      amount: 1000.0,
+      accountId: '1100',
+      description: 'Revenue entry'
+    }
   ],
   accounts: [
-    // Account records
+    {
+      id: '1100',
+      name: 'Revenue Account',
+      type: '4', // Revenue
+      balance: 1000.0
+    }
   ],
   inventory: [
-    // Inventory records
+    {
+      id: 'ITEM001',
+      name: 'Service Item',
+      quantity: 1,
+      unitPrice: 1000.0
+    }
   ]
 }
 
-const result = generateUniformFormatReport(reportInput)
+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)`
+
+Parses SHAAM uniform format files back into structured JSON.
+
+```typescript
+import { parseUniformFormatFiles } from '@accounter/shaam-uniform-format-generator'
+
+const parsedData = parseUniformFormatFiles(iniFileContent, dataFileContent)
+console.log(parsedData.business) // Parsed business metadata
+console.log(parsedData.documents) // Parsed documents
+```
+
+### 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
+}
+```
+
+#### `Account`
+
+```typescript
+interface Account {
+  id: string
+  name: string
+  type: string // Account type code
+  balance: number
+}
+```
+
+#### `InventoryItem`
+
+```typescript
+interface InventoryItem {
+  id: string
+  name: string
+  quantity: number
+  unitPrice: number
+}
+```
+
+#### `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[]
+  }
+}
+```
+
+### 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,
+  DocumentTypeEnum,
+  PaymentMethodEnum
+} from '@accounter/shaam-uniform-format-generator'
+
+// Document types
+const invoiceType = DocumentTypeEnum.enum['320'] // Invoice
+const creditNoteType = DocumentTypeEnum.enum['330'] // Credit note
+
+// 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
+```
+
+## 🎯 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'
+    },
+    {
+      id: 'JE-2023-002',
+      date: '2023-04-10',
+      amount: -340.0,
+      accountId: '4000',
+      description: 'Revenue adjustment'
+    }
+  ],
+  accounts: [
+    {
+      id: '4000',
+      name: 'Consulting Revenue',
+      type: '4', // Revenue account
+      balance: 2000.0
+    },
+    {
+      id: '1200',
+      name: 'Accounts Receivable',
+      type: '1', // Asset account
+      balance: 1500.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)
+}
+```
+
+### Working with Individual Records
+
+```typescript
+import { encodeC100, parseC100, type C100Input } from '@accounter/shaam-uniform-format-generator'
+
+// Encode a single document record
+const documentRecord: C100Input = {
+  code: 'C100',
+  recordNumber: '1',
+  vatId: '123456789',
+  documentType: '320',
+  documentId: 'INV001',
+  documentIssueDate: '20230315'
+  // ... other fields
+}
+
+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:
@@ -109,7 +440,24 @@ yarn lint
 - Node.js ^20.0.0 || >= 22
 - TypeScript support
 
-## 📄 License
+## � 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)
+  }
+}
+```
+
+## �📄 License
 
 MIT
 
@@ -121,3 +469,8 @@ 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