tally-simple 0.0.0-stage → 1.3.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.0
+
+- Expose the Tally query API as an installable ESM package.
+- Add `createTallyClient()` for endpoint, header, timeout, and fetch configuration.
+- Add the `tally-simple` command for querying a published API path from a shell.
+- Keep the default import as a ready-to-use client for backwards compatibility.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KeshavSoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 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)
+
+Tally Simple is a small, typed JavaScript client and CLI for asking Tally for business data.
+
+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.
+
+**[View the package on npm](https://www.npmjs.com/package/tally-simple)** · **[Open the visual guide](docs/index.html)**
+
+## The story in one minute
+
+Tally Simple sits between your code or shell and a Tally HTTP endpoint:
+
+~~~text
+your app / shell command
+          │  choose a public query + company
+          ▼
+       Tally Simple
+          │  builds the XML request
+          ▼
+    Tally HTTP endpoint
+          │
+          ▼
+     XML response text
+~~~
+
+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.
+
+## Requirements
+
+- Node.js 20.10 or newer
+- A Tally HTTP endpoint that accepts the request, usually http://localhost:9000
+
+Tally Simple returns Tally's response body as XML text.
+
+## Install
+
+~~~bash
+npm install tally-simple
+~~~
+
+The package has no runtime dependencies and requires Node.js 20.10 or newer.
+
+## Use it in JavaScript
+
+~~~js
+import tally from "tally-simple";
+
+const xml = await tally.masters.units.fetch("Mani9");
+console.log(xml);
+~~~
+
+The default import is a ready-to-use client. For a different endpoint, headers, timeout, or fetch implementation, use `createTallyClient()`:
+
+~~~js
+import { createTallyClient } from "tally-simple";
+
+const tally = createTallyClient({
+    url: "http://localhost:9000",
+    timeout: 15_000
+});
+
+const xml = await tally.masters.ledgers.withGstDetails("Mani9");
+~~~
+
+## Use it from the command line
+
+Run a query with npm's command runner:
+
+~~~bash
+npx tally-simple masters.units.fetch --company Mani9
+~~~
+
+You can also include the root name:
+
+~~~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:
+
+~~~bash
+npx tally-simple masters.ledgers.withGstDetails --company Mani9 > ledgers.xml
+~~~
+
+For environment-based use:
+
+~~~bash
+TALLY_COMPANY=Mani9 TALLY_URL=http://localhost:9000 \
+    npx tally-simple masters.units.fetch
+~~~
+
+Run npx tally-simple --help to see all CLI options.
+
+In PowerShell, environment variables use this form:
+
+~~~powershell
+$env:TALLY_COMPANY = "Mani9"
+$env:TALLY_URL = "http://localhost:9000"
+npx tally-simple masters.units.fetch
+~~~
+
+## Available queries
+
+| 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 |
+
+Every query accepts one company name. Blank company names are rejected before a request is sent. HTTP errors include the status and response body.
+
+## 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.
+
+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).

