@spectratools/cli-shared 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spectra-the-bot
+
+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,218 @@
+# @spectra-the-bot/cli-shared
+
+Shared middleware, utilities, and testing helpers used across `@spectra-the-bot` CLI packages.
+
+## Installation
+
+```bash
+pnpm add @spectra-the-bot/cli-shared
+```
+
+## Import paths
+
+```ts
+import { ... } from '@spectra-the-bot/cli-shared';
+import { ... } from '@spectra-the-bot/cli-shared/middleware';
+import { ... } from '@spectra-the-bot/cli-shared/utils';
+import { ... } from '@spectra-the-bot/cli-shared/testing';
+```
+
+---
+
+## Middleware
+
+### `apiKeyAuth` + `MissingApiKeyError` (auth)
+
+Reads an API key from an env var and throws a typed error if missing.
+
+```ts
+import { apiKeyAuth, MissingApiKeyError } from '@spectra-the-bot/cli-shared/middleware';
+
+try {
+  const { apiKey } = apiKeyAuth('ETHERSCAN_API_KEY');
+  // use apiKey in request headers
+} catch (err) {
+  if (err instanceof MissingApiKeyError) {
+    console.error(err.message);
+  }
+}
+```
+
+---
+
+### `withRetry` (retry)
+
+Wraps async calls with exponential backoff + jitter.
+
+- Retries up to `maxRetries`
+- Delay grows from `baseMs` to `maxMs`
+- For `HttpError` 429/503, respects `Retry-After` headers
+
+```ts
+import { withRetry } from '@spectra-the-bot/cli-shared/middleware';
+
+const result = await withRetry(
+  () => fetch('https://example.com/data').then((r) => r.json()),
+  {
+    maxRetries: 4,
+    baseMs: 200,
+    maxMs: 5_000,
+  },
+);
+```
+
+---
+
+### `createRateLimiter` + `withRateLimit` (rate-limit)
+
+Token-bucket rate limiter for request throughput control.
+
+```ts
+import { createRateLimiter, withRateLimit } from '@spectra-the-bot/cli-shared/middleware';
+
+const acquire = createRateLimiter({ requestsPerSecond: 5 });
+
+const data = await withRateLimit(
+  () => fetch('https://example.com/items').then((r) => r.json()),
+  acquire,
+);
+```
+
+---
+
+### `paginateCursor` + `paginateOffset` (pagination)
+
+Async iterators that flatten paged APIs.
+
+#### Cursor pagination
+
+```ts
+import { paginateCursor } from '@spectra-the-bot/cli-shared/middleware';
+
+for await (const item of paginateCursor({
+  fetchPage: async (cursor) => {
+    const res = await fetch(`/api/items?cursor=${cursor ?? ''}`).then((r) => r.json());
+    return { items: res.items, nextCursor: res.nextCursor };
+  },
+})) {
+  console.log(item);
+}
+```
+
+#### Offset pagination
+
+```ts
+import { paginateOffset } from '@spectra-the-bot/cli-shared/middleware';
+
+for await (const item of paginateOffset({
+  limit: 100,
+  fetchPage: async (offset, limit) => {
+    const res = await fetch(`/api/items?offset=${offset}&limit=${limit}`).then((r) => r.json());
+    return { items: res.items, total: res.total };
+  },
+})) {
+  console.log(item);
+}
+```
+
+---
+
+## Utils
+
+### `createHttpClient` + `HttpError` (http client)
+
+Typed fetch wrapper with:
+
+- `baseUrl`
+- default and per-request headers
+- query serialization
+- JSON request body encoding
+- `HttpError` on non-2xx responses
+
+```ts
+import { createHttpClient, HttpError } from '@spectra-the-bot/cli-shared/utils';
+
+type Proposal = { id: string; title: string };
+
+const client = createHttpClient({
+  baseUrl: 'https://api.assembly.abs.xyz',
+  defaultHeaders: {
+    'X-Api-Key': process.env.ASSEMBLY_API_KEY ?? '',
+  },
+});
+
+try {
+  const proposals = await client.request<Proposal[]>('/v1/proposals', {
+    query: { status: 'active' },
+  });
+  console.log(proposals);
+} catch (err) {
+  if (err instanceof HttpError) {
+    console.error(err.status, err.statusText, err.body);
+  }
+}
+```
+
+---
+
+### Format helpers (`weiToEth`, `checksumAddress`, `formatTimestamp`, `truncate`) (format)
+
+```ts
+import {
+  weiToEth,
+  checksumAddress,
+  formatTimestamp,
+  truncate,
+} from '@spectra-the-bot/cli-shared/utils';
+
+weiToEth('1234500000000000000');
+// => "1.2345"
+
+checksumAddress('0x742d35cc6634c0532925a3b844bc454e4438f44e');
+// => EIP-55 checksummed address
+
+formatTimestamp(1700000000);
+// => "2023-11-14T22:13:20.000Z"
+
+truncate('0x742d35cc6634c0532925a3b844bc454e4438f44e');
+// => "0x742d...f44e"
+```
+
+---
+
+## Testing
+
+### `createMockServer` (mock-server)
+
+Spin up a lightweight local HTTP server for integration tests.
+
+- Configure route responses (`addRoute`)
+- Record incoming requests (`requests`)
+- Cleanly close after tests (`close`)
+
+```ts
+import { createMockServer } from '@spectra-the-bot/cli-shared/testing';
+
+const server = await createMockServer();
+
+server.addRoute('GET', '/v1/proposals', {
+  status: 200,
+  body: [{ id: '1', title: 'Test Proposal' }],
+});
+
+const res = await fetch(`${server.url}/v1/proposals`);
+const data = await res.json();
+
+console.log(data);
+console.log(server.requests[0]); // method/url/headers/body
+
+await server.close();
+```
+
+---
+
+## Export summary
+
+- **Middleware**: `apiKeyAuth`, `MissingApiKeyError`, `withRetry`, `createRateLimiter`, `withRateLimit`, `paginateCursor`, `paginateOffset`
+- **Utils**: `createHttpClient`, `HttpError`, `weiToEth`, `checksumAddress`, `formatTimestamp`, `truncate`
+- **Testing**: `createMockServer`

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+declare class MissingApiKeyError extends Error {
+    constructor(envVar: string);
+}
+interface ApiKeyAuthContext {
+    apiKey: string;
+}
+/**
+ * Reads an API key from the environment and returns it.
+ * Throws MissingApiKeyError if the variable is not set.
+ */
+declare function apiKeyAuth(envVar: string): ApiKeyAuthContext;
+
+interface CursorPaginationOptions<T> {
+    fetchPage: (cursor: string | null) => Promise<{
+        items: T[];
+        nextCursor: string | null;
+    }>;
+}
+interface OffsetPaginationOptions<T> {
+    fetchPage: (offset: number, limit: number) => Promise<{
+        items: T[];
+        total: number;
+    }>;
+    limit?: number;
+}
+/**
+ * Async iterator for cursor-based pagination.
+ */
+declare function paginateCursor<T>(options: CursorPaginationOptions<T>): AsyncGenerator<T>;
+/**
+ * Async iterator for offset-based pagination.
+ */
+declare function paginateOffset<T>(options: OffsetPaginationOptions<T>): AsyncGenerator<T>;
+
+interface RateLimitOptions {
+    requestsPerSecond: number;
+}
+/**
+ * Token bucket rate limiter. Returns a function that must be called
+ * before each request; it resolves when the request is allowed.
+ */
+declare function createRateLimiter(options: RateLimitOptions): () => Promise<void>;
+/**
+ * Wraps a fetch-like function with token bucket rate limiting.
+ */
+declare function withRateLimit<T>(fn: () => Promise<T>, acquire: () => Promise<void>): Promise<T>;
+
+interface RetryOptions {
+    maxRetries: number;
+    baseMs: number;
+    maxMs: number;
+}
+/**
+ * Wraps a fetch-like function with exponential backoff retry logic.
+ * Respects Retry-After headers on 429/503 responses.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+
+interface RecordedRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+}
+interface MockResponse {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+interface MockServer {
+    url: string;
+    requests: RecordedRequest[];
+    addRoute(method: string, path: string, response: MockResponse): void;
+    close(): Promise<void>;
+}
+/**
+ * Creates a lightweight HTTP mock server for integration testing.
+ * Records all incoming requests and returns configured fixture responses.
+ */
+declare function createMockServer(): Promise<MockServer>;
+
+/**
+ * Converts wei (as bigint or string) to a human-readable ETH string.
+ */
+declare function weiToEth(wei: bigint | string, decimals?: number): string;
+/**
+ * Checksums an Ethereum address using EIP-55.
+ * Accepts lowercase or mixed-case hex addresses.
+ */
+declare function checksumAddress(address: string): string;
+/**
+ * Formats a Unix timestamp (seconds) to a human-readable string.
+ */
+declare function formatTimestamp(unixSeconds: number): string;
+/**
+ * Truncates a string in the middle, e.g. "0x1234...abcd".
+ */
+declare function truncate(str: string, prefixLen?: number, suffixLen?: number): string;
+
+interface HttpClientOptions {
+    baseUrl: string;
+    defaultHeaders?: Record<string, string>;
+}
+interface RequestOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+}
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    readonly headers: Headers;
+    constructor(status: number, statusText: string, body: string, headers?: Headers);
+}
+/**
+ * Typed fetch wrapper with base URL, default headers, query serialization, and error handling.
+ */
+declare function createHttpClient(options: HttpClientOptions): {
+    request: <T>(path: string, opts?: RequestOptions) => Promise<T>;
+};
+
+export { type ApiKeyAuthContext, type CursorPaginationOptions, type HttpClientOptions, HttpError, MissingApiKeyError, type MockResponse, type MockServer, type OffsetPaginationOptions, type RateLimitOptions, type RecordedRequest, type RequestOptions, type RetryOptions, apiKeyAuth, checksumAddress, createHttpClient, createMockServer, createRateLimiter, formatTimestamp, paginateCursor, paginateOffset, truncate, weiToEth, withRateLimit, withRetry };

