@accounter/shaam-uniform-format-generator 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @accounter/shaam-uniform-format-generator
+
+A fully typed TypeScript library for generating, parsing, and validating SHAAM uniform format tax
+reports (`INI.TXT` and `BKMVDATA.TXT` files).
+
+## 🧩 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
+3. **Validate** data against SHAAM 1.31 specifications
+4. **Format** output with spec-compliant field widths, padding, and CRLF line endings
+
+## 🚀 Features
+
+- **Type Safety**: Full TypeScript support with strict typing
+- **Validation**: Built-in Zod schemas for data validation
+- **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
+
+## 📁 Supported Record Types
+
+### `INI.TXT`
+
+- `A000` — Header
+- `B100`, `B110`, `C100`, `D110`, `D120`, `M100` — Count summary records
+
+### `BKMVDATA.TXT`
+
+- `A100` — Opening
+- `C100` — Document header
+- `D110` — Document line
+- `D120` — Payment/receipt
+- `B100` — Journal entry line
+- `B110` — Account
+- `M100` — Inventory item
+- `Z900` — Closing
+
+## 🛠️ Installation
+
+```bash
+npm install @accounter/shaam-uniform-format-generator
+# or
+yarn add @accounter/shaam-uniform-format-generator
+```
+
+## 📖 Usage
+
+```typescript
+import { generateUniformFormatReport } from '@accounter/shaam-uniform-format-generator'
+
+const reportInput = {
+  business: {
+    // Business metadata
+  },
+  documents: [
+    // Document records
+  ],
+  journalEntries: [
+    // Journal entry records
+  ],
+  accounts: [
+    // Account records
+  ],
+  inventory: [
+    // Inventory records
+  ]
+}
+
+const result = generateUniformFormatReport(reportInput)
+
+console.log(result.iniText) // INI.TXT content
+console.log(result.dataText) // BKMVDATA.TXT content
+console.log(result.summary) // Generation summary
+```
+
+## 🏗️ Development
+
+This project uses:
+
+- **TypeScript** in strict mode for type safety
+- **Zod** for runtime validation
+- **Vitest** for testing
+- **Bob the Bundler** for building
+
+### 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
+
+## 📄 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.

package/cjs/api/generate-report.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Main API for generating SHAAM uniform format reports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUniformFormatReport = generateUniformFormatReport;
+const errors_js_1 = require("../validation/errors.js");
+const validate_input_js_1 = require("../validation/validate-input.js");
+/**
+ * Generates SHAAM uniform format report files (INI.TXT and BKMVDATA.TXT)
+ * from a high-level JSON input object.
+ *
+ * @param input - The report input data
+ * @param options - Generation options
+ * @returns Report output with generated file content
+ */
+function generateUniformFormatReport(input, options = {}) {
+    // Validate input data first
+    const validationMode = options.validationMode || 'fail-fast';
+    const validationErrors = (0, validate_input_js_1.validateInput)(input, validationMode);
+    if (validationErrors.length > 0) {
+        if (validationMode === 'fail-fast') {
+            // This should have already thrown, but just in case
+            throw new errors_js_1.ShaamFormatError('Validation failed', validationErrors);
+        }
+        // For collect-all mode, we still throw if there are errors
+        // The user can catch and inspect the errors if needed
+        throw new errors_js_1.ShaamFormatError('Input validation failed', validationErrors);
+    }
+    // TODO: Implement the actual generation logic
+    const iniText = 'A000placeholder\r\n'; // Placeholder
+    const dataText = 'A100placeholder\r\n'; // Placeholder
+    // Create virtual File objects
+    const iniFile = new File([iniText], `${options.fileNameBase || 'report'}.INI.TXT`, {
+        type: 'text/plain',
+    });
+    const dataFile = new File([dataText], `${options.fileNameBase || 'report'}.BKMVDATA.TXT`, {
+        type: 'text/plain',
+    });
+    return {
+        iniText,
+        dataText,
+        iniFile,
+        dataFile,
+        summary: {
+            totalRecords: 2, // Placeholder
+            perType: {
+                A000: 1,
+                A100: 1,
+            },
+        },
+    };
+}

