@butlr/butlr-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Butlr Technologies
+
+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,195 @@
+# Butlr MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@butlr/butlr-mcp-server.svg)](https://www.npmjs.com/package/@butlr/butlr-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that connects AI assistants to [Butlr's](https://www.butlr.com) occupancy sensing platform. Query real-time space utilization, search facility assets, and analyze occupancy patterns through natural language.
+
+### What you can do
+
+- **Find available spaces** — "Are there any free conference rooms right now with capacity for 8?"
+- **Monitor occupancy** — "How busy is the cafe? Should I head there now?"
+- **Analyze trends** — "Show me occupancy patterns for Floor 3 over the past week"
+- **Search your portfolio** — "Find all rooms named 'huddle' across Building 2"
+- **Check sensor health** — "Which sensors are offline or need battery replacement?"
+- **Track foot traffic** — "How many people entered the main lobby today?"
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 20 or higher
+- An MCP-compatible client ([Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [VS Code](https://code.visualstudio.com/), [Cursor](https://cursor.com/), etc.)
+- Butlr API credentials (OAuth2 client ID, client secret, and organization ID) — see [Getting API Credentials](#getting-api-credentials)
+
+## Quick Start
+
+<details open>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "butlr": {
+      "command": "npx",
+      "args": ["-y", "@butlr/butlr-mcp-server@latest"],
+      "env": {
+        "BUTLR_CLIENT_ID": "your_client_id",
+        "BUTLR_CLIENT_SECRET": "your_client_secret",
+        "BUTLR_ORG_ID": "your_org_id"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add butlr -- npx -y @butlr/butlr-mcp-server@latest
+```
+
+Then set environment variables in your shell or `.env` file:
+
+```bash
+export BUTLR_CLIENT_ID=your_client_id
+export BUTLR_CLIENT_SECRET=your_client_secret
+export BUTLR_ORG_ID=your_org_id
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code (Copilot)</strong></summary>
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "butlr": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@butlr/butlr-mcp-server@latest"],
+      "env": {
+        "BUTLR_CLIENT_ID": "your_client_id",
+        "BUTLR_CLIENT_SECRET": "your_client_secret",
+        "BUTLR_ORG_ID": "your_org_id"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "butlr": {
+      "command": "npx",
+      "args": ["-y", "@butlr/butlr-mcp-server@latest"],
+      "env": {
+        "BUTLR_CLIENT_ID": "your_client_id",
+        "BUTLR_CLIENT_SECRET": "your_client_secret",
+        "BUTLR_ORG_ID": "your_org_id"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Other MCP clients</strong></summary>
+
+For any MCP client that supports stdio transport, use this command:
+
+```
+npx -y @butlr/butlr-mcp-server@latest
+```
+
+Pass the required environment variables (`BUTLR_CLIENT_ID`, `BUTLR_CLIENT_SECRET`, `BUTLR_ORG_ID`) through your client's configuration.
+
+</details>
+
+## Available Tools
+
+| Tool | Description | Try asking... |
+|------|-------------|---------------|
+| `butlr_search_assets` | Search for assets (sites, buildings, floors, rooms, sensors) by name with fuzzy matching | "Find the main lobby" |
+| `butlr_get_asset_details` | Get comprehensive details for specific assets by ID with batch support | "Show me details for Conference Room 401" |
+| `butlr_hardware_snapshot` | Device health check: online/offline status and battery levels across your portfolio | "Which sensors need battery replacement?" |
+| `butlr_available_rooms` | Find currently unoccupied rooms, filterable by capacity and tags | "Are there any free conference rooms right now?" |
+| `butlr_space_busyness` | Current occupancy with qualitative labels (quiet/moderate/busy) and trend comparison | "How busy is the cafe right now?" |
+| `butlr_traffic_flow` | Entry/exit counts with hourly breakdown for traffic-mode sensors | "How many people entered the lobby today?" |
+| `butlr_list_topology` | Display org hierarchy tree with flexible depth control | "Show me all floors in Building 2" |
+| `butlr_fetch_entity_details` | Retrieve specific fields for entities by ID (minimal token usage) | "What's the timezone for this site?" |
+| `butlr_get_occupancy_timeseries` | Historical occupancy data with configurable time ranges | "Show occupancy trends for Floor 3 this week" |
+| `butlr_get_current_occupancy` | Real-time occupancy snapshot (last 5 minutes median) | "How many people are on Floor 2 right now?" |
+
+All tools are **read-only** — the server cannot modify any data in your Butlr account.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BUTLR_CLIENT_ID` | **Yes** | - | OAuth2 client ID |
+| `BUTLR_CLIENT_SECRET` | **Yes** | - | OAuth2 client secret |
+| `BUTLR_ORG_ID` | **Yes** | - | Organization ID |
+| `BUTLR_BASE_URL` | No | `https://api.butlr.io` | API base URL |
+| `BUTLR_TIMEZONE` | No | `UTC` | Default timezone |
+| `MCP_CACHE_TOPO_TTL` | No | `600` | Topology cache TTL (seconds) |
+| `DEBUG` | No | - | Set to `butlr-mcp` for verbose logging |
+
+## Getting API Credentials
+
+To use this MCP server, you need OAuth2 API credentials from Butlr:
+
+1. **Contact your Butlr account representative** or visit [butlr.com](https://www.butlr.com) to request API access
+2. You will receive a **Client ID**, **Client Secret**, and **Organization ID**
+3. These credentials provide read-only access scoped to your organization's data
+
+## Troubleshooting
+
+**Authentication errors** — Verify your `BUTLR_CLIENT_ID`, `BUTLR_CLIENT_SECRET`, and `BUTLR_ORG_ID` are correct. Tokens are refreshed automatically.
+
+**Rate limiting** — The server handles rate limits automatically with retry logic. If you see persistent rate limit errors, reduce the frequency of requests.
+
+**No data returned** — Ensure your organization has active sensors deployed. Use `butlr_search_assets` to verify your org has discoverable assets.
+
+**Debug logging** — Set `DEBUG=butlr-mcp` in your environment to see detailed request/response logs on stderr.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development workflow and standards.
+
+```bash
+npm install          # Install dependencies
+npm run build        # Build TypeScript
+npm test             # Run tests (442 tests)
+npm run typecheck    # Type checking
+npm run lint         # ESLint
+npm run dev          # Dev with hot-reload
+npm run dev:debug    # Dev with debug logging
+```
+
+## Security
+
+- All tools enforce read-only API access
+- Never commit credentials to version control
+- See [SECURITY.md](SECURITY.md) for vulnerability disclosure
+
+## License
+
+MIT - see [LICENSE](LICENSE)

package/dist/cache/occupancy-cache.d.ts

@@ -0,0 +1,72 @@
+import { LRUCache } from "lru-cache";
+interface OccupancyCacheEntry {
+    occupancy: number;
+    timestamp: string;
+    asset_id: string;
+    asset_type: string;
+}
+/**
+ * LRU cache for current occupancy data with short TTL
+ * Reduces API calls for frequently accessed current occupancy queries
+ *
+ * Cache key format: occupancy:{asset_id}:{minute_bucket}
+ * Example: occupancy:room_123:202501131400 (truncated to minute)
+ */
+export declare const occupancyCache: LRUCache<string, OccupancyCacheEntry, unknown>;
+/**
+ * Generate cache key for occupancy queries
+ * Includes minute bucket to group queries within same minute
+ */
+export declare function generateOccupancyCacheKey(assetId: string, timestamp?: Date): string;
+/**
+ * Get cached occupancy data
+ */
+export declare function getCachedOccupancy(assetId: string, timestamp?: Date): OccupancyCacheEntry | undefined;
+/**
+ * Get cached occupancy for multiple assets
+ * Returns { hits: {}, misses: [] }
+ */
+export declare function getBulkCachedOccupancy(assetIds: string[], timestamp?: Date): {
+    hits: Record<string, OccupancyCacheEntry>;
+    misses: string[];
+};
+/**
+ * Store occupancy data in cache
+ */
+export declare function setCachedOccupancy(assetId: string, occupancy: number, assetType: string, timestamp?: Date): void;
+/**
+ * Store multiple occupancy values
+ */
+export declare function setBulkCachedOccupancy(entries: Array<{
+    assetId: string;
+    occupancy: number;
+    assetType: string;
+    timestamp?: Date;
+}>): void;
+/**
+ * Clear all cached occupancy data
+ */
+export declare function clearOccupancyCache(): void;
+/**
+ * Invalidate cache for specific asset
+ */
+export declare function invalidateAssetOccupancy(assetId: string): void;
+/**
+ * Get cache statistics
+ */
+export declare function getOccupancyCacheStats(): {
+    size: number;
+    maxSize: number;
+    ttl: number;
+    utilizationPercent: number;
+};
+export declare function recordCacheHit(): void;
+export declare function recordCacheMiss(): void;
+export declare function getCacheHitRate(): {
+    hits: number;
+    misses: number;
+    hitRate: number;
+};
+export declare function resetCacheMetrics(): void;
+export {};
+//# sourceMappingURL=occupancy-cache.d.ts.map

package/dist/cache/occupancy-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"occupancy-cache.d.ts","sourceRoot":"","sources":["../../src/cache/occupancy-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC,UAAU,mBAAmB;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,gDAKzB,CAAC;AAEH;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAanF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,IAAI,GACf,mBAAmB,GAAG,SAAS,CAkBjC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,CAAC,EAAE,IAAI,GACf;IACD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC1C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAoBA;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,IAAI,GACf,IAAI,CAkBN;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB,CAAC,GACD,IAAI,CAQN;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAM1C;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAa9D;AAED;;GAEG;AACH,wBAAgB,sBAAsB;;;;;EAOrC;AASD,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,wBAAgB,eAAe,IAAI;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAOA;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC"}

package/dist/cache/occupancy-cache.js

@@ -0,0 +1,166 @@
+import { LRUCache } from "lru-cache";
+/**
+ * Occupancy cache configuration
+ * TTL: 60 seconds (fast-changing data)
+ */
+const CACHE_TTL_SECONDS = parseInt(process.env.MCP_CACHE_OCCUPANCY_TTL || "60", 10) * 1000; // Convert to milliseconds
+const MAX_CACHE_ENTRIES = 500; // More entries than topology (many rooms)
+/**
+ * LRU cache for current occupancy data with short TTL
+ * Reduces API calls for frequently accessed current occupancy queries
+ *
+ * Cache key format: occupancy:{asset_id}:{minute_bucket}
+ * Example: occupancy:room_123:202501131400 (truncated to minute)
+ */
+export const occupancyCache = new LRUCache({
+    max: MAX_CACHE_ENTRIES,
+    ttl: CACHE_TTL_SECONDS,
+    updateAgeOnGet: true, // Reset TTL on cache hit
+    updateAgeOnHas: false,
+});
+/**
+ * Generate cache key for occupancy queries
+ * Includes minute bucket to group queries within same minute
+ */
+export function generateOccupancyCacheKey(assetId, timestamp) {
+    const now = timestamp || new Date();
+    // Truncate to minute (ignore seconds)
+    const minuteBucket = new Date(now);
+    minuteBucket.setSeconds(0, 0);
+    const bucketStr = minuteBucket
+        .toISOString()
+        .replace(/[-:T]/g, "") // Remove dashes, colons, and T
+        .substring(0, 12); // YYYYMMDDHHmm
+    return `occupancy:${assetId}:${bucketStr}`;
+}
+/**
+ * Get cached occupancy data
+ */
+export function getCachedOccupancy(assetId, timestamp) {
+    const key = generateOccupancyCacheKey(assetId, timestamp);
+    const cached = occupancyCache.get(key);
+    // Track cache hit/miss metrics
+    if (cached) {
+        recordCacheHit();
+        if (process.env.DEBUG) {
+            console.error(`[occupancy-cache] Cache HIT for ${assetId}`);
+        }
+    }
+    else {
+        recordCacheMiss();
+        if (process.env.DEBUG) {
+            console.error(`[occupancy-cache] Cache MISS for ${assetId}`);
+        }
+    }
+    return cached;
+}
+/**
+ * Get cached occupancy for multiple assets
+ * Returns { hits: {}, misses: [] }
+ */
+export function getBulkCachedOccupancy(assetIds, timestamp) {
+    const hits = {};
+    const misses = [];
+    for (const assetId of assetIds) {
+        const cached = getCachedOccupancy(assetId, timestamp);
+        if (cached) {
+            hits[assetId] = cached;
+        }
+        else {
+            misses.push(assetId);
+        }
+    }
+    if (process.env.DEBUG) {
+        console.error(`[occupancy-cache] Bulk query: ${Object.keys(hits).length} hits, ${misses.length} misses`);
+    }
+    return { hits, misses };
+}
+/**
+ * Store occupancy data in cache
+ */
+export function setCachedOccupancy(assetId, occupancy, assetType, timestamp) {
+    const now = timestamp || new Date();
+    const key = generateOccupancyCacheKey(assetId, now);
+    const entry = {
+        occupancy,
+        timestamp: now.toISOString(),
+        asset_id: assetId,
+        asset_type: assetType,
+    };
+    occupancyCache.set(key, entry);
+    if (process.env.DEBUG) {
+        console.error(`[occupancy-cache] Cached occupancy for ${assetId}: ${occupancy} (TTL: ${CACHE_TTL_SECONDS / 1000}s)`);
+    }
+}
+/**
+ * Store multiple occupancy values
+ */
+export function setBulkCachedOccupancy(entries) {
+    for (const entry of entries) {
+        setCachedOccupancy(entry.assetId, entry.occupancy, entry.assetType, entry.timestamp);
+    }
+    if (process.env.DEBUG) {
+        console.error(`[occupancy-cache] Bulk cached ${entries.length} occupancy values`);
+    }
+}
+/**
+ * Clear all cached occupancy data
+ */
+export function clearOccupancyCache() {
+    occupancyCache.clear();
+    if (process.env.DEBUG) {
+        console.error("[occupancy-cache] Cache cleared");
+    }
+}
+/**
+ * Invalidate cache for specific asset
+ */
+export function invalidateAssetOccupancy(assetId) {
+    // Delete all keys for this asset (all time buckets)
+    let deleted = 0;
+    for (const key of occupancyCache.keys()) {
+        if (key.startsWith(`occupancy:${assetId}:`)) {
+            occupancyCache.delete(key);
+            deleted++;
+        }
+    }
+    if (process.env.DEBUG && deleted > 0) {
+        console.error(`[occupancy-cache] Invalidated ${deleted} cache entries for ${assetId}`);
+    }
+}
+/**
+ * Get cache statistics
+ */
+export function getOccupancyCacheStats() {
+    return {
+        size: occupancyCache.size,
+        maxSize: MAX_CACHE_ENTRIES,
+        ttl: CACHE_TTL_SECONDS / 1000, // Convert back to seconds for display
+        utilizationPercent: (occupancyCache.size / MAX_CACHE_ENTRIES) * 100,
+    };
+}
+/**
+ * Calculate cache hit rate over time
+ * (For monitoring/debugging)
+ */
+let cacheHits = 0;
+let cacheMisses = 0;
+export function recordCacheHit() {
+    cacheHits++;
+}
+export function recordCacheMiss() {
+    cacheMisses++;
+}
+export function getCacheHitRate() {
+    const total = cacheHits + cacheMisses;
+    return {
+        hits: cacheHits,
+        misses: cacheMisses,
+        hitRate: total > 0 ? (cacheHits / total) * 100 : 0,
+    };
+}
+export function resetCacheMetrics() {
+    cacheHits = 0;
+    cacheMisses = 0;
+}
+//# sourceMappingURL=occupancy-cache.js.map

package/dist/cache/occupancy-cache.js.map

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

package/dist/cache/topology-cache.d.ts

@@ -0,0 +1,36 @@
+import { LRUCache } from "lru-cache";
+interface CacheEntry {
+    data: Record<string, unknown>;
+    timestamp: string;
+}
+/**
+ * LRU cache for topology data with TTL
+ * Reduces API calls for frequently accessed topology structures
+ */
+export declare const topologyCache: LRUCache<string, CacheEntry, unknown>;
+/**
+ * Generate cache key for topology queries
+ */
+export declare function generateTopologyCacheKey(orgId: string, includeDevices: boolean, includeZones: boolean, siteIds?: string[]): string;
+/**
+ * Get cached topology data
+ */
+export declare function getCachedTopology(key: string): CacheEntry | undefined;
+/**
+ * Store topology data in cache
+ */
+export declare function setCachedTopology(key: string, data: Record<string, unknown>): void;
+/**
+ * Clear all cached topology data
+ */
+export declare function clearTopologyCache(): void;
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(): {
+    size: number;
+    maxSize: number;
+    ttl: number;
+};
+export {};
+//# sourceMappingURL=topology-cache.d.ts.map

package/dist/cache/topology-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology-cache.d.ts","sourceRoot":"","sources":["../../src/cache/topology-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAQrC,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,uCAKxB,CAAC;AAEH;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,OAAO,EACrB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAUrE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAalF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC;AAED;;GAEG;AACH,wBAAgB,aAAa;;;;EAM5B"}

package/dist/cache/topology-cache.js

@@ -0,0 +1,74 @@
+import { LRUCache } from "lru-cache";
+/**
+ * Topology cache configuration
+ */
+const CACHE_TTL_SECONDS = parseInt(process.env.MCP_CACHE_TOPO_TTL || "600", 10) * 1000; // Convert to milliseconds
+const MAX_CACHE_ENTRIES = 100;
+/**
+ * LRU cache for topology data with TTL
+ * Reduces API calls for frequently accessed topology structures
+ */
+export const topologyCache = new LRUCache({
+    max: MAX_CACHE_ENTRIES,
+    ttl: CACHE_TTL_SECONDS,
+    updateAgeOnGet: true, // Reset TTL on cache hit
+    updateAgeOnHas: false,
+});
+/**
+ * Generate cache key for topology queries
+ */
+export function generateTopologyCacheKey(orgId, includeDevices, includeZones, siteIds) {
+    const parts = ["topo", orgId];
+    if (siteIds && siteIds.length > 0) {
+        parts.push(`sites:${siteIds.sort().join(",")}`);
+    }
+    parts.push(`devices:${includeDevices}`);
+    parts.push(`zones:${includeZones}`);
+    return parts.join(":");
+}
+/**
+ * Get cached topology data
+ */
+export function getCachedTopology(key) {
+    const cached = topologyCache.get(key);
+    if (cached && process.env.DEBUG) {
+        console.error(`[topology-cache] Cache HIT for key: ${key}`);
+    }
+    else if (process.env.DEBUG) {
+        console.error(`[topology-cache] Cache MISS for key: ${key}`);
+    }
+    return cached;
+}
+/**
+ * Store topology data in cache
+ */
+export function setCachedTopology(key, data) {
+    const entry = {
+        data,
+        timestamp: new Date().toISOString(),
+    };
+    topologyCache.set(key, entry);
+    if (process.env.DEBUG) {
+        console.error(`[topology-cache] Cached data for key: ${key} (TTL: ${CACHE_TTL_SECONDS / 1000}s)`);
+    }
+}
+/**
+ * Clear all cached topology data
+ */
+export function clearTopologyCache() {
+    topologyCache.clear();
+    if (process.env.DEBUG) {
+        console.error("[topology-cache] Cache cleared");
+    }
+}
+/**
+ * Get cache statistics
+ */
+export function getCacheStats() {
+    return {
+        size: topologyCache.size,
+        maxSize: MAX_CACHE_ENTRIES,
+        ttl: CACHE_TTL_SECONDS / 1000, // Convert back to seconds for display
+    };
+}
+//# sourceMappingURL=topology-cache.js.map

package/dist/cache/topology-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology-cache.js","sourceRoot":"","sources":["../../src/cache/topology-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,0BAA0B;AAClH,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAO9B;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,QAAQ,CAAqB;IAC5D,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,iBAAiB;IACtB,cAAc,EAAE,IAAI,EAAE,yBAAyB;IAC/C,cAAc,EAAE,KAAK;CACtB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAa,EACb,cAAuB,EACvB,YAAqB,EACrB,OAAkB;IAElB,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE9B,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,WAAW,cAAc,EAAE,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IAEpC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEtC,IAAI,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,uCAAuC,GAAG,EAAE,CAAC,CAAC;IAC9D,CAAC;SAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,wCAAwC,GAAG,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,IAA6B;IAC1E,MAAM,KAAK,GAAe;QACxB,IAAI;QACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAE9B,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,CAAC,KAAK,CACX,yCAAyC,GAAG,UAAU,iBAAiB,GAAG,IAAI,IAAI,CACnF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,aAAa,CAAC,KAAK,EAAE,CAAC;IAEtB,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAClD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,IAAI,EAAE,aAAa,CAAC,IAAI;QACxB,OAAO,EAAE,iBAAiB;QAC1B,GAAG,EAAE,iBAAiB,GAAG,IAAI,EAAE,sCAAsC;KACtE,CAAC;AACJ,CAAC"}

package/dist/clients/auth-client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Butlr Authentication Client
+ * Manages OAuth2 client credentials flow for API authentication
+ */
+declare class ButlrAuthClient {
+    private token;
+    private tokenExpiry;
+    private readonly clientId;
+    private readonly clientSecret;
+    constructor();
+    /**
+     * Get a valid access token, fetching a new one if needed
+     */
+    getToken(): Promise<string>;
+    /**
+     * Clear cached token (useful for testing)
+     */
+    clearToken(): void;
+}
+export declare const authClient: ButlrAuthClient;
+export {};
+//# sourceMappingURL=auth-client.d.ts.map

package/dist/clients/auth-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../src/clients/auth-client.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,cAAM,eAAe;IACnB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;;IAOtC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAgEjC;;OAEG;IACH,UAAU,IAAI,IAAI;CAInB;AAGD,eAAO,MAAM,UAAU,iBAAwB,CAAC"}