tally-xml-tdl 1.4.1

package/src/v4/core/request/envelope.js

@@ -0,0 +1,86 @@
+import { jsonToXml } from "./jsonToXml.js";
+
+/**
+ * Creates a base Tally XML Envelope JavaScript Object.
+ * 
+ * @param {object} [params]
+ * @param {string} [params.id=""] - Collection or Request ID
+ * @param {string} [params.type="COLLECTION"] - Request Type (default "COLLECTION")
+ * @param {object} [params.staticVariables] - Static variables for DESC
+ * @param {object} [params.tdlMessage] - Object to place inside TDLMESSAGE
+ * @returns {object} Tally Envelope JS Object
+ */
+export const createEnvelope = ({
+    id = "",
+    type = "COLLECTION",
+    staticVariables = { SVEXPORTFORMAT: "$$SysName:XML" },
+    tdlMessage = {}
+} = {}) => {
+    return {
+        ENVELOPE: {
+            HEADER: {
+                VERSION: 1,
+                TALLYREQUEST: "EXPORT",
+                TYPE: type,
+                ID: id
+            },
+            BODY: {
+                DESC: {
+                    STATICVARIABLES: staticVariables,
+                    TDL: {
+                        TDLMESSAGE: tdlMessage
+                    }
+                }
+            }
+        }
+    };
+};
+
+/**
+ * Creates a Tally Collection Request Envelope object.
+ * 
+ * @param {object} params
+ * @param {string} params.name - Collection name (used for ID and COLLECTION NAME)
+ * @param {string} params.type - Tally Object Type (e.g. 'Group', 'Ledger', 'Company')
+ * @param {string|string[]} [params.fields] - Field names to FETCH
+ * @param {object} [params.filters] - Additional collection child nodes or filters
+ * @param {object} [params.staticVariables] - Static variables for DESC
+ * @returns {object} Tally Envelope JS Object
+ */
+export const createCollectionEnvelope = ({
+    name,
+    type,
+    fields = [],
+    filters = {},
+    staticVariables = { SVEXPORTFORMAT: "$$SysName:XML" }
+} = {}) => {
+    const fetchValue = Array.isArray(fields)
+        ? fields.join(",\n        ")
+        : (fields || "");
+
+    const collectionDef = {
+        "@_NAME": name,
+        TYPE: type,
+        ...(fetchValue ? { FETCH: fetchValue } : {}),
+        ...filters
+    };
+
+    return createEnvelope({
+        id: name,
+        type: "COLLECTION",
+        staticVariables,
+        tdlMessage: {
+            COLLECTION: collectionDef
+        }
+    });
+};
+
+/**
+ * Helper to build an XML string directly for a collection query.
+ * 
+ * @param {object} options - Options passed to createCollectionEnvelope
+ * @returns {string} XML string ready to send to Tally
+ */
+export const buildCollectionXml = (options) => {
+    return jsonToXml(createCollectionEnvelope(options));
+};

package/src/v4/core/request/index.js

@@ -0,0 +1,6 @@
+export { jsonToXml } from "./jsonToXml.js";
+export {
+    createEnvelope,
+    createCollectionEnvelope,
+    buildCollectionXml
+} from "./envelope.js";

package/src/v4/core/request/jsonToXml.js

@@ -0,0 +1,19 @@
+import { XMLBuilder } from "fast-xml-parser";
+
+/**
+ * Converts a JavaScript Object into a formatted XML string.
+ * Preserves XML attributes prefixed with `@_`.
+ * 
+ * @param {object} jsonObj - The JavaScript object to serialize.
+ * @param {object} [options] - Optional XMLBuilder configurations.
+ * @returns {string} Formatted XML string.
+ */
+export const jsonToXml = (jsonObj, options = {}) => {
+    const builder = new XMLBuilder({
+        ignoreAttributes: false,
+        format: true,
+        ...options
+    });
+
+    return builder.build(jsonObj);
+};

package/src/v4/core/response/extract.js