package/cjs/api/parse-files.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * API for parsing SHAAM uniform format files
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUniformFormatFiles = parseUniformFormatFiles;
+/**
+ * Parses SHAAM uniform format files (INI.TXT and BKMVDATA.TXT)
+ * back into structured JSON objects.
+ *
+ * @param iniContent - Content of the INI.TXT file
+ * @param dataContent - Content of the BKMVDATA.TXT file
+ * @returns Parsed report input data
+ */
+function parseUniformFormatFiles(_iniContent, _dataContent) {
+    // TODO: Implement the actual parsing logic
+    return {
+        business: {
+            businessId: 'placeholder',
+            name: 'Placeholder Business',
+            taxId: '000000000',
+            reportingPeriod: {
+                startDate: '2024-01-01',
+                endDate: '2024-12-31',
+            },
+        },
+        documents: [],
+        journalEntries: [],
+        accounts: [],
+        inventory: [],
+    };
+}

package/cjs/format/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Format utilities for SHAAM uniform format files
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./padding.js"), exports);
+tslib_1.__exportStar(require("./newline.js"), exports);

package/cjs/format/newline.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Line ending constants for SHAAM format files
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CRLF = void 0;
+/**
+ * CRLF line ending as required by SHAAM format specification
+ */
+exports.CRLF = '\r\n';

package/cjs/format/padding.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * String padding utilities for fixed-width formatting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.padLeft = padLeft;
+exports.padRight = padRight;
+/**
+ * Pads a string on the left (right-aligns the content)
+ *
+ * @param value - The string to pad
+ * @param width - Target width
+ * @param fill - Character to use for padding (default: space)
+ * @returns Left-padded string
+ */
+function padLeft(value, width, fill = ' ') {
+    if (value.length >= width) {
+        return value.substring(0, width);
+    }
+    const padLength = width - value.length;
+    const padding = fill.repeat(padLength);
+    return padding + value;
+}
+/**
+ * Pads a string on the right (left-aligns the content)
+ *
+ * @param value - The string to pad
+ * @param width - Target width
+ * @param fill - Character to use for padding (default: space)
+ * @returns Right-padded string
+ */
+function padRight(value, width, fill = ' ') {
+    if (value.length >= width) {
+        return value.substring(0, width);
+    }
+    const padLength = width - value.length;
+    const padding = fill.repeat(padLength);
+    return value + padding;
+}

package/cjs/generator/format/decoder.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Fixed-width decoding utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeFixedWidth = decodeFixedWidth;
+/**
+ * Decodes a fixed-width string value
+ *
+ * @param line - The line to decode from
+ * @param start - Start position (0-based)
+ * @param length - Field length
+ * @returns Decoded and trimmed value
+ */
+function decodeFixedWidth(line, start, length) {
+    return line.substring(start, start + length).trim();
+}

package/cjs/generator/format/encoder.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Fixed-wiexport function formatField(
+  value: string,
+  width: number,
+  align: 'left' | 'right',
+  padChar = ' '
+): string {
+  if (align === 'left') {
+    return padRight(value, width, padChar);
+  }
+  return padLeft(value, width, padChar);
+} utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatField = formatField;
+exports.encodeFixedWidth = encodeFixedWidth;
+const padding_js_1 = require("../../format/padding.js");
+/**
+ * Formats a field value with specified width and alignment
+ *
+ * @param value - The value to format
+ * @param width - Target field width
+ * @param align - Alignment ('left' or 'right')
+ * @param padChar - Character to use for padding (default: space)
+ * @returns Formatted fixed-width string
+ */
+function formatField(value, width, align, padChar = ' ') {
+    if (align === 'left') {
+        return (0, padding_js_1.padRight)(value, width, padChar);
+    }
+    return (0, padding_js_1.padLeft)(value, width, padChar);
+}
+/**
+ * Encodes a value to fixed-width format with padding
+ *
+ * @param value - The value to encode
+ * @param width - Target width
+ * @param padChar - Padding character (default: space)
+ * @param align - Alignment ('left' or 'right')
+ * @returns Fixed-width encoded string
+ */
+function encodeFixedWidth(value, width, padChar = ' ', align = 'left') {
+    const str = String(value);
+    return formatField(str, width, align, padChar);
+}

package/cjs/generator/format/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Format encoding and decoding utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./encoder.js"), exports);
+tslib_1.__exportStar(require("./decoder.js"), exports);

package/cjs/generator/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * File generation utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./records/index.js"), exports);
+tslib_1.__exportStar(require("./format/index.js"), exports);

