tally-simple 1.3.1 → 1.8.4

package/docs/execution-pipeline.md

@@ -0,0 +1,158 @@
+# Execution Pipeline
+
+[**View this document as HTML**](./execution-pipeline.html) · [**Documentation Hub**](./index.html)
+
+When a consumer invokes an endpoint like `tally.masters.units.fetch("Mani9")`, the execution engine handles the request through a clean, 4-step pipeline.
+
+---
+
+## The Pipeline Flow
+
+```text
+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
+```
+
+---
+
+## The Four Narrative Steps
+
+Each step is encapsulated in its own focused module under `internal-working/execution/`:
+
+### Step 1: Validate Company Name (`validateCompany.js`)
+
+Verifies that the supplied company name is a non-empty string. Throws early if invalid:
+
+```javascript
+const startFunc = ({ inCompany }) => {
+    const localCompany = inCompany;
+
+    if (typeof localCompany !== "string" || !localCompany.trim()) {
+        throw new TypeError("Company name is required.");
+    }
+
+    return localCompany.trim();
+};
+
+export default startFunc;
+```
+
+---
+
+### Step 2: Direct TDL Lookup (`getTdl.js`)
+
+Instead of crawling or traversing the JSON structure, the endpoint is retrieved in a single line using path reduction:
+
+```javascript
+const startFunc = ({ inSource, inRoutePath }) => {
+    const localSource = inSource;
+    const localRoutePath = inRoutePath;
+
+    const endpoint = localRoutePath
+        .split(".")
+        .reduce((current, key) => current?.[key], localSource);
+
+    return endpoint?.tdl;
+};
+
+export default startFunc;
+```
+
+---
+
+### Step 3: XML Body Construction (`buildXmlBody.js`)
+
+Safely escapes XML special characters (`&`, `<`, `>`, `"`, `'`) in the company name and substitutes `{company}` and `{collectionBody}` into the envelope template:
+
+```javascript
+const startFunc = ({ inCompany, inTdl }) => {
+    const localCompany = inCompany;
+    const localTdl = inTdl;
+
+    return xmlEnvelopeTemplate
+        .replace("{company}", escapeXml(localCompany))
+        .replace("{collectionBody}", localTdl?.collection ?? "");
+};
+
+export default startFunc;
+```
+
+---
+
+### Step 4: HTTP Transport (`postHttp.js`)
+
+Performs a standard `POST` request to `http://localhost:9000` with `Content-Type: text/xml`:
+
+```javascript
+const url = "http://localhost:9000";
+const headers = { "Content-Type": "text/xml" };
+
+const startFunc = async ({ inXmlBody }) => {
+    const localXmlBody = inXmlBody;
+
+    const response = await fetch(url, {
+        method: "POST",
+        headers: headers,
+        body: localXmlBody
+    });
+
+    const responseText = await response.text();
+
+    if (!response.ok) {
+        throw new Error(`Tally request failed with HTTP ${response.status}: ${responseText}`);
+    }
+
+    return responseText;
+};
+
+export default startFunc;
+```
+
+---
+
+### The Coordinator (`index.js`)
+
+The main entry point reads like a 4-line story:
+
+```javascript
+import validateCompany from "./validateCompany.js";
+import getTdl from "./getTdl.js";
+import buildXmlBody from "./buildXmlBody.js";
+import postHttp from "./postHttp.js";
+
+const startFunc = async ({ inRoutePath, inCompany, inSource }) => {
+    const localRoutePath = inRoutePath;
+    const localCompany = inCompany;
+    const localSource = inSource;
+
+    const companyName = validateCompany({ inCompany: localCompany });
+    const tdl = getTdl({ inSource: localSource, inRoutePath: localRoutePath });
+    const xmlBody = buildXmlBody({ inCompany: companyName, inTdl: tdl });
+
+    return await postHttp({ inXmlBody: xmlBody });
+};
+
+export default startFunc;
+```
+
+---
+
+## Architectural Highlights
+
+- **Direct Resolution:** No recursion, no skipping keys, no runtime guessing.
+- **Single Responsibility:** Each file does exactly one job.
+- **Strict Single Export:** Every file exports `export default startFunc;`.

