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

package/dist/cjs/utils/file-helpers.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * File Helper Utilities for SHAAM Uniform Format Generator
+ * Provides utilities for creating and managing File objects
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileNaming = void 0;
+exports.createFile = createFile;
+exports.createIniFile = createIniFile;
+exports.createDataFile = createDataFile;
+exports.createShaamFiles = createShaamFiles;
+exports.validateShaamFile = validateShaamFile;
+exports.readFileAsText = readFileAsText;
+exports.getFileInfo = getFileInfo;
+/**
+ * Creates a File object with the given text content and filename
+ * This is a utility function to standardize File creation across the package
+ *
+ * @param text - The text content for the file
+ * @param name - The filename (should include extension)
+ * @param options - Optional File constructor options
+ * @returns A File object containing the text content
+ *
+ * @example
+ * ```typescript
+ * const iniFile = createFile(iniText, 'report.INI.TXT');
+ * const dataFile = createFile(dataText, 'report.BKMVDATA.TXT');
+ * ```
+ */
+function createFile(text, name, options = { type: 'text/plain' }) {
+    if (!text || typeof text !== 'string') {
+        throw new Error('Text content must be a non-empty string');
+    }
+    if (!name || typeof name !== 'string') {
+        throw new Error('Filename must be a non-empty string');
+    }
+    // Ensure we have proper line endings for SHAAM format
+    const normalizedText = text.replace(/\r?\n/g, '\r\n');
+    return new File([normalizedText], name, {
+        type: 'text/plain',
+        ...options,
+    });
+}
+/**
+ * Creates an INI.TXT File object with standardized naming
+ *
+ * @param iniText - The INI text content
+ * @param baseFileName - Base filename (without extension)
+ * @returns A File object for the INI file
+ *
+ * @example
+ * ```typescript
+ * const iniFile = createIniFile(iniText, 'my-report');
+ * // Creates file named: my-report.INI.TXT
+ * ```
+ */
+function createIniFile(iniText, baseFileName = 'report') {
+    const fileName = `${baseFileName}.INI.TXT`;
+    return createFile(iniText, fileName);
+}
+/**
+ * Creates a BKMVDATA.TXT File object with standardized naming
+ *
+ * @param dataText - The data text content
+ * @param baseFileName - Base filename (without extension)
+ * @returns A File object for the data file
+ *
+ * @example
+ * ```typescript
+ * const dataFile = createDataFile(dataText, 'my-report');
+ * // Creates file named: my-report.BKMVDATA.TXT
+ * ```
+ */
+function createDataFile(dataText, baseFileName = 'report') {
+    const fileName = `${baseFileName}.BKMVDATA.TXT`;
+    return createFile(dataText, fileName);
+}
+/**
+ * Creates both INI and Data File objects from the report output
+ *
+ * @param iniText - The INI text content
+ * @param dataText - The data text content
+ * @param baseFileName - Base filename (without extension)
+ * @returns An object containing both File objects
+ *
+ * @example
+ * ```typescript
+ * const { iniFile, dataFile } = createShaamFiles(iniText, dataText, 'my-report');
+ * ```
+ */
+function createShaamFiles(iniText, dataText, baseFileName = 'report') {
+    return {
+        iniFile: createIniFile(iniText, baseFileName),
+        dataFile: createDataFile(dataText, baseFileName),
+    };
+}
+/**
+ * Validates that a File object appears to be a valid SHAAM format file
+ *
+ * @param file - The File object to validate
+ * @param expectedType - Expected file type ('ini' | 'data')
+ * @returns True if the file appears valid
+ *
+ * @example
+ * ```typescript
+ * const isValidIni = validateShaamFile(iniFile, 'ini');
+ * const isValidData = validateShaamFile(dataFile, 'data');
+ * ```
+ */
+function validateShaamFile(file, expectedType) {
+    if (!file || !(file instanceof File)) {
+        return false;
+    }
+    // Check filename convention
+    const expectedExtension = expectedType === 'ini' ? '.INI.TXT' : '.BKMVDATA.TXT';
+    if (!file.name.toUpperCase().endsWith(expectedExtension)) {
+        return false;
+    }
+    // Check MIME type
+    if (file.type !== 'text/plain') {
+        return false;
+    }
+    // Check that file has content
+    if (file.size === 0) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Reads text content from a File object
+ * This is an async utility for reading File objects back to text
+ *
+ * @param file - The File object to read
+ * @returns Promise that resolves to the text content
+ *
+ * @example
+ * ```typescript
+ * const text = await readFileAsText(file);
+ * ```
+ */
+async function readFileAsText(file) {
+    if (!file || !(file instanceof File)) {
+        throw new Error('Input must be a valid File object');
+    }
+    return file.text();
+}
+/**
+ * Gets file information from a File object
+ *
+ * @param file - The File object to inspect
+ * @returns File information object
+ *
+ * @example
+ * ```typescript
+ * const info = getFileInfo(iniFile);
+ * console.log(`File: ${info.name}, Size: ${info.size} bytes`);
+ * ```
+ */
+function getFileInfo(file) {
+    if (!file || !(file instanceof File)) {
+        throw new Error('Input must be a valid File object');
+    }
+    return {
+        name: file.name,
+        size: file.size,
+        type: file.type,
+        lastModified: file.lastModified,
+    };
+}
+/**
+ * File naming utilities for SHAAM format files
+ */
+exports.FileNaming = {
+    /**
+     * Generates a standardized INI filename
+     */
+    iniFileName: (base = 'report') => `${base}.INI.TXT`,
+    /**
+     * Generates a standardized data filename
+     */
+    dataFileName: (base = 'report') => `${base}.BKMVDATA.TXT`,
+    /**
+     * Extracts base filename from a SHAAM file
+     */
+    extractBaseName: (fileName) => {
+        if (!fileName || !exports.FileNaming.isValidShaamFileName(fileName)) {
+            return 'report';
+        }
+        const name = fileName.replace(/\.(INI|BKMVDATA)\.TXT$/i, '');
+        return name || 'report';
+    },
+    /**
+     * Validates filename follows SHAAM conventions
+     */
+    isValidShaamFileName: (fileName) => {
+        return /\.(INI|BKMVDATA)\.TXT$/i.test(fileName);
+    },
+};

package/dist/cjs/utils/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Utility functions for SHAAM uniform format generator
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./file-helpers.js"), exports);
+tslib_1.__exportStar(require("./key-generator.js"), exports);

package/dist/cjs/utils/key-generator.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Key generator utility for generating unique identifiers
+ * Used for fields 1004, 1103, and 1153 which require randomly generated unique IDs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultKeyGenerator = exports.KeyGeneratorContext = void 0;
+exports.generateRandomKey = generateRandomKey;
+exports.generatePrimaryIdentifier = generatePrimaryIdentifier;
+/**
+ * Generates a random numeric string of specified length
+ * @param length - The length of the numeric string to generate (max 15 digits)
+ * @returns A random numeric string padded with leading zeros if necessary
+ */
+function generateRandomKey(length = 15) {
+    if (length <= 0 || length > 15) {
+        throw new Error('Key length must be between 1 and 15 digits');
+    }
+    // Generate a random number with the specified number of digits
+    // For length 15, max value is 999,999,999,999,999 (15 nines)
+    const maxValue = Math.pow(10, length) - 1;
+    const minValue = Math.pow(10, length - 1); // Ensures we always get the full length
+    // Generate random number between minValue and maxValue
+    const randomNum = Math.floor(Math.random() * (maxValue - minValue + 1)) + minValue;
+    // Convert to string and pad with zeros if needed
+    return randomNum.toString().padStart(length, '0');
+}
+/**
+ * Generates a primary identifier for fields 1004, 1103, and 1153
+ * These fields must have the same value across all records in a single file
+ * @returns A 15-digit numeric string
+ */
+function generatePrimaryIdentifier() {
+    return generateRandomKey(15);
+}
+/**
+ * Key generator context to maintain consistent IDs across records
+ * This ensures that fields 1004, 1103, and 1153 use the same value within a single file
+ */
+class KeyGeneratorContext {
+    _primaryIdentifier = null;
+    /**
+     * Gets or generates the primary identifier for this context
+     * Ensures the same ID is used across all records that require it
+     */
+    getPrimaryIdentifier() {
+        this._primaryIdentifier ||= generatePrimaryIdentifier();
+        return this._primaryIdentifier;
+    }
+    /**
+     * Resets the context, generating new IDs for the next file
+     */
+    reset() {
+        this._primaryIdentifier = null;
+    }
+    /**
+     * Sets a specific primary identifier (useful for testing or when you have a specific ID requirement)
+     */
+    setPrimaryIdentifier(id) {
+        if (!/^\d{1,15}$/.test(id)) {
+            throw new Error('Primary identifier must be a numeric string with 1-15 digits');
+        }
+        this._primaryIdentifier = id.padStart(15, '0');
+    }
+}
+exports.KeyGeneratorContext = KeyGeneratorContext;
+/**
+ * Default key generator context instance
+ * Use this for most cases to ensure consistency across records
+ */
+exports.defaultKeyGenerator = new KeyGeneratorContext();

package/dist/esm/api/generate-report-legacy.js

@@ -0,0 +1,2 @@
+// Placeholder for generateReport implementation
+export { generateUniformFormatReport } from './generate-report.js';

package/dist/esm/api/generate-report.js

@@ -0,0 +1,325 @@
+/**
+ * Main API for generating SHAAM uniform format reports
+ */
+import { assembleFile } from '../generator/format/encoder.js';
+import { encodeA000, encodeA000Sum, encodeA100, encodeB100, encodeB110, encodeC100, encodeD110, encodeD120, encodeM100, encodeZ900, } from '../generator/records/index.js';
+import { ShaamFormatError } from '../validation/errors.js';
+import { validateInput } from '../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
+ */
+export function generateUniformFormatReport(input, options = {}) {
+    // Validate input data first
+    const validationMode = options.validationMode || 'fail-fast';
+    const validationErrors = validateInput(input, validationMode);
+    if (validationErrors.length > 0) {
+        if (validationMode === 'fail-fast') {
+            // This should have already thrown, but just in case
+            throw new 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 ShaamFormatError('Input validation failed', validationErrors);
+    }
+    const records = [];
+    const iniRecords = [];
+    const recordCounts = {};
+    let recordNumber = 1;
+    // Helper function to count and add data record
+    const addRecord = (recordType, recordContent) => {
+        records.push(recordContent);
+        recordCounts[recordType] = (recordCounts[recordType] || 0) + 1;
+        recordNumber++;
+    };
+    // Helper function to add INI record
+    const addIniRecord = (recordType, recordContent) => {
+        iniRecords.push(recordContent);
+        recordCounts[recordType] = (recordCounts[recordType] || 0) + 1;
+    };
+    // Generate A000 record for INI.TXT
+    const fileHeaderRecord = {
+        reservedFuture: '',
+        totalRecords: '0', // Will be updated later with actual count
+        vatId: input.business.taxId,
+        softwareRegNumber: '12345678', // TODO: Use actual software registration number
+        softwareName: 'SHAAM Generator',
+        softwareVersion: '1.0.0',
+        vendorVatId: '123456789', // TODO: Use actual vendor VAT ID
+        vendorName: 'Accounter',
+        softwareType: '2', // Multi-year software
+        fileOutputPath: options.fileNameBase || 'report',
+        accountingType: '2', // Double-entry accounting
+        balanceRequired: '1',
+        companyRegId: '',
+        withholdingFileNum: '',
+        reserved1017: '',
+        businessName: input.business.name,
+        businessStreet: '',
+        businessHouseNum: '',
+        businessCity: '',
+        businessZip: '',
+        taxYear: '',
+        startDate: input.business.reportingPeriod.startDate.replace(/-/g, ''),
+        endDate: input.business.reportingPeriod.endDate.replace(/-/g, ''),
+        processStartDate: new Date().toISOString().slice(0, 10).replace(/-/g, ''),
+        processStartTime: new Date().toTimeString().slice(0, 5).replace(':', ''),
+        languageCode: '0', // Hebrew
+        characterEncoding: '1', // ISO-8859-8-i
+        compressionSoftware: '',
+        reserved1031: '',
+        baseCurrency: 'ILS',
+        reserved1033: '',
+        branchInfoFlag: '0', // No branches for now
+        reserved1035: '',
+    };
+    addIniRecord('A000', encodeA000(fileHeaderRecord));
+    // Add A000Sum records for each record type to INI.TXT
+    // Calculate expected counts based on input data
+    const expectedCounts = {
+        A100: 1,
+        C100: input.documents.length,
+        D110: input.documents.length,
+        D120: input.documents.length,
+        B100: input.journalEntries.length,
+        B110: input.accounts.length,
+        M100: input.inventory.length,
+        Z900: 1,
+    };
+    // Add summary records for each record type
+    for (const [recordType, count] of Object.entries(expectedCounts)) {
+        if (count > 0) {
+            const summaryRecord = {
+                code: recordType,
+                recordCount: count.toString(),
+            };
+            addIniRecord('A000Sum', encodeA000Sum(summaryRecord));
+        }
+    }
+    // 1. Business metadata - A100 record
+    const businessMetadata = {
+        recordNumber: recordNumber.toString(),
+        vatId: input.business.taxId,
+        reserved: '',
+    };
+    addRecord('A100', encodeA100(businessMetadata));
+    // TODO: 2. Summaries... (not implemented yet)
+    // 3. For each document in input.documents
+    for (const document of input.documents) {
+        // Document header - C100 record
+        const documentRecord = {
+            code: 'C100',
+            recordNumber: recordNumber.toString(),
+            vatId: input.business.taxId,
+            documentType: document.type,
+            documentId: document.id,
+            documentIssueDate: document.date.replace(/-/g, ''), // Convert YYYY-MM-DD to YYYYMMDD
+            documentIssueTime: '',
+            customerName: '',
+            customerStreet: '',
+            customerHouseNumber: '',
+            customerCity: '',
+            customerPostCode: '',
+            customerCountry: '',
+            customerCountryCode: '',
+            customerPhone: '',
+            customerVatId: '',
+            documentValueDate: '',
+            foreignCurrencyAmount: '',
+            currencyCode: '',
+            amountBeforeDiscount: '',
+            documentDiscount: '',
+            amountAfterDiscountExcludingVat: '',
+            vatAmount: '',
+            amountIncludingVat: document.amount.toFixed(2), // Format as decimal with 2 places
+            withholdingTaxAmount: '',
+            customerKey: '',
+            matchingField: '',
+            cancelledAttribute1: '',
+            cancelledDocument: '',
+            cancelledAttribute2: '',
+            documentDate: '',
+            branchKey: '',
+            cancelledAttribute3: '',
+            actionExecutor: '',
+            lineConnectingField: '',
+            reserved: '',
+        };
+        addRecord('C100', encodeC100(documentRecord));
+        // Document line - D110 record
+        const documentLineRecord = {
+            code: 'D110',
+            recordNumber: recordNumber.toString(),
+            vatId: input.business.taxId,
+            documentType: document.type,
+            documentNumber: document.id,
+            lineNumber: '1',
+            baseDocumentType: '',
+            baseDocumentNumber: '',
+            transactionType: '',
+            internalCatalogCode: '',
+            goodsServiceDescription: document.description || 'Item',
+            manufacturerName: '',
+            serialNumber: '',
+            unitOfMeasureDescription: '',
+            quantity: '1',
+            unitPriceExcludingVat: '',
+            lineDiscount: '',
+            lineTotal: '',
+            vatRatePercent: '',
+            reserved1: '',
+            branchId: '1',
+            reserved2: '',
+            documentDate: document.date.replace(/-/g, ''),
+            headerLinkField: '',
+            baseDocumentBranchId: '',
+            reserved3: '',
+        };
+        addRecord('D110', encodeD110(documentLineRecord));
+        // Payment record - D120 record (if applicable)
+        const paymentRecord = {
+            code: 'D120',
+            recordNumber: recordNumber.toString(),
+            vatId: input.business.taxId,
+            documentType: document.type,
+            documentNumber: document.id,
+            lineNumber: '1',
+            paymentMethod: '1', // Default payment method
+            bankNumber: '',
+            branchNumber: '',
+            accountNumber: '',
+            checkNumber: '',
+            paymentDueDate: '',
+            lineAmount: document.amount.toFixed(2), // Format as decimal with 2 places
+            acquirerCode: '',
+            cardBrand: '',
+            creditTransactionType: '',
+            firstPaymentAmount: '',
+            installmentsCount: '',
+            additionalPaymentAmount: '',
+            reserved1: '',
+            branchId: '1',
+            reserved2: '',
+            documentDate: document.date.replace(/-/g, ''),
+            headerLinkField: '',
+            reserved: '',
+        };
+        addRecord('D120', encodeD120(paymentRecord));
+    }
+    // 4. Journal lines: for each entry and its lines
+    for (const entry of input.journalEntries) {
+        const journalRecord = {
+            code: 'B100',
+            recordNumber: recordNumber.toString(),
+            vatId: input.business.taxId,
+            transactionNumber: entry.id.replace(/\D/g, '') || '1', // Extract only digits, default to '1'
+            transactionLineNumber: '1',
+            batchNumber: '',
+            transactionType: '',
+            referenceDocument: '',
+            referenceDocumentType: '',
+            referenceDocument2: '',
+            referenceDocumentType2: '',
+            details: entry.description || '',
+            date: entry.date.replace(/-/g, ''),
+            valueDate: entry.date.replace(/-/g, ''), // Same as date for simplicity
+            accountKey: entry.accountId,
+            counterAccountKey: '',
+            debitCreditIndicator: (entry.amount >= 0 ? '1' : '2'),
+            currencyCode: '',
+            transactionAmount: Math.abs(entry.amount).toFixed(2), // Format as decimal with 2 places
+            foreignCurrencyAmount: '',
+            quantityField: '',
+            matchingField1: '',
+            matchingField2: '',
+            branchId: '',
+            entryDate: entry.date.replace(/-/g, ''),
+            operatorUsername: '',
+            reserved: '',
+        };
+        addRecord('B100', encodeB100(journalRecord));
+    }
+    // 5. Accounts: B110 records
+    for (const account of input.accounts) {
+        const accountRecord = {
+            code: 'B110',
+            recordNumber: recordNumber.toString(),
+            vatId: input.business.taxId,
+            accountKey: account.id,
+            accountName: account.name,
+            trialBalanceCode: account.type,
+            trialBalanceCodeDescription: account.type,
+            customerSupplierAddressStreet: '',
+            customerSupplierAddressHouseNumber: '',
+            customerSupplierAddressCity: '',
+            customerSupplierAddressZip: '',
+            customerSupplierAddressCountry: '',
+            countryCode: '',
+            parentAccountKey: '',
+            accountOpeningBalance: '0',
+            totalDebits: '0',
+            totalCredits: '0',
+            accountingClassificationCode: '',
+            supplierCustomerTaxId: '',
+            branchId: '',
+            openingBalanceForeignCurrency: '',
+            foreignCurrencyCode: '',
+            reserved: '',
+        };
+        addRecord('B110', encodeB110(accountRecord));
+    }
+    // 6. Inventory: M100 records
+    for (const item of input.inventory) {
+        const inventoryRecord = {
+            code: 'M100',
+            recordNumber: recordNumber.toString(),
+            vatId: input.business.taxId,
+            universalItemCode: '',
+            supplierItemCode: '',
+            internalItemCode: item.id,
+            itemName: item.name,
+            classificationCode: '',
+            classificationDescription: '',
+            unitOfMeasure: '',
+            openingStock: '0',
+            totalStockIn: '0',
+            totalStockOut: item.quantity.toString(),
+            endPeriodCostNonBonded: '',
+            endPeriodCostBonded: '',
+            reserved: '',
+        };
+        addRecord('M100', encodeM100(inventoryRecord));
+    }
+    // 7. Closing record: Z900
+    const closingRecord = {
+        recordNumber: recordNumber.toString(),
+        vatId: input.business.taxId,
+        totalRecords: records.length.toString(), // Count of records before Z900 is added
+        reserved: '',
+    };
+    addRecord('Z900', encodeZ900(closingRecord));
+    // Build iniText and dataText using the assembler
+    const iniText = assembleFile(iniRecords);
+    const dataText = assembleFile(records);
+    // 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: records.length + iniRecords.length,
+            perType: recordCounts,
+        },
+    };
+}

