tally-simple 1.3.1 → 1.8.2

package/README.md

@@ -1,127 +1,176 @@
 # 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)](https://github.com/keshavsoft/tally-simple/blob/main/LICENSE)
+[![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)
 
-Tally Simple is a small, typed JavaScript client and CLI for asking Tally for business data.
+**A typed JavaScript client and CLI for querying business data from Tally via TDL definitions.**
 
-Choose a supported query, provide the company name, and receive Tally's response as XML. The same query paths work in an application and from a shell, so a quick experiment can grow into an automated job without changing the request model.
+Query Tally using declarative endpoint paths, supply a company name, and receive Tally's exact, raw XML response.
 
-**[View the package on npm](https://www.npmjs.com/package/tally-simple)** · **[Open the visual guide](docs/index.html)**
+**[Documentation Hub](https://keshavsoft.github.io/tally-simple/)** · **[View on npm](https://www.npmjs.com/package/tally-simple)**
 
-## The story in one minute
+---
 
-Tally Simple sits between your code or shell and a Tally HTTP endpoint:
+## 📖 The Story of Tally Simple
 
-~~~text
-your app / shell command
-          │  choose a public query + company
-          ▼
-       Tally Simple
-          │  builds the XML request
-          ▼
-    Tally HTTP endpoint
-          │
-          ▼
-     XML response text
-~~~
+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.
 
-It deliberately keeps the response raw. You can inspect it, save it, pipe it to another tool, or parse it with the XML library your application already uses.
+### 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.
 
-## Requirements
+### 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.
 
-- Node.js 20.10 or newer
-- A Tally HTTP endpoint that accepts the request, usually http://localhost:9000
+```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
+```
 
-Tally Simple returns Tally's response body as XML text.
+---
 
-## Install
+## ⚡ Quick Start
 
-~~~bash
+### Installation
+
+```bash
 npm install tally-simple
-~~~
+```
+
+*Requires Node.js 20.10+ and a running Tally instance with XML server enabled on `http://localhost:9000`.*
+
+---
 
-The package has no runtime dependencies and requires Node.js 20.10 or newer.
+## 💻 JavaScript Usage (ESM)
 
-## Use it in JavaScript
+Import the default `tally` client and call any query path by passing the company name:
 
-~~~js
+```javascript
 import tally from "tally-simple";
 
-const xml = await tally.masters.units.fetch("Mani9");
-console.log(xml);
-~~~
+// Fetch units of measurement
+const unitsXml = await tally.masters.units.fetch("Mani9");
+console.log(unitsXml);
 
-The default import is a ready-to-use client. For a different endpoint, headers, timeout, or fetch implementation, use `createTallyClient()`:
+// Fetch stock items with batch allocations
+const stockXml = await tally.masters.stockItems.withBatches("Mani9");
 
-~~~js
-import { createTallyClient } from "tally-simple";
+// Fetch ledgers with GST registration details
+const ledgersXml = await tally.masters.ledgers.withGstDetails("Mani9");
 
-const tally = createTallyClient({
-    url: "http://localhost:9000",
-    timeout: 15_000
-});
+// Fetch stock groups with parent hierarchies
+const groupsXml = await tally.masters.stockGroup.withParent("Mani9");
+```
 
-const xml = await tally.masters.ledgers.withGstDetails("Mani9");
-~~~
+Each query returns a `Promise<string>` resolving to Tally's complete raw XML response body.
 
-## Use it from the command line
+---
 
-Run a query with npm's command runner:
+## ⌨️ Command Line Interface (CLI)
 
-~~~bash
+Run any query directly from your terminal using `npx`:
+
+```bash
+# Query units
 npx tally-simple masters.units.fetch --company Mani9
-~~~
 
-You can also include the root name:
+# 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 |
 
-~~~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:
+## 🧠 System Architecture
 
-~~~bash
-npx tally-simple masters.ledgers.withGstDetails --company Mani9 > ledgers.xml
-~~~
+`tally-simple` is built on a clean, declarative 3-layer architecture:
 
-For environment-based use:
+```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) │
+└─────────────────────────────────────────────────────────────┘
+```
 
-~~~bash
-TALLY_COMPANY=Mani9 TALLY_URL=http://localhost:9000 \
-    npx tally-simple masters.units.fetch
-~~~
+### The 4-Step Execution Pipeline
 
-Run npx tally-simple --help to see all CLI options.
+When any query method is called (e.g. `tally.masters.units.fetch("Mani9")`), execution flows through 4 focused steps:
 
-In PowerShell, environment variables use this form:
+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.
 
-~~~powershell
-$env:TALLY_COMPANY = "Mani9"
-$env:TALLY_URL = "http://localhost:9000"
-npx tally-simple masters.units.fetch
-~~~
+---
 
-## Available queries
+## 📚 Documentation Guides
 
-| 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 |
-| masters.stockGroup.withParent | Stock groups and their parent groups |
+Explore the detailed architecture and usage guides:
 
-Every query accepts one company name. Blank company names are rejected before a request is sent. HTTP errors include the status and response body.
+- **[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.
 
-## Choose your next step
+---
 
-- [JavaScript usage](docs/usage.md): configure the client, test without Tally, and use TypeScript.
-- [CLI reference](docs/cli.md): see options, environment variables, piping, and errors.
-- [Available query paths](docs/api.md): see the public API and the TDL each path requests.
-- [Architecture story](docs/architecture.md): see how one definition drives the client and CLI.
-- [Developer guide](docs/development.md): see versioning, declaration generation, and verification.
-- [Visual guide](docs/index.html): a dependency-free HTML walkthrough of the same flow.
+## 📄 License
 
-The source code is on [GitHub](https://github.com/keshavsoft/tally-simple), and the published package is on [npm](https://www.npmjs.com/package/tally-simple).
+MIT © [KeshavSoft](https://github.com/keshavsoft)

package/bin/tally-simple.js

@@ -3,7 +3,7 @@
 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";
+import tally from "../src/index.js";
 
 const usage = [
     "Usage:",
@@ -151,12 +151,7 @@ const run = async (args) => {
         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 endpoint = findEndpoint(parsed.apiPath, tally);
     const response = await endpoint(company);
 
     process.stdout.write(response + "\n");

package/docs/.nojekyll

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

package/docs/architecture.html

@@ -1,74 +1,73 @@
-<!doctype html>
+<!DOCTYPE html>
 <html lang="en">
 <head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-<title>Architecture</title>
-<style>
-body{font-family:system-ui,-apple-system,Segoe UI,Arial,sans-serif;max-width:900px;margin:40px auto;padding:0 24px;line-height:1.65;color:#202124}
-nav{padding:12px 16px;margin-bottom:28px;background:#f5f5f5;border-radius:8px}
-nav a{margin-right:16px;text-decoration:none}
-h1{font-size:30px;margin-top:0}
-h2{font-size:22px;margin-top:32px}
-h3{font-size:18px;margin-top:24px}
-pre{background:#f6f8fa;padding:16px;border-radius:8px;overflow:auto}
-code{background:#f1f3f4;padding:2px 5px;border-radius:4px}
-pre code{background:none;padding:0}
-table{border-collapse:collapse;width:100%;margin:16px 0}
-th,td{border:1px solid #ddd;padding:8px;text-align:left}
-th{background:#f6f6f6}
-a{color:#0969da}
-</style>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>System Architecture — Tally Simple</title>
+    <link rel="stylesheet" href="style.css">
 </head>
 <body>
-<nav>
-<a href="../README.html">README</a>
-<a href="end-user.html">End User</a>
-<a href="developer.html">Application Developer</a>
-<a href="repo-developer.html">Repository Developer</a>
-<a href="api.html">API</a>
-<a href="architecture.html">Architecture</a>
-</nav>
-<h1>Architecture</h1>
-<p>The package is intentionally small.</p>
-<pre><code>Caller
-  │
-  │ public path + company
-  ▼
-external-api
-  │
-  ▼
-traversal
-  │
-  ▼
-source.json
-  │
-  ▼
-request definition
-  │
-  ▼
-Tally HTTP endpoint
-  │
-  ▼
-XML response</code></pre>
-<h2>Two JSON roles</h2>
-<h3><code>source.json</code></h3>
-<p>Internal implementation definition.</p>
-<p>It contains the information required to construct the Tally request.</p>
-<h3><code>external-api/api.json</code></h3>
-<p>Public contract.</p>
-<p>It contains only the paths that should be exposed to consumers.</p>
-<p>This prevents internal request details from becoming the public API automatically.</p>
-<h2>Why JSON</h2>
-<p>Adding a new Tally operation should normally be a definition change:</p>
-<pre><code>add definition
-→ expose path
-→ regenerate declarations
-→ test</code></pre>
-<p>The execution engine remains unchanged.</p>
-<h2>Company</h2>
-<p>Company is runtime data supplied by the caller, not a fixed value in the public API.</p>
-<h2>XML</h2>
-<p>The package creates and sends Tally XML. It does not require the response to be converted to JSON as part of this layer.</p>
+    <div class="container">
+        <nav class="doc-nav">
+            <a href="index.html">&larr; Documentation Hub</a>
+            <a href="architecture.md">View Markdown</a>
+        </nav>
+
+        <h1>System Architecture</h1>
+        <p>Tally Simple is designed with strict boundaries separating the public contract from the internal execution engines.</p>
+
+        <h2>Architectural Overview</h2>
+        <pre><code>┌─────────────────────────────────────────────────────────────┐
+│                 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                                           │
+│   (Injects Specifications into Route &amp; Execution Engines)   │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 3. Internal Working Engines                 │
+│                                                             │
+│   internal-working/route/         internal-working/execution│
+│   (Object Tree Assembly)          (4-Step Request Pipeline) │
+└─────────────────────────────────────────────────────────────┘</code></pre>
+
+        <h2>The Three Layers</h2>
+
+        <h3>1. The Declarative Specifications (<code>src/v7/</code>)</h3>
+        <ul>
+            <li><strong><code>api.json</code> (The Allowlist)</strong>: An explicit array of dot-separated string paths that declare the public API boundary (e.g., <code>["tally.masters.units.fetch", "tally.masters.stockItems.withBatches", ...]</code>).</li>
+            <li><strong><code>source.json</code> (The Tree of Truth)</strong>: A pure domain tree containing the TDL collection queries (<code>&lt;TYPE&gt;Unit&lt;/TYPE&gt;...</code>) and actions. It is completely decoupled from transport and contains no connection settings or HTTP logic.</li>
+        </ul>
+
+        <h3>2. The Public Composition Root (<code>src/v7/index.js</code>)</h3>
+        <ul>
+            <li>Acts as the single entry point for the active version.</li>
+            <li>Imports <code>source.json</code> and <code>api.json</code> and injects them directly into the internal route builder via dependency injection.</li>
+            <li>Exports a single, ready-to-use default client object.</li>
+        </ul>
+
+        <h3>3. The Internal Working Engines (<code>src/v7/internal-working/</code>)</h3>
+        <ul>
+            <li><strong><code>route/</code></strong>: Dynamically builds the nested, callable JavaScript object tree based on <code>api.json</code> without hardcoding methods.</li>
+            <li><strong><code>execution/</code></strong>: Executes the runtime query: validates the company argument, retrieves the TDL query from <code>source.json</code>, constructs the XML request envelope, and dispatches the HTTP POST request to Tally.</li>
+        </ul>
+
+        <h2>Architectural Principles</h2>
+        <ol>
+            <li><strong>Single Source of Truth for Domain Only:</strong> <code>source.json</code> is the authority on <em>what queries exist and what TDL they request</em>, not a dumping ground for server URLs or HTTP headers.</li>
+            <li><strong>Strictly One Export per File:</strong> Every module in the codebase adheres to a single default export (<code>export default startFunc;</code>).</li>
+            <li><strong>Explicit Parameter Unwrapping:</strong> Every function accepts a single object with <code>in</code>-prefixed keys and unwraps them immediately to <code>local</code>-prefixed variables.</li>
+            <li><strong>Zero Runtime Dependencies:</strong> Built entirely on standard Node.js built-ins.</li>
+        </ol>
+    </div>
 </body>
 </html>

package/docs/architecture.md

@@ -1,65 +1,82 @@
-[**View this document as HTML**](./architecture.html)
+# System Architecture
 
-# Architecture
+[**View this document as HTML**](./architecture.html) · [**Documentation Hub**](./index.html)
 
-The package is intentionally small.
+Tally Simple is designed with strict boundaries separating the public contract from the internal execution engines.
 
-```text
-Caller
-  │
-  │ public path + company
-  ▼
-external-api
-  │
-  ▼
-traversal
-  │
-  ▼
-source.json
-  │
-  ▼
-request definition
-  │
-  ▼
-Tally HTTP endpoint
-  │
-  ▼
-XML response
-```
-
-## Two JSON roles
-
-### `source.json`
-
-Internal implementation definition.
-
-It contains the information required to construct the Tally request.
-
-### `external-api/api.json`
-
-Public contract.
+---
 
-It contains only the paths that should be exposed to consumers.
-
-This prevents internal request details from becoming the public API automatically.
-
-## Why JSON
-
-Adding a new Tally operation should normally be a definition change:
+## Architectural Overview
 
 ```text
-add definition
-→ expose path
-→ regenerate declarations
-→ test
+┌─────────────────────────────────────────────────────────────┐
+│                 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                                           │
+│   (Injects Specifications into Route & Execution Engines)   │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 3. Internal Working Engines                 │
+│                                                             │
+│   internal-working/route/         internal-working/execution│
+│   (Object Tree Assembly)          (4-Step Request Pipeline) │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-The execution engine remains unchanged.
-
-## Company
-
-Company is runtime data supplied by the caller, not a fixed value in the public API.
-
-## XML
-
-The package creates and sends Tally XML. It does not require the response to be converted to JSON as part of this layer.
+---
+
+## The Three Layers
+
+### 1. The Declarative Specifications (`src/v7/`)
+- **`api.json` (The Allowlist)**: An explicit array of dot-separated string paths that declare the public API boundary (e.g., `["tally.masters.units.fetch", "tally.masters.stockItems.withBatches", ...]`).
+- **`source.json` (The Tree of Truth)**: A pure domain tree containing the TDL collection queries (`<TYPE>Unit</TYPE>...`) and actions. It is completely decoupled from transport and contains **no** connection settings or HTTP logic.
+
+### 2. The Public Composition Root (`src/v7/index.js`)
+- Acts as the single entry point for the active version.
+- Imports `source.json` and `api.json` and injects them directly into the internal route builder:
+  ```javascript
+  const tally = createRoute({
+      inApiPaths: apiPaths,
+      inSource: source,
+      inExecutor: execute
+  });
+  ```
+- Exports a single, ready-to-use default client object.
+
+### 3. The Internal Working Engines (`src/v7/internal-working/`)
+- **`route/`**: Dynamically builds the nested, callable JavaScript object tree based on `api.json` without hardcoding methods.
+- **`execution/`**: Executes the runtime query: validates the company argument, retrieves the TDL query from `source.json`, constructs the XML request envelope, and dispatches the HTTP POST request to Tally.
+
+---
+
+## Architectural Principles
+
+1. **Single Source of Truth for Domain Only:**
+   `source.json` is the sole authority on *what queries exist and what TDL they request*, not a dumping ground for server URLs or HTTP headers.
+
+2. **Strictly One Export per File:**
+   Every module in the codebase adheres to a single default export (`export default startFunc;`).
+
+3. **Explicit Parameter Unwrapping:**
+   Every function accepts a single object with `in`-prefixed keys and unwraps them immediately to `local`-prefixed variables:
+   ```javascript
+   const startFunc = ({ inRoutePath, inCompany, inSource }) => {
+       const localRoutePath = inRoutePath;
+       const localCompany = inCompany;
+       const localSource = inSource;
+       // ...
+   };
+   ```
+
+4. **Zero Runtime Dependencies:**
+   Built entirely on standard Node.js built-ins. No intermediate proxy frameworks, no third-party HTTP libraries.

package/docs/execution-pipeline.html

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Execution Pipeline — Tally Simple</title>
+    <link rel="stylesheet" href="style.css">
+</head>
+<body>
+    <div class="container">
+        <nav class="doc-nav">
+            <a href="index.html">&larr; Documentation Hub</a>
+            <a href="execution-pipeline.md">View Markdown</a>
+        </nav>
+
+        <h1>Execution Pipeline</h1>
+        <p>When a consumer invokes an endpoint like <code>tally.masters.units.fetch("Mani9")</code>, the execution engine handles the request through a clean, 4-step pipeline.</p>
+
+        <h2>The Pipeline Flow</h2>
+        <pre><code>Invocation: tally.masters.units.fetch("Mani9")
+  │
+  ▼
+Step 1: validateCompany({ inCompany })
+  │  Ensures company is a non-empty string; returns trimmed name
+  ▼
+Step 2: getTdl({ inSource, inRoutePath })
+  │  Direct O(1) path lookup of TDL collection query from source.json
+  ▼
+Step 3: buildXmlBody({ inCompany, inTdl })
+  │  XML-escapes company name and injects into XML envelope template
+  ▼
+Step 4: postHttp({ inXmlBody })
+  │  Sends HTTP POST to Tally (http://localhost:9000) and returns XML text
+  ▼
+Caller receives raw XML string</code></pre>
+
+        <h2>The Four Narrative Steps</h2>
+
+        <h3>Step 1: Validate Company Name (<code>validateCompany.js</code>)</h3>
+        <p>Verifies that the supplied company name is a non-empty string. Throws early if invalid.</p>
+
+        <h3>Step 2: Direct TDL Lookup (<code>getTdl.js</code>)</h3>
+        <p>Instead of crawling or traversing the JSON structure, the endpoint is retrieved in a single line using path reduction.</p>
+
+        <h3>Step 3: XML Body Construction (<code>buildXmlBody.js</code>)</h3>
+        <p>Safely escapes XML special characters in the company name and substitutes <code>{company}</code> and <code>{collectionBody}</code> into the envelope template.</p>
+
+        <h3>Step 4: HTTP Transport (<code>postHttp.js</code>)</h3>
+        <p>Performs a standard <code>POST</code> request to <code>http://localhost:9000</code> with <code>Content-Type: text/xml</code>.</p>
+
+        <h2>The Coordinator (<code>index.js</code>)</h2>
+        <p>The main entry point reads like a 4-line story:</p>
+        <pre><code>const companyName = validateCompany({ inCompany: localCompany });
+const tdl = getTdl({ inSource: localSource, inRoutePath: localRoutePath });
+const xmlBody = buildXmlBody({ inCompany: companyName, inTdl: tdl });
+
+return await postHttp({ inXmlBody: xmlBody });</code></pre>
+
+        <h2>Architectural Highlights</h2>
+        <ul>
+            <li><strong>Direct Resolution:</strong> No recursion, no skipping keys, no runtime guessing.</li>
+            <li><strong>Single Responsibility:</strong> Each file does exactly one job.</li>
+            <li><strong>Strict Single Export:</strong> Every file exports <code>export default startFunc;</code>.</li>
+        </ul>
+
+        <footer>
+            <p>&copy; KeshavSoft. Distributed under the MIT License.</p>
+        </footer>
+    </div>
+</body>
+</html>