tally-simple 1.1.1 → 1.3.1

package/CHANGELOG.md

@@ -1,8 +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.
+# 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

@@ -1,21 +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.
+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,70 +1,127 @@
-# Tally Simple
-
-Tally Simple gives JavaScript applications and shell scripts a straightforward way to ask Tally for business data.
-
-Choose a supported query, provide the company name, and receive the response directly from Tally. The same queries work from an application or from the command line.
-
-## 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
-~~~
-
-## Use it in JavaScript
-
-~~~js
-import tally from "tally-simple";
-
-const xml = await tally.masters.units.fetch("Mani9");
-console.log(xml);
-~~~
-
-## 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.
-
-## 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 |
-
-Every query accepts one company name. Blank company names are rejected before a request is sent. HTTP errors include the status and response body.
-
-More user-facing details are available in [usage](docs/usage.md), the [CLI reference](docs/cli.md), and the [available query list](docs/api.md).
+# 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

@@ -1,175 +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 is written",
-    "to stdout exactly as Tally returns it, 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 };
+#!/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>