tally-simple 1.1.1 → 1.8.2

package/CHANGELOG.md

@@ -1,8 +1,8 @@
-# Changelog
-
-## 1.0.0
-
-- Expose the Tally query API as an installable ESM package.
-- Add `createTallyClient()` for endpoint, header, timeout, and fetch configuration.
-- Add the `tally-simple` command for querying a published API path from a shell.
-- Keep the default import as a ready-to-use client for backwards compatibility.
+# Changelog
+
+## 1.0.0
+
+- Expose the Tally query API as an installable ESM package.
+- Add `createTallyClient()` for endpoint, header, timeout, and fetch configuration.
+- Add the `tally-simple` command for querying a published API path from a shell.
+- Keep the default import as a ready-to-use client for backwards compatibility.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 KeshavSoft
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 KeshavSoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,70 +1,176 @@
-# Tally Simple
-
-Tally Simple gives JavaScript applications and shell scripts a straightforward way to ask Tally for business data.
-
-Choose a supported query, provide the company name, and receive the response directly from Tally. The same queries work from an application or from the command line.
-
-## Requirements
-
-- Node.js 20.10 or newer
-- A Tally HTTP endpoint that accepts the request, usually http://localhost:9000
-
-Tally Simple returns Tally's response body as XML text.
-
-## Install
-
-~~~bash
-npm install tally-simple
-~~~
-
-## Use it in JavaScript
-
-~~~js
-import tally from "tally-simple";
-
-const xml = await tally.masters.units.fetch("Mani9");
-console.log(xml);
-~~~
-
-## Use it from the command line
-
-Run a query with npm's command runner:
-
-~~~bash
-npx tally-simple masters.units.fetch --company Mani9
-~~~
-
-You can also include the root name:
-
-~~~bash
-npx tally-simple tally.masters.stockItems.withBatches \
-    --company Mani9 \
-    --url http://localhost:9000
-~~~
-
-The response is written to stdout, so it can be saved or piped:
-
-~~~bash
-npx tally-simple masters.ledgers.withGstDetails --company Mani9 > ledgers.xml
-~~~
-
-For environment-based use:
-
-~~~bash
-TALLY_COMPANY=Mani9 TALLY_URL=http://localhost:9000 \
-    npx tally-simple masters.units.fetch
-~~~
-
-Run npx tally-simple --help to see all CLI options.
-
-## Available queries
-
-| Query | Returns |
-| --- | --- |
-| masters.units.fetch | Units and their aliases |
-| masters.stockItems.withBatches | Stock items, base units, and batch allocations |
-| masters.ledgers.withGstDetails | Ledgers and GST registration details |
-
-Every query accepts one company name. Blank company names are rejected before a request is sent. HTTP errors include the status and response body.
-
-More user-facing details are available in [usage](docs/usage.md), the [CLI reference](docs/cli.md), and the [available query list](docs/api.md).
+# Tally Simple
+
+[![npm version](https://img.shields.io/npm/v/tally-simple.svg)](https://www.npmjs.com/package/tally-simple)
+[![license](https://img.shields.io/npm/l/tally-simple.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20.10-brightgreen.svg)](package.json)
+[![dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](package.json)
+
+**A typed JavaScript client and CLI for querying business data from Tally via TDL definitions.**
+
+Query Tally using declarative endpoint paths, supply a company name, and receive Tally's exact, raw XML response.
+
+**[Documentation Hub](https://keshavsoft.github.io/tally-simple/)** · **[View on npm](https://www.npmjs.com/package/tally-simple)**
+
+---
+
+## 📖 The Story of Tally Simple
+
+Tally ERP and Tally Prime expose an HTTP XML/ODBC interface (defaulting to `http://localhost:9000`), but speaking to it directly is notoriously complex:
+- Requests require heavy, boilerplate `<ENVELOPE>` XML wrappers.
+- Field extraction depends on specific, case-sensitive TDL (Tally Definition Language) collection queries.
+- Developers often end up copy-pasting raw XML string templates throughout their applications.
+
+### The Purpose of `tally-simple`
+`tally-simple` solves this by serving as the **pure transport and query execution engine** for Tally:
+1. It encapsulates complex TDL collection definitions declaratively inside the library.
+2. It provides an intuitive, autocomplete-friendly JavaScript API and matching CLI commands.
+3. It deliberately returns **pure raw XML strings** from Tally.
+
+### Why Raw XML?
+Keeping the response as raw XML follows the **UNIX philosophy**:
+- **Zero Loss**: No information or attributes are lost or warped by premature JSON conversion.
+- **Pipeable & Inspectable**: Output can be redirected directly to files (`> units.xml`) or formatted with standard XML tools (`| xmllint`).
+- **Downstream Decoupling**: Downstream layers (such as `tally-simple-json` or custom parsers) can parse and shape the XML as needed, without coupling transport to data formatting.
+
+```mermaid
+flowchart LR
+    A[Your App or CLI] -->|Path + Company Name| B[tally-simple<br/>Transport & TDL Engine]
+    B -->|TDL XML Request Envelope| C[Tally ERP / Prime<br/>http://localhost:9000]
+    C -->|Raw XML Response| B
+    B -->|Raw XML String| A
+```
+
+---
+
+## ⚡ Quick Start
+
+### Installation
+
+```bash
+npm install tally-simple
+```
+
+*Requires Node.js 20.10+ and a running Tally instance with XML server enabled on `http://localhost:9000`.*
+
+---
+
+## 💻 JavaScript Usage (ESM)
+
+Import the default `tally` client and call any query path by passing the company name:
+
+```javascript
+import tally from "tally-simple";
+
+// Fetch units of measurement
+const unitsXml = await tally.masters.units.fetch("Mani9");
+console.log(unitsXml);
+
+// Fetch stock items with batch allocations
+const stockXml = await tally.masters.stockItems.withBatches("Mani9");
+
+// Fetch ledgers with GST registration details
+const ledgersXml = await tally.masters.ledgers.withGstDetails("Mani9");
+
+// Fetch stock groups with parent hierarchies
+const groupsXml = await tally.masters.stockGroup.withParent("Mani9");
+```
+
+Each query returns a `Promise<string>` resolving to Tally's complete raw XML response body.
+
+---
+
+## ⌨️ Command Line Interface (CLI)
+
+Run any query directly from your terminal using `npx`:
+
+```bash
+# Query units
+npx tally-simple masters.units.fetch --company Mani9
+
+# Or include the 'tally.' root prefix
+npx tally-simple tally.masters.stockItems.withBatches --company Mani9
+```
+
+### Piping and Saving Output
+
+Because the response is written directly to `stdout`, you can seamlessly pipe or save the raw XML:
+
+```bash
+# Save to file
+npx tally-simple masters.units.fetch --company Mani9 > units.xml
+
+# Format output using xmllint
+npx tally-simple masters.ledgers.withGstDetails --company Mani9 | xmllint --format -
+```
+
+---
+
+## 📋 Available Queries
+
+All queries target master records and return Tally's native export collection XML:
+
+| Query Path | Target Domain | TDL Collection Query | What it returns |
+| :--- | :--- | :--- | :--- |
+| `masters.units.fetch` | Unit | `<TYPE>Unit</TYPE><FETCH>$$Alias:Name</FETCH>` | Units of measurement and aliases |
+| `masters.stockItems.withBatches` | StockItem | `<TYPE>StockItem</TYPE><FETCH>BaseUnits</FETCH><FETCH>BatchAllocations.*</FETCH>` | Stock items, base units, and batch allocations |
+| `masters.ledgers.withGstDetails` | Ledger | `<TYPE>Ledger</TYPE><FETCH>LEDGSTREGDETAILS.LIST</FETCH>` | Accounting ledgers and GST details |
+| `masters.stockGroup.withParent` | StockGroup | `<TYPE>StockGroup</TYPE><FETCH>Parent</FETCH>` | Stock groups and parent hierarchy |
+
+---
+
+## 🧠 System Architecture
+
+`tally-simple` is built on a clean, declarative 3-layer architecture:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                   1. Declarative Specifications             │
+│                                                             │
+│   src/v7/api.json                 src/v7/source.json        │
+│   (Public Route Allowlist)        (TDL Definition Tree)     │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   2. Public Composition Root                │
+│                                                             │
+│   src/v7/index.js                                           │
+│   (Binds Specifications to Engines via Dependency Injection)│
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   3. Internal Working Engines               │
+│                                                             │
+│   internal-working/route/         internal-working/execution│
+│   (Builds Callable Object Tree)   (4-Step Request Pipeline) │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### The 4-Step Execution Pipeline
+
+When any query method is called (e.g. `tally.masters.units.fetch("Mani9")`), execution flows through 4 focused steps:
+
+1. **`validateCompany`**: Ensures the company name is a non-empty string and trims whitespace.
+2. **`getTdl`**: Fast $O(1)$ reduction lookup into `source.json` to extract the corresponding TDL definition.
+3. **`buildXmlBody`**: Safely escapes XML special characters and injects the company and TDL into the `<ENVELOPE>` request template.
+4. **`postHttp`**: Sends an HTTP POST request to `http://localhost:9000` with `Content-Type: text/xml` and returns the raw response body.
+
+---
+
+## 📚 Documentation Guides
+
+Explore the detailed architecture and usage guides:
+
+- **[Documentation Hub](https://keshavsoft.github.io/tally-simple/)**: The interactive documentation portal.
+- **[System Architecture](docs/architecture.md)**: Deep dive into the declarative design and layers.
+- **[Execution Pipeline](docs/execution-pipeline.md)**: Step-by-step walkthrough of the 4-stage request flow.
+- **[Route Assembly Engine](docs/route-engine.md)**: How the callable JavaScript tree is synthesized from `api.json`.
+- **[Available Queries Reference](docs/queries.md)**: Complete TDL definitions and XML structures.
+- **[Usage Guide](docs/usage.md)**: Advanced options, CLI piping, and TypeScript integration.
+
+---
+
+## 📄 License
+
+MIT © [KeshavSoft](https://github.com/keshavsoft)

package/bin/tally-simple.js

@@ -1,175 +1,170 @@
-#!/usr/bin/env node
-
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import packageInfo from "../package.json" with { type: "json" };
-import tally, { createTallyClient } from "../src/index.js";
-
-const usage = [
-    "Usage:",
-    "  tally-simple <api-path> --company <company> [options]",
-    "",
-    "Examples:",
-    "  tally-simple masters.units.fetch --company Mani9",
-    "  tally-simple tally.masters.ledgers.withGstDetails --company Mani9 --url http://localhost:9000",
-    "",
-    "Options:",
-    "  -c, --company <name>   Tally company name (or TALLY_COMPANY)",
-    "  -u, --url <url>        Tally HTTP endpoint (or TALLY_URL)",
-    "      --header <k:v>     Add a request header; may be repeated",
-    "      --timeout <ms>     Abort a request after the given number of milliseconds",
-    "  -h, --help             Show this help",
-    "  -v, --version          Show the package version",
-    "",
-    "The API path is one of the paths listed in docs/api.md. The response is written",
-    "to stdout exactly as Tally returns it, so it can be piped to another command.",
-    ""
-].join("\n");
-
-const readValue = (args, index, option) => {
-    const value = args[index + 1];
-
-    if (!value || value.startsWith("-")) {
-        throw new Error(option + " requires a value.");
-    }
-
-    return value;
-};
-
-const parseHeader = (value) => {
-    const separator = value.indexOf(":");
-
-    if (separator < 1) {
-        throw new Error("Invalid header \"" + value + "\". Use the form name:value.");
-    }
-
-    return [
-        value.slice(0, separator).trim(),
-        value.slice(separator + 1).trim()
-    ];
-};
-
-const parseArgs = (args) => {
-    const options = { headers: {} };
-    let apiPath;
-
-    for (let index = 0; index < args.length; index += 1) {
-        const argument = args[index];
-
-        if (argument === "--help" || argument === "-h") {
-            return { help: true };
-        }
-
-        if (argument === "--version" || argument === "-v") {
-            return { version: true };
-        }
-
-        if (argument === "--company" || argument === "-c") {
-            options.company = readValue(args, index, argument);
-            index += 1;
-            continue;
-        }
-
-        if (argument === "--url" || argument === "-u") {
-            options.url = readValue(args, index, argument);
-            index += 1;
-            continue;
-        }
-
-        if (argument === "--timeout") {
-            const value = readValue(args, index, argument);
-            options.timeout = Number(value);
-
-            if (!Number.isFinite(options.timeout) || options.timeout <= 0) {
-                throw new Error("--timeout must be a positive number of milliseconds.");
-            }
-
-            index += 1;
-            continue;
-        }
-
-        if (argument === "--header") {
-            const [name, value] = parseHeader(readValue(args, index, argument));
-            options.headers[name] = value;
-            index += 1;
-            continue;
-        }
-
-        if (argument.startsWith("-")) {
-            throw new Error("Unknown option: " + argument);
-        }
-
-        if (apiPath) {
-            throw new Error(
-                "Only one API path may be supplied; received \"" + argument + "\" too."
-            );
-        }
-
-        apiPath = argument;
-    }
-
-    return { ...options, apiPath };
-};
-
-const normalizePath = (apiPath) => apiPath.startsWith("tally.")
-    ? apiPath.slice("tally.".length)
-    : apiPath;
-
-const findEndpoint = (apiPath, client = tally) => {
-    const endpoint = normalizePath(apiPath).split(".").reduce(
-        (current, part) => current?.[part],
-        client
-    );
-
-    if (typeof endpoint !== "function") {
-        throw new Error("Unknown API path: " + apiPath);
-    }
-
-    return endpoint;
-};
-
-const run = async (args) => {
-    const parsed = parseArgs(args);
-
-    if (parsed.help) {
-        process.stdout.write(usage);
-        return;
-    }
-
-    if (parsed.version) {
-        process.stdout.write(packageInfo.version + "\n");
-        return;
-    }
-
-    if (!parsed.apiPath) {
-        throw new Error("An API path is required. Use --help to see examples.");
-    }
-
-    const company = parsed.company ?? process.env.TALLY_COMPANY;
-
-    if (!company) {
-        throw new Error("A company is required. Pass --company or set TALLY_COMPANY.");
-    }
-
-    const client = createTallyClient({
-        url: parsed.url ?? process.env.TALLY_URL,
-        headers: parsed.headers,
-        timeout: parsed.timeout
-    });
-    const endpoint = findEndpoint(parsed.apiPath, client);
-    const response = await endpoint(company);
-
-    process.stdout.write(response + "\n");
-};
-
-const isMain = process.argv[1]
-    && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
-
-if (isMain) {
-    run(process.argv.slice(2)).catch((error) => {
-        process.stderr.write("Error: " + error.message + "\n\n" + usage);
-        process.exitCode = 1;
-    });
-}
-
-export { findEndpoint, parseArgs, run };
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import packageInfo from "../package.json" with { type: "json" };
+import tally from "../src/index.js";
+
+const usage = [
+    "Usage:",
+    "  tally-simple <api-path> --company <company> [options]",
+    "",
+    "Examples:",
+    "  tally-simple masters.units.fetch --company Mani9",
+    "  tally-simple tally.masters.ledgers.withGstDetails --company Mani9 --url http://localhost:9000",
+    "",
+    "Options:",
+    "  -c, --company <name>   Tally company name (or TALLY_COMPANY)",
+    "  -u, --url <url>        Tally HTTP endpoint (or TALLY_URL)",
+    "      --header <k:v>     Add a request header; may be repeated",
+    "      --timeout <ms>     Abort a request after the given number of milliseconds",
+    "  -h, --help             Show this help",
+    "  -v, --version          Show the package version",
+    "",
+    "The API path is one of the paths listed in docs/api.md. The response body is",
+    "written to stdout with a trailing newline, so it can be piped to another command.",
+    ""
+].join("\n");
+
+const readValue = (args, index, option) => {
+    const value = args[index + 1];
+
+    if (!value || value.startsWith("-")) {
+        throw new Error(option + " requires a value.");
+    }
+
+    return value;
+};
+
+const parseHeader = (value) => {
+    const separator = value.indexOf(":");
+
+    if (separator < 1) {
+        throw new Error("Invalid header \"" + value + "\". Use the form name:value.");
+    }
+
+    return [
+        value.slice(0, separator).trim(),
+        value.slice(separator + 1).trim()
+    ];
+};
+
+const parseArgs = (args) => {
+    const options = { headers: {} };
+    let apiPath;
+
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+
+        if (argument === "--help" || argument === "-h") {
+            return { help: true };
+        }
+
+        if (argument === "--version" || argument === "-v") {
+            return { version: true };
+        }
+
+        if (argument === "--company" || argument === "-c") {
+            options.company = readValue(args, index, argument);
+            index += 1;
+            continue;
+        }
+
+        if (argument === "--url" || argument === "-u") {
+            options.url = readValue(args, index, argument);
+            index += 1;
+            continue;
+        }
+
+        if (argument === "--timeout") {
+            const value = readValue(args, index, argument);
+            options.timeout = Number(value);
+
+            if (!Number.isFinite(options.timeout) || options.timeout <= 0) {
+                throw new Error("--timeout must be a positive number of milliseconds.");
+            }
+
+            index += 1;
+            continue;
+        }
+
+        if (argument === "--header") {
+            const [name, value] = parseHeader(readValue(args, index, argument));
+            options.headers[name] = value;
+            index += 1;
+            continue;
+        }
+
+        if (argument.startsWith("-")) {
+            throw new Error("Unknown option: " + argument);
+        }
+
+        if (apiPath) {
+            throw new Error(
+                "Only one API path may be supplied; received \"" + argument + "\" too."
+            );
+        }
+
+        apiPath = argument;
+    }
+
+    return { ...options, apiPath };
+};
+
+const normalizePath = (apiPath) => apiPath.startsWith("tally.")
+    ? apiPath.slice("tally.".length)
+    : apiPath;
+
+const findEndpoint = (apiPath, client = tally) => {
+    const endpoint = normalizePath(apiPath).split(".").reduce(
+        (current, part) => current?.[part],
+        client
+    );
+
+    if (typeof endpoint !== "function") {
+        throw new Error("Unknown API path: " + apiPath);
+    }
+
+    return endpoint;
+};
+
+const run = async (args) => {
+    const parsed = parseArgs(args);
+
+    if (parsed.help) {
+        process.stdout.write(usage);
+        return;
+    }
+
+    if (parsed.version) {
+        process.stdout.write(packageInfo.version + "\n");
+        return;
+    }
+
+    if (!parsed.apiPath) {
+        throw new Error("An API path is required. Use --help to see examples.");
+    }
+
+    const company = parsed.company ?? process.env.TALLY_COMPANY;
+
+    if (!company) {
+        throw new Error("A company is required. Pass --company or set TALLY_COMPANY.");
+    }
+
+    const endpoint = findEndpoint(parsed.apiPath, tally);
+    const response = await endpoint(company);
+
+    process.stdout.write(response + "\n");
+};
+
+const isMain = process.argv[1]
+    && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+    run(process.argv.slice(2)).catch((error) => {
+        process.stderr.write("Error: " + error.message + "\n\n" + usage);
+        process.exitCode = 1;
+    });
+}
+
+export { findEndpoint, parseArgs, run };

package/docs/.nojekyll

@@ -0,0 +1 @@
+# disable jekyll