tally-xml-tdl 1.4.1

package/src/v2/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 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>;
+

package/src/v2/index.js

@@ -0,0 +1,12 @@
+export { xmlToJson } from "./xmlToJson.js";
+export { jsonToXml } from "./jsonToXml.js";
+export {
+    createEnvelope,
+    createCollectionEnvelope,
+    buildCollectionXml
+} from "./envelope.js";
+export {
+    sendToTally,
+    fetchCollection
+} from "./client.js";
+

package/src/v2/jsonToXml.js

@@ -0,0 +1,20 @@
+import { XMLBuilder } from "fast-xml-parser";
+
+/**
+ * Converts a JavaScript Object into 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/v2/xmlToJson.js

@@ -0,0 +1,19 @@
+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/v3/client.js

@@ -0,0 +1,105 @@
+import { xmlToJson } from "./xmlToJson.js";
+import { jsonToXml } from "./jsonToXml.js";
+import { createCollectionEnvelope } from "./envelope.js";
+
+/**
+ * Sends an XML payload to Tally via HTTP POST.
+ * 
+ * @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 res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "text/xml"
+        },
+        body: xml
+    });
+
+    const text = await res.text();
+    return xmlToJson(text);
+};
+
+/**
+ * High-level helper to fetch any Tally collection directly.
+ * 
+ * @param {object} params
+ * @param {string} params.name - Collection name (e.g. 'KeshavGroups')
+ * @param {string} params.type - Tally Object Type (e.g. 'Group', 'Ledger', 'Company')
+ * @param {string|string[]} [params.fields] - Fields to fetch (e.g. ['Name', 'Parent'])
+ * @param {object} [params.filters] - Filters/additional collection properties
+ * @param {object} [params.staticVariables] - Optional static variables
+ * @param {string} [params.url="http://localhost:9000"] - Tally URL
+ * @returns {Promise<object>} Parsed JSON response from Tally
+ */
+export const fetchCollection = async ({
+    name,
+    type,
+    fields,
+    filters,
+    staticVariables,
+    url = "http://localhost:9000"
+} = {}) => {
+    const envelope = createCollectionEnvelope({
+        name,
+        type,
+        fields,
+        filters,
+        staticVariables
+    });
+    const xml = jsonToXml(envelope);
+    return await sendToTally({ xml, url });
+};
+
+/**
+ * Executes a Tally request from a JSON body (either envelope or collection definition).
+ * 
+ * @param {object} body - JSON body (either { ENVELOPE: ... } or { name, type, fields, ... })
+ * @param {object} [options]
+ * @param {boolean} [options.full=false] - If true, returns full ENVELOPE JSON. If false, returns only children of DATA.COLLECTION on success.
+ * @param {string} [options.url="http://localhost:9000"] - Tally URL endpoint
+ * @returns {Promise<object>} Tally response data
+ */
+export const executeBody = async (body, {
+    full = false,
+    url = "http://localhost:9000"
+} = {}) => {
+    let rawRes;
+    if (body.ENVELOPE) {
+        const xml = jsonToXml(body);
+        rawRes = await sendToTally({ xml, url });
+    } else if (body.name && body.type) {
+        rawRes = await fetchCollection({ ...body, url });
+    } else {
+        throw new Error("Unrecognized body format: must contain ENVELOPE or name & type properties");
+    }
+
+    if (full) {
+        return rawRes;
+    }
+
+    const headerStatus = rawRes?.ENVELOPE?.HEADER?.STATUS;
+    if (headerStatus === 0 || headerStatus === "0" || Number(headerStatus) === 0) {
+        throw new Error(`Tally returned error status: ${JSON.stringify(rawRes?.ENVELOPE?.BODY || rawRes)}`);
+    }
+
+    if (rawRes?.ENVELOPE?.BODY?.DATA?.LINEERROR) {
+        throw new Error(`Tally line error: ${JSON.stringify(rawRes?.ENVELOPE?.BODY?.DATA?.LINEERROR)}`);
+    }
+
+
+    const collectionData = rawRes?.ENVELOPE?.BODY?.DATA?.COLLECTION;
+    if (!collectionData) {
+        throw new Error("No DATA.COLLECTION found in Tally response");
+    }
+
+    return collectionData;
+};
+
+

package/src/v3/envelope.js

@@ -0,0 +1,87 @@
+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/v3/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 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>;
+
+

package/src/v3/index.js

@@ -0,0 +1,14 @@
+export { xmlToJson } from "./xmlToJson.js";
+export { jsonToXml } from "./jsonToXml.js";
+export {
+    createEnvelope,
+    createCollectionEnvelope,
+    buildCollectionXml
+} from "./envelope.js";
+export {
+    sendToTally,
+    fetchCollection,
+    executeBody
+} from "./client.js";
+
+

package/src/v3/jsonToXml.js

