@spectratools/cli-shared 0.1.1 → 0.2.0

package/dist/chunk-MCKGQKYU.js

@@ -0,0 +1,15 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+export {
+  __require,
+  __commonJS
+};

package/dist/{chunk-IW62SQFU.js → chunk-OPDNZWSI.js}

@@ -9,6 +9,9 @@ function weiToEth(wei, decimals = 6) {
   const fracStr = frac.toString().padStart(18, "0").slice(0, decimals).replace(/0+$/, "");
   return fracStr.length > 0 ? `${whole}.${fracStr}` : `${whole}`;
 }
+function isAddress(address) {
+  return Address.validate(address);
+}
 function checksumAddress(address) {
   return Address.checksum(address);
 }
@@ -22,6 +25,7 @@ function truncate(str, prefixLen = 6, suffixLen = 4) {
 
 export {
   weiToEth,
+  isAddress,
   checksumAddress,
   formatTimestamp,
   truncate

package/dist/chunk-YWGC33UJ.js

@@ -0,0 +1,201 @@
+import {
+  __commonJS,
+  __require
+} from "./chunk-MCKGQKYU.js";
+
+// package.json
+var require_package = __commonJS({
+  "package.json"(exports, module) {
+    module.exports = {
+      name: "@spectratools/cli-shared",
+      version: "0.2.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: "./dist/index.d.ts",
+          default: "./dist/index.js"
+        },
+        "./middleware": {
+          types: "./dist/middleware/index.d.ts",
+          default: "./dist/middleware/index.js"
+        },
+        "./utils": {
+          types: "./dist/utils/index.d.ts",
+          default: "./dist/utils/index.js"
+        },
+        "./telemetry": {
+          types: "./dist/telemetry/index.d.ts",
+          default: "./dist/telemetry/index.js"
+        },
+        "./testing": {
+          types: "./dist/testing/index.d.ts",
+          default: "./dist/testing/index.js"
+        }
+      },
+      scripts: {
+        build: "tsup",
+        typecheck: "tsc --noEmit -p tsconfig.json",
+        test: "vitest run",
+        prepublishOnly: "pnpm build"
+      },
+      devDependencies: {
+        typescript: "5.7.3",
+        vitest: "2.1.8"
+      },
+      dependencies: {
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
+        "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+        "@opentelemetry/resources": "^2.6.0",
+        "@opentelemetry/sdk-metrics": "^2.6.0",
+        "@opentelemetry/sdk-node": "^0.213.0",
+        "@opentelemetry/sdk-trace-node": "^2.6.0",
+        "@opentelemetry/semantic-conventions": "^1.40.0",
+        ox: "^0.14.0"
+      },
+      files: ["dist", "README.md"],
+      main: "./dist/index.js",
+      types: "./dist/index.d.ts"
+    };
+  }
+});
+
+// src/telemetry/init.ts
+var sdk;
+var initialized = false;
+function isOtelEnabled() {
+  return !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.SPECTRA_OTEL_ENABLED === "true");
+}
+function initTelemetry(serviceName) {
+  if (initialized) return;
+  initialized = true;
+  if (!isOtelEnabled()) return;
+  const sdkMod = __require("@opentelemetry/sdk-node");
+  const traceExpMod = __require("@opentelemetry/exporter-trace-otlp-http");
+  const metricExpMod = __require("@opentelemetry/exporter-metrics-otlp-http");
+  const metricsMod = __require("@opentelemetry/sdk-metrics");
+  const resourcesMod = __require("@opentelemetry/resources");
+  const semconvMod = __require("@opentelemetry/semantic-conventions");
+  let version = "0.0.0";
+  try {
+    const pkg = require_package();
+    version = pkg.version ?? version;
+  } catch {
+  }
+  const resolvedServiceName = process.env.OTEL_SERVICE_NAME || `spectra-${serviceName}`;
+  const resource = resourcesMod.resourceFromAttributes({
+    [semconvMod.ATTR_SERVICE_NAME]: resolvedServiceName,
+    [semconvMod.ATTR_SERVICE_VERSION]: version
+  });
+  const traceExporter = new traceExpMod.OTLPTraceExporter();
+  const metricExporter = new metricExpMod.OTLPMetricExporter();
+  sdk = new sdkMod.NodeSDK({
+    resource,
+    traceExporter,
+    metricReader: new metricsMod.PeriodicExportingMetricReader({
+      exporter: metricExporter
+    })
+  });
+  sdk.start();
+  const shutdown = () => {
+    sdk?.shutdown().then(
+      () => process.exit(0),
+      () => process.exit(1)
+    );
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+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();
+  if (!sdk2) return;
+  await sdk2.shutdown();
+}
+
+export {
+  initTelemetry,
+  createCommandSpan,
+  withSpan,
+  recordError,
+  shutdownTelemetry
+};

package/dist/index.d.ts

@@ -1,3 +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 { MockResponse, MockServer, RecordedRequest, createMockServer } from './testing/index.js';
-export { HttpClientOptions, HttpError, RequestOptions, checksumAddress, createHttpClient, formatTimestamp, truncate, weiToEth } from './utils/index.js';
+export { HttpClientOptions, HttpError, RequestOptions, checksumAddress, createHttpClient, formatTimestamp, isAddress, truncate, weiToEth } from './utils/index.js';
+import '@opentelemetry/api';

package/dist/index.js

@@ -7,32 +7,47 @@ import {
   withRateLimit,
   withRetry
 } from "./chunk-74BQLM22.js";
+import {
+  createCommandSpan,
+  initTelemetry,
+  recordError,
+  shutdownTelemetry,
+  withSpan
+} from "./chunk-YWGC33UJ.js";
+import {
+  createMockServer
+} from "./chunk-QEANTXUE.js";
 import {
   checksumAddress,
   formatTimestamp,
+  isAddress,
   truncate,
   weiToEth
-} from "./chunk-IW62SQFU.js";
+} from "./chunk-OPDNZWSI.js";
 import {
   HttpError,
   createHttpClient
 } from "./chunk-TKORXDDX.js";