package/dist/index.js

@@ -0,0 +1,257 @@
+// src/middleware/auth.ts
+var MissingApiKeyError = class extends Error {
+  constructor(envVar) {
+    super(`Missing required API key. Set the ${envVar} environment variable.`);
+    this.name = "MissingApiKeyError";
+  }
+};
+function apiKeyAuth(envVar) {
+  const apiKey = process.env[envVar];
+  if (!apiKey) {
+    throw new MissingApiKeyError(envVar);
+  }
+  return { apiKey };
+}
+
+// src/middleware/pagination.ts
+async function* paginateCursor(options) {
+  let cursor = null;
+  while (true) {
+    const { items, nextCursor } = await options.fetchPage(cursor);
+    for (const item of items) {
+      yield item;
+    }
+    if (!nextCursor) break;
+    cursor = nextCursor;
+  }
+}
+async function* paginateOffset(options) {
+  const limit = options.limit ?? 100;
+  let offset = 0;
+  while (true) {
+    const { items, total } = await options.fetchPage(offset, limit);
+    for (const item of items) {
+      yield item;
+    }
+    offset += items.length;
+    if (offset >= total || items.length === 0) break;
+  }
+}
+
+// src/middleware/rate-limit.ts
+function createRateLimiter(options) {
+  const { requestsPerSecond } = options;
+  const intervalMs = 1e3 / requestsPerSecond;
+  const queue = [];
+  let tokens = requestsPerSecond;
+  let lastRefill = Date.now();
+  let processingInterval = null;
+  function refill() {
+    const now = Date.now();
+    const elapsed = now - lastRefill;
+    const newTokens = elapsed / 1e3 * requestsPerSecond;
+    tokens = Math.min(requestsPerSecond, tokens + newTokens);
+    lastRefill = now;
+  }
+  function processQueue() {
+    refill();
+    while (queue.length > 0 && tokens >= 1) {
+      tokens -= 1;
+      const resolve = queue.shift();
+      resolve?.();
+    }
+    if (queue.length === 0 && processingInterval !== null) {
+      clearInterval(processingInterval);
+      processingInterval = null;
+    }
+  }
+  return () => {
+    return new Promise((resolve) => {
+      refill();
+      if (tokens >= 1) {
+        tokens -= 1;
+        resolve();
+        return;
+      }
+      queue.push(resolve);
+      if (processingInterval === null) {
+        processingInterval = setInterval(processQueue, intervalMs);
+      }
+    });
+  };
+}
+function withRateLimit(fn, acquire) {
+  return acquire().then(() => fn());
+}
+
+// src/utils/http.ts
+var HttpError = class extends Error {
+  constructor(status, statusText, body, headers = new Headers()) {
+    super(`HTTP ${status} ${statusText}: ${body}`);
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+    this.headers = headers;
+    this.name = "HttpError";
+  }
+};
+function serializeQuery(params) {
+  const parts = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+  }
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+function createHttpClient(options) {
+  const { baseUrl, defaultHeaders = {} } = options;
+  async function request(path, opts = {}) {
+    const { method = "GET", headers = {}, query = {}, body } = opts;
+    const qs = serializeQuery(query);
+    const url = `${baseUrl}${path}${qs}`;
+    const init = {
+      method
+    };
+    const mergedHeaders = {
+      ...defaultHeaders,
+      ...headers
+    };
+    if (body !== void 0) {
+      mergedHeaders["Content-Type"] ??= "application/json";
+      init.body = JSON.stringify(body);
+    }
+    init.headers = mergedHeaders;
+    const res = await fetch(url, init);
+    if (!res.ok) {
+      const text = await res.text();
+      throw new HttpError(res.status, res.statusText, text, res.headers);
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      return res.json();
+    }
+    return res.text();
+  }
+  return { request };
+}
+
+// src/middleware/retry.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function jitter(ms) {
+  return ms * (0.5 + Math.random() * 0.5);
+}
+function parseRetryAfter(headers) {
+  const retryAfter = headers.get("Retry-After");
+  if (!retryAfter) return null;
+  const seconds = Number(retryAfter);
+  if (!Number.isNaN(seconds)) return seconds * 1e3;
+  const date = Date.parse(retryAfter);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return null;
+}
+async function withRetry(fn, options) {
+  const { maxRetries, baseMs, maxMs } = options;
+  let attempt = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= maxRetries) throw err;
+      let delayMs;
+      if (err instanceof HttpError && (err.status === 429 || err.status === 503)) {
+        const retryAfterMs = parseRetryAfter(err.headers);
+        delayMs = retryAfterMs ?? Math.min(baseMs * 2 ** attempt, maxMs);
+      } else {
+        delayMs = Math.min(baseMs * 2 ** attempt, maxMs);
+      }
+      await sleep(jitter(delayMs));
+      attempt++;
+    }
+  }
+}
+
+// src/testing/mock-server.ts
+import { createServer } from "http";
+async function createMockServer() {
+  const routes = /* @__PURE__ */ new Map();
+  const requests = [];
+  const server = createServer((req, res) => {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      const recorded = {
+        method: req.method ?? "GET",
+        url: req.url ?? "/",
+        headers: req.headers,
+        body
+      };
+      requests.push(recorded);
+      const key = `${recorded.method}:${recorded.url.split("?")[0]}`;
+      const mock = routes.get(key) ?? routes.get("*");
+      const status = mock?.status ?? 200;
+      const responseHeaders = mock?.headers ?? { "Content-Type": "application/json" };
+      const responseBody = mock?.body !== void 0 ? JSON.stringify(mock.body) : "{}";
+      res.writeHead(status, responseHeaders);
+      res.end(responseBody);
+    });
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new Error("Failed to get server address");
+  }
+  return {
+    url: `http://127.0.0.1:${address.port}`,
+    requests,
+    addRoute(method, path, response) {
+      routes.set(`${method.toUpperCase()}:${path}`, response);
+    },
+    close() {
+      return new Promise((resolve, reject) => {
+        server.close((err) => err ? reject(err) : resolve());
+      });
+    }
+  };
+}
+
+// src/utils/format.ts
+import { Address } from "ox";
+var ETH_DECIMALS = 18n;
+var WEI_PER_ETH = 10n ** ETH_DECIMALS;
+function weiToEth(wei, decimals = 6) {
+  const weiValue = typeof wei === "string" ? BigInt(wei) : wei;
+  const whole = weiValue / WEI_PER_ETH;
+  const frac = weiValue % WEI_PER_ETH;
+  const fracStr = frac.toString().padStart(18, "0").slice(0, decimals).replace(/0+$/, "");
+  return fracStr.length > 0 ? `${whole}.${fracStr}` : `${whole}`;
+}
+function checksumAddress(address) {
+  return Address.checksum(address);
+}
+function formatTimestamp(unixSeconds) {
+  return new Date(unixSeconds * 1e3).toISOString();
+}
+function truncate(str, prefixLen = 6, suffixLen = 4) {
+  if (str.length <= prefixLen + suffixLen + 3) return str;
+  return `${str.slice(0, prefixLen)}...${str.slice(-suffixLen)}`;
+}
+export {
+  HttpError,
+  MissingApiKeyError,
+  apiKeyAuth,
+  checksumAddress,
+  createHttpClient,
+  createMockServer,
+  createRateLimiter,
+  formatTimestamp,
+  paginateCursor,
+  paginateOffset,
+  truncate,
+  weiToEth,
+  withRateLimit,
+  withRetry
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@spectratools/cli-shared",
+  "version": "0.1.0",
+  "description": "Shared middleware, utilities, and testing helpers for spectra CLI tools",
+  "type": "module",
+  "license": "MIT",
+  "author": "spectra-the-bot",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./middleware": {
+      "types": "./src/middleware/index.ts",
+      "default": "./src/middleware/index.ts"
+    },
+    "./utils": {
+      "types": "./src/utils/index.ts",
+      "default": "./src/utils/index.ts"
+    },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "default": "./src/testing/index.ts"
+    }
+  },
+  "devDependencies": {
+    "typescript": "5.7.3",
+    "vitest": "2.1.8"
+  },
+  "dependencies": {
+    "ox": "^0.14.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}