tally-simple 0.0.0-stage → 1.3.1

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.

package/package.json

@@ -1,6 +1,55 @@
-{
-  "name": "tally-simple",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+    "name": "tally-simple",
+    "version": "1.3.1",
+    "description": "A small, typed JavaScript client and CLI for querying Tally through TDL definitions.",
+    "homepage": "https://github.com/keshavsoft/tally-simple#readme",
+    "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": "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"
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Generated from src/v3/external-api/api.json and src/v3/source.json.
+ * Do not edit this file directly. Run npm run generate:dts instead.
+ */
+export interface TallyClientOptions {
+    /** Tally HTTP endpoint. Defaults to http://localhost:9000. */
+    url?: string;
+    /** HTTP method used for the Tally request. Defaults to POST. */
+    method?: string;
+    /** Additional request headers. */
+    headers?: Record<string, string>;
+    /** Abort the request after this many milliseconds. */
+    timeout?: number;
+    /** Optional fetch-compatible implementation for tests or adapters. */
+    fetch?: (url: string, options: {
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+        signal?: unknown;
+    }) => Promise<{
+        ok: boolean;
+        status: number;
+        text: () => Promise<string>;
+    }>;
+}
+
+export type TallyApi = {
+    masters: {
+        units: {
+            /** Runs tally.masters.units.fetch and returns Tally's raw XML response. */
+            fetch: (company: string) => Promise<string>;
+        };
+        stockItems: {
+            /** Runs tally.masters.stockItems.withBatches and returns Tally's raw XML response. */
+            withBatches: (company: string) => Promise<string>;
+        };
+        ledgers: {
+            /** Runs tally.masters.ledgers.withGstDetails and returns Tally's raw XML response. */
+            withGstDetails: (company: string) => Promise<string>;
+        };
+        stockGroup: {
+            /** Runs tally.masters.stockGroup.withParent and returns Tally's raw XML response. */
+            withParent: (company: string) => Promise<string>;
+        };
+    };
+};
+
+/** Create an independently configured Tally client. */
+export declare const createTallyClient: (options?: TallyClientOptions) => TallyApi;
+
+/** Default Tally client using the package connection defaults. */
+export declare const tally: TallyApi;
+
+export default tally;

package/src/index.js

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

package/src/v1/external-api/api.js

@@ -0,0 +1,67 @@
+import source from "../source.json" with { type: "json" };
+import traverse from "../traverse.js";
+import apiPaths from "./api.json" with { type: "json" };
+
+const createApi = (options = {}) => {
+    const connection = {
+        ...source.tally.connection,
+        ...options.connection,
+        ...(options.url ? { url: options.url } : {}),
+        ...(options.method ? { method: options.method } : {}),
+        headers: {
+            ...source.tally.connection.headers,
+            ...options.connection?.headers,
+            ...options.headers
+        }
+    };
+    const request = options.request ?? source.tally.request;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const clientSource = {
+        ...source,
+        tally: {
+            ...source.tally,
+            connection,
+            request
+        }
+    };
+
+    const createFunction = (path) => async (company) => {
+        if (typeof company !== "string" || !company.trim()) {
+            throw new TypeError("Company name is required.");
+        }
+
+        return await traverse(clientSource, "", path, {
+            company: company.trim(),
+            connection,
+            request,
+            fetch: fetchImpl,
+            timeout: options.timeout
+        });
+    };
+
+    const root = {};
+
+    for (const path of apiPaths) {
+        const parts = path.split(".");
+        let current = root;
+
+        parts.forEach((part, index) => {
+            const isLast = index === parts.length - 1;
+
+            if (isLast) {
+                current[part] = createFunction(path);
+                return;
+            }
+
+            current[part] ??= {};
+            current = current[part];
+        });
+    }
+
+    const rootName = apiPaths[0]?.split(".")[0];
+
+    return rootName ? root[rootName] : root;
+};
+
+export { createApi };
+export default createApi();

package/src/v1/external-api/api.json

@@ -0,0 +1,5 @@
+[
+  "tally.masters.units.fetch",
+  "tally.masters.stockItems.withBatches",
+  "tally.masters.ledgers.withGstDetails"
+]

package/src/v1/external-api/index.js

@@ -0,0 +1 @@
+export { createApi, default } from "./api.js";

package/src/v1/index.js

@@ -0,0 +1 @@
+export { createApi, default } from "./external-api/api.js";

package/src/v1/source.json

@@ -0,0 +1,40 @@
+{
+    "tally": {
+        "connection": {
+            "url": "http://localhost:9000",
+            "method": "POST",
+            "headers": {
+                "Content-Type": "text/xml"
+            }
+        },
+        "request": {
+            "body": "<ENVELOPE>\n<HEADER>\n<VERSION>1</VERSION>\n<TALLYREQUEST>Export</TALLYREQUEST>\n<TYPE>Collection</TYPE>\n<ID>TDLID</ID>\n</HEADER>\n<BODY>\n<DESC>\n<STATICVARIABLES>\n<SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>\n<SVCURRENTCOMPANY>{company}</SVCURRENTCOMPANY>\n</STATICVARIABLES>\n<TDL>\n<TDLMESSAGE>\n<COLLECTION NAME=\"TDLID\">\n{collectionBody}</COLLECTION>\n</TDLMESSAGE>\n</TDL>\n</DESC>\n</BODY>\n</ENVELOPE>"
+        },
+        "masters": {
+            "units": {
+                "fetch": {
+                    "tdl": {
+                        "collection": "<TYPE>Unit</TYPE>\n<FETCH>$$Alias:Name</FETCH>\n"
+                    },
+                    "action": "fetch"
+                }
+            },
+            "stockItems": {
+                "withBatches": {
+                    "tdl": {
+                        "collection": "<TYPE>StockItem</TYPE><FETCH>$$Alias:Name</FETCH><FETCH>BaseUnits</FETCH><FETCH>BatchAllocations.*</FETCH>"
+                    },
+                    "action": "fetch"
+                }
+            },
+            "ledgers": {
+                "withGstDetails": {
+                    "tdl": {
+                        "collection": "<TYPE>Ledger</TYPE><FETCH>$$Alias:Name</FETCH><FETCH>LEDGSTREGDETAILS.LIST</FETCH>"
+                    },
+                    "action": "fetch"
+                }
+            }
+        }
+    }
+}

package/src/v1/traverse.js

@@ -0,0 +1,103 @@
+import traverseObject from "./traverseObject/index.js";
+
+const escapeXml = (value) => value.replace(/[&<>"']/g, (character) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&apos;"
+}[character]));
+
+const buildRequestBody = (requestBody, { company, collection }) => {
+    return requestBody
+        .replace("{company}", escapeXml(company))
+        .replace("{collectionBody}", collection);
+};
+
+const execute = async (connection, xml, fetchImpl, timeout) => {
+    if (typeof fetchImpl !== "function") {
+        throw new Error(
+            "No fetch implementation is available. Use Node.js 20+ or provide fetch to createTallyClient()."
+        );
+    }
+
+    const controller = typeof AbortController === "function"
+        ? new AbortController()
+        : undefined;
+    const timeoutId = Number.isFinite(timeout) && timeout > 0
+        ? setTimeout(() => controller?.abort(), timeout)
+        : undefined;
+
+    let response;
+
+    try {
+        response = await fetchImpl(connection.url, {
+            method: connection.method,
+            headers: connection.headers,
+            body: xml,
+            ...(controller ? { signal: controller.signal } : {})
+        });
+    } catch (error) {
+        if (controller?.signal.aborted) {
+            throw new Error(`Tally request timed out after ${timeout} ms.`, {
+                cause: error
+            });
+        }
+
+        throw error;
+    } finally {
+        if (timeoutId) clearTimeout(timeoutId);
+    }
+
+    const responseText = await response.text();
+
+    if (!response.ok) {
+        throw new Error(
+            `Tally request failed with HTTP ${response.status}: ${responseText}`
+        );
+    }
+
+    return responseText;
+};
+
+const traverse = async (
+    raka,
+    relativePath,
+    pathToFind,
+    context = {}
+) => {
+    if (relativePath === pathToFind) {
+        if (raka?.action === "fetch") {
+            const body = buildRequestBody(
+                context.request.body,
+                {
+                    company: context.company,
+                    collection: raka.tdl.collection
+                }
+            );
+
+            return await execute(
+                context.connection,
+                body,
+                context.fetch,
+                context.timeout
+            );
+        }
+
+        return raka;
+    }
+
+    if (typeof raka === "object" && raka !== null) {
+        return await traverseObject(
+            raka,
+            relativePath,
+            pathToFind,
+            context
+        );
+    }
+
+    return undefined;
+};
+
+export { traverse };
+export default traverse;

package/src/v1/traverseObject/index.js

@@ -0,0 +1,39 @@
+import { traverse } from "../traverse.js";
+
+const traverseObject = async (
+    specJson,
+    relativePath,
+    pathToFind,
+    context = {}
+) => {
+    const nextContext = {
+        ...context,
+        connection: specJson.connection ?? context.connection,
+        request: specJson.request ?? context.request
+    };
+
+    for (const [key, value] of Object.entries(specJson)) {
+        if (key === "connection" || key === "request") continue;
+
+        if (typeof value === "object" && value !== null) {
+            const nextPath = relativePath
+                ? `${relativePath}.${key}`
+                : key;
+
+            const result = await traverse(
+                value,
+                nextPath,
+                pathToFind,
+                nextContext
+            );
+
+            if (result !== undefined) {
+                return result;
+            }
+        }
+    }
+
+    return undefined;
+};
+
+export default traverseObject;