-import {
-  createMockServer
-} from "./chunk-QEANTXUE.js";
+import "./chunk-MCKGQKYU.js";
 export {
   HttpError,
   MissingApiKeyError,
   apiKeyAuth,
   checksumAddress,
+  createCommandSpan,
   createHttpClient,
   createMockServer,
   createRateLimiter,
   formatTimestamp,
+  initTelemetry,
+  isAddress,
   paginateCursor,
   paginateOffset,
+  recordError,
+  shutdownTelemetry,
   truncate,
   weiToEth,
   withRateLimit,
-  withRetry
+  withRetry,
+  withSpan
 };

package/dist/middleware/index.js

@@ -8,6 +8,7 @@ import {
   withRetry
 } from "../chunk-74BQLM22.js";
 import "../chunk-TKORXDDX.js";
+import "../chunk-MCKGQKYU.js";
 export {
   MissingApiKeyError,
   apiKeyAuth,

package/dist/telemetry/index.d.ts

@@ -0,0 +1,47 @@
+import { Span } from '@opentelemetry/api';
+
+/**
+ * Initialize OpenTelemetry SDK for a CLI service.
+ *
+ * This is a **lazy** initializer — if neither `OTEL_EXPORTER_OTLP_ENDPOINT` nor
+ * `SPECTRA_OTEL_ENABLED=true` is set, it returns immediately without importing
+ * any OTEL modules, ensuring zero overhead when instrumentation is disabled.
+ *
+ * @param serviceName - Logical name of the CLI service (used as fallback for `service.name`).
+ */
+declare function initTelemetry(serviceName: string): void;
+
+/**
+ * Create a root span for a CLI command invocation.
+ *
+ * @param commandName - The command being executed (e.g. `"account balance"`).
+ * @param args - Optional key-value arguments to attach as span attributes (sensitive values are stripped).
+ * @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 child span, runs the given async function,
+ * and automatically ends the span. On error, the error is recorded on the span
+ * before being re-thrown.
+ *
+ * @param name - Span name.
+ * @param fn - Async function to execute within the span context.
+ * @returns The result of `fn`.
+ */
+declare function withSpan<T>(name: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Attach error details and stack trace to a span and mark it as errored.
+ *
+ * @param span - The span to annotate.
+ * @param error - The error value (may be an `Error` instance or arbitrary value).
+ */
+declare function recordError(span: Span, error: unknown): void;
+
+/**
+ * Flush pending spans/metrics and shut down the OTEL SDK.
+ *
+ * Safe to call even if telemetry was never initialized — in that case it is a no-op.
+ */
+declare function shutdownTelemetry(): Promise<void>;
+
+export { createCommandSpan, initTelemetry, recordError, shutdownTelemetry, withSpan };

package/dist/telemetry/index.js

@@ -0,0 +1,15 @@
+import {
+  createCommandSpan,
+  initTelemetry,
+  recordError,
+  shutdownTelemetry,
+  withSpan
+} from "../chunk-YWGC33UJ.js";
+import "../chunk-MCKGQKYU.js";
+export {
+  createCommandSpan,
+  initTelemetry,
+  recordError,
+  shutdownTelemetry,
+  withSpan
+};

package/dist/testing/index.js

@@ -1,6 +1,7 @@
 import {
   createMockServer
 } from "../chunk-QEANTXUE.js";
+import "../chunk-MCKGQKYU.js";
 export {
   createMockServer
 };

package/dist/utils/index.d.ts

@@ -2,6 +2,10 @@
  * Converts wei (as bigint or string) to a human-readable ETH string.
  */
 declare function weiToEth(wei: bigint | string, decimals?: number): string;
+/**
+ * Returns true if the value is a valid 0x-prefixed 20-byte hex address.
+ */
+declare function isAddress(address: string): boolean;
 /**
  * Checksums an Ethereum address using EIP-55.
  * Accepts lowercase or mixed-case hex addresses.
@@ -40,4 +44,4 @@ declare function createHttpClient(options: HttpClientOptions): {
     request: <T>(path: string, opts?: RequestOptions) => Promise<T>;
 };
 
-export { type HttpClientOptions, HttpError, type RequestOptions, checksumAddress, createHttpClient, formatTimestamp, truncate, weiToEth };
+export { type HttpClientOptions, HttpError, type RequestOptions, checksumAddress, createHttpClient, formatTimestamp, isAddress, truncate, weiToEth };

package/dist/utils/index.js

@@ -1,18 +1,21 @@
 import {
   checksumAddress,
   formatTimestamp,
+  isAddress,
   truncate,
   weiToEth
-} from "../chunk-IW62SQFU.js";
+} from "../chunk-OPDNZWSI.js";
 import {
   HttpError,
   createHttpClient
 } from "../chunk-TKORXDDX.js";
+import "../chunk-MCKGQKYU.js";
 export {
   HttpError,
   checksumAddress,
   createHttpClient,
   formatTimestamp,
+  isAddress,
   truncate,
   weiToEth
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/cli-shared",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Shared middleware, utilities, and testing helpers for spectra CLI tools",
   "type": "module",
   "license": "MIT",
@@ -21,6 +21,10 @@
       "types": "./dist/utils/index.d.ts",
       "default": "./dist/utils/index.js"
     },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "default": "./dist/telemetry/index.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
@@ -31,6 +35,14 @@
     "vitest": "2.1.8"
   },
   "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-metrics": "^2.6.0",
+    "@opentelemetry/sdk-node": "^0.213.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
     "ox": "^0.14.0"
   },
   "files": [