tally-simple 1.3.1 → 1.8.4

package/docs/queries.md

@@ -0,0 +1,122 @@
+# Available Queries Reference
+
+[**View this document as HTML**](./queries.html) · [**Documentation Hub**](./index.html)
+
+This document details the queries available in Tally Simple, the underlying TDL requests generated, and the XML data returned.
+
+---
+
+## Master Endpoints Overview
+
+| Query Path | Domain Object | TDL Action |
+| :--- | :--- | :--- |
+| `tally.masters.units.fetch` | Unit of Measurement | `fetch` |
+| `tally.masters.stockItems.withBatches` | Inventory Stock Item | `fetch` |
+| `tally.masters.ledgers.withGstDetails` | Accounting Ledger | `fetch` |
+| `tally.masters.stockGroup.withParent` | Stock Classification | `fetch` |
+
+---
+
+## 1. Units (`masters.units.fetch`)
+
+Fetches all defined units of measurement in the specified company along with their aliases and names.
+
+### TDL Definition:
+```xml
+<TYPE>Unit</TYPE>
+<FETCH>$$Alias:Name</FETCH>
+```
+
+### Usage:
+```javascript
+const xml = await tally.masters.units.fetch("Mani9");
+```
+
+---
+
+## 2. Stock Items with Batches (`masters.stockItems.withBatches`)
+
+Fetches stock items including their base unit of measure and batch allocation details.
+
+### TDL Definition:
+```xml
+<TYPE>StockItem</TYPE>
+<FETCH>$$Alias:Name</FETCH>
+<FETCH>BaseUnits</FETCH>
+<FETCH>BatchAllocations.*</FETCH>
+```
+
+### Usage:
+```javascript
+const xml = await tally.masters.stockItems.withBatches("Mani9");
+```
+
+---
+
+## 3. Ledgers with GST Details (`masters.ledgers.withGstDetails`)
+
+Fetches accounting ledgers including their GST registration details list.
+
+### TDL Definition:
+```xml
+<TYPE>Ledger</TYPE>
+<FETCH>$$Alias:Name</FETCH>
+<FETCH>LEDGSTREGDETAILS.LIST</FETCH>
+```
+
+### Usage:
+```javascript
+const xml = await tally.masters.ledgers.withGstDetails("Mani9");
+```
+
+---
+
+## 4. Stock Groups with Parent (`masters.stockGroup.withParent`)
+
+Fetches stock groups and their parent group hierarchy.
+
+### TDL Definition:
+```xml
+<TYPE>StockGroup</TYPE>
+<FETCH>$$Alias:Name</FETCH>
+<FETCH>Parent</FETCH>
+```
+
+### Usage:
+```javascript
+const xml = await tally.masters.stockGroup.withParent("Mani9");
+```
+
+---
+
+## The Request Envelope
+
+Every query is wrapped inside Tally's standard Export Collection XML envelope:
+
+```xml
+<ENVELOPE>
+  <HEADER>
+    <VERSION>1</VERSION>
+    <TALLYREQUEST>Export</TALLYREQUEST>
+    <TYPE>Collection</TYPE>
+    <ID>TDLID</ID>
+  </HEADER>
+  <BODY>
+    <DESC>
+      <STATICVARIABLES>
+        <SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>
+        <SVCURRENTCOMPANY>{company}</SVCURRENTCOMPANY>
+      </STATICVARIABLES>
+      <TDL>
+        <TDLMESSAGE>
+          <COLLECTION NAME="TDLID">
+            {collectionBody}
+          </COLLECTION>
+        </TDLMESSAGE>
+      </TDL>
+    </DESC>
+  </BODY>
+</ENVELOPE>
+```
+
+Tally Simple dynamically substitutes `{company}` (XML-escaped) and `{collectionBody}` (the TDL collection query) at runtime.

