tally-simple 1.1.1 → 1.8.2

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

@@ -1,73 +1,117 @@
-# Usage
-
-## The shortest library path
-
-~~~js
-import tally from "tally-simple";
-
-const response = await tally.masters.units.fetch("Mani9");
-~~~
-
-Every endpoint takes a company name. Blank names are rejected before a request is sent.
-
-## Configure a client
-
-~~~js
-import { createTallyClient } from "tally-simple";
-
-const tally = createTallyClient({
-    url: "http://localhost:9000",
-    headers: {
-        Authorization: "Bearer example"
-    },
-    timeout: 15_000
-});
-~~~
-
-Options:
-
-- url: Tally HTTP endpoint. The default is http://localhost:9000.
-- method: request method. The default is POST.
-- headers: headers merged with the default Content-Type: text/xml.
-- timeout: optional request timeout in milliseconds.
-- fetch: optional fetch-compatible function, useful for tests or an application adapter.
-
-The endpoint returns the response text. HTTP responses outside the 2xx range throw an error containing the status and response body.
-
-## Test without Tally
-
-~~~js
-import { createTallyClient } from "tally-simple";
-
-const tally = createTallyClient({
-    fetch: async (url, options) => {
-        console.log(url, options.body);
-        return {
-            ok: true,
-            status: 200,
-            text: async () => "<ENVELOPE><STATUS>1</STATUS></ENVELOPE>"
-        };
-    }
-});
-
-const response = await tally.masters.units.fetch("Mani9");
-~~~
-
-The package escapes XML-sensitive characters in the company name before inserting it into the request.
-
-## TypeScript
-
-The package ships declarations generated from the public API definition:
-
-~~~ts
-import { createTallyClient } from "tally-simple";
-
-const tally = createTallyClient();
-const response: Promise<string> = tally.masters.units.fetch("Mani9");
-~~~
-
-Regenerate the declarations after changing an API path:
-
-~~~bash
-npm run generate:dts
-~~~
+# 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,47 +1,61 @@
-{
-    "name": "tally-simple",
-    "version": "1.1.1",
-    "description": "A small, typed JavaScript client and CLI for querying Tally through TDL definitions.",
-    "type": "module",
-    "exports": {
-        ".": {
-            "types": "./src/index.d.ts",
-            "import": "./src/index.js",
-            "default": "./src/index.js"
-        },
-        "./package.json": "./package.json"
-    },
-    "bin": {
-        "tally-simple": "bin/tally-simple.js"
-    },
-    "main": "./src/index.js",
-    "types": "./src/index.d.ts",
-    "files": [
-        "bin",
-        "src",
-        "docs",
-        "README.md",
-        "CHANGELOG.md",
-        "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"
-    },
-    "keywords": [
-        "tally",
-        "tdl",
-        "api",
-        "accounting"
-    ],
-    "license": "MIT",
-    "engines": {
-        "node": ">=20.10"
-    },
-    "publishConfig": {
-        "access": "public"
-    }
-}
+{
+    "name": "tally-simple",
+    "version": "1.8.2",
+    "description": "A small, typed JavaScript client and CLI for querying Tally through TDL definitions.",
+    "homepage": "https://keshavsoft.github.io/tally-simple/",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/keshavsoft/tally-simple.git"
+    },
+    "bugs": {
+        "url": "https://github.com/keshavsoft/tally-simple/issues"
+    },
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "import": "./src/index.js",
+            "default": "./src/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "bin": {
+        "tally-simple": "./bin/tally-simple.js"
+    },
+    "main": "./src/index.js",
+    "types": "./src/index.d.ts",
+    "files": [
+        "bin",
+        "src",
+        "docs",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "generate:dts": "create-intellisense",
+        "test": "node --test test/test.js test/units.js"
+    },
+    "keywords": [
+        "tally",
+        "tdl",
+        "api",
+        "accounting"
+    ],
+    "license": "MIT",
+    "engines": {
+        "node": ">=20.10"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "create-intellisense": "^1.2.1"
+    },
+    "dependencies": {
+        "@keshavsoft/api-tree": "^11.1.1",
+        "@keshavsoft/json-transformer": "^1.7.1",
+        "tally-simple-json": "^1.16.3",
+        "tally-spec": "^1.2.1"
+    }
+}

package/src/index.js

@@ -1,8 +1,2 @@
-import { createApi } from "./v1/index.js";
-
-const createTallyClient = (options = {}) => createApi(options);
-
-const tally = createTallyClient();
-
-export { createTallyClient, tally };
-export default tally;
+export { default } from "./v8/index.js";
+export * from "./v8/index.js";