@spectratools/cli-shared 0.2.0 → 0.4.0

package/README.md

@@ -211,8 +211,93 @@ await server.close();
 
 ---
 
+## Telemetry (OpenTelemetry)
+
+Built-in OpenTelemetry instrumentation for distributed tracing and metrics. Zero overhead when disabled — OTEL modules are lazy-loaded only when telemetry is active.
+
+### Initialize telemetry
+
+```ts
+import { initTelemetry, shutdownTelemetry } from '@spectra-the-bot/cli-shared/telemetry';
+
+// Initialize at CLI startup — no-op if OTEL env vars are not set
+initTelemetry('my-cli');
+
+// Shut down gracefully at exit — safe to call even if never initialized
+await shutdownTelemetry();
+```
+
+Telemetry is enabled when `OTEL_EXPORTER_OTLP_ENDPOINT` is set or `SPECTRA_OTEL_ENABLED=true`.
+
+### Command spans
+
+```ts
+import { createCommandSpan, withCommandSpan } from '@spectra-the-bot/cli-shared/telemetry';
+
+// Option 1: Manual span management
+const span = createCommandSpan('account balance', { address: '0x...', format: 'json' });
+try {
+  // ... execute command
+  span.setStatus({ code: SpanStatusCode.OK });
+} catch (err) {
+  recordError(span, err);
+  throw err;
+} finally {
+  span.end();
+}
+
+// Option 2: Automatic span lifecycle
+const result = await withCommandSpan('account balance', { address: '0x...' }, async () => {
+  // ... execute command
+  return data;
+});
+```
+
+### Child spans
+
+```ts
+import { withSpan } from '@spectra-the-bot/cli-shared/telemetry';
+
+const result = await withSpan('parse-response', async (span) => {
+  // span is automatically ended and errors are recorded
+  return parseData(raw);
+});
+```
+
+### HTTP spans (automatic)
+
+The `createHttpClient` utility automatically creates child spans for every HTTP request when OTEL is active:
+
+```ts
+import { createHttpClient } from '@spectra-the-bot/cli-shared/utils';
+
+const client = createHttpClient({ baseUrl: 'https://api.example.com' });
+
+// This request automatically creates an HTTP span with method, URL, and status code
+const data = await client.request('/v1/items');
+```
+
+### Attribute sanitization
+
+Span attributes are automatically sanitized — keys or values matching sensitive patterns (private keys, passwords, API keys, mnemonics, tokens, secrets) are stripped before being attached to spans.
+
+```ts
+import { sanitizeAttributes } from '@spectra-the-bot/cli-shared/telemetry';
+
+const safe = sanitizeAttributes({
+  address: '0x1234',      // ✓ kept
+  private_key: '0xdead',  // ✗ stripped
+  api_key: 'sk-secret',   // ✗ stripped
+  format: 'json',         // ✓ kept
+});
+// => { address: '0x1234', format: 'json' }
+```
+
+---
+
 ## Export summary
 
 - **Middleware**: `apiKeyAuth`, `MissingApiKeyError`, `withRetry`, `createRateLimiter`, `withRateLimit`, `paginateCursor`, `paginateOffset`
 - **Utils**: `createHttpClient`, `HttpError`, `weiToEth`, `checksumAddress`, `formatTimestamp`, `truncate`
+- **Telemetry**: `initTelemetry`, `shutdownTelemetry`, `createCommandSpan`, `withCommandSpan`, `withSpan`, `recordError`, `sanitizeAttributes`, `createHttpSpan`, `endHttpSpan`, `endHttpSpanWithError`, `extractPath`
 - **Testing**: `createMockServer`

package/dist/{chunk-TKORXDDX.js → chunk-BBONIM34.js}

@@ -1,4 +1,11 @@
+import {
+  createHttpSpan,
+  endHttpSpan,
+  endHttpSpanWithError
+} from "./chunk-G7AGMLZE.js";
+
 // src/utils/http.ts