package/docs/route-engine.html

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Route Assembly Engine — 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="route-engine.md">View Markdown</a>
+        </nav>
+
+        <h1>Route Assembly Engine</h1>
+        <p>The route engine transforms a flat allowlist of string paths (from <code>api.json</code>) into an intuitive, nested, callable JavaScript object tree at initialization.</p>
+
+        <h2>Why Route Assembly?</h2>
+        <p>Consumers expect to call:</p>
+        <pre><code>await tally.masters.units.fetch("Mani9");</code></pre>
+        <p>The route engine builds this tree dynamically from <code>api.json</code> without hardcoding methods.</p>
+
+        <h2>The Three Narrative Modules</h2>
+        <p>Inside <code>internal-working/route/</code>, the responsibility is divided into three small, story-driven files:</p>
+        <pre><code>internal-working/route/
+├── index.js              &lt;-- Coordinator: iterates paths &amp; returns root
+├── attachPath.js         &lt;-- Walks tree branches &amp; mounts leaf
+└── createLeafHandler.js  &lt;-- Factory creating the callable endpoint</code></pre>
+
+        <h2>1. The Leaf Factory (<code>createLeafHandler.js</code>)</h2>
+        <p>A leaf is the terminal callable function at the end of a route. When the user executes <code>fetch("Mani9")</code>, the leaf handler captures the bound route path and delegates execution to the executor.</p>
+
+        <h2>2. Path Attacher (<code>attachPath.js</code>)</h2>
+        <p>To attach a path like <code>"tally.masters.units.fetch"</code>:</p>
+        <ol>
+            <li>Split the path into branch segments (<code>["tally", "masters", "units"]</code>) and a leaf name (<code>"fetch"</code>).</li>
+            <li>Walk through the branch segments, creating intermediate objects if they don't yet exist.</li>
+            <li>Attach the callable leaf handler at the target position.</li>
+        </ol>
+
+        <h2>3. Route Coordinator (<code>index.js</code>)</h2>
+        <p>The entry coordinator iterates each path in <code>inApiPaths</code>, mounts it into the tree using <code>attachPath</code>, and returns the root namespace.</p>
+
+        <h2>Benefits of this Design</h2>
+        <ul>
+            <li><strong>Predictable:</strong> Built once at module load time. Zero runtime overhead during queries.</li>
+            <li><strong>Narrative-Driven:</strong> Every file is under 40 lines and has a single, obvious purpose.</li>
+            <li><strong>Strictly One Export:</strong> Every file uses <code>export default startFunc;</code>.</li>
+        </ul>
+
+        <footer>
+            <p>&copy; KeshavSoft. Distributed under the MIT License.</p>
+        </footer>
+    </div>
+</body>
+</html>

package/docs/route-engine.md

@@ -0,0 +1,141 @@
+# Route Assembly Engine
+
+[**View this document as HTML**](./route-engine.html) · [**Documentation Hub**](./index.html)
+
+The route engine transforms a flat allowlist of string paths (from `api.json`) into an intuitive, nested, callable JavaScript object tree at initialization.
+
+---
+
+## Why Route Assembly?
+
+Consumers expect to call:
+
+```javascript
+await tally.masters.units.fetch("Mani9");
+```
+
+Rather than manual string dispatch:
+
+```javascript
+// Not this:
+await execute("tally.masters.units.fetch", "Mani9");
+```
+
+The route engine builds this tree dynamically from `api.json` without hardcoding methods.
+
+---
+
+## The Three Narrative Modules
+
+Inside `internal-working/route/`, the responsibility is divided into three small, story-driven files:
+
+```text
+internal-working/route/
+├── index.js              <-- Coordinator: iterates paths & returns root
+├── attachPath.js         <-- Walks tree branches & mounts leaf
+└── createLeafHandler.js  <-- Factory creating the callable endpoint
+```
+
+---
+
+### 1. The Leaf Factory (`createLeafHandler.js`)
+
+A leaf is the terminal callable function at the end of a route. When the user executes `fetch("Mani9")`, the leaf handler captures the bound route path and delegates execution to the executor:
+
+```javascript
+const startFunc = ({ inPath, inSource, inExecutor }) => {
+    const localPath = inPath;
+    const localSource = inSource;
+    const localExecutor = inExecutor;
+
+    return async (inCompany) => {
+        const localCompany = inCompany;
+
+        return await localExecutor({
+            inRoutePath: localPath,
+            inCompany: localCompany,
+            inSource: localSource
+        });
+    };
+};
+
+export default startFunc;
+```
+
+---
+
+### 2. Path Attacher (`attachPath.js`)
+
+To attach a path like `"tally.masters.units.fetch"`:
+1. Split the path into branch segments (`["tally", "masters", "units"]`) and a leaf name (`"fetch"`).
+2. Walk through the branch segments, creating intermediate objects if they don't yet exist.
+3. Attach the callable leaf handler at the target position.
+
+```javascript
+import createLeafHandler from "./createLeafHandler.js";
+
+const startFunc = ({ inTree, inPath, inSource, inExecutor }) => {
+    const localTree = inTree;
+    const localPath = inPath;
+    const localSource = inSource;
+    const localExecutor = inExecutor;
+
+    const parts = localPath.split(".");
+    const leafName = parts.pop();
+
+    let branch = localTree;
+    for (const segment of parts) {
+        branch[segment] ??= {};
+        branch = branch[segment];
+    }
+
+    branch[leafName] = createLeafHandler({
+        inPath: localPath,
+        inSource: localSource,
+        inExecutor: localExecutor
+    });
+};
+
+export default startFunc;
+```
+
+---
+
+### 3. Route Coordinator (`index.js`)
+
+The entry coordinator iterates each path in `inApiPaths`, mounts it into the tree using `attachPath`, and returns the root namespace:
+
+```javascript
+import attachPath from "./attachPath.js";
+
+const startFunc = ({ inApiPaths, inSource, inExecutor }) => {
+    const localApiPaths = inApiPaths;
+    const localSource = inSource;
+    const localExecutor = inExecutor;
+
+    const tree = {};
+
+    for (const path of localApiPaths) {
+        attachPath({
+            inTree: tree,
+            inPath: path,
+            inSource: localSource,
+            inExecutor: localExecutor
+        });
+    }
+
+    const rootNamespace = localApiPaths[0]?.split(".")[0];
+
+    return rootNamespace ? tree[rootNamespace] : tree;
+};
+
+export default startFunc;
+```
+
+---
+
+## Benefits of this Design
+
+- **Predictable:** Built once at module load time. Zero runtime overhead during queries.
+- **Narrative-Driven:** Every file is under 40 lines and has a single, obvious purpose.
+- **Strictly One Export:** Every file uses `export default startFunc;`.