@@ -0,0 +1,17 @@
+/**
+ * Extracts and unwraps the collection entities from a parsed Tally response object,
+ * stripping away all protocol envelope boilerplate (ENVELOPE, HEADER, DESC, CMPINFO).
+ * 
+ * @param {object} res - Parsed Tally response object.
+ * @returns {object} The children of DATA.COLLECTION (e.g. { VOUCHER: [...] }, { GROUP: [...] }).
+ * @throws {Error} If no DATA.COLLECTION node is found in the response.
+ */
+export const extractCollection = (res) => {
+    const collectionData = res?.ENVELOPE?.BODY?.DATA?.COLLECTION;
+    if (!collectionData) {
+        throw new Error("No DATA.COLLECTION found in Tally response");
+    }
+
+    return collectionData;
+};
+

package/src/v4/core/response/index.js

@@ -0,0 +1,4 @@
+export { xmlToJson } from "./xmlToJson.js";
+export { validateResponse } from "./validate.js";
+export { extractCollection } from "./extract.js";
+

package/src/v4/core/response/validate.js

@@ -0,0 +1,20 @@
+/**
+ * Validates a parsed Tally response object.
+ * Checks for error status (STATUS === 0) and line errors.
+ * 
+ * @param {object} res - Parsed Tally response object.
+ * @returns {object} The validated response object.
+ * @throws {Error} If Tally returned an error status or line error.
+ */
+export const validateResponse = (res) => {
+    const headerStatus = res?.ENVELOPE?.HEADER?.STATUS;
+    if (headerStatus === 0 || headerStatus === "0" || Number(headerStatus) === 0) {
+        throw new Error(`Tally returned error status: ${JSON.stringify(res?.ENVELOPE?.BODY || res)}`);
+    }
+
+    if (res?.ENVELOPE?.BODY?.DATA?.LINEERROR) {
+        throw new Error(`Tally line error: ${JSON.stringify(res?.ENVELOPE?.BODY?.DATA?.LINEERROR)}`);
+    }
+
+    return res;
+};

package/src/v4/core/response/xmlToJson.js

@@ -0,0 +1,18 @@
+import { XMLParser } from "fast-xml-parser";
+
+/**
+ * Converts XML string into a JavaScript Object.
+ * Preserves XML attributes using the `@_` prefix.
+ * 
+ * @param {string} xml - The XML string to parse.
+ * @param {object} [options] - Optional XMLParser configurations.
+ * @returns {object} The parsed JavaScript object.
+ */
+export const xmlToJson = (xml, options = {}) => {
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        ...options
+    });
+
+    return parser.parse(xml);
+};

package/src/v4/core/transport/http.js

@@ -0,0 +1,40 @@
+import { xmlToJson } from "../response/xmlToJson.js";
+
+/**
+ * Sends a raw XML string to Tally via HTTP POST and returns the raw response text.
+ * 
+ * @param {object} params
+ * @param {string} params.xml - The XML payload to send.
+ * @param {string} [params.url="http://localhost:9000"] - Tally HTTP endpoint URL.
+ * @returns {Promise<string>} Raw XML response text from Tally.
+ */
+export const sendXml = async ({
+    xml,
+    url = "http://localhost:9000"
+} = {}) => {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "text/xml"
+        },
+        body: xml
+    });
+
+    return await res.text();
+};
+
+/**
+ * Sends an XML payload to Tally via HTTP POST and parses the response to JSON.
+ * 
+ * @param {object} params
+ * @param {string} params.xml - The XML string to send.
+ * @param {string} [params.url="http://localhost:9000"] - Tally HTTP endpoint URL.
+ * @returns {Promise<object>} Parsed JSON response from Tally.
+ */
+export const sendToTally = async ({
+    xml,
+    url = "http://localhost:9000"
+} = {}) => {
+    const text = await sendXml({ xml, url });
+    return xmlToJson(text);
+};

package/src/v4/core/transport/index.js

@@ -0,0 +1 @@
+export { sendXml, sendToTally } from "./http.js";

package/src/v4/import/index.js

@@ -0,0 +1,7 @@
+import transaction from "./transaction/index.js";
+
+export { transaction };
+
+export default {
+    transaction
+};

package/src/v4/import/transaction/index.js

@@ -0,0 +1,10 @@
+export { default as sales, body as salesBody, get as getSales } from "./sales/index.js";
+export { default as last, body as lastBody, get as getLast } from "./last/index.js";
+
+import sales from "./sales/index.js";
+import last from "./last/index.js";
+
+export default {
+    sales,
+    last
+};

package/src/v4/import/transaction/last/body.xml