+import { context } from "@opentelemetry/api";
 var HttpError = class extends Error {
   constructor(status, statusText, body, headers = new Headers()) {
     super(`HTTP ${status} ${statusText}: ${body}`);
@@ -35,16 +42,31 @@ function createHttpClient(options) {
       init.body = JSON.stringify(body);
     }
     init.headers = mergedHeaders;
-    const res = await fetch(url, init);
-    if (!res.ok) {
+    const { span, ctx } = createHttpSpan(method, url);
+    try {
+      const res = await context.with(ctx, () => fetch(url, init));
+      if (!res.ok) {
+        const text2 = await res.text();
+        const err = new HttpError(res.status, res.statusText, text2, res.headers);
+        endHttpSpanWithError(span, err, res.status);
+        throw err;
+      }
+      const contentLength = res.headers.get("content-length");
+      const contentType = res.headers.get("content-type") ?? "";
+      if (contentType.includes("application/json")) {
+        const data = await res.json();
+        endHttpSpan(span, res.status, contentLength ? Number(contentLength) : void 0);
+        return data;
+      }
       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();
+      endHttpSpan(span, res.status, contentLength ? Number(contentLength) : void 0);
+      return text;
+    } catch (err) {
+      if (!(err instanceof HttpError)) {
+        endHttpSpanWithError(span, err);
+      }
+      throw err;
     }
-    return res.text();
   }
   return { request };
 }

package/dist/chunk-G7AGMLZE.js

@@ -0,0 +1,136 @@
+// src/telemetry/spans.ts
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+import {
+  ATTR_HTTP_REQUEST_METHOD,
+  ATTR_HTTP_RESPONSE_STATUS_CODE,
+  ATTR_URL_FULL,
+  ATTR_URL_PATH
+} from "@opentelemetry/semantic-conventions";
+var TRACER_NAME = "@spectratools/cli-shared";
+var SENSITIVE_PATTERNS = [
+  /private[\s_-]?key/i,
+  /secret/i,
+  /password/i,
+  /passphrase/i,
+  /mnemonic/i,
+  /seed/i,
+  /token/i,
+  /api[\s_-]?key/i,
+  /auth/i
+];
+function sanitizeAttributes(attrs) {
+  const result = {};
+  for (const [key, value] of Object.entries(attrs)) {
+    const strKey = key.toLowerCase();
+    const strVal = typeof value === "string" ? value : "";
+    const isSensitive = SENSITIVE_PATTERNS.some(
+      (p) => p.test(strKey) || strVal.length > 0 && p.test(strVal)
+    );
+    if (isSensitive) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      result[key] = value;
+    } else if (value !== void 0 && value !== null) {
+      result[key] = String(value);
+    }
+  }
+  return result;
+}
+function createCommandSpan(commandName, args) {
+  const tracer = trace.getTracer(TRACER_NAME);
+  const span = tracer.startSpan(`cli.command.${commandName}`);
+  if (args) {
+    const safe = sanitizeAttributes(args);
+    for (const [k, v] of Object.entries(safe)) {
+      span.setAttribute(`cli.arg.${k}`, v);
+    }
+  }
+  return span;
+}
+async function withCommandSpan(commandPath, args, fn) {
+  const span = createCommandSpan(commandPath, args);
+  try {
+    const result = await fn();
+    span.setStatus({ code: SpanStatusCode.OK });
+    return result;
+  } catch (err) {
+    recordError(span, err);
+    throw err;
+  } finally {
+    span.end();
+  }
+}
+async function withSpan(name, fn) {
+  const tracer = trace.getTracer(TRACER_NAME);
+  const span = tracer.startSpan(name);
+  const ctx = trace.setSpan(context.active(), span);
+  try {
+    const result = await context.with(ctx, () => fn(span));
+    span.setStatus({ code: SpanStatusCode.OK });
+    return result;
+  } catch (err) {
+    recordError(span, err);
+    throw err;
+  } finally {
+    span.end();
+  }
+}
+function recordError(span, error) {
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error instanceof Error ? error.message : String(error)
+  });
+  if (error instanceof Error) {
+    span.recordException(error);
+  } else {
+    span.recordException(new Error(String(error)));
+  }
+}
+function extractPath(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    const qIndex = url.indexOf("?");
+    return qIndex >= 0 ? url.slice(0, qIndex) : url;
+  }
+}
+function createHttpSpan(method, url) {
+  const tracer = trace.getTracer(TRACER_NAME);
+  const path = extractPath(url);
+  const span = tracer.startSpan(`HTTP ${method} ${path}`, {
+    kind: SpanKind.CLIENT,
+    attributes: {
+      [ATTR_HTTP_REQUEST_METHOD]: method,
+      [ATTR_URL_FULL]: url,
+      [ATTR_URL_PATH]: path
+    }
+  });
+  const ctx = trace.setSpan(context.active(), span);
+  return { span, ctx };
+}
+function endHttpSpan(span, statusCode, contentLength) {
+  span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, statusCode);
+  if (contentLength !== void 0) {
+    span.setAttribute("http.response_content_length", contentLength);
+  }
+  span.setStatus({ code: SpanStatusCode.OK });
+  span.end();
+}
+function endHttpSpanWithError(span, error, statusCode) {
+  if (statusCode !== void 0) {
+    span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, statusCode);
+  }
+  recordError(span, error);
+  span.end();
+}
+
+export {
+  sanitizeAttributes,
+  createCommandSpan,
+  withCommandSpan,
+  withSpan,
+  recordError,
+  extractPath,
+  createHttpSpan,
+  endHttpSpan,
+  endHttpSpanWithError
+};

