observability-toolkit 1.8.0 → 1.8.4

package/dist/lib/server-utils.js

@@ -0,0 +1,141 @@
+/**
+ * Server utilities - Rate limiter and error classes
+ *
+ * Extracted from server.ts to allow importing in tests without starting the MCP server.
+ */
+// Rate limiting configuration
+export const RATE_LIMIT = {
+    windowMs: 60_000, // 1 minute window
+    maxRequests: 100, // max requests per window
+    bucketCount: 60, // 60 buckets for 1-second granularity
+    /** Maximum allowed bucketCount to prevent memory exhaustion */
+    maxBucketCount: 3600, // 1 hour max granularity
+};
+/**
+ * Sliding window counter rate limiter with O(1) operations and bounded memory.
+ * Uses fixed-size bucket array to track request counts per time slice.
+ *
+ * Memory usage: O(bucketCount) - fixed regardless of request volume
+ * Time complexity: O(bucketCount) for sum, but bucketCount is constant (60)
+ */
+export class RateLimiter {
+    buckets;
+    bucketTimestamps;
+    bucketMs;
+    windowMs;
+    maxRequests;
+    bucketCount;
+    constructor(windowMs = RATE_LIMIT.windowMs, maxRequests = RATE_LIMIT.maxRequests, bucketCount = RATE_LIMIT.bucketCount) {
+        // Validate bounds to prevent memory exhaustion or invalid state
+        if (bucketCount < 1 || bucketCount > RATE_LIMIT.maxBucketCount) {
+            throw new Error(`bucketCount must be between 1 and ${RATE_LIMIT.maxBucketCount} (1 hour max granularity)`);
+        }
+        if (maxRequests < 1) {
+            throw new Error('maxRequests must be >= 1');
+        }
+        // Validate windowMs bounds: 1ms minimum, 86400000ms (1 day) maximum to prevent overflow
+        if (windowMs < 1 || windowMs > 86400000) {
+            throw new Error('windowMs must be between 1ms and 86400000ms (1 day)');
+        }
+        this.windowMs = windowMs;
+        this.maxRequests = maxRequests;
+        this.bucketCount = bucketCount;
+        this.bucketMs = Math.floor(windowMs / bucketCount);
+        // Pre-allocate fixed-size arrays
+        this.buckets = new Array(bucketCount).fill(0);
+        this.bucketTimestamps = new Array(bucketCount).fill(0);
+    }
+    /**
+     * Get the bucket index for a given timestamp.
+     * Uses modulo to create circular buffer behavior.
+     */
+    getBucketIndex(timestamp) {
+        return Math.floor(timestamp / this.bucketMs) % this.bucketCount;
+    }
+    /**
+     * Clear expired buckets and return the current valid count.
+     * A bucket is expired if its timestamp is older than windowMs ago.
+     */
+    cleanAndCount(now) {
+        const windowStart = now - this.windowMs;
+        let count = 0;
+        for (let i = 0; i < this.bucketCount; i++) {
+            if (this.bucketTimestamps[i] < windowStart) {
+                // Bucket is expired, reset it
+                this.buckets[i] = 0;
+                this.bucketTimestamps[i] = 0;
+            }
+            else {
+                count += this.buckets[i];
+            }
+        }
+        return count;
+    }
+    /**
+     * Check if a request is allowed and record it if so.
+     * O(bucketCount) time complexity where bucketCount is constant.
+     */
+    isAllowed() {
+        const now = Date.now();
+        const currentCount = this.cleanAndCount(now);
+        if (currentCount >= this.maxRequests) {
+            return false;
+        }
+        // Record the request in the current bucket
+        const bucketIndex = this.getBucketIndex(now);
+        // If this bucket is from a different time period, reset it
+        const bucketWindowStart = now - this.windowMs;
+        if (this.bucketTimestamps[bucketIndex] < bucketWindowStart) {
+            this.buckets[bucketIndex] = 0;
+        }
+        this.buckets[bucketIndex]++;
+        this.bucketTimestamps[bucketIndex] = now;
+        return true;
+    }
+    /**
+     * Get the number of remaining allowed requests in the current window.
+     */
+    getRemainingRequests() {
+        const now = Date.now();
+        const currentCount = this.cleanAndCount(now);
+        return Math.max(0, this.maxRequests - currentCount);
+    }
+    /**
+     * Get the current memory footprint (for testing).
+     * Returns the fixed size of internal arrays.
+     */
+    getMemoryFootprint() {
+        return {
+            bucketCount: this.bucketCount,
+            arraySize: this.buckets.length + this.bucketTimestamps.length,
+        };
+    }
+    /**
+     * Reset the rate limiter state.
+     * @internal For testing ONLY - not thread-safe, do not use in production
+     */
+    reset() {
+        this.buckets.fill(0);
+        this.bucketTimestamps.fill(0);
+    }
+}
+/**
+ * Server initialization error with explicit step information.
+ *
+ * Steps:
+ * - tool-validation: Validating tool configuration
+ * - server-creation: Creating MCP server instance
+ * - handler-registration: Registering request handlers
+ * - transport-connection: Connecting stdio transport
+ */
+export class ServerInitError extends Error {
+    step;
+    cause;
+    constructor(step, cause, message) {
+        super(message || `Server initialization failed at step: ${step}`);
+        this.step = step;
+        this.cause = cause;
+        this.name = 'ServerInitError';
+    }
+}
+//# sourceMappingURL=server-utils.js.map