@@ -0,0 +1,34 @@
+<ENVELOPE>
+    <HEADER>
+        <VERSION>1</VERSION>
+        <TALLYREQUEST>Export</TALLYREQUEST>
+        <TYPE>Collection</TYPE>
+        <ID>KeshavLastVoucher</ID>
+    </HEADER>
+
+    <BODY>
+        <DESC>
+            <STATICVARIABLES>
+                <SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>
+            </STATICVARIABLES>
+
+            <TDL>
+                <TDLMESSAGE>
+
+                    <COLLECTION NAME="KeshavLastVoucher">
+                        <TYPE>Voucher</TYPE>
+                        <FILTER>LastVoucher</FILTER>
+                        <FETCH>*</FETCH>
+                          <FETCH>AllLedgerEntries.*</FETCH>
+    <FETCH>AllInventoryEntries.*</FETCH>
+                    </COLLECTION>
+
+                    <SYSTEM TYPE="Formulae" NAME="LastVoucher">
+                        $MasterID = 181839
+                    </SYSTEM>
+
+                </TDLMESSAGE>
+            </TDL>
+        </DESC>
+    </BODY>
+</ENVELOPE>

package/src/v4/import/transaction/last/index.js

@@ -0,0 +1,12 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { executeXml } from "../../../core/index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const body = fs.readFileSync(path.join(__dirname, "body.xml"), "utf8");
+
+export const get = (options) => executeXml(body, options);
+get.body = body;
+
+export default get;

package/src/v4/import/transaction/sales/body.xml

@@ -0,0 +1,50 @@
+<ENVELOPE>
+    <HEADER>
+        <TALLYREQUEST>Import Data</TALLYREQUEST>
+    </HEADER>
+
+    <BODY>
+        <IMPORTDATA>
+            <REQUESTDESC>
+                <REPORTNAME>Vouchers</REPORTNAME>
+                <STATICVARIABLES>
+                    <SVCURRENTCOMPANY>Mani9</SVCURRENTCOMPANY>
+                </STATICVARIABLES>
+            </REQUESTDESC>
+
+            <REQUESTDATA>
+                <TALLYMESSAGE xmlns:UDF="TallyUDF">
+
+                    <VOUCHER
+                        VCHTYPE="Sales"
+                        ACTION="Create"
+                        OBJVIEW="Accounting Voucher View">
+
+                        <DATE>20260917</DATE>
+                        <VOUCHERTYPENAME>Sales</VOUCHERTYPENAME>
+
+                        <PARTYLEDGERNAME>Cash</PARTYLEDGERNAME>
+
+                        <ALLLEDGERENTRIES.LIST>
+
+                            <LEDGERNAME>Cash</LEDGERNAME>
+                            <ISDEEMEDPOSITIVE>Yes</ISDEEMEDPOSITIVE>
+                            <AMOUNT>-1000.00</AMOUNT>
+
+                        </ALLLEDGERENTRIES.LIST>
+
+                        <ALLLEDGERENTRIES.LIST>
+
+                            <LEDGERNAME>Sales</LEDGERNAME>
+                            <ISDEEMEDPOSITIVE>No</ISDEEMEDPOSITIVE>
+                            <AMOUNT>1000.00</AMOUNT>
+
+                        </ALLLEDGERENTRIES.LIST>
+
+                    </VOUCHER>
+
+                </TALLYMESSAGE>
+            </REQUESTDATA>
+        </IMPORTDATA>
+    </BODY>
+</ENVELOPE>

package/src/v4/import/transaction/sales/index.js

@@ -0,0 +1,12 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { executeXml } from "../../../core/index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const body = fs.readFileSync(path.join(__dirname, "body.xml"), "utf8");
+
+export const get = (options) => executeXml(body, options);
+get.body = body;
+
+export default get;