package/bin/tally-simple.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+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";
+
+const usage = [
+    "Usage:",
+    "  tally-simple <api-path> --company <company> [options]",
+    "",
+    "Examples:",
+    "  tally-simple masters.units.fetch --company Mani9",
+    "  tally-simple tally.masters.ledgers.withGstDetails --company Mani9 --url http://localhost:9000",
+    "",
+    "Options:",
+    "  -c, --company <name>   Tally company name (or TALLY_COMPANY)",
+    "  -u, --url <url>        Tally HTTP endpoint (or TALLY_URL)",
+    "      --header <k:v>     Add a request header; may be repeated",
+    "      --timeout <ms>     Abort a request after the given number of milliseconds",
+    "  -h, --help             Show this help",
+    "  -v, --version          Show the package version",
+    "",
+    "The API path is one of the paths listed in docs/api.md. The response body is",
+    "written to stdout with a trailing newline, so it can be piped to another command.",
+    ""
+].join("\n");
+
+const readValue = (args, index, option) => {
+    const value = args[index + 1];
+
+    if (!value || value.startsWith("-")) {
+        throw new Error(option + " requires a value.");
+    }
+
+    return value;
+};
+
+const parseHeader = (value) => {
+    const separator = value.indexOf(":");
+
+    if (separator < 1) {
+        throw new Error("Invalid header \"" + value + "\". Use the form name:value.");
+    }
+
+    return [
+        value.slice(0, separator).trim(),
+        value.slice(separator + 1).trim()
+    ];
+};
+
+const parseArgs = (args) => {
+    const options = { headers: {} };
+    let apiPath;
+
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+
+        if (argument === "--help" || argument === "-h") {
+            return { help: true };
+        }
+
+        if (argument === "--version" || argument === "-v") {
+            return { version: true };
+        }
+
+        if (argument === "--company" || argument === "-c") {
+            options.company = readValue(args, index, argument);
+            index += 1;
+            continue;
+        }
+
+        if (argument === "--url" || argument === "-u") {
+            options.url = readValue(args, index, argument);
+            index += 1;
+            continue;
+        }
+
+        if (argument === "--timeout") {
+            const value = readValue(args, index, argument);
+            options.timeout = Number(value);
+
+            if (!Number.isFinite(options.timeout) || options.timeout <= 0) {
+                throw new Error("--timeout must be a positive number of milliseconds.");
+            }
+
+            index += 1;
+            continue;
+        }
+
+        if (argument === "--header") {
+            const [name, value] = parseHeader(readValue(args, index, argument));
+            options.headers[name] = value;
+            index += 1;
+            continue;
+        }
+
+        if (argument.startsWith("-")) {
+            throw new Error("Unknown option: " + argument);
+        }
+
+        if (apiPath) {
+            throw new Error(
+                "Only one API path may be supplied; received \"" + argument + "\" too."
+            );
+        }
+
+        apiPath = argument;
+    }
+
+    return { ...options, apiPath };
+};
+
+const normalizePath = (apiPath) => apiPath.startsWith("tally.")
+    ? apiPath.slice("tally.".length)
+    : apiPath;
+
+const findEndpoint = (apiPath, client = tally) => {
+    const endpoint = normalizePath(apiPath).split(".").reduce(
+        (current, part) => current?.[part],
+        client
+    );
+
+    if (typeof endpoint !== "function") {
+        throw new Error("Unknown API path: " + apiPath);
+    }
+
+    return endpoint;
+};
+
+const run = async (args) => {
+    const parsed = parseArgs(args);
+
+    if (parsed.help) {
+        process.stdout.write(usage);
+        return;
+    }
+
+    if (parsed.version) {
+        process.stdout.write(packageInfo.version + "\n");
+        return;
+    }
+
+    if (!parsed.apiPath) {
+        throw new Error("An API path is required. Use --help to see examples.");
+    }
+
+    const company = parsed.company ?? process.env.TALLY_COMPANY;
+
+    if (!company) {
+        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 response = await endpoint(company);
+
+    process.stdout.write(response + "\n");
+};
+
+const isMain = process.argv[1]
+    && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+    run(process.argv.slice(2)).catch((error) => {
+        process.stderr.write("Error: " + error.message + "\n\n" + usage);
+        process.exitCode = 1;
+    });
+}
+
+export { findEndpoint, parseArgs, run };

package/docs/api.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Api</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>API Reference</h1>
+<p>The public API is generated from <code>src/v1/external-api/api.json</code>.</p>
+<p>Current public paths:</p>
+<pre><code>tally.masters.units.fetch
+tally.masters.stockItems.withBatches</code></pre>
+<p>Example:</p>
+<pre><code>await tally.masters.units.fetch(&quot;Mani9&quot;);</code></pre>
+<p>The exact public surface should be changed through <code>external-api/api.json</code>, followed by declaration generation.</p>
+</body>
+</html>

package/docs/api.md

@@ -0,0 +1,20 @@
+[**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

@@ -0,0 +1,65 @@
+[**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>