package/dist/lib/server-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-utils.js","sourceRoot":"","sources":["../../src/lib/server-utils.ts"],"names":[],"mappings":"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"}

package/dist/lib/shared-schemas.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared Zod schemas for common tool parameters
+ * Reduces token usage by centralizing repeated definitions
+ */
+import { z } from 'zod';
+/**
+ * Common date range parameters
+ */
+export declare const dateRangeSchema: {
+    startDate: z.ZodOptional<z.ZodString>;
+    endDate: z.ZodOptional<z.ZodString>;
+};
+/**
+ * Common pagination parameters
+ */
+export declare const paginationSchema: {
+    limit: z.ZodDefault<z.ZodNumber>;
+};
+/**
+ * Pagination with higher default for metrics
+ */
+export declare const metricsPaginationSchema: {
+    limit: z.ZodDefault<z.ZodNumber>;
+};
+/**
+ * Backend selection parameter
+ */
+export declare const backendSchema: {
+    backend: z.ZodDefault<z.ZodEnum<["local", "signoz", "auto"]>>;
+};
+/**
+ * Session ID filter parameter
+ */
+export declare const sessionSchema: {
+    sessionId: z.ZodOptional<z.ZodString>;
+};
+/**
+ * Trace ID filter parameter
+ */
+export declare const traceIdSchema: {
+    traceId: z.ZodOptional<z.ZodString>;
+};
+/**
+ * Combined common query parameters (backend + session + date range + pagination)
+ */
+export declare const commonQuerySchema: {
+    limit: z.ZodDefault<z.ZodNumber>;
+    startDate: z.ZodOptional<z.ZodString>;
+    endDate: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    backend: z.ZodDefault<z.ZodEnum<["local", "signoz", "auto"]>>;
+};
+/**
+ * OTel GenAI operation name enum
+ */
+export declare const operationNameSchema: {
+    operationName: z.ZodOptional<z.ZodEnum<["chat", "embeddings", "invoke_agent", "execute_tool"]>>;
+};
+//# sourceMappingURL=shared-schemas.d.ts.map

package/dist/lib/shared-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.d.ts","sourceRoot":"","sources":["../../src/lib/shared-schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,eAAe;;;CAG3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB;;CAE5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB;;CAEnC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;CAEzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;CAEzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;CAEzB,CAAC;AAGF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;CAK7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB;;CAE/B,CAAC"}

package/dist/lib/shared-schemas.js

@@ -0,0 +1,58 @@
+/**
+ * Shared Zod schemas for common tool parameters
+ * Reduces token usage by centralizing repeated definitions
+ */
+import { z } from 'zod';
+/**
+ * Common date range parameters
+ */
+export const dateRangeSchema = {
+    startDate: z.string().optional().describe('Start (YYYY-MM-DD)'),
+    endDate: z.string().optional().describe('End (YYYY-MM-DD)'),
+};
+/**
+ * Common pagination parameters
+ */
+export const paginationSchema = {
+    limit: z.number().max(1000).default(50).describe('Max results'),
+};
+/**
+ * Pagination with higher default for metrics
+ */
+export const metricsPaginationSchema = {
+    limit: z.number().max(1000).default(100).describe('Max results'),
+};
+/**
+ * Backend selection parameter
+ */
+export const backendSchema = {
+    backend: z.enum(['local', 'signoz', 'auto']).default('auto').describe('Backend (default: auto)'),
+};
+/**
+ * Session ID filter parameter
+ */
+export const sessionSchema = {
+    sessionId: z.string().max(128).optional().describe('Session ID'),
+};
+/**
+ * Trace ID filter parameter
+ */
+export const traceIdSchema = {
+    traceId: z.string().max(64).optional().describe('Trace ID'),
+};
+/**
+ * Combined common query parameters (backend + session + date range + pagination)
+ */
+export const commonQuerySchema = {
+    ...backendSchema,
+    ...sessionSchema,
+    ...dateRangeSchema,
+    ...paginationSchema,
+};
+/**
+ * OTel GenAI operation name enum
+ */
+export const operationNameSchema = {
+    operationName: z.enum(['chat', 'embeddings', 'invoke_agent', 'execute_tool']).optional().describe('GenAI operation'),
+};
+//# sourceMappingURL=shared-schemas.js.map