package/cjs/generator/records/a000.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * A000 - Header record for INI.TXT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A000_PLACEHOLDER = void 0;
+// TODO: Implement A000 record schema and functions
+exports.A000_PLACEHOLDER = 'A000';

package/cjs/generator/records/a100.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * A100 - Opening record for BKMVDATA.TXT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A100_PLACEHOLDER = void 0;
+// TODO: Implement A100 record schema and functions
+exports.A100_PLACEHOLDER = 'A100';

package/cjs/generator/records/b100.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * B100 - Journal entry line record
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.B100_PLACEHOLDER = void 0;
+// TODO: Implement B100 record schema and functions
+exports.B100_PLACEHOLDER = 'B100';

package/cjs/generator/records/b110.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * B110 - Account record
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.B110_PLACEHOLDER = void 0;
+// TODO: Implement B110 record schema and functions
+exports.B110_PLACEHOLDER = 'B110';

package/cjs/generator/records/c100.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * C100 - Document header record
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.C100_PLACEHOLDER = void 0;
+// TODO: Implement C100 record schema and functions
+exports.C100_PLACEHOLDER = 'C100';

package/cjs/generator/records/d110.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * D110 - Document line record
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.D110_PLACEHOLDER = void 0;
+// TODO: Implement D110 record schema and functions
+exports.D110_PLACEHOLDER = 'D110';

package/cjs/generator/records/d120.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * D120 - Payment/receipt record
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.D120_PLACEHOLDER = void 0;
+// TODO: Implement D120 record schema and functions
+exports.D120_PLACEHOLDER = 'D120';

package/cjs/generator/records/index.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Record type definitions and generators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./a000.js"), exports);
+tslib_1.__exportStar(require("./a100.js"), exports);
+tslib_1.__exportStar(require("./b100.js"), exports);
+tslib_1.__exportStar(require("./b110.js"), exports);
+tslib_1.__exportStar(require("./c100.js"), exports);
+tslib_1.__exportStar(require("./d110.js"), exports);
+tslib_1.__exportStar(require("./d120.js"), exports);
+tslib_1.__exportStar(require("./m100.js"), exports);
+tslib_1.__exportStar(require("./z900.js"), exports);

package/cjs/generator/records/m100.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * M100 - Inventory item record
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.M100_PLACEHOLDER = void 0;
+// TODO: Implement M100 record schema and functions
+exports.M100_PLACEHOLDER = 'M100';

package/cjs/generator/records/z900.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Z900 - Closing record for BKMVDATA.TXT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Z900_PLACEHOLDER = void 0;
+// TODO: Implement Z900 record schema and functions
+exports.Z900_PLACEHOLDER = 'Z900';

package/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * @accounter/shaam-uniform-format-generator
+ *
+ * A fully typed TypeScript library for generating, parsing, and validating
+ * SHAAM uniform format tax reports (INI.TXT and BKMVDATA.TXT files).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUniformFormatFiles = exports.generateUniformFormatReport = void 0;
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./types/index.js"), exports);
+tslib_1.__exportStar(require("./generator/index.js"), exports);
+tslib_1.__exportStar(require("./parser/index.js"), exports);
+tslib_1.__exportStar(require("./validation/index.js"), exports);
+// Main API
+var generate_report_js_1 = require("./api/generate-report.js");
+Object.defineProperty(exports, "generateUniformFormatReport", { enumerable: true, get: function () { return generate_report_js_1.generateUniformFormatReport; } });
+var parse_files_js_1 = require("./api/parse-files.js");
+Object.defineProperty(exports, "parseUniformFormatFiles", { enumerable: true, get: function () { return parse_files_js_1.parseUniformFormatFiles; } });

package/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/cjs/parser/data-parser.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * BKMVDATA.TXT file parsing utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDataFile = parseDataFile;
+/**
+ * Parses BKMVDATA.TXT file content
+ *
+ * @param content - Raw BKMVDATA.TXT file content
+ * @returns Parsed data structure
+ */
+function parseDataFile(_content) {
+    // TODO: Implement data file parsing logic
+    return {};
+}

package/cjs/parser/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * File parsing utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./ini-parser.js"), exports);
+tslib_1.__exportStar(require("./data-parser.js"), exports);