package/docs/style.css

@@ -0,0 +1,137 @@
+:root {
+    --bg: #0f172a;
+    --panel-bg: #1e293b;
+    --border: #334155;
+    --text-main: #f8fafc;
+    --text-muted: #94a3b8;
+    --accent: #38bdf8;
+    --code-bg: #0b1120;
+    --inline-code-bg: #334155;
+}
+
+* { 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.65;
+    padding: 2.5rem 1.5rem;
+}
+
+.container {
+    max-width: 820px;
+    margin: 0 auto;
+}
+
+nav.doc-nav {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    border-bottom: 1px solid var(--border);
+    padding-bottom: 1rem;
+    margin-bottom: 2.5rem;
+    font-size: 0.9rem;
+}
+
+nav.doc-nav a {
+    color: var(--accent);
+    text-decoration: none;
+    font-weight: 500;
+}
+
+nav.doc-nav a:hover {
+    text-decoration: underline;
+}
+
+h1 {
+    font-size: 2.2rem;
+    color: var(--text-main);
+    margin-bottom: 1rem;
+    line-height: 1.25;
+}
+
+h2 {
+    font-size: 1.5rem;
+    color: var(--accent);
+    margin-top: 2rem;
+    margin-bottom: 0.75rem;
+    border-bottom: 1px solid var(--border);
+    padding-bottom: 0.35rem;
+}
+
+h3 {
+    font-size: 1.2rem;
+    color: #cbd5e1;
+    margin-top: 1.5rem;
+    margin-bottom: 0.5rem;
+}
+
+p, ul, ol {
+    margin-bottom: 1.2rem;
+    color: #e2e8f0;
+}
+
+ul, ol {
+    padding-left: 1.75rem;
+}
+
+li {
+    margin-bottom: 0.4rem;
+}
+
+code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+    font-size: 0.88em;
+    background-color: var(--inline-code-bg);
+    color: #f1f5f9;
+    padding: 0.15rem 0.35rem;
+    border-radius: 4px;
+}
+
+pre {
+    background-color: var(--code-bg);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    padding: 1.2rem;
+    overflow-x: auto;
+    margin-bottom: 1.5rem;
+}
+
+pre code {
+    background: transparent;
+    padding: 0;
+    font-size: 0.92rem;
+    color: #f8fafc;
+}
+
+table {
+    width: 100%;
+    border-collapse: collapse;
+    margin-bottom: 1.5rem;
+}
+
+th, td {
+    padding: 0.75rem 1rem;
+    text-align: left;
+    border: 1px solid var(--border);
+}
+
+th {
+    background-color: var(--panel-bg);
+    color: var(--accent);
+    font-weight: 600;
+}
+
+tr:nth-child(even) {
+    background-color: rgba(30, 41, 59, 0.5);
+}
+
+footer {
+    margin-top: 3rem;
+    border-top: 1px solid var(--border);
+    padding-top: 1.5rem;
+    color: var(--text-muted);
+    font-size: 0.85rem;
+    text-align: center;
+}