package/dist/lib/shared-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.js","sourceRoot":"","sources":["../../src/lib/shared-schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAC/D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;CAC5D,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC;CAChE,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC;CACjE,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC;CACjG,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;CACjE,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC;CAC5D,CAAC;AAGF;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,GAAG,aAAa;IAChB,GAAG,aAAa;IAChB,GAAG,eAAe;IAClB,GAAG,gBAAgB;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;CACrH,CAAC"}

package/dist/lib/shared-schemas.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for shared Zod schemas
+ */
+export {};
+//# sourceMappingURL=shared-schemas.test.d.ts.map

package/dist/lib/shared-schemas.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.test.d.ts","sourceRoot":"","sources":["../../src/lib/shared-schemas.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/lib/shared-schemas.test.js

@@ -0,0 +1,106 @@
+/**
+ * Tests for shared Zod schemas
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { z } from 'zod';
+import { traceIdSchema, sessionSchema, dateRangeSchema, paginationSchema, backendSchema, } from './shared-schemas.js';
+describe('shared-schemas', () => {
+    describe('traceIdSchema', () => {
+        const schema = z.object(traceIdSchema);
+        it('should accept valid traceId', () => {
+            const result = schema.safeParse({ traceId: 'abc123' });
+            assert.strictEqual(result.success, true);
+        });
+        it('should accept traceId at max length (64)', () => {
+            const result = schema.safeParse({ traceId: 'a'.repeat(64) });
+            assert.strictEqual(result.success, true);
+        });
+        it('should reject traceId exceeding 64 characters', () => {
+            const result = schema.safeParse({ traceId: 'a'.repeat(65) });
+            assert.strictEqual(result.success, false);
+        });
+        it('should accept undefined traceId', () => {
+            const result = schema.safeParse({});
+            assert.strictEqual(result.success, true);
+        });
+    });
+    describe('sessionSchema', () => {
+        const schema = z.object(sessionSchema);
+        it('should accept valid sessionId', () => {
+            const result = schema.safeParse({ sessionId: 'session-123' });
+            assert.strictEqual(result.success, true);
+        });
+        it('should accept sessionId at max length (128)', () => {
+            const result = schema.safeParse({ sessionId: 'a'.repeat(128) });
+            assert.strictEqual(result.success, true);
+        });
+        it('should reject sessionId exceeding 128 characters', () => {
+            const result = schema.safeParse({ sessionId: 'a'.repeat(129) });
+            assert.strictEqual(result.success, false);
+        });
+        it('should accept undefined sessionId', () => {
+            const result = schema.safeParse({});
+            assert.strictEqual(result.success, true);
+        });
+    });
+    describe('dateRangeSchema', () => {
+        const schema = z.object(dateRangeSchema);
+        it('should accept valid date range', () => {
+            const result = schema.safeParse({
+                startDate: '2026-01-01',
+                endDate: '2026-01-31',
+            });
+            assert.strictEqual(result.success, true);
+        });
+        it('should accept partial date range', () => {
+            const result = schema.safeParse({ startDate: '2026-01-01' });
+            assert.strictEqual(result.success, true);
+        });
+        it('should accept empty object', () => {
+            const result = schema.safeParse({});
+            assert.strictEqual(result.success, true);
+        });
+    });
+    describe('paginationSchema', () => {
+        const schema = z.object(paginationSchema);
+        it('should default limit to 50', () => {
+            const result = schema.safeParse({});
+            assert.strictEqual(result.success, true);
+            if (result.success) {
+                assert.strictEqual(result.data.limit, 50);
+            }
+        });
+        it('should accept valid limit', () => {
+            const result = schema.safeParse({ limit: 100 });
+            assert.strictEqual(result.success, true);
+        });
+        it('should reject limit exceeding 1000', () => {
+            const result = schema.safeParse({ limit: 1001 });
+            assert.strictEqual(result.success, false);
+        });
+    });
+    describe('backendSchema', () => {
+        const schema = z.object(backendSchema);
+        it('should default backend to auto', () => {
+            const result = schema.safeParse({});
+            assert.strictEqual(result.success, true);
+            if (result.success) {
+                assert.strictEqual(result.data.backend, 'auto');
+            }
+        });
+        it('should accept local backend', () => {
+            const result = schema.safeParse({ backend: 'local' });
+            assert.strictEqual(result.success, true);
+        });
+        it('should accept signoz backend', () => {
+            const result = schema.safeParse({ backend: 'signoz' });
+            assert.strictEqual(result.success, true);
+        });
+        it('should reject invalid backend', () => {
+            const result = schema.safeParse({ backend: 'invalid' });
+            assert.strictEqual(result.success, false);
+        });
+    });
+});
+//# sourceMappingURL=shared-schemas.test.js.map

package/dist/lib/shared-schemas.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.test.js","sourceRoot":"","sources":["../../src/lib/shared-schemas.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/toon-encoder.d.ts

@@ -0,0 +1,21 @@
+/**
+ * TOON (Token-Oriented Object Notation) encoding utilities
+ * Provides 40-60% token reduction for uniform array responses
+ */
+export type ResponseFormat = 'json' | 'toon';
+/**
+ * Encode data to TOON format
+ * @param data - Data to encode (typically an array of objects)
+ * @returns TOON-encoded string
+ *
+ * Security: Logs encoding failures for debugging instead of silently falling back
+ */
+export declare function toToon<T>(data: T[]): string;
+/**
+ * Check if TOON format is beneficial for the given data
+ * TOON works best with uniform arrays of objects
+ * @param data - Data to check
+ * @returns true if TOON would be beneficial
+ */
+export declare function isToonBeneficial(data: unknown[]): boolean;
+//# sourceMappingURL=toon-encoder.d.ts.map

