tally-simple 0.0.0-stage → 1.1.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,70 @@
-# Temporary Holding Version
+# Tally Simple
 
-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 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).

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 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 };

package/docs/api.md

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

package/docs/architecture.md

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

package/docs/cli.md

@@ -0,0 +1,32 @@
+# CLI reference
+
+The package publishes the tally-simple executable. With npm, use it through npx:
+
+~~~bash
+npx tally-simple <api-path> --company <company>
+~~~
+
+## Options
+
+| Option | Meaning |
+| --- | --- |
+| -c, --company <name> | Company to query. Also reads TALLY_COMPANY. |
+| -u, --url <url> | Tally endpoint. Also reads TALLY_URL. |
+| --header <name:value> | Adds a request header. Repeat it for multiple headers. |
+| --timeout <ms> | Aborts a request after the given number of milliseconds. |
+| -h, --help | Prints command help. |
+| -v, --version | Prints the installed package version. |
+
+The command accepts masters.units.fetch and tally.masters.units.fetch equivalently. The response is written unchanged to stdout; errors and usage help are written to stderr.
+
+Examples:
+
+~~~bash
+npx tally-simple masters.units.fetch --company Mani9
+
+npx tally-simple masters.stockItems.withBatches \
+    --company Mani9 \
+    --header X-Request-Source:nightly
+
+TALLY_COMPANY=Mani9 npx tally-simple masters.units.fetch
+~~~

package/docs/development.md

@@ -0,0 +1,66 @@
+# Developer guide
+
+This document explains how Tally Simple is built and how to change it. End-user installation and query examples are kept in the root README.
+
+## The developer story
+
+Tally Simple keeps the TDL request definitions in one internal source and exposes only the queries deliberately selected for users.
+
+~~~text
+source.json
+    │
+    ├── public API list ──> JavaScript client
+    │
+    └── request traversal ──> XML over HTTP ──> Tally
+                         │
+                         └──> CLI stdout
+~~~
+
+The source definitions describe how Tally should answer a query. The public API list is the product boundary: only listed paths become JavaScript methods and CLI commands.
+
+## Repository map
+
+- src/v1/source.json: Tally connection defaults, request envelope, and TDL collections.
+- src/v1/external-api/api.json: public query allowlist.
+- src/v1/external-api/api.js: builds the nested runtime API.
+- src/v1/traverse.js: validates, builds, and sends a request.
+- src/index.d.ts: generated TypeScript declarations.
+- bin/tally-simple.js: command-line entrypoint.
+- test/test.js and test/units.js: offline behavior and CLI tests.
+- test/v1/units.js: manual integration smoke check against a reachable Tally instance; it is not part of npm test.
+
+## Request lifecycle
+
+1. The application or CLI selects a public query path.
+2. The client validates and trims the company name.
+3. The path is resolved in source.json.
+4. The company name is XML-escaped and inserted into the request envelope.
+5. The selected 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.
+
+## Adding a query
+
+1. Add or update the TDL definition in 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 source definition and public path list.
+
+## Client configuration
+
+createTallyClient() is the application boundary for a different URL, method, headers, timeout, or fetch implementation. The default import uses the default connection from source.json.
+
+The fetch option is intentionally injectable so tests can run without a Tally installation or network connection.
+
+## Verification and publishing
+
+~~~bash
+npm install
+npm run verify
+npm pack --dry-run
+~~~
+
+The prepack and prepublishOnly hooks run declaration generation and the offline test suite. The package files allowlist publishes the runtime, CLI, user documentation, and package metadata while excluding tests and development-only scripts.

package/docs/usage.md

@@ -0,0 +1,73 @@
+# 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
+~~~

package/package.json

@@ -1,6 +1,47 @@
 {
-  "name": "tally-simple",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "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"
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,36 @@
+export interface TallyClientOptions {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    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: {
+            fetch: (company: string) => Promise<string>;
+        };
+        stockItems: {
+            withBatches: (company: string) => Promise<string>;
+        };
+        ledgers: {
+            withGstDetails: (company: string) => Promise<string>;
+        };
+    };
+};
+
+declare const tally: TallyApi;
+
+export declare const createTallyClient: (options?: TallyClientOptions) => TallyApi;
+export declare const tally: TallyApi;
+export default tally;

package/src/index.js

@@ -0,0 +1,8 @@
+import { createApi } from "./v1/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;