package/docs/usage.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Usage Guide — 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="usage.md">View Markdown</a>
+        </nav>
+
+        <h1>Usage Guide</h1>
+        <p>This guide explains how to consume Tally Simple in JavaScript/TypeScript applications and from the command line.</p>
+
+        <h2>Requirements</h2>
+        <ul>
+            <li><strong>Node.js</strong>: Version 20.10 or newer.</li>
+            <li><strong>Tally</strong>: A running Tally Prime / ERP instance with the ODBC/XML server enabled on <code>http://localhost:9000</code>.</li>
+        </ul>
+
+        <h2>Installation</h2>
+        <pre><code>npm install tally-simple</code></pre>
+        <p>The package contains zero runtime dependencies and ships as an ECMAScript Module (ESM).</p>
+
+        <h2>Using in JavaScript (ESM)</h2>
+        <p>Import the default <code>tally</code> client and call any supported query path with a company name:</p>
+        <pre><code>import tally from "tally-simple";
+
+const unitsXml = await tally.masters.units.fetch("Mani9");
+console.log(unitsXml);</code></pre>
+
+        <h3>Supported Query Paths</h3>
+        <p>The client mirrors the hierarchy exposed in the public API:</p>
+        <pre><code>// Units
+const units = await tally.masters.units.fetch("Mani9");
+
+// Stock items with batch details
+const items = await tally.masters.stockItems.withBatches("Mani9");
+
+// Ledgers with GST registration
+const ledgers = await tally.masters.ledgers.withGstDetails("Mani9");
+
+// Stock groups with parent hierarchy
+const groups = await tally.masters.stockGroup.withParent("Mani9");</code></pre>
+
+        <h2>TypeScript Support</h2>
+        <p>Tally Simple automatically generates TypeScript declarations (<code>src/index.d.ts</code>) directly from the domain specification.</p>
+        <p>You receive full autocomplete and inline documentation in editors like VS Code:</p>
+        <pre><code>import tally from "tally-simple";
+
+// Editor automatically autocompletes:
+// tally.masters.units.fetch
+// tally.masters.stockItems.withBatches
+// tally.masters.ledgers.withGstDetails
+// tally.masters.stockGroup.withParent
+
+const xml: string = await tally.masters.units.fetch("Mani9");</code></pre>
+
+        <h2>Command Line Interface (CLI)</h2>
+        <p>You can run any query path directly from the shell using <code>npx</code>:</p>
+        <pre><code>npx tally-simple masters.units.fetch --company Mani9</code></pre>
+
+        <h3>Saving &amp; Piping Output</h3>
+        <p>The CLI writes Tally's raw XML response directly to <code>stdout</code>, making it easy to pipe to a file or another command:</p>
+        <pre><code>npx tally-simple masters.units.fetch --company Mani9 > units.xml</code></pre>
+
+        <h2>Error Handling</h2>
+        <ul>
+            <li><strong>Company Name Validation:</strong> Passing an empty or non-string company name throws a <code>TypeError</code> before sending a request.</li>
+            <li><strong>HTTP Failures:</strong> If the Tally endpoint returns an HTTP error, an exception is thrown containing the status code and response body.</li>
+        </ul>
+
+        <footer>
+            <p>&copy; KeshavSoft. Distributed under the MIT License.</p>
+        </footer>
+    </div>
+</body>
+</html>

package/docs/usage.md

