tally-simple 1.1.1 → 1.3.1

package/docs/api.md

@@ -1,19 +1,20 @@
-# Published API paths
-
-These are the paths intentionally exposed by the package. The root tally is present on the default JavaScript import, while the CLI accepts paths with or without that root.
-
-| JavaScript call | CLI path | TDL request |
-| --- | --- | --- |
-| tally.masters.units.fetch(company) | masters.units.fetch | Unit with $$Alias:Name |
-| tally.masters.stockItems.withBatches(company) | masters.stockItems.withBatches | StockItem with base units and batch allocations |
-| tally.masters.ledgers.withGstDetails(company) | masters.ledgers.withGstDetails | Ledger with GST registration details |
-
-All current calls:
-
-- accept one company name;
-- make a POST request with XML;
-- return Tally's response body as a string;
-- use the configured endpoint and headers;
-- reject blank company names.
-
-The source of truth for the request definitions is src/v1/source.json. The allowlist for this published surface is src/v1/external-api/api.json.
+[**View this document as HTML**](./api.html)
+
+# API Reference
+
+The public API is generated from `src/v1/external-api/api.json`.
+
+Current public paths:
+
+```text
+tally.masters.units.fetch
+tally.masters.stockItems.withBatches
+```
+
+Example:
+
+```js
+await tally.masters.units.fetch("Mani9");
+```
+
+The exact public surface should be changed through `external-api/api.json`, followed by declaration generation.

package/docs/architecture.html

@@ -0,0 +1,74 @@
+<!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>
+</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>
+</body>
+</html>

package/docs/architecture.md