package/cjs/parser/ini-parser.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * INI.TXT file parsing utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseIniFile = parseIniFile;
+/**
+ * Parses INI.TXT file content
+ *
+ * @param content - Raw INI.TXT file content
+ * @returns Parsed data structure
+ */
+function parseIniFile(_content) {
+    // TODO: Implement INI file parsing logic
+    return {};
+}

package/cjs/types/index.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Type definitions for SHAAM uniform format generator
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportOutputSchema = exports.ReportInputSchema = exports.InventoryItemSchema = exports.AccountSchema = exports.JournalEntrySchema = exports.DocumentSchema = exports.BusinessMetadataSchema = void 0;
+const zod_1 = require("zod");
+// Business metadata schema
+exports.BusinessMetadataSchema = zod_1.z.object({
+    businessId: zod_1.z.string().min(1, 'Business ID is required'),
+    name: zod_1.z.string().min(1, 'Business name is required'),
+    taxId: zod_1.z.string().min(1, 'Tax ID is required'),
+    reportingPeriod: zod_1.z.object({
+        startDate: zod_1.z.string().min(1, 'Start date is required'),
+        endDate: zod_1.z.string().min(1, 'End date is required'),
+    }),
+});
+// Document schema
+exports.DocumentSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1, 'Document ID is required'),
+    type: zod_1.z.string().min(1, 'Document type is required'),
+    date: zod_1.z.string().min(1, 'Document date is required'),
+    amount: zod_1.z.number(),
+    description: zod_1.z.string().optional(),
+});
+// Journal entry schema
+exports.JournalEntrySchema = zod_1.z.object({
+    id: zod_1.z.string().min(1, 'Journal entry ID is required'),
+    date: zod_1.z.string().min(1, 'Journal entry date is required'),
+    amount: zod_1.z.number(),
+    accountId: zod_1.z.string().min(1, 'Account ID is required'),
+    description: zod_1.z.string().optional(),
+});
+// Account schema
+exports.AccountSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1, 'Account ID is required'),
+    name: zod_1.z.string().min(1, 'Account name is required'),
+    type: zod_1.z.string().min(1, 'Account type is required'),
+    balance: zod_1.z.number(),
+});
+// Inventory item schema
+exports.InventoryItemSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1, 'Inventory item ID is required'),
+    name: zod_1.z.string().min(1, 'Inventory item name is required'),
+    quantity: zod_1.z.number(),
+    unitPrice: zod_1.z.number(),
+});
+// Main input schema
+exports.ReportInputSchema = zod_1.z.object({
+    business: exports.BusinessMetadataSchema,
+    documents: zod_1.z.array(exports.DocumentSchema),
+    journalEntries: zod_1.z.array(exports.JournalEntrySchema),
+    accounts: zod_1.z.array(exports.AccountSchema),
+    inventory: zod_1.z.array(exports.InventoryItemSchema),
+});
+// Output schema
+exports.ReportOutputSchema = zod_1.z.object({
+    iniText: zod_1.z.string(),
+    dataText: zod_1.z.string(),
+    iniFile: zod_1.z.instanceof(File),
+    dataFile: zod_1.z.instanceof(File),
+    summary: zod_1.z.object({
+        totalRecords: zod_1.z.number(),
+        perType: zod_1.z.record(zod_1.z.string(), zod_1.z.number()),
+        errors: zod_1.z
+            .array(zod_1.z.object({
+            recordType: zod_1.z.string(),
+            recordIndex: zod_1.z.number(),
+            field: zod_1.z.string(),
+            message: zod_1.z.string(),
+        }))
+            .optional(),
+    }),
+});

package/cjs/validation/errors.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Error handling utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShaamFormatError = void 0;
+exports.createValidationError = createValidationError;
+/**
+ * Custom error class for SHAAM format generation errors
+ */
+class ShaamFormatError extends Error {
+    errors;
+    constructor(message, errors = []) {
+        super(message);
+        this.errors = errors;
+        this.name = 'ShaamFormatError';
+    }
+}
+exports.ShaamFormatError = ShaamFormatError;
+/**
+ * Creates a validation error object
+ */
+function createValidationError(recordType, recordIndex, field, message) {
+    return {
+        recordType,
+        recordIndex,
+        field,
+        message,
+    };
+}

package/cjs/validation/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Validation utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./validate-input.js"), exports);
+tslib_1.__exportStar(require("./errors.js"), exports);