package/dist/lib/toon-encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon-encoder.d.ts","sourceRoot":"","sources":["../../src/lib/toon-encoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,MAAM,CAc3C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAazD"}

package/dist/lib/toon-encoder.js

@@ -0,0 +1,46 @@
+/**
+ * TOON (Token-Oriented Object Notation) encoding utilities
+ * Provides 40-60% token reduction for uniform array responses
+ */
+import { encode as toonEncode } from '@toon-format/toon';
+/**
+ * Encode data to TOON format
+ * @param data - Data to encode (typically an array of objects)
+ * @returns TOON-encoded string
+ *
+ * Security: Logs encoding failures for debugging instead of silently falling back
+ */
+export function toToon(data) {
+    if (Array.isArray(data) && data.length > 0) {
+        try {
+            return toonEncode(data);
+        }
+        catch (error) {
+            // Log warning for debugging - silent fallback makes issues hard to diagnose
+            console.warn('[TOON] Encoding failed, falling back to JSON:', error instanceof Error ? error.message : String(error));
+            return JSON.stringify(data);
+        }
+    }
+    return JSON.stringify(data);
+}
+/**
+ * Check if TOON format is beneficial for the given data
+ * TOON works best with uniform arrays of objects
+ * @param data - Data to check
+ * @returns true if TOON would be beneficial
+ */
+export function isToonBeneficial(data) {
+    if (!Array.isArray(data) || data.length < 2)
+        return false;
+    // Check if all items are objects with same keys
+    const firstItem = data[0];
+    if (typeof firstItem !== 'object' || firstItem === null)
+        return false;
+    const firstKeys = Object.keys(firstItem).sort().join(',');
+    return data.every(item => {
+        if (typeof item !== 'object' || item === null)
+            return false;
+        return Object.keys(item).sort().join(',') === firstKeys;
+    });
+}
+//# sourceMappingURL=toon-encoder.js.map

package/dist/lib/toon-encoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon-encoder.js","sourceRoot":"","sources":["../../src/lib/toon-encoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIzD;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAI,IAAS;IACjC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4EAA4E;YAC5E,OAAO,CAAC,IAAI,CACV,+CAA+C,EAC/C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;YACF,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAe;IAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAE1D,gDAAgD;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAEtE,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE1D,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;QACvB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC5D,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server.d.ts

@@ -7,5 +7,5 @@
  *
  * Install: claude mcp add observability-toolkit -- npx -y @alyshia/observability-toolkit
  */
-export {};
+export { RateLimiter, ServerInitError } from './lib/server-utils.js';
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AA8BH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}