package/docs/index.html

@@ -1,32 +1,294 @@
-<!doctype html>
+<!DOCTYPE html>
 <html lang="en">
 <head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Tally Public API — Documentation</title>
-<style>
-body{font-family:system-ui,-apple-system,Segoe UI,Arial,sans-serif;max-width:760px;margin:60px auto;padding:0 24px;line-height:1.6;color:#222}
-h1{margin-bottom:6px}
-p{color:#666}
-ul{padding-left:20px}
-li{margin:10px 0}
-a{text-decoration:none}
-a:hover{text-decoration:underline}
-small{color:#888}
-</style>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Tally Simple — Documentation Hub</title>
+    <style>
+        :root {
+            --bg: #0f172a;
+            --card-bg: #1e293b;
+            --card-border: #334155;
+            --text-main: #f8fafc;
+            --text-muted: #94a3b8;
+            --accent: #38bdf8;
+            --accent-hover: #7dd3fc;
+            --success: #34d399;
+        }
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+            background-color: var(--bg);
+            color: var(--text-main);
+            line-height: 1.6;
+            padding: 2.5rem 1.5rem;
+        }
+        .container {
+            max-width: 920px;
+            margin: 0 auto;
+        }
+        header {
+            margin-bottom: 2.5rem;
+            border-bottom: 1px solid var(--card-border);
+            padding-bottom: 1.5rem;
+        }
+        .badge-row {
+            display: flex;
+            gap: 0.5rem;
+            margin-bottom: 0.75rem;
+            flex-wrap: wrap;
+        }
+        .badge {
+            font-size: 0.75rem;
+            font-weight: 600;
+            padding: 0.2rem 0.55rem;
+            border-radius: 9999px;
+            background: rgba(56, 189, 248, 0.12);
+            color: var(--accent);
+            border: 1px solid rgba(56, 189, 248, 0.25);
+            text-transform: uppercase;
+            letter-spacing: 0.05em;
+        }
+        .badge-green {
+            background: rgba(52, 211, 153, 0.12);
+            color: var(--success);
+            border-color: rgba(52, 211, 153, 0.25);
+        }
+        h1 {
+            font-size: 2.3rem;
+            font-weight: 800;
+            color: var(--text-main);
+            margin-bottom: 0.5rem;
+            letter-spacing: -0.02em;
+        }
+        .subtitle {
+            font-size: 1.15rem;
+            color: var(--text-muted);
+        }
+        .story-hero {
+            background: var(--card-bg);
+            border: 1px solid var(--card-border);
+            border-radius: 10px;
+            padding: 1.75rem;
+            margin-bottom: 2.5rem;
+            position: relative;
+            overflow: hidden;
+        }
+        .story-hero::before {
+            content: "";
+            position: absolute;
+            top: 0;
+            left: 0;
+            width: 4px;
+            height: 100%;
+            background: var(--accent);
+        }
+        .story-hero h2 {
+            font-size: 1.35rem;
+            color: var(--accent);
+            margin-bottom: 0.5rem;
+        }
+        .story-hero p {
+            color: var(--text-muted);
+            font-size: 1rem;
+            margin-bottom: 1rem;
+        }
+        .story-flow {
+            background: rgba(15, 23, 42, 0.7);
+            border: 1px solid var(--card-border);
+            border-radius: 6px;
+            padding: 1rem;
+            font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+            font-size: 0.88rem;
+            color: #38bdf8;
+            margin: 1rem 0;
+            overflow-x: auto;
+        }
+        .pipeline-diagram {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+            gap: 1rem;
+            margin-top: 1.25rem;
+        }
+        .pipeline-step {
+            background: rgba(15, 23, 42, 0.5);
+            border: 1px solid var(--card-border);
+            border-radius: 6px;
+            padding: 0.85rem;
+        }
+        .pipeline-step .step-num {
+            font-size: 0.75rem;
+            font-weight: 700;
+            color: var(--accent);
+            margin-bottom: 0.2rem;
+        }
+        .pipeline-step h3 {
+            font-size: 0.95rem;
+            margin-bottom: 0.35rem;
+            color: var(--text-main);
+        }
+        .pipeline-step p {
+            font-size: 0.82rem;
+            color: var(--text-muted);
+            margin-bottom: 0;
+        }
+        .grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+            gap: 1.5rem;
+        }
+        .card {
+            background-color: var(--card-bg);
+            border: 1px solid var(--card-border);
+            border-radius: 8px;
+            padding: 1.5rem;
+            display: flex;
+            flex-direction: column;
+            justify-content: space-between;
+            transition: border-color 0.2s, transform 0.2s;
+            text-decoration: none;
+            color: inherit;
+        }
+        .card:hover {
+            border-color: var(--accent);
+            transform: translateY(-2px);
+        }
+        .card h2 {
+            font-size: 1.25rem;
+            color: var(--accent);
+            margin-bottom: 0.5rem;
+        }
+        .card p {
+            color: var(--text-muted);
+            font-size: 0.93rem;
+            margin-bottom: 1rem;
+        }
+        .formats {
+            display: flex;
+            gap: 0.75rem;
+            font-size: 0.85rem;
+        }
+        .format-badge {
+            background: rgba(56, 189, 248, 0.1);
+            color: var(--accent);
+            padding: 0.2rem 0.5rem;
+            border-radius: 4px;
+            font-weight: 600;
+        }
+        footer {
+            margin-top: 3.5rem;
+            text-align: center;
+            color: var(--text-muted);
+            font-size: 0.9rem;
+            border-top: 1px solid var(--card-border);
+            padding-top: 1.5rem;
+        }
+    </style>
 </head>
 <body>
-<h1>Tally Public API</h1>
-<p>Small, JSON-driven Tally query API.</p>
-
-<ul>
-<li><a href="end-user.html">End User</a> — use the package</li>
-<li><a href="developer.html">Application Developer</a> — integrate the package</li>
-<li><a href="repo-developer.html">Repository Developer</a> — maintain the repository</li>
-<li><a href="api.html">API Reference</a> — public API paths</li>
-<li><a href="architecture.html">Architecture</a> — how it works</li>
-</ul>
-
-<p><small><a href="../README.html">README</a> · <a href="../README.md">README.md</a></small></p>
+    <div class="container">
+        <header>
+            <div class="badge-row">
+                <span class="badge">v1.7.2</span>
+                <span class="badge badge-green">Zero Dependencies</span>
+                <span class="badge">Node.js &gt;= 20.10</span>
+                <span class="badge">Raw XML Transport</span>
+            </div>
+            <h1>Tally Simple Documentation Hub</h1>
+            <p class="subtitle">A small, typed JavaScript client and CLI for querying Tally via TDL definitions.</p>
+        </header>
+
+        <section class="story-hero">
+            <h2>The Story of Tally Simple</h2>
+            <p>Querying Tally ERP / Prime directly over HTTP (port 9000) requires complex XML request wrappers and obscure TDL syntax. <code>tally-simple</code> acts as the pure transport engine: choose an endpoint, supply a company name, and receive Tally's exact, raw XML response.</p>
+            <p>Following the UNIX philosophy, responses are kept as raw XML text—making them 100% loss-free, directly pipeable into shell files (<code>> units.xml</code>), and ideal for downstream transformation layers like <code>tally-simple-json</code>.</p>
+            
+            <div class="story-flow">Your App / Shell ───► tally-simple ───► Tally (:9000) ───► Raw XML Response String</div>
+
+            <div class="pipeline-diagram">
+                <div class="pipeline-step">
+                    <div class="step-num">STEP 1</div>
+                    <h3>Validate Company</h3>
+                    <p>Ensures company name is a non-empty string and trims whitespace.</p>
+                </div>
+                <div class="pipeline-step">
+                    <div class="step-num">STEP 2</div>
+                    <h3>Get TDL Query</h3>
+                    <p>O(1) path reduction lookup into <code>source.json</code> to retrieve TDL.</p>
+                </div>
+                <div class="pipeline-step">
+                    <div class="step-num">STEP 3</div>
+                    <h3>Build XML Body</h3>
+                    <p>Escapes XML entities and injects into Tally request envelope.</p>
+                </div>
+                <div class="pipeline-step">
+                    <div class="step-num">STEP 4</div>
+                    <h3>Post HTTP</h3>
+                    <p>POST to <code>localhost:9000</code> and returns raw response body.</p>
+                </div>
+            </div>
+        </section>
+
+        <div class="grid">
+            <a class="card" href="usage.html">
+                <div>
+                    <h2>1. Usage Guide</h2>
+                    <p>How to consume Tally Simple via ESM JavaScript, TypeScript typings, and the command line interface.</p>
+                </div>
+                <div class="formats">
+                    <span class="format-badge">HTML</span>
+                    <span class="format-badge" onclick="event.preventDefault(); window.location.href='usage.md';">Markdown</span>
+                </div>
+            </a>
+
+            <a class="card" href="queries.html">
+                <div>
+                    <h2>2. Available Queries</h2>
+                    <p>Complete directory of supported master endpoints, requested TDL collections, and raw XML returns.</p>
+                </div>
+                <div class="formats">
+                    <span class="format-badge">HTML</span>
+                    <span class="format-badge" onclick="event.preventDefault(); window.location.href='queries.md';">Markdown</span>
+                </div>
+            </a>
+
+            <a class="card" href="architecture.html">
+                <div>
+                    <h2>3. System Architecture</h2>
+                    <p>Clean boundaries between public allowlists, domain-only specifications, and the internal engines.</p>
+                </div>
+                <div class="formats">
+                    <span class="format-badge">HTML</span>
+                    <span class="format-badge" onclick="event.preventDefault(); window.location.href='architecture.md';">Markdown</span>
+                </div>
+            </a>
+
+            <a class="card" href="route-engine.html">
+                <div>
+                    <h2>4. Route Engine</h2>
+                    <p>How the nested, callable object tree is assembled from allowlisted dot-paths without hardcoding.</p>
+                </div>
+                <div class="formats">
+                    <span class="format-badge">HTML</span>
+                    <span class="format-badge" onclick="event.preventDefault(); window.location.href='route-engine.md';">Markdown</span>
+                </div>
+            </a>
+
+            <a class="card" href="execution-pipeline.html">
+                <div>
+                    <h2>5. Execution Pipeline</h2>
+                    <p>The 4-step story: company validation, O(1) TDL lookup, XML body building, and HTTP dispatch.</p>
+                </div>
+                <div class="formats">
+                    <span class="format-badge">HTML</span>
+                    <span class="format-badge" onclick="event.preventDefault(); window.location.href='execution-pipeline.md';">Markdown</span>
+                </div>
+            </a>
+        </div>
+
+        <footer>
+            <p>&copy; KeshavSoft. Distributed under the MIT License.</p>
+        </footer>
+    </div>
 </body>
 </html>

package/docs/queries.html

@@ -0,0 +1,107 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Available Queries — 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="queries.md">View Markdown</a>
+        </nav>
+
+        <h1>Available Queries Reference</h1>
+        <p>This document details the queries available in Tally Simple, the underlying TDL requests generated, and the XML data returned.</p>
+
+        <h2>Master Endpoints Overview</h2>
+        <table>
+            <thead>
+                <tr>
+                    <th>Query Path</th>
+                    <th>Domain Object</th>
+                    <th>TDL Action</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td><code>tally.masters.units.fetch</code></td>
+                    <td>Unit of Measurement</td>
+                    <td><code>fetch</code></td>
+                </tr>
+                <tr>
+                    <td><code>tally.masters.stockItems.withBatches</code></td>
+                    <td>Inventory Stock Item</td>
+                    <td><code>fetch</code></td>
+                </tr>
+                <tr>
+                    <td><code>tally.masters.ledgers.withGstDetails</code></td>
+                    <td>Accounting Ledger</td>
+                    <td><code>fetch</code></td>
+                </tr>
+                <tr>
+                    <td><code>tally.masters.stockGroup.withParent</code></td>
+                    <td>Stock Classification</td>
+                    <td><code>fetch</code></td>
+                </tr>
+            </tbody>
+        </table>
+
+        <h2>1. Units (<code>masters.units.fetch</code>)</h2>
+        <p>Fetches all defined units of measurement in the specified company along with their aliases and names.</p>
+        <pre><code>&lt;TYPE&gt;Unit&lt;/TYPE&gt;
+&lt;FETCH&gt;$$Alias:Name&lt;/FETCH&gt;</code></pre>
+
+        <h2>2. Stock Items with Batches (<code>masters.stockItems.withBatches</code>)</h2>
+        <p>Fetches stock items including their base unit of measure and batch allocation details.</p>
+        <pre><code>&lt;TYPE&gt;StockItem&lt;/TYPE&gt;
+&lt;FETCH&gt;$$Alias:Name&lt;/FETCH&gt;
+&lt;FETCH&gt;BaseUnits&lt;/FETCH&gt;
+&lt;FETCH&gt;BatchAllocations.*&lt;/FETCH&gt;</code></pre>
+
+        <h2>3. Ledgers with GST Details (<code>masters.ledgers.withGstDetails</code>)</h2>
+        <p>Fetches accounting ledgers including their GST registration details list.</p>
+        <pre><code>&lt;TYPE&gt;Ledger&lt;/TYPE&gt;
+&lt;FETCH&gt;$$Alias:Name&lt;/FETCH&gt;
+&lt;FETCH&gt;LEDGSTREGDETAILS.LIST&lt;/FETCH&gt;</code></pre>
+
+        <h2>4. Stock Groups with Parent (<code>masters.stockGroup.withParent</code>)</h2>
+        <p>Fetches stock groups and their parent group hierarchy.</p>
+        <pre><code>&lt;TYPE&gt;StockGroup&lt;/TYPE&gt;
+&lt;FETCH&gt;$$Alias:Name&lt;/FETCH&gt;
+&lt;FETCH&gt;Parent&lt;/FETCH&gt;</code></pre>
+
+        <h2>The Request Envelope</h2>
+        <p>Tally Simple dynamically injects the company name and TDL collection into Tally's standard Export Collection envelope:</p>
+        <pre><code>&lt;ENVELOPE&gt;
+  &lt;HEADER&gt;
+    &lt;VERSION&gt;1&lt;/VERSION&gt;
+    &lt;TALLYREQUEST&gt;Export&lt;/TALLYREQUEST&gt;
+    &lt;TYPE&gt;Collection&lt;/TYPE&gt;
+    &lt;ID&gt;TDLID&lt;/ID&gt;
+  &lt;/HEADER&gt;
+  &lt;BODY&gt;
+    &lt;DESC&gt;
+      &lt;STATICVARIABLES&gt;
+        &lt;SVEXPORTFORMAT&gt;$$SysName:XML&lt;/SVEXPORTFORMAT&gt;
+        &lt;SVCURRENTCOMPANY&gt;{company}&lt;/SVCURRENTCOMPANY&gt;
+      &lt;/STATICVARIABLES&gt;
+      &lt;TDL&gt;
+        &lt;TDLMESSAGE&gt;
+          &lt;COLLECTION NAME="TDLID"&gt;
+            {collectionBody}
+          &lt;/COLLECTION&gt;
+        &lt;/TDLMESSAGE&gt;
+      &lt;/TDL&gt;
+    &lt;/DESC&gt;
+  &lt;/BODY&gt;
+&lt;/ENVELOPE&gt;</code></pre>
+
+        <footer>
+            <p>&copy; KeshavSoft. Distributed under the MIT License.</p>
+        </footer>
+    </div>
+</body>
+</html>