@valve-tech/trueblocks-sdk 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@valve-tech/trueblocks-sdk` are documented in
+this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+Experimental package, not yet published. Vertical-slice prototype:
+codegen pipeline + client core + `/status` and `/blocks` verbs with
+100/100/100/100 coverage on what's implemented.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 valve-tech
+
+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

@@ -0,0 +1,140 @@
+# `@valve-tech/trueblocks-sdk`
+
+Typed TypeScript HTTP client to a running [TrueBlocks](https://trueblocks.io)
+`chifra` daemon. Same verb surface as the upstream Go SDK, delivered
+as `fetch`-based REST calls — no Go runtime, no subprocess spawning,
+browser/mobile safe.
+
+Part of the
+[`valve-tech/evm-toolkit`](https://github.com/valve-tech/evm-toolkit)
+monorepo.
+
+## Prerequisite
+
+You need a running `chifra daemon` somewhere this client can reach
+over HTTP. That requires installing `trueblocks-core` and indexing
+the chains you care about. **This package does not bundle or invoke
+chifra.** See [TrueBlocks install docs](https://trueblocks.io/docs/install/install-core/).
+
+If you can't run chifra, this package isn't for you.
+
+## Install
+
+```sh
+npm install @valve-tech/trueblocks-sdk
+```
+
+No peer dependencies. Uses `globalThis.fetch` (Node 18+, every modern
+browser).
+
+## 30-second quickstart
+
+```ts
+import { createTrueblocksClient } from '@valve-tech/trueblocks-sdk'
+
+const client = createTrueblocksClient({
+  baseUrl: 'http://localhost:8080',
+})
+
+// Daemon status
+const status = await client.status()
+console.log(status)
+
+// Block reads
+const blocks = await client.blocks({
+  blocks: ['18000000', '18000001'],
+})
+console.log(blocks)
+
+// List appearances for an address
+const appearances = await client.list({
+  addrs: ['0xd8da6bf26964af9d7eed9e03e53415d37aa96045'],
+})
+console.log(appearances)
+```
+
+## Public surface
+
+### `createTrueblocksClient(options)`
+
+```ts
+interface CreateTrueblocksClientOptions {
+  baseUrl: string                     // e.g. 'http://localhost:8080'
+  fetch?: typeof globalThis.fetch     // optional override (testing, custom transport)
+}
+```
+
+Returns a `TrueblocksClient` with one method per chifra endpoint
+(flat surface — see [Verbs](#verbs) below).
+
+### Errors
+
+Every chifra-side failure throws a `TrueblocksError`:
+
+```ts
+import { TrueblocksError } from '@valve-tech/trueblocks-sdk'
+
+try {
+  await client.status()
+} catch (err) {
+  if (err instanceof TrueblocksError) {
+    console.log(err.path)        // chifra endpoint that failed (e.g. '/status')
+    console.log(err.status)      // HTTP status if applicable
+  }
+}
+```
+
+### Verbs
+
+Every chifra HTTP endpoint is exposed as a typed method on the
+client. Method names match the chifra CLI verbs.
+
+| Group | Method | Endpoint | Variants |
+|---|---|---|---|
+| Accounts | `client.list(...)` | `GET /list` | — |
+| Accounts | `client.export(...)` | `GET /export` | `.appearances` `.receipts` `.logs` `.approvals` `.traces` `.neighbors` `.statements` `.transfers` `.assets` `.balances` `.withdrawals` `.count` |
+| Accounts | `client.monitors(...)` | `GET /monitors` | — |
+| Accounts | `client.names(...)` | `GET /names` | — |
+| Accounts | `client.abis(...)` | `GET /abis` | — |
+| Chain Data | `client.blocks(...)` | `GET /blocks` | `.hashes` `.uncles` `.traces` `.uniq` `.logs` `.withdrawals` `.count` |
+| Chain Data | `client.transactions(...)` | `GET /transactions` | `.traces` `.uniq` `.logs` |
+| Chain Data | `client.receipts(...)` | `GET /receipts` | — |
+| Chain Data | `client.logs(...)` | `GET /logs` | — |
+| Chain Data | `client.traces(...)` | `GET /traces` | `.count` |
+| Chain State | `client.when(...)` | `GET /when` | — |
+| Chain State | `client.state(...)` | `GET /state` | `.call` |
+| Chain State | `client.tokens(...)` | `GET /tokens` | — |
+| Admin | `client.config(...)` | `GET /config` | — |
+| Admin | `client.status(...)` | `GET /status` | — |
+| Admin | `client.chunks(...)` | `GET /chunks` | `.manifest` `.index` `.blooms` `.pins` `.addresses` `.appearances` `.stats` |
+| Admin | `client.init(...)` | `GET /init` | — |
+| Other | `client.slurp(...)` | `GET /slurp` | `.appearances` `.count` |
+
+**Base methods** return the OpenAPI polymorphic union — useful when
+flag combinations are constructed at runtime. **Variants** preselect
+a flag (or `mode` enum value, for `chunks`) and narrow the return
+type to the single concrete shape that flag produces. Mirrors the
+Go SDK's `XxxOptions.XxxFlag()` family.
+
+Example:
+
+```ts
+// Polymorphic — narrow at the call site:
+const result = await client.blocks({ blocks: ['18000000'], logs: true })
+// result.data is (Block | LightBlock | Log | …)[]
+
+// Variant — concrete return type, no narrowing needed:
+const result = await client.blocks.logs({ blocks: ['18000000'] })
+// result.data is Log[]
+```
+
+Per-method query parameters are typed against the upstream OpenAPI
+spec — your editor surfaces the available options via IntelliSense.
+
+## License
+
+MIT, in line with the rest of the `@valve-tech/*` toolkit. The
+upstream `trueblocks-core` project is GPL-3.0-or-later, but this
+package is a clean-room TypeScript reimplementation against the
+public OpenAPI spec — no GPL code is incorporated. See the
+`LICENSE` file for full terms.

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import type { paths } from './generated.js';
+import { type Verbs } from './verbs.js';
+export type FetchFn = typeof globalThis.fetch;
+export interface CreateTrueblocksClientOptions {
+    /**
+     * Base URL of the chifra daemon, e.g. `'http://localhost:8080'`.
+     * A trailing slash is allowed and stripped.
+     */
+    baseUrl: string;
+    /**
+     * Optional fetch override. Defaults to `globalThis.fetch`. Useful
+     * for tests, custom transports, or environments that need to wrap
+     * the fetch call (auth headers, retry, instrumentation).
+     */
+    fetch?: FetchFn;
+}
+/**
+ * Internal request function used by every verb. Verbs are pure
+ * factories that take this and return their typed callable — tests
+ * inject a mock to exercise verb logic without hitting fetch.
+ */
+export type RequestFn = <R>(path: keyof paths, query?: Record<string, unknown>) => Promise<R>;
+export type TrueblocksClient = Verbs;
+export declare function createTrueblocksClient(options: CreateTrueblocksClientOptions): TrueblocksClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,YAAY,CAAA;AAEpD,MAAM,MAAM,OAAO,GAAG,OAAO,UAAU,CAAC,KAAK,CAAA;AAE7C,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,KAAK,EACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,CAAC,CAAC,CAAA;AAEf,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAA;AAEpC,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,gBAAgB,CAyClB"}