package/dist/{chunk-74BQLM22.js → chunk-I2D7COI7.js}

@@ -1,6 +1,9 @@
 import {
   HttpError
-} from "./chunk-TKORXDDX.js";
+} from "./chunk-BBONIM34.js";
+import {
+  recordError
+} from "./chunk-G7AGMLZE.js";
 
 // src/middleware/auth.ts
 var MissingApiKeyError = class extends Error {
@@ -43,6 +46,7 @@ async function* paginateOffset(options) {
 }
 
 // src/middleware/rate-limit.ts
+import { trace } from "@opentelemetry/api";
 function createRateLimiter(options) {
   const { requestsPerSecond } = options;
   const intervalMs = 1e3 / requestsPerSecond;
@@ -85,10 +89,21 @@ function createRateLimiter(options) {
   };
 }
 function withRateLimit(fn, acquire) {
-  return acquire().then(() => fn());
+  const start = Date.now();
+  return acquire().then(() => {
+    const waitMs = Date.now() - start;
+    if (waitMs > 0) {
+      const activeSpan = trace.getActiveSpan();
+      if (activeSpan) {
+        activeSpan.setAttribute("rate_limit.wait_ms", waitMs);
+      }
+    }
+    return fn();
+  });
 }
 
 // src/middleware/retry.ts
+import { trace as trace2 } from "@opentelemetry/api";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -111,7 +126,13 @@ async function withRetry(fn, options) {
     try {
       return await fn();
     } catch (err) {
-      if (attempt >= maxRetries) throw err;
+      if (attempt >= maxRetries) {
+        const activeSpan2 = trace2.getActiveSpan();
+        if (activeSpan2) {
+          recordError(activeSpan2, err);
+        }
+        throw err;
+      }
       let delayMs;
       if (err instanceof HttpError && (err.status === 429 || err.status === 503)) {
         const retryAfterMs = parseRetryAfter(err.headers);
@@ -119,8 +140,18 @@ async function withRetry(fn, options) {
       } else {
         delayMs = Math.min(baseMs * 2 ** attempt, maxMs);
       }
-      await sleep(jitter(delayMs));
+      const actualDelay = jitter(delayMs);
       attempt++;
+      const activeSpan = trace2.getActiveSpan();
+      if (activeSpan) {
+        activeSpan.setAttribute("retry.attempt", attempt);
+        activeSpan.addEvent("retry", {
+          attempt,
+          delay_ms: Math.round(actualDelay),
+          reason: err instanceof Error ? err.message : String(err)
+        });
+      }
+      await sleep(actualDelay);
     }
   }
 }

package/dist/{chunk-YWGC33UJ.js → chunk-S4AQMOWL.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@spectratools/cli-shared",
-      version: "0.2.0",
+      version: "0.4.0",
       description: "Shared middleware, utilities, and testing helpers for spectra CLI tools",
       type: "module",
       license: "MIT",
@@ -116,75 +116,6 @@ function _getSdk() {
   return sdk;
 }
 
-// src/telemetry/spans.ts
-import { SpanStatusCode, context, trace } from "@opentelemetry/api";
-var TRACER_NAME = "@spectratools/cli-shared";
-var SENSITIVE_PATTERNS = [
-  /private[\s_-]?key/i,
-  /secret/i,
-  /password/i,
-  /passphrase/i,
-  /mnemonic/i,
-  /seed/i,
-  /token/i,
-  /api[\s_-]?key/i,
-  /auth/i
-];
-function sanitizeAttributes(attrs) {
-  const result = {};
-  for (const [key, value] of Object.entries(attrs)) {
-    const strKey = key.toLowerCase();
-    const strVal = typeof value === "string" ? value : "";
-    const isSensitive = SENSITIVE_PATTERNS.some(
-      (p) => p.test(strKey) || strVal.length > 0 && p.test(strVal)
-    );
-    if (isSensitive) continue;
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-      result[key] = value;
-    } else if (value !== void 0 && value !== null) {
-      result[key] = String(value);
-    }
-  }
-  return result;
-}
-function createCommandSpan(commandName, args) {
-  const tracer = trace.getTracer(TRACER_NAME);
-  const span = tracer.startSpan(`cli.command.${commandName}`);
-  if (args) {
-    const safe = sanitizeAttributes(args);
-    for (const [k, v] of Object.entries(safe)) {
-      span.setAttribute(`cli.arg.${k}`, v);
-    }
-  }
-  return span;
-}
-async function withSpan(name, fn) {
-  const tracer = trace.getTracer(TRACER_NAME);
-  const span = tracer.startSpan(name);
-  const ctx = trace.setSpan(context.active(), span);
-  try {
-    const result = await context.with(ctx, () => fn(span));
-    span.setStatus({ code: SpanStatusCode.OK });
-    return result;
-  } catch (err) {
-    recordError(span, err);
-    throw err;
-  } finally {
-    span.end();
-  }
-}
-function recordError(span, error) {
-  span.setStatus({
-    code: SpanStatusCode.ERROR,
-    message: error instanceof Error ? error.message : String(error)
-  });
-  if (error instanceof Error) {
-    span.recordException(error);
-  } else {
-    span.recordException(new Error(String(error)));
-  }
-}
-
 // src/telemetry/shutdown.ts
 async function shutdownTelemetry() {
   const sdk2 = _getSdk();
@@ -194,8 +125,5 @@ async function shutdownTelemetry() {
 
 export {
   initTelemetry,
-  createCommandSpan,
-  withSpan,
-  recordError,
   shutdownTelemetry
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ApiKeyAuthContext, CursorPaginationOptions, MissingApiKeyError, OffsetPaginationOptions, RateLimitOptions, RetryOptions, apiKeyAuth, createRateLimiter, paginateCursor, paginateOffset, withRateLimit, withRetry } from './middleware/index.js';
-export { createCommandSpan, initTelemetry, recordError, shutdownTelemetry, withSpan } from './telemetry/index.js';
+export { createCommandSpan, createHttpSpan, endHttpSpan, endHttpSpanWithError, extractPath, initTelemetry, recordError, sanitizeAttributes, shutdownTelemetry, withCommandSpan, withSpan } from './telemetry/index.js';
 export { MockResponse, MockServer, RecordedRequest, createMockServer } from './testing/index.js';
 export { HttpClientOptions, HttpError, RequestOptions, checksumAddress, createHttpClient, formatTimestamp, isAddress, truncate, weiToEth } from './utils/index.js';
 import '@opentelemetry/api';

package/dist/index.js

@@ -6,14 +6,11 @@ import {
   paginateOffset,
   withRateLimit,
   withRetry
-} from "./chunk-74BQLM22.js";
+} from "./chunk-I2D7COI7.js";
 import {
-  createCommandSpan,
   initTelemetry,
-  recordError,
-  shutdownTelemetry,
-  withSpan
-} from "./chunk-YWGC33UJ.js";
+  shutdownTelemetry
+} from "./chunk-S4AQMOWL.js";
 import {
   createMockServer
 } from "./chunk-QEANTXUE.js";
@@ -27,7 +24,18 @@ import {
 import {
   HttpError,
   createHttpClient
-} from "./chunk-TKORXDDX.js";
+} from "./chunk-BBONIM34.js";
+import {
+  createCommandSpan,
+  createHttpSpan,
+  endHttpSpan,
+  endHttpSpanWithError,
+  extractPath,
+  recordError,
+  sanitizeAttributes,
+  withCommandSpan,
+  withSpan
+} from "./chunk-G7AGMLZE.js";
 import "./chunk-MCKGQKYU.js";
 export {
   HttpError,
@@ -36,17 +44,23 @@ export {
   checksumAddress,
   createCommandSpan,
   createHttpClient,
+  createHttpSpan,
   createMockServer,
   createRateLimiter,
+  endHttpSpan,
+  endHttpSpanWithError,
+  extractPath,
   formatTimestamp,
   initTelemetry,
   isAddress,
   paginateCursor,
   paginateOffset,
   recordError,
+  sanitizeAttributes,
   shutdownTelemetry,
   truncate,
   weiToEth,
+  withCommandSpan,
   withRateLimit,
   withRetry,
   withSpan

package/dist/middleware/index.d.ts

@@ -42,6 +42,7 @@ interface RateLimitOptions {
 declare function createRateLimiter(options: RateLimitOptions): () => Promise<void>;
 /**
  * Wraps a fetch-like function with token bucket rate limiting.
+ * Records wait time as a span attribute when OTEL is active.
  */
 declare function withRateLimit<T>(fn: () => Promise<T>, acquire: () => Promise<void>): Promise<T>;
 
@@ -53,6 +54,7 @@ interface RetryOptions {
 /**
  * Wraps a fetch-like function with exponential backoff retry logic.
  * Respects Retry-After headers on 429/503 responses.
+ * Records retry attempts as span events and attributes when OTEL is active.
  */
 declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
 

package/dist/middleware/index.js

@@ -6,8 +6,9 @@ import {
   paginateOffset,
   withRateLimit,
   withRetry
-} from "../chunk-74BQLM22.js";
-import "../chunk-TKORXDDX.js";
+} from "../chunk-I2D7COI7.js";
+import "../chunk-BBONIM34.js";
+import "../chunk-G7AGMLZE.js";
 import "../chunk-MCKGQKYU.js";
 export {
   MissingApiKeyError,

package/dist/telemetry/index.d.ts

@@ -1,4 +1,4 @@
-import { Span } from '@opentelemetry/api';
+import { Span, trace } from '@opentelemetry/api';
 
 /**
  * Initialize OpenTelemetry SDK for a CLI service.
@@ -11,6 +11,11 @@ import { Span } from '@opentelemetry/api';
  */
 declare function initTelemetry(serviceName: string): void;
 
+/**
+ * Sanitize a record of span attributes by stripping any key/value that looks
+ * like it contains a private key, password, or other sensitive material.
+ */
+declare function sanitizeAttributes(attrs: Record<string, unknown>): Record<string, string | number | boolean>;
 /**
  * Create a root span for a CLI command invocation.
  *
@@ -19,6 +24,17 @@ declare function initTelemetry(serviceName: string): void;
  * @returns A started `Span`. The caller is responsible for calling `span.end()`.
  */
 declare function createCommandSpan(commandName: string, args?: Record<string, unknown>): Span;
+/**
+ * Convenience wrapper that creates a root command span, executes `fn`, and
+ * automatically sets the span status and ends it. On error, the error is
+ * recorded on the span and re-thrown.
+ *
+ * @param commandPath - The command being executed (e.g. `"account balance"`).
+ * @param args - Key-value arguments to attach as sanitized span attributes.
+ * @param fn - Async function to execute within the span.
+ * @returns The result of `fn`.
+ */
+declare function withCommandSpan<T>(commandPath: string, args: Record<string, unknown>, fn: () => Promise<T>): Promise<T>;
 /**
  * Convenience wrapper that creates a child span, runs the given async function,
  * and automatically ends the span. On error, the error is recorded on the span
@@ -36,6 +52,29 @@ declare function withSpan<T>(name: string, fn: (span: Span) => Promise<T>): Prom
  * @param error - The error value (may be an `Error` instance or arbitrary value).
  */
 declare function recordError(span: Span, error: unknown): void;
+/**
+ * Extract the pathname from a URL string, stripping the base URL and query parameters.
+ */
+declare function extractPath(url: string): string;
+/**
+ * Create a child span for an HTTP client request.
+ *
+ * @param method - HTTP method (e.g. GET, POST).
+ * @param url - Full request URL.
+ * @returns An object with the started `span` and `ctx` for context propagation.
+ */
+declare function createHttpSpan(method: string, url: string): {
+    span: Span;
+    ctx: ReturnType<typeof trace.setSpan>;
+};
+/**
+ * Finalize an HTTP span with response details.
+ */
+declare function endHttpSpan(span: Span, statusCode: number, contentLength?: number): void;
+/**
+ * Finalize an HTTP span with an error.
+ */
+declare function endHttpSpanWithError(span: Span, error: unknown, statusCode?: number): void;
 
 /**
  * Flush pending spans/metrics and shut down the OTEL SDK.
@@ -44,4 +83,4 @@ declare function recordError(span: Span, error: unknown): void;
  */
 declare function shutdownTelemetry(): Promise<void>;
 
-export { createCommandSpan, initTelemetry, recordError, shutdownTelemetry, withSpan };
+export { createCommandSpan, createHttpSpan, endHttpSpan, endHttpSpanWithError, extractPath, initTelemetry, recordError, sanitizeAttributes, shutdownTelemetry, withCommandSpan, withSpan };

package/dist/telemetry/index.js

@@ -1,15 +1,29 @@
 import {
-  createCommandSpan,
   initTelemetry,
+  shutdownTelemetry
+} from "../chunk-S4AQMOWL.js";
+import {
+  createCommandSpan,
+  createHttpSpan,
+  endHttpSpan,
+  endHttpSpanWithError,
+  extractPath,
   recordError,
-  shutdownTelemetry,
+  sanitizeAttributes,
+  withCommandSpan,
   withSpan
-} from "../chunk-YWGC33UJ.js";
+} from "../chunk-G7AGMLZE.js";
 import "../chunk-MCKGQKYU.js";
 export {
   createCommandSpan,
+  createHttpSpan,
+  endHttpSpan,
+  endHttpSpanWithError,
+  extractPath,
   initTelemetry,
   recordError,
+  sanitizeAttributes,
   shutdownTelemetry,
+  withCommandSpan,
   withSpan
 };

package/dist/utils/index.d.ts

@@ -39,6 +39,7 @@ declare class HttpError extends Error {
 }
 /**
  * Typed fetch wrapper with base URL, default headers, query serialization, and error handling.
+ * Automatically creates OpenTelemetry spans for each request when OTEL is active.
  */
 declare function createHttpClient(options: HttpClientOptions): {
     request: <T>(path: string, opts?: RequestOptions) => Promise<T>;

package/dist/utils/index.js

@@ -8,7 +8,8 @@ import {
 import {
   HttpError,
   createHttpClient
-} from "../chunk-TKORXDDX.js";
+} from "../chunk-BBONIM34.js";
+import "../chunk-G7AGMLZE.js";
 import "../chunk-MCKGQKYU.js";
 export {
   HttpError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/cli-shared",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shared middleware, utilities, and testing helpers for spectra CLI tools",
   "type": "module",
   "license": "MIT",