@@ -0,0 +1,20 @@
+import { XMLBuilder } from "fast-xml-parser";
+
+/**
+ * Converts a JavaScript Object into 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/v3/xmlToJson.js

@@ -0,0 +1,19 @@
+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/company/body.json

@@ -0,0 +1,7 @@
+{
+  "name": "KeshavOpenCompanies",
+  "type": "Company",
+  "fields": [
+    "Name"
+  ]
+}

package/src/v4/company/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/core/execute/executeBody.js

@@ -0,0 +1,48 @@
+import { jsonToXml } from "../request/jsonToXml.js";
+import { createCollectionEnvelope } from "../request/envelope.js";
+import { sendXml } from "../transport/http.js";
+import { xmlToJson } from "../response/xmlToJson.js";
+import { validateResponse } from "../response/validate.js";
+import { extractCollection } from "../response/extract.js";
+
+/**
+ * The Story of a Query:
+ * Act 1 - Request: Build XML payload from body
+ * Act 2 - Transport: Send XML over HTTP to Tally
+ * Act 3 - Response: Parse XML, validate status, and extract collection entities
+ * 
+ * @param {object} body - Query specification (either { ENVELOPE: ... } or { name, type, fields, ... })
+ * @param {object} [options]
+ * @param {boolean} [options.full=false] - If true, returns the raw full ENVELOPE JSON. If false, validates and returns only children of DATA.COLLECTION.
+ * @param {string} [options.url="http://localhost:9000"] - Tally HTTP endpoint URL.
+ * @returns {Promise<object>} Tally data response.
+ */
+export const executeBody = async (body, {
+    full = false,
+    url = "http://localhost:9000"
+} = {}) => {
+    // Act 1: Request (Formulating what to send)
+    let xml;
+    if (body.ENVELOPE) {
+        xml = jsonToXml(body);
+    } else if (body.name && body.type) {
+        const envelope = createCollectionEnvelope(body);
+        xml = jsonToXml(envelope);
+    } else {
+        throw new Error("Unrecognized body format: must contain ENVELOPE or name & type properties");
+    }
+
+    // Act 2: Transport (Sending over the wire)
+    const rawXml = await sendXml({ xml, url });
+
+    // Act 3: Response (Interpreting the answer)
+    const res = xmlToJson(rawXml);
+
+    if (full) {
+        return res;
+    }
+
+    validateResponse(res);
+    return extractCollection(res);
+};
+

package/src/v4/core/execute/executeXml.js

@@ -0,0 +1,13 @@
+// src/v4/core/execute/executeXml.js
+
+import { sendXml } from "../transport/http.js";
+import { xmlToJson } from "../response/xmlToJson.js";
+
+export const executeXml = async (
+    xml,
+    { url = "http://localhost:9000" } = {}
+) => {
+    const rawXml = await sendXml({ xml, url });
+
+    return xmlToJson(rawXml);
+};

package/src/v4/core/execute/fetchCollection.js

@@ -0,0 +1,35 @@
+import { createCollectionEnvelope } from "../request/envelope.js";
+import { jsonToXml } from "../request/jsonToXml.js";
+import { sendToTally } from "../transport/http.js";
+
+/**
+ * High-level helper to fetch any Tally collection directly.
+ * 
+ * @param {object} params
+ * @param {string} params.name - Collection name (e.g. 'KeshavGroups')
+ * @param {string} params.type - Tally Object Type (e.g. 'Group', 'Ledger', 'Company')
+ * @param {string|string[]} [params.fields] - Fields to fetch (e.g. ['Name', 'Parent'])
+ * @param {object} [params.filters] - Filters/additional collection properties
+ * @param {object} [params.staticVariables] - Optional static variables
+ * @param {string} [params.url="http://localhost:9000"] - Tally URL
+ * @returns {Promise<object>} Parsed JSON response from Tally
+ */
+export const fetchCollection = async ({
+    name,
+    type,
+    fields,
+    filters,
+    staticVariables,
+    url = "http://localhost:9000"
+} = {}) => {
+    const envelope = createCollectionEnvelope({
+        name,
+        type,
+        fields,
+        filters,
+        staticVariables
+    });
+    const xml = jsonToXml(envelope);
+    return await sendToTally({ xml, url });
+};
+

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

@@ -0,0 +1,4 @@
+export { executeBody } from "./executeBody.js";
+export { fetchCollection } from "./fetchCollection.js";
+export { executeXml } from "./executeXml.js";
+

package/src/v4/core/index.js

@@ -0,0 +1,31 @@
+// Sub-modules (The Narrative Story)
+export * as request from "./request/index.js";
+export * as transport from "./transport/index.js";
+export * as response from "./response/index.js";
+export * as execute from "./execute/index.js";
+
+// Direct Core Exports
+export {
+    jsonToXml,
+    createEnvelope,
+    createCollectionEnvelope,
+    buildCollectionXml
+} from "./request/index.js";
+
+export {
+    sendXml,
+    sendToTally
+} from "./transport/index.js";
+
+export {
+    xmlToJson,
+    validateResponse,
+    extractCollection
+} from "./response/index.js";
+
+export {
+    executeBody,
+    fetchCollection,
+    executeXml
+} from "./execute/index.js";
+