package/src/v4/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Converts an XML string into a JavaScript object.
+ * Attributes are prefixed with '@_'.
+ */
+export function xmlToJson<T = any>(xml: string, options?: Record<string, any>): T;
+
+/**
+ * Converts a JavaScript object into a formatted XML string.
+ */
+export function jsonToXml(jsonObj: Record<string, any>, options?: Record<string, any>): string;
+
+export interface CreateEnvelopeOptions {
+    id?: string;
+    type?: string;
+    staticVariables?: Record<string, any>;
+    tdlMessage?: Record<string, any>;
+}
+
+/**
+ * Creates a base Tally XML Envelope JavaScript Object.
+ */
+export function createEnvelope(options?: CreateEnvelopeOptions): Record<string, any>;
+
+export interface CreateCollectionEnvelopeOptions {
+    name: string;
+    type: string;
+    fields?: string | string[];
+    filters?: Record<string, any>;
+    staticVariables?: Record<string, any>;
+}
+
+/**
+ * Creates a Tally Collection Request Envelope object.
+ */
+export function createCollectionEnvelope(options: CreateCollectionEnvelopeOptions): Record<string, any>;
+
+/**
+ * Directly builds a Tally XML string for a collection request.
+ */
+export function buildCollectionXml(options: CreateCollectionEnvelopeOptions): string;
+
+export interface SendXmlOptions {
+    xml: string;
+    url?: string;
+}
+
+/**
+ * Sends a raw XML string to Tally via HTTP POST and returns the raw response text.
+ */
+export function sendXml(options: SendXmlOptions): Promise<string>;
+
+export interface SendToTallyOptions {
+    xml: string;
+    url?: string;
+}
+
+/**
+ * Sends an XML payload to Tally via HTTP POST and returns parsed JSON response.
+ */
+export function sendToTally<T = any>(options: SendToTallyOptions): Promise<T>;
+
+export interface FetchCollectionOptions {
+    name: string;
+    type: string;
+    fields?: string | string[];
+    filters?: Record<string, any>;
+    staticVariables?: Record<string, any>;
+    url?: string;
+}
+
+/**
+ * High-level helper to fetch any Tally collection directly.
+ */
+export function fetchCollection<T = any>(options: FetchCollectionOptions): Promise<T>;
+
+export interface ExecuteBodyOptions {
+    full?: boolean;
+    url?: string;
+}
+
+/**
+ * Executes a Tally request from a JSON body (either envelope or collection definition).
+ * If options.full is false (default), returns only the children of DATA.COLLECTION on success.
+ * If options.full is true, returns the raw full ENVELOPE JSON response.
+ */
+export function executeBody<T = any>(body: Record<string, any>, options?: ExecuteBodyOptions): Promise<T>;
+
+/**
+ * Validates a parsed Tally response object.
+ */
+export function validateResponse<T = any>(res: T): T;
+
+/**
+ * Extracts and unwraps the collection entities from a parsed Tally response object.
+ */
+export function extractCollection<T = any>(res: any): T;
+
+// Story modules
+export * as request from "./core/request/index.js";
+export * as transport from "./core/transport/index.js";
+export * as response from "./core/response/index.js";
+export * as execute from "./core/execute/index.js";
+export * as core from "./core/index.js";
+
+export interface DomainNodeCallable<T = any> {
+    (options?: ExecuteBodyOptions): Promise<T>;
+    body: Record<string, any>;
+}
+
+export namespace masters {
+    namespace accounting {
+        const group: DomainNodeCallable;
+        const voucherTypes: DomainNodeCallable;
+    }
+    namespace inventory {
+        const godown: DomainNodeCallable;
+        const stockCategory: DomainNodeCallable;
+        const uom: DomainNodeCallable;
+    }
+}
+
+export namespace transactions {
+    const purchase: DomainNodeCallable;
+    const purc: DomainNodeCallable;
+    const sale: DomainNodeCallable;
+    const stockJournal: DomainNodeCallable;
+}
+
+export const company: DomainNodeCallable;
+export const trans: typeof transactions;
+export const comp: typeof company;
+

package/src/v4/index.js

@@ -0,0 +1,15 @@
+export * from "./core/index.js";
+export * as core from "./core/index.js";
+
+// Domain Tree (Option B)
+export * as masters from "./masters/index.js";
+export * as transactions from "./transactions/index.js";
+export * as reports from "./reports/index.js";
+export * as importData from "./import/index.js";
+
+export { default as company } from "./company/index.js";
+export * as companyModule from "./company/index.js";
+
+// Shorthand Aliases
+export * as trans from "./transactions/index.js";
+export { default as comp } from "./company/index.js";

package/src/v4/masters/accounting/currency/body.json

@@ -0,0 +1,10 @@
+{
+  "name": "KeshavCurrencies",
+  "type": "Currency",
+  "fields": [
+    "Name",
+    "Symbol",
+    "FormalName",
+    "DecimalPlaces"
+  ]
+}