@@ -0,0 +1,117 @@
+# Usage Guide
+
+[**View this document as HTML**](./usage.html) · [**Documentation Hub**](./index.html)
+
+This guide explains how to consume Tally Simple in JavaScript/TypeScript applications and from the command line.
+
+---
+
+## Requirements
+
+- **Node.js**: Version 20.10 or newer.
+- **Tally**: A running Tally Prime / ERP instance with the ODBC/XML server enabled on `http://localhost:9000`.
+
+---
+
+## Installation
+
+Add Tally Simple to your project:
+
+```bash
+npm install tally-simple
+```
+
+The package contains zero runtime dependencies and ships as an ECMAScript Module (ESM).
+
+---
+
+## Using in JavaScript (ESM)
+
+Import the default `tally` client and call any supported query path with a company name:
+
+```javascript
+import tally from "tally-simple";
+
+const unitsXml = await tally.masters.units.fetch("Mani9");
+console.log(unitsXml);
+```
+
+### Supported Query Paths
+
+The client mirrors the hierarchy exposed in the public API:
+
+```javascript
+// Units
+const units = await tally.masters.units.fetch("Mani9");
+
+// Stock items with batch details
+const items = await tally.masters.stockItems.withBatches("Mani9");
+
+// Ledgers with GST registration
+const ledgers = await tally.masters.ledgers.withGstDetails("Mani9");
+
+// Stock groups with parent hierarchy
+const groups = await tally.masters.stockGroup.withParent("Mani9");
+```
+
+---
+
+## TypeScript Support
+
+Tally Simple automatically generates TypeScript declarations (`src/index.d.ts`) directly from the domain specification.
+
+You receive full autocomplete and inline documentation in editors like VS Code:
+
+```typescript
+import tally from "tally-simple";
+
+// Editor automatically autocompletes:
+// tally.masters.units.fetch
+// tally.masters.stockItems.withBatches
+// tally.masters.ledgers.withGstDetails
+// tally.masters.stockGroup.withParent
+
+const xml: string = await tally.masters.units.fetch("Mani9");
+```
+
+---
+
+## Command Line Interface (CLI)
+
+You can run any query path directly from the shell using `npx`:
+
+```bash
+npx tally-simple masters.units.fetch --company Mani9
+```
+
+### Saving & Piping Output
+
+The CLI writes Tally's raw XML response directly to `stdout`, making it easy to pipe to a file or another command:
+
+```bash
+npx tally-simple masters.units.fetch --company Mani9 > units.xml
+```
+
+Pipe directly into `xmllint` or formatting utilities:
+
+```bash
+npx tally-simple masters.units.fetch --company Mani9 | xmllint --format -
+```
+
+---
+
+## Error Handling
+
+Tally Simple provides clear, predictable errors:
+
+1. **Company Name Validation:**
+   Passing an empty string or non-string argument throws a `TypeError` before any request is sent:
+   ```javascript
+   await tally.masters.units.fetch(" "); // Throws: TypeError: Company name is required.
+   ```
+
+2. **HTTP Failures:**
+   If the Tally server returns an error status (e.g. 500), an error is thrown containing the HTTP status and response body:
+   ```text
+   Error: Tally request failed with HTTP 500: Tally is unavailable
+   ```

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "tally-simple",
-    "version": "1.3.1",
+    "version": "1.8.4",
     "description": "A small, typed JavaScript client and CLI for querying Tally through TDL definitions.",
-    "homepage": "https://github.com/keshavsoft/tally-simple#readme",
+    "homepage": "https://keshavsoft.github.io/tally-simple/",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/keshavsoft/tally-simple.git"
@@ -33,11 +33,8 @@
         "LICENSE"
     ],
     "scripts": {
-        "generate:dts": "node generate-dts.js",
-        "test": "node --test test/test.js test/units.js",
-        "verify": "npm run generate:dts && npm test",
-        "prepack": "npm run verify",
-        "prepublishOnly": "npm run verify"
+        "generate:dts": "create-intellisense",
+        "test": "node --test test/test.js test/units.js"
     },
     "keywords": [
         "tally",
@@ -51,5 +48,14 @@
     },
     "publishConfig": {
         "access": "public"
+    },
+    "devDependencies": {
+        "create-intellisense": "^1.2.1"
+    },
+    "dependencies": {
+        "@keshavsoft/api-tree": "^11.1.1",
+        "@keshavsoft/json-transformer": "^1.9.2",
+        "tally-simple-json": "^1.16.6",
+        "tally-spec": "^1.2.3"
     }
-}
+}