package/dist/client.js

@@ -0,0 +1,35 @@
+import { TrueblocksError } from './errors.js';
+import { createVerbs } from './verbs.js';
+export function createTrueblocksClient(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, '');
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    const request = async (path, query) => {
+        const url = new URL(baseUrl + path);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value === undefined || value === null)
+                    continue;
+                if (Array.isArray(value)) {
+                    for (const item of value)
+                        url.searchParams.append(key, String(item));
+                }
+                else {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        let response;
+        try {
+            response = await fetchFn(url.toString());
+        }
+        catch (err) {
+            throw new TrueblocksError(`chifra request to ${path} failed: ${err.message}`, { path: path, cause: err });
+        }
+        if (!response.ok) {
+            throw new TrueblocksError(`chifra ${path} returned ${response.status} ${response.statusText}`, { path: path, status: response.status });
+        }
+        return response.json();
+    };
+    return createVerbs(request);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EAAE,WAAW,EAAc,MAAM,YAAY,CAAA;AA8BpD,MAAM,UAAU,sBAAsB,CACpC,OAAsC;IAEtC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAA;IAEjD,MAAM,OAAO,GAAc,KAAK,EAC9B,IAAiB,EACjB,KAA+B,EACnB,EAAE;QACd,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,GAAI,IAAe,CAAC,CAAA;QAC/C,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;oBAAE,SAAQ;gBACnD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzB,KAAK,MAAM,IAAI,IAAI,KAAK;wBAAE,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;gBACtE,CAAC;qBAAM,CAAC;oBACN,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;gBAC1C,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,QAAkB,CAAA;QACtB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,eAAe,CACvB,qBAAqB,IAAc,YAAa,GAAa,CAAC,OAAO,EAAE,EACvE,EAAE,IAAI,EAAE,IAAc,EAAE,KAAK,EAAE,GAAG,EAAE,CACrC,CAAA;QACH,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,eAAe,CACvB,UAAU,IAAc,aAAa,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,EAC7E,EAAE,IAAI,EAAE,IAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAClD,CAAA;QACH,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAgB,CAAA;IACtC,CAAC,CAAA;IAED,OAAO,WAAW,CAAC,OAAO,CAAC,CAAA;AAC7B,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Error class for failures originating from the chifra daemon, or
+ * from the network transport between this client and the daemon.
+ *
+ * - `path` always holds the chifra endpoint that failed
+ *   (e.g. `'/status'`, `'/blocks'`).
+ * - `status` is set when the daemon responded with a non-2xx HTTP
+ *   status; absent when the failure was at the transport layer
+ *   (DNS, connection refused, fetch threw).
+ * - `cause` is set when wrapping a transport-layer error so callers
+ *   can drill into the original failure if needed.
+ */
+export declare class TrueblocksError extends Error {
+    readonly path: string;
+    readonly status?: number;
+    constructor(message: string, init: {
+        path: string;
+        status?: number;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;gBAGtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAW3D"}

package/dist/errors.js

@@ -0,0 +1,26 @@
+/**
+ * Error class for failures originating from the chifra daemon, or
+ * from the network transport between this client and the daemon.
+ *
+ * - `path` always holds the chifra endpoint that failed
+ *   (e.g. `'/status'`, `'/blocks'`).
+ * - `status` is set when the daemon responded with a non-2xx HTTP
+ *   status; absent when the failure was at the transport layer
+ *   (DNS, connection refused, fetch threw).
+ * - `cause` is set when wrapping a transport-layer error so callers
+ *   can drill into the original failure if needed.
+ */
+export class TrueblocksError extends Error {
+    constructor(message, init) {
+        super(message);
+        this.name = 'TrueblocksError';
+        this.path = init.path;
+        this.status = init.status;
+        if (init.cause !== undefined) {
+            // ES2022 Error.cause; assigned post-super for ES2020 target compat.
+            ;
+            this.cause = init.cause;
+        }
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAIxC,YACE,OAAe,EACf,IAAwD;QAExD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,oEAAoE;YACpE,CAAC;YAAC,IAA4B,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACnD,CAAC;IACH,CAAC;CACF"}