package/dist/esm/constants.js

@@ -0,0 +1,8 @@
+/**
+ * SHAAM format constants
+ */
+/**
+ * SHAAM specification version identifier
+ * Used in fields 1104 (A100) and 1154 (Z900)
+ */
+export const SHAAM_VERSION = '&OF1.31&';

package/dist/esm/generator/format/encoder.js

@@ -0,0 +1,77 @@
+/**
+ * Fixed-width formatting utilities
+ */
+import { CRLF } from '../../format/newline.js';
+import { padLeft, padRight } from '../../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
+ */
+export function formatField(value, width, align, padChar = ' ') {
+    if (align === 'left') {
+        return padRight(value, width, padChar);
+    }
+    return 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
+ */
+export function encodeFixedWidth(value, width, padChar = ' ', align = 'left') {
+    const str = String(value);
+    return formatField(str, width, align, padChar);
+}
+/**
+ * Helper function to format numeric fields with zero padding
+ */
+export function formatNumericField(value, width) {
+    return padLeft(value, width, '0');
+}
+/**
+ * Joins an array of field values into a single record line with CRLF ending
+ * This is used by individual record encoders to create their output
+ *
+ * @param fields - Array of formatted field values
+ * @returns Single record line ending with CRLF
+ */
+export function joinFields(fields) {
+    return fields.join('') + CRLF;
+}
+/**
+ * Joins an array of record lines that already have CRLF endings
+ *
+ * @param lines - Array of record lines to join (each line should already end with CRLF)
+ * @returns Joined string
+ */
+export function joinRecords(lines) {
+    return lines.join('');
+}
+/**
+ * Joins an array of record lines and adds CRLF to each line
+ *
+ * @param lines - Array of record lines to join (without CRLF endings)
+ * @returns Joined string with CRLF line endings
+ */
+export function joinLinesWithCRLF(lines) {
+    return lines.map(line => line + CRLF).join('');
+}
+/**
+ * Creates a complete SHAAM format file by joining records
+ * This is the main function for assembling final file content
+ *
+ * @param records - Array of encoded record strings (each already ending with CRLF)
+ * @returns Complete file content ready for output
+ */
+export function assembleFile(records) {
+    return joinRecords(records);
+}