@@ -1,43 +1,65 @@
-# Architecture and the package story
-
-## One definition, two ways to use it
-
-The package has one query model and two entrypoints:
-
-~~~text
-src/v1/source.json
-        │
-        ├── api.json ──> generated JavaScript client ──> application imports
-        │
-        └── request traversal ──> XML over HTTP ──> Tally
-
-api.json ──> tally-simple CLI ──> stdout
-~~~
-
-source.json owns the TDL collection definitions and the default request envelope. api.json is the product boundary: only paths listed there become public methods or CLI commands.
-
-## Request lifecycle
-
-1. An application or CLI selects a public path.
-2. The client validates and trims the company name.
-3. The path is traversed into the source definition.
-4. The company is XML-escaped and inserted into the request envelope.
-5. The collection body is inserted into the envelope.
-6. The configured fetch implementation sends the request to Tally.
-7. The response body is returned as text; non-2xx responses become errors.
-
-The default client is useful for a quick start. createTallyClient() provides the boundary for applications that need a different URL, headers, timeout, or fetch implementation.
-
-## Adding a public endpoint
-
-1. Add the TDL definition under src/v1/source.json.
-2. Add its complete path to src/v1/external-api/api.json.
-3. Run npm run generate:dts.
-4. Add or update an offline test.
-5. Run npm run verify.
-
-Do not edit src/index.d.ts by hand; it is generated from the public path list.
-
-## Publish boundary
-
-package.json exposes the ESM entrypoint and CLI explicitly. Its files allowlist publishes src, bin, docs, and the package-facing metadata while excluding tests and development scripts. prepublishOnly runs declaration generation and the offline test suite before npm publish.
+[**View this document as HTML**](./architecture.html)
+
+# Architecture
+
+The package is intentionally small.
+
+```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:
+
+```text
+add definition
+→ expose path
+→ regenerate declarations
+→ test
+```
+
+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.

package/docs/developer.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">
+<title>Developer</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>
+</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>Application Developer Guide</h1>
+<p>This guide is for developers consuming Tally Public API from another application.</p>
+<h2>Public boundary</h2>
+<p>The consumer sees a tree-shaped JavaScript API:</p>
+<pre><code>const result = await tally.masters.units.fetch(&quot;Mani9&quot;);</code></pre>
+<p>The consumer does not need to know:</p>
+<ul>
+<li>the internal source JSON structure;</li>
+<ul>
+<li>the TDL request template;</li>
+<ul>
+<li>how traversal finds the definition;</li>
+<ul>
+<li>how the HTTP request is constructed.</li>
+<h2>Company name</h2>
+<p>The company is runtime input.</p>
+<pre><code>await tally.masters.units.fetch(&quot;Mani9&quot;);
+await tally.masters.units.fetch(&quot;Another Company&quot;);</code></pre>
+<p>The company should therefore not be permanently embedded in the source definition.</p>
+<h2>CLI / scripting</h2>
+<p>The same public operation can be exposed through a CLI layer without duplicating the Tally definition.</p>
+<h2>Response</h2>
+<p>The package returns the Tally response body. XML parsing and application-specific normalization remain outside this package.</p>
+<p>For the internal architecture, see <a href="repo-developer.md">Repository Developer Guide</a>.</p>
+</body>
+</html>

package/docs/developer.md

@@ -0,0 +1,41 @@
+[**View this document as HTML**](./developer.html)
+
+# Application Developer Guide
+
+This guide is for developers consuming Tally Public API from another application.
+
+## Public boundary
+
+The consumer sees a tree-shaped JavaScript API:
+
+```js
+const result = await tally.masters.units.fetch("Mani9");
+```
+
+The consumer does not need to know:
+
+- the internal source JSON structure;
+- the TDL request template;
+- how traversal finds the definition;
+- how the HTTP request is constructed.
+
+## Company name
+
+The company is runtime input.
+
+```js
+await tally.masters.units.fetch("Mani9");
+await tally.masters.units.fetch("Another Company");
+```
+
+The company should therefore not be permanently embedded in the source definition.
+
+## CLI / scripting
+
+The same public operation can be exposed through a CLI layer without duplicating the Tally definition.
+
+## Response
+
+The package returns the Tally response body. XML parsing and application-specific normalization remain outside this package.
+
+For the internal architecture, see [Repository Developer Guide](repo-developer.md).

package/docs/end-user.html

@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>End User</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>
+</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>End User Guide</h1>
+<p>This guide is for someone who wants to use the Tally package, not modify it.</p>
+<h2>JavaScript</h2>
+<pre><code>import tally from &quot;./src/index.js&quot;;
+
+const units = await tally.masters.units.fetch(&quot;Mani9&quot;);
+console.log(units);</code></pre>
+<p>The company name is supplied by the caller:</p>
+<pre><code>tally.masters.units.fetch(&quot;My Company&quot;);</code></pre>
+<p>The package builds the Tally request internally.</p>
+<h2>What you receive</h2>
+<p>The Tally response is returned as XML text. This package does not force an XML-to-JSON format on the consumer.</p>
+<p>You can parse or transform the response with the tool you prefer.</p>
+<h2>Public API</h2>
+<p>See <a href="api.md">API Reference</a> for the currently exposed operations.</p>
+<p>If you are integrating this package into a larger application, continue with the <a href="developer.md">Application Developer Guide</a>.</p>
+</body>
+</html>

package/docs/end-user.md

@@ -0,0 +1,34 @@
+[**View this document as HTML**](./end-user.html)
+
+# End User Guide
+
+This guide is for someone who wants to use the Tally package, not modify it.
+
+## JavaScript
+
+```js
+import tally from "./src/index.js";
+
+const units = await tally.masters.units.fetch("Mani9");
+console.log(units);
+```
+
+The company name is supplied by the caller:
+
+```js
+tally.masters.units.fetch("My Company");
+```
+
+The package builds the Tally request internally.
+
+## What you receive
+
+The Tally response is returned as XML text. This package does not force an XML-to-JSON format on the consumer.
+
+You can parse or transform the response with the tool you prefer.
+
+## Public API
+
+See [API Reference](api.md) for the currently exposed operations.
+
+If you are integrating this package into a larger application, continue with the [Application Developer Guide](developer.md).

package/docs/index.html

@@ -0,0 +1,32 @@
+<!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>
+</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>
+</body>
+</html>

package/docs/repo-developer.html

@@ -0,0 +1,91 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Repo Developer</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>
+</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>Repository Developer Guide</h1>
+<p>This guide is for developers who change the repository itself.</p>
+<h2>Source of truth</h2>
+<p>The active version contains the Tally definitions:</p>
+<pre><code>src/
+└── v1/
+    ├── source.json
+    ├── traverse.js
+    ├── traverseObject/
+    ├── external-api/
+    │   ├── api.json
+    │   ├── api.js
+    │   └── index.js
+    └── index.js</code></pre>
+<p><code>source.json</code> contains the internal request definitions.</p>
+<p><code>external-api/api.json</code> contains only the public paths.</p>
+<p>That separation is intentional.</p>
+<h2>Adding a public operation</h2>
+<p>1. Add or change the internal TDL definition in <code>source.json</code>.</p>
+<p>2. Add its public path to <code>external-api/api.json</code>.</p>
+<p>3. Regenerate <code>src/index.d.ts</code>.</p>
+<p>4. Test the public call.</p>
+<p>5. Leave older source versions untouched.</p>
+<h2>Company input</h2>
+<p>Do not hardcode a real company name into the public definition.</p>
+<p>The caller supplies the company:</p>
+<pre><code>tally.masters.units.fetch(&quot;Mani9&quot;);</code></pre>
+<p>The runtime passes that value into the request builder.</p>
+<h2>Traversal</h2>
+<p>Traversal should remain generic.</p>
+<p>Its job is to locate the requested definition.</p>
+<p>The action/request layer interprets the terminal definition and performs the Tally HTTP request.</p>
+<p>Avoid putting endpoint-specific paths directly into the traversal engine.</p>
+<h2>Versioning</h2>
+<p>When a new implementation is required:</p>
+<pre><code>src/v1
+src/v2
+src/v3</code></pre>
+<p>Create the next version and make the root <code>src/index.js</code> point to the highest active version.</p>
+<p>Do not rewrite old versions merely to keep them visually consistent.</p>
+<h2>Declaration generation</h2>
+<p>The generated declaration file represents the public API tree.</p>
+<p>It should be generated from the public API definition rather than manually maintained.</p>
+<pre><code>node generate-dts.js</code></pre>
+<h2>Testing</h2>
+<p>Test both:</p>
+<p>1. the public JavaScript API;</p>
+<p>2. the generated request sent to Tally.</p>
+<p>Keep Tally-specific request definitions in JSON where possible so adding another operation is primarily a data change rather than a new JavaScript module.</p>
+<h2>Design boundary</h2>
+<p>The repository deliberately has three layers:</p>
+<pre><code>public API
+    ↓
+traversal / execution
+    ↓
+source JSON</code></pre>
+<p>The public consumer sees the first layer.</p>
+<p>The repository developer maintains all three.</p>
+</body>
+</html>

package/docs/repo-developer.md

@@ -0,0 +1,107 @@
+[**View this document as HTML**](./repo-developer.html)
+
+# Repository Developer Guide
+
+This guide is for developers who change the repository itself.
+
+## Source of truth
+
+The active version contains the Tally definitions:
+
+```text
+src/
+└── v1/
+    ├── source.json
+    ├── traverse.js
+    ├── traverseObject/
+    ├── external-api/
+    │   ├── api.json
+    │   ├── api.js
+    │   └── index.js
+    └── index.js
+```
+
+`source.json` contains the internal request definitions.
+
+`external-api/api.json` contains only the public paths.
+
+That separation is intentional.
+
+## Adding a public operation
+
+1. Add or change the internal TDL definition in `source.json`.
+2. Add its public path to `external-api/api.json`.
+3. Regenerate `src/index.d.ts`.
+4. Test the public call.
+5. Leave older source versions untouched.
+
+## Company input
+
+Do not hardcode a real company name into the public definition.
+
+The caller supplies the company:
+
+```js
+tally.masters.units.fetch("Mani9");
+```
+
+The runtime passes that value into the request builder.
+
+## Traversal
+
+Traversal should remain generic.
+
+Its job is to locate the requested definition.
+
+The action/request layer interprets the terminal definition and performs the Tally HTTP request.
+
+Avoid putting endpoint-specific paths directly into the traversal engine.
+
+## Versioning
+
+When a new implementation is required:
+
+```text
+src/v1
+src/v2
+src/v3
+```
+
+Create the next version and make the root `src/index.js` point to the highest active version.
+
+Do not rewrite old versions merely to keep them visually consistent.
+
+## Declaration generation
+
+The generated declaration file represents the public API tree.
+
+It should be generated from the public API definition rather than manually maintained.
+
+```bash
+node generate-dts.js
+```
+
+## Testing
+
+Test both:
+
+1. the public JavaScript API;
+2. the generated request sent to Tally.
+
+Keep Tally-specific request definitions in JSON where possible so adding another operation is primarily a data change rather than a new JavaScript module.
+
+## Design boundary
+
+The repository deliberately has three layers:
+
+```text
+public API
+    ↓
+traversal / execution
+    ↓
+source JSON
+```
+
+The public consumer sees the first layer.
+
+The repository developer maintains all three.