package/src/v4/masters/accounting/currency/index.js

@@ -0,0 +1,12 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { executeBody } from "../../../core/index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const body = JSON.parse(fs.readFileSync(path.join(__dirname, "body.json"), "utf8"));
+
+export const get = (options) => executeBody(body, options);
+get.body = body;
+
+export default get;

package/src/v4/masters/accounting/group/body.json

@@ -0,0 +1,8 @@
+{
+  "name": "KeshavGroups",
+  "type": "Group",
+  "fields": [
+    "Name",
+    "Parent"
+  ]
+}

package/src/v4/masters/accounting/group/index.js

@@ -0,0 +1,12 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { executeBody } from "../../../core/index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const body = JSON.parse(fs.readFileSync(path.join(__dirname, "body.json"), "utf8"));
+
+export const get = (options) => executeBody(body, options);
+get.body = body;
+
+export default get;

package/src/v4/masters/accounting/index.js

@@ -0,0 +1,16 @@
+export { default as group, body as groupBody, get as getGroup } from "./group/index.js";
+export { default as voucherTypes, body as voucherTypesBody, get as getVoucherTypes } from "./voucherTypes/index.js";
+export { default as ledgers, body as ledgersBody, get as getLedgers } from "./Ledger/index.js";
+export { default as currencies, body as currenciesBody, get as getCurrencies } from "./currency/index.js";
+
+import group from "./group/index.js";
+import voucherTypes from "./voucherTypes/index.js";
+import ledgers from "./Ledger/index.js";
+import currencies from "./currency/index.js";
+
+export default {
+    group,
+    voucherTypes,
+    ledgers,
+    currencies
+};

package/src/v4/masters/accounting/ledger/body.json

@@ -0,0 +1,8 @@
+{
+  "name": "KeshavLedgers",
+  "type": "Ledger",
+  "fields": [
+    "Name",
+    "Parent"
+  ]
+}

package/src/v4/masters/accounting/ledger/index.js

@@ -0,0 +1,12 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { executeBody } from "../../../core/index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const body = JSON.parse(fs.readFileSync(path.join(__dirname, "body.json"), "utf8"));
+
+export const get = (options) => executeBody(body, options);
+get.body = body;
+
+export default get;

package/src/v4/masters/accounting/voucherTypes/body.json

@@ -0,0 +1,11 @@
+{
+  "name": "KeshavVoucherTypes",
+  "type": "VoucherType",
+  "fields": [
+    "Name",
+    "Parent",
+    "IsDeemedPositive",
+    "IsOptional",
+    "IsActive"
+  ]
+}

package/src/v4/masters/accounting/voucherTypes/index.js

@@ -0,0 +1,12 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { executeBody } from "../../../core/index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const body = JSON.parse(fs.readFileSync(path.join(__dirname, "body.json"), "utf8"));
+
+export const get = (options) => executeBody(body, options);
+get.body = body;
+
+export default get;

package/src/v4/masters/index.js

@@ -0,0 +1,10 @@
+export * as accounting from "./accounting/index.js";
+export * as inventory from "./inventory/index.js";
+
+import accounting from "./accounting/index.js";
+import inventory from "./inventory/index.js";
+
+export default {
+    accounting,
+    inventory
+};

package/src/v4/masters/inventory/batch/body.json

@@ -0,0 +1,26 @@
+{
+  "ENVELOPE": {
+    "HEADER": {
+      "VERSION": 1,
+      "TALLYREQUEST": "EXPORT",
+      "TYPE": "COLLECTION",
+      "ID": "KeshavBatches"
+    },
+    "BODY": {
+      "DESC": {
+        "STATICVARIABLES": {
+          "SVEXPORTFORMAT": "$$SysName:XML"
+        },
+        "TDL": {
+          "TDLMESSAGE": {
+            "COLLECTION": {
+              "@_NAME": "KeshavBatches",
+              "TYPE": "StockItem",
+              "FETCH": "Name,Parent,BatchAllocations.*"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/v4/masters/inventory/batch/index.js

@@ -0,0 +1,12 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { executeBody } from "../../../core/index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const body = JSON.parse(fs.readFileSync(path.join(__dirname, "body.json"), "utf8"));
+
+export const get = (options) => executeBody(body, options);
+get.body = body;
+
+export default get;