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

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

@@ -0,0 +1,188 @@
+/**
+ * File Helper Utilities for SHAAM Uniform Format Generator
+ * Provides utilities for creating and managing File objects
+ */
+/**
+ * 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');
+ * ```
+ */
+export 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
+ * ```
+ */
+export 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
+ * ```
+ */
+export 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');
+ * ```
+ */
+export 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');
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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`);
+ * ```
+ */
+export 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
+ */
+export const 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 || !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/esm/utils/index.js

@@ -0,0 +1,5 @@
+/**
+ * Utility functions for SHAAM uniform format generator
+ */
+export * from './file-helpers.js';
+export * from './key-generator.js';

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

@@ -0,0 +1,65 @@
+/**
+ * Key generator utility for generating unique identifiers
+ * Used for fields 1004, 1103, and 1153 which require randomly generated unique IDs
+ */
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export 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');
+    }
+}
+/**
+ * Default key generator context instance
+ * Use this for most cases to ensure consistency across records
+ */
+export const defaultKeyGenerator = new KeyGeneratorContext();

package/dist/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@accounter/shaam-uniform-format-generator",
+  "version": "0.1.1",
+  "description": "Fully typed application that generates, parses, and validates SHAAM uniform format tax reports (INI.TXT and BKMVDATA.TXT).",
+  "dependencies": {
+    "iconv-lite": "0.6.3",
+    "zod": "3.25.76"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/urigo/accounter-fullstack.git",
+    "directory": "packages/shaam-uniform-format-generator"
+  },
+  "homepage": "https://github.com/urigo/accounter-fullstack/packages/shaam-uniform-format-generator#readme",
+  "keywords": [
+    "shaam",
+    "uniform-format",
+    "accountancy",
+    "accountant",
+    "accounter",
+    "tax-reports",
+    "ini",
+    "bkmvdata"
+  ],
+  "author": "Gil Gardosh <gilgardosh@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": "^20.0.0 || >= 22"
+  },
+  "main": "cjs/index.js",
+  "module": "esm/index.js",
+  "typings": "typings/index.d.ts",
+  "typescript": {
+    "definition": "typings/index.d.ts"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./typings/index.d.cts",
+        "default": "./cjs/index.js"
+      },
+      "import": {
+        "types": "./typings/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "default": {
+        "types": "./typings/index.d.ts",
+        "default": "./esm/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  }
+}

package/dist/typings/api/generate-report-legacy.d.cts

@@ -0,0 +1 @@
+export { generateUniformFormatReport } from './generate-report.cjs';

package/dist/typings/api/generate-report-legacy.d.ts

@@ -0,0 +1 @@
+export { generateUniformFormatReport } from './generate-report.js';

package/dist/typings/constants.d.cts

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

package/dist/typings/constants.d.ts

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

package/dist/typings/generator/format/encoder.d.cts

@@ -0,0 +1,57 @@
+/**
+ * Fixed-width formatting utilities
+ */
+/**
+ * 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 declare function formatField(value: string, width: number, align: 'left' | 'right', padChar?: string): string;
+/**
+ * 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 declare function encodeFixedWidth(value: string | number, width: number, padChar?: string, align?: 'left' | 'right'): string;
+/**
+ * Helper function to format numeric fields with zero padding
+ */
+export declare function formatNumericField(value: string, width: number): string;
+/**
+ * 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 declare function joinFields(fields: string[]): string;
+/**
+ * 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 declare function joinRecords(lines: string[]): string;
+/**
+ * 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 declare function joinLinesWithCRLF(lines: string[]): string;
+/**
+ * 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 declare function assembleFile(records: string[]): string;

package/dist/typings/generator/format/encoder.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Fixed-width formatting utilities
+ */
+/**
+ * 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 declare function formatField(value: string, width: number, align: 'left' | 'right', padChar?: string): string;
+/**
+ * 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 declare function encodeFixedWidth(value: string | number, width: number, padChar?: string, align?: 'left' | 'right'): string;
+/**
+ * Helper function to format numeric fields with zero padding
+ */
+export declare function formatNumericField(value: string, width: number): string;
+/**
+ * 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 declare function joinFields(fields: string[]): string;
+/**
+ * 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 declare function joinRecords(lines: string[]): string;
+/**
+ * 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 declare function joinLinesWithCRLF(lines: string[]): string;
+/**
+ * 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 declare function assembleFile(records: string[]): string;

package/dist/typings/generator/records/a000-sum.d.cts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * A000Sum Record Schema - Record count summary for INI.TXT
+ * Fields 1050-1051 based on SHAAM uniform format specification
+ */
+export declare const A000SumSchema: z.ZodObject<{
+    code: z.ZodString;
+    recordCount: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    recordCount: string;
+}, {
+    code: string;
+    recordCount: string;
+}>;
+/**
+ * A000Sum Input Schema - for user input (no auto-generated fields)
+ */
+export declare const A000SumInputSchema: z.ZodObject<{
+    code: z.ZodString;
+    recordCount: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    recordCount: string;
+}, {
+    code: string;
+    recordCount: string;
+}>;
+export type A000Sum = z.infer<typeof A000SumSchema>;
+export type A000SumInput = z.infer<typeof A000SumInputSchema>;
+/**
+ * Encodes an A000Sum record to fixed-width string format
+ * Total line width: 19 characters + CRLF
+ */
+export declare function encodeA000Sum(input: A000SumInput): string;
+/**
+ * Parses a fixed-width A000Sum record line back to object
+ * Expected line length: 19 characters (excluding CRLF)
+ */
+export declare function parseA000Sum(line: string): A000Sum;

package/dist/typings/generator/records/a000-sum.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * A000Sum Record Schema - Record count summary for INI.TXT
+ * Fields 1050-1051 based on SHAAM uniform format specification
+ */
+export declare const A000SumSchema: z.ZodObject<{
+    code: z.ZodString;
+    recordCount: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    recordCount: string;
+}, {
+    code: string;
+    recordCount: string;
+}>;
+/**
+ * A000Sum Input Schema - for user input (no auto-generated fields)
+ */
+export declare const A000SumInputSchema: z.ZodObject<{
+    code: z.ZodString;
+    recordCount: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    recordCount: string;
+}, {
+    code: string;
+    recordCount: string;
+}>;
+export type A000Sum = z.infer<typeof A000SumSchema>;
+export type A000SumInput = z.infer<typeof A000SumInputSchema>;
+/**
+ * Encodes an A000Sum record to fixed-width string format
+ * Total line width: 19 characters + CRLF
+ */
+export declare function encodeA000Sum(input: A000SumInput): string;
+/**
+ * Parses a fixed-width A000Sum record line back to object
+ * Expected line length: 19 characters (excluding CRLF)
+ */
+export declare function parseA000Sum(line: string): A000Sum;